Qtリソースシステム

Qtリソースシステムは、アプリケーションにリソースファイルを組み込むためのプラットフォーム非依存の仕組みです。アプリケーションで常に特定のファイルセット（アイコン、翻訳ファイル、画像など）が必要であり、これらのリソースのパッケージ化や検索にシステム固有の手段を使用したくない場合に、このシステムを利用してください。

最も一般的なのは、リソースファイルをアプリケーションの実行ファイル、あるいはアプリケーションの実行ファイルによって読み込まれるライブラリやプラグインに埋め込む方法です。あるいは、リソースファイルを外部のリソースファイルに保存することも可能です。

このリソースシステムは、QtのrccResource Compiler、ビルドシステム、およびQtランタイムAPIの緊密な連携に基づいています。

Qt XMLリソースコンパイラ（Resource Compiler 、rcc）

Resource Compiler （rcc）コマンドラインツールは、リソースファイルを読み取り、C++ または Python のソースファイル、あるいは `.rcc ` ファイルを生成します。

ファイルの一覧および関連するメタデータは、Qtリソースコレクションファイルの形式で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 ファイルが含まれるディレクトリを基準として解決されます。

また、このパスはデフォルトで、実行時にファイルの内容を識別するためにも使用されます。つまり、ファイルcopy.png は、リソースシステム内で:/images/copy.png またはqrc:/images/copy.png として利用可能になります。このデフォルトの実行時名を上書きするには、「プレフィックス とエイリアス」を参照してください。

Qt Creator, Qt Design Studio, Qt Widgets Designer, Qt Extension for Visual Studio Code, および Qt 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の代替手段として、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

単純なアプリケーションの場合、qmakeに.qrc ファイルの生成を任せることも可能であり、これにより追加のファイルを維持管理する必要がなくなります:

resources.files = \
    images/copy.png \
    images/cut.png \
    images/new.png \
    images/open.png \
    images/paste.png \
    images/save.png
resources.prefix = /

RESOURCES = resources

これにより、複数の.png ファイルからなるリソースが作成され、次のように参照できます：":/images/copy.png" 。

リソースに埋め込みたいファイルのディレクトリ構成がアプリケーションの想定と一致しない場合は、resources.base を指定できます。base は、ファイルのエイリアスのルートポイントを指定するパスプレフィックスです。以下の例では、resources.base が"images" に設定されている場合、copy.png は":/copy.png" として参照できます。

ランタイム API

QFile QDir QIcon QImage QPixmap

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

: というプレフィックスを付けることで、「/images/cut.png」が Qt リソースシステムから読み込まれるべきであることを明示しています。

QUrl を通じて Qt リソースシステムを参照することもできます。この場合は、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() が French である場合）、:/cut.jpg またはqrc:/cut.jpg は、cut_fr.jpg 画像への参照になります。その他のロケールでは、cut.jpg が使用されます。

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

ロケール固有のリソースを選択するための追加の仕組みについては、QFileSelector を参照してください。

大容量ファイルの埋め込み

デフォルトでは、rcc はリソースファイルを C++ 配列の形式で実行ファイルに埋め込みます。これは、特にリソースのサイズが大きい場合に問題となる可能性があります。

コンパイルに時間がかかりすぎたり、メモリオーバーフローにより失敗したりする場合は、2段階のプロセスを通じてリソースを埋め込む特別なモードを選択することができます。 C++ コンパイラは、ターゲットの実行ファイルまたはライブラリ内に、リソース用に十分な領域を確保するだけです。リソースファイルの内容やメタデータの実際の埋め込みは、コンパイルおよびリンク段階の終了後、別の rcc 呼び出しを通じて行われます。

qmake では、CONFIG 変数に `resources_big ` を追加することで、この機能を有効にできます。

CONFIG += resources_big

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 アプリケーションのリソース

リソースコレクションファイルは、Resource Compilerrcc を使用して 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負荷をかけたくない場合に役立ちます。 もう一つの理由は、ディスク使用量が問題にならず、アプリケーションが実行時にコンテンツをクリーンなメモリページとして保持したい場合です。これを行うには、-no-compress というコマンドライン引数を指定します。

rcc -no-compress myresources.qrc

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

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

また、.qrcファイル内のfile タグの属性として、compress やthreshold を使用することも可能です。アルゴリズムを選択するには、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() の呼び出しは、いかなる名前空間の外で行う必要があります。