Doc: Specify CMAKE_TOOLCHAIN_FILE for crosscompiling

Change-Id: I34e25044f203b277c0e57ef1d4a6df4260c1b361
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Jøger Hansegård <joger.hansegard@qt.io>
Reviewed-by: Lorn Potter <lorn.potter@gmail.com>

2 files changed, 25 insertions, 12 deletions

diff --git a/doc/src/cmake/cmake-manual.qdoc b/doc/src/cmake/cmake-manual.qdoc
index 53323f9fb..1a7cc1bbf 100644
--- a/doc/src/cmake/cmake-manual.qdoc
+++ b/doc/src/cmake/cmake-manual.qdoc
@@ -150,12 +150,26 @@
     \l{Module variables}. It furthermore imports the \c{Qt6::Core} target
     that we use below.
 
-    For \c{find_package} to be successful, \c CMake must find the Qt
-    installation. There are different ways you can tell \c CMake about Qt,
-    but the most common and recommended approach is to set the CMake cache
-    variable \c{CMAKE_PREFIX_PATH} to include the Qt 6 installation prefix.
-    Note that \l{Qt Creator Manual}{Qt Creator} will handle this transparently
-    for you.
+    For \c{find_package} to be successful, CMake must find the Qt
+    installation. \l{Qt Creator Manual}{Qt Creator} and \c{qt-cmake}
+    (\c{qt-cmake.bat} on Windows) handle this transparently.
+
+    When using vanilla CMake directly, there are different ways you can tell
+    CMake about Qt, but the most common and recommended approach is to set
+    the CMake cache variable \c{CMAKE_PREFIX_PATH} to include the Qt 6
+    installation prefix. This is a directory where Qt binaries are installed.
+    On Linux, it usually looks something like this:
+    \c{"~/Qt/6.6.1/gcc_64"} and you would pass it on the command line as
+    \c{-DCMAKE_PREFIX_PATH=$HOME/Qt/6.6.1/gcc_64}.
+
+    \note When cross-compiling (compiling for a platform other than the one you
+    are on, such as WebAssembly or Android) and when using vanilla \c{cmake},
+    set \c{CMAKE_TOOLCHAIN_FILE} instead of \c{CMAKE_PREFIX_PATH}. On Linux,
+    the toolchain file (specific to a particular target platform) is typically
+    located at a path similar to this:
+    "~/Qt/6.6.1/wasm_singlethread/lib/cmake/Qt6/qt.toolchain.cmake". It sets
+    the required variables like \c{CMAKE_PREFIX_PATH}, \c{CMAKE_FIND_ROOT_PATH},
+    and \c{QT_HOST_PATH}.
 
     \printuntil qt_standard_project_setup(
 
diff --git a/doc/src/platforms/wasm.qdoc b/doc/src/platforms/wasm.qdoc
index 5c8ad794b..419e7df85 100644
--- a/doc/src/platforms/wasm.qdoc
+++ b/doc/src/platforms/wasm.qdoc
@@ -107,12 +107,6 @@ 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.
 
-Although it should be detected, you may optionally set the
-\e{CMAKE_TOOLCHAIN_FILE} CMake variable to the Emscripten.cmake toolchain file
-that comes with Emscripten SDK. This can be done by setting the environment
-variable \e{CMAKE_TOOLCHAIN_FILE} or by passing
-\c{CMAKE_TOOLCHAIN_FILE=/path/to/Emscripten.cmake} to configure.
-
 \badcode
     ./configure -qt-host-path /path/to/Qt -platform wasm-emscripten -prefix $PWD/qtbase
 \endcode
@@ -141,6 +135,11 @@ Qt for WebAssembly supports building applications using qmake and make, or CMake
    $ cmake --build .
 \endcode
 
+\note When using vanilla \c CMake (as opposed to \c{qt-cmake} on Linux or
+\c{qt-cmake.bat} on Windows) remember to specify a toolchain file
+with "-DCMAKE_TOOLCHAIN_FILE", as for any other cross-platform build.
+For details see here: \l{Getting started with CMake}.
+
 Building the application generates several output files, including a .wasm file that contains
 the application and Qt code (statically linked), a .html file that can be opened in the browser
 to run the application.