Qt 配置选项

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

自 Qt 6 起，configure 成为cmake 的封装器。configure 提供额外的错误检查功能，并与 Qt 5 兼容。

本页将讨论 configure 的部分选项。如需完整的选项列表，请输入configure -h 命令。

配置工作流程

configure 必须在 CMake、编译器和所需构建工具随时可用的工作构建环境中调用。构建 Qt 源文件》列出了每个平台的此类依赖项。

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

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

您可能想尝试使用不同的 configure 标志，因此需要多次运行 configure。请注意，CMake 会将配置选项和环境信息缓存在一个名为 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 插件）链接并加载这些库。这称为共享编译，是大多数平台的默认配置。与之匹配的配置选项是-shared。

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

CMake 生成器

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

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

模块和功能

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

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

包含和排除 Qt 子模块

configureQt 的-skip选项用于从 Qt 构建中排除子模块（顶层源代码目录）。排除一个子模块会排除该子模块内的所有Qt 模块。qtwayland 子模块包含 Qt Wayland Compositor和 Qt Wayland QPA 插件。因此，在配置选项中指定-skip qtwayland 将排除这两个Qt 模块。

~/qt-source/configure -skip qtwayland

configure子模块"（-submodules）选项可用于配置只编译列出的子模块及其依赖项的编译。例如，通过指定qtmultimedia 子模块、 Qt Multimedia及其所有依赖模块都将包含在联编过程中。可以用逗号分隔多个子模块。

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

包含或排除功能

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

例如，可以使用-no-feature-accessibilityconfigure 选项禁用 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 可以使用系统的安全通道库来实现这一目的（配置选项-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 如果在加载时找不到，应用程序将继续运行，但无法处理 SSL 通信。如果在加载时找不到这些链接，应用程序将无法启动。可通过配置选项-openssl-linked 启用。
• Qt Network 根据静态版本的 OpenSSL 库编译，OpenSSL 将成为 库的一部分。使用 configure 选项Qt Network openssl-linked并将OPENSSL_USE_STATIC_LIBS变量设置为ON 即可启用。

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

有关支持 SSL 的 Qt 的进一步说明，请参阅Secure Sockets Layer (SSL) Classes。

跨平台编译选项

要为跨平台开发和部署配置 Qt，首先需要为主机提供匹配的 Qt 版本。此外，还需要为目标平台设置开发工具链。不同的支持平台需要不同的设置。

常见选项有

• -external-hostbindir- 为本机器构建的 Qt 工具的路径。
• -device- 为 qmake 辅助文件选择设备/mkspec。
• -device-option- 设置额外的 qmake 变量。

开发者构建

-developer-build（开发者构建）配置选项是一个方便的选项，用于优化 Qt 本身的开发构建。它不应用于为客户构建 Qt 变体。

与标准构建相比，开发者构建中的库包含更多导出符号，所有 Qt 代码编译时的警告级别也更高。它还会更改构建目录的默认前缀，避免在测试前安装 Qt，最后默认启用 Qt 的自动测试编译。

重新配置现有编译

Qt 联编系统基本支持使用不同的配置选项重新配置现有的 Qt 联编，但由于 CMake 内部的工作方式，这种支持并不强大。

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

平台的特定选项

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

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