Deploy

Gathering what a built or an installed binary needs to run, and putting it beside the binary. Windows is done after a build and every platform can be done during an install.

Warning

This module depends on qmcorecmd after installation.

QMSETUP_APPLOCAL_DEPS_PATHS

Library search paths that qm_win_applocal_deps() and qm_deploy_directory() add to their own. A relative path is resolved against CMAKE_SOURCE_DIR. Empty by default.

QMSETUP_APPLOCAL_DEPS_PATHS_<CONFIG>

Replaces QMSETUP_APPLOCAL_DEPS_PATHS if CMAKE_BUILD_TYPE is <CONFIG> and the list is not empty. _DEBUG and _RELEASE default to QMSETUP_APPLOCAL_DEPS_PATHS, and _RELWITHDEBINFO and _MINSIZEREL default to _RELEASE.

qm_win_applocal_deps

Automatically copy dependencies for Windows Executables after build.

qm_win_applocal_deps(<target>
    [CUSTOM_TARGET <target>]
    [FORCE] [VERBOSE]
    [EXTRA_SEARCHING_PATHS <path...>]
    [OUTPUT_DIR <dir>]
    [EXCLUDE <pattern...>]
)

Does nothing where the platform is not Windows, so a call needs no guard around it.

See also

qm_deploy_directory(), for the same thing done while installing rather than after building.

qm_deploy_directory

Add a deploy command when installing the project. Not for a debug build.

qm_deploy_directory(<install_dir>
    [FORCE] [STANDARD] [VERBOSE]
    [LIBRARY_DIR <dir>]
    [EXTRA_LIBRARIES <path>...]
    [EXTRA_PLUGIN_PATHS <path>...]
    [EXTRA_SEARCHING_PATHS <path>...]
    [EXCLUDE <regex>...]

    [PLUGINS <plugin>...]
    [QT_PLUGINS] [QT_PLUGINS_EXCLUDE <plugin>...] [QT_PLUGINS_EXCLUDE_MODULES <module>...]
    [QT_PLUGINS_PLATFORMS <platform>...]
    [PLUGIN_DIR <dir>]

    [QML <qml>...]
    [QML_DIR <dir>]

    [COMMENT <comment>]
)

A relative <install_dir> is relative to the install prefix, and a relative LIBRARY_DIR, PLUGIN_DIR or QML_DIR is relative to <install_dir>. Both are resolved while installing, so that cmake --install --prefix moves the deployment with the other install rules. "${CMAKE_INSTALL_PREFIX}" is the prefix of the configuration and does not follow --prefix. . is the install prefix itself.

PLUGINS

Plugins, in format of <category>/<name>, looked for in the plugin directory of Qt and in EXTRA_PLUGIN_PATHS. A plugin is not required to be one of Qt.

QT_PLUGINS

Also deploys the Qt plugins of every Qt module that the deployment requires, as qm_get_qt_plugins lists them. The modules are worked out while installing, from the binaries under <install_dir> and what they require. Each plugin is then resolved by itself, as windeployqt does, and a plugin that requires a further module brings that module and its plugins.

QT_PLUGINS_EXCLUDE

Plugins, as <category>/<name>, that QT_PLUGINS leaves out. PLUGINS is not affected.

QT_PLUGINS_EXCLUDE_MODULES

Qt modules without the prefix, such as Qml and Quick. QT_PLUGINS leaves out a plugin that requires one of them, and therefore the modules that only that plugin requires.

QT_PLUGINS_PLATFORMS

The platforms, such as windows, cocoa and xcb, whose platform plugins QT_PLUGINS deploys, in place of those that Qt names. Required with a Qt older than 6.9.

PLUGIN_DIR

Qt plugins destination, plugins by default

EXTRA_PLUGIN_PATHS

Extra Qt plugins searching paths

QML

Qt qml directories

QML_DIR

Qt qml destination, qml by default

LIBRARY_DIR

Library destination, bin on Windows and lib on other systems by default

EXTRA_LIBRARIES

Extra library names list to deploy

EXTRA_SEARCHING_PATHS

Extra library searching paths

EXCLUDE

Regular expressions for dependencies to skip. A dependency is skipped if its path, written with forward slashes, contains a match, and the libraries that only that dependency requires are skipped with it. Leading and trailing blanks of an expression are not preserved.

QT_PLUGINS supports Qt 6.9 or later, which describes the plugin types of each module and the platform plugins of the platform in the module descriptions that it installs. With an older Qt 6, the caller confirms that its module descriptions list plugin_types, sets QT6_INSTALL_DESCRIPTIONSDIR to their directory, usually modules, and names the platforms with QT_PLUGINS_PLATFORMS. Nothing is left out by default. windeployqt leaves out more by default, and the same choice is QT_PLUGINS_EXCLUDE_MODULES Qml Quick for a program without QML, so that the input context of the virtual keyboard does not bring Qt Quick along, and QT_PLUGINS_EXCLUDE tls/qopensslbackend generic/qinsighttracker. The first of these two plugins loads OpenSSL at run time, which the deployment does not bring along.

What it gathers is the release flavour of everything, and that is decided in the scripts underneath rather than here. A plugin is looked for by the name it was given, so iconengines/qsvgicon finds qsvgicon.dll and never qsvgicond.dll, and a debug build beside a release one is turned down on sight. Unix leaves out anything whose name carries debug, which is how a macOS framework spells its debug library.

So nothing stops this being called in a debug build, and what it leaves is a release deployment. Nothing here reads the configuration, and the note above is the whole of the enforcement.

QML is the one thing here that cannot be asked for without a Qt, the modules being named relative to a directory only qmake can say where is. PLUGINS given EXTRA_PLUGIN_PATHS never reaches qmake.

Note

Where qmake is wanted it has to be found first, which qm_find_qt() with any component is the short way to. A call that needs it and does not have it stops with an error saying so.

EXTRA_LIBRARIES is matched against what is on disk while the project is being read, so it names neither a target of this build nor a generator expression.

On Linux and macOS, a file under <install_dir> is processed if it is an executable, a shared library, or a loadable bundle, regardless of its permissions. Relocatable objects, static archives, and separate debug files are skipped. The deployed binaries receive execute permission if QMSETUP_FORCE_EXECUTABLE_PERMISSIONS is on.

Where this page comes from

The comments in cmake/modules/Deploy.cmake, which is what to change.