diff options
Diffstat (limited to 'src/corelib/doc/src/cmake/cmake-configure-variables.qdoc')
-rw-r--r-- | src/corelib/doc/src/cmake/cmake-configure-variables.qdoc | 587 |
1 files changed, 587 insertions, 0 deletions
diff --git a/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc new file mode 100644 index 0000000000..b710ba7275 --- /dev/null +++ b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc @@ -0,0 +1,587 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/* NOTE: The variables documented here are available when running CMake, they +** are not available in a deployment script. Both these and the set of +** deploy-time variables are all members of the cmake-variables-qtcore +** group. +**/ + +/*! +\group cmake-variables-qtcore +\title CMake Variables in Qt6 Core +\brief Lists CMake variables defined in Qt6::Core. + +The following CMake variables are defined when Qt6::Core is loaded, for instance +with + +\badcode +find_package(Qt6 REQUIRED COMPONENTS Core) +\endcode + +\sa{CMake Variable Reference} +*/ + +/*! +\page cmake-variable-android-ndk-host-system-name.html +\ingroup cmake-variables-qtcore + +\title ANDROID_NDK_HOST_SYSTEM_NAME +\target cmake-variable-ANDROID_NDK_HOST_SYSTEM_NAME + +\summary {Android-specific architecture of the host system.} + +\cmakevariablesince 6.0 +\preliminarycmakevariable +\cmakevariableandroidonly + +Usually, this variable is set by the Android NDK toolchain file. It is written out as +part of the deployment settings for a target. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-variable-android-sdk-root.html +\ingroup cmake-variables-qtcore + +\title ANDROID_SDK_ROOT +\target cmake-variable-ANDROID_SDK_ROOT + +\summary {Location of the Android SDK.} + +\cmakevariablesince 6.0 +\preliminarycmakevariable +\cmakevariableandroidonly + +Specifies the location of the Android SDK when building for the Android platform. +This variable is written out as part of the deployment settings for a target. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()}. +*/ + +/*! +\page cmake-variable-qt-android-application-arguments.html +\ingroup cmake-variables-qtcore +\ingroup cmake-android-manifest-properties + +\title QT_ANDROID_APPLICATION_ARGUMENTS +\target cmake-variable-QT_ANDROID_APPLICATION_ARGUMENTS + +\summary {List of arguments to pass to Android applications.} + +\cmakevariablesince 6.0 +\preliminarycmakevariable +\cmakevariableandroidonly + +Contains a list of arguments to be passed to Android applications. This variable +is written out as part of the deployment settings for a target. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-variable-qt-android-deployment-type.html +\ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_DEPLOYMENT_TYPE +\target cmake-variable-QT_ANDROID_DEPLOYMENT_TYPE + +\summary {Forces or disables release package signing regardless of the build type.} + +\cmakevariablesince 6.7 +\preliminarycmakevariable +\cmakevariableandroidonly + +When set to \c Release, the \c --release flag is passed to the \c +androiddeployqt tool, regardless of the application build type. When set to +another value, the \c --release flag is never passed to the tool, which +effectively disables release package signing even in Release or RelWithDebInfo +builds. When not set, the default behavior is to use release package signing in +build types other than Debug. + +\sa {androiddeployqt} +*/ + +/*! +\page cmake_variable-qt-android-multi-abi-forward-vars +\ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_MULTI_ABI_FORWARD_VARS +\target cmake-variable-QT_ANDROID_MULTI_ABI_FORWARD_VARS + +\summary {Allows to share CMake variables in multi-ABI builds.} + +\cmakevariablesince 6.4.2 +\preliminarycmakevariable +\cmakevariableandroidonly + +Allows specifying the list of +CMake variables that need to be forwarded from the main ABI project to +ABI-specific subprojects. Due to the specifics of the Multi-ABI project build +process, there is no generic way to forward the CMake cache variables +that are specified either in the command line or in another similar way. + +A typical use case for the variable is propagating CMake cache variables +specified in the command line. For example, a project has two variables +\c{PROJECT_WIDE_VARIABLE1} and \c{PROJECT_WIDE_VARIABLE2} that affect the +project configuration: +\badcode +cmake_minimum_required(VERSION 3.18) + +project(MyProject LANGUAGES CXX) + +find_package(Qt6 REQUIRED COMPONENTS Core) + +qt_add_executable(MyApp main.cpp) + +if(PROJECT_WIDE_VARIABLE1) + target_sources(MyApp PRIVATE sourcefile1.cpp) +endif() +if(PROJECT_WIDE_VARIABLE2) + target_sources(MyApp PRIVATE sourcefile2.cpp) +endif() +\endcode + +The above contents of \c{CMakeLists.txt} enable you to control how +\c{MyApp} is built by setting the corresponding CMake variables from the +command line: +\badcode +qt-cmake -S<source directory> -B<build directory> \ + -DPROJECT_WIDE_VARIABLE1=ON \ + -DPROJECT_WIDE_VARIABLE2=ON \ + -DQT_ANDROID_MULTI_ABI_FORWARD_VARS="PROJECT_WIDE_VARIABLE1;PROJECT_WIDE_VARIABLE2" +\endcode + +When configuring the application for desktop, \c{PROJECT_WIDE_VARIABLE1} and +\c{PROJECT_WIDE_VARIABLE2} are visible in CMake listings and scripts as global +cache variables. This doesn't work for Android Multi-ABI builds because +ABI-specific subprojects do not inherit the cache variables from the main-ABI +project. This issue can be solved by passing the list of required variables to +the \c{QT_ANDROID_MULTI_ABI_FORWARD_VARS} variable, so both +\c{PROJECT_WIDE_VARIABLE1} and \c{PROJECT_WIDE_VARIABLE2} values will be +propagated to the ABI-specific builds. + +The variable can be also defined in the project's CMakeLists.txt: +\badcode +... +qt_add_executable(MyApp main.cpp) +... +if(ANDROID) + set(QT_ANDROID_MULTI_ABI_FORWARD_VARS "PROJECT_WIDE_VARIABLE1;PROJECT_WIDE_VARIABLE2") +endif() +... +\endcode + +Set the variable in this way to have a predefined set of +variables that will always be forwarded to ABI-specific projects. + +\note The forwarding is done in the target finalizer, which is implicitly +called when \l{qt6_add_executable}{qt_add_executable()} is used. The +finalization occurs automatically when using CMake 3.19 or later. + +\sa {qt6_finalize_target}{qt_finalize_target()}, + {qt6_add_executable}{qt_add_executable()} +*/ + +/*! +\page cmake-variable-qt-android-build-all-abis.html +\ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_BUILD_ALL_ABIS +\target cmake-variable-QT_ANDROID_BUILD_ALL_ABIS + +\summary {Enables building multi-ABI packages using the autodetected Qt for Android SDK list.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable +\cmakevariableandroidonly + +Automatically detects available ABIs of Qt for Android and uses them to +build a package. The automatic detection expects the default directory structure +supplied by the Qt installer, with the corresponding naming of the directories. +\include cmake-android-supported-abis.qdocinc +The typical directory structure looks as below: +\badcode +/path/to/Qt/6.x.x + android_armv7 + android_arm64_v8a + android_x86 + android_x86_64 + ... +\endcode +The auto-detected paths can be customized using one of \c{QT_PATH_ANDROID_ABI_<ABI>} variables. + +The variable is set to \c FALSE by default. + +\sa{QT_PATH_ANDROID_ABI_<ABI>} +*/ + +/*! +\page cmake-variable-qt-android-abis.html +\ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_ABIS +\target cmake-variable-QT_ANDROID_ABIS + +\summary {List of ABIs that the project packages are built for.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable +\cmakevariableandroidonly + +Specifies a list of ABIs to be used to build the project packages. +\include cmake-android-supported-abis.qdocinc +Each ABI should have the corresponding Qt for Android either installed or +user-built. To specify the path to the Qt for Android ABI, use +the corresponding \c{QT_PATH_ANDROID_ABI_<ABI>} variable. + +\note \c{QT_ANDROID_BUILD_ALL_ABIS} has the higher priority and ignores the +QT_ANDROID_ABIS logic. + +\sa{QT_PATH_ANDROID_ABI_<ABI>}, {QT_ANDROID_BUILD_ALL_ABIS} +*/ + +/*! +\page cmake-variable-qt-path-android-abi.html +\ingroup cmake-variables-qtcore + +\title QT_PATH_ANDROID_ABI_<ABI> +\target cmake-variable-QT_PATH_ANDROID_ABI_<ABI> + +\summary {Set of variables to specify the path to Qt for Android for the corresponding ABI.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable +\cmakevariableandroidonly + +Each variable can be used to specify the path to Qt for Android for the corresponding ABI. +\include cmake-android-supported-abis.qdocinc + +\sa{cmake-variable-QT_ANDROID_ABIS}{QT_ANDROID_ABIS} +*/ + +/*! +\page cmake-variable-qt-android-sign-aab.html +\ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_SIGN_AAB +\target cmake-variable-QT_ANDROID_SIGN_AAB + +\summary {Signs the .aab package with the specified keystore, alias, and store password.} +\cmakevariablesince 6.4 +\preliminarycmakevariable +\cmakevariableandroidonly + +Signs the resulting package. The path of the keystore file, the alias of the key, and passwords +have to be specified by additional environment variables: +\badcode + QT_ANDROID_KEYSTORE_PATH + QT_ANDROID_KEYSTORE_ALIAS + QT_ANDROID_KEYSTORE_STORE_PASS + QT_ANDROID_KEYSTORE_KEY_PASS +\endcode +The mentioned variables are used internally by \l{androiddeployqt}. + +\sa{androiddeployqt} +*/ + +/*! +\page cmake-variable-qt-android-sign-apk.html +\ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_SIGN_APK +\target cmake-variable-QT_ANDROID_SIGN_APK + +\summary {Signs the package with the specified keystore, alias, and store password.} +\cmakevariablesince 6.4 +\preliminarycmakevariable +\cmakevariableandroidonly + +Signs the resulting package. The path of the keystore file, the alias of the key, and passwords +have to be specified by additional environment variables: +\badcode + QT_ANDROID_KEYSTORE_PATH + QT_ANDROID_KEYSTORE_ALIAS + QT_ANDROID_KEYSTORE_STORE_PASS + QT_ANDROID_KEYSTORE_KEY_PASS +\endcode +The mentioned variables are used internally by \l{androiddeployqt}. + +\sa{androiddeployqt} +*/ + +/*! +\page cmake-variable-qt-use-target-android-build-dir.html +\ingroup cmake-variables-qtcore + +\title QT_USE_TARGET_ANDROID_BUILD_DIR +\target cmake-variable-QT_USE_TARGET_ANDROID_BUILD_DIR + +\summary {Enables the use of per-target Android build directories.} + +\cmakevariablesince 6.7 +\preliminarycmakevariable +\cmakevariableandroidonly + +The variable appends the target-specific suffix to the android-build directory. +The variable only takes an effect when it's set in \c CACHE. The variable is +only supported by Qt Creator starting from version 13. +If a single \c CMakeLists.txt contains more than one Android executable and +this option is not set, you will see a warning. To disable the warning, set +\c QT_SKIP_ANDROID_BUILD_DIR_CHECK to \c TRUE. +*/ + +/*! +\page cmake-variable-qt-no-collect-build-tree-apk-deps.html +\ingroup cmake-variables-qtcore + +\title QT_NO_COLLECT_BUILD_TREE_APK_DEPS +\target cmake-variable-QT_NO_COLLECT_BUILD_TREE_APK_DEPS + +\summary {Prevents collecting of project-built shared library targets during Android deployment.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable +\cmakevariableandroidonly + +During project finalization, the build system collects the locations of +all built shared library targets in the project. +These locations are passed to \l androiddeployqt for deployment consideration when +resolving dependencies between libraries. +To disable this behavior, set this variable to \c TRUE. + +\sa {qt6_finalize_project}{qt_finalize_project()} +\sa {cmake-variable-QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS}{QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS} +*/ + +/*! +\page cmake-variable-qt-no-collect-imported-target-apk-deps.html +\ingroup cmake-variables-qtcore + +\title QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS +\target cmake-variable-QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS + +\summary {Prevents collecting of imported targets during Android deployment.} + +\cmakevariablesince 6.5 +\preliminarycmakevariable +\cmakevariableandroidonly + +When using CMake version 3.21 or later, the build system collects the locations of +imported shared library targets that might be relevant for deployment. +The collected targets are those that are reachable from the directory scope +of the currently processed executable target. That includes the target's source directory +scope and its parents. +The collected locations are passed to \l androiddeployqt for deployment consideration when +resolving dependencies between libraries. +To disable this behavior, set this variable to \c TRUE. + +\sa {qt6_finalize_project}{qt_finalize_project()} +\sa {cmake-variable-QT_NO_COLLECT_BUILD_TREE_APK_DEPS}{QT_NO_COLLECT_BUILD_TREE_APK_DEPS} +*/ + +/*! +\page cmake-variable-qt-host-path.html +\ingroup cmake-variables-qtcore + +\title QT_HOST_PATH +\target cmake-variable-QT_HOST_PATH + +\summary {Location of the host Qt installation when cross-compiling.} + +\cmakevariablesince 6.0 + +When cross-compiling, this variable must be set to the install location of Qt for the host +platform. It is used to locate tools to be run on the host (\l{moc}, \l{rcc}, +\l{androiddeployqt}, and so on). It's possible to reuse pre-installed tools +when compiling Qt for host systems too, by using \c QT_HOST_PATH that points to +a pre-installed host Qt and setting the \c QT_FORCE_FIND_TOOLS to \c ON. The Qt +versions should match in this case. +*/ + +/*! +\page cmake-variable-qt-no-set-xcode-development-team-id.html +\ingroup cmake-variables-qtcore + +\title QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID +\target cmake-variable-QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID + +\summary {Disables providing a fallback team ID during target finalization on iOS.} + +\cmakevariablesince 6.1 + +When finalizing an executable target on iOS, +\l{qt6_finalize_target}{qt_finalize_target()} will populate the target's +\c XCODE_ATTRIBUTE_DEVELOPMENT_TEAM property if it hasn't been set. +To prevent this, set \c QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID to \c TRUE. +*/ + +/*! +\page cmake-variable-qt-no-set-xcode-bundle-identifier.html +\ingroup cmake-variables-qtcore + +\title QT_NO_SET_XCODE_BUNDLE_IDENTIFIER +\target cmake-variable-QT_NO_SET_XCODE_BUNDLE_IDENTIFIER + +\summary {Disables providing a fallback app bundle ID during target finalization on iOS.} + +\cmakevariablesince 6.1 + +When finalizing an executable target on iOS, +\l{qt6_finalize_target}{qt_finalize_target()} will populate the target's +\c XCODE_ATTRIBUTE_PRODUCT_BUNDLE_IDENTIFIER and +\c MACOSX_BUNDLE_GUI_IDENTIFIER properties if they haven't been set. +To prevent this, set \c QT_NO_SET_XCODE_BUNDLE_IDENTIFIER to \c TRUE. +*/ + +/*! +\page cmake-variable-qt-enable-verbose-deployment.html +\ingroup cmake-variables-qtcore + +\title QT_ENABLE_VERBOSE_DEPLOYMENT +\target cmake-variable-QT_ENABLE_VERBOSE_DEPLOYMENT + +\summary {Enables verbose mode of deployment tools.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable + +Enables verbose mode of the \l androiddeployqt deployment tool when it is called +internally at build time, usually during target finalization. + +This variable also changes the default verbosity of install-time deployment +scripts for other platforms (see \l{qt6_deploy_runtime_dependencies()}), but it +must be set before the first \c{find_package(Qt6)} call to have that effect. +*/ + +/*! +\page cmake-variable-qt-deploy-support.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_SUPPORT +\target cmake-variable-QT_DEPLOY_SUPPORT + +\summary {Name of the file to include for setting up deployment support.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable +\note The value of this variable should never be modified by project code. + +This configure-phase variable is set by the Core package. It is intended to be +used as the first line of any deployment script to ensure access to the +deployment APIs provided by Qt. Such deployment scripts do not run during +CMake's configure phase. They are executed during installation or as +part of a post-build rule. + +The following example shows one way the variable would be used when installing +an application, along with its runtime dependencies: + +\include cmake-deploy-modified-variable-values.qdocinc + +\sa {qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}, + {qt6_deploy_qml_imports}{qt_deploy_qml_imports()} +*/ + +/*! +\page cmake-variable-qt-no-standard-project-setup.html +\ingroup cmake-variables-qtcore + +\title QT_NO_STANDARD_PROJECT_SETUP +\target cmake-variable-QT_NO_STANDARD_PROJECT_SETUP + +\summary {Prevents subsequent calls to qt_standard_project_setup() from making any changes.} + +\cmakevariablesince 6.3 + +The \l{qt6_standard_project_setup}{qt_standard_project_setup()} command is +typically called in the top level \c{CMakeLists.txt} file of a project. In some +scenarios, such a project may be absorbed as a child project of a larger project +hierarchy. A parent project may want to prevent any child project from applying +changes to the setup. The parent project can achieve this by setting +\c{QT_NO_STANDARD_PROJECT_SETUP} to \c TRUE before bringing in the child project +via \l{add_subdirectory()}, \l{FetchContent_MakeAvailable()}, or other similar +methods provided by CMake. + +\sa {qt6_standard_project_setup}{qt_standard_project_setup()} +*/ + +/*! +\page cmake-variable-qt-i18n-languages.html +\ingroup cmake-variables-qtcore + +\title QT_I18N_TRANSLATED_LANGUAGES +\target cmake-variable-QT_I18N_TRANSLATED_LANGUAGES + +\summary {List of languages to be used for project internationalization.} + +\cmakevariablesince 6.7 + +Specifies a list of languages that are used for project +internationalization. The single languages must be compatible with the +string-based \l QLocale constructor. + +The languages in \c QT_I18N_TRANSLATED_LANGUAGES are used to: +\list + \li Set up executable targets for consuming \c{.qm} files. + \li Automatically construct \c{.ts} file names in + \l{qt6_add_translations}{qt_add_translations()}. +\endlist + +This variable can be conveniently set with the +\l {qt6_standard_project_setup}{qt_standard_project_setup()} command. + +By default, translatable strings are considered to be written in \c{en}. + +\sa {qt6_standard_project_setup}{qt_standard_project_setup()} +\sa {qt6_add_translations}{qt_add_translations()} +*/ + +/*! +\page cmake-variable-qt-i18n-native-language.html +\ingroup cmake-variables-qtcore + +\title QT_I18N_SOURCE_LANGUAGE +\target cmake-variable-QT_I18N_SOURCE_LANGUAGE + +\summary {Specifies the language of translatable strings.} + +\cmakevariablesince 6.7 + +Specifies the language of translatable strings in the source code. +The language must be compatible with the string-based \l QLocale constructor. + +Together with \c{QT_I18N_TRANSLATED_LANGUAGES}, this variable is used to determine the +names of \c{.ts} files for \l{qt6_add_translations}{qt_add_translations()}. + +This variable can be conveniently set with the +\l {qt6_standard_project_setup}{qt_standard_project_setup()} command. + +\sa {qt6_standard_project_setup}{qt_standard_project_setup()} +\sa {qt6_add_translations}{qt_add_translations()} +*/ + +/*! +\page cmake-variable-qt-ios-launch-screen.html +\ingroup cmake-variables-qtcore + +\title QT_IOS_LAUNCH_SCREEN +\target cmake-variable-QT_IOS_LAUNCH_SCREEN + +\summary {Path to iOS launch screen storyboard used by all targets.} + +\cmakevariablesince 6.4 +\preliminarycmakevariable +\cmakevariableiosonly + +Specifies the path to an iOS launch screen storyboard file that will be used +by all targets within a project. + +\sa {Launch Screens and Launch Images} +*/ |