qt.conf の使用方法

qt.conf ファイルを使用すると、QLibraryInfo のパスを上書きしたり、プラットフォームプラグインに渡す引数を指定したりできます。

形式と保存場所

qt.conf ファイルは、QSettings のドキュメントに記載されているとおり、INI形式のテキストファイルです。

QLibraryInfo は、以下のいずれかの場所から `qt.conf ` を読み込みます：

1. :/qt/etc/qt.conf リソースシステムを使用する場合
2. Appleプラットフォームでは、アプリケーションバンドル内のResourceディレクトリから読み込みます。たとえば、macOSではassistant.app/Contents/Resources/qt.conf です。
3. アプリケーションの実行ファイルが含まれるディレクトリ内、つまりQCoreApplication::applicationDirPath() +QDir::separator() + "qt.conf"

パスの上書き

qt.conf ファイルを使用すると、Qt が使用するデフォルトのパスを上書きできます。これらのパスには、QLibraryInfo クラスを使用してアクセスできます。

qt.conf がない場合、Qt ライブラリはプラグインや翻訳などを検索するためにデフォルトのパスを使用します。これらのパスは、ターゲットシステム上に存在しない場合や、アクセスできない場合があります。このため、Qt ライブラリに別の場所を検索させるには、qt.conf が必要になる場合があります。

このファイルには、QLibraryInfo::LibraryLocation列挙型の値に対応する1つ以上のエントリを含むPaths グループを記述する必要があります。各ロケーションの意味の詳細については、QLibraryInfo のドキュメントを参照してください。

qt.conf ファイルで指定された絶対パスが使用されます。すべてのパスは、Prefix に対する相対パスです。Windows および Linux では、Prefix はアプリケーションの実行ファイル (QCoreApplication::applicationDirPath()) が格納されているディレクトリに対する相対パスです。macOS では、Prefix はアプリケーションバンドル内のContents に対する相対パスです。 たとえば、application.app/Contents/PlugIns/ は Qt プラグインを読み込むためのデフォルトの場所です。プラグインは、plugins ディレクトリの下の特定のサブディレクトリに配置する必要があることに注意してください（詳細については、「Qt プラグインの作成方法」を参照してください）。

たとえば、qt.conf ファイルには次のような内容が記述される場合があります：

[Paths]
Prefix = /some/path
Translations = i18n

Prefix = c:\\SomePath

Qt 6.8 以降、1 つのエントリにつき複数のパスを指定できるようになりました。これらはコンマ区切りのリストとして指定する必要があります。例えば

QmlImports = "/path/to/imports1","/path/to/imports2"

カンマの前後にスペースを入れることも可能です。また、パスにカンマやスペースが含まれていない場合は、エントリを囲む引用符を省略することもできます。

プラットフォームプラグインへの引数の設定

qt.conf には、Platforms グループが含まれる場合があります。このグループのキーは、プラットフォームプラグインに渡される引数のカンマ区切りリストです。キー名は、プラットフォームプラグインの名前の最初の文字を大文字にし、その後にArguments を付けたものです。

例：

[Platforms]
WindowsArguments = fontengine=freetype

と指定すると、WindowsプラットフォームプラグインはFreeTypeフォントエンジンを使用します。

古いバージョンのQtが並行してインストールされている場合の対処方法

以前のメジャーバージョンの Qt も併せてインストールする必要がある環境では、バージョン固有の qt.conf を使用することができます。これは、ある Qt バージョンから次のバージョンへの移行段階や、バージョン情報が指定されていない既存のファイルによって引き起こされる競合を回避するために、しばしば必要となります。

この目的のため、qt.conf ファイルの代わりにqt6.conf という名前のファイルを使用できます。上記のディレクトリに両方のファイルが存在する場合、qt6.conf が使用されます。