Update the macOS documentation to mention x86_64h

And recommend it for universal builds.

Change-Id: I76216ced393445a4ae2dfffd172a66c6b1995065
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

1 files changed, 17 insertions, 3 deletions

diff --git a/doc/src/platforms/macos.qdoc b/doc/src/platforms/macos.qdoc
index a6c1cae7..c4ba7fce 100644
--- a/doc/src/platforms/macos.qdoc
+++ b/doc/src/platforms/macos.qdoc
@@ -136,7 +136,8 @@
     \section2 Architectures
 
     By default, Qt will build for the architecture of your development machine -
-    either \c x86_64, or \c arm64 if you are on an Apple Silicon Mac.
+    either \c x86_64 if you're on an Intel Mac, or \c arm64 if you are on an
+    Apple Silicon Mac.
 
     To build for other architectures you can use the \l
     {https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_ARCHITECTURES.html}
@@ -163,6 +164,16 @@
     QMAKE_APPLE_DEVICE_ARCHS = x86_64 arm64
     \endcode
 
+    \section3 Sub-architecture support on Intel Macs
+
+    In addition to the baseline \c x86_64 architecture, Qt also supports the
+    \c x86_64h ("Haswell") sub-architecture, which improves performance on Intel
+    Macs. The Qt \qtver binary packages, which are universal builds for both Intel
+    and Apple Silicon Macs, use \c x86_64h for the Intel slice of the libraries.
+    However, this does not affect how your application is built, so you can still
+    build using the default \c x86_64 Intel architecture. If needed, you can follow
+    Qt's default by specifying \c "x86_64h;arm64" for \c CMAKE_OSX_ARCHITECTURES.
+
     \section1 Generating Xcode Project Files
 
     By default, CMake and qmake generates project files in Makefile
@@ -310,12 +321,15 @@
         As described in \l {Qt for \macos#Architectures}, Qt will
         build for the architecture of your development machine by
         default. To configure a universal build of Qt with support
-        for both \c x86_64 and \c arm64, add the following argument:
+        for both Intel and Apple Silicon Macs, add the following argument:
 
         \code
-        ./configure -- -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"
+        ./configure -- -DCMAKE_OSX_ARCHITECTURES="x86_64h;arm64"
         \endcode
 
+        Be careful to specify the Intel architecture ("x86_64h") first,
+        otherwise Qt may not enable all the x86 functionality.
+
         Qt can also be configured to be built with debugging symbols. This
         process is described in detail in the \l{Debugging Techniques}
         document.