Qtリソースシステム

Qt リソースシステムは、アプリケーション内のリソースファイルを出荷するための、プラットフォームに依存しないメカニズムです。アプリケーションが常に特定のファイル（アイコンや翻訳ファイル、画像など）を必要とし、これらのリソースをパッケージ化したり配置したりするためにシステム固有の手段を使いたくない場合に使用します。

ほとんどの場合、リソースファイルはアプリケーションの実行ファイルに埋め込まれるか、アプリケーションの実行ファイルによってロードされるライブラリやプラグインに埋め込まれます。あるいは、リソース・ファイルは外部リソース・ファイルに格納することもできます。

リソースシステムは、Qtのrccリソースコンパイラ、ビルドシステム、QtランタイムAPIの緊密な連携に基づいています。

QtResource Compiler (rcc)

Resource Compiler (rcc)コマンドラインツールはリソースファイルを読み込み、C++ または Python ソースファイル、または.rcc ファイルを生成します。

ファイルのリストと関連するメタデータは、Qt Resource Collection File の形式でrcc に渡されます。

デフォルトでは、rccはC++ソースコードを生成し、実行ファイルまたはライブラリの一部としてコンパイルされます。-g python オプションは、代わりに Python ソースコードを生成します。-binary オプションはバイナリ・アーカイブを生成します。このバイナリ・アーカイブは.rcc ファイルに保存され、実行時に読み込むことができます。

Qt リソースコレクションファイル (.qrc)

.qrc ファイルは、ランタイムリソースとして含めるローカルファイルを列挙した XML ドキュメントです。rcc への入力として機能します。

以下は.qrc ファイルの例です：

<RCC>
    <qresource prefix="/">
        <file>images/copy.png</file>
        <file>images/cut.png</file>
        <file>images/new.png</file>
        <file>images/open.png</file>
        <file>images/paste.png</file>
        <file>images/save.png</file>
    </qresource>
</RCC>

XML 内の各<file> 要素は、アプリケーションのソース・ツリー内のファイルを識別します。パスは、.qrc ファイルを含むディレクトリからの相対パスで解決されます。

パスはデフォルトで、実行時にファイルの内容を識別するためにも使用される。つまり、ファイルtitlebarLeft.png は、リソース・システムでは:/res/titlebarLeft.png またはqrc:/res/titlebarLeft.png として使用されます。このデフォルトのランタイム名を上書きするには、「接頭辞と エイリアス」を参照してください。

Qt Creator, Qt Design StudioQt Widgets DesignerQt Visual Studio Toolsでは、便利なユーザー・インターフェースを通じて、.qrc ファイルを作成、検査、編集することができます。Qt Widgets Designer を除き、Qt リソース・システムを使用するプロジェクト用のウィザードも提供されています。

ビルドシステムの統合

rcc でのリソースファイルの処理は、通常、アプリケーションのビルド時に行われます。CMakeや qmakeなど、いくつかのビルドツールはこのための専用サポートを持っています。

CMake

CMAKE_AUTORCC が有効になっていれば、.qrc ファイルをソースとして実行ファイルやライブラリに追加するだけです。参照されたリソースファイルは、バイナリに埋め込まれます：

set(CMAKE_AUTORCC ON)

qt_add_executable(my_app
    application.qrc
    main.cpp
)

AUTORCC の詳細については、CMake の AUTORCC ドキュメントを参照してください。

AUTORCCの詳細については、CMakeのAUTORCCのドキュメントを参照してください。AUTORCCの代わりに、Qt6CoreのCMake関数qt_add_resourcesを使用することもできます。例えば、.qrc ファイルを最初に記述することなく、プロジェクトファイル内でリソースの内容を直接指定することができます：

qt_add_resources(my_app "app_images"
    PREFIX "/"
    FILES
        images/copy.png
        images/cut.png
        images/new.png
        images/open.png
        images/paste.png
        images/save.png
)

最後に、qt_add_qml_module を使うと、Qt Quick リソースをアプリケーションのリソースシステムに埋め込むことができます。この関数はQt6 CMake パッケージのQml コンポーネントで定義されています。

qmake

qmakeは、RESOURCES変数を使ったリソースの受け渡しをサポートしています。この変数に.qrc ファイルパスを追加すると、リストされたリソースファイルが生成されるライブラリや実行ファイルに埋め込まれます：

RESOURCES = application.qrc

これは、次のようにアドレス指定可能な、いくつかの.png ファイルからなるリソースを作成します:":/res/titlebarLeft.png".

リソースに埋め込みたいファイルのディレクトリレイアウトがアプリケーションの期待に合わない場合は、resources.base を指定することができます。base は、ファイルのエイリアスのルートポイントを示すパスプレフィックスです。上の例では、resources.base を"res" に設定すると、titlebarLeft.png は":/titlebarLeft.png" としてアドレス指定可能です。

ランタイムAPI

ファイルの反復処理や読み込みを行う Qt API には、Qt Resource System のサポートが組み込まれています。QFile やQDir だけでなく、QIcon 、QImage 、QPixmap のコンストラクタにも、ローカル・ファイル・パスの代わりにリソース・パスを渡すことができます：

    cutAct = new QAction(QIcon(":/images/cut.png"), tr("Cu&t"), this);

: の接頭辞は、"/images/cut.png" が Qt Resource System から読み込まれることを明示します。

QUrlこの場合、qrc スキームを使用してください：

    QQmlApplicationEngine engine;
    engine.load(QUrl("qrc:/myapp/main.qml"));

高度なトピック

接頭辞

.qrc ファイルは、<file> 要素で与えられた各ローカルファイル名に追加する接頭辞を設定し、リソースシステム内でファイルが知られる名前を得ることができます。

プレフィックスによってリソースを構造化することができ、異なるライブラリやプラグインの異なる.qrc ファイルを通して追加されたリソースファイル間の衝突を避けることができます。

エイリアス

.qrc ファイルは、alias 属性を設定することで、これを可能にします：

<file alias="cut-img.png">images/cut.png</file>

ファイルはアプリケーションから:/cut-img.png またはqrc:/cut-img.png としてのみアクセス可能です。

ファイルの内容を破棄する

リソース・ファイル・システムにファイル・ノードを追加したいが、実際にはファイル・コンテンツを追加したくない場合があります。.qrc ファイルは、empty 属性をtrue に設定することで、これを可能にします。

<file empty="true">Button.qml</file>

こうしてできたファイルは、アプリケーションからはアクセスできますが、中身は空です。

これは、アプリケーションのバイナリからQMLのソースコードを取り除くのに便利です。

言語セレクタ

翻訳ファイルやアイコンのように、ユーザーのロケールに応じて変更する必要があるリソースがあります。リソースコレクションファイルでは、qresource タグにlang 属性を指定し、適切なロケール文字列を指定することで、これをサポートしています。例えば

<qresource>
    <file>cut.jpg</file>
</qresource>
<qresource lang="fr">
    <file alias="cut.jpg">cut_fr.jpg</file>
</qresource>

ユーザーのロケールがフランス語（すなわち、QLocale::system().language() がフランス語）の場合、:/cut.jpg またはqrc:/cut.jpg はcut_fr.jpg 画像への参照になります。その他のロケールの場合は、cut.jpg 。

ロケール文字列に使用する書式については、QLocale のドキュメントを参照してください。

ロケール固有のリソースを選択する追加メカニズムについてはQFileSelector を参照してください。

大きなファイルの埋め込み

デフォルトでは、rcc 、リソース・ファイルはC++配列の形で実行ファイルに埋め込まれます。これは、特に大きなリソースでは問題となることがあります。

Resourceコンパイラに時間がかかりすぎたり、メモリ・オーバーフローで失敗したりする場合は、リソースを2段階のプロセスの一部として埋め込む特別なモードを選択することができます。C++コンパイラは、ターゲット実行ファイルまたはライブラリにリソースのための十分なスペースを確保します。リソースファイルのコンテンツとメタデータの実際の埋め込みは、コンパイルとリンクの後に、別のrccコールによって行われます。

CMakeでは、qt_add_big_resources関数を使用する必要があります。

外部リソースファイル

リソースファイルをバイナリに埋め込む代わりに、リソースファイルを別の.rcc ファイルに保存することもできます。rcc では、-binary オプションを使用します。このような.rcc ファイルは、実行時にQResource でロードする必要があります。

例えば、.qrc ファイルで指定されたリソース・データのセットは、次のようにコンパイルすることができる：

rcc -binary myresource.qrc -o myresource.rcc

アプリケーションでは、このリソースは次のようなコードで登録される：

QResource::registerResource("/path/to/myresource.rcc");

CMakeを使用している場合は、qt_add_binary_resources関数を使用して、上記のrcc ：

qt_add_binary_resources(resources application.qrc DESTINATION application.rcc)
add_dependencies(my_app resources)

Qt for Python アプリケーションのリソース

リソースコレクションファイルはリソースコンパイラrcc を使って Python モジュールに変換されます：

rcc -g python mainwindow.qrc > mainwindow_rc.py

このモジュールはアプリケーションでインポートできます：

import mainwindow_rc.py

圧縮

rcc は、最終的なバイナリのディスク使用量を最適化するために、コンテンツの圧縮を試みます。デフォルトでは、圧縮する価値があるかどうかをヒューリスティックにチェックし、十分に圧縮できなかった場合はコンテンツを非圧縮で保存します。しきい値を制御するには、 オプションを使用します。このオプションは、 に、圧縮形式でファイルを保存するために必要な、元のファイルサイズのパーセンテージを指示します。-threshold rcc

rcc -threshold 25 myresources.qrc

デフォルト値は "70 "で、圧縮ファイルは元のファイルより70%小さくなければならない（元のファイルサイズの30%以下）。

必要に応じて圧縮をオフにすることも可能です。これは、.png ファイルなど、リソースにすでに圧縮形式が含まれていて、ビルド時に圧縮できないことを確認するために CPU コストをかけたくない場合に便利です。もう1つの理由は、ディスク使用量が問題ではなく、アプリケーションが実行時にコンテンツをクリーンなメモリ・ページとして保持することを好む場合です。この場合は、-no-compress コマンドライン引数を指定する。

rcc -no-compress myresources.qrc

rcc また、例えば圧縮レベルや圧縮アルゴリズムを制御することもできる：

rcc -compress 2 -compress-algo zlib myresources.qrc

compress,threshold を .qrcfile タグの属性として使用することも可能です。アルゴリズムを選択するには、compression-algorithm 属性を設定します。

<qresource>
    <file compress="1" compression-algorithm="zstd">data.txt</file>
</qresource>

上記の場合、圧縮レベル1のzstd アルゴリズムが選択されます。

rcc は以下の圧縮アルゴリズムと圧縮レベルをサポートしています：

• bestコンパイル時に多くのCPU時間を使用することを犠牲にして、最も圧縮を達成するために、最も高い圧縮レベルで、以下のものの中で最良のアルゴリズムを使用します。この値は、rcc がどのアルゴリズムをサポートしているかに関係なく、ファイルが最も圧縮されていることを示す XML ファイルで役立ちます。
• zstd: コンテンツの圧縮にはZstandardライブラリを使用します。有効な圧縮レベルは1から19までで、1が最小圧縮（CPU時間が最小）、19が最大圧縮（CPU時間が最大）です。デフォルトのレベルは14です。特別な値0は、zstd ライブラリに、実装で定義されたデフォルトを選択するように指示します。
• zlib:zlibライブラリを使用してコンテンツを圧縮します。有効な圧縮レベルは1から9までで、1が最小の圧縮(最小のCPU時間)、9が最大の圧縮(最大のCPU時間)です。特別な値0は「圧縮なし」を意味し、使用すべきではない。デフォルトは実装によって決まるが、通常はレベル6である。
• none: 圧縮なし。これは-no-compress オプションと同じである。

Zstandardとzlibの両方への対応はオプションである。指定したライブラリがコンパイル時に検出されなかった場合、そのライブラリの-compress-algo を渡そうとするとエラーになります。デフォルトの圧縮アルゴリズムは、有効な場合はzstd 、有効でない場合はzlib 。

組み込みリソースの明示的ロードとアンロード

C++ 実行可能コードやライブラリ・コードに埋め込まれたリソースは、内部グローバル変数のコンストラクタで自動的に Qt リソース・システムに登録されます。グローバル変数はmain()が実行される前に初期化されるため、プログラムの実行開始時にリソースが利用可能になります。

静的ライブラリにリソースを埋め込む場合、C++リンカはリソースを登録する静的変数を削除することがあります。そのため、静的ライブラリにリソースを埋め込む場合は、.qrc ファイルのベース名を指定してQ_INIT_RESOURCE() を呼び出し、明示的にリソースを登録する必要があります。例えば

MyClass::MyClass() : BaseClass()
{
    Q_INIT_RESOURCE(resources);

    QFile file(":/myfile.dat");
    ...
}

プラグインをアンロードするときなど、登録したリソースをアプリケーションから明示的に削除することもできます。この場合はQ_CLEANUP_RESOURCE() を使用します。

注意: rcc が生成するリソース・イニシャライザーはグローバル名前空間で宣言されているため、Q_INIT_RESOURCE() とQ_CLEANUP_RESOURCE() の呼び出しは、名前空間の外で行う必要があります。