Doc: improve directions for building on macOS.

In light of recent discussions, we should instruct people to
install Apple's command line tools; installing Xcode is secondary.

Also, fix sample command for finding out the default sysroot,
as we now know that the command originally recommended can give
a result that doesn't match your OS version.

Also document the workaround to use if you really don't want
configure to select a sysroot at all.

Discussion: https://postgr.es/m/20210119111625[email protected]

diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 552303e21142173c3b0c83b2f4f4536921d5aaa8..29b44dcbf00236c24ba23cdc08c687d934dd1b3f 100644 (file)
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -2356,6 +2356,17 @@ make MAX_CONNECTIONS=5 check
     installation on
    
 
+   
+    To build PostgreSQL from source
+    on macOS, you will need to install Apple's
+    command line developer tools, which can be done by issuing
+
+xcode-select --install
+
+    (note that this will pop up a GUI dialog window for confirmation).
+    You may or may not wish to also install Xcode.
+   
+
    
     On recent macOS releases, it's necessary to
     embed the sysroot path in the include switches used to
@@ -2372,7 +2383,7 @@ make PG_SYSROOT=/desired/path all
 
     To find out the appropriate path on your machine, run
 
-xcodebuild -version -sdk macosx Path
+xcrun --show-sdk-path
 
     Note that building an extension using a different sysroot version than
     was used to build the core server is not really recommended; in the
@@ -2386,6 +2397,19 @@ xcodebuild -version -sdk macosx Path
 
 ./configure ... PG_SYSROOT=/desired/path
 
+    This would primarily be useful to cross-compile for some other
+    macOS version.  There is no guarantee that the resulting executables
+    will run on the current host.
+   
+
+   
+    To suppress the -isysroot options altogether, use
+
+./configure ... PG_SYSROOT=none
+
+    (any nonexistent pathname will work).  This might be useful if you wish
+    to build with a non-Apple compiler, but beware that that case is not
+    tested or supported by the PostgreSQL developers.