Qt for Linux/X11 - Deployment

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

cd /path/to/Qt
./configure -static -prefix /path/to/Qt <other parameters>
make

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.

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:

cd /path/to/Qt/examples/widgets/tools/plugandpaint/app

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

make clean
PATH=/path/to/Qt/bin:$PATH
export PATH
qmake -config release
make

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):

ldd ./application

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.

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.

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:

cd /path/to/Qt/examples/tools/plugandpaint

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

make clean
qmake -config release
make

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

cd ../plugandpaint/plugins
make clean
qmake -config release
make

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.

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.

  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:

#!/bin/sh
appname=`basename $0 | sed s,\.sh$,,`

dirname=`dirname $0`
tmp="${dirname#?}"

if [ "${dirname%$tmp}" != "/" ]; then
dirname=$PWD/$dirname
fi
LD_LIBRARY_PATH=$dirname
export LD_LIBRARY_PATH
$dirname/$appname "$@"

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:

DESTDIR = /path/to/Qt/plugandpaint/plugins