qt_generate_deploy_app_script

Generate a deployment script for an application.

The command is defined in the Core component of the Qt6 package, which can be loaded like so:

 find_package(Qt6 REQUIRED COMPONENTS Core)

This command was introduced in Qt 6.3.

Synopsis

 qt_generate_deploy_app_script(
     TARGET target
     OUTPUT_SCRIPT <var>
     [NO_TRANSLATIONS]
     [NO_COMPILER_RUNTIME]
     [NO_UNSUPPORTED_PLATFORM_ERROR]
     [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...]
 )

If versionless commands are disabled, use qt6_generate_deploy_app_script() instead. It supports the same set of arguments as this command.

Description

Installing an executable target with install(TARGETS) only installs the target's executable (except for macOS app bundles, which will copy the whole bundle). You need to explicitly install any other libraries or plugins the executable depends on yourself. qt_generate_deploy_app_script() is a convenience command intended to simplify that process. It expects the application to follow Qt's recommended install directory structure fairly closely. That structure is based on CMake's default install layout, as determined by GNUInstallDirs (except for macOS app bundles, which follow Apple's requirements instead).

The command generates a script whose name will be stored in the variable named by the OUTPUT_SCRIPT option. That script is only written at CMake generation time. It is intended to be used with the install(SCRIPT) command, which should come after the application's target has been installed using install(TARGETS).

The deployment script will call qt_deploy_runtime_dependencies() with a suitable set of options for the standard install layout. Currently, this is only implemented for

• macOS app bundles built on a macOS host,
• Linux executables built on a Linux host,
• and Windows executables built on a Windows host.

Cross-building a Windows executable on a Linux host, as well as similar scenarios, are not currently supported. Calling qt_generate_deploy_app_script() in such a case will result in a fatal error, unless the NO_UNSUPPORTED_PLATFORM_ERROR option is given.

On platforms other than macOS, Qt translations are automatically deployed. To inhibit this behavior, specify NO_TRANSLATIONS. Use qt_deploy_translations() to deploy translations in a customized way.

For Windows desktop applications, the required runtime files for the compiler are also installed by default. To prevent this, specify NO_COMPILER_RUNTIME.

Since Qt 6.7, you can use DEPLOY_TOOL_OPTIONS to pass additional options to the underlying deployment tool. This only has an effect if the underlying deployment tool is either macdeployqt or windeployqt.

For deploying a QML application, use qt_generate_deploy_qml_app_script() instead.

For generating a custom deployment script, use qt_generate_deploy_script.

The options PRE_INCLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, POST_EXCLUDE_REGEXES, POST_INCLUDE_FILES, and POST_EXCLUDE_FILES can be specified to control the deployment of runtime dependencies. These options do not apply to all platforms and are forwarded unmodified to qt_deploy_runtime_dependencies().

Example

The following example shows how to deploy an application MyApp.

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

 find_package(Qt6 REQUIRED COMPONENTS Core)
 qt_standard_project_setup()

 qt_add_executable(MyApp main.cpp)

 install(TARGETS MyApp
     BUNDLE  DESTINATION .
     RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
 )

 qt_generate_deploy_app_script(
     TARGET MyApp
     OUTPUT_SCRIPT deploy_script
     NO_UNSUPPORTED_PLATFORM_ERROR
 )
 install(SCRIPT ${deploy_script})

The following example shows how to use the DEPLOY_TOOL_OPTIONS parameter to pass different options to macdeployqt and windeployqt.

 set(deploy_tool_options_arg "")
 if(APPLE)
     set(deploy_tool_options_arg --hardened-runtime)
 elseif(WIN32)
     set(deploy_tool_options_arg --no-compiler-runtime)
 endif()

 qt_generate_deploy_app_script(
     TARGET MyApp
     OUTPUT_SCRIPT deploy_script
     NO_UNSUPPORTED_PLATFORM_ERROR
     DEPLOY_TOOL_OPTIONS ${deploy_tool_options_arg}
 )
 install(SCRIPT ${deploy_script})