Qt for Windows - デプロイメント

このドキュメントでは、Windows 用のデプロイメントプロセスについて説明します。このドキュメントでは、Plug & Paint のサンプルアプリケーションを参照して、デプロイメントプロセスを説明します。

Windows デプロイツール

Windows デプロイメント ツールwindeployqt は、Qt 関連の依存関係（ライブラリ、QML インポート、プラグイン、および翻訳）を含むデプロイ可能なフォルダを作成し、そのフォルダからアプリケーションを実行するプロセスを自動化するように設計されています。Windowsデスクトップアプリケーションのインストールツリーを作成し、インストールパッケージに簡単にバンドルすることができます。

QTDIR/bin/windeployqtこのツールを正しく機能させるには、ビルド環境内で実行する必要があります。Qt Online Installer を使用する場合は、スクリプトQTDIR/bin/qtenv2.bat を使用してセットアップする必要があります。

windeployqt スクリプトは、 ファイルか、 ファイルを含むディレクトリを引数として取り、実行ファイルの依存関係をスキャンします。 の引数にディレクトリが渡された場合、 は ツールを使ってディレクトリ内の QML ファイルをスキャンし、QML インポートの依存関係を調べます。特定された依存関係は、実行ファイルのディレクトリにコピーされます。.exe .exe --qmldir windeployqt qmlimportscanner

Qt が configure スイッチ-relocatable をオフにしてビルドされた場合、windeployqt は Qt6Core.dll のハードコードされたローカルパスを相対パスに置き換えます。

Windows デスクトップアプリケーションの場合、コンパイラに必要なランタイムファイルもデフォルトで配置可能フォルダーにコピーされます（--no-compiler-runtime オプションが指定されていない限り）。Microsoft Visual C++ を使用するリリー ス・ビルドの場合、これらは Visual C++ 再頒布可能パッケージで構成され、ターゲッ ト・マシン上のアプリケーションのインストーラーによって再帰的にインス トールされるようになっています。それ以外の場合は、コンパイラー・ランタイムの共有ライブラリーが使用されます。

アプリケーションは、windeployqtでは考慮されない追加のサードパーティライブラリ（データベースライブラリなど）を必要とする場合があります。

追加の引数については、ツールのヘルプ出力に記載されています：

Usage: windeployqt [options] [files]
Qt Deploy Tool 6.0.0

The simplest way to use windeployqt is to add the bin directory of your Qt
installation (e.g. <QT_DIR\bin>) to the PATH variable and then run:
  windeployqt <path-to-app-binary>
If ICU, etc. are not in the bin directory, they need to be in the PATH
variable. If your application uses Qt Quick, run:
  windeployqt --qmldir <path-to-app-qml-files> <path-to-app-binary>

Options:
  -?, -h, --help              Displays help on commandline options.
  --help-all                  Displays help including Qt specific options.
  -v, --version               Displays version information.
  --dir <directory>           Use directory instead of binary directory.
  --qmake <path>              Use specified qmake instead of qmake from PATH.
  --libdir <path>             Copy libraries to path.
  --plugindir <path>          Copy plugins to path.
  --debug                     Assume debug binaries.
  --release                   Assume release binaries.
  --pdb                       Deploy .pdb files (MSVC).
  --force                     Force updating files.
  --dry-run                   Simulation mode. Behave normally, but do not
                              copy/update any files.
  --no-patchqt                Do not patch the Qt6Core library.
  --ignore-library-errors     Ignore errors when libraries cannot be found.
  --no-plugins                Skip plugin deployment.
  --no-libraries              Skip library deployment.
  --qmldir <directory>        Scan for QML-imports starting from directory.
  --qmlimport <directory>     Add the given path to the QML module search
                              locations.
  --no-quick-import           Skip deployment of Qt Quick imports.
  --translations <languages>  A comma-separated list of languages to deploy
                              (de,fi).
  --no-translations           Skip deployment of translations.
  --no-system-d3d-compiler    Skip deployment of the system D3D compiler.
  --compiler-runtime          Deploy compiler runtime (Desktop only).
  --no-virtualkeyboard        Disable deployment of the Virtual Keyboard.
  --no-compiler-runtime       Do not deploy compiler runtime (Desktop only).
  --json                      Print to stdout in JSON format.
  --no-opengl-sw              Do not deploy the software rasterizer library.
  --list <option>             Print only the names of the files copied.
                              Available options:
                               source:   absolute path of the source files
                               target:   absolute path of the target files
                               relative: paths of the target files, relative
                                         to the target directory
                               mapping:  outputs the source and the relative
                                         target, suitable for use within an
                                         Appx mapping file
  --verbose <level>           Verbose level (0-2).

Qt libraries can be added by passing their name (-xml) or removed by passing
the name prepended by --no- (--no-xml). Available libraries:
bluetooth concurrent core declarative designer designercomponents gui qthelp
multimedia multimediawidgets multimediaquick network nfc opengl openglwidgets
positioning printsupport qml qmltooling quick quickparticles quickwidgets script
scripttools sensors serialport sql svg svgwidgets test websockets widgets xml
webenginecore webengine webenginewidgets 3dcore 3drenderer 3dquick
3dquickrenderer 3dinput 3danimation 3dextras geoservices webchannel serialbus
webview

Arguments:
  [files]                     Binaries or directory containing the binary.

スタティックリンク

静的アプリケーションをビルドするには、-static で Qt を設定し、Qt を静的にビルドします：

cd C:\path\to\Qt
configure -static <any other options you need>

後で同じ場所から Qt を再設定して再構築する必要がある場合は、configure を再度実行する前に、ビルドディレクトリに入り、nmake distclean またはmingw32-make distclean を実行して、以前の設定の痕跡がすべて削除されていることを確認してください。

アプリケーションを静的バージョンの Qt にリンクする

ここでは例として、Plug & Paint のサンプルを静的にビルドします。

Qt のビルドが完了したら、Plug & Paintアプリケーションをビルドします。まず、アプリケーションを含むディレクトリに入ります：

cd examples\tools\plugandpaint

qmake を実行してアプリケーション用の新しい makefile を作成し、静的にリンクされた実行ファイルを作成するためにクリーンビルドを実行します：

nmake clean
qmake -config release
nmake

おそらくリリース・ライブラリとリンクしたいでしょうから、qmake を起動するときにこれを指定してください。これで、すべてのコンパイルとリンクがエラーなしで完了すれば、デプロイ準備が整ったplugandpaint.exe ファイルができあがります。アプリケーションに必要なライブラリがあるか確認するには、Qt や Qt アプリケーションがインストールされていないマシンに実行ファイルをコピーし、そのマシンで実行してください。

アプリケーションがコンパイラ固有のライブラリに依存している場合、これらのライブラリもアプリケーションと一緒に再配布する必要があることを覚えておいてください。アプリケーションがどのライブラリにリンクしているかは、depends ツールを使って確認することができます。詳しくは、アプリケーションの依存関係のセクションをお読みください。

静的リンクのアプローチを使ってプラグインをデプロイすることはできないので、準備したアプリケーションは不完全です。実行はできますが、プラグインが欠けているため、機能は無効になります。プラグイン・ベースのアプリケーションをデプロイするには、共有ライブラリ・アプローチを使うべきです。

共有ライブラリ

共有ライブラリアプローチを使ってplugandpaint アプリケーションをデプロイする場合、2 つの課題があります：Qtランタイムはアプリケーションの実行ファイルとともに正しく再配布されなければなりませんし、プラグインはアプリケーションが見つけられるようにターゲットシステムの正しい場所にインストールされなければなりません。

Qt を共有ライブラリとしてビルドする

この例では、Qt を共有ライブラリとして、C:Document:PathtoQt フォルダにインストールします。

共有ライブラリとして Qt にアプリケーションをリンクする。

Qt が共有ライブラリとしてビルドされていることを確認したら、plugandpaint アプリケーションをビルドします。まず、アプリケーションを含むディレクトリに移動します：

cd examples\tools\plugandpaint

次に、qmake を実行してアプリケーション用の新しい makefile を作成し、動的リンクされた実行ファイルを作成するためにクリーンビルドを行います：

nmake clean
qmake -config release
nmake

これでコア・アプリケーションがビルドされ、以下ではプラグインがビルドされる：

cd ..\plugandpaint/plugins
nmake clean
qmake -config release
nmake

すべてのコンパイルとリンクがエラーなしで完了すると、plugandpaint.exe 実行ファイルと、pnp_basictools.dll とpnp_extrafilters.dll プラグイン・ファイルが作成されます。

アプリケーション・パッケージの作成

アプリケーションをデプロイするには、関連する Qt DLL（アプリケーションで使用される Qt モジュールに対応）と Windows プラットフォーム・プラグインqwindows.dll を、実行ファイルと同様にrelease サブディレクトリの同じディレクトリツリーにコピーしておく必要があります。

ユーザープラグインとは対照的に、Qtプラグインはプラグインの種類に合ったサブディレクトリに置く必要があります。プラットフォーム・プラグインの正しい場所は、platforms というサブディレクトリです。Qt Pluginsセクションに、プラグインとQtによるプラグインの検索方法に関する追加情報があります。

ダイナミックOpenGLを使用する場合、アプリケーションがソフトウェアベースOpenGLと互換性があれば、ライブラリも必要です。

Qt が ICU や OpenSSL とリンクするように設定されている場合は、それぞれの DLL もrelease フォルダに追加する必要があります。しかし、Windows の Qt のバイナリパッケージはこれを必要とします。詳細については、サードパーティライブラリも参照してください。

アプリケーションがコンパイラ固有のライブラリに依存している場合、それらはアプリケーションと一緒に再配布されなければならないことを覚えておいてください。アプリケーションがどのライブラリにリンクしているかは、depends ツールを使って確認できます。詳細については、アプリケーションの依存関係のセクションを参照してください。

プラグインについては後ほど説明しますが、まずはアプリケーションがデプロイされた環境で動作するかどうかを確認します：実行ファイルと Qt DLL を、Qt や Qt アプリケーションがインストールされていないマシンにコピーするか、ビルドマシン上でテストしたい場合は、そのマシンの環境に Qt がないことを確認してください。

アプリケーションが問題なく起動すれば、plugandpaint アプリケーションの動的リンクバージョンの作成は成功です。しかし、関連するプラグインをまだデプロイしていないので、アプリケーションの機能はまだありません。

プラグインは通常のDLLとは動作が異なるため、Qt DLLと同じようにアプリケーションの実行ファイルと同じディレクトリにコピーすることはできません。プラグインを探すときは、アプリケーションの実行ファイルのディレクトリ内のplugins サブディレクトリを検索します。

そのため、プラグインをアプリケーションで利用できるようにするには、plugins サブディレクトリを作成し、関連する DLL をコピーする必要があります：

plugins\pnp_basictools.dll
plugins\pnp_extrafilters.dll

Plug & Paintアプリケーションの実行に必要なすべての Qt DLL とアプリケーション固有のプラグインを配布するアーカイブには、以下のファイルを含める必要があります：

アプリケーションが使用する機能によっては、他のプラグインが必要になるかもしれません (iconengines,imageformats)。

さらに、アーカイブには以下のコンパイラ固有のライブラリが含まれている必要があります（Visual Studio 16（2019）を想定）：

ダイナミックOpenGLが使われた場合、アーカイブにはさらに以下が含まれる：

最後に、QtがICUを使用するように設定されている場合、アーカイブには以下が含まれていなければなりません：

アプリケーションが正常にデプロイできることを確認するには、Qt もコンパイラもインストールされていないマシンでこのアーカイブを解凍し、実行してみてください。

プラグインを plugins サブディレクトリに置く代わりに、QCoreApplication::addLibraryPath() またはQCoreApplication::setLibraryPaths() を使用してアプリケーションを起動するときに、カスタム検索パスを追加することもできます。

QCoreApplication::addLibraryPath("C:/some/other/path");

プラグインを使用する利点の1つは、アプリケーション・ファミリー全体で簡単に利用できることです。

多くの場合、QApplication オブジェクトが作成された直後に、アプリケーションのmain() 関数でパスを追加するのが最も便利です。パスが追加されると、アプリケーションは、アプリケーション自身のディレクトリのplugins サブディレクトリを探すのに加えて、プラグインを検索します。パスはいくつでも追加できます。

マニフェスト・ファイル

Visual Studioでコンパイルされたアプリケーションをデプロイする際には、いくつかの追加ステップが必要です。

まず、アプリケーションのリンク時に作成されたマニフェストファイルをコピーする必要があります。このマニフェストファイルには、ランタイムライブラリなどのサイドバイサイドのアセンブリに対するアプリケーションの依存関係に関する情報が含まれています。

マニフェストファイルは、アプリケーションの実行ファイルと同じフォルダにコピーする必要があります。共有ライブラリ (DLL) のマニフェスト ファイルは使用されないため、コピーする必要はありません。

共有ライブラリが、それを使用するアプリケーションとは異なる依存関係を持つ場合は、マニフェストファイルを DLL バイナリに埋め込む必要があります。マニフェストの埋め込みには、次のCONFIG オプションを使用できます：

embed_manifest_dll
embed_manifest_exe

どちらのオプションもデフォルトで有効になっています。embed_manifest_exe を削除するには

CONFIG -= embed_manifest_exe

を追加してください。

マニフェスト ファイルとサイドバイサイド アセンブリの詳細については、サイドバイサイド アセンブリのドキュメント ページを参照してください。

ランタイムライブラリをアプリケーションにインクルードする正しい方法は、それらがエンドユーザーのシステムにインストールされていることを確認することです。

エンドユーザーのシステムにランタイム ライブラリをインストールするには、適切な Visual C++ 再頒布可能パッケージ (VCRedist) 実行ファイルをアプリケーションに含め、ユーザーがアプリケーションをインストールするときに実行されるようにする必要があります。

再配布可能ファイルはvc_redist.x64.exe (64-bit) という名前で、<Visual Studio install path>/VC/redist/<language-code> というフォルダーにあります。

または、https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads のように、ウェブからダウンロードすることもできます。

アプリケーションの依存関係

追加ライブラリ

設定によっては、コンパイラ固有のライブラリをアプリケーションと一緒に再配布する必要があります。

Dependency Walkerツールを使えば、アプリケーションがリンクしているライブラリを確認できます。以下のように実行するだけです：

depends <application executable>

アプリケーションが依存しているライブラリのリストとその他の情報が表示されます。

Plug & Paint 実行ファイル (plugandpaint.exe) のリリースビルドをdepends ツールで見ると、システム以外のライブラリへの即時依存性が以下のように表示されます：

プラグインDLLを見ると、まったく同じ依存関係がリストされている。

Qtプラグイン

すべての Qt GUI アプリケーションには、Qt のQPA（Qt Platform Abstraction）レイヤーを実装するプラグインが必要です。Windows の場合、プラットフォーム・プラグインの名前はqwindows.dll です。このファイルは、配布ディレクトリの特定のサブディレクトリ（デフォルトではplatforms ）に配置する必要があります。また、以下に説明するように、Qt がプラグインを見つけるために使用する検索パスを調整することもできます。

アプリケーションは、印刷サポートプラグイン、JPEG 画像フォーマットプラグイン、SQL ドライバプラグインなど、1 つ以上の Qt プラグインに依存している場合があります。必要な Qt プラグインは、必ずアプリケーションと一緒に配布してください。プラットフォーム・プラグインと同様に、各プラグインは配布ディレクトリ内の特定のサブディレクトリ（printsupport 、imageformats 、sqldrivers など）に配置する必要があります。

Qt が configure スイッチ-relocatable をオフにしてビルドされていない限り、ライブラリは再配置可能です。Qt プラグインの検索パスは、QtCore ライブラリの場所からの相対パスであり、ターゲットマシンにアプリケーションをインストールした後に、プラグインが見つかるようにするための追加の手順は必要ありません。

リロケータブルでないビルドを使用する場合にプラグインが見つかるようにする

非リロケータブル・ビルドの場合、アプリケーションがターゲット・マシンにインストールされた後にプラグインが検出されるように、追加の手順を実行する必要があります。

この場合、Qt プラグインの検索パスはQtCore ライブラリにハードコードされます。デフォルトでは、Qt インストールの plugins サブディレクトリが最初のプラグイン検索パスになります。しかし、デフォルトのようなあらかじめ決められたパスには、ある欠点があります。例えば、ターゲットマシンに存在しない可能性があります。そのため、Qt プラグインが見つかるかどうかを確認するために、様々な選択肢を調べる必要があります：

• qt.conf を使う。この方法は、同じプラグインを共有する実行ファイルが異なる場所にある場合に推奨されます。
• QApplication::addLibraryPath() またはQApplication::setLibraryPaths() を使う。プラグインを使用する実行ファイルが1つしかない場合は、この方法をお勧めします。
• サードパーティのインストール・ユーティリティを使用して、QtCore ライブラリのハードコードされたパスを変更する。

QApplication::addLibraryPathを使用してカスタムパスを追加すると、次のようになります：

QCoreApplication::addLibraryPath("C:/customPath/plugins");

そうすると、QCoreApplication::libraryPaths() は次のようなものを返します：

• C:/customPath/plugins
• C:/Qt/%VERSION%/plugins
• E:/myApplication/directory

実行ファイルは、これらのディレクトリで、QCoreApplication::libraryPaths() が返すQStringList と同じ順序でプラグインを探します。新しく追加されたパスは、QCoreApplication::libraryPaths() の前に付加され、それが最初に検索されることを意味します。ただし、QCoreApplication::setLibraryPaths() を使用する場合は、どのパスをどの順番で検索するかを指定できます。

Qt プラグインの作成方法』では、Qt アプリケーション用のプラグインをビルドおよびデプロイする際に注意する必要のある事項について概説しています。