Qt配置选项

Qt Configure Options

Qt配置选项

configure is a command-line tool that supports you in building a custom version of Qt from source. It's part of the main Qt source directory.

configure是一个命令行工具，支持从源代码构建Qt的自定义版本。它是Qt源代码主目录的一部分。

Since Qt 6, configure is a wrapper around cmake. CMake can also be invoked directly. configure provides additional error checking and compatibility with Qt 5.

从Qt 6开始，configure就是cmake的包装器。CMake也可以直接调用。configure提供了额外的错误检查和与Qt 5的兼容性。

This page discusses some of the configure options. For the full list of options, enter the command configure -h.

本页讨论了一些配置选项。有关选项的完整列表，请输入命令configure -h。

Note: Unless stated otherwise, the commands on this page are for the Linux platforms. On macOS and Windows, the PATH and directory structure are different, therefore the commands will vary. Also, on Windows systems, the configure script is called configure.bat.

注意：除非另有说明，否则此页面上的命令适用于Linux平台。在macOS和Windows上，PATH和目录结构不同，因此命令也会有所不同。此外，在Windows系统上，配置脚本称为configure.bat。

Configure Workflow

配置工作流

configure must be called in a working build environment where CMake, compilers, and required build tools are readily available. Building Qt Sources lists such dependencies per platform.

​必须在CMake、编译器和所需构建工具随时可用的工作构建环境中调用configure。构建Qt源代码列出了每个平台的依赖关系。

After setting up such an environment, the typical workflow is to create a separate build directory, and then first run configure, then build Qt, and then install Qt:

设置好这样的环境后，典型的工作流程是创建一个单独的构建目录，然后首先运行configure，然后构建Qt，然后安装Qt：

~/qt-source/configure
cmake --build . --parallel
cmake --install .

You might want to experiment with different configure flags, and therefore run configure multiple times. Note that CMake caches configure options and information about the environment in a file called CMakeCache.txt. Delete this file when you want to start over without cached information.

可能希望尝试不同的配置标志，因此需要多次运行configure。请注意，CMake缓存在名为CMakeCache.txt的文件中配置有关环境的选项和信息。当想在没有缓存信息的情况下重新开始时，请删除此文件。

Source, Build, and Install Directories

源、构建和安装目录

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

source目录包含从源代码包或git存储库获得的源代码。build目录是存储构建相关文件（如构建系统文件、目标文件和其他中间文件）的地方。install目录是安装二进制文件和库的位置，供系统或应用程序使用。

It's recommended to keep these directories separate by shadow-building and using the -prefix option. This enables you to keep the Qt 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 configure from a separate directory:

建议通过阴影构建和使用-prefix选项将这些目录分开。这使能够使Qt源代码树与存储在单独目录中的构建工件和二进制文件保持干净。如果想从同一个源代码树中生成多个版本，但针对不同的配置，这种方法非常方便。要进行影子构建，请从单独的目录运行configure：

mkdir ~/qt-build
cd ~/qt-build
~/qt-source/configure -prefix /opt/Qt6

Configuring with the -prefix option means that the Qt binaries and libraries are installed into another directory, which is /opt/Qt6 in this case.

使用-prefix选项进行配置意味着Qt二进制文件和库被安装到另一个目录中，在本例中为/opt/Qt6。

Examples, Tests, and Tools

示例、测试和工具

By default, configure only configures Qt's libraries and tools. You can use -make examples or -make tests to also build the examples or tests that come with Qt:

默认情况下，configure只配置Qt的库和工具。可以使用-make-examples或-make-tests来构建Qt附带的示例或测试：

~/qt-source/configure -make examples -make tests

You can also configure Qt such that examples, tests, and tools are configured, but not built by default. If you set the CMake variables QT_BUILD_EXAMPLES_BY_DEFAULT, QT_BUILD_TESTS_BY_DEFAULT, and QT_BUILD_TOOLS_BY_DEFAULT to OFF, the respective parts will not be built by cmake --build .. Instead, CMake will generate individual targets that you can then build individually.

还可以配置Qt，以便配置示例、测试和工具，但默认情况下不会构建。如果将CMake变量QT_BUILD_EXAMPLES_BY_DEFAULT、QT_BUILD_TESTS_BY_DEFAULT和QT_BUILED_TOOLS_BY_DEFOULT设置为OFF，则cmake --build .将不会构建相应的部分。。相反，CMake将生成单独的目标，然后可以单独构建。

Here we build Qt libraries and tools, but also the NotePad Example:

​在这里，我们构建Qt库和工具，以及NotePad示例：

~/qt-source/configure -make examples -- -D QT_BUILD_EXAMPLES_BY_DEFAULT=OFF
cmake --build . --parallel
cmake --build . --parallel --target notepad

Note: The -developer-build option builds tests by default. See also Developer Builds below.

​注意：默认情况下，-developer-build选项用于构建测试。另请参阅下面的开发人员构建。

Build Configurations

生成配置

You can build Qt libraries and tools in various variants, each of them optimized for a different use case.

可以构建各种变体的Qt库和工具，每种变体都针对不同的用例进行了优化。

Debug and Release Builds

调试和发布构建

-release tells the compiler to optimize the code, and not provide additional debug symbols alongside Qt and its tools.

-release告诉编译器要优化代码，不要在Qt及其工具的同时提供额外的调试符号。

-debug skips some optimizations to make it easier to debug Qt and its tools. This option also enables the generation of debug symbols that let you inspect the code and state of the built libraries in a debugger.

-debug跳过了一些优化，以便更容易调试Qt及其工具。此选项还允许生成调试符号，以便在调试器中检查代码和内置库的状态。

Finally, -debug-and-release lets you build both a debug and release variant of Qt libraries in one go. This is only supported if you configure a build for Windows.

最后，-debug and release允许一次性构建Qt库的调试和发布变体。仅当为Windows配置内部版本时，才支持此功能。

There are further options to tweak the configurations:

还有其他选项可以调整配置：

• -force-debug-info: Creates a release build with debug information.
• -force-debug-info：使用调试信息创建release版本。
• -separate-debug-info: Extracts the debug information into a separate file.
• -separate-debug-info：将调试信息提取到单独的文件中。
• -optimize-size: Optimizes release builds for size instead of speed.
• -optimize-size：根据大小而不是速度优化发布版本。

Static and Shared Builds

静态和共享构建

Qt Modules can be built as separate libraries that an executable links to and loads at start time (for Qt libraries), or runtime (for Qt plugins). This is called a shared build and is the default configuration on most platforms. The matching configure option is -shared.

Qt模块可以构建为单独的库，可执行文件可以在启动时（对于Qt库）或运行时（对于Qt插件）链接并加载这些库。这被称为共享构建，是大多数平台上的默认配置。匹配的配置选项是-shared。

You can also build Qt such that an executable binary will include all Qt modules it links to and all Qt plugins it needs. This is called a static build and can be selected when configuring with the -static option.

还可以构建Qt，使可执行二进制文件包含它链接到的所有Qt模块和它需要的所有Qt插件。这被称为静态构建，可以在配置时使用-static选项进行选择。

CMake Generators

CMake生成器

When configuring, you can select a CMake generator. Note that CMake supports generators that cannot be used with Qt. Therefore, configure automatically selects a generator for you.

配置时，可以选择CMake生成器。请注意，CMake支持不能与Qt一起使用的生成器。因此，configure会自动选择一个生成器。

configure always uses the Ninja generator and build tool if a ninja executable is available. Ninja is both cross-platform, feature-rich, and performant, and recommended on all platforms. Use of other generators might work, but is not officially supported.

如果Ninja 可执行文件可用，configure始终使用Ninja生成器和构建工具。Ninja是跨平台的、功能丰富的、高性能的，建议在所有平台上使用。使用其他生成器可能有效，但不受官方支持。

Modules and Features

模块和功能

The Qt source code is organized in several top-level directories called submodules, for example, qtbase, qtdeclarative or qtmultimedia. Inside these submodules, you find the source code for the different Qt Modules. Qt Core, Qt Quick, and Qt Multimedia are examples of such Qt modules.

​Qt源代码被组织在几个称为子模块的顶级目录中，例如qtbase、qtdeclarative或qtmultimedia。在这些子模块中，可以找到不同Qt模块的源代码。Qt Core、Qt Quick和Qt多媒体就是这样的Qt模块的例子。

Note: Many submodules (top-level source directories) have the same name as the Qt Modules they implement, but this is not always the case. For instance, qtdeclarative contains Qt Quick and Qt Qml, and various related modules. Consult the README.md file in the respective directories to get an overview.

​注意：许多子模块（顶级源代码目录）与它们实现的Qt模块同名，但情况并非总是如此。例如，qtdeclarative包含Qt Quick和Qt Qml以及各种相关模块。请查阅相应目录中的README.md文件以获取概述。

Submodules can be explicitly included or excluded to limit build times. Furthermore, each Qt module might have features that can also be explicitly enabled or disabled.

可以显式包含或排除子模块以限制构建时间。此外，每个Qt模块可能都有可以显式启用或禁用的功能。

Including and Excluding Qt Submodules

包括和不包括Qt子模块

configure's -skip option is used to exclude submodules (top-level source directories) from the Qt build. Excluding a submodule excludes all Qt Modules inside that submodule. The qtwayland submodule contains both the Qt Wayland Compositor and the Qt Wayland QPA plugin. Specifying -skip qtwayland as a configure option will therefore exclude both Qt Modules.

​configure的-skip选项用于从Qt构建中排除子模块（顶级源目录）。排除子模块会排除该子模块内的所有Qt模块。qtwayland子模块包含Qt Wayland合成器和Qt Wayland QPA插件。因此，将-skip qtwayland指定为配置选项将排除这两个Qt模块。

~/qt-source/configure -skip qtwayland

configure's -submodules option can be used to configure a build that only builds the listed submodules and their dependencies. For example, by specifying the qtmultimedia submodule, Qt Multimedia and all its dependencies will be included in the build. Multiple submodules can be separated by commas.

​configure的-submoduls选项可用于配置仅构建所列子模块及其依赖关系的构建。例如，通过指定qtmultimedia子模块，Qt Multimedia及其所有依赖项都将包含在构建中。多个子模块可以用逗号分隔。

~/qt-source/configure -submodules qtmultimedia,qtactiveqt

Including or Excluding Features

包含或排除功能

The -feature-<feature> and -no-feature-<feature> options include and exclude specific features, respectively.

-feature-<feature>和-no feature-<feature>选项分别包含和排除特定功能。

For example, you can use the -no-feature-accessibility configure option to disable Accessibility support in Qt:

​例如，可以使用-no-feature辅助功能配置选项来禁用Qt中的辅助功能支持：

~/qt-source/configure -no-feature-accessibility

Use 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.

使用configure-list功能在命令行上显示所有可用功能的列表。请注意，功能可能依赖于其他功能，因此禁用功能可能会对其他功能产生副作用。

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 -system or -qt before the name of the library to configure.

Qt源代码包包括第三方库。要设置Qt是应该使用系统版本的库还是使用捆绑版本，请在要配置的库名称前传递-system或-qt。

The table below summarizes some third-party options:

下表总结了一些第三方选项：

Library Name	Bundled in Qt	Installed in System
zlib	-qt-zlib	-system-zlib
libjpeg	-qt-libjpeg	-system-libjpeg
libpng	-qt-libpng	-system-libpng
freetype	-qt-freetype	-system-freetype
PCRE	-qt-pcre	-system-pcre
HarfBuzz-NG	-qt-harfbuzz	-system-harfbuzz

It's also possible to disable support for most of these libraries by using -no instead of -qt.

也可以通过使用-no代替-qt来禁用对大多数这些库的支持。

configure in Qt 6 relies on CMake to locate third-party libraries. It does so by checking various system paths. If you installed libraries somewhere else, you can let CMake know this by setting or extending the CMAKE_PREFIX_PATH variable.

Qt 6中的configure依赖于CMake来定位第三方库。它通过检查各种系统路径来实现。如果在其他地方安装了库，可以通过设置或扩展CMAKE_PREFIX_PATH 变量来让CMake知道这一点。

For a full list of options, consult the help with configure -help.

有关选项的完整列表，请参阅configure -help的帮助。

SSL

Qt Network can be configured to support communication for Secure Sockets Layer (SSL) but does not implement the actual algorithms itself. It needs to leverage other libraries instead.

Qt Network可以配置为支持安全套接字层（SSL）的通信，但本身并不实现实际的算法。它需要利用其他库。

On Windows, Qt can use the system's Secure Channel library for this purpose (configure option -schannel). On macOS and iOS, Qt can be configured to use the SecureTransport API (configure option -securetransport).

在Windows上，Qt可以为此目的使用系统的安全通道库（配置选项-schannel）。在macOS和iOS上，Qt可以配置为使用SecureTransport API（配置选项-securetrransport）。

The most feature-complete support that also works on almost all target platforms is provided by the OpenSSL Toolkit (option -openssl). Qt does require OpenSSL 1.1.1 or later.

​OpenSSL Toolkit（选项-openssl）提供了几乎适用于所有目标平台的功能最完整的支持。Qt确实需要OpenSSL 1.1.1或更高版本。

Qt can be configured to use OpenSSL in three ways:

Qt可以通过三种方式配置为使用OpenSSL：

• Qt Network loads OpenSSL libraries (DLLs) when first needed, at runtime. If not found, the application continues to run but fails to handle SSL communication. This is enabled by using the configure option -openssl-runtime.
• Qt Network在运行时首次需要时加载OpenSSL库（DLL）。如果未找到，应用程序将继续运行，但无法处理SSL通信。这是通过使用配置选项-openssl-runtime启用的。
• Qt Network links against the OpenSSL libraries. If they cannot be found at load time, the application fails to start. This is enabled by using the configure option -openssl-linked.
• Qt网络链接到OpenSSL库。如果在加载时找不到它们，则应用程序无法启动。这可以通过使用配置选项-openssl-linked来启用。
• Qt Network compiles against a static version of the OpenSSL libraries, and OpenSSL becomes part of the Qt Network library. This is enabled by using the configure option openssl-linked and setting the OPENSSL_USE_STATIC_LIBS variable to ON.
• Qt Network针对OpenSSL库的静态版本进行编译，OpenSSL成为Qt Network库的一部分。这是通过使用配置选项openssl-linked并将OPENSSL_USE_STATIC_LIBS 变量设置为ON来启用的。

Set the CMake variable OPENSSL_ROOT_DIR if OpenSSL is not installed in a standard location, and therefore not found by configure.

如果OPENSSL未安装在标准位置，因此无法通过配置找到，请设置CMake变量OPENSSL_ROOT_DIR。

See Secure Sockets Layer (SSL) Classes for further instructions on Qt with SSL support.

​有关支持SSL的Qt的更多说明，请参阅安全套接字层（SSL）类。

Cross-Compilation Options

交叉编译选项

To configure Qt for cross-platform development and deployment, you need to have a matching Qt version for the host machine first. Also, the development toolchain for the target platform needs to be set up. This set up varies among the Supported Platforms.

​要配置Qt进行跨平台开发和部署，需要首先为主机提供匹配的Qt版本。此外，还需要建立目标平台的开发工具链。此设置因支持的平台而异。

Common options are:

常见选项包括：

• -external-hostbindir - Path to Qt tools built for this machine.
• -external hostbindir-为这台机器构建的Qt工具的路径。
• -device - Select devices/mkspec for the qmake companion files.
• -device-为qmake伴随文件选择devices/mkspec。
• -device-option - sets additional qmake variables.
• -device-option-设置其他qmakes变量。

Note: Toolchains for non-desktop targets often come with a so-called sysroot that Qt needs to be configured against.

注意：非桌面目标的工具链通常附带一个所谓的sysroot，Qt需要对其进行配置。

Developer Builds

开发人员构建

The -developer-build configure option is a convenience option that optimizes the build for developing Qt itself. It shouldn't be used for building Qt variants that ship to customers.

-developer-build configure选项是一个方便的选项，可以优化Qt本身的构建。它不应该用于构建交付给客户的Qt变量。

Libraries in a developer build contain more exported symbols than a standard build, and all Qt code compiles with a higher warning level. It also changes the default prefix to the build directory, avoiding the need to install Qt before testing things, and finally enables the compilation of Qt's auto-tests by default.

开发人员版本中的库包含的导出符号比标准版本多，所有Qt代码在编译时都有更高的警告级别。它还更改了构建目录的默认前缀，避免了在测试之前安装Qt的需要，并最终默认启用了Qt自动测试的编译。

Reconfiguring Existing Builds

重新配置现有构建

The Qt build system has basic support for reconfiguring existing Qt builds with a different set of configure options, but it is not very robust due to the way CMake works internally.

Qt构建系统基本支持使用一组不同的配置选项重新配置现有的Qt构建，但由于CMake内部的工作方式，它不是很健壮。

The safest way to reconfigure an existing build is to pass the -redo option to configure. That will remove the build's CMakeCache.txt file, ensuring a relatively safe state for reconfiguration. The initial configure flags will still apply to the reconfigured build.

重新配置现有构建的最安全方法是传递-redo选项进行配置。这将删除构建的CMakeCache.txt文件，确保重新配置的相对安全状态。初始配置标志仍将应用于重新配置的版本。

Specific Options for Platforms

平台的具体选项

The following pages provide guidelines on how to configure Qt for specific platform development:

以下页面提供了如何为特定平台开发配置Qt的指南：

• Building Qt for QNX
• Configure an Embedded Linux Device
• Qt for Android - Building from Source
• Qt for Linux/X11 - Building from Source
• Qt for Windows - Building from Source
• Qt for macOS - Building from Source
• Qt for INTEGRITY - Monolith Project Tutorial
• Qt for iOS - Building from Source
• Qt for WebAssembly - Building from Source

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.