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}{external 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 \section1 Advanced Topics
137 A \c .qrc file can set a prefix to be added to each local file name, given
138 in a \c <file> element, to get the name by which the file shall be known
139 within the resource system.
141 Prefixes allow you to structure the resources, avoiding clashes between
142 resource files added through different \c .qrc files in different libraries
145 \note The \c /qt and \c /qt-project.org prefixes are reserved for documented
146 use cases in Qt. The \l{Using qt.conf}{qt.conf} file is for instance looked
147 up in \c{:/qt/etc/qt.conf} or \c{qrc:/qt/etc/qt.conf}.
151 Sometimes it is convenient to make a resource file available under a
152 different path at runtime. \c .qrc files allow this by setting an
155 \snippet code/doc_src_resources.qdoc 0
157 The file is from the application then only accessible as \c :/cut-img.png
158 or \c{qrc:/cut-img.png}.
160 \section2 Discarding the file contents
162 Sometimes you want to add a file node to the resource file system but
163 don't actually want to add the file contents. \c .qrc files allow this
164 by setting the \c empty attribute to \c{true}.
166 \snippet code/doc_src_resources.qdoc 4
168 The resulting file is then still accessible from the application, but
169 its contents are empty.
171 This is useful to strip QML source code from an application binary.
173 \note If you omit the QML source code from the binary, the QML engine has to
174 rely on the compilation units created by \l{qmlcachegen} or \l{qmlsc}.
175 Those are tied to the specific version of Qt they were built with. If you
176 change the version of Qt your application uses, they can't be loaded
179 \section2 Language Selectors
181 Some resources need to change based on the user's locale, such as
182 translation files or icons. \l{Resource Collection Files} support this
183 through a \c lang attribute to the \c qresource tag, specifying a suitable
184 locale string. For example:
186 \snippet code/doc_src_resources.qdoc 2
188 If the user's locale is French (i.e., QLocale::system().language() is
189 French), \c :/cut.jpg or \c qrc:/cut.jpg becomes a reference to the
190 \c cut_fr.jpg image. For other locales, \c cut.jpg is used.
192 See the QLocale documentation for a description of the format to use for
195 See QFileSelector for an additional mechanism to select locale-specific
198 \section2 Embedding Large Files
200 By default, \c rcc embeds the resource files into executables in the form
201 of C++ arrays. This can be problematic especially for large resources.
203 If the compiler takes too long, or even fails because of memory overflow,
204 you can opt into a special mode where the resources are embedded as part of
205 a two-step process. The C++ compiler only reserves enough space in the
206 target executable or library for the resources. The actual embedding of the
207 resource file's content and metadata is then done after the compilation and
208 linking phase, through another rcc call.
210 For CMake, you need to use the \l{qt_add_big_resources} function.
212 \section2 External Resource Files
214 An alternative to embedding the resource files into the binary is to store
215 them in a separate \c .rcc file. \c rcc allows this with the \c -binary
216 option. Such a \c .rcc file must then be loaded at runtime with QResource.
218 For example, a set of resource data specified in a \c .qrc file can be
219 compiled in the following way:
221 \snippet code/doc_src_resources.qdoc 3
223 In the application, this resource would be registered with code like this:
225 \snippet code/doc_src_resources.cpp 4
227 If you use CMake, you can use the \l{qt_add_binary_resources} function
228 to schedule the \c rcc call above:
230 \snippet resource-system/CMakeLists.txt qt_add_binary_resources
232 \section2 Resources in a Qt for Python application
234 The resource collection file is converted to a Python module by using the
235 resource compiler \l rcc:
238 rcc -g python mainwindow.qrc > mainwindow_rc.py
241 The module can then be imported in the application:
244 import mainwindow_rc.py
247 \section2 Compression
249 \c rcc attempts to compress the content to optimize disk space usage in the
250 final binaries. By default, it will perform a heuristic check to determine
251 whether compressing is worth it and will store the content uncompressed if
252 it fails to sufficiently compress. To control the threshold, you can use
253 the \c {-threshold} option, which tells \c rcc the percentage of the
254 original file size that must be gained for it to store the file in
258 rcc -threshold 25 myresources.qrc
261 The default value is "70", indicating that the compressed file must be 70%
262 smaller than the original (no more than 30% of the original file size).
264 It is possible to turn off compression if desired. This can be useful if
265 your resources already contain a compressed format, such as \c .png files,
266 and you do not want to incur the CPU cost at build time to confirm that it
267 can't be compressed. Another reason is if disk usage is not a problem and
268 the application would prefer to keep the content as clean memory pages at
269 runtime. You do this by giving the \c {-no-compress} command line argument.
272 rcc -no-compress myresources.qrc
275 \c rcc also gives you some control over the compression level and
276 compression algorithm, for example:
279 rcc -compress 2 -compress-algo zlib myresources.qrc
282 It is also possible to use \c threshold, \c compress, and \c compress-algo
283 as attributes in a .qrc \c file tag.
287 <file compress="1" compress-algo="zstd">data.txt</file>
291 The above will select the \c zstd algorithm with compression level 1.
293 \c rcc supports the following compression algorithms and compression
297 \li \c best: use the best algorithm among the ones below, at its highest
298 compression level, to achieve the most compression at the expense of
299 using a lot of CPU time during compilation. This value is useful in the
300 XML file to indicate a file should be most compressed, regardless of
301 which algorithms \c rcc supports.
303 \li \c zstd: use the \l{Zstandard Site}{Zstandard} library to compress
304 contents. Valid compression levels range from 1 to 19, 1 is least
305 compression (least CPU time) and 19 is the most compression (most CPU
306 time). The default level is 14. A special value of 0 tells the \c zstd
307 library to choose an implementation-defined default.
309 \li \c zlib: use the \l{https://zlib.net}{zlib} library to compress
310 contents. Valid compression levels range from 1 to 9, with 1 applying
311 the least compression (least CPU time) and 9 the most compression (most
312 CPU time). The special value 0 means "no compression" and should not be
313 used. The default is implementation-defined, but usually is level 6.
315 \li \c none: no compression. This is the same as the \c -no-compress
319 Support for both Zstandard and zlib are optional. If a given library was
320 not detected at compile time, attempting to pass \c {-compress-algo} for
321 that library will result in an error. The default compression algorithm is
322 \c zstd if it is enabled, \c zlib if not.
324 \section2 Explicit Loading and Unloading of Embedded Resources
326 Resources embedded in C++ executable or library code are automatically
327 registered to the Qt resource system in a constructor of an internal
328 global variable. Since the global variables are initialized before
329 main() runs, the resources are available when the program starts to
332 When embedding resources in \e{static} libraries, the C++ linker might
333 remove the static variables that register the resources. If you
334 embed resources in a static library, you therefore need to explicitly
335 register your resources by calling \l Q_INIT_RESOURCE() with the base
336 name of the \c .qrc file.
339 \snippet code/doc_src_resources.cpp 5
341 You can also explicitly remove registered resources from the application,
342 for instance when unloading a plugin. Use \l Q_CLEANUP_RESOURCE() for this.
344 Note: As the resource initializers generated by rcc are declared in the
345 global namespace, your calls to \l Q_INIT_RESOURCE() and
346 \l Q_CLEANUP_RESOURCE() need to be done outside any namespace.
1.10.0