Qt for Windows - デプロイメント

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

Windows デプロイツール

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

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

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

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

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

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

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

Usage: windeployqt.exe [options] [files]
Qt Deploy Tool 6.11.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 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 generic Qt
                                           options.
 -v, --version                             Displays version information.
 --dir <directory>                         Use directory instead of binary
                                           directory.
 --qmake <path>                            Use specified qmake instead of
                                           qmake from PATH. Deprecated, use
                                           qtpaths instead.
 --qtpaths <path>                          Use specified qtpaths.exe instead
                                           of qtpaths.exe from PATH.
 --libdir <path>                           Copy libraries to path.
 --plugindir <path>                        Copy plugins to path.
 --translationdir <path>                   Copy translations to path.
 --qml-deploy-dir <path>                   Copy qml files 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.
 --include-soft-plugins                    Include in the deployment all
                                           relevant plugins by taking into
                                           account all soft dependencies.
 --skip-plugin-types <plugin types>        A comma-separated list of plugin
                                           types that are not deployed
                                           (qmltooling,generic).
 --add-plugin-types <plugin types>         A comma-separated list of plugin
                                           types that will be added to
                                           deployment
                                           (imageformats,iconengines)
 --include-plugins <plugins>               A comma-separated list of
                                           individual plugins that will be
                                           added to deployment (scene2d,qjpeg)
 --exclude-plugins <plugins>               A comma-separated list of
                                           individual plugins that will not be
                                           deployed (qsvg,qpdf)
 --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.
 --no-system-dxc-compiler                  Skip deployment of the system DXC
                                           (dxcompiler.dll, dxil.dll).
 --compiler-runtime                        Deploy compiler runtime (Desktop
                                           only).
 --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.
 --no-ffmpeg                               Do not deploy the FFmpeg libraries.
 --force-openssl                           Deploy openssl plugin but ignore
                                           openssl library dependency
 --openssl-root <directory>                Directory containing openSSL
                                           libraries.
 --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).

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

静的リンク

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

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

同じ場所から Qt を再設定して再構築する必要がある場合は、以前の設定の痕跡がすべて削除されていることを確認してください。

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

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

Qt のビルドが完了したら、Plug & Paintアプリケーションをビルドします。このセクションでは、静的にビルドされた Qt がC:\path\to \static \Qt にインストールされていると仮定します。まず、アプリケーションのあるディレクトリに移動します：

cd examples\tools\plugandpaint

ビルドディレクトリを作成し、qt-cmake を呼び出してビルドシステムファイルを生成します。

md build_static
cd build_static
C:\path\to\static\Qt\bin\qt-cmake .. -DCMAKE_BUILD_TYPE=Release -GNinja
ninja

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

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

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

共有ライブラリ

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

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

この例では、Qt が共有ライブラリとしてC:\path\to \Qt ディレクトリにインストールされていると仮定します。

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

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

cd examples\tools\plugandpaint

専用のビルド・ディレクトリを作成し、qt-cmake を実行してビルド・システム・ファイルを作成します：

md build_shared
cd build_shared
C:\path\to\Qt\bin\qt-cmake .. -DCMAKE_BUILD_TYPE=Release -GNinja
ninja

すべてのコンパイルとリンクがエラーなしで完了すれば、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 17 (2022)を想定）：

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

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

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

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

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

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

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

Windowsアプリケーション・マニフェスト生成

Windows 上でビルドする場合、Qt は実行可能なターゲット用のアプリケーションマニフェストを自動的に生成して埋め込みます。

生成されたマニフェスト

• Windows 10 と Windows 11 の互換性を宣言します。
• 長いパスを認識するようにします。
• アプリケーションのバージョンを設定する (PROJECT_VERSION から)
• プロジェクト識別子を定義する
• 要求された実行レベルを設定する
• デフォルトのリンカー生成マニフェストを無効にする (/MANIFEST:NO)

カスタム.manifest ファイルが既にターゲットソースで提供されている場合、Qt はそれを上書きしません。

Windows 10/11 との互換性を宣言することで、以下のような最新の Windows の動作が可能になります：

• モダンウィンドウマネージャの動作へのオプトイン
• 子ウィンドウでのWS_EX_LAYERED のサポート（Windows 8 以降サポートされていますが、互換性の認識によって制限されています。）
• 長いパスのサポート（260文字以上）
• 明示的な実行レベル設定

適切な互換性宣言がない場合、Windowsはアプリケーションにレガシーな動作を適用する可能性があります。

デフォルトのマニフェスト内容

アプリケーション・アイデンティティ

マニフェストにはassemblyIdentity 要素が含まれます：

<assemblyIdentity
    type="win32"
    name="com.yourcompany.myapp"
    version="1.0.0.0"
    processorArchitecture="*" />

• name - プロジェクト識別子
• version - 正規化された 4 部構成の Windows バージョン

デフォルトでは、識別子は

com.yourcompany.<target_name>

QT_WINDOWS_APP_PROJECT_IDENTIFIER プロパティを使用して、ターゲットごとにオーバーライドできます：

set_target_properties(myapp PROPERTIES
    QT_WINDOWS_APP_PROJECT_IDENTIFIER "org.example.myapp"
)

Windows アプリケーション マニフェストでは、4 つの部分からなるバージョン番号が必要です：

Major.Minor.Build.Revision

各セグメントは 0 ～ 65535 の範囲の整数でなければなりません。

この値はPROJECT_VERSION から導き出され、次のように正規化されます：

• 不足の場合 → デフォルト1.0.0.0
• 4セグメント未満 → ゼロで埋める。
• 4セグメント以上 → 切り捨て
• 値 < 0 → 0 にクランプ。
• 値 > 65535 → 65535にクランプされる（警告が出る）

例

2.3        -> 2.3.0.0
1.2.3.4.5  -> 1.2.3.4
70000.1    -> 65535.1.0.0

Windowsとの互換性

マニフェストでは、Windows 10 および Windows 11 のサポートを宣言しています。

<supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />

{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}GUID はこれらのオペレーティング システムに対応しています：Windows 10、Windows 11、Windows Server 2016、Windows Server 2019、および Windows Server 2022。

詳細はこちら：マイクロソフト・アプリケーション・マニフェスト。

ロングパスの認識

<ws2:longPathAware>true</ws2:longPathAware>

オペレーティングシステムがサポートしている場合、260文字を超えるファイルパスを使用できるようにします。

実行レベル

<requestedExecutionLevel level="asInvoker" uiAccess="false" />

デフォルトの実行レベルはasInvoker です。

実行レベルを設定するには、QT_WINDOWS_APP_PROJECT_EXECUTION_LEVEL プロパティを使用します。

有効な値：

• asInvoker (デフォルト)
• highestAvailable
• requireAdministrator

例

set_target_properties(myapp PROPERTIES
    QT_WINDOWS_APP_PROJECT_EXECUTION_LEVEL "requireAdministrator"
)

無効な値が指定された場合、警告が発せられ、asInvoker 。

カスタム・マニフェストの提供

Qt はマニフェストファイルを検出し、実行可能ファイルがそのソースに既に.manifest ファイルを含んでいる場合、自動生成をスキップします：

add_executable(myapp
    main.cpp
    myapp.manifest
)

完全な例

以下の例では、識別子と実行レベルをカスタマイズして自動生成されたマニフェストを使用した Windows 実行ファイルを示します：

cmake_minimum_required(VERSION 3.21)
project(MyApp VERSION 2.5.1)

find_package(Qt6 REQUIRED COMPONENTS Core Widgets)

qt_add_executable(MyApp
    main.cpp
)

set_target_properties(MyApp PROPERTIES
    QT_WINDOWS_APP_PROJECT_IDENTIFIER "org.example.myapp"
    QT_WINDOWS_APP_PROJECT_EXECUTION_LEVEL "highestAvailable"
)

この例では、生成されたマニフェストのバージョンは次のようになります：

2.5.1.0

qmakeによるマニフェストファイル

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 のQt Platform Abstraction（QPA）レイヤーを実装するプラグインを必要とします。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 アプリケーション用のプラグインをビルドおよびデプロイする際に注意する必要のある問題の概要が記載されています。