Windows 向け Qt - 展開

このドキュメントでは、Windows 向けのデプロイ手順について説明します。デプロイ手順を説明するために、本文書全体を通じて「Plug & Paint」サンプルアプリケーションを例に挙げています。

Windows デプロイメント ツール

Windows Deploy Qt 上で Qt アプリケーションを展開する推奨される最も簡単な方法は、windeployqt ツールを使用することです。このツールは、必要なすべての Qt ライブラリ、プラグイン、QML モジュール、およびランタイム依存関係を自動的に収集し、すぐに実行可能な展開用フォルダにまとめます。

このツールは、Windows デスクトップアプリケーション用のインストールツリーを作成し、それをインストールパッケージに簡単にバンドルすることができます。

ビルド環境のセットアップ

Qt Online Installer を通じて Qt をインストールした場合は、windeployqt を実行する前にビルド環境を設定する必要があります。これを行うには、次のコマンドを実行してください：

<qt-installation-folder>/bin/qtenv2.bat

使用方法

windeployqt は<qt-installation-folder>/bin/ にあります。引数として、.exe ファイル、または.exe ファイルを含むディレクトリを受け取り、実行ファイルの依存関係をスキャンします。

以下の点に注意してください：

• --qmldir 引数としてディレクトリが指定された場合、windeployqtはqmlimportscannerツールを使用して、そのディレクトリ内のQMLファイルをスキャンし、QMLのインポート依存関係を検出します。検出された依存関係は、その後、実行ファイルのディレクトリにコピーされます。
• Qtのビルド時にconfigureスイッチの-relocatable が無効に設定されていた場合、windeployqtはQt6Core.dll 内のハードコードされたローカルパスを相対パスに置き換えます。
• Windows デスクトップアプリケーションの場合、--no-compiler-runtime が指定されていない限り、windeployqt はデフォルトで必要なコンパイラランタイムファイルをコピーします。Microsoft Visual C++ を使用したリリースビルドの場合、これは、ツールがアプリケーションインストーラに公式の Visual C++ 再配布可能パッケージが含まれていることを前提としていることを意味します。

  再配布可能パッケージが利用できない場合、windeployqtは開発者のマシン上にあるコンパイラの共有ランタイムDLLを使用することに切り替える可能性があります。これらの個々のDLLは再配布を意図したものではなく、再配布が許可されていません。したがって、直接同梱してはなりません。 エンドユーザーシステムへの展開には、Microsoftの公式再配布可能パッケージインストーラーのみを使用してください。

一般的な使用例

標準的なQt Widgets アプリケーションの展開

windeployqt.exe .\build\MyApp.exe

QMLソースを含むQt Quick アプリケーションのデプロイ

windeployqt.exe --qmldir .\qml .\build\MyApp.exe

パッケージング用の appx マニフェストの生成

アプリケーションを Windows appx パッケージとしてパッケージ化するための準備を行う際に、これを使用してください。

--appx オプションはAppxManifest.xml を作成し、--appx-certificate はマニフェストに埋め込む証明書を指定します。

windeployqt.exe --appx --appx-certificate MyCompany.cer .\build\MyApp.exe

ドライランの実行

ドライランでは、何もコピーしたり更新したりすることなく、デプロイをシミュレートします。

windeployqt.exe --dry-run MyApp.exe

オプション

一般

入出力制御

Qtのパス解決

ビルド設定

デプロイ時の動作

プラグイン

QML

翻訳

システムおよびランタイムコンポーネント

ファイル一覧の出力

静的リンク

静的アプリケーションをビルドするには、-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つの課題があります。1つは、アプリケーションの実行ファイルとともにQtランタイムを正しく再配布する必要があること、もう1つは、アプリケーションがプラグインを検出できるように、ターゲットシステム上の適切な場所にプラグインをインストールする必要があることです。

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プラグインのセクションには、プラグインに関する詳細情報や、Qtがプラグインを検索する方法についての情報が記載されています。

動的 OpenGL を使用する場合、アプリケーションが対応していれば、ソフトウェアベースの OpenGL に必要なライブラリを追加で含めることも検討してください。

Qt が ICU または OpenSSL に対してリンクするように構成されている場合、それぞれの DLL もrelease フォルダに追加する必要があるかもしれません。ただし、Windows 用の Qt バイナリパッケージでは、これは必要ありません。 特定のバージョンのICUまたはOpenSSLを使用してQtを構成した場合、windeployqtは、Qtの[bin] ディレクトリ内に該当するライブラリのDLLが見つかる限り、それらを自動的に検出します。詳細については、「サードパーティ製ライブラリ」も参照してください。

アプリケーションがコンパイラ固有のライブラリに依存している場合は、それらをアプリケーションと一緒に再配布する必要があることに注意してください。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つは、アプリケーションのファミリー全体でプラグインを簡単に利用できるようにできることです。

多くの場合、アプリケーションのmain() 関数内で、QApplication オブジェクトが作成された直後にパスを追加するのが最も便利です。パスが追加されると、アプリケーションは、アプリケーション自身のディレクトリにある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に対応しています。

詳細については、「Microsoft アプリケーションマニフェスト」をご覧ください。

ロングパス対応

<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 が使用されます。

カスタムマニフェストの指定

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

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

を.proファイルに追加してください。

マニフェスト ファイルおよびサイド・バイ・サイド アセンブリに関する詳細については、「サイド・バイ・サイド アセンブリ」のドキュメント ページをご覧ください。

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

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

この再配布可能パッケージは「vc_redist.x64.exe （64 ビット）」という名前で、<Visual Studio install path>/VC/redist/<language-code> フォルダ内にあります。

あるいは、Web からダウンロードすることも可能です。例:https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads。

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

追加のライブラリ

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

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

depends <application executable>

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

depends ツールを使用して、Plug & Paint実行ファイル（plugandpaint.exe ）のリリースビルドを確認すると、非システムライブラリに対する以下の直接的な依存関係が一覧表示されます：

プラグイン DLL を確認すると、まったく同じ依存関係が記載されています。

Qt プラグイン

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

printsupport imageformats また、アプリケーションは、Qt Print Support プラグイン、JPEG 画像フォーマットプラグイン、SQL ドライバプラグインなど、1 つ以上の Qt プラグインに依存している場合もあります。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アプリケーション用のプラグインをビルドおよびデプロイする際に注意すべき事項について概説しています。