qt-everywhere-src-5.14.1/qtdoc/doc/src/configure.qdoc - orbit - Git at Google

 /****************************************************************************
 **
 ** Copyright (C) 2019 The Qt Company Ltd.
 ** Contact: https://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 https://www.qt.io/terms-conditions. For further
 ** information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.html.
 ** $QT_END_LICENSE$
 **
 ****************************************************************************/

 /*!
     \page configure-options.html
     \title Qt Configure Options
     \brief Configuring Qt's compile options.

     \c configure is a command-line tool which determines how to build Qt for a
     particular platform. Configure can exclude a feature in Qt as well
     as determine how Qt builds and deploys applications onto host platforms.
     This page discusses some of the configure options, but for
     the full list of options, enter the command \c{configure -h}. Configure
     should be run from the main Qt source directory.

     Unless stated otherwise, the commands in this page are for the Linux
     platforms. On \macos and on Windows, the \c PATH and directory structure
     are different, therefore the commands will vary. Also, on Windows systems,
     the configure script is called \e configure.bat.

     After running \c configure, build the sources with the \c make tool
     belonging to the chosen toolchain.

     \section1 Source, Build, and Install Directories

     The \e source directory contains the source code that is obtained from
     the source package or git repository. The \e build directory is where the
     build-related files such as Makefiles, object files, and other intermediate
     files are stored. The \e install directory is where the binaries and
     libraries are installed, for use either by the system or by the
     application.

     It is recommended to keep these directories separate by shadow-building and
     using the \c -prefix option. This enables you to keep the Qt \e source tree
     clean from the build artifacts and binaries, which are stored in a separate
     directory. This method is very convenient if you want to have multiple
     builds from the same source tree, but for different configurations. To
     shadow-build, run \c configure from a separate directory:

     \badcode
     mkdir ~/qt-build
     cd ~/qt-build
     ~/qt-source/configure -prefix /opt/Qt5.9
     qmake
     \endcode

     Configuring with the \c -prefix option means that the Qt binaries and
     libraries are installed into another directory, which is \c /opt/Qt5.9 in
     this case. Running \c qmake generates the Makefiles in the \e ~/qt-build
     directory and not in the \e source directory. After the Makefiles are in
     place, run the following commands to build the Qt binaries and libraries,
     and install them:

     \badcode
     make
     make install
     \endcode

     \section1 Modules and Features

     Qt consists of different \l{All Modules}{modules} whose sources can be
     found in different directories inside the top-level source directory.
     Users can explicitly exclude specific top-level directories to limit build
     times. Furthermore, each Qt module might have features that can also be
     explicitly enabled or disabled.

     \section2 Excluding Qt Modules

     Configure's \c -skip option allows top-level source directories to be
     excluded from the Qt build. Note that many directories contain multiple Qt
     modules. For example, to exclude Qt NFC and Qt Bluetooth from the Qt build,
     provide \c{-skip qtconnectivity} as the argument to configure.

     \code
     ./configure -skip qtconnectivity
     \endcode

     \section2 Including or Excluding Features

     The \c{-feature-}\e{<feature>} and \c{-no-feature-}\e{<feature>} options
     include and exclude specific features, respectively.

     For example, to disable \l Accessibility, provide
     \c -no-feature-accessibility as the argument:
     \code
     ./configure -no-feature-accessibility
     \endcode

     Use \c{configure -list-features} to show a list of all available features
     on the command line. Note that features can depend on other features, so
     disabling a feature might have side-effects on other features.

     The \l{Qt Configuration Tool} that is part of \l{Qt for Device Creation}
     allows the tweaking of features and dependencies through a convenient user
     interface.

     \section1 Third-Party Libraries

     The Qt source packages include third-party libraries. To set whether Qt
     should use the system's versions of the libraries or to use the bundled
     version, pass either \c -system or \c -qt before the name of the library to
     configure.

     The table below summarizes the third-party options:
     \table
     \header
         \li Library Name
         \li Bundled in Qt
         \li Installed in System
     \row
         \li zlib
         \li \c -qt-zlib
         \li \c -system-zlib
     \row
         \li libjpeg
         \li \c -qt-libjpeg
         \li \c -system-libjpeg
     \row
         \li libpng
         \li \c -qt-libpng
         \li \c -system-libpng
     \row
         \li xcb
         \li \c -qt-xcb
         \li \c -system-xcb
     \row
         \li freetype
         \li \c -qt-freetype
         \li \c -system-freetype
     \row
         \li PCRE
         \li \c -qt-pcre
         \li \c -system-pcre
     \row
         \li HarfBuzz-NG
         \li \c -qt-harfbuzz
         \li \c -system-harfbuzz
     \endtable

     It is also possible to disable support for these libraries by using
     \c -no instead of \c{-qt}. For example, to use the system's xcb library
     and disable zlib support, enter the following:

     \code
     ./configure -no-zlib -qt-libjpeg -qt-libpng -system-xcb
     \endcode

     For a full list of options, consult the help with \c {configure -help}.

     \section1 Compiler Options

     The \c -platform option sets the host platform and the compiler for building
     the Qt sources. The list of supported platforms and compilers is found in
     the \l{Supported Platforms}{supported platforms} page while the
     full list is available in \e{qtbase/mkspecs} directory.

     For example, on Ubuntu Linux systems, Qt can be compiled by several
     compilers such as clang or g++:

     \code
     ./configure -platform linux-clang
     ./configure -platform linux-g++
     ./configure -platform linux-g++-32
     \endcode

     For \l{Qt for Windows}{Windows} machines, either MinGW or Visual Studio
     toolchains can be used to compile Qt.

     \code
     configure.bat -platform win32-g++
     configure.bat -platform win32-msvc
     \endcode

     Afterwards, the generated Makefiles will use the appropriate compiler
     commands.

     \section1 Cross-Compilation Options

     To configure Qt for cross-platform development and deployment, the
     development toolchain for the target platform needs to be set up. This
     set up varies among the \l{Supported Platforms}.

     Common options are:
     \list
     \li \c -xplatform - the target platform. Valid xplatform options are the same
     as the \c -platform options which are found in \e{qtbase/mkspecs}.
     \li \c -device - a specific device or chipsets. The list of devices that configure is compatible with are
     found in \e{qtbase/mkspecs/devices}. For more information, visit the \l{http://wiki.qt.io/Category:Devices}{Devices}
     Wiki page.
     \li \c -device-option - sets additional qmake variables. For example, \c{-device-option CROSS_COMPILE=}\e{<path-to-toolchain>} provides
     the environment variable, \c{CROSS_COMPILE}, as needed by certain devices.
     \endlist

     \note Toolchains for non-desktop targets often come with a so-called \e
     sysroot which Qt needs to be configured against.

     \section2 Specific Options for Platforms

     The following pages provide guidelines on how to configure Qt for specific
     platform development:
     \list
     \li \l{Building Qt 5 for Android} Wiki page
     \li \l{Qt for iOS - Building from Source}
     \li \l{Qt for UWP#Building from source}{Qt for UWP - Building from Source}
     \li \l{Configure an Embedded Linux Device}
     \li \l{http://wiki.qt.io/Qt_RaspberryPi}{Qt for Raspberry Pi} - a community-driven site for
     Raspberry devices
     \li \l{http://wiki.qt.io/Category:Devices}{Devices} - a list of other devices and chipsets
     \endlist

     \section1 OpenGL Options for Windows

     On Windows, Qt can be configured with the system OpenGL or with \l{ANGLE}.
     By default, Qt is configured to use dynamic OpenGL. This means that it tries
     to use system OpenGL and falls back to ANGLE, which is bundled with Qt and
     depends on the DirectX SDK, if native OpenGL does not work. ANGLE enables
     running Qt applications that depend on OpenGL, without installing the latest
     OpenGL drivers. If ANGLE also fails, Qt will fall back to software rendering,
     which is the slowest but most safe of the rendering methods.

     The \c -opengl option can be used to configure Qt to use
     the OpenGL in the target system, a different version of OpenGL ES (with or
     without ANGLE), or dynamically switch between the available OpenGL
     implementations.

     \code
     configure.bat -opengl dynamic
     \endcode

     With the \c dynamic option, Qt will try to use native OpenGL first. If that
     fails, it will fall back to ANGLE and finally to software rendering in case
     of ANGLE failing as well.

     \code
     configure.bat -opengl desktop
     \endcode

     With the \c desktop option, Qt uses the OpenGL installed on Windows,
     requiring that the OpenGL in the target Windows machine is compatible with
     the application. The \c -opengl option accepts two versions of OpenGL ES, \c
     es2 for OpenGL ES 2.0 or \c es1 for OpenGL ES Common Profile.

     \code
     configure.bat -opengl es2
     \endcode

     You can also use \c{-opengl dynamic}, which enable applications to
     dynamically switch between the available options at runtime. For more
     details about the benefits of using dynamic GL-switching, see
     \l{Graphics Drivers}.

     \section1 Developer Builds

     The \c -developer-build option is not meant for shipping applications,
     but can be used for developing Qt. Such a build contains more exported
     symbols than a standard build and compiles with a higher warning level.
 */
	/****************************************************************************
	**
	** Copyright (C) 2019 The Qt Company Ltd.
	** Contact: https://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 https://www.qt.io/terms-conditions. For further
	** information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.html.
	** $QT_END_LICENSE$
	**
	****************************************************************************/

	/*!
	\page configure-options.html
	\title Qt Configure Options
	\brief Configuring Qt's compile options.

	\c configure is a command-line tool which determines how to build Qt for a
	particular platform. Configure can exclude a feature in Qt as well
	as determine how Qt builds and deploys applications onto host platforms.
	This page discusses some of the configure options, but for
	the full list of options, enter the command \c{configure -h}. Configure
	should be run from the main Qt source directory.

	Unless stated otherwise, the commands in this page are for the Linux
	platforms. On \macos and on Windows, the \c PATH and directory structure
	are different, therefore the commands will vary. Also, on Windows systems,
	the configure script is called \e configure.bat.

	After running \c configure, build the sources with the \c make tool
	belonging to the chosen toolchain.

	\section1 Source, Build, and Install Directories

	The \e source directory contains the source code that is obtained from
	the source package or git repository. The \e build directory is where the
	build-related files such as Makefiles, object files, and other intermediate
	files are stored. The \e install directory is where the binaries and
	libraries are installed, for use either by the system or by the
	application.

	It is recommended to keep these directories separate by shadow-building and
	using the \c -prefix option. This enables you to keep the Qt \e source tree
	clean from the build artifacts and binaries, which are stored in a separate
	directory. This method is very convenient if you want to have multiple
	builds from the same source tree, but for different configurations. To
	shadow-build, run \c configure from a separate directory:

	\badcode
	mkdir ~/qt-build
	cd ~/qt-build
	~/qt-source/configure -prefix /opt/Qt5.9
	qmake
	\endcode

	Configuring with the \c -prefix option means that the Qt binaries and
	libraries are installed into another directory, which is \c /opt/Qt5.9 in
	this case. Running \c qmake generates the Makefiles in the \e ~/qt-build
	directory and not in the \e source directory. After the Makefiles are in
	place, run the following commands to build the Qt binaries and libraries,
	and install them:

	\badcode
	make
	make install
	\endcode

	\section1 Modules and Features

	Qt consists of different \l{All Modules}{modules} whose sources can be
	found in different directories inside the top-level source directory.
	Users can explicitly exclude specific top-level directories to limit build
	times. Furthermore, each Qt module might have features that can also be
	explicitly enabled or disabled.

	\section2 Excluding Qt Modules

	Configure's \c -skip option allows top-level source directories to be
	excluded from the Qt build. Note that many directories contain multiple Qt
	modules. For example, to exclude Qt NFC and Qt Bluetooth from the Qt build,
	provide \c{-skip qtconnectivity} as the argument to configure.

	\code
	./configure -skip qtconnectivity
	\endcode

	\section2 Including or Excluding Features

	The \c{-feature-}\e{<feature>} and \c{-no-feature-}\e{<feature>} options
	include and exclude specific features, respectively.

	For example, to disable \l Accessibility, provide
	\c -no-feature-accessibility as the argument:
	\code
	./configure -no-feature-accessibility
	\endcode

	Use \c{configure -list-features} to show a list of all available features
	on the command line. Note that features can depend on other features, so
	disabling a feature might have side-effects on other features.

	The \l{Qt Configuration Tool} that is part of \l{Qt for Device Creation}
	allows the tweaking of features and dependencies through a convenient user
	interface.

	\section1 Third-Party Libraries

	The Qt source packages include third-party libraries. To set whether Qt
	should use the system's versions of the libraries or to use the bundled
	version, pass either \c -system or \c -qt before the name of the library to
	configure.

	The table below summarizes the third-party options:
	\table
	\header
	\li Library Name
	\li Bundled in Qt
	\li Installed in System
	\row
	\li zlib
	\li \c -qt-zlib
	\li \c -system-zlib
	\row
	\li libjpeg
	\li \c -qt-libjpeg
	\li \c -system-libjpeg
	\row
	\li libpng
	\li \c -qt-libpng
	\li \c -system-libpng
	\row
	\li xcb
	\li \c -qt-xcb
	\li \c -system-xcb
	\row
	\li freetype
	\li \c -qt-freetype
	\li \c -system-freetype
	\row
	\li PCRE
	\li \c -qt-pcre
	\li \c -system-pcre
	\row
	\li HarfBuzz-NG
	\li \c -qt-harfbuzz
	\li \c -system-harfbuzz
	\endtable

	It is also possible to disable support for these libraries by using
	\c -no instead of \c{-qt}. For example, to use the system's xcb library
	and disable zlib support, enter the following:

	\code
	./configure -no-zlib -qt-libjpeg -qt-libpng -system-xcb
	\endcode

	For a full list of options, consult the help with \c {configure -help}.

	\section1 Compiler Options

	The \c -platform option sets the host platform and the compiler for building
	the Qt sources. The list of supported platforms and compilers is found in
	the \l{Supported Platforms}{supported platforms} page while the
	full list is available in \e{qtbase/mkspecs} directory.

	For example, on Ubuntu Linux systems, Qt can be compiled by several
	compilers such as clang or g++:

	\code
	./configure -platform linux-clang
	./configure -platform linux-g++
	./configure -platform linux-g++-32
	\endcode

	For \l{Qt for Windows}{Windows} machines, either MinGW or Visual Studio
	toolchains can be used to compile Qt.

	\code
	configure.bat -platform win32-g++
	configure.bat -platform win32-msvc
	\endcode

	Afterwards, the generated Makefiles will use the appropriate compiler
	commands.

	\section1 Cross-Compilation Options

	To configure Qt for cross-platform development and deployment, the
	development toolchain for the target platform needs to be set up. This
	set up varies among the \l{Supported Platforms}.

	Common options are:
	\list
	\li \c -xplatform - the target platform. Valid xplatform options are the same
	as the \c -platform options which are found in \e{qtbase/mkspecs}.
	\li \c -device - a specific device or chipsets. The list of devices that configure is compatible with are
	found in \e{qtbase/mkspecs/devices}. For more information, visit the \l{http://wiki.qt.io/Category:Devices}{Devices}
	Wiki page.
	\li \c -device-option - sets additional qmake variables. For example, \c{-device-option CROSS_COMPILE=}\e{<path-to-toolchain>} provides
	the environment variable, \c{CROSS_COMPILE}, as needed by certain devices.
	\endlist

	\note Toolchains for non-desktop targets often come with a so-called \e
	sysroot which Qt needs to be configured against.

	\section2 Specific Options for Platforms

	The following pages provide guidelines on how to configure Qt for specific
	platform development:
	\list
	\li \l{Building Qt 5 for Android} Wiki page
	\li \l{Qt for iOS - Building from Source}
	\li \l{Qt for UWP#Building from source}{Qt for UWP - Building from Source}
	\li \l{Configure an Embedded Linux Device}
	\li \l{http://wiki.qt.io/Qt_RaspberryPi}{Qt for Raspberry Pi} - a community-driven site for
	Raspberry devices
	\li \l{http://wiki.qt.io/Category:Devices}{Devices} - a list of other devices and chipsets
	\endlist

	\section1 OpenGL Options for Windows

	On Windows, Qt can be configured with the system OpenGL or with \l{ANGLE}.
	By default, Qt is configured to use dynamic OpenGL. This means that it tries
	to use system OpenGL and falls back to ANGLE, which is bundled with Qt and
	depends on the DirectX SDK, if native OpenGL does not work. ANGLE enables
	running Qt applications that depend on OpenGL, without installing the latest
	OpenGL drivers. If ANGLE also fails, Qt will fall back to software rendering,
	which is the slowest but most safe of the rendering methods.

	The \c -opengl option can be used to configure Qt to use
	the OpenGL in the target system, a different version of OpenGL ES (with or
	without ANGLE), or dynamically switch between the available OpenGL
	implementations.

	\code
	configure.bat -opengl dynamic
	\endcode

	With the \c dynamic option, Qt will try to use native OpenGL first. If that
	fails, it will fall back to ANGLE and finally to software rendering in case
	of ANGLE failing as well.

	\code
	configure.bat -opengl desktop
	\endcode

	With the \c desktop option, Qt uses the OpenGL installed on Windows,
	requiring that the OpenGL in the target Windows machine is compatible with
	the application. The \c -opengl option accepts two versions of OpenGL ES, \c
	es2 for OpenGL ES 2.0 or \c es1 for OpenGL ES Common Profile.

	\code
	configure.bat -opengl es2
	\endcode

	You can also use \c{-opengl dynamic}, which enable applications to
	dynamically switch between the available options at runtime. For more
	details about the benefits of using dynamic GL-switching, see
	\l{Graphics Drivers}.

	\section1 Developer Builds

	The \c -developer-build option is not meant for shipping applications,
	but can be used for developing Qt. Such a build contains more exported
	symbols than a standard build and compiles with a higher warning level.
	*/