1// Copyright (C) 2020 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5\page qt-add-resources.html
6\ingroup cmake-commands-qtcore
9\keyword qt6_add_resources
11\summary {Compiles binary resources into source code.}
13\include cmake-find-package-core.qdocinc
18qt_add_resources(<VAR> file1.qrc [file2.qrc ...]
22\versionlessCMakeCommandsNote qt6_add_resources()
27qt_add_resources(<TARGET> <RESOURCE_NAME>
32 [OUTPUT_TARGETS <VARIABLE_NAME>]
33 [FILES ...] [OPTIONS ...])
36\versionlessCMakeCommandsNote qt6_add_resources()
40To add resources, you can pass either a variable name or a target as the first
41argument of the command.
43When passing a variable name as first argument, \c qt_add_resources creates
44source code from Qt resource files using the \l{Resource Compiler (rcc)}. Paths
45to the generated source files are added to \c{<VAR>}.
47When passing a target as first argument, the function creates a resource with
48the name \c{RESOURCE_NAME}, containing the specified \c{FILES}. The resource is
49automatically linked into \c{TARGET}.
51See \l{The Qt Resource System} for a general description of Qt resources.
53\section1 Arguments of the target-based variant
55\c PREFIX specifies a path prefix under which all files of this resource are
56accessible from C++ code. This corresponds to the XML attribute \c prefix of the
57\c .qrc file format. If \c PREFIX is not given, the target property
58\l{cmake-target-property-QT_RESOURCE_PREFIX}{QT_RESOURCE_PREFIX} is used. Since
596.5, \c{PREFIX} is optional. If it is omitted and not specified by
60\c{QT_RESOURCE_PREFIX}, \c{"/"} will be used as the default path prefix.
62\c LANG specifies the locale of this resource. This corresponds to the XML
63attribute \c lang of the \c .qrc file format.
65\c BASE is a path prefix that denotes the root point of the file's alias. For
66example, if \c BASE is \c{"assets"} and \c FILES is
67\c{"assets/images/logo.png"}, then the alias of that file is
70Alias settings for files need to be set via the \c QT_RESOURCE_ALIAS source file
73\c BIG_RESOURCES can be specified to enable support for big resources. This
74directly generates object files (\c .o, \c .obj) instead of C++ source code.
75This allows embedding bigger resources, without having to compile generated C++
76sources, which can be too time consuming and memory intensive.
78Note that \c BIG_RESOURCES is not compatible with iOS due to restrictions of
79CMake's Xcode project generator. See
80\l{https://bugreports.qt.io/browse/QTBUG-103497}{QTBUG-103497} for details.
81Also, \c BIG_RESOURCES only works reliably from CMake 3.17 onwards.
83When using this command with static libraries, one or more special targets will
84be generated. Should you wish to perform additional processing on these targets,
85pass a variable name to the \c OUTPUT_TARGETS parameter. The \c qt_add_resources
86function stores the names of the special targets in the specified variable.
88\section1 Arguments of both variants
90You can set additional \c{OPTIONS} that should be added to the \c{rcc} calls.
91You can find possible options in the \l{rcc}{rcc documentation}.
95Variable variant, using a .qrc file:
96\snippet cmake-macros/examples.cmake qt_add_resources
98Target variant, using immediate resources:
99\snippet cmake-macros/examples.cmake qt_add_resources_target
103When adding multiple resources, \c{RESOURCE_NAME} must be unique across all
104resources linked into the final target.
106This especially affects static builds. There, the same resource name in
107different static libraries conflict in the consuming target.
109\sa {qt6_add_big_resources}{qt_add_big_resources()}