Setting CMake variables and properties

Qt's CMake API is controlled by CMake variables and CMake properties. The CMake Variable Reference and the CMake Property Reference list which ones exist and what they do. This page describes where to set them, and what to watch out for when you do.

Variables and properties

A CMake variable holds a value in the scope of the directory or function where it is set. Variables are set with the set() command.

A cache variable is stored in the CMakeCache.txt file of the build directory and persists across CMake runs. Cache variables are the ones you can set from outside the project: on the command line, in a preset, or in an IDE.

A property is attached to an entity: a target, a source file, a directory, or the global scope. Properties are always set from within the project.

Setting variables

In the project

Use the set() command to set a variable in the project's CMakeLists.txt:

set(QT_I18N_TRANSLATED_LANGUAGES de fr)

The variable is visible in the current directory scope and in every subdirectory that is added afterwards, but not in sibling directories or in the parent directory.

Set the variable before the command that reads it. The documentation of a variable states when it is read. Some variables are read while the Qt package is loaded and have to be set before the first find_package(Qt6) call. QT_ENABLE_VERBOSE_DEPLOYMENT is one of them:

cmake_minimum_required(VERSION 3.16)
project(MyApp)

set(QT_ENABLE_VERBOSE_DEPLOYMENT ON)

find_package(Qt6 REQUIRED COMPONENTS Widgets)
qt_standard_project_setup()

qt_add_executable(MyApp main.cpp)

A set() call without the CACHE keyword creates an ordinary variable that hides a cache variable of the same name in that scope. If a value is meant to be configurable from outside the project, do not overwrite it with an unconditional set().

From outside the project

Cache variables are set with -D when you configure the project:

cmake -DQT_ENABLE_VERBOSE_DEPLOYMENT=ON -S <source-dir> -B <build-dir>

They can also be set in a CMakePresets.json file or in a CMake GUI. None of this is specific to Qt. See the CMake User Interaction Guide for the general mechanics, and cmake-presets(7) for the preset file format.

The qt-cmake script forwards all of its arguments to CMake, so -D works there as well:

C:\Qt\6.13.0\msvc2022_64\bin\qt-cmake -DQT_ENABLE_VERBOSE_DEPLOYMENT=ON -S <source-dir> -B <build-dir>

In an IDE

In Qt Creator, go to Projects > Build to open the build settings of the current kit. The CMake section lists the variables in two groups:

• Initial Configuration holds the variables that Qt Creator passes to CMake when it configures the build directory from scratch, such as CMAKE_PREFIX_PATH.
• Current Configuration shows the current contents of CMakeCache.txt.

Both groups have a Batch Edit button that lets you enter several -D arguments at once, in the same syntax you would use on the command line. Qt Creator re-runs CMake when you apply the changes. For details, see Qt Creator: CMake Build Configuration, Qt Creator: Override CMake settings for a project, and Qt Creator: CMake Presets.

In Visual Studio Code, the CMake Tools extension reads presets, and takes individual variables from the cmake.configureSettings object in .vscode/settings.json. See Qt Extension for Visual Studio Code Documentation for how to set up Qt in Visual Studio Code. Visual Studio reads CMakePresets.json, or CMakeSettings.json if no presets file exists.

Setting properties

Properties cannot be set with -D. They are always set from the project, with the set_property() command or one of its convenience wrappers.

Target properties

Set target properties after the target has been created, and before the command that reads them:

qt_add_executable(MyApp main.cpp)

set_target_properties(MyApp PROPERTIES
    QT_RESOURCE_PREFIX "/myapp"
)

qt_add_resources(MyApp "images" FILES logo.png)

The set_property() command is equivalent and can append to a property that holds a list:

set_property(TARGET MyApp PROPERTY QT_ANDROID_EXTRA_LIBS "${extra_lib}")
set_property(TARGET MyApp APPEND PROPERTY QT_ANDROID_EXTRA_LIBS "${another_lib}")

Properties that Qt reads during target finalization, such as the Android packaging properties, must be set before qt_finalize_target() runs. If you do not call qt_finalize_target() yourself, finalization happens at the end of the directory scope, so setting the property anywhere in the same CMakeLists.txt is sufficient.

Source file properties

Use set_source_files_properties():

set_source_files_properties(images/logo.png PROPERTIES
    QT_RESOURCE_ALIAS "logo.png"
)

qt_add_resources(MyApp "images" FILES images/logo.png)

Directory properties

Directory properties apply to the current directory scope and are inherited by subdirectories that are added afterwards:

set_directory_properties(PROPERTIES QT_EXCLUDE_FROM_TRANSLATION ON)

Global properties

Global properties apply to the whole build:

set_property(GLOBAL PROPERTY QT_TARGETS_FOLDER "MyQtTargets")

Making a property configurable from outside the project

To control a property from the command line or an IDE, route it through a cache variable:

set(MY_APP_ANDROID_PACKAGE_NAME "org.example.myapp"
    CACHE STRING "Android package name of MyApp")

set_target_properties(MyApp PROPERTIES
    QT_ANDROID_PACKAGE_NAME "${MY_APP_ANDROID_PACKAGE_NAME}"
)

The property can then be changed with:

cmake -DMY_APP_ANDROID_PACKAGE_NAME=org.example.myapp.beta -S <source-dir> -B <build-dir>