三联密码变量

项目
07/23/2024

本文介绍可用于三元组文件的 vcpkg 变量。三元组文件还可以包含用户定义的变量。

有关三元组功能的高级视图，请参阅三元组概念文档。

变量

VCPKG_TARGET_ARCHITECTURE

指定目标计算机体系结构。

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

VCPKG_CRT_LINKAGE

指定所需的 CRT 链接（对于 MSVC）。

有效选项为 dynamic 和 static。

VCPKG_LIBRARY_LINKAGE

指定首选库链接。

有效选项为 dynamic 和 static。如果库不支持首选链接类型，则可以忽略此设置。

VCPKG_BUILD_TYPE

你可以将此值设置为 release 以构建端口的仅发布版本。默认情况下，此值为空。当此值为空时，vcpkg 将构建端口的发布和调试配置。

VCPKG_CMAKE_SYSTEM_NAME

指定目标平台。

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

空（出于旧原因的 Windows 桌面）
WindowsStore（通用 Windows 平台）
MinGW （适用于 Windows 的极简 GNU）
Darwin (Mac OSX)
iOS (iOS)
Linux (Linux)
Emscripten (WebAssembly)

VCPKG_CMAKE_SYSTEM_VERSION

指定目标平台系统版本。

此字段是可选字段，如果存在，将作为 CMAKE_SYSTEM_VERSION 传递到版本中。

另请参阅 CMake 文档了解 CMAKE_SYSTEM_VERSION

VCPKG_CHAINLOAD_TOOLCHAIN_FILE

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

如果设置，将替代所有其他编译器检测逻辑。默认情况下，工具链文件是从 scripts/toolchains/ 适合平台选择的。

注意

若要创建自定义工具链文件，最好先包括 ${VCPKG_ROOT}/scripts/toolchains 中的现有工具链并对其进行扩展。这可确保将 vcpkg 可执行文件设置的基本变量（如 VCPKG_TARGET_ARCHITECTURE、VCPKG_CXX_FLAGS、VCPKG_LINKER_FLAGS）和其他变量转发到 CMake。

另请参阅 CMake 文档了解工具链文件。

VCPKG_CXX_FLAGS

不使用 VCPKG_CHAINLOAD_TOOLCHAIN_FILE 时，设置要使用的其他编译器标志。

此选项还具有特定于配置的标志和 C 语言标志的窗体：

VCPKG_CXX_FLAGS
VCPKG_CXX_FLAGS_DEBUG
VCPKG_CXX_FLAGS_RELEASE
VCPKG_C_FLAGS
VCPKG_C_FLAGS_DEBUG
VCPKG_C_FLAGS_RELEASE

如果你设置 VCPKG_CXX_FLAGS，则还必须设置 VCPKG_C_FLAGS，反之亦然。对于特定于配置的标志，也是如此。这些变量接受以空格分隔的编译器标志字符串：

set(VCPKG_CXX_FLAGS "/wd4996 -D_CRT_SECURE_NO_WARNINGS")
set(VCPKG_C_FLAGS "/wd4996 -D_CRT_SECURE_NO_WARNINGS")

VCPKG_LINKER_FLAGS

当在没有 VCPKG_CHAINLOAD_TOOLCHAIN_FILE 的情况下生成动态库和可执行文件时，设置要使用的其他链接器标志。

此选项还具有特定于配置的标志的窗体：

VCPKG_LINKER_FLAGS
VCPKG_LINKER_FLAGS_DEBUG
VCPKG_LINKER_FLAGS_RELEASE

VCPKG_MESON_CONFIGURE_OPTIONS

设置要追加的其他 Meson 配置选项以配置命令（在 vcpkg_configure_meson 中）。

此字段可选。

还可以当作特定于版本类型的 VCPKG_MESON_CONFIGURE_OPTIONS_DEBUG 和 VCPKG_MESON_CONFIGURE_OPTIONS_RELEASE 变量来使用。

VCPKG_MESON_NATIVE_FILE_RELEA标准版

在跨/原生文件提供另一个配置依赖文件作为 meson。可用于替代 vcpkg 提供的设置，因为 vcpkg 生成的跨/原生文件传递之后会传递它。

在提供你自己的 build_machine 和 host_machine 条目时特别管用。

VCPKG_CMAKE_CONFIGURE_OPTIONS

设置要追加的其他 CMake 配置选项以配置命令（在 vcpkg_cmake_configure 中）。

此字段可选。

还可以当作特定于版本类型的 VCPKG_CMAKE_CONFIGURE_OPTIONS_DEBUG 和 VCPKG_CMAKE_CONFIGURE_OPTIONS_RELEASE 变量来使用。

VCPKG_CONFIGURE_MAKE_OPTIONS

设置要追加的其他 automake/autoconf 配置选项以配置命令（在 vcpkg_configure_make 中）。

此字段可选。

例如，用于跳过某些可能失败的 libtool 检查：

set(VCPKG_CONFIGURE_MAKE_OPTIONS "lt_cv_deplibs_check_method=pass_all")

还可以当作特定于版本类型的 VCPKG_CONFIGURE_MAKE_OPTIONS_DEBUG 和 VCPKG_CONFIGURE_MAKE_OPTIONS_RELEASE 变量来使用。

VCPKG_HASH_ADDITIONAL_FILES

要包含在包 ABI 哈希计算中的文件列表。

此字段可选。

声明影响包内容的任何文件，并应将其纳入 ABI 哈希计算中。例如：

自定义三元组和工具链中（通过 include(filepath)）包含的文件。
在 VCPKG_MESON_(NATIVE|CROSS)_FILE_<CONFIG> 中定义的文件

仅考虑文件的内容和顺序，文件的路径不会影响 ABI 哈希。

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

VCPKG_POST_PORTFILE_INCLUDES

执行 portfile.cmake 后要包括的 CMake 文件的列表。

此字段可选。

文件的内容和顺序用于 ABI 哈希，文件的路径不会影响 ABI 哈希。

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

VCPKG_DEP_INFO_OVERRIDE_VARS

注意

本部分介绍 vcpkg 的实验性功能，此类功能随时可能会更改或删除。

替换三联密码“支持的”术语的默认计算列表。

如果设置，此选项会替代用于进行平台表达式评估的默认术语集。

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

注意

此列表通过 vcpkg_get_dep_info 帮助程序函数提取。

VCPKG_DISABLE_COMPILER_TRACKING

警告

不建议启用此选项，因为它可能会导致还原的二进制包中 ABI 不兼容。请参阅二进制缓存文档了解详细信息

如果此选项设置为 TRUE、ON 或 1，则不会将编译器作为包 ABI 的一部分进行跟踪。

这会导致二进制缓存重复使用更旧或更新的编译器中的版本。

特定于 Windows 的变量

VCPKG_ENV_PASSTHROUGH

指示 vcpkg 允许其他环境变量进入生成进程。

在 Windows 上，vcpkg 在与当前命令提示符隔离的特殊干净环境中生成包，以确保生成的可靠性和一致性。可将此三联密码选项设置为将会添加到干净环境中的其他环境变量列表。这些环境变量的值将哈希处理到包 abi 中 -- 若要在不跟踪 abi 的情况下传递环境变量，请参阅 VCPKG_ENV_PASSTHROUGH_UNTRACKED。

另请参阅 vcpkg env 命令，了解如何检查要使用的精准环境。

注意

此列表通过 vcpkg_get_tags 帮助程序函数提取。

VCPKG_ENV_PASSTHROUGH_UNTRACKED

指示 vcpkg 允许在不跟踪 abi 的情况下，让其他环境变量进入生成进程。

请参阅 VCPKG_ENV_PASSTHROUGH。

VCPKG_VISUAL_STUDIO_PATH

指定要使用的 Visual Studio 安装。

我们采用以下分步算法，介绍如何选择 Visual Studio 实例和工具集版本的精确组合：

确定从三联密码或环境变量 VCPKG_VISUAL_STUDIO_PATH 中 VCPKG_VISUAL_STUDIO_PATH 的设置，或当作未设置
确定从三联密码中 VCPKG_PLATFORM_TOOLSET 的设置，或当作未设置
收集 Visual Studio 实例与这些实例中提供的所有工具集的全部配对的列表
- 先按照实例类型（稳定、预发布、旧版）顺序，然后按照工具集版本（v143、v142、v141、v140）
根据 VCPKG_VISUAL_STUDIO_PATH 和 VCPKG_PLATFORM_TOOLSET 的设置筛选列表。
选择最佳剩余选项

路径应是绝对路径，格式为反斜杠，并且结尾没有斜杠：

set(VCPKG_VISUAL_STUDIO_PATH "C:\\Program Files (x86)\\Microsoft Visual Studio\\Preview\\Community")

VCPKG_PLATFORM_TOOLSET

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

请参阅 VCPKG_VISUAL_STUDIO_PATH，查看完整的选择算法。

有效设置

Visual Studio 2022 平台工具集为 v143。
Visual Studio 2019 平台工具集为 v142。
Visual Studio 2017 平台工具集为 v141。
Visual Studio 2015 平台工具集为 v140。

VCPKG_PLATFORM_TOOLSET_VERSION

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

默认情况下，VCPKG_PLATFORM_TOOLSET 始终选择所选工具集的最新已安装次要版本。如果需要更多粒度，可以使用此变量。你可以指定部分或完整版本号。有效值的示例为 14.25 或 14.27.29110。

VCPKG_LOAD_VCVARS_ENV

确定 vcpkg 是否将搜索并使用 Visual Studio 实例作为三联密码环境的一部分。

默认情况下，这是不指定 VCPKG_CHAINLOAD_TOOLCHAIN_FILE 的 Windows 三联密码的 ON。如果是非 Windows 三联密码以及指定 VCPKG_CHAINLOAD_TOOLCHAIN_FILE 的三联密码，此选项默认为 OFF。

Linux 变量

VCPKG_FIXUP_ELF_RPATH

如果此选项设置为 (true|1|on)，vcpkg 会将 $ORIGIN 和 $ORIGIN/<path_relative_to_lib> 添加到可执行文件和共享库的 RUNPATH 标头。此选项允许在 Linux 上重定位包。

MacOS 变量

VCPKG_INSTALL_NAME_DIR

设置生成 macOS 动态库时使用的安装名称。默认值是 @rpath。有关详细信息，请参阅 CMake 文档的 CMAKE_INSTALL_NAME_DIR 部分。

VCPKG_FIXUP_MACHO_RPATH

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

设置为 ON 时：

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

重要

默认情况下，当 VCPKG_TARGET_IS_OSX 为 TRUE 时，启用此功能。若要禁用，请在三元组文件中将 VCPKG_FIXUP_MACHO_RPATH 显式设置为 OFF。

有关 macOS 上动态库的详细信息，请参阅以下链接：

VCPKG_OSX_DEPLOYMENT_TARGET

设置已编译二进制文件的最低 macOS 版本。这还会更改 CMake 将搜索的 macOS 平台 SDK 版本。有关详细信息，请参阅 CMake 文档的 CMAKE_OSX_DEPLOYMENT_TARGET 部分。

VCPKG_OSX_SYSROOT

设置 CMake 将使用的 macOS 平台 SDK 的名称或路径。有关详细信息，请参阅 CMake 文档的 CMAKE_OSX_SYSROOT 部分。

VCPKG_OSX_ARCHITECTURES

设置 CMake 将会使用的 macOS/iOS 目标体系结构。有关详细信息，请参阅 CMake 文档的 CMAKE_OSX_ARCHITECTURES 部分。

每个端口的自定义

解释三元组文件时，将设置 CMake 变量 PORT。它可用于根据每个端口来更改设置（例如 VCPKG_LIBRARY_LINKAGE）。

示例：

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

这会将所有 qt5-* 端口生成为动态库，不过每个其他端口则会生成为静态库。

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

通过

三联密码变量

变量

VCPKG_TARGET_ARCHITECTURE

VCPKG_CRT_LINKAGE

VCPKG_LIBRARY_LINKAGE

VCPKG_BUILD_TYPE

VCPKG_CMAKE_SYSTEM_NAME

VCPKG_CMAKE_SYSTEM_VERSION

VCPKG_CHAINLOAD_TOOLCHAIN_FILE

VCPKG_CXX_FLAGS

VCPKG_LINKER_FLAGS

VCPKG_MESON_CONFIGURE_OPTIONS

VCPKG_MESON_NATIVE_FILE_RELEA标准版

VCPKG_MESON_NATIVE_FILE_DEBUG

VCPKG_MESON_CROSS_FILE_RELEASE

VCPKG_MESON_CROSS_FILE_DEBUG

VCPKG_CMAKE_CONFIGURE_OPTIONS

VCPKG_CONFIGURE_MAKE_OPTIONS

VCPKG_HASH_ADDITIONAL_FILES

VCPKG_POST_PORTFILE_INCLUDES

VCPKG_DEP_INFO_OVERRIDE_VARS

VCPKG_DISABLE_COMPILER_TRACKING

特定于 Windows 的变量

VCPKG_ENV_PASSTHROUGH

VCPKG_ENV_PASSTHROUGH_UNTRACKED

VCPKG_VISUAL_STUDIO_PATH

VCPKG_PLATFORM_TOOLSET

VCPKG_PLATFORM_TOOLSET_VERSION

VCPKG_LOAD_VCVARS_ENV

Linux 变量

VCPKG_FIXUP_ELF_RPATH

MacOS 变量

VCPKG_INSTALL_NAME_DIR

VCPKG_FIXUP_MACHO_RPATH

VCPKG_OSX_DEPLOYMENT_TARGET

VCPKG_OSX_SYSROOT

VCPKG_OSX_ARCHITECTURES

每个端口的自定义

其他资源