Qt 配置选项

configure是一个命令行工具，可协助您从源代码构建自定义版本的 Qt。它位于 Qt 主源代码目录中。

从 Qt 6 开始，configure 已成为 CMake 的封装工具。CMake 也可以直接调用。configure 提供了额外的错误检查功能，并兼容 Qt 5。

本页将介绍部分 configure 选项。如需查看完整选项列表，请执行命令configure -h 。

配置工作流

必须在具备 CMake、编译器及所需构建工具的正常工作构建环境中调用`configure`。在“构建 Qt 源代码”中列出了各平台的具体依赖项。

在设置好此类环境后，典型的操作流程是创建一个独立的构建目录，然后先运行 configure，接着构建 Qt，最后安装 Qt：

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

您可能需要尝试不同的 `configure` 参数，因此可能需要多次运行 `configure`。请注意，CMake 会将 `configure` 选项和环境信息缓存到一个名为 `CMakeCache.txt` 的文件中。如果您希望在不使用缓存信息的情况下重新开始，请删除该文件。

源代码、构建和安装目录

源代码目录包含从源代码包或 Git 仓库获取的源代码。构建目录用于存储与构建相关的文件，例如构建系统文件、目标文件及其他中间文件。安装目录则是二进制文件和库文件的安装位置，供系统或应用程序使用。

建议通过“影子构建”并使用-prefix选项将这些目录分开。这样可以确保 Qt源代码树保持干净，而构建产物和二进制文件则存储在单独的目录中。如果您希望从同一源代码树进行多次构建，但配置各不相同，这种方法非常方便。 要进行影子构建，请在另一个目录中运行 configure：

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

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

示例、测试和工具

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

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

您还可以将 Qt 配置为默认仅配置示例、测试和工具，但不进行构建。如果您将 CMake 变量QT_BUILD_EXAMPLES_BY_DEFAULT 、QT_BUILD_TESTS_BY_DEFAULT 和QT_BUILD_TOOLS_BY_DEFAULT 设置为 OFF，则cmake --build . 不会构建相应的组件。相反，CMake 将生成单独的目标，您可以随后分别进行构建。

在此，我们将构建 Qt 库和工具，同时还会构建NotePad 示例：

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

构建配置

您可以以多种变体构建 Qt 库和工具，每种变体都针对不同的使用场景进行了优化。

调试版和发布版

-release 该选项指示编译器对代码进行优化，且不在 Qt 及其工具中提供额外的调试符号。

-debug 跳过部分优化，以便更轻松地调试 Qt 及其工具。此选项还会生成调试符号，使您能够在调试器中检查已构建库的代码和状态。

最后，-debug-and-release 允许您一次性构建 Qt 库的调试版和发布版。此功能仅在配置 Windows 构建时受支持。

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

• -force-debug-info: 生成包含调试信息的发布版。
• -separate-debug-info: 将调试信息提取到单独的文件中。
• -optimize-size: 优化发布版构建以减小文件大小，而非提高运行速度。

静态和共享构建

Qt 模块可以构建为独立的库，可由可执行文件在启动时（针对 Qt 库）或运行时（针对 Qt 插件）进行链接和加载。这被称为共享构建，也是大多数平台上的默认配置。相应的 configure 选项是-shared 。

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

CMake 生成器

在配置时，您可以选择一个 CMake 生成器。请注意，CMake 支持某些无法与 Qt 配合使用的生成器。因此，configure 会自动为您选择一个生成器。

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

模块与特性

Qt 源代码组织在几个称为子模块的顶级目录中，例如qtbase 、qtdeclarative 或qtmultimedia 。在这些子模块中，您可以找到不同Qt 模块的源代码。 Qt Core, Qt Quick，以及 Qt Multimedia 都是此类 Qt 模块的示例。

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

包含和排除 Qt 子模块

configure 的 -skip 选项用于将子模块（顶级源代码目录）从 Qt 构建中排除。排除一个子模块即会排除该子模块内的所有Qt 模块。qtwayland 子模块同时包含 Qt Wayland Compositor 和 Qt Wayland QPA 插件。因此，将 `-skip qtwayland ` 作为 `configure` 选项指定将同时排除这两个Qt 模块。

~/qt-source/configure -skip qtwayland

configure 的 -submodules 选项可用于配置仅构建列出的子模块及其依赖项的构建过程。例如，通过指定qtmultimedia 子模块， Qt Multimedia 其所有依赖项都将被纳入构建范围。多个子模块可用逗号分隔。

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

包含或排除功能

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

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

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

使用 `configure -list-features ` 可在命令行上显示所有可用功能的列表。请注意，功能之间可能存在依赖关系，因此禁用某项功能可能会对其他功能产生连锁影响。

第三方库

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

下表总结了部分第三方选项：

此外，您还可以通过使用-no 代替-qt ，来禁用对其中大部分库的支持。

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

如需查看选项的完整列表，请查阅configure -help 的帮助文档。

SSL

Qt Network 可配置为支持安全套接层（SSL）通信，但自身并不实现具体的加密算法，而是需要借助其他库来实现。

在 Windows 上，Qt 可以使用系统的 Secure Channel 库来实现此功能（配置选项-schannel ）。在 macOS 和 iOS 上，可以配置 Qt 使用 SecureTransport API（配置选项-securetransport ）。

功能最完善且几乎支持所有目标平台的支持由OpenSSL 工具包提供（选项-openssl ）。Qt 确实需要 OpenSSL 1.1.1 或更高版本。

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

• Qt Network 在运行时首次需要时加载 OpenSSL 库（DLL）。如果找不到这些库，应用程序将继续运行，但无法处理 SSL 通信。可通过配置选项-openssl-runtime 启用此功能。
• Qt Network 与 OpenSSL 库进行链接。如果在加载时找不到这些库，应用程序将无法启动。可通过使用配置选项 `-openssl-linked` 启用此功能。
• Qt Network 使用静态版本的 OpenSSL 库进行编译，此时 OpenSSL 将成为Qt Network 库的一部分。通过使用配置选项openssl-linked 并将OPENSSL_USE_STATIC_LIBS 变量设置为ON 来启用此功能。

如果 OpenSSL 未安装在标准位置，导致 configure 无法找到它，请设置 CMake 变量OPENSSL_ROOT_DIR 。

有关 Qt 支持 SSL 的更多说明，请参阅“安全套接层 (SSL) 类”。

交叉编译选项

要配置 Qt 以进行跨平台开发和部署，首先需要确保主机上安装了与之匹配的 Qt 版本。此外，还需要设置目标平台的开发工具链。该设置因“支持的平台”而异。

常见选项包括：

• -external-hostbindir - 针对该机器构建的 Qt 工具路径。
• -device - 选择用于生成 qmake 辅助文件的 devices/mkspec。
• -device-option - 设置额外的 qmake 变量。

开发者构建

-developer-build 配置选项是一个便捷选项，用于优化 Qt 本身的开发构建。不应将其用于构建提供给客户的 Qt 变体。

开发者构建中的库包含比标准构建更多的导出符号，且所有 Qt 代码均以更高的警告级别进行编译。它还会将默认前缀更改为构建目录，从而避免在测试前需要安装 Qt，并默认启用 Qt 自动测试的编译。

重新配置现有构建

Qt 构建系统基本支持使用不同的 configure 选项重新配置现有的 Qt 构建，但由于 CMake 的内部工作原理，这种支持并不十分可靠。

重新配置现有构建的最安全方法是向 `configure` 传递 `-redo ` 选项。这将删除该构建的 `CMakeCache.txt` 文件，确保重新配置时处于相对安全的状态。初始的 `configure` 标志仍将适用于重新配置后的构建。

安装配置摘要和选项

自 Qt 6.9 起，configure 摘要文件以及传递给 `configure` 的选项均可作为安装的一部分自动包含。

通过将 CMake 变量QT_INSTALL_CONFIG_INFO_FILES 设置为ON 即可启用此功能：

~/qt-source/configure -prefix /opt/Qt6 -- -D QT_INSTALL_CONFIG_INFO_FILES=ON

在安装过程中，用于配置摘要和选项的文本文件（针对构建中的每个仓库部分）将被复制到architecture-independent Qt data directory 目录中。

例如，

/opt/Qt6/config_qtbase.opt
/opt/Qt6/config_qtbase.summary
/opt/Qt6/config_qtdeclarative.opt
/opt/Qt6/config_qtdeclarative.summary
...

各平台的特定选项

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

• 为 QNX 构建 Qt
• 为 VxWorks 构建 Qt
• 配置嵌入式 Linux 设备
• Android 版 Qt - 从源代码构建
• HarmonyOS 版 Qt - 从源代码构建
• Linux 版 Qt——从源代码构建
• Windows 版 Qt - 从源代码构建
• macOS 版 Qt - 从源代码构建
• INTEGRITY 版 Qt - Monolith 项目教程
• 适用于 iOS 的 Qt - 从源代码构建
• WebAssembly 版 Qt - 从源代码构建