创作帮助程序端口

项目
05/06/2024

帮助程序端口（也称为脚本端口）公开函数，供其他端口在其生成过程中使用。例如，vcpkg-cmake 端口定义 vcpkg_cmake_configure() 函数供其他端口使用。通过将公用脚本打包到帮助程序端口中，可以在单个位置进行更新，从而使维护变得更加简化。此外，可以使用与常规端口相同的机制对帮助程序端口进行版本控制和依赖。

它们如何工作？

帮助程序端口通过 vcpkg-port-config.cmake 扩展机制实现。

在执行端口之前，vcpkg 将导入由即将执行的端口的直接依赖项导出的任何 vcpkg-port-config.cmake 文件。

如果一个帮助程序端口依赖于其他帮助程序端口，则必须显式导入其依赖项的 vcpkg-port-config.cmake 文件。不应将帮助程序到帮助程序端口依赖项标记为主机依赖项，这可确保一个脚本可以依赖于同一安装目录中的另一个脚本。

依赖于帮助程序端口的端口应将依赖项标记为主机依赖项。

帮助程序端口必须始终在安装树的 share/${PORT} 子目录中安装其 vcpkg-port-config.cmake 文件。

示例：编写简单的帮助程序端口

1 - 创建定义帮助程序函数的 CMake 文件。

my-helper/my_helper_function.cmake

include_guard(GLOBAL)

function(my_helper_function)
  message(STATUS "my_helper_function() was called")
  my_other_helper_function()
endfunction()

当文件被多次包含时，文件顶部的 include_guard(GLOBAL) 可防止重新定义此函数。

以下几行声明了一个名为 my_helper_function 的函数，该函数显示一条消息并调用在另一个帮助程序端口中定义的 my_other_helper_function。

2 - 创建帮助程序端口的 porftile.cmake 文件

my-helper/portfile.cmake

set(VCPKG_POLICY_HELPER_PORT enabled)

file(INSTALL
  "${CMAKE_CURRENT_LIST_DIR}/vcpkg-port-config.cmake"
  DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")

file(INSTALL "${VCPKG_ROOT_DIR}/LICENSE.txt" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)

通过启用 VCPKG_POLICY_HELPER_PORT 策略，vcpkg 可以启用专门适用于帮助程序端口的生成后检查。具体来说，检查 vcpkg-port-config.cmake 是否安装在正确的路径中，以及 include 目录中是否没有安装任何文件。

接下来的几行将所需的 vcpkg-port-config.cmake 和 copyright 文件安装在正确的位置 (share/${PORT})。

3 - 创建帮助程序端口的 vcpkg.json 文件

my-helper/vcpkg.json

{
  "name": "my-helper",
  "version-date": "2024-03-20",
  "description": "Provide my_helper_function()",
  "license": "MIT",
  "dependencies": [ 
    { "name": "my-other-helper" } 
  ]
}

建议使用 version-date 作为帮助程序端口的版本控制方案。

本示例中的 dependencies 包含对另一个名为 my-other-helper 的帮助程序端口的引用。故意不将依赖项标记为主机依赖项，因为这是一个帮助程序到帮助程序的端口依赖项。

4 - 创建帮助程序端口的 vcpkg-port-config.cmake 文件

my-helper/vcpkg-port-config.cmake

include_guard(GLOBAL)

include("${CMAKE_CURRENT_LIST_DIR}/../my-other-helper/vcpkg-port-config.cmake")
include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function.cmake")

vcpkg-port-config.cmake 文件由三行组成，第一行是全局包含防护，可防止文件被多次包含。

第二行包含 my-other-helper/vcpkg-port-config.cmake，使 my-other-helper 中的函数可供依赖 my-helper 的端口使用，而不必将 my-other-helper 包含在其直接依赖项列表中。

最后，还包括 my_helper_function.cmake 文件，其中包含 my_helper_function 定义。

5 - 在清单中使用 my-helper

my-helper 的任何使用者只需要包含对 my-helper 本身的直接依赖，而不需要对 my-other-helper 的依赖。使用清单应将依赖项标记为主机依赖项。

my-port/vcpkg.json

{
  "name": "my-port",
  "version": "1.0.0",
  "dependencies": [
    {
      "name": "my-helper",
      "host": true
    }
  ]
}

这使得 my_helper_function 在 my-port/portfile.cmake 中可用。

my-port/portfile.cmake

my_helper_function()

通过

创作帮助程序端口

它们如何工作？

示例：编写简单的帮助程序端口

其他资源