1// Copyright (C) 2021 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
6 \title The Qt Resource System
7 \brief A platform-independent mechanism for shipping resource files in an
10 \keyword resource system
12 The Qt resource system is a platform-independent mechanism for shipping
13 resource files in an application. Use it if your application always needs a
14 certain set of files (like icons, translation files, images), and you don't
15 want to use system-specific means to package and locate these resources.
17 Most commonly, the resource files are embedded into your application
18 executable, or in libraries and plugins that are loaded by the application
19 executable. Alternatively, the resource files can also be stored in an
20 \l{External Resource Files}{exernal resource file}.
22 The resource system is based on tight cooperation between Qt's \l rcc
23 resource compiler, the build system, and the Qt runtime API.
25 \note Currently, the Qt resource system does not make use of any
26 system-specific capabilities for handling resources, such as the ones on
27 Windows, \macos, and iOS. This might change in a future Qt release.
29 \section1 The Qt Resource Compiler (rcc)
31 The \l{Resource Compiler (rcc)} command line tool reads resource files and
32 generates either a C++ or Python source file, or an \c .rcc file.
34 The list of files and related metadata is passed to \c rcc in the form of a
35 \l{Qt Resource Collection File}.
37 By default, rcc will generate C++ source code that is then compiled as part
38 of an executable or library. The \c{-g python} option generates Python
39 source code instead. The \c -binary option generates a binary archive that
40 is by convention saved in an \c .rcc file and can be loaded at runtime.
42 \note While it is possible to run \c rcc from the command line, this is
43 typically best left to a build system. See also the sections about
44 \l{qmake} and \l{CMake} below.
46 \section1 Qt Resource Collection File (.qrc)
47 \target {Qt Resource Collection File}
48 \target {Resource Collection Files}
50 A \c .qrc file is an XML document that enumerates local files to be
51 included as runtime resources. It serves as input to \c{rcc}.
53 Here's an example \c .qrc file:
55 \quotefile resource-system/application.qrc
57 Each \c <file> element in the XML identifies a file in the application's
58 source tree. The path is resolved relative to the directory containing
61 The path is also used by default to identify the file's content at runtime.
62 That is, the file \c titlebarLeft.png will be available in the resource system as
63 \c{:/res/titlebarLeft.png} or \c{qrc:/res/titlebarLeft.png}.
64 To override this default run-time name, see \l{Prefixes} and \l{Aliases}.
66 \e{Qt Creator}, \e{Qt Design Studio}, \QD, and \e{Qt Visual Studio Tools}
67 allow you to create, inspect and edit \c .qrc files through a convenient
68 user interface. Except for \QD, they also provide wizards for projects
69 using the Qt resource system.
71 \section1 Build System Integration
73 The processing of resource files with \c rcc is typically done at the time
74 the application is built. Several build tools have dedicated support for
75 this, including \l CMake and \l qmake.
79 If \c CMAKE_AUTORCC is enabled, you can just add \c .qrc files as sources
80 to your executable or library. The referenced resource files will then be
81 embedded into the binary:
83 \snippet resource-system/CMakeLists.txt AUTORCC
85 See \l {https://cmake.org/cmake/help/latest/prop_tgt/AUTORCC.html}
86 {CMake's AUTORCC documentation} for more details about AUTORCC.
88 An alternative to AUTORCC is using Qt6Core's CMake function
89 \l qt_add_resources, which gives more control over the creation of
90 resources. For example, it allows you to specify the content of the
91 resource directly in the project file without writing a \c .qrc file first:
93 \snippet resource-system/CMakeLists.txt qt_add_resources
95 Finally, \l qt_add_qml_module allows you to embed Qt Quick resources into
96 the resource system of your application. The function is defined in the
97 \c Qml component of the \c Qt6 CMake package.
101 \l{qmake Manual}{qmake} supports handing resources with the \l{RESOURCES}
102 variable. If you add a \c .qrc file path to the variable, the listed
103 resource files will be embedded into the generated library or executable:
105 \snippet resource-system/application.pro qrc
107 This creates a resource of several \c{.png} files, that are addressable
108 like this: \c{":/res/titlebarLeft.png"}.
110 If the directory layout of the files you want to embed into the resource
111 doesn't match the expectations of the application, you can specify
112 \c{resources.base}. \c base is a path prefix that denotes the root point of
113 the file's alias. In the example above, if \c{resources.base} is set to
114 \c{"res"}, then \c{titlebarLeft.png} is addressable as \c{":/titlebarLeft.png"}.
116 \section1 Runtime API
118 Qt API that deals with iterating and reading files has built-in support for
119 the Qt Resource System. You can pass a resource path instead of a local
120 file path to QFile and QDir, but also for instance to the QIcon, QImage, and
121 QPixmap constructors:
123 \snippet resource-system/mainwindow.cpp 21
125 The \c : prefix makes it explicit that "/images/cut.png" should be loaded
126 from the Qt Resource System.
128 You can also reference the Qt resource system through a QUrl. Use the
129 \c qrc scheme in this case:
131 \snippet resource-system/main.cpp url
133 See the \l{mainwindows/mainwindow}{Mainwindow} example for an actual
134 application that uses Qt's resource system to store its icons.
136 \section1 Advanced Topics
140 A \c .qrc file can set a prefix to be added to each local file name, given
141 in a \c <file> element, to get the name by which the file shall be known
142 within the resource system.
144 Prefixes allow you to structure the resources, avoiding clashes between
145 resource files added through different \c .qrc files in different libraries
148 \note The \c /qt and \c /qt-project.org prefixes are reserved for documented
149 use cases in Qt. The \l{Using qt.conf}{qt.conf} file is for instance looked
150 up in \c{:/qt/etc/qt.conf} or \c{qrc:/qt/etc/qt.conf}.
154 Sometimes it is convenient to make a resource file available under a
155 different path at runtime. \c .qrc files allow this by setting an
158 \snippet code/doc_src_resources.qdoc 0
160 The file is from the application then only accessible as \c :/cut-img.png
161 or \c{qrc:/cut-img.png}.
163 \section2 Discarding the file contents
165 Sometimes you want to add a file node to the resource file system but
166 don't actually want to add the file contents. \c .qrc files allow this
167 by setting the \c empty attribute to \c{true}.
169 \snippet code/doc_src_resources.qdoc 4
171 The resulting file is then still accessible from the application, but
172 its contents are empty.
174 This is useful to strip QML source code from an application binary.
176 \note If you omit the QML source code from the binary, the QML engine has to
177 rely on the compilation units created by \l{qmlcachegen} or \l{qmlsc}.
178 Those are tied to the specific version of Qt they were built with. If you
179 change the version of Qt your application uses, they can't be loaded
182 \section2 Language Selectors
184 Some resources need to change based on the user's locale, such as
185 translation files or icons. \l{Resource Collection Files} support this
186 through a \c lang attribute to the \c qresource tag, specifying a suitable
187 locale string. For example:
189 \snippet code/doc_src_resources.qdoc 2
191 If the user's locale is French (i.e., QLocale::system().language() is
192 French), \c :/cut.jpg or \c qrc:/cut.jpg becomes a reference to the
193 \c cut_fr.jpg image. For other locales, \c cut.jpg is used.
195 See the QLocale documentation for a description of the format to use for
198 See QFileSelector for an additional mechanism to select locale-specific
201 \section2 Embedding Large Files
203 By default, \c rcc embeds the resource files into executables in the form
204 of C++ arrays. This can be problematic especially for large resources.
206 If the compiler takes too long, or even fails because of memory overflow,
207 you can opt into a special mode where the resources are embedded as part of
208 a two-step process. The C++ compiler only reserves enough space in the
209 target executable or library for the resources. The actual embedding of the
210 resource file's content and metadata is then done after the compilation and
211 linking phase, through another rcc call.
213 For CMake, you need to use the \l{qt_add_big_resources} function.
215 \section2 External Resource Files
217 An alternative to embedding the resource files into the binary is to store
218 them in a separate \c .rcc file. \c rcc allows this with the \c -binary
219 option. Such a \c .rcc file must then be loaded at runtime with QResource.
221 For example, a set of resource data specified in a \c .qrc file can be
222 compiled in the following way:
224 \snippet code/doc_src_resources.qdoc 3
226 In the application, this resource would be registered with code like this:
228 \snippet code/doc_src_resources.cpp 4
230 If you use CMake, you can use the \l{qt_add_binary_resources} function
231 to schedule the \c rcc call above:
233 \snippet resource-system/CMakeLists.txt qt_add_binary_resources
235 \section2 Resources in a Qt for Python application
237 The resource collection file is converted to a Python module by using the
238 resource compiler \l rcc:
241 rcc -g python mainwindow.qrc > mainwindow_rc.py
244 The module can then be imported in the application:
247 import mainwindow_rc.py
250 \section2 Compression
252 \c rcc attempts to compress the content to optimize disk space usage in the
253 final binaries. By default, it will perform a heuristic check to determine
254 whether compressing is worth it and will store the content uncompressed if
255 it fails to sufficiently compress. To control the threshold, you can use
256 the \c {-threshold} option, which tells \c rcc the percentage of the
257 original file size that must be gained for it to store the file in
261 rcc -threshold 25 myresources.qrc
264 The default value is "70", indicating that the compressed file must be 70%
265 smaller than the original (no more than 30% of the original file size).
267 It is possible to turn off compression if desired. This can be useful if
268 your resources already contain a compressed format, such as \c .png files,
269 and you do not want to incur the CPU cost at build time to confirm that it
270 can't be compressed. Another reason is if disk usage is not a problem and
271 the application would prefer to keep the content as clean memory pages at
272 runtime. You do this by giving the \c {-no-compress} command line argument.
275 rcc -no-compress myresources.qrc
278 \c rcc also gives you some control over the compression level and
279 compression algorithm, for example:
282 rcc -compress 2 -compress-algo zlib myresources.qrc
285 It is also possible to use \c threshold, \c compress, and \c compress-algo
286 as attributes in a .qrc \c file tag.
290 <file compress="1" compress-algo="zstd">data.txt</file>
294 The above will select the \c zstd algorithm with compression level 1.
296 \c rcc supports the following compression algorithms and compression
300 \li \c best: use the best algorithm among the ones below, at its highest
301 compression level, to achieve the most compression at the expense of
302 using a lot of CPU time during compilation. This value is useful in the
303 XML file to indicate a file should be most compressed, regardless of
304 which algorithms \c rcc supports.
306 \li \c zstd: use the \l{Zstandard Site}{Zstandard} library to compress
307 contents. Valid compression levels range from 1 to 19, 1 is least
308 compression (least CPU time) and 19 is the most compression (most CPU
309 time). The default level is 14. A special value of 0 tells the \c zstd
310 library to choose an implementation-defined default.
312 \li \c zlib: use the \l{https://zlib.net}{zlib} library to compress
313 contents. Valid compression levels range from 1 to 9, with 1 applying
314 the least compression (least CPU time) and 9 the most compression (most
315 CPU time). The special value 0 means "no compression" and should not be
316 used. The default is implementation-defined, but usually is level 6.
318 \li \c none: no compression. This is the same as the \c -no-compress
322 Support for both Zstandard and zlib are optional. If a given library was
323 not detected at compile time, attempting to pass \c {-compress-algo} for
324 that library will result in an error. The default compression algorithm is
325 \c zstd if it is enabled, \c zlib if not.
327 \section2 Explicit Loading and Unloading of Embedded Resources
329 Resources embedded in C++ executable or library code are automatically
330 registered to the Qt resource system in a constructor of an internal
331 global variable. Since the global variables are initialized before
332 main() runs, the resources are available when the program starts to
335 When embedding resources in \e{static} libraries, the C++ linker might
336 remove the static variables that register the resources. If you
337 embed resources in a static library, you therefore need to explicitly
338 register your resources by calling \l Q_INIT_RESOURCE() with the base
339 name of the \c .qrc file.
342 \snippet code/doc_src_resources.cpp 5
344 You can also explicitly remove registered resources from the application,
345 for instance when unloading a plugin. Use \l Q_CLEANUP_RESOURCE() for this.
347 Note: As the resource initializers generated by rcc are declared in the
348 global namespace, your calls to \l Q_INIT_RESOURCE() and
349 \l Q_CLEANUP_RESOURCE() need to be done outside any namespace.
1.9.7 