Macro qmetaobject::qrc

qrc!() { /* proc-macro */ }

Embed files and made them available to the Qt resource system.

The macro accepts an identifier with optional preceding visibility modifier, and a comma-separated list of resources. Then macro generates a function with given name and visibility, which can be used to register all the resources.

Input

The macro accepts the following formal grammar in pseudo rust macro syntax:

macro call ::= qrc!( $f:Function $( $r:Recource ),* )
Function   ::= $v:vis $name:ident
Resource   ::= $( $base_dir:physical as )? $prefix:virtual { $( $f:File ),* }
File       ::= $path:physical $( as $alias:virtual )?

physical   ::= $path:literal
virtual    ::= $path:literal

Function is the name for the generated function, optionally preceded by the visibility modifier (pub(crate) etc.)

Physical path literal represents path on a local file system; virtual path represents virtual path in the generated qrc resource tree accessible at qrc:///virtual/path URI.

Note that for Resource physical part is optional, meanwhile File has optional Virtual part.

Resources and Files are comma-separated lists.

Resources consist of a

• $base_dir:physical: optional path to base directory on local file system, separated from the prefix by the as keyword. By default, base directory is the cargo project’s root - directory with Cargo.toml, a.k.a. $CARGO_MANIFEST_DIR. (Custom extention which does not interfere with qrc format, but merely resolves physical path of files in this resource relative to the base directory, and helps keeping both project’s root directory and resource definitions clean and short.)
• $prefix:virtual: prefix directory path in qrc’s virtual file system. It will be prepended to every file’s virtual path. (Corresponds to qrc format.)
• A curly-braced list of comma-separated Files.

Files are specified as

• $path:physical: path to the file on local file system. Relative to the resource’s base directory. (Corresponds to qrc format, with the exception below.)
• $alias:virtual: an optional alias in qrc’s virtual file system, separated from the physical path by the as keyword. By default, virtual path of a file is the same as its phisycal path. (Corresponds to qrc format).
• Note about physical path: resource’s base directory is prepended to the file’s physical path before looking for the file on the local file system, but after the physical path is cloned to the virtual counterpart (if the later one was omitted, i.e. no explicit alias was given).

It does not matter if the prefix has leading ‘/’ or not.

Output

The macro creates a function with given name and visibility modifier, that needs to be run in order to register the resource. Function is idempotent, i.e. calling it more than once is allowed but has no effect.

Example

Consider this project files structure:

.
├── Cargo.toml
├── tests/qml
│   ├── qml.qrc
│   ├── main.qml
│   └── Bar.qml
└── src
    └── main.rs

then the following Rust code:

// private fn, and base directory shortcut
qrc!(my_resource_1,
    "tests/qml" as "foo1" {
        "main.qml",
        "Bar.qml" as "baz/Foo.qml",
     }
);

// public fn, no shortcuts
qrc!(pub my_resource_2,
    "foo2" {
        // either use file alias or re-organize files
        "tests/qml/main.qml" as "main.qml",
        "tests/qml/Bar.qml" as "baz/Foo.qml",
     }
);

// registers the resource to Qt
my_resource_1();
my_resource_2();
// do something with resources
use_resource("qrc:/foo1/baz/Foo.qml");
use_resource("qrc:/foo2/baz/Foo.qml");

corresponds to the .qrc (tests/qml/qml.qrc) file:

<RCC>
    <qresource prefix="/foo">
        <file>main.qml</file>
        <file alias="baz/Foo.qml">Bar.qml</file>
    </qresource>
</RCC>

Implementation of the qmetaobject::qrc! macro