summaryrefslogtreecommitdiffstats
path: root/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'src/corelib/doc/src/cmake/cmake-configure-variables.qdoc')
-rw-r--r--src/corelib/doc/src/cmake/cmake-configure-variables.qdoc587
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}
+*/