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 | 189 |
1 files changed, 151 insertions, 38 deletions
diff --git a/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc index 249326cfd1..8422a688f0 100644 --- a/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc +++ b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc @@ -35,7 +35,7 @@ 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()} @@ -54,8 +54,8 @@ 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()}. */ @@ -63,6 +63,7 @@ It is written out as part of the deployment settings for a target. /*! \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 @@ -73,27 +74,32 @@ 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-deploy-release.html +\page cmake-variable-qt-android-deployment-type.html \ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties -\title QT_ANDROID_DEPLOY_RELEASE -\target cmake-variable-QT_ANDROID_DEPLOY_RELEASE +\title QT_ANDROID_DEPLOYMENT_TYPE +\target cmake-variable-QT_ANDROID_DEPLOYMENT_TYPE -\summary {Set the package type as a release} +\summary {Forces or disables release package signing regardless of the build type.} -\cmakevariablesince 6.5.1 +\cmakevariablesince 6.7 \preliminarycmakevariable \cmakevariableandroidonly -Setting \c{QT_ANDROID_DEPLOY_RELEASE} to true allows to create release package by passing --release -flag to androiddeployqt tool. +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} */ @@ -101,17 +107,18 @@ flag to androiddeployqt tool. /*! \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} +\summary {Allows to share CMake variables in multi-ABI builds.} \cmakevariablesince 6.4.2 \preliminarycmakevariable \cmakevariableandroidonly -The \c{QT_ANDROID_MULTI_ABI_FORWARD_VARS} variable allows specifying the list of +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 @@ -168,8 +175,8 @@ endif() ... \endcode -Setting the variable in this way allows you to have a predefined set of -variables that will always be forwarded to abi-specific projects. +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 @@ -182,6 +189,7 @@ finalization occurs automatically when using CMake 3.19 or later. /*! \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 @@ -192,7 +200,7 @@ finalization occurs automatically when using CMake 3.19 or later. \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 @@ -207,7 +215,7 @@ The typical directory structure looks as below: \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>} */ @@ -215,6 +223,7 @@ The variable is set to FALSE by default. /*! \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 @@ -225,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 @@ -259,16 +268,17 @@ Each variable can be used to specify the path to Qt for Android for the correspo /*! \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 {Sign the .aab package with the specified keystore, alias and store password.} +\summary {Signs the .aab package with the specified keystore, alias, and store password.} \cmakevariablesince 6.4 \preliminarycmakevariable \cmakevariableandroidonly -Sign the resulting package. The path of the keystore file, the alias of the key and passwords +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 @@ -276,7 +286,7 @@ have to be specified by additional environment variables: QT_ANDROID_KEYSTORE_STORE_PASS QT_ANDROID_KEYSTORE_KEY_PASS \endcode -Mentioned variables are used internally by \l{androiddeployqt}. +The mentioned variables are used internally by \l{androiddeployqt}. \sa{androiddeployqt} */ @@ -284,16 +294,17 @@ Mentioned variables are used internally by \l{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 {Sign the package with the specified keystore, alias and store password.} +\summary {Signs the package with the specified keystore, alias, and store password.} \cmakevariablesince 6.4 \preliminarycmakevariable \cmakevariableandroidonly -Sign the resulting package. The path of the keystore file, the alias of the key and passwords +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 @@ -301,12 +312,56 @@ have to be specified by additional environment variables: QT_ANDROID_KEYSTORE_STORE_PASS QT_ANDROID_KEYSTORE_KEY_PASS \endcode -Mentioned variables are used internally by \l{androiddeployqt}. +The mentioned variables are used internally by \l{androiddeployqt}. \sa{androiddeployqt} */ /*! +\page cmake-variable-qt-android-generate-java-qml-components.html +\ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_GENERATE_JAVA_QML_COMPONENTS +\target cmake-variable-QT_ANDROID_GENERATE_JAVA_QML_COMPONENTS + +\summary {Enables the generation of QtQmlComponent-based classes.} +\cmakevariablesince 6.8 +\preliminarycmakevariable +\cmakevariableandroidonly + +This variable enables Java code generation for QML components of the target application. The +generated code will be included in the resulting package. The Java package name of generated +classes will be the same as the Android app package. If the leaf part of the package name is +not the same as the target executable, an extra static class with the same name as the +capitalized target executable will surround all QML modules enclosing Java classes. Each QML +module class, again in a capitalized form, will contain QtQmlComponent extension classes that +represent QML components of that module. +*/ + +\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 @@ -323,7 +378,7 @@ 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. -Set \c QT_NO_COLLECT_BUILD_TREE_APK_DEPS to \c TRUE to disable this behavior. +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} @@ -349,7 +404,7 @@ of the currently processed executable target. That includes the target's source scope and its parents. The collected locations are passed to \l androiddeployqt for deployment consideration when resolving dependencies between libraries. -Set \c QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS to \c TRUE to disable this behavior. +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} @@ -366,9 +421,12 @@ Set \c QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS to \c TRUE to disable this behavio \cmakevariablesince 6.0 -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. */ /*! @@ -385,7 +443,7 @@ 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. */ /*! @@ -403,7 +461,7 @@ 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. */ /*! @@ -413,7 +471,7 @@ Set \c QT_NO_SET_XCODE_BUNDLE_IDENTIFIER to true if you want to prevent this. \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 @@ -442,7 +500,7 @@ 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 @@ -467,24 +525,79 @@ an application, along with its runtime dependencies: 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} +\summary {Path to iOS launch screen storyboard used by all targets.} \cmakevariablesince 6.4 \preliminarycmakevariable |