/**************************************************************************** ** ** Copyright (C) 2015 The Qt Company Ltd. ** Contact: http://www.qt.io/licensing/ ** ** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:FDL$ ** Commercial License Usage ** Licensees holding valid commercial Qt licenses may use this file in ** accordance with the commercial license agreement provided with the ** Software or, alternatively, in accordance with the terms contained in ** a written agreement between you and The Qt Company. For licensing terms ** and conditions see http://www.qt.io/terms-conditions. For further ** information use the contact form at http://www.qt.io/contact-us. ** ** GNU Free Documentation License Usage ** Alternatively, this file may be used under the terms of the GNU Free ** Documentation License version 1.3 as published by the Free Software ** Foundation and appearing in the file included in the packaging of ** this file. Please review the following information to ensure ** the GNU Free Documentation License version 1.3 requirements ** will be met: http://www.gnu.org/copyleft/fdl.html. ** $QT_END_LICENSE$ ** ****************************************************************************/ /*! \page linux.html \title Qt for Linux/X11 \brief Platform support for Linux/X11. \ingroup supportedplatform Qt's support for different Linux platforms is extensive and mature. \section1 Downloading and Installing Qt There are two ways to install Qt: \list 1 \li through the Qt Installers - downloads and installs Qt \li through the \e{Qt sources}. \endlist You can download the Qt 5 installers and sources from the \l Downloads page. For more information, visit the \l{Getting Started with Qt} page. \section2 Requirements for Development Host The Qt installers for Linux assume that a C++ compiler, debugger, make, and other development tools are provided by the host operating system. In addition, building graphical Qt applications requires OpenGL libraries and headers installed. Most Linux distributions do not install all of these by default, but setting up a development environment is still straightforward. Use the following commands to install the basic requirements for building Qt applications: \section3 Debian/Ubuntu (apt-get) \badcode sudo apt-get install build-essential libgl1-mesa-dev \endcode \section3 Fedora/RHEL/CentOS (yum) \badcode sudo yum groupinstall "C Development Tools and Libraries" sudo yum install mesa-libGL-devel \endcode \section3 openSUSE (zypper) \badcode sudo zypper install -t pattern devel_basis \endcode \section2 Building Qt 5 from Source You can also build Qt 5 from the source package and configure it according to your target platform. The source packages are obtained from \l{http://www.qt.io/download/}. Below, you will find more information about building Qt from source. \list \li \l {Qt for X11 Requirements} \li \l{Qt for Linux/X11 - Building from Source} \endlist \section1 Deployment and Other Issues The pages below covers specific issues and recommendations for creating Linux/X11 applications. \list \li \l{Qt for Linux/X11 - Deployment} \li \l{Qt for Linux/X11 - Specific Issues} \endlist \section1 Where to Go from Here We invite you to explore the rest of Qt. We prepared overviews which help you decide which APIs to use and our examples demonstrate how to use our API. \list \li \l{Qt Overviews} - list of topics about application development \li \l{Qt Examples and Tutorials}{Examples and Tutorials} - code samples and tutorials \li \l{Qt Reference Pages} - a listing of C++ and QML APIs \li \l{Qt X11 Extras} - provides additional APIs for X11 \endlist Qt's vibrant and active community site, \l{http://qt.io} houses a wiki, a forum, and additional learning guides and presentations. */ /*! \page linux-requirements.html \title Qt for X11 Requirements \brief Setting up the X11 environment for Qt. \section1 Platform Plugin Dependencies On Linux, the \e xcb QPA (Qt Platform Abstraction) platform plugin is used. It provides the basic functionality needed by \l{Qt GUI} and \l{Qt Widgets} to run against X11. Its library dependencies are described the following table. To build Qt from its source code, you will also need to install the development packages for these libraries for your system. It's possible to configure Qt with -qt-xcb, which compiles in a set of xcb helper libraries instead of trying to link against the system versions. This can help make Qt less dependent on some of the xcb helper libraries that might not be available on all distributions. The table specifies which dependencies are provided by -qt-xcb. \table 100% \header \li Name \li Library \li Notes \li Configuration options \li Minimum working version \row {id="OptionalColor"} \li XRender \li libXrender \li X Rendering Extension; used for anti-aliasing and alpha cursor support \li \tt{-xrender} or auto-detected \li 0.9.0 \row {id="OptionalColor"} \li xcb-render \li libxcb-render \li X C Bindings for Render extension \li auto-detected or provided by -qt-xcb \li 1.8.1 \row {id="OptionalColor"} \li xcb-render-util \li libxcb-render-util \li Utility library for XCB for Render extension \li auto-detected or provided by -qt-xcb \li 0.3.8 \row {id="OptionalColor"} \li xcb-shape \li libxcb-shape \li X C Bindings for Shape extension \li auto-detected or provided by -qt-xcb \li 1.8.1 \row {id="DefaultColor"} \li xcb-randr \li libxcb-randr \li X C Bindings for Resize and Rotate Extension \li auto-detected or provided by -qt-xcb \li 1.8.1 \row {id="DefaultColor"} \li xcb-xfixes \li libxcb-xfixes \li X C Bindings for Fixes Extension \li auto-detected or provided by -qt-xcb \li 1.8.1 \row {id="DefaultColor"} \li xcb-sync \li libxcb-sync \li X C Bindings for Sync Extension \li auto-detected or provided by -qt-xcb \li 1.8.1 \row {id="DefaultColor"} \li xcb-shm \li libxcb-shm \li X C Bindings for Shared Memory Extension \li auto-detected or provided by -qt-xcb \li 1.8.1 \row {id="DefaultColor"} \li xcb-icccm \li libxcb-icccm \li X C Bindings for ICCCM Protocol \li auto-detected or provided by -qt-xcb \li 0.3.9 \row {id="DefaultColor"} \li xcb-keysyms \li libxcb-keysyms \li Utility library for XCB for keycode conversion \li auto-detected or provided by -qt-xcb \li 0.3.9 \row {id="DefaultColor"} \li xcb-image \li libxcb-image \li Utility library for XCB for XImage and XShmImage, used for QBackingStore and cursor support \li auto-detected or provided by -qt-xcb \li 0.3.9 \row {id="OptionalColor"} \li Fontconfig \li libfontconfig \li Font customization and configuration \li \tt{-fontconfig} or auto-detected \li 2.1 \row {id="OptionalColor"} \li FreeType \li libfreetype \li Font engine \li \li 2.1.3 \row {id="DefaultColor"} \li Xi \li libXi \li X11 Input Extensions \li \tt{-xinput} or auto-detected \li 1.3.0 \row {id="DefaultColor"} \li Xext \li libXext \li X Extensions \li \li 6.4.3 \row {id="DefaultColor"} \li X11 \li libX11 \li X11 client-side library \li \li 6.2.1 \row {id="DefaultColor"} \li xcb \li libxcb \li X C Binding library \li \li 1.8.1 \row {id="DefaultColor"} \li X11-xcb \li libX11-xcb \li Xlib/XCB interface library \li \li 1.3.2 \row {id="SMColor"} \li SM \li libSM \li X Session Management \li \tt{-sm} or auto-detected \li 6.0.4 \row {id="SMColor"} \li ICE \li libICE \li Inter-Client Exchange \li \tt{-sm} or auto-detected \li 6.3.5 \row {id="GlibColor"} \li glib \li libglib-2.0 \li Common event loop handling \li \tt{-glib} or auto-detected \li 2.8.3 \row {id="PthreadColor"} \li pthread \li libpthread \li Multithreading \li \li 2.3.5 \endtable Development packages for these libraries contain header files that are used when building Qt from its source code. On Debian-based GNU/Linux systems, for example, we recommend that you install the following development packages: \list \li libfontconfig1-dev \li libfreetype6-dev \li libx11-dev \li libxext-dev \li libxfixes-dev \li libxi-dev \li libxrender-dev \li libxcb1-dev \li libx11-xcb-dev \li libxcb-glx0-dev \endlist Additionally, if you do not configure with -qt-xcb, you should also install these development packages: \list \li libxcb-keysyms1-dev \li libxcb-image0-dev \li libxcb-shm0-dev \li libxcb-icccm4-dev \li libxcb-sync0-dev \li libxcb-xfixes0-dev \li libxcb-shape0-dev \li libxcb-randr0-dev \li libxcb-render-util0-dev \endlist Some of these packages depend on others in this list, so installing one may cause others to be automatically installed. Other distributions may provide system packages with similar names. \section1 OpenGL Dependencies The configure script will autodetect if OpenGL headers and libraries are installed on your system, and if so, it will include the \l{Qt OpenGL} module in the Qt library. If your OpenGL headers or libraries are placed in a non-standard directory, you may need to change the \c QMAKE_INCDIR_OPENGL and/or \c QMAKE_LIBDIR_OPENGL in the config file for your system. The QGL documentation assumes that you are familiar with OpenGL programming. If you're new to the subject a good starting point is \l{http://www.opengl.org/}. \section1 Multimedia Dependencies As described in the \l Multimedia overview, Qt Multimedia uses the GStreamer multimedia framework as the backend for audio and video playback on Linux. The minimum required version of GStreamer is 0.10.24. The 1.x series is also supported. To build Qt Multimedia, you need the GStreamer library, base plugins, and development files for your system. To run applications that use Qt Multimedia, you might also need to install the following GStreamer plugins: 'good', 'ugly', 'bad', ffmpeg (0.10), and libav (1.x). These additional plugins contain various codecs for audio and video decoding, as well as the necessary components for using the camera APIs. The package names for GStreamer vary between Linux distributions; try searching for \c gstreamer or \c libgstreamer in your distribution's package repository to find suitable packages. \section1 Qt WebEngine Dependencies \l{Qt WebEngine} depends on some extra development tools in addition to those required for the rest of Qt. \note These dependencies are only needed if you use a source version of Qt. They are not required when using a prebuilt library. For the most up-to-date information about \l{Qt WebEngine} dependencies, see the \l{Qt WebEngine Wiki}{Qt WebEngine} wiki. */ /*! \page linux-building.html \title Qt for Linux/X11 - Building from Source \brief How to configure and build Qt on Linux/X11 platforms. You can download the Qt 5 sources from the \l Downloads page. For more information, visit the \l{Getting Started with Qt} page. Qt for X11 has some requirements that are given in more detail in the \l{Qt for X11 Requirements} document. \section1 Step 1: Installing the License File (Commercial Editions Only) If you have the commercial edition of Qt, install your license file as \c{$HOME/.qt-license}. For the open source version you do not need a license file. \section1 Step 2: Unpacking the Archive Unpack the archive if you have not done so already. For example, if you have the \c{qt-everywhere-opensource-src-%VERSION%.tar.gz} package, type the following commands at a command line prompt: \snippet snippets/code/doc_src_installation.qdoc 0 This creates the directory \c{/tmp/qt-everywhere-opensource-src-%VERSION%} containing the files from the archive. We only support the GNU version of the tar archiving utility. Note that on some systems it is called gtar. \section1 Step 3: Building the Library To configure the Qt library for your machine type, run the \c{./configure} script in the package directory. By default, Qt is configured for installation in the \c{/usr/local/Qt-%VERSION%} directory, but this can be changed by using the \c{-prefix} option. \snippet snippets/code/doc_src_installation.qdoc 1 The \l{Qt Configure Options}{Configure Options} page contains more information about the configure options. To create the library and compile all the examples, tools, and tutorials, type: \snippet snippets/code/doc_src_installation.qdoc 2 If \c{-prefix} is outside the build directory, you need to install the library, examples, tools, and tutorials in the appropriate place. To do this (as root if necessary), type: \snippet snippets/code/doc_src_installation.qdoc 3 Note that on some systems the make utility is named differently, e.g. gmake. The configure script tells you which make utility to use. \b{Note:} If you later need to reconfigure and rebuild Qt from the same location, ensure that all traces of the previous configuration are removed by entering the build directory and typing \c{make confclean} before running \c configure again. \section1 Step 4: Set the Environment Variables In order to use Qt, some environment variables needs to be extended. \snippet snippets/code/doc_src_installation.qdoc 4 This is done like this: In \c{.profile} (if your shell is bash, ksh, zsh or sh), add the following lines: \snippet snippets/code/doc_src_installation.qdoc 5 In \c{.login} (in case your shell is csh or tcsh), add the following line: \snippet snippets/code/doc_src_installation.qdoc 6 If you use a different shell, please modify your environment variables accordingly. For compilers that do not support rpath you must also extended the \c LD_LIBRARY_PATH environment variable to include \c{/usr/local/Qt-%VERSION%/lib}. On Linux with GCC this step is not needed. */ /*! \page linux-deployment.html \title Qt for Linux/X11 - Deployment This documentation discusses specific deployment issues for \l{Qt for Linux/X11}. We will demonstrate the procedures in terms of deploying the \l{tools/plugandpaint}{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. \section1 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. \section2 Building Qt Statically To use this approach, you must start by installing a static version of the Qt library: \snippet snippets/code/doc_src_deployment.qdoc 0 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 \c make is done, you will find the Qt libraries in the \c /path/to/Qt/lib directory. When linking your application against static Qt libraries, note that you might need to add more libraries to the \c LIBS line in your project file. For more information, see the \l {Application Dependencies} section. \section2 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: \snippet snippets/code/doc_src_deployment.qdoc 1 Now run qmake to create a new makefile for the application, and do a clean build to create the statically linked executable: \snippet snippets/code/doc_src_deployment.qdoc 2 You probably want to link against the release libraries, and you can specify this when invoking \c 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 \c ldd tool (available on most Unices): \snippet snippets/code/doc_src_deployment.qdoc 3 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 \c 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 \l {Application Dependencies} section. The \l {tools/plugandpaint}{Plug & Paint} example consists of several components: The core application (\l {tools/plugandpaint}{Plug & Paint}), and the \l {tools/plugandpaintplugins/basictools}{Basic Tools} and \l {tools/plugandpaintplugins/extrafilters}{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. \section1 Shared Libraries We have two challenges when deploying the \l {tools/plugandpaint}{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. \section2 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 \c /path/to/Qt directory. \section2 Linking the Application to Qt as a Shared Library After ensuring that Qt is built as a shared library, we can build the \l {tools/plugandpaint}{Plug & Paint} application. First, we must go into the directory that contains the application: \snippet snippets/code/doc_src_deployment.qdoc 4 Now run qmake to create a new makefile for the application, and do a clean build to create the dynamically linked executable: \snippet snippets/code/doc_src_deployment.qdoc 5 This builds the core application, the following will build the plugins: \snippet snippets/code/doc_src_deployment.qdoc 6 If everything compiled and linked without any errors, we will get a \c plugandpaint executable and the \c libpnp_basictools.so and \c libpnp_extrafilters.so plugin files. \section2 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 \l {Qt Plugins}{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 \l {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: \list \li You can install the Qt libraries in one of the system library paths (e.g. \c /usr/lib on most systems). \li You can pass a predetermined path to the \c -rpath command-line option when linking the application. This will tell the dynamic linker to look in this directory when starting your application. \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 \c 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). \endlist 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 \c plugandpaint.sh script will look like this: \snippet snippets/code/doc_src_deployment.qdoc 7 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 \c plugins directory, or you can set the \c DESTDIR in the plugins' project files: \snippet snippets/code/doc_src_deployment.pro 8 An archive distributing all the Qt libraries, and all the plugins, required to run the \l {tools/plugandpaint}{Plug & Paint} application, would have to include the following files: \table 100% \header \li Component \li {2, 1} File Name \row \li The executable \li {2, 1} \c plugandpaint \row \li The script to run the executable \li {2, 1} \c plugandpaint.sh \row \li The Basic Tools plugin \li {2, 1} \c plugins\libpnp_basictools.so \row \li The ExtraFilters plugin \li {2, 1} \c plugins\libpnp_extrafilters.so \row \li The Qt xcb platform plugin \li {2, 1} \c platforms\libqxcb.so \row \li The Qt Core module \li {2, 1} \c libQt5Core.so.5 \row \li The Qt GUI module \li {2, 1} \c libQt5Gui.so.5 \row \li The Qt Widgets module \li {2, 1} \c libQt5Widgets.so.5 \endtable On most systems, the extension for shared libraries is \c .so. A notable exception is HP-UX, which uses \c .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 \l {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 \c plugandpaint.sh script. An alternative to putting the plugins in the \c plugins subdirectory is to add a custom search path when you start your application using QApplication::addLibraryPath() or QApplication::setLibraryPaths(). \snippet snippets/code/doc_src_deployment.cpp 9 \section1 Application Dependencies \section2 Additional Libraries To find out which libraries your application depends on, run the \c ldd tool (available on most Unices): \snippet snippets/code/doc_src_deployment.qdoc 10 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 \c 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. \c {./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 \c LIBS variable in your project file. \section2 Qt Plugins All Qt GUI applications require a plugin that implements the \l {Qt Platform Abstraction} (QPA) layer in Qt 5. For Linux/X11, the name of the platform plugin is \c {libqxcb.so}. This file must be located within a specific subdirectory (by default, \c 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 \c imageformats or \c 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 \c /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: \list \li \l{qt-conf.html}{Using \c qt.conf}. This is the recommended approach since it provides the most flexibility. \li Using QApplication::addLibraryPath() or QApplication::setLibraryPaths(). \li Using a third party installation utility or the target system's package manager to change the hard-coded paths in the QtCore library. \endlist The \l{How to Create Qt Plugins} document outlines the issues you need to pay attention to when building and deploying plugins for Qt applications. */ /*! \page linux-issues.html \title Qt for Linux/X11 - Specific Issues \brief A description of issues with Qt that are specific to Linux/X11. This page contains information about the X11 platforms Qt is currently known to run on, with links to platform-specific notes. \section1 Linux There are no known problems with using Qt on production versions of Linux/x86, Linux/ppc, Linux/amd64 and Linux/ia64 (including Altix(R)). For information about the specific compilers supported, visit the \l{Community Supported Platforms#Reference Configurations}{supported platforms} page. \section2 Installation problems Installing the source (\e{.tgz}) will likely conflict with the Qt version from your Linux distribution. This can result in link errors, such as: \snippet snippets/code/doc_src_platform-notes.qdoc 0 This is solved by removing the older version of the library. If you have problems installing open source versions of Qt provided by your Linux distribution, for example, from RPM or APT repositories, please consult the maintainers of the distribution. Some RPM versions have problems installing some of the Qt RPM archives where installation stops with an error message warning about a \gui{Failed Dependency}. Use the \c{--nodeps} option of \c rpm as workaround this problem. \section2 Intel C++ Compiler for Linux Qt can be compiled with the Intel C++ compile for Linux, though, this configuration is not tested on a regular basis. \section2 Known Issues with Intel C++ Compiler for Linux \list \li Precompiled header support does not work in version 10.0.025 and older. For these compilers, you should configure Qt with -no-pch. Precompiled header support works properly in version 10.0.026 and later. \li Version 10.0.026 for Intel 64 is known to miscompile qmake when building in release mode. For now, configure Qt with -debug. Version 10.1.008 and later can compile qmake in release mode. \li Versions 10.1.008 to 10.1.015 for both IA-32 and Intel 64 are known crash with "(0): internal error: 0_47021" when compiling \l{Qt XML Patterns} and \l{Qt Designer} in release mode. Version 10.1.017 compiles these modules correctly in release mode. \endlist */