Merge branch 'mac-build'

Improve Mac build documentation and build itself.

See #24128.

docs/gtk/install.md

@@ -18,13 +18,38 @@ the following in wxWidgets directory:
     $ cd buildgtk
     $ ../configure --with-gtk
     $ make
+
+It is recommended to use `-jN` option with the last command, where `N` is a
+number of the processors in your system (which can be checked using `nproc`
+command if you are not sure), as this will dramatically speed up the build
+on modern systems. So in practice you should use a command like this:
+
+    $ make -j8
+
+(but don't use it unless you actually have 8 CPUs and enough memory for that
+many parallel compiler invocations).
+
+You may also prefer to add `-s` option to avoid normal output from make and/or
+redirect it you to a log file for further inspection.
+
+You should build at least the smallest possible wxWidgets sample to verify that
+everything is working as intended, by doing
+
+    $ cd samples/minimal
+    $ make
+
+and try running it using `./minimal` command from the same directory.
+
+After confirming that it works, you may want to install wxWidgets by running
+
     $ sudo make install
     $ sudo ldconfig
 
 (if you get "ldconfig: command not found", try using `/sbin/ldconfig`)
 
-If you don't do the `make install` part, you can still use the libraries from
-the `buildgtk` directory, but they may not be available to other users.
+but note that this part is optional and you can use the libraries from
+the `buildgtk` directory by running `.../buildgtk/wx-config` script using its
+full path instead of just using `wx-config`.
 
 Note that by default, GTK 3 is used. GTK 2 can be specified
 with `--with-gtk=2` configure option.

docs/osx/install.md

@@ -9,11 +9,11 @@ Most OS X developers should start by downloading and installing Xcode
 from the App Store.  It is a free IDE from Apple that provides
 all of the tools you need for working with wxWidgets.
 
-After Xcode is installed, download wxWidgets-{version}.tar.bz2 and then
+After Xcode is installed, download `wxWidgets-{version}.tar.bz2` and then
 double-click on it to unpack it to create a wxWidgets directory.
 
 Next use Terminal (under Applications, Utilities, Terminal) to access a command
-prompt.  Use cd to change directories to your wxWidgets directory and execute
+prompt.  Use `cd` to change directories to your wxWidgets directory and execute
 the following sets of commands from the wxWidgets directory.
 
     mkdir build-cocoa-debug
@@ -21,27 +21,54 @@ the following sets of commands from the wxWidgets directory.
     ../configure --enable-debug
     make
 
-Build the samples and demos
+It is recommended to use `-jN` option with the last command, where `N` is a
+number of the processors in your system (which can be checked using `sysctl -n
+hw.ncpu` command if you are not sure), as this will dramatically speed up the
+build on modern systems. So in practice you should use a command like this:
+
+    make -j8
+
+(but don't use it unless you actually have 8 CPUs and enough memory for that
+many parallel compiler invocations).
+
+You may also prefer to add `-s` option to avoid normal output from make and/or
+redirect it you to a log file for further inspection.
+
+You should build at least the smallest possible wxWidgets sample to verify that
+everything is working as intended, by doing
+
+    cd samples/minimal
+    make
+
+and then running `minimal.app` from this directory from Finder.
+
+If you'd like to, you can also build all the other samples and demos
 
     cd samples; make;cd ..
     cd demos;   make;cd ..
 
-After the compilation completes, use Finder to run the samples and demos
-* Go to build-cocoa-debug/samples to experiment with the Cocoa samples.
-* Go to build-cocoa-debug/demos to experiment with the Cocoa demos.
-* Double-click on the executables which have an icon showing three small squares.
-* The source code for the samples is in wxWidgets/samples
-* The source code for the demos is in wxWidgets/demos
-
-More information about building on macOS is available in the wxWiki.
-Here are two useful links
-  * https://wiki.wxwidgets.org/Guides_%26_Tutorials
-  * https://wiki.wxwidgets.org/Development:_wxMac
-
 
 Advanced topics                        {#osx_advanced}
 ===============
 
+Building library for distribution
+---------------------------------
+
+When building library for the distribution with your application, you shouldn't
+use `--enable-debug` option above but you may want to use `--disable-sys-libs`
+option to ensure that it has no dependencies on the other libraries available
+on the current system as they might not be present on all systems where the
+application is used.
+
+It is also often desirable to build the final version of the application as
+"universal binary", i.e. a combination of binaries for several different
+architectures. In this case, you should build wxWidgets as universal binary
+too, using `--enable-universal_binary` option. By default, this option enables
+building for the usually wanted set of architectures (currently ARM and Intel)
+but you may override this by listing the architectures you want to use
+explicitly, separating them with commas.
+
+
 Installing library                     {#osx_install}
 ------------------