diff options
Diffstat (limited to 'cmake/README.md')
| -rw-r--r-- | cmake/README.md | 163 |
1 files changed, 120 insertions, 43 deletions
diff --git a/cmake/README.md b/cmake/README.md index 65be11666d..9d0743566d 100644 --- a/cmake/README.md +++ b/cmake/README.md @@ -1,23 +1,37 @@ -# Status +# Overview -Port is still on-going. -Most of qtbase and qtsvg is ported. -Other repositories are ported, but not under CI control yet. -Some libraries, tests and examples are still missing. +This document gives an overview of the Qt 6 build system. For a hands-on guide on how +to build Qt 6, see https://doc.qt.io/qt-6/build-sources.html and +https://wiki.qt.io/Building_Qt_6_from_Git -Note: -You need CMake 3.16.0 or later for most platforms (due to new AUTOMOC json feature). -You need CMake 3.17.0 to build Qt for iOS with the simulator_and_device feature. -You need CMake 3.17.0 + Ninja to build Qt in debug_and_release mode on Windows / Linux. -You need CMake 3.18.0 + Ninja to build Qt on macOS in debug_and_release mode when using frameworks. +# Contributing -# Intro +See qtbase/cmake/CODESTYLE.md for the code style you should follow when contributing +to Qt's cmake files. -The CMake update offers an opportunity to revisit some topics that came up during the last few -years. +# CMake Versions -* The Qt build system does not support building host tools during a cross-compilation run. You need - to build a Qt for your host machine first and then use the platform tools from that version. The +* You need CMake 3.16.0 or later for most platforms (due to new AUTOMOC json feature). +* You need CMake 3.17.0 to build Qt for iOS with the simulator_and_device feature. +* You need CMake 3.17.0 + Ninja to build Qt in debug_and_release mode on Windows / Linux. +* You need CMake 3.18.0 + Ninja to build Qt on macOS in debug_and_release mode when using + frameworks. +* You need CMake 3.18.0 in user projects that use a static Qt together with QML + (cmake_language EVAL is required for running the qmlimportscanner deferred finalizer) +* You need CMake 3.19.0 in user projects to use automatic deferred finalizers + (automatic calling of qt_finalize_target) +* You need CMake 3.21.0 in user projects that create user libraries that link against a static Qt + with a linker that is not capable to resolve circular dependencies between libraries + (GNU ld, MinGW ld) + +# Changes to Qt 5 + +The build system of Qt 5 was done on top of qmake. Qt 6 is built with CMake. + +This offered an opportunity to revisit other areas of the build system, too: + +* The Qt 5 build system allowed to build host tools during a cross-compilation run. Qt 6 requires + you to build a Qt for your host machine first and then use the platform tools from that version. The decision to do this was reached independent of cmake: This does save resources on build machines as the host tools will only get built once. @@ -27,23 +41,21 @@ years. * There is less need for bootstrapping. Only moc and rcc (plus the lesser known tracegen and qfloat16-tables) are linking against the bootstrap Qt library. Everything else can link against - the full QtCore. This will include qmake. - Qmake is supported as a build system for applications *using* Qt going forward and will + the full QtCore. This does include qmake. + qmake is supported as a build system for applications *using* Qt going forward and will not go away anytime soon. -* We keep the qmake-based Qt build system working so that we do not interfere too much with ongoing - development. - - # Building against homebrew on macOS You may use brew to install dependencies needed to build QtBase. * Install homebrew: - ```/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"``` + `/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"` * Build Qt dependencies: ``brew install pcre2 harfbuzz freetype`` * Install cmake: ``brew install cmake`` - * When running cmake in qtbase, pass ``-DCMAKE_PREFIX_PATH=/usr/local`` + * When running cmake in qtbase, pass ``-DFEATURE_pkg_config=ON`` together with + ``-DCMAKE_PREFIX_PATH=/usr/local``, or ``-DCMAKE_PREFIX_PATH=/opt/homebrew`` if you have a Mac + with Apple Silicon. # Building @@ -110,7 +122,8 @@ the source directory next to them using the helper script ``path_to_qtbase_source/util/cmake/configurejson2cmake.py``. They are checked into the repository. If the feature in configure.json has the name "dlopen", you can specify whether to enable or disable that feature in CMake with a -D flag on the CMake command line. So for example -DFEATURE_dlopen=ON or --DFEATURE_sql_mysql=OFF. At the moment, if you change a FEATURE flag's value, you have to remove the +-DFEATURE_sql_mysql=OFF. Remember to convert all '-' to '_' in the feature name. +At the moment, if you change a FEATURE flag's value, you have to remove the CMakeCache.txt file and reconfigure with CMake. And even then you might stumble on some issues when reusing an existing build, because of an automoc bug in upstream CMake. @@ -126,11 +139,11 @@ Compiling for a target architecture that's different than the host requires one host. This "host build" is needed because the process of building Qt involves the compilation of intermediate code generator tools, that in turn are called to produce source code that needs to be compiled into the final libraries. These tools are built using Qt itself and they need to run on the -machine you're building on, regardless of the architecure you are targeting. +machine you're building on, regardless of the architecture you are targeting. Build Qt regularly for your host system and install it into a directory of your choice using the ``CMAKE_INSTALL_PREFIX`` variable. You are free to disable the build of tests and examples by -passing ``-DBUILD_EXAMPLES=OFF`` and ``-DBUILD_TESTING=OFF``. +passing ``-DQT_BUILD_EXAMPLES=OFF`` and ``-DQT_BUILD_TESTS=OFF``. With this installation of Qt in place, which contains all tools needed, we can proceed to create a new build of Qt that is cross-compiled to the target architecture of choice. You may proceed by @@ -156,22 +169,29 @@ The specified path needs to point to a directory that contains an installed host In order to cross-compile Qt to Android, you need a host build (see instructions above) and an Android build. In addition, it is necessary to install the Android NDK. -The environment for Android can be set up using the following steps: +The following CMake variables are required for an Android build: + * `ANDROID_SDK_ROOT` must point to where the Android SDK is installed + * `CMAKE_TOOLCHAIN_FILE` must point to the toolchain file that comes with the NDK + * `QT_HOST_PATH` must point to a host installation of Qt - * Set the ``ANDROID_NDK_HOME`` environment variable to the path where you have installed the Android NDK. - * Set the ``ANDROID_SDK_HOME`` environment variable to the path where you have installed the Android SDK. +Call CMake with the following arguments: +`-DCMAKE_TOOLCHAIN_FILE=<path/to/ndk>/build/cmake/android.toolchain.cmake -DQT_HOST_PATH=/path/to/your/host/build -DANDROID_SDK_ROOT=<path/to/sdk> -DCMAKE_INSTALL_PREFIX=$INSTALL_PATH` -When running cmake in qtbase, pass -``-DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake -DQT_HOST_PATH=/path/to/your/host/build -DANDROID_SDK_ROOT=$ANDROID_SDK_HOME -DCMAKE_INSTALL_PREFIX=$INSTALL_PATH`` +The toolchain file is usually located below the NDK's root at "build/cmake/android.toolchain.cmake". +Instead of specifying the toolchain file you may specify `ANDROID_NDK_ROOT` instead. +This variable is exclusively used for auto-detecting the toolchain file. + +In a recent SDK installation, the NDK is located in a subdirectory "ndk_bundle" below the SDK's root +directory. In that situation you may omit `ANDROID_NDK_ROOT` and `CMAKE_TOOLCHAIN_FILE`. If you don't supply the configuration argument ``-DANDROID_ABI=...``, it will default to ``armeabi-v7a``. To target other architectures, use one of the following values: - * arm64: ``-DANDROID_ABI=arm64-v8`` + * arm64: ``-DANDROID_ABI=arm64-v8a`` * x86: ``-DANDROID_ABI=x86`` * x86_64: ``-DANDROID_ABI=x86_64`` -By default we set the android API level to 21. Should you need to change this supply the following -configuration argument to the above CMake call: ``-DANDROID_NATIVE_API_LEVEL=${API_LEVEL}`` +By default we set the android API level to 23. Should you need to change this supply the following +configuration argument to the above CMake call: ``-DANDROID_PLATFORM=android-${API_LEVEL}``. ### Cross compiling for iOS @@ -180,13 +200,13 @@ In order to cross-compile Qt to iOS, you need a host macOS build. When running cmake in qtbase, pass ``-DCMAKE_SYSTEM_NAME=iOS -DQT_HOST_PATH=/path/to/your/host/build -DCMAKE_INSTALL_PREFIX=$INSTALL_PATH`` -If you don't supply the configuration argument ``-DQT_UIKIT_SDK=...``, it will default to -``iphonesimulator``. To target another SDK / device type, use one of the following values: - * iphonesimulator: ``-DQT_UIKIT_SDK=iphonesimulator`` - * iphoneos: ``-DQT_UIKIT_SDK=iphoneos`` - * simulator_and_device: ``-DQT_FORCE_SIMULATOR_AND_DEVICE=ON -DQT_UIKIT_SDK=`` +If you don't supply the configuration argument ``-DQT_APPLE_SDK=...``, CMake will build a +multi-arch simulator_and_device iOS build. +To target another SDK / device type, use one of the following values: + * iphonesimulator: ``-DQT_APPLE_SDK=iphonesimulator`` + * iphoneos: ``-DQT_APPLE_SDK=iphoneos`` -Depending on what value you pass to ``-DQT_UIKIT_SDK=`` a list of target architectures is chosen +Depending on what value you pass to ``-DQT_APPLE_SDK=`` a list of target architectures is chosen by default: * iphonesimulator: ``x86_64`` * iphoneos: ``arm64`` @@ -197,9 +217,6 @@ You can try choosing a different list of architectures by passing Note that if you choose different architectures compared to the default ones, the build might fail. Only do it if you know what you are doing. -#### simulator_and_device special considerations -To do a simulator_and_device build, an unreleased version of CMake is required (3.17.0). - # Debugging CMake files CMake allows specifying the ``--trace`` and ``--trace-expand`` options, which work like @@ -254,3 +271,63 @@ While the supporting code for building with vcpkg is still there, it is not test | ``qtHaveModule(foo)`` | ``if(TARGET Qt::foo)`` | | ``qtConfig(foo)`` | ``if (QT_FEATURE_foo)`` | + +# Convenience Scripts + +A Qt installation's bin directory contains a number of convenience scripts. + +## qt-cmake + +This is a wrapper around the CMake executable which passes a Qt-internal `CMAKE_TOOLCHAIN_FILE`. Use +this to build projects against the installed Qt. + +To use a custom toolchain file, use `-DQT_CHAINLOAD_TOOLCHAIN_FILE=<file path>`. + +## qt-cmake-private + +The same as `qt-cmake`, but in addition, sets the CMake generator to Ninja. + +Example: + +``` +$ cd some/empty/directory +$ ~/Qt/6.0.0/bin/qt-cmake-private ~/source/of/qtdeclarative -DFEATURE_qml_network=OFF +$ cmake --build . && cmake --install . +``` + +## qt-configure-module + +Call the configure script for a single Qt module, doing a CMake build. + +Example: + +``` +$ cd some/empty/directory +$ ~/Qt/6.0.0/bin/qt-configure-module ~/source/of/qtdeclarative -no-feature-qml-network +$ cmake --build . && cmake --install . +``` + +## qt-cmake-standalone-test + +Build a single standalone test outside the Qt build. + +Example: + +``` +$ cd some/empty/directory +$ ~/Qt/6.0.0/bin/qt-cmake-standalone-test ~/source/of/qtbase/test/auto/corelib/io/qprocess +$ cmake --build . +``` + +## qt-cmake-create + +Generates a simple CMakeLists.txt based on source files in specified project directory. + +Example: + +``` +$ cd some/source/directory/ +$ qt-cmake-create +$ qt-cmake -S . -B /build/directory +$ cmake --build /build/directory +``` |