/usr/share/qt5/doc/qtdoc/linux-deployment.html is in qt5-doc-html 5.2.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- linux.qdoc -->
<title>Qt for Linux/X11 - Deployment | QtDoc 5.2</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li><a href="index.html">Qt 5.2</a></li>
<li>Qt for Linux/X11 - Deployment</li>
<li id="buildversion">
Qt 5.2.1 Reference Documentation</li>
</ul>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#static-linking">Static Linking</a></li>
<li class="level2"><a href="#building-qt-statically">Building Qt Statically</a></li>
<li class="level2"><a href="#linking-the-application-to-the-static-version-of-qt">Linking the Application to the Static Version of Qt</a></li>
<li class="level1"><a href="#shared-libraries">Shared Libraries</a></li>
<li class="level2"><a href="#building-qt-as-a-shared-library">Building Qt as a Shared Library</a></li>
<li class="level2"><a href="#linking-the-application-to-qt-as-a-shared-library">Linking the Application to Qt as a Shared Library</a></li>
<li class="level2"><a href="#creating-the-application-package">Creating the Application Package</a></li>
<li class="level1"><a href="#application-dependencies">Application Dependencies</a></li>
<li class="level2"><a href="#additional-libraries">Additional Libraries</a></li>
<li class="level2"><a href="#qt-plugins">Qt Plugins</a></li>
</ul>
</div>
<h1 class="title">Qt for Linux/X11 - Deployment</h1>
<span class="subtitle"></span>
<!-- $$$linux-deployment.html-description -->
<div class="descr"> <a name="details"></a>
<p>This documentation discusses specific deployment issues for <a href="linux.html">Qt for Linux/X11</a>. We will demonstrate the procedures in terms of deploying the <a href="../qtwidgets/qtwidgets-tools-plugandpaint-example.html">Plug & Paint</a> application that is provided in Qt's examples directory.</p>
<p>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.</p>
<a name="static-linking"></a>
<h2>Static Linking</h2>
<p>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.</p>
<a name="building-qt-statically"></a>
<h3>Building Qt Statically</h3>
<p>To use this approach, you must start by installing a static version of the Qt library:</p>
<pre class="cpp">cd <span class="operator">/</span>path<span class="operator">/</span>to<span class="operator">/</span><span class="type"><a href="../qtcore/qt.html">Qt</a></span>
<span class="operator">.</span><span class="operator">/</span>configure <span class="operator">-</span><span class="keyword">static</span> <span class="operator">-</span>prefix <span class="operator">/</span>path<span class="operator">/</span>to<span class="operator">/</span><span class="type"><a href="../qtcore/qt.html">Qt</a></span> <span class="operator"><</span>other parameters<span class="operator">></span>
make sub<span class="operator">-</span>src</pre>
<p>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 <tt>make</tt> is done, you will find the Qt libraries in the <tt>/path/to/Qt/lib</tt> directory.</p>
<p>When linking your application against static Qt libraries, note that you might need to add more libraries to the <tt>LIBS</tt> line in your project file. For more information, see the <a href="#application-dependencies">Application Dependencies</a> section.</p>
<a name="linking-the-application-to-the-static-version-of-qt"></a>
<h3>Linking the Application to the Static Version of Qt</h3>
<p>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:</p>
<pre class="cpp">cd <span class="operator">/</span>path<span class="operator">/</span>to<span class="operator">/</span><span class="type"><a href="../qtcore/qt.html">Qt</a></span><span class="operator">/</span>examples<span class="operator">/</span>tools<span class="operator">/</span>plugandpaint</pre>
<p>Now run qmake to create a new makefile for the application, and do a clean build to create the statically linked executable:</p>
<pre class="cpp">make clean
PATH<span class="operator">=</span><span class="operator">/</span>path<span class="operator">/</span>to<span class="operator">/</span><span class="type"><a href="../qtcore/qt.html">Qt</a></span><span class="operator">/</span>bin:$PATH
<span class="keyword">export</span> PATH
qmake <span class="operator">-</span>config release
make</pre>
<p>You probably want to link against the release libraries, and you can specify this when invoking <tt>qmake</tt>. Note that we must set the path to the static Qt that we just built.</p>
<p>To check that the application really links statically with Qt, run the <tt>ldd</tt> tool (available on most Unices):</p>
<pre class="cpp">ldd <span class="operator">.</span><span class="operator">/</span>application</pre>
<p>Verify that the Qt libraries are not mentioned in the output.</p>
<p>Now, provided that everything compiled and linked without any errors, we should have a <tt>plugandpaint</tt> 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.</p>
<p>Remember that if your application depends on compiler specific libraries, these must still be redistributed along with your application. For more information, see the <a href="#application-dependencies">Application Dependencies</a> section.</p>
<p>The <a href="../qtwidgets/qtwidgets-tools-plugandpaint-example.html">Plug & Paint</a> example consists of several components: The core application (<a href="../qtwidgets/qtwidgets-tools-plugandpaint-example.html">Plug & Paint</a>), and the <a href="../qtwidgets/qtwidgets-tools-plugandpaintplugins-basictools-example.html">Basic Tools</a> and <a href="../qtwidgets/qtwidgets-tools-plugandpaintplugins-extrafilters-example.html">Extra Filters</a> 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.</p>
<a name="shared-libraries"></a>
<h2>Shared Libraries</h2>
<p>We have two challenges when deploying the <a href="../qtwidgets/qtwidgets-tools-plugandpaint-example.html">Plug & Paint</a> 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.</p>
<a name="building-qt-as-a-shared-library"></a>
<h3>Building Qt as a Shared Library</h3>
<p>We assume that you already have installed Qt as a shared library, which is the default when installing Qt, in the <tt>/path/to/Qt</tt> directory.</p>
<a name="linking-the-application-to-qt-as-a-shared-library"></a>
<h3>Linking the Application to Qt as a Shared Library</h3>
<p>After ensuring that Qt is built as a shared library, we can build the <a href="../qtwidgets/qtwidgets-tools-plugandpaint-example.html">Plug & Paint</a> application. First, we must go into the directory that contains the application:</p>
<pre class="cpp">cd <span class="operator">/</span>path<span class="operator">/</span>to<span class="operator">/</span><span class="type"><a href="../qtcore/qt.html">Qt</a></span><span class="operator">/</span>examples<span class="operator">/</span>tools<span class="operator">/</span>plugandpaint</pre>
<p>Now run qmake to create a new makefile for the application, and do a clean build to create the dynamically linked executable:</p>
<pre class="cpp">make clean
qmake <span class="operator">-</span>config release
make</pre>
<p>This builds the core application, the following will build the plugins:</p>
<pre class="cpp">cd <span class="operator">.</span><span class="operator">.</span><span class="operator">/</span>plugandpaintplugins
make clean
qmake <span class="operator">-</span>config release
make</pre>
<p>If everything compiled and linked without any errors, we will get a <tt>plugandpaint</tt> executable and the <tt>libpnp_basictools.so</tt> and <tt>libpnp_extrafilters.so</tt> plugin files.</p>
<a name="creating-the-application-package"></a>
<h3>Creating the Application Package</h3>
<p>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.</p>
<p>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 <a href="#qt-plugins">platform plugin</a>, 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 <a href="#application-dependencies">Application Dependencies</a> section.</p>
<p>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:</p>
<ul>
<li>You can install the Qt libraries in one of the system library paths (e.g. <tt>/usr/lib</tt> on most systems).</li>
<li>You can pass a predetermined path to the <tt>-rpath</tt> command-line option when linking the application. This will tell the dynamic linker to look in this directory when starting your application.</li>
<li>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 <tt>LD_LIBRARY_PATH</tt> environment variable.<p><b>Note: </b>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).</p></li>
</ul>
<p>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 <tt>plugandpaint.sh</tt> script will look like this:</p>
<pre class="cpp"><span class="preprocessor">#!/bin/sh</span>
appname<span class="operator">=</span>`basename $<span class="number">0</span> <span class="operator">|</span> sed s<span class="operator">,</span>\<span class="operator">.</span>sh$<span class="operator">,</span><span class="operator">,</span>`
dirname<span class="operator">=</span>`dirname $<span class="number">0</span>`
tmp<span class="operator">=</span><span class="string">"${dirname#?}"</span>
<span class="keyword">if</span> <span class="operator">[</span> <span class="string">"${dirname%$tmp}"</span> <span class="operator">!</span><span class="operator">=</span> <span class="string">"/"</span> <span class="operator">]</span>; then
dirname<span class="operator">=</span>$PWD<span class="operator">/</span>$dirname
fi
LD_LIBRARY_PATH<span class="operator">=</span>$dirname
<span class="keyword">export</span> LD_LIBRARY_PATH
$dirname<span class="operator">/</span>$appname <span class="string">"$@"</span></pre>
<p>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.</p>
<p>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 <tt>plugins</tt> directory, or you can set the <tt>DESTDIR</tt> in the plugins' project files:</p>
<pre class="cpp">DESTDIR = /path/to/Qt/plugandpaint/plugins</pre>
<p>An archive distributing all the Qt libraries, and all the plugins, required to run the <a href="../qtwidgets/qtwidgets-tools-plugandpaint-example.html">Plug & Paint</a> application, would have to include the following files:</p>
<table class="generic" width="100%">
<thead><tr class="qt-style"><th >Component</th><th colspan="2" rowspan=" 1">File Name</th></tr></thead>
<tr valign="top" class="odd"><td >The executable</td><td colspan="2" rowspan=" 1"><tt>plugandpaint</tt></td></tr>
<tr valign="top" class="even"><td >The script to run the executable</td><td colspan="2" rowspan=" 1"><tt>plugandpaint.sh</tt></td></tr>
<tr valign="top" class="odd"><td >The Basic Tools plugin</td><td colspan="2" rowspan=" 1"><tt>plugins\libpnp_basictools.so</tt></td></tr>
<tr valign="top" class="even"><td >The ExtraFilters plugin</td><td colspan="2" rowspan=" 1"><tt>plugins\libpnp_extrafilters.so</tt></td></tr>
<tr valign="top" class="odd"><td >The Qt xcb platform plugin</td><td colspan="2" rowspan=" 1"><tt>platforms\libqxcb.so</tt></td></tr>
<tr valign="top" class="even"><td >The Qt Core module</td><td colspan="2" rowspan=" 1"><tt>libQt5Core.so.5</tt></td></tr>
<tr valign="top" class="odd"><td >The Qt GUI module</td><td colspan="2" rowspan=" 1"><tt>libQt5Gui.so.5</tt></td></tr>
<tr valign="top" class="even"><td >The Qt Widgets module</td><td colspan="2" rowspan=" 1"><tt>libQt5Widgets.so.5</tt></td></tr>
</table>
<p>On most systems, the extension for shared libraries is <tt>.so</tt>. A notable exception is HP-UX, which uses <tt>.sl</tt>.</p>
<p>Remember that if your application depends on compiler specific libraries, these must still be redistributed along with your application. For more information, see the <a href="#application-dependencies">Application Dependencies</a> section.</p>
<p>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 <tt>plugandpaint.sh</tt> script.</p>
<p>An alternative to putting the plugins in the <tt>plugins</tt> subdirectory is to add a custom search path when you start your application using QApplication::addLibraryPath() or QApplication::setLibraryPaths().</p>
<pre class="cpp">qApp<span class="operator">-</span><span class="operator">></span>addLibraryPath(<span class="string">"/some/other/path"</span>);</pre>
<a name="application-dependencies"></a>
<h2>Application Dependencies</h2>
<a name="additional-libraries"></a>
<h3>Additional Libraries</h3>
<p>To find out which libraries your application depends on, run the <tt>ldd</tt> tool (available on most Unices):</p>
<pre class="cpp">ldd <span class="operator">.</span><span class="operator">/</span>application</pre>
<p>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.</p>
<p>You will probably want to link dynamically with the regular X11 libraries, since some implementations will try to open other shared libraries with <tt>dlopen()</tt>, and if this fails, the X11 library might cause your application to crash.</p>
<p>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. <tt>./configure -no-xrandr</tt>).</p>
<p>FontConfig and <a href="qt-embedded-fonts.html#freetype">FreeType</a> 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.</p>
<p>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 <tt>LIBS</tt> variable in your project file.</p>
<a name="qt-plugins"></a>
<h3>Qt Plugins</h3>
<p>All Qt GUI applications require a plugin that implements the <a href="qpa.html">Qt Platform Abstraction</a> (QPA) layer in Qt 5. For Linux/X11, the name of the platform plugin is <tt>libqxcb.so</tt>. This file must be located within a specific subdirectory (by default, <tt>platforms</tt>) under your distribution directory. Alternatively, it is possible to adjust the search path Qt uses to find its plugins, as described below.</p>
<p>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 <tt>imageformats</tt> or <tt>sqldrivers</tt>) within your distribution directory.</p>
<p><b>Note: </b>If you are deploying an application that uses <a href="../qtwebkit/qtwebkit-index.html">Qt WebKit</a> to display HTML pages from the World Wide Web, you should include all text codec plugins to support as many HTML encodings possible.</p><p>The search path for Qt plugins (as well as a few other paths) is hard-coded into the <a href="../qtserialport/qtcore-module.html">QtCore</a> library. By default, the first plugin search path will be hard-coded as <tt>/path/to/Qt/plugins</tt>. 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:</p>
<ul>
<li><a href="qt-conf.html">Using <tt>qt.conf</tt></a>. This is the recommended approach since it provides the most flexibility.</li>
<li>Using QApplication::addLibraryPath() or QApplication::setLibraryPaths().</li>
<li>Using a third party installation utility or the target system's package manager to change the hard-coded paths in the <a href="../qtserialport/qtcore-module.html">QtCore</a> library.</li>
</ul>
<p>The <a href="../qtcore/plugins-howto.html">How to Create Qt Plugins</a> document outlines the issues you need to pay attention to when building and deploying plugins for Qt applications.</p>
</div>
<!-- @@@linux-deployment.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Digia, Qt and their respective logos are trademarks of Digia Plc in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|