Revision control
Copy as Markdown
// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page linux.html
\title Qt for Linux
\brief Qt natively supports Linux.
\ingroup supportedplatform
\keyword Qt for Linux/X11
Qt's support for different Linux platforms is extensive and mature.
To download and install Qt for Linux, follow the instructions on the
\l{Getting Started with Qt} page. You can also install Qt using your
distribution's package manager; see
\l{Qt for Linux - Alternative ways of installing Qt}{Alternative ways of installing Qt for Linux}
for more information.
\target linux-supported-configurations
\section1 Supported Configurations
The following configurations are supported.
\include supported-platforms.qdocinc linux
\section1 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
\l {Qt for Linux - Requirements}, and 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 Supported Glibc Versions
The Qt installer and Qt Framework components and tools are built
against a specific glibc version, and cannot be run on a system
with an older glibc version.
\table
\header
\li Qt release
\li Required glibc version
\row
\li \b{Qt 6.8}+
\li glibc 2.28+
\row
\li \b{Qt 6.10}+
\li glibc 2.34+
\endtable
\note If you build Qt from source, there is no limitation for the
glibc version.
\section1 Building Qt from Source
You can also build Qt from the source package and configure it according
to your target platform. The source packages are obtained from
Below, you will find more information about building Qt from source.
\list
\li \l {Qt for Linux - Requirements}
\li \l{Qt for Linux - 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 - Deployment}
\li \l{Qt for Linux - 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{All 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
\endlist
a wiki, a forum, and additional learning guides and presentations.
*/
/*!
\page linux-requirements.html
\title Qt for Linux - Requirements
\keyword {Qt for X11 Requirements}
\brief Setting up the Linux 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.
\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 \c{-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
\li 1.11
\row {id="OptionalColor"}
\li xcb-render-util
\li libxcb-render-util
\li Utility library for XCB for Render extension
\li auto-detected
\li 0.3.9
\row {id="OptionalColor"}
\li xcb-shape
\li libxcb-shape
\li X C Bindings for Shape extension
\li auto-detected
\li 1.11
\row {id="DefaultColor"}
\li xcb-randr
\li libxcb-randr
\li X C Bindings for Resize and Rotate Extension
\li auto-detected
\li 1.11
\row {id="DefaultColor"}
\li xcb-xfixes
\li libxcb-xfixes
\li X C Bindings for Fixes Extension
\li auto-detected
\li 1.11
\row {id="DefaultColor"}
\li xcb-xkb
\li libxcb-xkb
\li X C Bindings for XKeyboard Extension
\li auto-detected
\li 1.11
\row {id="DefaultColor"}
\li xcb-sync
\li libxcb-sync
\li X C Bindings for Sync Extension
\li auto-detected
\li 1.11
\row {id="DefaultColor"}
\li xcb-shm
\li libxcb-shm
\li X C Bindings for Shared Memory Extension
\li auto-detected
\li 1.11
\row {id="DefaultColor"}
\li xcb-icccm
\li libxcb-icccm
\li X C Bindings for ICCCM Protocol
\li auto-detected
\li 0.3.9
\row {id="DefaultColor"}
\li xcb-keysyms
\li libxcb-keysyms
\li Utility library for XCB for keycode conversion
\li auto-detected
\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
\li 0.3.9
\row {id="DefaultColor"}
\li xcb-util
\li libxcb-util
\li Utility library for XCB for atom, aux and event
\li auto-detected
\li 0.3.9
\row {id="DefaultColor"}
\li xcb-cursor0
\li libxcb-cursor0
\li Utility library for XCB for cursor
\li auto-detected
\li 0.1.1
\row {id="OptionalColor"}
\li xkbcommon
\li libxkbcommon
\li Keymap handling
\li \c{-xkbcommon} or auto-detected
\li 0.9.0
\row {id="OptionalColor"}
\li xkbcommon-x11
\li libxkbcommon-x11
\li Keymap handling
\li auto-detected
\li 0.9.0
\row {id="OptionalColor"}
\li Fontconfig
\li libfontconfig
\li Font customization and configuration
\li \c{-fontconfig} or auto-detected
\li 2.6
\row {id="OptionalColor"}
\li FreeType
\li libfreetype
\li Font engine
\li
\li 2.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.11
\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 \c{-sm} or auto-detected
\li 6.0.4
\row {id="SMColor"}
\li ICE
\li libICE
\li Inter-Client Exchange
\li \c{-sm} or auto-detected
\li 6.3.5
\row {id="GlibColor"}
\li glib
\li libglib-2.0
\li Common event loop handling
\li \c{-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 the above libraries contain header files that are
used when building Qt from its source code. The package names may differ
among Linux distributions, and some distributions may not include all
packages in the default configuration for their package management system.
As an example, you can run the following command to install the recommended
packages on Debian-based GNU/Linux systems:
\badcode
apt install \
libfontconfig1-dev \
libfreetype-dev \
libgtk-3-dev \
libx11-dev \
libx11-xcb-dev \
libxcb-cursor-dev \
libxcb-glx0-dev \
libxcb-icccm4-dev \
libxcb-image0-dev \
libxcb-keysyms1-dev \
libxcb-randr0-dev \
libxcb-render-util0-dev \
libxcb-shape0-dev \
libxcb-shm0-dev \
libxcb-sync-dev \
libxcb-util-dev \
libxcb-xfixes0-dev \
libxcb-xkb-dev \
libxcb1-dev \
libxext-dev \
libxfixes-dev \
libxi-dev \
libxkbcommon-dev \
libxkbcommon-x11-dev \
libxrender-dev
\endcode
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.
Qt does not maintain a comprehensive package list for all distributions.
Some distributions, such as \tm{Red Hat} and its derivatives, may require
additional repositories for certain packages (e.g., EPEL for RHEL).
Consult your distribution's documentation for specific package names. RHEL
users can contact \tm{Red Hat} support for detailed information.
\section1 Accessibility Dependencies
The Qt accessibility implementation uses the \e{Assistive Technology
Service Provider Interface} (AT-SPI). Besides DBUS, the development
package \c{libatspi2.0-dev} must be installed.
\section1 OpenGL Dependencies
Configure attempts to automatically detect OpenGL ES 2.0, or later, or
regular desktop OpenGL. You can disable OpenGL support by using the
\c -no-opengl option.
\note The Qt OpenGL module (which contains classes that start with \e QGL)
has been deprecated in favor of the \l{Qt GUI} module (which contains
classes that start with \e QOpenGL).
\omit
\section1 Speech Dependencies
\l{Qt Speech} depends on Speech Dispatcher (libspeechd) on the Linux platform.
The following development packages should be installed:
\list
\li flite1-dev
\li libspeechd-dev
\li speech-dispatcher
\endlist
\endomit
\section1 QDoc Dependencies
\l{QDoc Manual}{QDoc} uses Clang to parse C++ code.
If you wish to build QDoc manually, refer to \l {Installing Clang for QDoc}
for specific build requirements.
*/
/*!
\page linux-building.html
\title Qt for Linux - Building from Source
\keyword {Qt for Linux/X11 - Building from Source}
\brief How to configure and build Qt on Linux/X11 platforms.
This page describes configuring and building \l{Qt for Linux} from
sources. Note that it is typically easier to install the pre-built Qt
libraries and tools via \l [QtDoc] {Get and Install Qt}
{\QOI}. A lot of Linux distributions also provide Qt packages
through their package manager. Build Qt from sources, however, if you want
to customize Qt further or are using a distribution for which no binary Qt
packages (in the right version) are available.
Distribution packagers can find further information on how to package Qt in
the \l{Qt Packaging Recommendations}{packaging recommendations}.
\section1 Step 1: Getting the Sources
Qt sources can be installed in \QOI. Source packages are also
available \l{Getting Qt Sources from the Git repository}{through Git}, as
archives in the \l{Qt Account} (commercial users), and on
(open-source users).
If you install the sources through \QOI, they will
be available in the Qt installation directory, for example
\tt{$HOME/Qt/\QtVersion/Src}.
If you downloaded the single source archive, extract it to a directory of
your choice:
\include snippets/code/doc_src_installation.qdoc 11
\section1 Step 2: Install Build Requirements
Building Qt requires a build environment with tools, compilers, and
development packages.
\section2 Build Tools
\table 80%
\header \li Tool \li Supported Versions
\row
\li CMake
\li Version 3.25 and newer.
\row
\li \notranslate Ninja
\li -
\row
\li Python
\li Version 3
\endtable
\include use-ninja-note.qdocinc ninja-note
\section2 Compilers & Development Packages
The following compilers and configurations are supported in Qt \QtVer:
\include supported-platforms.qdocinc linux
Other compilers and configurations might work but are not actively tested.
Qt also relies on the availability of various libraries and development
packages, which are typically installed by the package manager of the
respective resolution. See \l{Qt for Linux - Requirements} for the details.
\section1 Step 3: Build the Qt Libraries and Tools
To configure your build, create a build directory and run the
\c{./configure} script in this directory:
\include snippets/code/doc_src_installation.qdoc 12
By default, Qt is configured for installation in the
\tt{/usr/local/Qt-\QtVersion} directory. This can be changed by using the
\c{-prefix} option. See the list of \l{Qt Configure Options}{configure options}
to tweak further.
Did \c{configure} run successfully? Then proceed with building the libraries
and tools:
\badcode
cmake --build . --parallel
\endcode
After building, you need to install the libraries and tools in the
appropriate place (unless you enabled a
\l{Developer Builds}{developer build}):
\badcode
cmake --install .
\endcode
Note that this might require root access.
\section1 Step 4: Building Your Application
After Qt is installed, you can start building applications with it.
If you work from the command line, consider adding the Qt tools to your
default \c PATH. This is done as follows:
In \c{.profile} (if your shell is bash, ksh, zsh or sh), add the
following lines:
\badcode \QtVersion
PATH=/usr/local/Qt-\1/bin:$PATH
export PATH
\endcode
In \c{.login} (if your shell is csh or tcsh), add the following line:
\badcode \QtVersion
setenv PATH /usr/local/Qt-\1/bin:$PATH
\endcode
If you plan to build your application from an IDE, you need to register
the Qt version explicitly there:
\list
\li For \QC, see \l{\QC: Add Qt versions}.
\li For \QVSC, see \l{\QVSC: Register Qt installations}.
\endlist
*/
/*!
\page linux-deployment.html
\title Qt for Linux - Deployment
\keyword {Qt for Linux/X11 - Deployment}
\brief Deployment of Qt applications on Linux.
This documentation discusses specific deployment issues for
\l{Qt for Linux}. We will demonstrate the procedures in terms of deploying
the \l{tools/plugandpaint/app}{Plug & Paint} example application that comes
with the Qt source package.
Due to the proliferation of Unix systems (such as commercial Unixes or Linux
distributions), 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 Shared Libraries
We have two challenges when deploying the \c plugandpaint 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 \c plugandpaint 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}{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 (for example, \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 (for example, 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 \c plugandpaint 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 libQt6Core.so.6
\row
\li The Qt GUI module
\li {2, 1} \c libQt6Gui.so.6
\row
\li The Qt Widgets module
\li {2, 1} \c libQt6Widgets.so.6
\row
\li The Qt XCB QPA library, required by the xcb platform plugin
\li {2, 1} \c libQt6XcbQpa.so.6
\row
\li The Qt D-Bus module, required by Qt GUI when Qt is built with
D-Bus support, which is the default on Linux
\li {2, 1} \c libQt6DBus.so.6
\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}{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, that is, 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 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 building a _static_ version
of the Qt libraries. Follow the steps in
\l{Qt for Linux - Building from Source}, but remember to add
a \c{-static} argument to configure:
\include snippets/code/doc_src_deployment.qdoc 0
\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 Unixes):
\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}{Application Dependencies} section.
The \l {tools/plugandpaint/app}{Plug & Paint} example consists of
several components: The core application (\l
{tools/plugandpaint/app}{Plug & Paint}), and the \l
{tools/plugandpaint/plugins/basictools}{Basic Tools} and \l
{tools/plugandpaint/plugins/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 Application Dependencies
\section2 Additional Libraries
To find out which libraries your application depends on, run the
\c ldd tool (available on most Unixes):
\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.
Qt loads plugins at runtime, so \c ldd doesn't list the libraries that
plugins depend on. Run \c ldd on each plugin you deploy as well, such as
\c platforms/libqxcb.so, and redistribute the Qt libraries it lists.
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 (for example, \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. 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.
\section1 Walkthrough: Create a DEB Package
This section describes how to create a DEB package for your Qt application
on Linux using CMake deployment API available in Qt 6.5 or newer. There's
no dedicated \c linuxdeployqt tool. The current solution only relies on
CMake's built-in functionality.
\section2 Example Project Setup
Start with a simple CMake project:
\badcode
cmake_minimum_required(VERSION 3.22)
project(MyApp)
find_package(Qt6 REQUIRED COMPONENTS Widgets)
qt_standard_project_setup()
qt_add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE Qt::Widgets)
\endcode
\section2 Step 1: Prepare the Installation
Add commands for installing the application and generating a deployment
script to create a self-contained directory:
\badcode
# Install the executable to "${CMAKE_INSTALL_PREFIX}/bin".
install(TARGETS MyApp
BUNDLE DESTINATION .
RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)
# Generate the deployment script for MyApp.
qt_generate_deploy_app_script(
TARGET MyApp
FILENAME_VARIABLE deploy_script
NO_UNSUPPORTED_PLATFORM_ERROR
)
# Run the deployment script during installation (on "cmake --install").
install(SCRIPT ${deploy_script})
\endcode
Build and install the project:
\badcode
qt-cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/tmp/my-application ..
cmake --build .
cmake --install .
\endcode
The deployment script:
\list
\li Creates a qt.conf file next to the executable that contains information
about the directory layout. This is needed at runtime to find the
plugins and assets. See the qt.conf documentation for details.
\li Inspects the executable and used Qt plugins with CMake's built-in file
(GET_RUNTIME_DEPENDENCIES) to determine which Qt libraries to deploy.
\li Installs the necessary Qt plugins and Qt libraries.
\endlist
The installation directory can now be copied to a different machine, and
the application should still work.
\section2 Step 2: Create the DEB Package
After installation, package the directory using CPack. Add the following to
your CMake project:
\badcode
set(CPACK_PACKAGE_NAME my-app)
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "My amazing application")
set(CPACK_PACKAGE_VENDOR "My Company")
set(CPACK_PACKAGE_INSTALL_DIRECTORY ${CPACK_PACKAGE_NAME})
set(CPACK_VERBATIM_VARIABLES ON)
set(CPACK_PACKAGING_INSTALL_PREFIX "/opt/myapp")
set(CPACK_DEBIAN_PACKAGE_MAINTAINER "Package Maintainer <maintainer@example.com>")
set(CPACK_DEBIAN_PACKAGE_DEPENDS libc6 libstdc++6 libgcc-s1)
include(CPack)
\endcode
Reconfigure the project, navigate to the build directory (it must contain
the \c CPackConfig.cmake file), and run CPack to generate the DEB package:
\badcode
cpack -G DEB
\endcode
To inspect the contents of the package:
\badcode
dpkg -c my_app-1.0-Linux.deb
\endcode
To install the package:
\badcode
sudo dpkg -i my_app-1.0-Linux.deb
\endcode
*/
/*!
\page linux-issues.html
\title Qt for Linux - Specific Issues
\keyword {Qt for Linux/X11 - Specific Issues}
\brief A description of issues with Qt that are specific to Linux.
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 Linux. For information
about the specific compilers and distributions supported, visit the
\l{Supported Platforms}{supported platforms} page.
*/
/*!
\page linux-alternative-installers.html
\title Qt for Linux - Alternative ways of installing Qt
\brief This article explains how to install Qt on Linux using \QOI, distribution
packages, and Flatpak.
\section1 Overview
You can install Qt Framework as well as design and development tools on Linux
from these sources:
\list
\li \l{Get and Install Qt with \QOI}{\QOI} (Recommended).
\list
\li Gives you access to latest versions of Qt, on the day of their release.
\li Allows you to install older versions of Qt, in parallel to newer ones.
\li Features all Qt modules, including ones that are commercial-only.
\li Preconfigures Qt versions in \QC and \QDS.
\endlist
\QOI is full-featured, flexible, and fully supports commercial use cases,
including shipping distribution-independent builds of your application. It
is also the one supported best by The Qt Company and The Qt Project. We
recommend it if you plan to develop with Qt.
\li Native package managers.
\list
\li Do not require a Qt Account.
\li Typically ship a recent version of Qt 6 (though not always the latest one).
\li Qt libraries and tools use third-party modules from the package manager,
instead of bundled ones.
\li May miss some of the Qt modules (especially commercial-only ones) and
tools.
\li May require additional configuration after installation.
\endlist
You can install Qt Framework, \QDS, and \QC using:
\list
\li Distribution's package manager (for Qt Framework and \QC).
\li Flatpak (for \QDS and \QC).
\endlist
Installing Qt Framework from native package managers is lightweight and easy
to automate. It relieves you from selecting and maintaining a particular Qt
version, at the expense of flexibility and control. It works best if you
need to install Qt only as a dependency for a local application, or plan to
make your application available via the native package manager.
\endlist
\section1 Installing Qt and \QC using your distribution's package manager
Many Linux distributions provide Qt packages and \QC through their package
managers.
\section2 Installing Qt on Ubuntu and Debian-based systems
Use the following commands to find and install the packages required for
building Qt applications on Debian-based systems:
\list
\li To see available packages:
\badcode
apt list qt6-*dev*
\endcode
\li To install specific dev packages, for example, \c qtbase and
\c qtdeclarative:
\badcode
sudo apt install qt6-{base,declarative}-dev
\endcode
\li To install all the available dev packages with the documentation, build
tools, and \QC:
\badcode
sudo apt install qt6-*{dev,doc}* qtcreator cmake clazy g++
\endcode
\endlist
See also: \l{Enterprise Qt Debian Packages}
\section2 Installing Qt on Fedora-based systems
Use the following commands to find and install the packages required for
building Qt applications on Fedora-based systems:
\list
\li To see available packages:
\badcode
dnf repoquery qt6-*devel*
\endcode
\li To install specific dev packages, for example, \c qtbase and
\c qtdeclarative:
\badcode
sudo dnf install qt6-{qtbase,qtdeclarative}*devel*
\endcode
\li To install all the available dev packages with the documentation, build
tools, and \QC:
\badcode
sudo dnf install qt6-*{devel,doc}* qt-creator
\endcode
\endlist
\section2 Installing Qt on openSUSE-based systems
Use the following commands to find and install the packages required for
building Qt applications on openSUSE-based systems:
\list
\li To see available packages:
\badcode
zypper se qt6*devel*
\endcode
\li To install specific devel packages, for example, \c base and \c declarative:
\badcode
sudo zypper in qt6-{base,declarative}*devel
\endcode
\li To install all the available devel packages with the documentation, and \QC:
\badcode
sudo zypper in qt6*{devel,docs,creator}*
\endcode
\endlist
\section1 Installing \QC and \QDS using Flatpak
You can install \QC and \QDS as Flatpak applications from the Flathub
repository:
\list
\endlist
Refer to your distribution documentation for instructions on how to install
Flatpak applications on your system.
\section1 Additional configuration
After installing Qt Framework and \QC from your distribution's package manager,
you may need to configure your development environment. For example, you may
want to create and configure Qt versions and kits in \QC.
Refer to the \l{\QC: Configuring \QC} page for details.
*/