qt_add_resources

Compiles binary resources into source code.

The command is defined in the Core component of the Qt6 package, which can be loaded like so:

find_package(Qt6 REQUIRED COMPONENTS Core)

Synopsis

qt_add_resources(<VAR> file1.qrc [file2.qrc ...]
                  [OPTIONS ...])

If versionless commands are disabled, use qt6_add_resources() instead. It supports the same set of arguments as this command.

Since 6.0:

qt_add_resources(<TARGET> <RESOURCE_NAME>
                  [PREFIX <PATH>]
                  [LANG <LANGUAGE>]
                  [BASE <PATH>]
                  [BIG_RESOURCES]
                  [OUTPUT_TARGETS <VARIABLE_NAME>]
                  [FILES ...] [OPTIONS ...])

If versionless commands are disabled, use qt6_add_resources() instead. It supports the same set of arguments as this command.

Description

To add resources, you can pass either a variable name or a target as the first argument of the command.

When passing a variable name as first argument, qt_add_resources creates source code from Qt resource files using the Resource Compiler (rcc). Paths to the generated source files are added to <VAR>.

When passing a target as first argument, the function creates a resource with the name RESOURCE_NAME, containing the specified FILES. The resource is automatically linked into TARGET.

See The Qt Resource System for a general description of Qt resources.

Arguments of the target-based variant

PREFIX specifies a path prefix under which all files of this resource are accessible from C++ code. This corresponds to the XML attribute prefix of the .qrc file format. If PREFIX is not given, the target property QT_RESOURCE_PREFIX is used. Since 6.5, PREFIX is optional. If it is omitted and not specified by QT_RESOURCE_PREFIX, "/" will be used as the default path prefix.

LANG specifies the locale of this resource. This corresponds to the XML attribute lang of the .qrc file format.

BASE is a path prefix that denotes the root point of the file's alias. For example, if BASE is "assets" and FILES is "assets/images/logo.png", then the alias of that file is "images/logo.png".

Alias settings for files need to be set via the QT_RESOURCE_ALIAS source file property.

BIG_RESOURCES can be specified to enable support for big resources. This directly generates object files (.o, .obj) instead of C++ source code. This allows embedding bigger resources, without having to compile generated C++ sources, which can be too time consuming and memory intensive.

Note that BIG_RESOURCES is not compatible with iOS due to restrictions of CMake's Xcode project generator. See QTBUG-103497 for details. Also, BIG_RESOURCES only works reliably from CMake 3.17 onwards.

When using this command with static libraries, one or more special targets will be generated. Should you wish to perform additional processing on these targets, pass a variable name to the OUTPUT_TARGETS parameter. The qt_add_resources function stores the names of the special targets in the specified variable.

Arguments of both variants

You can set additional OPTIONS that should be added to the rcc calls. You can find possible options in the rcc documentation.

Examples

Variable variant, using a .qrc file:

set(SOURCES main.cpp)
qt_add_resources(SOURCES example.qrc)
qt_add_executable(myapp ${SOURCES})

Target variant, using immediate resources:

qt_add_executable(myapp main.cpp)
qt_add_resources(myapp "images"
    PREFIX "/images"
    FILES image1.png image2.png)

Caveats

When adding multiple resources, RESOURCE_NAME must be unique across all resources linked into the final target.

This especially affects static builds. There, the same resource name in different static libraries conflict in the consuming target.