本文档介绍在对 vcpkg 做出贡献时要遵循的策略、准则和最佳做法。
它旨在充当与以下相同的角色:
精心策划注册表设计目标
端口必须同步安装
特选注册表中包含的端口必须在注册表中存在所有其他端口的情况下成功生成。 vcpkg 的自动化 CI 定期测试所有端口的完整组合。
端口不得执行以下任一作:
- 安装与另一个端口冲突的文件。
- 安装属于另一个包的符号和定义,但不包括将冲突库放在
manual-link目录中所述的范围较窄、显式链接的库。 - 测试是否存在其他端口。 声明依赖项除外。
针对以下项进行了例外:
- 正式替代另一端口的端口。 这包括以下情况:
- 同一项目发布了一个后继组件。
- 另一个项目接管被放弃的组件的维护,包括通过分叉。
- 另一个项目发布了一个后继组件。
- 没有平台重叠的端口。 例如,一个仅适用于 Windows 的替代项,用于替换不支持 Windows 的 Linux 组件。
- 早于本策略存在、并且可证明拥有相当数量用户和参与者的端口。
vcpkg 维护人员会逐案评估祖父条款例外情况。 例如,boringssl 是在自定义注册表可用之前添加的,并且仍保留在特选注册表中,因为它仍有实际用户,尽管 openssl 是 OpenSSL 分支家族的规范提供程序。 仅先前的接受并不能保证例外。
不符合此策略的端口无法接受到特选注册表中。
端口必须在至少一个官方三元组中进行测试。
特选注册表中的所有端口都必须在 CI 中至少一个官方三元组进行测试。
针对以下项进行了例外:
- 临时情况,例如:
- 如果不更新 CI 基础结构,该端口就无法构建。
- 因为某个上游依赖最近出现了破坏性变更,该端口无法构建,我们目前正在努力解决此问题。
- 早于本策略存在、并且可证明拥有相当数量用户和参与者的端口。
无法在至少一个官方三元组中进行测试的新端口不会入选特选注册表。 不再符合此策略且不具备上文所列例外资格的现有端口将从注册表中取消列出。 例如,如果在端口支持的每个官方三元组中都禁用了 CI 测试,且不适用任何例外情况,则会将该端口从清单中删除。
打包组件应稳定并得到积极维护
在特选注册表中打包的组件必须处于活动维护状态。 非活动组件的端口可能会从列表中移除。
如果出现以下情况,则组件被视为处于非活动状态:
- 其维护人员已声明该组件已被弃用。
- 其源存储库已存档或不再接受贡献。
- 维护人员无响应或无法访问。
- 很长一段时间没有做出有意义的更改。
对于被视为成熟、稳定且不常变更的基础组件,可予以例外处理。
例如: zlib。
打包的组件应当成熟稳定
打包在特选注册表中的组件必须成熟,供 vcpkg 用户使用。 应将用于个人使用的组件 发布到自定义注册表。
如果以下语句之一为 true,则组件被视为足够成熟,适合特选注册表:
- 该组件有一个至少已发布六个月的版本。
- 该组件表明其至少有六个月的公开且活跃的开发。
- 该组件是某个项目的官方组成部分,该项目已发布至少六个月,或已进行至少六个月的公开活跃开发。 例如,新的 Boost 库或 Qt 组件。
- 该组件在某些其他方面表现出与先前的要求相当的成熟度。
组件不成熟性的某些指标包括:
- 该组件不会出现在搜索引擎结果中。
- 该组件经常被重命名。
- 与其他库文件冲突。
PR 结构
为每个端口发出单独的拉取请求
较小的拉取请求(PR)更易于审查。 拉取请求应对单个端口进行更改。 这也减少了持续集成 (CI) 结果的等待时间。
在某些情况下,可能无法将 PR 限制为单个端口。 例如,更改端口时,需要更新或修补下游使用者。
避免不相关的外观改动
不要对原本未作修改的端口进行无关的修饰性更改,例如重新格式化、重命名变量或修正拼写错误。 这些更改会占用原本可更好地用于其他地方的计算时间。 改进生成正确性、兼容性、可靠性或可重现性的更改,并不会仅仅因为已安装的文件保持不变而被视为微不足道。
使用独特的端口名称
端口的名称应指示其内容。
在搜索引擎或专用包浏览器中搜索端口的名称(如 Repology)时,应能找到其对应的组件。
具有短名称或以常用单词命名的端口需要消除歧义。 这仅适用于特选注册表中端口的名称,打包组件的名称及其内容不需要符合此策略。
对于将组件与其端口名称紧密关联并打包的端口,可作例外处理。 例如:libpng、openssl或zlib。
若要符合此策略,具有不明确名称的新端口可以使用前缀,例如:
- 存储库的所有者、用户名或组织。 示例:
google-cloud-cpp。 对于托管在 GitHub 上的组件的端口,GitHub 所有者是可接受的明确前缀<github owner>-<repository name>。 - 包所属的套件的名称:
boost-dll。 仅当包是此类套件的官方组件时。
示例:不明确端口名称
具有名称 ip 的端口被视为不明确,因为:
- 名称太短,
- 名称是一个常见单词,并且
- 名称与任何单一组件不强关联。
若要确定名称是否有歧义,请从端口名称中删除 C++ 和开源组件使用的以下常见前缀和后缀:
cppfreelibopen- 数字
例如:ip-cpp,libip 和 ip5 是模棱两可的,因为它们简化为同样的 ip 词干。
限制端口重命名
为了避免给用户造成困惑,不得在任何 12 个月的时间段内多次重命名端口。
使用 GitHub Draft PR
GitHub Draft PR 是获取尚未准备好合并的工作 CI 或人工反馈的一种好方法。 大多数新的 PR 应作为草稿打开,并在 CI 通过后转换为普通 PR。
有关 GitHub Draft PR 的详细信息,请参阅 草稿拉取请求简介。
vcpkg 维护者可能会在评审过程中将 PR 转换为草稿,通常是在请求更改或留下指示何时将 PR 标记为准备好审阅的注释时。
关闭非活动 PR
vcpkg 维护者可能会在 PR 等待贡献者采取行动超过 60 天后关闭该 PR。 非活动倒计时仅在需要参与者操作时运行。 在 PR 等待生成实验室验证或由 vcpkg 维护者审查时,它不会运行。
一个 PR 处于可审阅状态时:
- 没有失败的 PR 检查,或者项目参与者寻求帮助或解释失败的原因。
- vcpkg 维护者没有任何挂起的请求更改或澄清。
- 没有发现合并冲突。
当 PR 进入需要参与者操作的状态时,将开始倒计时。 当 PR 打开后存在参与者需要解决的问题时,或者当 vcpkg 维护者请求更改或澄清时,可能会发生这种情况。 请求参与者操作时,vcpkg 维护者可能会将 PR 标记为草稿。
参与者的实质性反应将重置倒计时。 如果响应解决了所有挂起的请求,并且 PR 已准备好进行评审,则倒计时将停止,直到再次需要贡献者采取操作。 如果参与者在需要采取行动时 60 天内未作出回应,则 PR 会被视为已过时,并可能由 vcpkg 维护者酌情关闭。
Portfiles
避免使用已弃用的帮助程序函数
目前,以下辅助工具已弃用:
-
vcpkg_extract_source_archive_ex()应替换为vcpkg_extract_source_archive()支持的重载(使用ARCHIVE) - 已弃用的
vcpkg_extract_source_archive()的重载(不带ARCHIVE)应替换为支持的重载(带ARCHIVE)。 -
vcpkg_apply_patches()应替换为“提取”帮助程序的PATCHES参数(例如vcpkg_from_github()) -
vcpkg_build_msbuild()应替换为vcpkg_install_msbuild() -
vcpkg_copy_tool_dependencies()应替换为vcpkg_copy_tools() -
vcpkg_configure_cmake在移除vcpkg_cmake_configure()后应替换为PREFER_NINJA -
vcpkg_build_cmake应替换为vcpkg_cmake_build() -
vcpkg_install_cmake应替换为vcpkg_cmake_install() -
vcpkg_fixup_cmake_targets应替换为vcpkg_cmake_config_fixup
一些替换帮助程序函数位于“工具端口”中,允许使用者在特定版本固定其行为,以便锁定特定版本中帮助程序的行为。 工具端口需要被添加到相应端口的"dependencies"中,如下所示:
{
"name": "vcpkg-cmake",
"host": true
},
{
"name": "vcpkg-cmake-config",
"host": true
}
避免 portfile 中的注释过多
理想情况下,端口文件应简短、简单且尽可能具有声明性。
在提交 PR 之前,移除 create 命令引入的所有样板注释。
对十六进制数字字符串使用小写
vcpkg 中的许多功能都依赖于比较十六进制数字的字符串。 一些示例包括但不限于 SHA512 哈希、Git 提交 ID 和树对象哈希。
在内部,当此类值的大小写不影响比较时,vcpkg 会将其规范化为小写后再比较。 但是,在 vcpkg 的基础结构之上构建工具可能不会做出同样的考虑。 因此,我们需要十六进制字符串
在以下情形中,应小写以保持一致性:
- vcpkg 帮助程序函数中的
SHA512参数。 -
REFvcpkg 帮助程序函数中的参数(当值为十六进制字符串时)。 -
git-tree版本数据库文件中的对象。 -
sha512文件中的scripts/vcpkg-tools.json对象。 - 其他不关心十六进制字符串大小写的地方。
端口不得依赖于路径
端口不应根据已安装的具体端口来更改其行为,因为这样会更改该端口所安装的内容。 例如,给定:
> vcpkg install a
> vcpkg install b
> vcpkg remove a
和
> vcpkg install b
b 安装的文件必须相同,而不考虑 a 以前安装文件的影响。 这意味着,在采取一些操作之前,端口不得尝试检测安装树中是否有其他端口提供的内容。 下面的“定义功能时,显式控制依赖项”中介绍了此类“路径依赖”行为具体和常见原因。
唯一端口分配规则
在整个 vcpkg 系统中,用户预计并发使用的两个端口不会提供相同的文件。 如果软件包尝试安装已由另一个软件包提供的文件,安装将失败。 例如,如果端口希望对标头使用极常见的名称,则应将这些标头放在子目录中而不是 include 中。
此属性由尝试在注册表中安装所有端口的连续集成运行定期检查,如果两个端口提供相同的文件,则会以 FILE_CONFLICTS 失败。
在非官方命名空间中添加 CMake 导出
vcpkg 的核心设计理念是不要为用户造成“锁定”。 在构建系统中,依赖于系统库和依赖于 vcpkg 库之间不应有任何区别。 为此,我们避免将 CMake 导出或目标添加到具有“明显名称”的现有库,以允许上游添加自己的官方 CMake 导出,而不会与 vcpkg 冲突。
为此,端口导出的任何 CMake 配置(不在上游库中)都应将 unofficial- 作为前缀。 任何其他目标都应位于 unofficial::<port>:: 命名空间中。
这意味着用户应看到:
-
find_package(unofficial-<port> CONFIG)作为获取 unique-to-vcpkg 包的途径 -
unofficial::<port>::<target>作为从该端口导出的目标。
示例:
-
brotli创建unofficial-brotli包,生成目标unofficial::brotli::brotli。
安装版权文件
每个端口都必须在文件夹 copyright 中提供一个名为 ${CURRENT_PACKAGES_DIR}/share/${PORT} 的文件。 如果包的许可证内容在其源文件中可用,则应通过调用 vcpkg_install_copyright() 创建此文件。 如有必要,vcpkg_install_copyright 还可捆绑多个版权文件。
vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")
手动创建此文件的旧方法是使用 CMake 的内置 file 命令。 不建议在改用 vcpkg_install_copyright 的新端口中使用此命令,但仍允许这样做。
file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)
如果上游源文件中的许可证内容并非文本格式(例如 PDF 文件),则 copyright 应包含用户如何找到许可证要求的说明。 如果可能,该文件还应包含指向原始源文件的链接来表明这一点,以便用户可以检查其是否最新。
file(WRITE "${CURRENT_PACKAGES_DIR}/share/${PORT}/copyright" [[As of 2023-07-25, according to
https://github.com/GPUOpen-LibrariesAndSDKs/display-library/blob/master/Public-Documents/README.md#end-user-license-agreement
this software is bound by the "SOFTWARE DEVELOPMENT KIT LICENSE AGREEMENT" PDF located at
https://github.com/GPUOpen-LibrariesAndSDKs/display-library/blob/master/Public-Documents/ADL%20SDK%20EULA.pdf
]])
端口中的版本约束
通常应避免端口内的版本约束,因为它们可能会阻碍组件的独立演变。 只有在有充分证据的情况下,才允许添加此类约束,例如证明与特定早期版本不兼容。 不应仅使用这些约束来保持与独立组件的一致。
中的 MAYBE_UNUSED_VARIABLES 变量必须应用于至少一个配置
在 CMake 配置步骤中添加新变量 MAYBE_UNUSED_VARIABLES 以静音警告时,必须添加注释来解释新变量应用时的情况。 如果变量在任何配置中都不适用,则很可能存在潜在缺陷(例如变量名称拼写错误),并且添加该变量对构建没有实际影响。
vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
FEATURES
windowsfeature WINDOWS_OPTION
)
vcpkg_cmake_configure(
SOURCE_PATH "${SOURCE_PATH}"
OPTIONS
${FEATURE_OPTIONS}
MAYBE_UNUSED_VARIABLES
WINDOWS_OPTION # Applies only on Windows
)
功能
请勿使用功能实现备选方案
功能必须被视为附加功能。 如果安装了 port[featureA] 和 port[featureB],则必须安装 port[featureA,featureB]。 此外,如果第二个端口依赖于 [featureA] 而第三个端口依赖于 [featureB],则同时安装第二个和第三个端口应满足其依赖项。
在这种情况下,库必须选择 vcpkg 中表示的可用选项之一,并且想要其他设置的用户此时必须使用覆盖端口。
保留我们目前不接受的现有示例以实现后向兼容性:
-
libgit2、libzip、open62541都有选择 TLS 或加密后端的功能。curl有不同的加密后端选项,但允许在运行时在这些选项之间进行选择,这意味着维持上述原则。 -
darknet有opencv2、opencv3,即控制其依赖项使用哪个版本 opencv 的功能。
可能涉及预览版或 beta 版功能一项功能
尽管有上述功能,但如果预览分支或类似的分支,预览功能很有可能不会中断非预览功能(例如,没有 API 移除),因此可接受使用某一功能对此设置进行建模。
示例:
- Azure SDK(形式为
azure-Xxx)具有public-preview功能。 -
imgui具有experimental-docking功能,后者使用附加到每个公共编号版本的合并提交来参与其预览停靠分支。
默认功能不得添加 API
注释
上游生成系统默认启用的功能并不意味着应将该功能添加到 default-features 条目。 根据预期目的,default-features 并不是为了对上游做出的决策进行建模,而是为了为 经典模式 用户提供便利。
默认功能旨在确保:对于那些并不知道自己正在使用某个库的客户,也能安装一个功能合理的库构建。 如果他们不知道自己在使用某个库,就无法知道要列出哪些功能。 例如,libarchive 向现有泛型接口公开用来启用压缩算法的功能;如果不具备这些功能,库可能毫无用处。
此处,客户既涵盖使用该包图的用户项目,也涵盖该图内的下游端口。 两者都通过相同的功能接口表达其依赖项要求。
请仔细考虑是否应默认启用某个功能,因为禁用默认功能很复杂。
若要禁用可传递依赖项的默认功能,请执行以下操作:
- 每个依赖该端口的依赖方都必须使用
"default-features": false在其依赖声明中禁用默认特性。 - 顶级项目还必须直接命名传递依赖项,可以在其包含
"default-features": false的清单中进行,或者在vcpkg install命令行中使用[core]。
禁用默认功能不会阻止另一位客户显式请求其中任何一项功能。
对于此策略,API 是向使用者公开的任何接口,包括库接口、可执行命令行接口和其他二进制接口。 当某个功能是通过现有 API 增加功能时,可能会默认启用该功能,例如通过现有的通用接口支持其他压缩算法。
在 vcpkg 的特选注册表中,如果某个功能添加了 API,则默认情况下必须关闭该功能。 如有疑问,请勿将功能标记为默认值。
不要使用功能来控制已发布接口中的备选方案
如果端口的使用者仅依赖于该端口的核心功能,则启用该功能可能不会破坏这些功能。 当备选方案并非由使用者直接控制,而是由编译器设置(例如 /std:c++17 / -std=c++17)控制时,这一点更为重要。
保留我们目前不接受的现有示例以实现后向兼容性:
-
redis-plus-plus[cxx17]控制 polyfill,但不会将设置嵌入到已安装的树中。 -
ace[wchar]更改所有 API 以接受const wchar_t*而不是const char*。
某项功能可以用别名替换 polyfill,前提是替换已嵌入已安装的树中
尽管有上述功能,但端口可能会移除包含某项功能的 polyfill,只要满足以下条件:
- 启用该功能会将 polyfill 更改为已填充实体的别名
- polyfill 的状态将嵌入已安装的标头中,以使 ABI 不太可能不匹配“不可能”运行时错误
- 端口使用者可以使用这两种模式编写代码,例如,使用已填充或未填充的 typedef
示例:
-
abseil[cxx17]将absl::string_view更改为替换或std::string_view;修补程序将实现放置要求。
建议的解决方案
如果公开基础备选方案至关重要,我们建议在构建时提供消息,以指示用户如何将端口复制到专用覆盖:
set(USING_DOG 0)
message(STATUS "This version of LibContoso uses the Kittens backend. To use the Dog backend instead, create an overlay port of this with USING_DOG set to 1 and the `kittens` dependency replaced with `dog`.")
message(STATUS "This recipe is at ${CMAKE_CURRENT_LIST_DIR}")
message(STATUS "See the overlay ports documentation at https://github.com/microsoft/vcpkg/blob/master/docs/specifications/ports-overlay.md")
构建技术
不要使用供应商的依赖项
更倾向于单独打包依赖项,以便用户可以通过 vcpkg 选择和更新依赖项。 随项目附带的依赖项引入了几个挑战:
- 难以更新:内置依赖项更难跟踪和更新,尤其是在应用安全修复时。
- 符号冲突: 随附的依赖项可以定义与另一版本的依赖项相同的符号,从而导致运行时错误或未定义的行为。
- 许可合规性: 内置的依赖项可能会掩盖许可要求或造成许可证兼容性问题。
- 维护负担增加:使随附依赖与其上游版本保持同步会增加维护工作,并可能在不同端口之间造成重复工作。
出于这些原因,只要实际可行,都应取消内置依赖。 内置依赖不得暴露到用户的链接域。
链接域是可在运行时相互解析的符号集。 在Windows上,每个 DLL 通常都有自己的链接域。 在具有进程范围的符号表的平台上,链接域通常包括整个进程。
如果某个组件将内置依赖暴露到与通过 vcpkg 选择的依赖相同的链接域中,那么这两个副本可能会定义相同的符号。 这违反了单一定义规则,可能会导致运行时错误或未定义行为。 仅当两个版本差异足以不兼容时,才会出现此问题。
仅当内置依赖与下游端口和用户应用程序所使用的链接域完全隔离时,才允许使用内置依赖。 例如,如果下游二进制文件未链接到该工具,并且依赖项的符号无法进入其链接域,则仅主机使用的构建工具可以包含静态链接的依赖项。
首选使用 CMake
当有多个构建系统可用时,首选使用 CMake。
此外,在适当的时候,使用 file(GLOB) 指令将备选构建系统重写为 CMake 可能更容易且更易于维护。
示例:abseil
选择静态或共享的二进制文件
在生成 CMake 库时,vcpkg_cmake_configure() 将根据用户请求的变体传递 BUILD_SHARED_LIBS 的正确值。
可以使用 string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" ...) 计算替代配置参数。
# portfile.cmake
string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "static" KEYSTONE_BUILD_STATIC)
string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "dynamic" KEYSTONE_BUILD_SHARED)
vcpkg_cmake_configure(
SOURCE_PATH ${SOURCE_PATH}
OPTIONS
-DKEYSTONE_BUILD_STATIC=${KEYSTONE_BUILD_STATIC}
-DKEYSTONE_BUILD_SHARED=${KEYSTONE_BUILD_SHARED}
)
如果库不提供配置选项来选择构建变体,则必须对构建进行修补。 修补生成时,应始终尝试最大程度地提高端口的未来可维护性。 通常,这意味着要尽量减少需要修改的行数以解决当前的问题。
示例:修补 CMake 库以避免生成不需要的变体
例如,在修补基于 CMake 的库时,向不需要的目标添加 EXCLUDE_FROM_ALL 并将 install(TARGETS ...) 调用封装在 if(BUILD_SHARED_LIBS) 中可能就足够了。 这将比换行或删除提及不需要的变体的每一行要短。
对于包含以下内容的项目 CMakeLists.txt:
add_library(contoso SHARED contoso.c)
add_library(contoso_static STATIC contoso.c)
install(TARGETS contoso contoso_static EXPORT ContosoTargets)
install(EXPORT ContosoTargets
FILE ContosoTargets
NAMESPACE contoso::
DESTINATION share/contoso)
将 install(TARGETS) 行替换为条件块,该块还会从默认生成中排除不需要的目标:
add_library(contoso SHARED contoso.c)
add_library(contoso_static STATIC contoso.c)
if(BUILD_SHARED_LIBS)
set_target_properties(contoso_static PROPERTIES EXCLUDE_FROM_ALL 1)
install(TARGETS contoso EXPORT ContosoTargets)
else()
set_target_properties(contoso PROPERTIES EXCLUDE_FROM_ALL 1)
install(TARGETS contoso_static EXPORT ContosoTargets)
endif()
install(EXPORT ContosoTargets
FILE ContosoTargets
NAMESPACE contoso::
DESTINATION share/contoso)
定义功能时,显式控制依赖项
定义捕获可选依赖项的功能时,请确保在未显式启用该功能时不会意外使用依赖项。
set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON)
set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB OFF)
if ("zlib" IN_LIST FEATURES)
set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF)
set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB ON)
endif()
vcpkg_cmake_configure(
SOURCE_PATH ${SOURCE_PATH}
OPTIONS
-DCMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB}
-DCMAKE_REQUIRE_FIND_PACKAGE_ZLIB=${CMAKE_REQUIRE_FIND_PACKAGE_ZLIB}
)
下面使用 vcpkg_check_features() 的代码段是等效的。
vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
FEATURES
"zlib" CMAKE_REQUIRE_FIND_PACKAGE_ZLIB
INVERTED_FEATURES
"zlib" CMAKE_DISABLE_FIND_PACKAGE_ZLIB
)
vcpkg_cmake_configure(
SOURCE_PATH ${SOURCE_PATH}
OPTIONS
${FEATURE_OPTIONS}
)
代码段中的 ZLIB 区分大小写。 有关详细信息,请参阅 CMAKE_DISABLE_FIND_PACKAGE_<PackageName> 和 CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> 文档。
将冲突库放在 manual-link 目录中
如果安装在 lib 或 debug/lib 中的链接器输入文件(例如 .lib、.a、.so 或 .dylib 文件)有以下任一行为,则将其视为存在冲突:
- 定义
main。 - 定义
malloc。 - 定义在其他库中也定义的符号。
某些链接器输入文件有意为使用方原本会在其他位置定义或获取的符号提供范围较窄的替换。 例如,Google Test 的 gtest-main.lib 为测试可执行文件提供 main,这些测试可执行文件的作者选择使用它,而不是自行定义入口点。
将存在冲突的链接器输入文件置于 lib/manual-link 或 debug/lib/manual-link 中,这样自动从库目录中链接文件的构建系统就不会选中它们。 Windows DLL 保留在bin或debug/bin;需要显式链接时,将其导入库放在manual-link中。 使用者必须明确选择链接这些文件,并负责避免出现冲突的定义。 此异常不是打包另一个组件的替代提供程序的一般机制,并且将链接器输入文件移动到 manual-link 中不会将其符号与使用者的链接域隔离开来。
安装预生成的二进制文件
允许安装预生成(仅二进制)构件的端口,但强烈建议不要这样做,前提是这些构件不会阻止用户通过 vcpkg 选择或更新依赖项。 首选从源代码构建,因为它遵循控制编译器和标志的 vcpkg 设置。
我们将拒绝满足以下所有条件的端口:
- 安装预生成的二进制文件,而不是从源生成,以及
- 这些二进制文件包含或在运行时需要由特选注册表中的其他端口提供的依赖项,以及
- 已安装的构件会将这些依赖暴露到一个链接域中,而该链接域也可能包含通过 vcpkg 选择的版本。
此组合有效地将依赖项图锁定到生成上游预生成时使用的版本。
如果 vcpkg 更新依赖项(如 zlib 或 openssl),则预生成版本和用户选择的版本可以在同一链接域中定义不兼容的符号。 这可能会导致单一定义规则冲突、ABI 不兼容或错过安全更新。
只要某个依赖参与了用户的链接域,构件就会暴露该依赖,无论上游是否有意暴露它。 这包括:
- 使用者可链接的
.lib、.a、.so、.dylib或将依赖项引入用户链接域的导入库。 - 已安装的标头引用(直接或通过内联/模板代码)来自其他 vcpkg 端口的符号、类型或宏。
- 已安装的在其他 vcpkg 端口中调用
find_dependency()或Requires:的 CMake 配置或 pkg-config 文件。
允许(但仍不鼓励)的方案:
- 仅在构建时使用的主机专用辅助工具,其输出会被使用,但依赖的端口不会链接它们;前提是这些工具隔离了捆绑依赖,或仅依赖普遍存在的系统运行时库。
- 预生成库的捆绑依赖项完全保留在单独的链接域中,并且不会显示在已安装的标头或导出的接口中。 仅静态链接不会将依赖项与用户的链接域隔离开来。
- 纯数据、固件或资产包不会链接到用户代码中。
禁止的示例:
- 一个预生成的库,该库静态链接其专用副本
zlib并将其符号公开给还可以包含通过 vcpkg 选择的zlib版本的链接域。 - 预生成的
libfoo可安装lib/libfoo.lib以及头文件(包括<zlib.h>),并且是针对特定zlib版本编译的;随后使用者会链接libfoo并期望其兼容。 - 预构建的 SDK,它会安装一个调用
find_dependency(OpenSSL)的 CMake 包文件,而其中的二进制文件是针对较旧版本的 OpenSSL 编译的。
缓解措施/替代方法:
- 提供使用上游脚本的从源码构建,或添加一个精简 CMake 包装器。
- 要求上游发布基于源代码的版本或可重复构建的指令,在注释
portfile.cmake或vcpkg.json中链接上游的问题/PR。 - 对无法满足这些规则的组织特定的预生成使用覆盖端口或专用注册表。
版本控制
遵循 "version" 字段的通用约定
创建新端口时,请遵循包作者所使用的版本控制约定。 更新端口时,除非上游另有说明,否则,请继续使用同一约定。 有关约定的完整说明,请参阅我们的版本控制文档。
如果上游有一段时间未发布版本,请不要将端口的版本控制方案更改为 version-date 来获取最新更改。 这些提交可能包括尚未准备好用于生产的更改。 改为要求上游存储库发布新版本。
更新每个已修改端口的 "port-version" 字段
修改端口的每个 PR 都必须生成该端口的新版本。 PR 采用压缩合并,因此每个修改端口的版本在每个 PR 中只更新一次,而不是每次提交或每次评审修订都更新一次。
如果上游版本未更改,请递增 "port-version" 字段。 如果上游版本已更改,请通过删除该字段或将其设置为 0,将 "port-version" 重置为零。
例如:
- Zlib 的包版本目前为
1.2.1,没有显式"port-version"(相当于"port-version"为0)。 - 你发现部署了错误的版权文件,并在端口配置文件中修复了这个问题。
- 应将清单文件中的
"port-version"字段更新为1。
有关详细信息,请参阅版本控制文档。
更新 versions/ 中每个已修改的端口的版本文件
vcpkg 使用一组元数据文件为其版本控制功能提供支持。 这些文件位于以下位置:
-
${VCPKG_ROOT}/versions/baseline.json,(此文件对所有端口通用)和 -
${VCPKG_ROOT}/versions/${first-letter-of-portname}-/${portname}.json(每个端口一个)。
例如,对于 zlib,相关文件包括:
${VCPKG_ROOT}/versions/baseline.json${VCPKG_ROOT}/versions/z-/zlib.json
对于 PR 中的每个修改端口,请更新其版本文件以记录最终的 Git 树。 如果在评审期间进行进一步更改,请运行 vcpkg x-add-version <port-name> --overwrite-version 以刷新未合并的版本条目
而不再次递增"port-version"。
更新这些文件的建议方法是运行 x-add-version 命令,例如:
vcpkg x-add-version zlib
如果要同时更新多个端口,可以改为运行:
vcpkg x-add-version --all
一次更新所有已修改端口的文件。
补丁
vcpkg 是一种打包解决方案,而不是我们所部署组件的最终所有者。 在某些情况下,我们需要应用修补程序,以提高组件与平台的兼容性,或相互兼容性。
- 我们希望避免出现如下修补程序:
- 上游可能会不同意
- 导致漏洞或崩溃
- 我们无法在上游版本更新中进行维护
- 足够大,导致与 vcpkg 存储库本身的许可证纠缠
上游通知和等待期
上游所有者是其组件行为的最终裁决者。 vcpkg 维护者要求对与上游相关的补丁进行上游通知,并且对于新端口提交中由 AI 代码评审工具识别出的 bug,也要求通知上游。
与上游相关的补丁
如果某个修补程序可能对上游有用,vcpkg 维护者要求将修补程序内容通知上游。 应用与上游无关的 vcpkg 特定行为的修补程序,例如开发依赖项,不需要通知。
为了避免上游不同意该补丁的情况,vcpkg 维护者在通知上游后至少等待 30 天,然后再应用此类修补程序。
如果 vcpkg 维护人员对更改正确充满信心,则 vcpkg 维护人员会跳过此等待期。 高置信度修补程序示例包括,但不限于:
- 上游接受作为修补程序(例如,从上游的拉取请求向后移植特定更改已合并)。
- 添加缺失的
#include。 - 小而明显的产品代码修复(例如,初始化未初始化的变量)。
- 禁用构建的 irrelevant-in-vcpkg 组件,例如测试或示例。
新端口中由 AI 发现的 bug
精选注册表旨在避免分发已知存在可被利用漏洞的代码,但 vcpkg 维护者无法全面审核每个组件的源代码。 AI 代码评审结果本身并不是认定上游代码存在漏洞的最终结论。
当 AI 代码审查工具在审查新端口提交时发现 bug,vcpkg 维护者要求将该 bug 报告给上游;对于可能被利用的 bug,应遵循项目的安全报告流程。 即使发现的问题涉及端口未修补的上游代码,此要求也适用。
- 如果上游确定报告的行为不是 bug,vcpkg 维护者会接受该决定作为最终决定,并且不会根据该发现拒绝新 port 的提交。
- 如果上游修复了该 bug,则 vcpkg 维护者会接受修复后的版本或经上游批准的修补程序,但须符合修补政策以及新端口的其他要求。
- 如果上游在报告 bug 后 30 天内未响应,vcpkg 维护者默认将 AI 发现视为可利用的问题并关闭新端口提交。
修补程序等待期的高置信度异常不会免除此 bug 报告要求或上游响应的需求。
首选选项优先于修补
最好在调用 vcpkg_configure_xyz() 时设置选项,而不是直接修补设置。
可以避免修补的常用选项:
- [MSBUILD] 项目文件内的
<PropertyGroup>设置可以通过/p:参数覆盖 - [CMAKE] 通过
find_package(XYz)可以禁用对 CMake 脚本中-DCMAKE_DISABLE_FIND_PACKAGE_XYz=ON的调用 - [CMAKE] 缓存变量(声明为
set(VAR "value" CACHE STRING "Documentation")或option(VAR "Documentation" "Default Value"))可通过仅在命令行中作为-DVAR:STRING=Foo传入进行覆盖。 一个值得注意的例外是将FORCE参数传递给set()的情况。 有关详细信息,请参阅 CMakeset文档
更喜欢下载已批准的修补程序,而不是将其签入端口
如果可从上游提交获取已批准或已合并的修补程序,请下载并应用该修补程序,而不是将其签入端口。 此过程是首选的,因为它:
- 确认上游已接受修补程序更改。
- 通过将责任前移来简化评审过程。
- 减少未使用修补程序的用户的 vcpkg 存储库大小。
- 避免与 vcpkg 存储库发生许可证冲突。
仅从固定到完整提交 ID 的 URL 下载修补程序,而不要从内容可能变化的拉取请求或合并请求差异 URL 下载修补程序。 从 GitHub 或 GitLab 下载提交修补程序时,请追加?full_index=1到 URL。 此参数请求差异中的完整对象 ID;它不会使可变 URL 不可变。
例如:
修补优先于覆盖 VCPKG_<VARIABLE> 值
前缀为 VCPKG_<VARIABLE> 的一些变量具有等效 CMAKE_<VARIABLE>。
但是,并非所有变量都传递到内部包构建(请参阅实现:Windows 工具链)。
请考虑以下示例:
set(VCPKG_C_FLAGS "-O2 ${VCPKG_C_FLAGS}")
set(VCPKG_CXX_FLAGS "-O2 ${VCPKG_CXX_FLAGS}")
使用 vcpkg 内置的工具链可以正常工作,因为 VCPKG_<LANG>_FLAGS 的值将转发给相应的 CMAKE_<LANG>_FLAGS 变量。 但是,不知道 vcpkg 变量的自定义工具链不会进行转发。
因此,首选在设置 CMAKE_<LANG>_FLAGS 时直接修补构建系统。
尽量减少补丁
对库进行更改时,尽量减少最终差异。 这意味着,在进行更改影响区域时,不应重新设置上游源代码格式。 禁用条件时,最好向条件添加 AND FALSE 或 && 0,而不是删除条件的每一行。 如果需要禁用大型区域,则在区域周围添加 if(0) 或 #if 0 比删除补丁中的每一行更短。
如果端口已过时,不要添加修补程序,将端口更新为较新的发布版本可以解决相同的问题。 vcpkg 更喜欢更新端口,而不是修补过时的版本。
这有助于缩小 vcpkg 存储库的大小,并提高修补程序将应用于未来代码版本的可能性。
请勿在修补程序中实现功能
在 vcpkg 中修补的目的是实现与编译器、库和平台的兼容性。 其并非要实现新功能取代以下适当的开放源代码过程(提交问题/PR/等)。
默认情况下不要构建测试/文档/示例
提交新端口时,请检查 BUILD_TESTS、WITH_TESTS 或 POCO_ENABLE_SAMPLES 等任何选项,并确保禁用其他二进制文件。 这将最大限度地缩短普通用户的构建时间和减少依赖项。
(可选)可以添加一项 test 功能来构建测试,但这不应该出现在 Default-Features 列表中。
使库的现有用户能够切换到 vcpkg
不要添加 CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS
除非库的作者已经在使用,否则我们不应使用此 CMake 功能,因为它与 C++ 模板交互不佳,并破坏了某些编译器功能。 不提供 .def 文件且不使用 __declspec() 声明的库根本不支持 Windows 的共享版本,应标记为:
if(VCPKG_TARGET_IS_WINDOWS)
vcpkg_check_linkage(ONLY_STATIC_LIBRARY)
endif()
不要在上游给定的名称之外重命名二进制文件
这意味着,如果上游库在发布和调试时具有不同的名称(libx 与 libxd),则不应将调试库重命名为 libx。 反之亦然,如果上游库在发布和调试时具有相同的名称,则不应引入新名称。
重要注意事项:
- 静态和共享变体通常应重命名为通用方案。 这使使用者能够使用公用名并忽略下游链接。 这是安全的,因为我们一次只提供一个。
如果库构建 CMake 集成文件 (foo-config.cmake),则必须通过修补 CMake 构建本身来完成重命名,而不是简单地在输出存档/库上调用 file(RENAME)。
最后,Windows 上的 DLL 文件不应在构建后重命名,因为这会破坏构建的 LIB。
清单
我们需要格式化清单文件。 使用以下命令设置所有清单文件的格式:
> vcpkg format-manifest --all
三元组
我们目前不接受添加非社区三元组的请求。 从社区提升到完全三元状态主要基于硬件测试此类三重体的预算,并将由 vcpkg 提交的指标驱动,以最大程度地提高人们实际使用的可能性。从社区升级到完整三元组状态主要基于测试此类三元组的硬件预算,并将由 vcpkg 提交的指标驱动,以最大限度地提高人们实际使用的内容得到充分测试的可能性。
如果出现以下情况,我们将添加社区三元组:
- 事实证明,人们实际上会使用该社区三元组;以及
- 我们不知道这样的三元组是否被破坏。
例如,我们没有在 https://github.com/microsoft/vcpkg/pull/29034 中添加三元组,因为作者只是试图“完成集合”,而并不是表明其实际上会使用这样的东西。我们直到创建了 patchelf 解决方案,以使结果可重定位后,才添加了 linux-dynamic。
有用的实现说明
端口文件在脚本模式下运行
虽然 portfile.cmake 和 CMakeLists.txt 共享通用语法和核心 CMake 语言构造(即“脚本命令”),但端口文件在“脚本模式”中运行,而 CMakeLists.txt 文件在“项目模式”中运行。 这两种模式之间最重要的区别是,“脚本模式”没有“工具链”、“语言”和“目标”的概念。 依赖于这些构造(例如,CMAKE_CXX_COMPILER、CMAKE_EXECUTABLE_SUFFIX、CMAKE_SYSTEM_NAME)的任何行为(包括脚本命令)都不正确。
端口文件可以直接访问三元组文件中设置的变量,但 CMakeLists.txt 不能(尽管经常会发生转换 - VCPKG_LIBRARY_LINKAGE 与 BUILD_SHARED_LIBS)。
端口文件和端口文件调用的项目构建在不同的进程中运行。 从概念上讲:
+----------------------------+ +------------------------------------+
| CMake.exe | | CMake.exe |
+----------------------------+ +------------------------------------+
| Triplet file | ====> | Toolchain file |
| (x64-windows.cmake) | | (scripts/buildsystems/vcpkg.cmake) |
+----------------------------+ +------------------------------------+
| Portfile | ====> | CMakeLists.txt |
| (ports/foo/portfile.cmake) | | (buildtrees/../CMakeLists.txt) |
+----------------------------+ +------------------------------------+
要确定端口文件中的主机,标准 CMake 变量足以 (CMAKE_HOST_WIN32)。
要确定端口文件中的目标,应使用 vcpkg 三元组变量 (VCPKG_CMAKE_SYSTEM_NAME)。
另请参阅我们的三元组文档,以全面了解可能的设置选项。