qt_deploy_runtime_dependencies

実行ファイルに必要なQtプラグイン、Qtおよび非Qtライブラリをデプロイします。

このコマンドは、Qt6 パッケージのCore コンポーネントで定義されており、次のように読み込むことができます:

find_package(Qt6 REQUIRED COMPONENTS Core)

Qt が提供する他のほとんどの CMake コマンドとは異なり、qt_deploy_runtime_dependencies() はデプロイスクリプトからのみ呼び出すことができます。configure 段階でプロジェクトから直接呼び出すことはできません。

このコマンドは Qt 6.3 で導入されました。

概要

qt_deploy_runtime_dependencies(
    EXECUTABLE executable
    [ADDITIONAL_EXECUTABLES files...]
    [ADDITIONAL_LIBRARIES files...]
    [ADDITIONAL_MODULES files...]
    [GENERATE_QT_CONF]
    [BIN_DIR bin_dir]
    [LIBEXEC_DIR libexec_dir]
    [LIB_DIR lib_dir]
    [PLUGINS_DIR plugins_dir]
    [QML_DIR qml_dir]
    [VERBOSE]
    [NO_OVERWRITE]
    [NO_APP_STORE_COMPLIANCE]
    [NO_PLUGINS]                                  # since Qt 6.10
    [EXCLUDE_PLUGIN_TYPES type...]                # since Qt 6.10
    [INCLUDE_PLUGIN_TYPES type...]                # since Qt 6.10
    [EXCLUDE_PLUGINS name...]                     # since Qt 6.10
    [INCLUDE_PLUGINS name...]                     # since Qt 6.10
    [NO_TRANSLATIONS]
    [NO_COMPILER_RUNTIME]
    [DEPLOY_TOOL_OPTIONS]
    [PRE_INCLUDE_REGEXES regexes...]
    [PRE_EXCLUDE_REGEXES regexes...]
    [POST_INCLUDE_REGEXES regexes...]
    [POST_EXCLUDE_REGEXES regexes...]
    [POST_INCLUDE_FILES files...]
    [POST_EXCLUDE_FILES files...]
)

説明

アプリケーションをインストールする際、そのアプリケーションが依存するライブラリやプラグインも併せてインストールしたい場合があります。アプリケーションが macOS アプリバンドルまたは Windows 実行ファイルである場合、インストール時のスクリプトから `qt_deploy_runtime_dependencies() ` を呼び出すことで、それらの依存関係をデプロイできます。これにより、システム以外の Qt ライブラリと、適切な Qt プラグインのセットがインストールされます。

Linux では、このコマンドは Qt に関連するものだけでなく、プロジェクトに含まれている追加のライブラリもデプロイします。ただし、macOS または Windows で実行された場合、このコマンドは `macdeployqt ` または `windeployqt` のいずれかを使用し、Qt に固有のライブラリのみをデプロイします。

このコマンドは、基盤となるバイナリ内にリンク関係が存在するランタイム依存関係のみを考慮します。QMLモジュールの展開は行いません。QMLモジュールの展開については、qt_deploy_qml_imports()を参照してください。

引数

EXECUTABLE オプションを指定する必要があります。

executable 引数には、ビルドディレクトリ内の実行ファイルへのパスを指定する必要があります。例えば、${CMAKE_CURRENT_BINARY_DIR}/MyApp.exe 、あるいはより動的な形式として$<TARGET_FILE:MyApp> などです。$<TARGET_FILE:> のようにジェネレータ式で囲まれていない生のターゲット名を指定することはサポートされていません。

macOS アプリバンドルの場合、executable 引数には、ベースのインストール場所を基準としたバンドルディレクトリへのパスを指定する必要があります。例えば、MyApp.app や、より動的な方法として$<TARGET_FILE_NAME:MyApp>.app などです。$<TARGET_FILE_NAME:> のようにジェネレーター式で囲まれていない生のターゲット名を指定することはサポートされていません。

また、executable に関連する他のバイナリの依存関係をインストールしたい場合もあるでしょう。例えば、プロジェクトが提供するプラグインにはさらなる依存関係があるかもしれませんが、それらのプラグインは実行ファイルに直接リンクされないため、qt_deploy_runtime_dependencies() では自動的に検出されません。ADDITIONAL_EXECUTABLES 、ADDITIONAL_LIBRARIES 、およびADDITIONAL_MODULES オプションを使用すると、依存関係としてデプロイすべき追加のバイナリを指定できます（指定されたバイナリ自体のインストールは、依然としてプロジェクト側の責任となります）。 これらのキーワードの命名規則は CMake の規約に従うため、Qt プラグインはADDITIONAL_MODULES のように指定します。各値は、ベースのインストール場所を基準とした相対パスである必要があります。値には、EXECUTABLE オプションと同様に、ジェネレータ式を使用できます。$<TARGET_FILE_NAME:> のように、ジェネレータ式で囲まれていない生のターゲット名を指定することはサポートされていません。

Windows アプリケーションをインストールする場合、CMake のデフォルトのインストールディレクトリ構造に従う際には、qt.confファイルが必要になることがよくあります。GENERATE_QT_CONF オプションが指定された場合、適切なqt.conf ファイルがexecutable と同じディレクトリに書き込まれます。そのqt.conf ファイル内のパスは、CMAKE_INSTALL_xxxDIR 変数に基づいており、そのデフォルト値は CMake のGNUInstallDirsモジュールによって提供されます。

以下の表に示すパラメータを使用して、これらのデフォルト値の一部を上書きすることができます。これらのパラメータはすべて、ベースのインストール場所を基準とする相対パスであることが想定されています。

executable がmacOSアプリバンドルである場合、qt.conf ファイルは書き込まれず、その場合はGENERATE_QT_CONF および..._DIR オプションの両方が無視されます。アプリバンドルのディレクトリ構成はAppleの要件によって規定されており、Qtはqt.conf を使用せずに、それらの標準的な場所からライブラリ、プラグイン、リソースを検出します。

VERBOSE オプションを指定することで、デプロイ手順に関するより詳細な出力を有効にできます。あるいは、最初のfind_package(Qt6) 呼び出しの前にプロジェクト内でQT_ENABLE_VERBOSE_DEPLOYMENT変数を設定することで、デプロイ出力をデフォルトで詳細表示にすることも可能です。

qt_deploy_runtime_dependencies() コマンドは、デフォルトで既存のファイルを上書きします（警告が表示される場合があります）。既存のファイルの上書きを防ぐには、NO_OVERWRITE オプションを使用してください。なお、このオプションは現在、macOS および Windows へのデプロイにのみ影響します。

デフォルトでは、executable がmacOSアプリバンドルの場合、AppleのApp Store要件に準拠したQtプラグインおよびQtライブラリのみがデプロイされます。この制約を無効にするには、NO_APP_STORE_COMPLIANCE オプションを指定します。

macOS 以外のプラットフォームでは、Qt の翻訳ファイルが自動的にデプロイされます。この動作を無効にするには、NO_TRANSLATIONS を指定してください。翻訳ファイルをカスタマイズしてデプロイするには、qt_deploy_translations()を使用してください。

Windows デスクトップアプリケーションの場合、コンパイラに必要なランタイムファイルもデフォルトでインストールされます。これを防ぐには、NO_COMPILER_RUNTIME を指定してください。

Qt 6.7 以降では、DEPLOY_TOOL_OPTIONS を使用して、基盤となるデプロイツールに追加のオプションを渡すことができます。これは、基盤となるデプロイツールが macdeployqt または windeployqt である場合にのみ有効です。

Linux では、ランタイム依存関係のデプロイは CMake のfile(GET_RUNTIME_DEPENDENCIES) コマンドに基づいて行われます。PRE_INCLUDE_REGEXES 、PRE_EXCLUDE_REGEXES 、POST_INCLUDE_REGEXES 、POST_EXCLUDE_REGEXES 、POST_INCLUDE_FILES 、およびPOST_EXCLUDE_FILES の各オプションは、このコンテキストでのみ意味を持ち、変更されずにfile(GET_RUNTIME_DEPENDENCIES) に渡されます。詳細については、そのコマンドのドキュメントを参照してください。

Linux では、システムライブラリディレクトリにあるランタイム依存関係は、デフォルトではデプロイされません。POST_EXCLUDE_REGEXES が指定されている場合、この自動的な除外は行われません。

POST_EXCLUDE_REGEXES のデフォルト値は、QT_DEPLOY_IGNORED_LIB_DIRS の値に基づいて決定されます。

Qt プラグインのデプロイの制御

Qt プラグインは、QT_DEPLOY_PLUGINS_DIR に自動的にデプロイされます。

NO_PLUGINS 引数を使用すると、プラグインのデプロイを無効にすることができます。

INCLUDE_PLUGIN_TYPES 引数を使用すると、特定のタイプのプラグインをすべて含めることができます。EXCLUDE_PLUGIN_TYPES 引数を使用すると、特定のタイプのプラグインをすべて除外することができます。どちらの引数も、プラグインのタイプ（例：imageformats ）を指定します。

引数 `INCLUDE_PLUGINS ` および `EXCLUDE_PLUGINS` を使用すると、特定のプラグインを含めたり除外したりできます。どちらの引数もプラグイン名を受け取ります。例：qjpeg 。

例

次の例は、MyApp を使用してアプリケーションをデプロイする方法を示しています。

cmake_minimum_required(VERSION 3.16...3.22)
project(MyThings)

find_package(Qt6 REQUIRED COMPONENTS Core)
qt_standard_project_setup()

# Keep the QT_DEPLOY_* references below for the generated script to expand,
# see \l {QTP0008}.
qt_policy(SET QTP0008 NEW)

qt_add_executable(MyApp main.cpp)

set_target_properties(MyApp PROPERTIES
    WIN32_EXECUTABLE TRUE
    MACOSX_BUNDLE TRUE
)

# App bundles on macOS have an .app suffix
if(APPLE)
    set(executable_path "$<TARGET_FILE_NAME:MyApp>.app")
else()
    set(executable_path "\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:MyApp>")
endif()

# Helper app, not necessarily built as part of this project.
qt_add_executable(HelperApp helper.cpp)
set(helper_app_path "\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:HelperApp>")

# Generate a deployment script to be executed at install time
qt_generate_deploy_script(
    TARGET MyApp
    OUTPUT_SCRIPT deploy_script
    CONTENT "
qt_deploy_runtime_dependencies(
    EXECUTABLE \"${executable_path}\"
    ADDITIONAL_EXECUTABLES \"${helper_app_path}\"
    GENERATE_QT_CONF
    VERBOSE
)")

# Omitting RUNTIME DESTINATION will install a non-bundle target to CMAKE_INSTALL_BINDIR,
# which coincides with the default value of QT_DEPLOY_BIN_DIR used above, './bin'.
# Installing macOS bundles always requires an explicit BUNDLE DESTINATION option.
install(TARGETS MyApp HelperApp    # Install to CMAKE_INSTALL_PREFIX/bin/MyApp.exe
                                   #                           and ./binHelperApp.exe
        BUNDLE  DESTINATION .      # Install to CMAKE_INSTALL_PREFIX/MyApp.app/Contents/MacOS/MyApp
)
install(SCRIPT ${deploy_script})    # Add its runtime dependencies

以下の例は、DEPLOY_TOOL_OPTIONS パラメータを使用して、macdeployqt および windeployqt にさまざまなオプションを渡す方法を示しています。

set(deploy_tool_options_arg "")
if(APPLE)
    # The CONTENT below is parsed when the generated script runs.
    # To preserve the code signing identity, it needs to be wrapped in escaped quotes.
    # In addition, all the options need to be wrapped into a single quoted string,
    # so that CMake doesn't replace each space with a semicolon in the generated text.
    set(deploy_tool_options_arg
        "-hardened-runtime \"-codesign=Developer ID Application: Joe Developer (1234567890)\""
    )
elseif(WIN32)
    set(deploy_tool_options_arg --no-compiler-runtime)
endif()

# Generate a deployment script to be executed at install time
qt_generate_deploy_script(
    TARGET MyApp
    OUTPUT_SCRIPT deploy_script
    CONTENT "
qt_deploy_runtime_dependencies(
    EXECUTABLE \"${executable_path}\"
    DEPLOY_TOOL_OPTIONS ${deploy_tool_options_arg}
    GENERATE_QT_CONF
    VERBOSE
)")