Doc: Document general aspects of cross-building QtHEADdev

Fixes: QTBUG-137138
Pick-to: 6.9 6.10
Change-Id: I4d2b1c1df2506bfbc228badf08ca51fbac511b92
Reviewed-by: Alexei Cazacov <[email protected]>
Reviewed-by: Alexandru Croitor <[email protected]>

10 files changed, 122 insertions, 40 deletions

diff --git a/doc/src/platforms/android/android-building.qdoc b/doc/src/platforms/android/android-building.qdoc
index 7e9aac553..687c92cf2 100644
--- a/doc/src/platforms/android/android-building.qdoc
+++ b/doc/src/platforms/android/android-building.qdoc
@@ -52,21 +52,7 @@
     With Qt 6, you can build Qt for Android from source code using \c CMake. Qt 6
     for Android requires a host Qt build, which means to build Qt for Android, you
     need to build Qt for the desktop platform used as a host (that is, Linux, \macos,
-    or Windows).
-
-    To configure and do a minimalistic host build to be used with Qt for Android
-    build, use the following command:
-
-    \badcode
-    mkdir ~/dev/build-host
-    cd ~/dev/build-host
-    ./configure -developer-build -nomake tests -nomake examples
-    cmake --build . --target host_tools
-    \endcode
-
-    That will configure a developer build for your host and only build the necessary
-    dependencies used for the Android build. For more information on doing a full
-    and more customizable build for your host, see \l{Building Qt Sources}.
+    or Windows). See \l{Cross-compiling Qt} for details.
 
     To configure Qt for Android, create a shadow build directory to keep the source
     directory clean:
diff --git a/doc/src/platforms/apple/ios.qdoc b/doc/src/platforms/apple/ios.qdoc
index 1cc5bf4d8..c62deb8f4 100644
--- a/doc/src/platforms/apple/ios.qdoc
+++ b/doc/src/platforms/apple/ios.qdoc
@@ -193,6 +193,9 @@
     Qt sources can be obtained either by cloning the repositories or
     downloading the source package(s).
 
+    To cross-build Qt, you need a host build of Qt first. See \l{Cross-compiling
+    Qt} for details.
+
     You can then configure and build Qt. This is done from the Qt top
     directory:
 
diff --git a/doc/src/platforms/configure-linux-device.qdoc b/doc/src/platforms/configure-linux-device.qdoc
index a14cf3cc4..407d5b86e 100644
--- a/doc/src/platforms/configure-linux-device.qdoc
+++ b/doc/src/platforms/configure-linux-device.qdoc
@@ -86,11 +86,8 @@
 
     \section1 Host Tools
 
-    Cross-compiling Qt requires a host build of Qt being available. During the build,
-    tools such as \c moc, \c rcc, \c qmlcachegen, \c qsb, and others, are invoked from
-    there. For example, if one cross-compiles for ARM on an x64 machine, a local x64 build
-    of the same Qt version must be made available first. The path to this Qt build will be
-    passed to configure or cmake.
+    Cross-compiling Qt requires a host build of Qt being available. See
+    \l{Cross-compiling Qt} for details.
 
     \section1 Configuring Qt
 
diff --git a/doc/src/platforms/cross-compiling-qt.qdoc b/doc/src/platforms/cross-compiling-qt.qdoc
new file mode 100644
index 000000000..52b0001c0
--- /dev/null
+++ b/doc/src/platforms/cross-compiling-qt.qdoc
@@ -0,0 +1,104 @@
+// Copyright (C) 2025 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \page cross-compiling-qt.html
+    \title Cross-compiling Qt
+    \brief Building Qt for a platform different from your host platform.
+
+    This page describes the general process and requirements of cross-compiling
+    Qt.
+
+    If you're just looking for a way to build a host Qt, see \l{Creating the
+    host build of Qt}.
+
+    \section1 Terms and definitions
+
+    \e Cross-compiling means configuring and building for a target platform
+    that's different from your host platform.
+
+    The \e host is the computer you are building Qt on, for example a Linux
+    machine. The \e target is the device you're building Qt for, for example an
+    Android tablet.
+
+    When building Qt, several tools are run that generate code or do some other
+    processing. These tools run on the \e host and are therefore called the
+    \e{host tools}. These host tools are part of a \e{host build} of Qt. This
+    host build must be prepared as a prerequisite to building Qt for the
+    \e{target platform}.
+
+    A \e{minimal host build} of Qt is a \e{host build} of Qt that only contains
+    the \e{host tools} necessary to create a \e{target build} of Qt.
+
+    Qt is built with CMake, and CMake needs a \e{toolchain file} when
+    cross-compiling. This file contains information about the target platform
+    and the used toolchain. See the
+    \l{https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html#cross-compiling}
+    {CMake documentation on cross-compiling}.
+
+    For some target platforms, the Qt configure script automatically selects the
+    file. See the documentation that's specific for the desired target platform
+    for details.
+
+    For some target platforms, you need to specify a \e sysroot. That is a
+    self-contained environment that includes all necessary files and libraries
+    required for compiling and linking applications.
+
+    \section1 General notes on the host build of Qt
+
+    During the build of Qt for the target, tools such as \c moc, \c rcc, \c
+    qmlcachegen, \c qsb, and others, are invoked from there. For example, if one
+    cross-compiles for ARM on an x64 machine, a local x64 build of the same Qt
+    version must be made available first. The path to this Qt build will be
+    passed to \c configure or \c cmake. The host build of Qt is usually a
+    regular build of Qt for your host device.
+
+    The host build of Qt must contain all necessary host tools for building Qt
+    for the target platform. For example, if your target Qt is supposed to
+    support Qt Quick, the host Qt must contain \e qsb, the shader compiler. An
+    easy way to ensure that the host Qt provides all necessary tools is to build
+    the same Qt modules on the host that you'll need on the target.
+
+    Avoid building the host Qt statically if the target Qt is built shared. A
+    static build of Qt might not contain all tools necessary to build a shared
+    Qt.
+
+    Ensure you use the same version of Qt for the host and target Qt to avoid
+    incompatibility issues.
+
+    \section1 Creating the host build of Qt
+
+    See \l{Building Qt Sources}{the documentation of the desired host} for
+    details on how to build Qt for that platform.
+
+    To build a \e{minimal host Qt}, use the following build command after
+    configuring Qt:
+
+    \badcode
+    mkdir ~/QtHostBuild
+    cd ~/QtHostBuild
+    ~/QtSource/configure -developer-build -nomake tests
+    cmake --build . --target host_tools
+    \endcode
+
+    This build won't be suitable for developing Qt programs for your host
+    platform, but it will contain the tools necessary to cross-build Qt.
+
+    \section1 Specifying the host build of Qt when cross-compiling
+
+    When cross-compiling, you must point the target Qt to the location of the
+    host Qt.
+
+    When using the configure script, you use
+    \badcode
+    ~/QtSource/configure -qt-host-path ~/QtHostBuild ...target-specific options...
+    \endcode
+
+    When using CMake directly, you use
+    \badcode
+    cmake -S ~/QtSource -DQT_HOST_PATH=~/QtHostBuild ...target-specific options...
+    \endcode
+
+    See \l{Building Qt Sources}{the documentation of the desired target} for
+    target-specific options.
+*/
diff --git a/doc/src/platforms/integrity-build-monolith-app-tutorial.qdoc b/doc/src/platforms/integrity-build-monolith-app-tutorial.qdoc
index a96d9f1c7..219e8094e 100644
--- a/doc/src/platforms/integrity-build-monolith-app-tutorial.qdoc
+++ b/doc/src/platforms/integrity-build-monolith-app-tutorial.qdoc
@@ -84,7 +84,8 @@
     \previouspage integrity-installing-dependencies.html
     \nextpage integrity-win-monolith.html
 
-    \include qt6CMakeCrossCompile.qdocinc Qt cross-compile introduction
+    For building Qt for INTEGRITY, you first need a host build of Qt. See
+    \l{Cross-compiling Qt} for details.
 
     The following tutorial content is for building a Qt for \e {INTEGRITY 19.0.13} target on an \e {Ubuntu 20.04 64 host}:
     \list
@@ -436,7 +437,8 @@
     \previouspage integrity-linux-monolith.html
     \nextpage integrity-monolith-project-tutorial.html
 
-    \include qt6CMakeCrossCompile.qdocinc Qt cross-compile introduction
+    For building Qt for INTEGRITY, you first need a host build of Qt. See
+    \l{Cross-compiling Qt} for details.
 
     The following tutorial content is for building a Qt for \e {INTEGRITY 19.0.13} target on a \e {Windows 10 64 host}:
     \list
diff --git a/doc/src/platforms/qnx.qdoc b/doc/src/platforms/qnx.qdoc
index e794852c1..1168794f6 100644
--- a/doc/src/platforms/qnx.qdoc
+++ b/doc/src/platforms/qnx.qdoc
@@ -235,7 +235,7 @@
             functional for your host platform.
         \li The toolchain file, in this example \c{$HOME/qnx.cmake}.
         \li The Qt source code checked out or installed, in this example under \c{$HOME/qt}.
-        \li Host build of Qt, in this example \c{$HOME/qt-host}.
+        \li \l{Cross-compiling Qt}{Host build of Qt}, in this example \c{$HOME/qt-host}.
         \li Prefix for the Qt build installation location on the local system, in this example
         \c{$HOME/qnx-install}.
         \li Prefix for the Qt build deployment location on the target device, in this example
diff --git a/doc/src/platforms/qt6CMakeCrossCompile.qdocinc b/doc/src/platforms/qt6CMakeCrossCompile.qdocinc
deleted file mode 100644
index 8271fd4b5..000000000
--- a/doc/src/platforms/qt6CMakeCrossCompile.qdocinc
+++ /dev/null
@@ -1,13 +0,0 @@
-// Copyright (C) 2021 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
-
-/*!
-//! [Qt cross-compile introduction]
-
-In Qt 6, CMake is the build tool, which supports cross-compiling,
-that means the software is built on one system, but is intended to run on a different system.
-
-The system used to build is called the \c host. The device which will run the software product is called the \c target.
-
-//! [Qt cross-compile introduction]
-*/
diff --git a/doc/src/platforms/vxworks.qdoc b/doc/src/platforms/vxworks.qdoc
index 8231a7088..0461986d3 100644
--- a/doc/src/platforms/vxworks.qdoc
+++ b/doc/src/platforms/vxworks.qdoc
@@ -145,8 +145,9 @@
   {https://gallery.windriver.com/portal/products}.
 
   Building Qt for a given device requires a Qt 6 installation for compilation
-  host, a toolchain and a sysroot. Additionally, some devices require vendor
-  specific adaptation code for EGL and OpenGL 2.0 support.
+  host, a toolchain and a sysroot. See \l{Cross-compiling Qt} for details.
+  Additionally, some devices require vendor specific adaptation code for EGL and
+  OpenGL 2.0 support.
 
   \section2 VxWorks Image Requirements
 
diff --git a/doc/src/platforms/wasm.qdoc b/doc/src/platforms/wasm.qdoc
index 93b9de77c..56f3fd7f9 100644
--- a/doc/src/platforms/wasm.qdoc
+++ b/doc/src/platforms/wasm.qdoc
@@ -114,8 +114,9 @@ This sets the \c -static, \c -no-feature-thread, and \c{-no-make examples}
 configure options. You can enable thread support with the \c -feature-thread,
 configure option. Shared library builds are not supported.
 
-You need a host build of the same version of Qt and specify that path in the \e
-QT_HOST_PATH CMake variable or by using the \c -qt-host-path configure argument.
+You need a \l{Cross-compiling Qt}{host build of the same version of Qt}. Also,
+set the path to the host build in the \e QT_HOST_PATH CMake variable or by using
+the \c -qt-host-path configure argument.
 
 \badcode
     ./configure -qt-host-path /path/to/Qt -platform wasm-emscripten -prefix $PWD/qtbase
diff --git a/doc/src/qtdoc-toc.qdoc b/doc/src/qtdoc-toc.qdoc
index caa047f2b..9b01d142c 100644
--- a/doc/src/qtdoc-toc.qdoc
+++ b/doc/src/qtdoc-toc.qdoc
@@ -142,6 +142,7 @@
                     \li \l {Qt for VxWorks}
                     \li \l {Qt for WebAssembly}
                     \li \l {Qt for webOS}
+                    \li \l {Cross-compiling Qt}
                 \endlist
             \li \l {Qt Releases}
             \li \l {Qt Licensing}