Deploying applications on linux

Deploying applications on linux

linuxdeployqt

This Linux Deployment Tool, linuxdeployqt , takes an application as input and makes it self-contained by copying in the resources that the application uses (like libraries, graphics, and plugins) into a bundle. The resulting bundle can be distributed as an AppDir or as an AppImage to users, or can be put into cross-distribution packages. It can be used as part of the build process to deploy applications written in C, C++, and other compiled languages with systems like CMake , qmake , and make . When used on Qt-based applications, it can bundle a specific minimal subset of Qt required to run the application.

Differences to macdeployqt

This tool is conceptually based on the Mac Deployment Tool, macdeployqt in the tools applications of the Qt Toolkit, but has been changed to a slightly different logic and other tools needed for Linux.

• Instead of an .app bundle for macOS, this produces an AppDir for Linux
• Instead of a .dmg disk image for macOS, this produces an AppImage for Linux which is quite similar to a dmg but executes the contained application rather than just opening a window on the desktop from where the application can be launched

A note on binary compatibility

To produce binaries that are compatible with many target systems, build on the oldest still-supported build system. The oldest still-supported release of Ubuntu is currently targeted, tested and supported by the team.

We recommend to target the oldest still-supported Ubuntu LTS release and build your applications on that. If you do this, the resulting binaries should be able to run on newer (but not older) systems (Ubuntu and other distributions).

We do not support linuxdeployqt on systems newer than the oldest Ubuntu LTS release, because we want to encourage developers to build applications in a way that makes them possible to run on all still-supported distribution releases. For an overview about the support cycles of Ubuntu LTS releases, please see https://wiki.ubuntu.com/Releases.

Please download linuxdeployqt-x86_64.AppImage from the Releases page and chmod a+x it. If you would like to build linuxdeployqt from source instead, see BUILDING.md.

: Let the given executable use the deployed libraries too -extra-plugins=
: List of extra plugins which should be deployed, separated by comma. -no-copy-copyright-files : Skip deployment of copyright files. -no-plugins : Skip plugin deployment. -no-strip : Don’t run ‘strip’ on the binaries. -no-translations : Skip deployment of translations. -qmake=

: The qmake executable to use. -qmldir=

: Scan for QML imports in the given path. -qmlimport=

: Add the given path to QML module search locations. -show-exclude-libs : Print exclude libraries list. -verbose= : 0 = no output, 1 = error/warning (default), 2 = normal, 3 = debug. -updateinformation= : Embed update information STRING; if zsyncmake is installed, generate zsync file -version : Print version statement and exit. linuxdeployqt takes an application as input and makes it self-contained by copying in the Qt libraries and plugins that the application uses. By default it deploys the Qt instance that qmake on the $PATH points to. The ‘-qmake’ option can be used to point to the qmake executable to be used instead. Plugins related to a Qt library are copied in with the library. See the «Deploying Applications on Linux» topic in the documentation for more information about deployment on Linux. «>

You’ll need to provide the basic structure of an AppDir which should look something like this:

Replace and with (for example) hicolor and 256×256 respectively; see icon theme spec for more details.

Using the desktop file linuxdeployqt can determine the parameters of the build.

Where your desktop file would look something like:

• Notice that both Exec and Icon only have file names.
• Also Notice that the Icon entry does not include an extension.

Read more about desktop files in the Desktop Entry Specification 1.0.

Now you can say: linuxdeployqt-continuous-x86_64.AppImage path/to/AppDir/usr/share/applications/your_app.desktop

For a more detailed example, see «Using linuxdeployqt with Travis CI» below.

Checking library inclusion

Open in Qt Creator and build your application. Run it from the command line and inspect it with ldd to make sure the correct libraries from the correct locations are getting loaded, as linuxdeployqt will use ldd internally to determine from where to copy libraries into the bundle.

Important: By default, linuxdeployqt deploys the Qt instance that qmake on the $PATH points to, so make sure that it is the correct one. Verify that qmake finds the correct Qt instance like this before running the linuxdeployqt tool:

If this does not show the correct path to your Qt instance that you want to be bundled, then adjust your $PATH to find the correct qmake .

Alternatively, use the -qmake command line option to point the tool directly to the qmake executable to be used.

Remove unnecessary files

Before running linuxdeployqt it may be wise to delete unneeded files that you do not wish to distribute from the build directory. These may be autogenerated during the build. You can delete them like so:

Alternatively, you could use $DESTDIR .

Adding icon and icon theme support

To enable icon and icon theme support you must add iconengines as an extra Qt plugin while running linuxdeployqt . In order for your application to locate the system theme icons, the libqgtk3.so platform theme must also be added:

Adding extra Qt plugins

If you want aditional plugins which the tool doesn’t deploy, for a variety of reasons, you can use the -extra-plugins argument and include a list of plugins separated by a comma.
The plugins deployed are from the Qt installation pointed out by qmake -v .
You can deploy entire plugin directories, a specific directory or a mix of both.

1. -extra-plugins=sqldrivers/libqmsql.so,iconengines/libqsvgicon.so
2. -extra-plugins=sqldrivers,iconengines/libqsvgicon.so
3. -extra-plugins=sqldrivers,iconengines,mediaservice,gamepads

Handle Qt libraries infix

If you prepared a custom Qt distribution using the option -qtlibinfix during Qt configuration (resulting in library names such as libQt5CoreCustom.so ), you must mention this infix on linuxdeployqt call. As an example, let’s see if we configure our distribution using the infix Custom .

On Qt build chain: configure -qtlibinfix «Custom» [. ] . This will generate Qt libraries (.so) like libQt5CoreCustom.so

So, on linuxdeployqt call: linuxdeployqt [. ] -qtlibinfix «Custom» [. ] .

If you don’t mention this infix, linuxdeployqt won’t be able to detect Qt Core and Widgets libraries.

Using linuxdeployqt with Travis CI

A common use case for linuxdeployqt is to use it on Travis CI after the make command. The following example illustrates how to use linuxdeployqt with Travis CI. Create a .travis.yml file similar to this one (be sure to customize it, e.g., change APPNAME to the name of your application as it is spelled in the Name= entry of the .desktop file):

When you save your change, then Travis CI should build and upload an AppImage for you. More likely than not, some fine-tuning will still be required.

For this to work, you need to set up GITHUB_TOKEN in Travis CI; please see https://github.com/probonopd/uploadtool.

By default, qmake .pro files generated by Qt Creator unfortunately don’t support make install out of the box. In this case you will get

Fix for «make: Nothing to be done for ‘install'»

If qmake does not allow for make install or does not install the desktop file and icon, then you need to change your .pro file it similar to https://github.com/probonopd/FeedTheMonkey/blob/master/FeedTheMonkey.pro.

Here is another simple example.

It is common on Unix to also use the build tool to install applications and libraries; for example, by invoking make install . For this reason, qmake has the concept of an install set, an object which contains instructions about the way a part of a project is to be installed.

For projects that use CMake, autotools, or meson with ninja instead of qmake

CMake wants DESTDIR instead:

Some applications have the bad habit of relying on CMake versions newer than what comes with the oldest still-supported distributions. In this case, install a newer CMake with

Under some circumstances it may also be required to add -DCMAKE_INSTALL_LIBDIR=/usr/lib to the cmake call.

autotools (the dinosaur that spends precious minutes «checking. «) wants DESTDIR too but insists on an absolute link which we can feed it using readlink:

Caution if you encounter

Here, CONFIG+=use_qt_paths needs to be removed, otherwise it will install everything under the Qt installation paths in /opt/qt58 when using the beineri ppa.

The exception is that you are building Qt libraries that should be installed to the same location where Qt resides on your system, from where it will be picked up by linuxdeployqt .

meson with ninja apparently wants

When using Qt from distribution packages

On Ubuntu 14.04, you will need to pass in -qmake=/usr/lib/x86_64-linux-gnu/qt5/bin/qmake when using distribution packages.

A note on DESTDIR

Automating DESTDIR can be a pain, so it’s best if the program supports it to start with; my package Auto-DESTDIR can automatically support DESTDIR in some cases if the program installation does not support it to begin with.

Sending Pull Requests on GitHub

linuxdeployqt is great for upstream application projects that want to release their software in binary form to Linux users quickly and without much overhead. If you would like to see a particular application use linuxdeployqt , then sending a Pull Request may be an option to get the upstream application project to consider it. You can use the following template text for Pull Requests but make sure to customize it to the project in question.

Projects using linuxdeployqt

These projects are already using Travis CI and linuxdeployqt to provide AppImages of their builds:

These projects are using GitHub Actions and linuxdeployqt to provide AppImages of their builds:

This project is already using linuxdeployqt in a custom Jenkins workflow:

This GitHub template invokes linuxdeployqt during a GitHub CI Action:

These projects are already using linuxdeployqt:

This project on GitLab uses linuxdeployqt:

This project can be bundled successfully using linuxdeployqt:

One great way to contribute is to send Pull Requests to the application projects you’d like to see use linuxdeployqt, as described above. You are also welcome to contribute to linuxdeployqt development itself. Please discuss in the forum or using GitHub issues and Pull Requests.

The developers are in the channel #AppImage on irc.freenode.net

About

Makes Linux applications self-contained by copying in the libraries and plugins that the application uses, and optionally generates an AppImage. Can be used for Qt and other applications

Источник

Qt Documentation

Contents

This documentation discusses specific deployment issues for Qt for Linux/X11. We will demonstrate the procedures in terms of deploying the Plug & Paint application that is provided in Qt’s examples directory.

Due to the proliferation of Unix systems (such as commercial Unixes, Linux distributions, and so on), deployment on Unix is a complex topic. Before we start, be aware that programs compiled for one Unix flavor will probably not run on a different Unix system. For example, unless you use a cross-compiler, you cannot compile your application on Irix and distribute it on AIX.

Static Linking

Static linking is often the safest and easiest way to distribute an application on Unix since it relieves you from the task of distributing the Qt libraries and ensuring that they are located in the default search path for libraries on the target system.

Building Qt Statically

To use this approach, you must start by installing a static version of the Qt library:

We specify the prefix so that we do not overwrite the existing Qt installation. The example above only builds the Qt libraries, i.e. the examples and Qt Designer will not be built. When make is done, you will find the Qt libraries in the /path/to/Qt/lib directory.

When linking your application against static Qt libraries, note that you might need to add more libraries to the LIBS line in your project file. For more information, see the Application Dependencies section.

Linking the Application to the Static Version of Qt

Once Qt is built statically, the next step is to regenerate the makefile and rebuild the application. First, we must go into the directory that contains the application:

Now run qmake to create a new makefile for the application, and do a clean build to create the statically linked executable:

You probably want to link against the release libraries, and you can specify this when invoking qmake . Note that we must set the path to the static Qt that we just built.

To check that the application really links statically with Qt, run the ldd tool (available on most Unices):

Verify that the Qt libraries are not mentioned in the output.

Now, provided that everything compiled and linked without any errors, we should have a plugandpaint file that is ready for deployment. One easy way to check that the application really can be run stand-alone is to copy it to a machine that doesn’t have Qt or any Qt applications installed, and run it on that machine.

Remember that if your application depends on compiler specific libraries, these must still be redistributed along with your application. For more information, see the Application Dependencies section.

The Plug & Paint example consists of several components: The core application (Plug & Paint), and the Basic Tools and Extra Filters plugins. Since we cannot deploy plugins using the static linking approach, the executable we have prepared so far is incomplete. The application will run, but the functionality will be disabled due to the missing plugins. To deploy plugin-based applications we should use the shared library approach.

Shared Libraries

We have two challenges when deploying the Plug & Paint application using the shared libraries approach: The Qt runtime has to be correctly redistributed along with the application executable, and the plugins have to be installed in the correct location on the target system so that the application can find them.

Building Qt as a Shared Library

We assume that you already have installed Qt as a shared library, which is the default when installing Qt, in the /path/to/Qt directory.

Linking the Application to Qt as a Shared Library

After ensuring that Qt is built as a shared library, we can build the Plug & Paint application. First, we must go into the directory that contains the application:

Now run qmake to create a new makefile for the application, and do a clean build to create the dynamically linked executable:

This builds the core application, the following will build the plugins:

If everything compiled and linked without any errors, we will get a plugandpaint executable and the libpnp_basictools.so and libpnp_extrafilters.so plugin files.

Creating the Application Package

There is no standard package management on Unix, so the method we present below is a generic solution. See the documentation for your target system for information on how to create a package.

To deploy the application, we must make sure that we copy the relevant Qt libraries (corresponding to the Qt modules used in the application), the platform plugin, and the executable to the same directory tree. Remember that if your application depends on compiler specific libraries, these must also be redistributed along with your application. For more information, see the Application Dependencies section.

We’ll cover the plugins shortly, but the main issue with shared libraries is that you must ensure that the dynamic linker will find the Qt libraries. Unless told otherwise, the dynamic linker doesn’t search the directory where your application resides. There are many ways to solve this:

• You can install the Qt libraries in one of the system library paths (e.g. /usr/lib on most systems).
• You can pass a predetermined path to the -rpath command-line option when linking the application. This will tell the dynamic linker to look in this directory when starting your application.
• You can write a startup script for your application, where you modify the dynamic linker configuration (e.g., adding your application’s directory to the LD_LIBRARY_PATH environment variable.

Note: If your application will be running with «Set user ID on execution,» and if it will be owned by root, then LD_LIBRARY_PATH will be ignored on some platforms. In this case, use of the LD_LIBRARY_PATH approach is not an option).

The disadvantage of the first approach is that the user must have super user privileges. The disadvantage of the second approach is that the user may not have privileges to install into the predetermined path. In either case, the users don’t have the option of installing to their home directory. We recommend using the third approach since it is the most flexible. For example, a plugandpaint.sh script will look like this:

By running this script instead of the executable, you are sure that the Qt libraries will be found by the dynamic linker. Note that you only have to rename the script to use it with other applications.

When looking for plugins, the application searches in a plugins subdirectory inside the directory of the application executable. Either you have to manually copy the plugins into the plugins directory, or you can set the DESTDIR in the plugins’ project files:

An archive distributing all the Qt libraries, and all the plugins, required to run the Plug & Paint application, would have to include the following files:

Component	File Name
The executable	plugandpaint
The script to run the executable	plugandpaint.sh
The Basic Tools plugin	plugins\libpnp_basictools.so
The ExtraFilters plugin	plugins\libpnp_extrafilters.so
The Qt xcb platform plugin	platforms\libqxcb.so
The Qt Core module	libQt5Core.so.5
The Qt GUI module	libQt5Gui.so.5
The Qt Widgets module	libQt5Widgets.so.5

On most systems, the extension for shared libraries is .so . A notable exception is HP-UX, which uses .sl .

Remember that if your application depends on compiler specific libraries, these must still be redistributed along with your application. For more information, see the Application Dependencies section.

To verify that the application now can be successfully deployed, you can extract this archive on a machine without Qt and without any compiler installed, and try to run it, i.e. run the plugandpaint.sh script.

An alternative to putting the plugins in the plugins subdirectory is to add a custom search path when you start your application using QApplication::addLibraryPath() or QApplication::setLibraryPaths().

Application Dependencies

Additional Libraries

To find out which libraries your application depends on, run the ldd tool (available on most Unices):

This will list all the shared library dependencies for your application. Depending on configuration, these libraries must be redistributed along with your application. In particular, the standard C++ library must be redistributed if you’re compiling your application with a compiler that is binary incompatible with the system compiler. When possible, the safest solution is to link against these libraries statically.

You will probably want to link dynamically with the regular X11 libraries, since some implementations will try to open other shared libraries with dlopen() , and if this fails, the X11 library might cause your application to crash.

It’s also worth mentioning that Qt will look for certain X11 extensions, such as Xinerama and Xrandr, and possibly pull them in, including all the libraries that they link against. If you can’t guarantee the presence of a certain extension, the safest approach is to disable it when configuring Qt (e.g. ./configure -no-xrandr ).

FontConfig and FreeType are other examples of libraries that aren’t always available or that aren’t always binary compatible. As strange as it may sound, some software vendors have had success by compiling their software on very old machines and have been very careful not to upgrade any of the software running on them.

When linking your application against the static Qt libraries, you must explicitly link with the dependent libraries mentioned above. Do this by adding them to the LIBS variable in your project file.

From Qt version 5.2 onwards, the officially supported version for OpenSSL is 1.0.0 or later. Versions >= 0.9.7 and libqxcb.so . This file must be located within a specific subdirectory (by default, platforms ) under your distribution directory. Alternatively, it is possible to adjust the search path Qt uses to find its plugins, as described below.

Your application may also depend on one or more Qt plugins, such as the JPEG image format plugin or a SQL driver plugin. Be sure to distribute any Qt plugins that you need with your application. Similar to the platform plugin, each type of plugin must be located within a specific subdirectory (such as imageformats or sqldrivers ) within your distribution directory.

The search path for Qt plugins (as well as a few other paths) is hard-coded into the QtCore library. By default, the first plugin search path will be hard-coded as /path/to/Qt/plugins . As mentioned above, using predetermined paths has certain disadvantages, so you need to examine various alternatives to make sure that the Qt plugins are found:

• Using qt.conf . This is the recommended approach since it provides the most flexibility.
• Using QApplication::addLibraryPath() or QApplication::setLibraryPaths().
• Using a third party installation utility or the target system’s package manager to change the hard-coded paths in the QtCore library.

The How to Create Qt Plugins document outlines the issues you need to pay attention to when building and deploying plugins for Qt applications.

В© 2021 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.

Источник