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 | 392 |
1 files changed, 350 insertions, 42 deletions
diff --git a/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc index 25d69c36c3..b710ba7275 100644 --- a/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc +++ b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// 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 @@ -10,6 +10,7 @@ /*! \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 @@ -21,8 +22,8 @@ find_package(Qt6 REQUIRED COMPONENTS Core) \sa{CMake Variable Reference} */ -*/*! -\page cmake-variable-ANDROID_NDK_HOST_SYSTEM_NAME.html +/*! +\page cmake-variable-android-ndk-host-system-name.html \ingroup cmake-variables-qtcore \title ANDROID_NDK_HOST_SYSTEM_NAME @@ -34,14 +35,14 @@ find_package(Qt6 REQUIRED COMPONENTS Core) \preliminarycmakevariable \cmakevariableandroidonly -This is normally set by the Android NDK toolchain file. It is written out as +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 +\page cmake-variable-android-sdk-root.html \ingroup cmake-variables-qtcore \title ANDROID_SDK_ROOT @@ -53,15 +54,16 @@ part of the deployment settings for a target. \preliminarycmakevariable \cmakevariableandroidonly -This specifies the location of the Android SDK when building for the Android platform. -It is written out as part of the deployment settings for a target. +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 +\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 @@ -72,15 +74,122 @@ It is written out as part of the deployment settings for a target. \preliminarycmakevariable \cmakevariableandroidonly -This contains a list of arguments to be passed to Android applications. It is written -out as part of the deployment settings for a target. +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_BUILD_ALL_ABIS.html +\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 @@ -91,29 +200,30 @@ out as part of the deployment settings for a target. \preliminarycmakevariable \cmakevariableandroidonly -The option automatically detects available ABIs of Qt for Android and uses them to +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 - ... + 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 FALSE by default. +The variable is set to \c FALSE by default. \sa{QT_PATH_ANDROID_ABI_<ABI>} */ /*! -\page cmake-variable-QT_ANDROID_ABIS.html +\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 @@ -124,10 +234,10 @@ The variable is set to FALSE by default. \preliminarycmakevariable \cmakevariableandroidonly -This variable specifies a list of ABIs to be used to build the project packages. +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. It's possible to specify the path to the Qt for Android ABI using +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 @@ -137,7 +247,7 @@ QT_ANDROID_ABIS logic. */ /*! -\page cmake-variable-QT_PATH_ANDROID_ABI.html +\page cmake-variable-qt-path-android-abi.html \ingroup cmake-variables-qtcore \title QT_PATH_ANDROID_ABI_<ABI> @@ -156,7 +266,129 @@ Each variable can be used to specify the path to Qt for Android for the correspo */ /*! -\page cmake-variable-QT_HOST_PATH.html +\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 @@ -165,15 +397,17 @@ Each variable can be used to specify the path to Qt for Android for the correspo \summary {Location of the host Qt installation when cross-compiling.} \cmakevariablesince 6.0 -\preliminarycmakevariable -When cross-compiling, this must be set to the install location of Qt for the host +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). +\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 +\page cmake-variable-qt-no-set-xcode-development-team-id.html \ingroup cmake-variables-qtcore \title QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID @@ -186,11 +420,11 @@ platform. It is used to locate tools to be run on the host (\l{moc}, \l{rcc}, 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. -Set \c QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID to true if you want to prevent this. +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 +\page cmake-variable-qt-no-set-xcode-bundle-identifier.html \ingroup cmake-variables-qtcore \title QT_NO_SET_XCODE_BUNDLE_IDENTIFIER @@ -204,17 +438,17 @@ 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. -Set \c QT_NO_SET_XCODE_BUNDLE_IDENTIFIER to true if you want to prevent this. +To prevent this, set \c QT_NO_SET_XCODE_BUNDLE_IDENTIFIER to \c TRUE. */ /*! -\page cmake-variable-QT_ENABLE_VERBOSE_DEPLOYMENT.html +\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} +\summary {Enables verbose mode of deployment tools.} \cmakevariablesince 6.3 \preliminarycmakevariable @@ -223,12 +457,12 @@ 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{qt_deploy_runtime_dependencies()}), but it +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 +\page cmake-variable-qt-deploy-support.html \ingroup cmake-variables-qtcore \title QT_DEPLOY_SUPPORT @@ -243,19 +477,20 @@ must be set before the first \c{find_package(Qt6)} call to have that effect. 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 +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-runtime-dependencies.qdocinc +\include cmake-deploy-modified-variable-values.qdocinc -\sa qt_deploy_runtime_dependencies(), qt_deploy_qml_imports() +\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 +\page cmake-variable-qt-no-standard-project-setup.html \ingroup cmake-variables-qtcore \title QT_NO_STANDARD_PROJECT_SETUP @@ -264,16 +499,89 @@ an application, along with its runtime dependencies: \summary {Prevents subsequent calls to qt_standard_project_setup() from making any changes.} \cmakevariablesince 6.3 -\preliminarycmakevariable 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 projects may be absorbed as a child project of a larger project +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 true before bringing in the child project -via \l{add_subdirectory()}, \l{FetchContent_MakeAvailable()} or other similar +\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} +*/ |