/**************************************************************************** ** ** Copyright (C) 2021 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:FDL$ ** Commercial License Usage ** Licensees holding valid commercial Qt licenses may use this file in ** accordance with the commercial license agreement provided with the ** Software or, alternatively, in accordance with the terms contained in ** a written agreement between you and The Qt Company. For licensing terms ** and conditions see https://www.qt.io/terms-conditions. For further ** information use the contact form at https://www.qt.io/contact-us. ** ** GNU Free Documentation License Usage ** Alternatively, this file may be used under the terms of the GNU Free ** Documentation License version 1.3 as published by the Free Software ** Foundation and appearing in the file included in the packaging of ** this file. Please review the following information to ensure ** the GNU Free Documentation License version 1.3 requirements ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. ** $QT_END_LICENSE$ ** ****************************************************************************/ /*! \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 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 \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 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 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 data.txt \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. */