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