跳到主要内容

三元组变量

本文介绍可用于三元组文件的 kmpkg 变量。三元组文件也可包含用户自定义变量。

有关三元组功能的概览，请参阅三元组概念文档。

通用变量​

KMPKG_TARGET_ARCHITECTURE​

指定目标机器架构。

有效选项包括 x86、x64、arm、arm64、arm64ec、s390x、ppc64le、riscv32、riscv64、loongarch32、loongarch64、mips64 和 wasm32。

KMPKG_CRT_LINKAGE​

指定所需的 CRT 链接方式（适用于 MSVC）。

有效选项为 dynamic（动态）和 static（静态）。

KMPKG_LIBRARY_LINKAGE​

指定首选的库链接方式。

有效选项为 dynamic（动态）和 static（静态）。如果库不支持该首选链接类型，可忽略此设置。

KMPKG_BUILD_TYPE​

可将该值设为 release，仅构建端口的发布（Release）版本。默认值为空；当值为空时，kmpkg 会同时构建端口的发布版本和调试（Debug）版本。

KMPKG_CMAKE_SYSTEM_NAME​

指定目标平台。

有效选项包括任意 CMake 系统名称，例如：

  • 空值（出于兼容原因，对应 Windows 桌面版）
  • WindowsStore（通用 Windows 平台，UWP）
  • MinGW（适用于 Windows 的极简 GNU 工具集）
  • Darwin（macOS）
  • iOS（iOS）
  • Linux（Linux）
  • Emscripten（WebAssembly）

KMPKG_CMAKE_SYSTEM_VERSION​

指定目标平台的系统版本。

该字段为可选字段；若设置，其值会以 CMAKE_SYSTEM_VERSION 传入构建过程。

另请参阅 CMake 官方文档中关于 CMAKE_SYSTEM_VERSION 的说明。

KMPKG_CHAINLOAD_TOOLCHAIN_FILE​

指定要使用的备用 CMake 工具链文件。

若设置该变量，将覆盖所有其他编译器检测逻辑。默认情况下，会从 scripts/toolchains/ 目录中选择与平台匹配的工具链文件。

信息

若要创建自定义工具链文件，建议先包含 ${KMPKG_ROOT}/scripts/toolchains 目录下的现有工具链文件，再对其进行扩展。这能确保 kmpkg 可执行文件设置的关键变量（如 KMPKG_TARGET_ARCHITECTURE、KMPKG_CXX_FLAGS、KMPKG_LINKER_FLAGS 及其他变量）被传递到 CMake 中。

另请参阅 CMake 官方文档中关于工具链文件的说明。

KMPKG_CXX_FLAGS​

设置未使用 KMPKG_CHAINLOAD_TOOLCHAIN_FILE 时要使用的额外编译器标志。

该选项还提供针对特定配置的标志形式，以及 C 语言标志形式：

  • KMPKG_CXX_FLAGS（通用 C++ 标志）
  • KMPKG_CXX_FLAGS_DEBUG（调试模式 C++ 标志）
  • KMPKG_CXX_FLAGS_RELEASE（发布模式 C++ 标志）
  • KMPKG_C_FLAGS（通用 C 标志）
  • KMPKG_C_FLAGS_DEBUG（调试模式 C 标志）
  • KMPKG_C_FLAGS_RELEASE（发布模式 C 标志）

若设置 KMPKG_CXX_FLAGS，则必须同时设置 KMPKG_C_FLAGS，反之亦然；针对特定配置的标志也遵循此规则。这些变量接受以空格分隔的编译器标志字符串：

set(KMPKG_CXX_FLAGS "/wd4996 -D_CRT_SECURE_NO_WARNINGS")
set(KMPKG_C_FLAGS "/wd4996 -D_CRT_SECURE_NO_WARNINGS")

KMPKG_LINKER_FLAGS​

设置未使用 KMPKG_CHAINLOAD_TOOLCHAIN_FILE 时，构建动态库和可执行文件要使用的额外链接器标志。

该选项还提供针对特定配置的标志形式：

  • KMPKG_LINKER_FLAGS（通用链接器标志）
  • KMPKG_LINKER_FLAGS_DEBUG（调试模式链接器标志）
  • KMPKG_LINKER_FLAGS_RELEASE（发布模式链接器标志）

KMPKG_MESON_CONFIGURE_OPTIONS​

设置要追加到配置命令中的额外 Meson 配置选项（适用于 kmpkg_configure_meson 函数）。

该字段为可选字段。也提供针对构建类型的变体变量：KMPKG_MESON_CONFIGURE_OPTIONS_DEBUG（调试模式）和 KMPKG_MESON_CONFIGURE_OPTIONS_RELEASE（发布模式）。

KMPKG_MESON_NATIVE_FILE_RELEASE​

提供额外的、与配置相关的文件作为 Meson 交叉/原生配置文件。由于该文件会在 kmpkg 生成的交叉/原生配置文件之后传入，因此可用于覆盖 kmpkg 提供的设置。

该变量对于自定义 build_machine 和 host_machine 配置项尤为有用。

KMPKG_MESON_NATIVE_FILE_DEBUG​

请参阅 KMPKG_MESON_NATIVE_FILE_RELEASE。

KMPKG_MESON_CROSS_FILE_RELEASE​

请参阅 KMPKG_MESON_NATIVE_FILE_RELEASE。

KMPKG_MESON_CROSS_FILE_DEBUG​

请参阅 KMPKG_MESON_NATIVE_FILE_RELEASE。

KMPKG_CMAKE_CONFIGURE_OPTIONS​

设置要追加到配置命令中的额外 CMake 配置选项（适用于 kmpkg_cmake_configure 函数）。

该字段为可选字段。也提供针对构建类型的变体变量：KMPKG_CMAKE_CONFIGURE_OPTIONS_DEBUG（调试模式）和 KMPKG_CMAKE_CONFIGURE_OPTIONS_RELEASE（发布模式）。

KMPKG_CONFIGURE_MAKE_OPTIONS​

设置要追加到配置命令中的额外 automake/autoconf 配置选项（适用于 kmpkg_configure_make 函数）。

该字段为可选字段。例如，跳过某些可能错误失败的 libtool 检查：

set(KMPKG_CONFIGURE_MAKE_OPTIONS "lt_cv_deplibs_check_method=pass_all")

也提供针对构建类型的变体变量：KMPKG_CONFIGURE_MAKE_OPTIONS_DEBUG（调试模式）和 KMPKG_CONFIGURE_MAKE_OPTIONS_RELEASE（发布模式）。

KMPKG_HASH_ADDITIONAL_FILES​

要纳入包 ABI 哈希计算的文件列表。

该字段为可选字段。声明所有影响包内容、且应纳入 ABI 哈希计算的文件，例如：

  • 在自定义三元组和工具链中通过 include(filepath) 引入的文件；
  • 在 KMPKG_MESON_(NATIVE|CROSS)_FILE_<CONFIG> 中定义的文件。

仅文件的内容和顺序会被纳入计算，文件路径不影响 ABI 哈希。

set(KMPKG_HASH_ADDITIONAL_FILES
  "${CMAKE_CURRENT_LIST_DIR}/file1.cmake"
  "${CMAKE_CURRENT_LIST_DIR}/meson-cross.txt"
)

KMPKG_POST_PORTFILE_INCLUDES​

在 portfile.cmake 执行完成后要包含的 CMake 文件列表。

该字段为可选字段。文件的内容和顺序会纳入 ABI 哈希计算，文件路径不影响 ABI 哈希。

set(KMPKG_POST_PORTFILE_INCLUDES
  "${CMAKE_CURRENT_LIST_DIR}/file1.cmake"
  "${CMAKE_CURRENT_LIST_DIR}/file2.cmake"
)

KMPKG_DEP_INFO_OVERRIDE_VARS​

本节介绍 kmpkg 的实验性功能，该功能可能随时变更或移除，恕不另行通知。

替换默认计算的三元组“Supports”（支持项）列表。若设置该选项，将覆盖用于平台表达式求值的默认支持项集合。

有关详细信息，请参阅清单文件中 "supports" 字段的文档。

信息

该列表通过 kmpkg_get_dep_info 辅助函数提取。

KMPKG_DISABLE_COMPILER_TRACKING​

注意

不建议启用该选项，因为这可能导致恢复的二进制包出现 ABI 不兼容问题。更多信息请参阅二进制缓存文档。

当该选项设为 TRUE、ON 或 1 时，编译器信息将不会被纳入包 ABI 的跟踪范围。这会导致二进制缓存复用来自较旧或较新版本编译器的构建产物。

仅限 Windows 系统的变量​

KMPKG_ENV_PASSTHROUGH​

指示 kmpkg 允许额外的环境变量进入构建过程。

在 Windows 系统中，kmpkg 会在与当前命令提示符隔离的专用干净环境中构建包，以确保构建的可靠性和一致性。该三元组选项可设为额外环境变量的列表，这些变量会被添加到干净环境中。这些环境变量的值会被哈希到包 ABI 中——若要传递环境变量但不纳入 ABI 跟踪，请参阅 KMPKG_ENV_PASSTHROUGH_UNTRACKED。

有关如何查看将使用的精确环境，请参阅 kmpkg env 命令。

信息

该列表通过 kmpkg_get_tags 辅助函数提取。

KMPKG_ENV_PASSTHROUGH_UNTRACKED​

指示 kmpkg 允许额外的环境变量进入构建过程，且不将其纳入 ABI 跟踪。

请参阅 KMPKG_ENV_PASSTHROUGH。

KMPKG_VISUAL_STUDIO_PATH​

指定要使用的 Visual Studio 安装路径。

要选择 Visual Studio 实例和工具集版本的精确组合，会执行以下算法：

  1. 从三元组中获取 KMPKG_VISUAL_STUDIO_PATH 的设置；若未设置，则读取环境变量 KMPKG_VISUAL_STUDIO_PATH；若仍未设置，则视为未配置。
  2. 从三元组中获取 KMPKG_PLATFORM_TOOLSET 的设置；若未设置，则视为未配置。
  3. 收集所有 Visual Studio 实例与其实例中可用工具集的组合列表：
    • 排序规则：先按实例类型（稳定版、预发布版、旧版）排序，再按工具集版本（v143、v142、v141、v140）排序。
  4. 根据 KMPKG_VISUAL_STUDIO_PATH 和 KMPKG_PLATFORM_TOOLSET 的设置过滤该列表。
  5. 选择剩余选项中最优的组合。

路径必须为绝对路径，使用反斜杠分隔，且末尾无斜杠：

set(KMPKG_VISUAL_STUDIO_PATH "C:\\Program Files\\Microsoft Visual Studio\\2022\\Preview")

KMPKG_PLATFORM_TOOLSET​

指定要使用的、基于 Visual Studio 的 C/C++ 编译器工具链。

完整的选择算法请参阅 KMPKG_VISUAL_STUDIO_PATH。

有效设置：

  • Visual Studio 2022 平台工具集：v143
  • Visual Studio 2019 平台工具集：v142
  • Visual Studio 2017 平台工具集：v141
  • Visual Studio 2015 平台工具集：v140

KMPKG_PLATFORM_TOOLSET_VERSION​

指定要使用的 MSVC C/C++ 编译器工具链的详细版本。

默认情况下，KMPKG_PLATFORM_TOOLSET 会选择所选工具集的最新已安装次要版本。若需要更精细的版本控制，可使用该变量。可指定部分版本号或完整版本号，例如 14.25 或 14.27.29110。

KMPKG_LOAD_VCVARS_ENV​

决定 kmpkg 是否会在三元组环境中搜索并使用 Visual Studio 实例。

默认情况下，对于未指定 KMPKG_CHAINLOAD_TOOLCHAIN_FILE 的 Windows 三元组，该值为 ON；对于非 Windows 三元组，以及指定了 KMPKG_CHAINLOAD_TOOLCHAIN_FILE 的三元组，该值默认为 OFF。

仅限 Linux 系统的变量​

KMPKG_FIXUP_ELF_RPATH​

当该选项设为 true、1 或 on 时，kmpkg 会将 $ORIGIN 和 $ORIGIN/<path_relative_to_lib> 添加到可执行文件和共享库的 RUNPATH 头中。这使得包可在 Linux 系统中被重定位。

仅限 macOS 系统的变量​

KMPKG_INSTALL_NAME_DIR​

设置构建 macOS 动态库时使用的安装名称。默认值为 @rpath。更多信息请参阅 CMake 官方文档中关于 CMAKE_INSTALL_NAME_DIR 的说明。

KMPKG_FIXUP_MACHO_RPATH​

通过使用相对安装名称和运行路径，确保 kmpkg 构建的 Mach-O 二进制文件可被重定位。

当设为 ON 时：

  • 将共享库二进制文件中绝对的 LC_ID_DYLIB 字段修改为 @rpath/<library>；
  • 将可执行文件和共享库二进制文件中绝对的 LC_RPATH 字段修改为相对的 @loader_path/<relative/path/to/library>。
注意

当 KMPKG_TARGET_IS_OSX 为 TRUE 时，该功能默认启用。若要禁用，需在三元组文件中显式将 KMPKG_FIXUP_MACHO_RPATH 设为 OFF。

有关 macOS 动态库的更多信息，请参考以下链接：

KMPKG_OSX_DEPLOYMENT_TARGET​

设置编译后的二进制文件支持的最低 macOS 版本。这也会改变 CMake 搜索的 macOS 平台 SDK 版本。更多信息请参阅 CMake 官方文档中关于 CMAKE_OSX_DEPLOYMENT_TARGET 的说明。

KMPKG_OSX_SYSROOT​

设置 CMake 要使用的 macOS 平台 SDK 的名称或路径。更多信息请参阅 CMake 官方文档中关于 CMAKE_OSX_SYSROOT 的说明。

KMPKG_OSX_ARCHITECTURES​

设置 CMake 要使用的 macOS/iOS 目标架构。更多信息请参阅 CMake 官方文档中关于 CMAKE_OSX_ARCHITECTURES 的说明。

按端口自定义配置​

解析三元组文件时，CMake 变量 PORT 会被自动设置。可通过该变量按端口自定义设置（如 KMPKG_LIBRARY_LINKAGE）。

示例：

set(KMPKG_LIBRARY_LINKAGE static)
if(PORT MATCHES "qt5-")
    set(KMPKG_LIBRARY_LINKAGE dynamic)
endif()

上述配置会将所有 qt5-* 端口构建为动态库，而其他所有端口构建为静态库。

有关真实项目中的示例，请参考：https://github.com/Intelight/kmpkg/blob/master/triplets/x86-windows-mixed.cmake。