qt5base-lts/cmake
Joerg Bornemann 7f94aa23f5 CMake: Fix initialization of QT_BUILD_TOOLS_BY_DEFAULT
...when QT_BUILD_TOOLS_WHEN_CROSSCOMPILING is ON.

When QT_BUILD_TOOLS_WHEN_CROSSCOMPILING is ON, we want to set
QT_FORCE_BUILD_TOOLS.  But this happened too late: after the
initialization of QT_BUILD_TOOLS_BY_DEFAULT.  This value depends on
QT_FORCE_BUILD_TOOLS.

This amends commit acfbe3b779.

Change-Id: Ibdba54da943aea1b55618f10d2b8485f4390878a
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
2022-05-11 18:53:37 +02:00
..
3rdparty Reorganize work with graphical libraries on INTEGRITY 2022-04-05 17:27:15 +03:00
ios CMake: Add default launch screen storyboard for iOS apps 2022-02-16 05:14:24 +01:00
macos Remove CFBundleGetInfoString from CMake Info.plist templates 2021-11-01 18:58:00 +00:00
platforms Reorganize work with graphical libraries on INTEGRITY 2022-04-05 17:27:15 +03:00
QtBuildInternals Pass compilers on to examples configs 2022-04-26 22:58:56 +02:00
tests CMake: Bump almost all cmake_minimum_required calls to 3.16 2021-09-22 19:36:49 +02:00
configure-cmake-mapping.md Map the 'verbose' configure option to CMake 2022-04-06 16:46:59 +02:00
FindATSPI2.cmake
FindCups.cmake
FindDB2.cmake Adjust database packages FindFoo.cmake files to CMake convention 2021-01-19 13:17:55 +00:00
FindDirectFB.cmake
Finddouble-conversion.cmake
FindGLESv2.cmake Reorganize work with graphical libraries on INTEGRITY 2022-04-05 17:27:15 +03:00
FindGSSAPI.cmake Fix finding GSSAPI 2022-01-29 11:46:04 +00:00
FindGTK3.cmake
FindInterbase.cmake ibase: Fix the compilation and include it again so it can be detected 2021-01-26 21:47:36 +01:00
FindLibb2.cmake FindLibb2: Don't rely solely on pkg-config 2021-01-18 15:42:52 +11:00
FindLibproxy.cmake
FindLibsystemd.cmake
FindLibudev.cmake
FindMtdev.cmake
FindMySQL.cmake Adjust database packages FindFoo.cmake files to CMake convention 2021-01-19 13:17:55 +00:00
FindOracle.cmake Adjust database packages FindFoo.cmake files to CMake convention 2021-01-19 13:17:55 +00:00
FindPostgreSQL.cmake Add upstream version of FindPostgreSQL.cmake 2021-01-26 16:05:05 +01:00
FindPPS.cmake
FindSlog2.cmake
FindTslib.cmake
FindWrapAtomic.cmake Explicitly check for atomic addition and relaxed load operation support 2022-04-18 15:01:53 +00:00
FindWrapBacktrace.cmake Fix backtrace on non-linux systems 2021-03-22 21:31:09 +00:00
FindWrapBrotli.cmake CMake: fix build with static Brotli 2021-05-07 02:06:44 +08:00
FindWrapDBus1.cmake
FindWrapDoubleConversion.cmake
FindWrapFreetype.cmake
FindWrapHarfbuzz.cmake
FindWrapJpeg.cmake Install 3rdparty headers for static builds 2022-02-19 01:52:32 +01:00
FindWrapOpenGL.cmake
FindWrapOpenSSL.cmake CMake: Fix WrapOpenSSL package 2022-01-07 11:16:21 +01:00
FindWrapOpenSSLHeaders.cmake CMake: Make WrapVulkanHeaders target optional for QtGui consumers 2021-07-29 16:38:50 +02:00
FindWrapPCRE2.cmake
FindWrapPNG.cmake
FindWrapRt.cmake cmake: avoid unused parameters in cmake tests 2022-02-22 02:02:48 +08:00
FindWrapSystemFreetype.cmake
FindWrapSystemHarfbuzz.cmake
FindWrapSystemJpeg.cmake Install 3rdparty headers for static builds 2022-02-19 01:52:32 +01:00
FindWrapSystemMd4c.cmake Fix support for using system supplied md4c library 2021-06-03 20:08:32 +02:00
FindWrapSystemPCRE2.cmake Fix check for pcre2 using cmake 2022-04-08 13:03:30 +02:00
FindWrapSystemPNG.cmake
FindWrapSystemZLIB.cmake zlib as static library 2022-04-22 14:34:47 +02:00
FindWrapVulkan.cmake CMake: Fix Vulkan to be found when targeting Android 2021-07-01 18:57:50 +02:00
FindWrapVulkanHeaders.cmake Support MoltenVK from homebrew 2021-10-13 09:37:36 +00:00
FindWrapZLIB.cmake zlib as static library 2022-04-22 14:34:47 +02:00
FindWrapZSTD.cmake CMake: Rename FindZSTD to FindWrapZSTD 2022-02-28 23:08:20 +01:00
FindXKB_COMMON_X11.cmake
FindXRender.cmake
modulecppexports_p.h.in Implement generating of private cpp exports 2021-08-27 11:01:47 +02:00
modulecppexports.h.in Make one QT_REMOVED_SINCE/QT_BUILD_REMOVED_API per module 2022-02-01 11:47:58 +00:00
ModuleDescription.json.in CMake: Use PROJECT_VERSION for generated QtModule.json files 2021-04-15 14:23:11 +02:00
PkgConfigLibrary.pc.in CMake build: generate pkgconfig for public modules 2022-02-28 08:39:54 -03:00
Qt3rdPartyLibraryConfig.cmake.in CMake: Enable NEW policies by CMake version with a global default 2020-12-07 13:22:57 +11:00
Qt3rdPartyLibraryHelpers.cmake CMake: Fix exclusion of QtFoo in QtBarDepends for 3rd party libs 2022-02-23 15:17:42 +01:00
qt.toolchain.cmake.in CMake: Read QT_HOST_PATH from the environment too 2022-02-24 17:07:43 +01:00
QtAndroidHelpers.cmake Replace ANDROID_ABI argument with the QT_ANDROID_ABI target property 2022-01-03 14:35:13 +01:00
QtAppHelpers.cmake CMake: Work around build rpath issue when CMAKE_STAGING_PREFIX is set 2022-04-22 14:34:47 +02:00
QtAutoDetect.cmake CMake: Handle detection of linux-g++-32 mkspec 2022-04-25 15:42:19 +02:00
QtAutogenHelpers.cmake Long live Q_GADGET_EXPORT! 2021-11-27 01:25:10 +01:00
QtBaseCMakeTesting.cmake
QtBaseConfigureTests.cmake CMake: Print prefix info when building qtbase 2022-04-19 17:20:14 +02:00
QtBaseGlobalTargets.cmake CMake: Pass -v to ninja when using ctest --build-and-test 2022-04-04 15:41:20 +02:00
QtBuild.cmake CMake: Make possible building Qt tools without the use of core library 2022-05-06 22:06:22 +02:00
QtBuildInformation.cmake CMake: Fix interleaved configure output 2022-04-22 14:34:47 +02:00
QtBuildInternalsExtra.cmake.in CMake: Support overriding CMAKE_BUILD_TYPE per-repo or test 2022-01-21 14:24:09 +01:00
QtCMakeHelpers.cmake CMake: Allow disabling package version check 2021-10-27 16:41:26 +02:00
QtCMakePackageVersionFile.cmake.in CMake: Allow disabling package version check 2021-10-27 16:41:26 +02:00
QtCMakeVersionHelpers.cmake CMake: Warn when using unsuitable CMake due to issue finding host perl 2021-10-29 15:34:12 +02:00
QtCompilerFlags.cmake Delete -Wextra compilation flag for GHS compiler 2021-11-18 09:38:43 +00:00
QtCompilerOptimization.cmake CMake: add detection of x86 VAES and AVX512VBMI2 features 2022-03-08 00:31:30 -08:00
QtConfig.cmake.in Fix QT_ADDITIONAL_(HOST_)PACKAGES_PREFIX_PATH environment variables 2022-02-23 17:06:20 +01:00
QtConfigDependencies.cmake.in CMake: Use namespaced variables in Qt6*Dependencies.cmake 2021-07-24 03:51:53 +08:00
QtConfigExtras.cmake.in Revert "CMake: Warn if cmake_minimum_required has an unsupported low version" 2021-10-04 15:55:10 +02:00
QtCopyFileIfDifferent.cmake Use 'copy' but not 'copy_if_different' on Windows platforms 2022-02-10 02:31:05 +01:00
QtDbusHelpers.cmake
QtDeferredDependenciesHelpers.cmake
QtDocsHelpers.cmake Assume qhelpgenerator in libexec instead of bin 2021-11-08 19:27:32 +01:00
QtExecutableHelpers.cmake CMake: Make possible building Qt tools without the use of core library 2022-05-06 22:06:22 +02:00
QtFeature.cmake CMake: add detection of x86 VAES and AVX512VBMI2 features 2022-03-08 00:31:30 -08:00
QtFeatureCommon.cmake
QtFileConfigure.txt.in
QtFindPackageHelpers.cmake CMake: Fix -rpath-link dependencies take two 2021-10-22 22:57:46 +02:00
QtFindWrapConfigExtra.cmake.in
QtFindWrapHelper.cmake
QtFinishPkgConfigFile.cmake CMake build: generate pkgconfig for public modules 2022-02-28 08:39:54 -03:00
QtFinishPrlFile.cmake Fix generated pri and prl files 2021-07-17 02:42:13 +08:00
QtFlagHandlingHelpers.cmake Bump QT_DEPRECATED_WARNINGS_SINCE 2022-03-18 07:00:30 +01:00
QtFrameworkHelpers.cmake Add VERBATIM option to add_custom_command calls 2022-03-17 15:15:06 +01:00
QtGenerateExtPri.cmake
QtGenerateLibHelpers.cmake Fix generated pri and prl files 2021-07-17 02:42:13 +08:00
QtGenerateLibPri.cmake Fix generated pri and prl files 2021-07-17 02:42:13 +08:00
QtGlobalStateHelpers.cmake
QtHeadersClean.cmake Enable QT_TYPESAFE_FLAGS in headersclean 2022-03-12 06:33:29 +01:00
QtHostInfoConfig.cmake.in
QtInstallHelpers.cmake CMake: Run export(EXPORT) for prefixed and top-level builds 2022-02-01 16:51:00 +01:00
QtInternalTargets.cmake Build system: Allow user to enable Intel CET 2022-04-06 13:06:24 +08:00
QtJavaHelpers.cmake
QtLalrHelpers.cmake Add VERBATIM option to add_custom_command calls 2022-03-17 15:15:06 +01:00
QtModuleConfig.cmake.in CMake: Don't create targets if dependencies are not found 2021-11-02 11:51:26 +01:00
QtModuleDependencies.cmake.in CMake: Introduce QT_ADDITIONAL_HOST_PACKAGES_PREFIX_PATH 2022-02-15 14:48:20 +01:00
QtModuleHelpers.cmake Add qpa include directory to the return values of qt_internal_module_info 2022-05-02 12:03:42 +02:00
QtModuleToolsConfig.cmake.in CMake: Enable NEW policies by CMake version with a global default 2020-12-07 13:22:57 +11:00
QtModuleToolsDependencies.cmake.in CMake: Use namespaced variables in Qt6*Dependencies.cmake 2021-07-24 03:51:53 +08:00
QtModuleToolsVersionlessTargets.cmake.in CMake: Create global imported versionless tool targets 2021-06-01 16:29:15 +02:00
QtNoLinkTargetHelpers.cmake
QtPkgConfigHelpers.cmake Suppress cmake warning about empty string argument 2022-04-12 04:57:14 +00:00
QtPlatformAndroid.cmake Use the highest-available android SDK version as the 'target' SDK 2021-12-14 17:09:21 +01:00
QtPlatformSupport.cmake QtPlatformSupport: add support for detecting webOS 2022-03-21 21:36:23 +02:00
QtPlatformTargetHelpers.cmake Add '-stdlib=libc++' only for c++ compilers 2022-03-14 20:52:47 +01:00
QtPluginConfig.cmake.in CMake: Fix auto-linking of static plugins in standalone tests 2021-04-21 15:21:08 +02:00
QtPluginDependencies.cmake.in CMake: Use namespaced variables in Qt6*Dependencies.cmake 2021-07-24 03:51:53 +08:00
QtPluginHelpers.cmake CMake: Work around build rpath issue when CMAKE_STAGING_PREFIX is set 2022-04-22 14:34:47 +02:00
QtPlugins.cmake.in CMake: Introduce finalizer mode handling of static plugins 2021-05-20 00:55:46 +02:00
QtPostProcess.cmake Generate information about user-facing applications in build dir 2021-03-02 22:00:51 +01:00
QtPostProcessHelpers.cmake CMake: also allow building tools when found elsewhere in host builds 2022-05-04 15:20:35 +02:00
QtPrecompiledHeadersHelpers.cmake
QtPriHelpers.cmake CMake: also allow building tools when found elsewhere in host builds 2022-05-04 15:20:35 +02:00
QtPrlHelpers.cmake Fix generated pri and prl files 2021-07-17 02:42:13 +08:00
QtProcessConfigureArgs.cmake Map the 'verbose' configure option to CMake 2022-04-06 16:46:59 +02:00
QtProperties.cmake
QtPublicCMakeHelpers.cmake Unify DEPFILE support check 2022-03-21 12:39:49 +01:00
QtPublicCMakeVersionHelpers.cmake Revert "CMake: Warn if cmake_minimum_required has an unsupported low version" 2021-10-04 15:55:10 +02:00
QtPublicDependencyHelpers.cmake CMake: Fix QT_ADDITIONAL_PACKAGES_PREFIX_PATH for cross-builds 2021-08-19 16:42:56 +02:00
QtPublicFinalizerHelpers.cmake Disable finalizers by default for the non-ld linkers 2021-06-19 11:06:04 +02:00
QtPublicFindPackageHelpers.cmake CMake: Add public FindPackageHelpers 2021-06-14 20:58:00 +02:00
QtPublicPluginHelpers.cmake Avoid implicit linking of plugin init library if finalizers were called 2021-09-08 19:51:58 +02:00
QtPublicTargetHelpers.cmake Remove TODOs related to checking CMake 3.21 features post-release 2021-09-18 01:54:08 +10:00
QtPublicToolHelpers.cmake Use IMPORTED_LOCATION of rcc target 2022-02-01 15:06:46 +01:00
QtPublicWalkLibsHelpers.cmake CMake build: generate pkgconfig for public modules 2022-02-28 08:39:54 -03:00
QtPublicWasmToolchainHelpers.cmake wasm: update recommended emscripten to 3.0.0 2021-12-09 03:22:36 +10:00
QtQmakeHelpers.cmake CMake: also allow building tools when found elsewhere in host builds 2022-05-04 15:20:35 +02:00
QtResourceHelpers.cmake CMake: Add OUTPUT_TARGETS option to qt_internal_add_resource 2022-01-20 19:36:00 +01:00
QtRpathHelpers.cmake CMake: Work around build rpath issue when CMAKE_STAGING_PREFIX is set 2022-04-22 14:34:47 +02:00
QtSanitizerHelpers.cmake CMake: Propagate sanitizer flags to public projects 2021-06-25 12:33:58 +02:00
QtScopeFinalizerHelpers.cmake CMake: Allow promoting the Qt libraries to be global targets 2021-06-16 13:22:17 +02:00
QtSeparateDebugInfo.cmake CMake: Fix picking of the binary_for_strip project location 2022-03-29 14:56:14 +02:00
QtSeparateDebugInfo.Info.plist.in
QtSetup.cmake CMake: Fix initialization of QT_BUILD_TOOLS_BY_DEFAULT 2022-05-11 18:53:37 +02:00
QtSimdHelpers.cmake CMake: Teach qt_internal_add_simd to exclude given osx architectures 2021-04-01 18:14:56 +02:00
QtSingleRepoTargetSetBuildHelpers.cmake Add support for building and installing repo target sets 2021-05-20 12:08:33 +02:00
QtStandaloneTestsConfig.cmake.in
QtSyncQtHelpers.cmake CMake: Remove unnecessary IF DEFINED HOST_PERL check 2021-09-08 14:20:05 +02:00
QtTargetHelpers.cmake build system: support module local definitions 2022-03-11 20:32:08 +01:00
QtTestHelpers.cmake Add WASM testrunner 2022-03-31 16:50:25 +02:00
QtToolchainHelpers.cmake CMake: Handle detection of linux-g++-32 mkspec 2022-04-25 15:42:19 +02:00
QtToolHelpers.cmake CMake: Fix initialization of QT_BUILD_TOOLS_BY_DEFAULT 2022-05-11 18:53:37 +02:00
QtWasmHelpers.cmake wasm: add specialHTMLTargets to EXPORTED_RUNTIME_METHODS for qmake 2022-04-21 13:00:57 +10:00
QtWrapperScriptHelpers.cmake CMake: Generate wrapper shell scripts for all hosts when requested 2022-03-04 01:58:10 +01:00
QtWriteArgsFile.cmake CMake: Bump almost all cmake_minimum_required calls to 3.16 2021-09-22 19:36:49 +02:00
README.md CMake:Android: Use ANDROID_PLATFORM instead of ANDROID_NATIVE_API_LEVEL 2022-03-11 18:30:32 +02:00

Overview

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

CMake Versions

  • 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.

  • For now Qt still ships and builds bundled 3rd party code, due to time constraints on getting all the necessary pieces together in order to remove the bundled code (changes are necessary not only in the build system but in other parts of the SDK like the Qt Installer).

  • 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 does include qmake. qmake is supported as a build system for applications using Qt going forward and will not go away anytime soon.

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)"
  • Build Qt dependencies: brew install pcre2 harfbuzz freetype
  • Install cmake: brew install cmake
  • When running cmake in qtbase, pass -DCMAKE_PREFIX_PATH=/usr/local

Building

The basic way of building with cmake is as follows:

    cd {build directory}
    cmake -DCMAKE_INSTALL_PREFIX=/path/where/to/install {path to source directory}
    cmake --build .
    cmake --install .

The mapping of configure options to CMake arguments is described here.

You need one build directory per Qt module. The build directory can be a sub-directory inside the module qtbase/build or an independent directory qtbase_build. The installation prefix is chosen when running cmake by passing -DCMAKE_INSTALL_PREFIX. To build more than one Qt module, make sure to pass the same install prefix.

cmake --build and cmake --install are simple wrappers around the basic build tool that CMake generated a build system for. It works with any supported build backend supported by cmake, but you can also use the backend build tool directly, e.g. by running make.

CMake has a ninja backend that works quite well and is noticeably faster (and more featureful) than make, so you may want to use that:

    cd {build directory}
    cmake -GNinja -DCMAKE_INSTALL_PREFIX=/path/where/to/install {path to source directory}
    cmake --build .
    cmake --install .

You can look into the generated build.ninja file if you're curious and you can also build targets directly, such as ninja lib/libQt6Core.so.

Make sure to remove CMakeCache.txt if you forgot to set the CMAKE_INSTALL_PREFIX on the first configuration, otherwise a second re-configuration will not pick up the new install prefix.

You can use cmake-gui {path to build directory} or ccmake {path to build directory} to configure the values of individual cmake variables or Qt features. After changing a value, you need to choose the configure step (usually several times:-/), followed by the generate step (to generate makefiles/ninja files).

Developer Build

When working on Qt itself, it can be tedious to wait for the install step. In that case you want to use the developer build option, to get as many auto tests enabled and no longer be required to make install:

    cd {build directory}
    cmake -GNinja -DFEATURE_developer_build=ON {path to source directory}
    cmake --build .
    # do NOT make install

Specifying configure.json features on the command line

QMake defines most features in configure.json files, like -developer-build or -no-opengl.

In CMake land, we currently generate configure.cmake files from the configure.json files into 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. 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.

Building with CCache

You can pass -DQT_USE_CCACHE=ON to make the build system look for ccache in your PATH and prepend it to all C/C++/Objective-C compiler calls. At the moment this is only supported for the Ninja and the Makefile generators.

Cross Compiling

Compiling for a target architecture that's different than the host requires one build of Qt for the 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.

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 -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 setting up your environment. The CMake wiki has further information how to do that at

https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/CrossCompiling

Yocto based device SDKs come with an environment setup script that needs to be sourced in your shell and takes care of setting up environment variables and a cmake alias with a toolchain file, so that you can call cmake as you always do.

In order to make sure that Qt picks up the code generator tools from the host build, you need to pass an extra parameter to cmake:

    -DQT_HOST_PATH=/path/to/your/host_build

The specified path needs to point to a directory that contains an installed host build of Qt.

Cross Compiling for Android

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 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

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

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-v8a
  • x86: -DANDROID_ABI=x86
  • x86_64: -DANDROID_ABI=x86_64

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

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=..., 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_UIKIT_SDK=iphonesimulator
  • iphoneos: -DQT_UIKIT_SDK=iphoneos

Depending on what value you pass to -DQT_UIKIT_SDK= a list of target architectures is chosen by default:

  • iphonesimulator: x86_64
  • iphoneos: arm64
  • simulator_and_device: arm64;x86_64

You can try choosing a different list of architectures by passing -DCMAKE_OSX_ARCHITECTURES=x86_64;i386. 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.

Debugging CMake files

CMake allows specifying the --trace and --trace-expand options, which work like qmake -d -d: As the cmake code is evaluated, the values of parameters and variables is shown. This can be a lot of output, so you may want to redirect it to a file using the --trace-redirect=log.txt option.

Porting Help

We have some python scripts to help with the conversion from qmake to cmake. These scripts can be found in utils/cmake.

configurejson2cmake.py

This script converts all configure.json in the Qt repository to configure.cmake files for use with CMake. We want to generate configure.cmake files for the foreseeable future, so if you need to tweak the generated configure.cmake files, please tweak the generation script instead.

configurejson2cmake.py is run like this: util/cmake/configurejson2cmake.py . in the top-level source directory of a Qt repository.

pro2cmake.py

pro2cmake.py generates a skeleton CMakeLists.txt file from a .pro-file. You will need to polish the resulting CMakeLists.txt file, but e.g. the list of files, etc. should be extracted for you.

pro2cmake.py is run like this: path_to_qtbase_source/util/cmake/pro2cmake.py some.pro.

run_pro2cmake.py

`` A small helper script to run pro2cmake.py on all .pro-files in a directory. Very useful to e.g. convert all the unit tests for a Qt module over to cmake;-)

run_pro2cmake.py is run like this: path_to_qtbase_source/util/cmake/run_pro2cmake.py some_dir.

vcpkg support

The initial port used vcpkg to provide 3rd party packages that Qt requires.

At the moment the Qt CI does not use vcpkg anymore, and instead builds bundled 3rd party sources if no relevant system package is found.

While the supporting code for building with vcpkg is still there, it is not tested at this time.

How to convert certain constructs

qmake CMake
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 .