Help: Add note about /usr/local/include on macOS without CMAKE_OSX_SYSROOT

Issue: #19180

Help/release/4.0.rst

@@ -235,6 +235,12 @@ Other Changes
   does not do this, users must now specify :variable:`CMAKE_OSX_SYSROOT`
   when configuring their build, e.g., ``-DCMAKE_OSX_SYSROOT=macosx``.
 
+  Note that Xcode's compilers, when not invoked with ``-isysroot``, search
+  for headers in ``/usr/local/include`` before system SDK paths, matching the
+  convention on many platforms.  Users on macOS-x86_64 hosts with Homebrew
+  installed in ``/usr/local`` should pass ``-DCMAKE_OSX_SYSROOT=macosx``,
+  or ``export SDKROOT=macosx``, when not building with Homebrew tools.
+
 * On AIX, ``SHARED`` library targets now produce a shared library archive
   by default.  See policy :policy:`CMP0182`.
 

Help/variable/CMAKE_OSX_SYSROOT.rst

@@ -15,4 +15,12 @@ sysroot is used.
   The default is now empty.  Previously a default was computed based on
   the :variable:`CMAKE_OSX_DEPLOYMENT_TARGET` or the host platform.
 
+.. note::
+
+  Xcode's compilers, when not invoked with ``-isysroot``, search for
+  headers in ``/usr/local/include`` before system SDK paths, matching the
+  convention on many platforms.  Users on macOS-x86_64 hosts with Homebrew
+  installed in ``/usr/local`` should pass ``-DCMAKE_OSX_SYSROOT=macosx``,
+  or ``export SDKROOT=macosx``, when not building with Homebrew tools.
+
 .. include:: CMAKE_OSX_VARIABLE.txt