// Copyright (C) 2021 The Qt Company Ltd.
// Copyright (C) 2019 Luxoft Sweden AB
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!

\page use-qt-resources.html
\title Using Qt Resources
\brief Discusses compiling, loading and accesses resources in your program's executable.
\ingroup qtappman
\ingroup qtappman-highlights


\l{The Qt Resource System} lets you store files in your program's executable. In some ways,
this feature resembles a dedicated file system, which we call \e{resource file system}. Usually,
this file system contains QML code and other assets like images. If you use the QML compiler, the
compiled code is always placed in the resource file system. This leads to a few application manager
specific considerations, especially when your application needs to support both single-process and
multi-process modes.

\section1 Compiling Resources

You can add resources as \l{External Resource Files}{external binary resources} or as
\l{Resource Collection Files}{compiled-in resources}; both are generated from a \c .qrc file.
Typically, external binary resources are stored in a file with the \c .rcc extension, whereas
compiled-in resources are stored in libraries in the Application Manager context.

It's important to understand that each process has its own resource file system. Consequently, to
support multi-process mode, resources must be generated separately for the System UI and for each
application. Conversely, in single-process mode there is only one resource file system and you must
ensure that file paths don't clash. To prevent clashes, we recommend you prefix each application
file path with the unique application ID.

Consider the following application file structure:

\badcode
apps
|---- spaceinvaders
|     |---- main.qml
|     |---- spaceinvaders.qrc
|     ...
|---- grandtheftdolphin
|     |---- main.qml
|     |---- grandtheftdolphin.qrc
|     ...
\endcode

Without a prefix, in single-process mode, the \c main.qml files would clash. To avoid this, the
\c .qrc file for spaceinvaders should read like this:

\badcode
<!DOCTYPE RCC><RCC version="1.0">
<qresource prefix="spaceinvaders">
    <file>main.qml</file>
</qresource>
</RCC>
\endcode

For \c grandtheftdolphin the prefix should be "grandtheftdolphin", respectively.
Generally, all files contained in any \c .qrc file should be unique; this also
includes files that the System UI uses.


\section1 Loading Resources

In addition to the approaches described in \l{The Qt Resource System}, the Application Manager
provides configuration options to load resources, both -- external binary resources and
compiled-in resources in the form of a library.

Suppose you have a \c my.rcc binary file and a \c myplugin.so library file. These can be loaded
into the System UI by adding the following lines to the \c am-config.yaml file:

\badcode
ui:
  resources: [ "${CONFIG_PWD}/my.rcc",
               "${CONFIG_PWD}/myplugin.so" ]
\endcode

You can also load these two files into an application by adding the following snippet to the
\c info.yaml file:

\badcode
runtimeParameters:
  resources: [ "my.rcc",
               "myplugin.so" ]
\endcode

The resources are loaded when the System UI starts, before the QML engine is instantiated. In
multi-process mode the application resources are also loaded into the application process at
startup. In single-process mode, resources are loaded when the application first starts and then
reused on subsequent invocations; they are never unloaded.

\section1 Accessing Resources

The application manager allows for file access in the resource file system, either with the URL
scheme (\c{qrc}) or the file name prefix (\c{:}). Both these options require an absolute file path
in the resource file system, such as:

\list
  \li \c{qrc:/spaceinvaders/main.qml} or \c{qrc:///spaceinvaders/main.qml}
  \li \c{:/spaceinvaders/main.qml}
\endlist

While the Qt Application Manager accepts this relaxed naming structure, the QML engine
distinguishes between URLs and file names. For instance, an \l{Image::source}
{Image source} property only accepts the \c{qrc} scheme.

If you want to specify a relative path, don't use the scheme or file path prefix.

If your files aren't found in the resource file system, you can list the contents of the entire
resource file system with the following code snippet:

\code
QDirIterator it(qSL(":"), QDirIterator::Subdirectories);
while (it.hasNext()) {
    const QString fn = it.next();
    if (!fn.startsWith(qSL(":/qt-project.org")))  // exclude Qt internal files
        qDebug() << fn;
}
\endcode

*/