1// Copyright (C) 2022 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
4/* NOTE: The variables documented here are available when running CMake, they
5** are not available in a deployment script. Both these and the set of
6** deploy-time variables are all members of the cmake-variables-qtcore
11\group cmake-variables-qtcore
12\title CMake Variables in Qt6 Core
13\brief Lists CMake variables defined in Qt6::Core.
15The following CMake variables are defined when Qt6::Core is loaded, for instance
19find_package(Qt6 REQUIRED COMPONENTS Core)
22\sa{CMake Variable Reference}
26\page cmake-variable-android-ndk-host-system-name.html
27\ingroup cmake-variables-qtcore
29\title ANDROID_NDK_HOST_SYSTEM_NAME
30\target cmake-variable-ANDROID_NDK_HOST_SYSTEM_NAME
32\summary {Android-specific architecture of the host system.}
34\cmakevariablesince 6.0
35\preliminarycmakevariable
36\cmakevariableandroidonly
38Usually, this variable is set by the Android NDK toolchain file. It is written out as
39part of the deployment settings for a target.
41\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()}
45\page cmake-variable-android-sdk-root.html
46\ingroup cmake-variables-qtcore
48\title ANDROID_SDK_ROOT
49\target cmake-variable-ANDROID_SDK_ROOT
51\summary {Location of the Android SDK.}
53\cmakevariablesince 6.0
54\preliminarycmakevariable
55\cmakevariableandroidonly
57Specifies the location of the Android SDK when building for the Android platform.
58This variable is written out as part of the deployment settings for a target.
60\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()}.
64\page cmake-variable-qt-android-application-arguments.html
65\ingroup cmake-variables-qtcore
66\ingroup cmake-android-manifest-properties
68\title QT_ANDROID_APPLICATION_ARGUMENTS
69\target cmake-variable-QT_ANDROID_APPLICATION_ARGUMENTS
71\summary {List of arguments to pass to Android applications.}
73\cmakevariablesince 6.0
74\preliminarycmakevariable
75\cmakevariableandroidonly
77Contains a list of arguments to be passed to Android applications. This variable
78is written out as part of the deployment settings for a target.
80\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()}
84\page cmake-variable-qt-android-deployment-type.html
85\ingroup cmake-variables-qtcore
86\ingroup cmake-android-build-properties
88\title QT_ANDROID_DEPLOYMENT_TYPE
89\target cmake-variable-QT_ANDROID_DEPLOYMENT_TYPE
91\summary {Forces or disables release package signing regardless of the build type.}
93\cmakevariablesince 6.7
94\preliminarycmakevariable
95\cmakevariableandroidonly
97When set to \c Release, the \c --release flag is passed to the \c
98androiddeployqt tool, regardless of the application build type. When set to
99another value, the \c --release flag is never passed to the tool, which
100effectively disables release package signing even in Release or RelWithDebInfo
101builds. When not set, the default behavior is to use release package signing in
102build types other than Debug.
108\page cmake_variable-qt-android-multi-abi-forward-vars
109\ingroup cmake-variables-qtcore
110\ingroup cmake-android-build-properties
112\title QT_ANDROID_MULTI_ABI_FORWARD_VARS
113\target cmake-variable-QT_ANDROID_MULTI_ABI_FORWARD_VARS
115\summary {Allows to share CMake variables in multi-ABI builds.}
117\cmakevariablesince 6.4.2
118\preliminarycmakevariable
119\cmakevariableandroidonly
121Allows specifying the list of
122CMake variables that need to be forwarded from the main ABI project to
123ABI-specific subprojects. Due to the specifics of the Multi-ABI project build
124process, there is no generic way to forward the CMake cache variables
125that are specified either in the command line or in another similar way.
127A typical use case for the variable is propagating CMake cache variables
128specified in the command line. For example, a project has two variables
129\c{PROJECT_WIDE_VARIABLE1} and \c{PROJECT_WIDE_VARIABLE2} that affect the
130project configuration:
132cmake_minimum_required(VERSION 3.18)
134project(MyProject LANGUAGES CXX)
136find_package(Qt6 REQUIRED COMPONENTS Core)
138qt_add_executable(MyApp main.cpp)
140if(PROJECT_WIDE_VARIABLE1)
141 target_sources(MyApp PRIVATE sourcefile1.cpp)
143if(PROJECT_WIDE_VARIABLE2)
144 target_sources(MyApp PRIVATE sourcefile2.cpp)
148The above contents of \c{CMakeLists.txt} enable you to control how
149\c{MyApp} is built by setting the corresponding CMake variables from the
152qt-cmake -S<source directory> -B<build directory> \
153 -DPROJECT_WIDE_VARIABLE1=ON \
154 -DPROJECT_WIDE_VARIABLE2=ON \
155 -DQT_ANDROID_MULTI_ABI_FORWARD_VARS="PROJECT_WIDE_VARIABLE1;PROJECT_WIDE_VARIABLE2"
158When configuring the application for desktop, \c{PROJECT_WIDE_VARIABLE1} and
159\c{PROJECT_WIDE_VARIABLE2} are visible in CMake listings and scripts as global
160cache variables. This doesn't work for Android Multi-ABI builds because
161ABI-specific subprojects do not inherit the cache variables from the main-ABI
162project. This issue can be solved by passing the list of required variables to
163the \c{QT_ANDROID_MULTI_ABI_FORWARD_VARS} variable, so both
164\c{PROJECT_WIDE_VARIABLE1} and \c{PROJECT_WIDE_VARIABLE2} values will be
165propagated to the ABI-specific builds.
167The variable can be also defined in the project's CMakeLists.txt:
170qt_add_executable(MyApp main.cpp)
173 set(QT_ANDROID_MULTI_ABI_FORWARD_VARS "PROJECT_WIDE_VARIABLE1;PROJECT_WIDE_VARIABLE2")
178Set the variable in this way to have a predefined set of
179variables that will always be forwarded to ABI-specific projects.
181\note The forwarding is done in the target finalizer, which is implicitly
182called when \l{qt6_add_executable}{qt_add_executable()} is used. The
183finalization occurs automatically when using CMake 3.19 or later.
185\sa {qt6_finalize_target}{qt_finalize_target()},
186 {qt6_add_executable}{qt_add_executable()}
190\page cmake-variable-qt-android-build-all-abis.html
191\ingroup cmake-variables-qtcore
192\ingroup cmake-android-build-properties
194\title QT_ANDROID_BUILD_ALL_ABIS
195\target cmake-variable-QT_ANDROID_BUILD_ALL_ABIS
197\summary {Enables building multi-ABI packages using the autodetected Qt for Android SDK list.}
199\cmakevariablesince 6.3
200\preliminarycmakevariable
201\cmakevariableandroidonly
203Automatically detects available ABIs of Qt for Android and uses them to
204build a package. The automatic detection expects the default directory structure
205supplied by the Qt installer, with the corresponding naming of the directories.
206\include cmake-android-supported-abis.qdocinc
207The typical directory structure looks as below:
216The auto-detected paths can be customized using one of \c{QT_PATH_ANDROID_ABI_<ABI>} variables.
218The variable is set to \c FALSE by default.
220\sa{QT_PATH_ANDROID_ABI_<ABI>}
224\page cmake-variable-qt-android-abis.html
225\ingroup cmake-variables-qtcore
226\ingroup cmake-android-build-properties
228\title QT_ANDROID_ABIS
229\target cmake-variable-QT_ANDROID_ABIS
231\summary {List of ABIs that the project packages are built for.}
233\cmakevariablesince 6.3
234\preliminarycmakevariable
235\cmakevariableandroidonly
237Specifies a list of ABIs to be used to build the project packages.
238\include cmake-android-supported-abis.qdocinc
239Each ABI should have the corresponding Qt for Android either installed or
240user-built. To specify the path to the Qt for Android ABI, use
241the corresponding \c{QT_PATH_ANDROID_ABI_<ABI>} variable.
243\note \c{QT_ANDROID_BUILD_ALL_ABIS} has the higher priority and ignores the
244QT_ANDROID_ABIS logic.
246\sa{QT_PATH_ANDROID_ABI_<ABI>}, {QT_ANDROID_BUILD_ALL_ABIS}
250\page cmake-variable-qt-path-android-abi.html
251\ingroup cmake-variables-qtcore
253\title QT_PATH_ANDROID_ABI_<ABI>
254\target cmake-variable-QT_PATH_ANDROID_ABI_<ABI>
256\summary {Set of variables to specify the path to Qt for Android for the corresponding ABI.}
258\cmakevariablesince 6.3
259\preliminarycmakevariable
260\cmakevariableandroidonly
262Each variable can be used to specify the path to Qt for Android for the corresponding ABI.
263\include cmake-android-supported-abis.qdocinc
265\sa{cmake-variable-QT_ANDROID_ABIS}{QT_ANDROID_ABIS}
269\page cmake-variable-qt-android-sign-aab.html
270\ingroup cmake-variables-qtcore
271\ingroup cmake-android-build-properties
273\title QT_ANDROID_SIGN_AAB
274\target cmake-variable-QT_ANDROID_SIGN_AAB
276\summary {Signs the .aab package with the specified keystore, alias, and store password.}
277\cmakevariablesince 6.4
278\preliminarycmakevariable
279\cmakevariableandroidonly
281Signs the resulting package. The path of the keystore file, the alias of the key, and passwords
282have to be specified by additional environment variables:
284 QT_ANDROID_KEYSTORE_PATH
285 QT_ANDROID_KEYSTORE_ALIAS
286 QT_ANDROID_KEYSTORE_STORE_PASS
287 QT_ANDROID_KEYSTORE_KEY_PASS
289The mentioned variables are used internally by \l{androiddeployqt}.
295\page cmake-variable-qt-android-sign-apk.html
296\ingroup cmake-variables-qtcore
297\ingroup cmake-android-build-properties
299\title QT_ANDROID_SIGN_APK
300\target cmake-variable-QT_ANDROID_SIGN_APK
302\summary {Signs the package with the specified keystore, alias, and store password.}
303\cmakevariablesince 6.4
304\preliminarycmakevariable
305\cmakevariableandroidonly
307Signs the resulting package. The path of the keystore file, the alias of the key, and passwords
308have to be specified by additional environment variables:
310 QT_ANDROID_KEYSTORE_PATH
311 QT_ANDROID_KEYSTORE_ALIAS
312 QT_ANDROID_KEYSTORE_STORE_PASS
313 QT_ANDROID_KEYSTORE_KEY_PASS
315The mentioned variables are used internally by \l{androiddeployqt}.
321\page cmake-variable-qt-use-target-android-build-dir.html
322\ingroup cmake-variables-qtcore
324\title QT_USE_TARGET_ANDROID_BUILD_DIR
325\target cmake-variable-QT_USE_TARGET_ANDROID_BUILD_DIR
327\summary {Enables the use of per-target Android build directories.}
329\cmakevariablesince 6.7
330\preliminarycmakevariable
331\cmakevariableandroidonly
333The variable appends the target-specific suffix to the android-build directory.
334The variable only takes an effect when it's set in \c CACHE. The variable is
335only supported by Qt Creator starting from version 13.
336If a single \c CMakeLists.txt contains more than one Android executable and
337this option is not set, you will see a warning. To disable the warning, set
338\c QT_SKIP_ANDROID_BUILD_DIR_CHECK to \c TRUE.
342\page cmake-variable-qt-no-collect-build-tree-apk-deps.html
343\ingroup cmake-variables-qtcore
345\title QT_NO_COLLECT_BUILD_TREE_APK_DEPS
346\target cmake-variable-QT_NO_COLLECT_BUILD_TREE_APK_DEPS
348\summary {Prevents collecting of project-built shared library targets during Android deployment.}
350\cmakevariablesince 6.3
351\preliminarycmakevariable
352\cmakevariableandroidonly
354During project finalization, the build system collects the locations of
355all built shared library targets in the project.
356These locations are passed to \l androiddeployqt for deployment consideration when
357resolving dependencies between libraries.
358To disable this behavior, set this variable to \c TRUE.
360\sa {qt6_finalize_project}{qt_finalize_project()}
361\sa {cmake-variable-QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS}{QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS}
365\page cmake-variable-qt-no-collect-imported-target-apk-deps.html
366\ingroup cmake-variables-qtcore
368\title QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS
369\target cmake-variable-QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS
371\summary {Prevents collecting of imported targets during Android deployment.}
373\cmakevariablesince 6.5
374\preliminarycmakevariable
375\cmakevariableandroidonly
377When using CMake version 3.21 or later, the build system collects the locations of
378imported shared library targets that might be relevant for deployment.
379The collected targets are those that are reachable from the directory scope
380of the currently processed executable target. That includes the target's source directory
381scope and its parents.
382The collected locations are passed to \l androiddeployqt for deployment consideration when
383resolving dependencies between libraries.
384To disable this behavior, set this variable to \c TRUE.
386\sa {qt6_finalize_project}{qt_finalize_project()}
387\sa {cmake-variable-QT_NO_COLLECT_BUILD_TREE_APK_DEPS}{QT_NO_COLLECT_BUILD_TREE_APK_DEPS}
391\page cmake-variable-qt-host-path.html
392\ingroup cmake-variables-qtcore
395\target cmake-variable-QT_HOST_PATH
397\summary {Location of the host Qt installation when cross-compiling.}
399\cmakevariablesince 6.0
401When cross-compiling, this variable must be set to the install location of Qt for the host
402platform. It is used to locate tools to be run on the host (\l{moc}, \l{rcc},
403\l{androiddeployqt}, and so on). It's possible to reuse pre-installed tools
404when compiling Qt for host systems too, by using \c QT_HOST_PATH that points to
405a pre-installed host Qt and setting the \c QT_FORCE_FIND_TOOLS to \c ON. The Qt
406versions should match in this case.
410\page cmake-variable-qt-no-set-xcode-development-team-id.html
411\ingroup cmake-variables-qtcore
413\title QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID
414\target cmake-variable-QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID
416\summary {Disables providing a fallback team ID during target finalization on iOS.}
418\cmakevariablesince 6.1
420When finalizing an executable target on iOS,
421\l{qt6_finalize_target}{qt_finalize_target()} will populate the target's
422\c XCODE_ATTRIBUTE_DEVELOPMENT_TEAM property if it hasn't been set.
423To prevent this, set \c QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID to \c TRUE.
427\page cmake-variable-qt-no-set-xcode-bundle-identifier.html
428\ingroup cmake-variables-qtcore
430\title QT_NO_SET_XCODE_BUNDLE_IDENTIFIER
431\target cmake-variable-QT_NO_SET_XCODE_BUNDLE_IDENTIFIER
433\summary {Disables providing a fallback app bundle ID during target finalization on iOS.}
435\cmakevariablesince 6.1
437When finalizing an executable target on iOS,
438\l{qt6_finalize_target}{qt_finalize_target()} will populate the target's
439\c XCODE_ATTRIBUTE_PRODUCT_BUNDLE_IDENTIFIER and
440\c MACOSX_BUNDLE_GUI_IDENTIFIER properties if they haven't been set.
441To prevent this, set \c QT_NO_SET_XCODE_BUNDLE_IDENTIFIER to \c TRUE.
445\page cmake-variable-qt-enable-verbose-deployment.html
446\ingroup cmake-variables-qtcore
448\title QT_ENABLE_VERBOSE_DEPLOYMENT
449\target cmake-variable-QT_ENABLE_VERBOSE_DEPLOYMENT
451\summary {Enables verbose mode of deployment tools.}
453\cmakevariablesince 6.3
454\preliminarycmakevariable
456Enables verbose mode of the \l androiddeployqt deployment tool when it is called
457internally at build time, usually during target finalization.
459This variable also changes the default verbosity of install-time deployment
460scripts for other platforms (see \l{qt6_deploy_runtime_dependencies()}), but it
461must be set before the first \c{find_package(Qt6)} call to have that effect.
465\page cmake-variable-qt-deploy-support.html
466\ingroup cmake-variables-qtcore
468\title QT_DEPLOY_SUPPORT
469\target cmake-variable-QT_DEPLOY_SUPPORT
471\summary {Name of the file to include for setting up deployment support.}
473\cmakevariablesince 6.3
474\preliminarycmakevariable
475\note The value of this variable should never be modified by project code.
477This configure-phase variable is set by the Core package. It is intended to be
478used as the first line of any deployment script to ensure access to the
479deployment APIs provided by Qt. Such deployment scripts do not run during
480CMake's configure phase. They are executed during installation or as
481part of a post-build rule.
483The following example shows one way the variable would be used when installing
484an application, along with its runtime dependencies:
486\include cmake-deploy-modified-variable-values.qdocinc
488\sa {qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()},
489 {qt6_deploy_qml_imports}{qt_deploy_qml_imports()}
493\page cmake-variable-qt-no-standard-project-setup.html
494\ingroup cmake-variables-qtcore
496\title QT_NO_STANDARD_PROJECT_SETUP
497\target cmake-variable-QT_NO_STANDARD_PROJECT_SETUP
499\summary {Prevents subsequent calls to qt_standard_project_setup() from making any changes.}
501\cmakevariablesince 6.3
503The \l{qt6_standard_project_setup}{qt_standard_project_setup()} command is
504typically called in the top level \c{CMakeLists.txt} file of a project. In some
505scenarios, such a project may be absorbed as a child project of a larger project
506hierarchy. A parent project may want to prevent any child project from applying
507changes to the setup. The parent project can achieve this by setting
508\c{QT_NO_STANDARD_PROJECT_SETUP} to \c TRUE before bringing in the child project
509via \l{add_subdirectory()}, \l{FetchContent_MakeAvailable()}, or other similar
510methods provided by CMake.
512\sa {qt6_standard_project_setup}{qt_standard_project_setup()}
516\page cmake-variable-qt-i18n-languages.html
517\ingroup cmake-variables-qtcore
519\title QT_I18N_TRANSLATED_LANGUAGES
520\target cmake-variable-QT_I18N_TRANSLATED_LANGUAGES
522\summary {List of languages to be used for project internationalization.}
524\cmakevariablesince 6.7
526Specifies a list of languages that are used for project
527internationalization. The single languages must be compatible with the
528string-based \l QLocale constructor.
530The languages in \c QT_I18N_TRANSLATED_LANGUAGES are used to:
532 \li Set up executable targets for consuming \c{.qm} files.
533 \li Automatically construct \c{.ts} file names in
534 \l{qt6_add_translations}{qt_add_translations()}.
537This variable can be conveniently set with the
538\l {qt6_standard_project_setup}{qt_standard_project_setup()} command.
540By default, translatable strings are considered to be written in \c{en}.
542\sa {qt6_standard_project_setup}{qt_standard_project_setup()}
543\sa {qt6_add_translations}{qt_add_translations()}
547\page cmake-variable-qt-i18n-native-language.html
548\ingroup cmake-variables-qtcore
550\title QT_I18N_SOURCE_LANGUAGE
551\target cmake-variable-QT_I18N_SOURCE_LANGUAGE
553\summary {Specifies the language of translatable strings.}
555\cmakevariablesince 6.7
557Specifies the language of translatable strings in the source code.
558The language must be compatible with the string-based \l QLocale constructor.
560Together with \c{QT_I18N_TRANSLATED_LANGUAGES}, this variable is used to determine the
561names of \c{.ts} files for \l{qt6_add_translations}{qt_add_translations()}.
563This variable can be conveniently set with the
564\l {qt6_standard_project_setup}{qt_standard_project_setup()} command.
566\sa {qt6_standard_project_setup}{qt_standard_project_setup()}
567\sa {qt6_add_translations}{qt_add_translations()}
571\page cmake-variable-qt-ios-launch-screen.html
572\ingroup cmake-variables-qtcore
574\title QT_IOS_LAUNCH_SCREEN
575\target cmake-variable-QT_IOS_LAUNCH_SCREEN
577\summary {Path to iOS launch screen storyboard used by all targets.}
579\cmakevariablesince 6.4
580\preliminarycmakevariable
583Specifies the path to an iOS launch screen storyboard file that will be used
584by all targets within a project.
586\sa {Launch Screens and Launch Images}