跳到主要内容

编写脚本端口

脚本端口（也称为辅助端口）用于向其他端口暴露函数，供其在构建过程中调用。例如，kmpkg-cmake 端口定义了 kmpkg_cmake_configure() 函数，供其他端口调用。将通用脚本封装为辅助端口后，维护工作会更高效（只需在单一位置更新代码）；此外，辅助端口可像普通端口一样进行版本控制和依赖管理。

工作原理​

辅助端口基于 kmpkg-port-config.cmake 扩展机制实现，核心规则如下：

  1. 执行某端口前，kmpkg 会自动导入该端口直接依赖项所导出的所有 kmpkg-port-config.cmake 文件；
  2. 若辅助端口依赖另一个辅助端口，需显式导入依赖项的 kmpkg-port-config.cmake 文件；且辅助端口之间的依赖不应标记为主机依赖，确保两个脚本安装在同一目录下并相互依赖；
  3. 依赖辅助端口的普通端口，需将该依赖标记为主机依赖；
  4. 辅助端口必须将 kmpkg-port-config.cmake 文件安装到安装目录结构的 share/${PORT} 子目录中。

示例：编写简单的辅助端口​

步骤 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：创建辅助端口的 portfile.cmake 文件​

创建 my-helper/portfile.cmake，内容如下：

# 启用辅助端口专属的构建后检查策略
set(KMPKG_POLICY_CMAKE_HELPER_PORT enabled)

# 安装辅助函数文件和配置文件到指定目录
file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/my_helper_function.cmake" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")
file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/kmpkg-port-config.cmake" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")

# 安装许可证文件（重命名为 copyright，符合 kmpkg 规范）
file(INSTALL "${KMPKG_ROOT_DIR}/LICENSE.txt" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)
  • KMPKG_POLICY_CMAKE_HELPER_PORT：启用该策略后，kmpkg 会执行辅助端口专属的构建后检查，包括：kmpkg-port-config.cmake 路径是否正确、是否向 include 目录安装了文件（辅助端口不应在此目录安装文件）；
  • 核心操作：将辅助函数文件、配置文件和许可证文件安装到 share/${PORT} 目录（辅助端口的标准安装路径）。

步骤 3：创建辅助端口的 kmpkg.json 文件​

创建 my-helper/kmpkg.json，内容如下：

{
  "name": "my-helper",
  "version-date": "2024-03-20",  // 辅助端口推荐使用日期版本方案
  "description": "Provide my_helper_function()",
  "license": "MIT",
  "dependencies": [ 
    { "name": "my-other-helper" }  // 依赖另一个辅助端口（不标记为 host）
  ]
}
  • 版本方案：推荐为辅助端口使用 version-date（日期型版本），符合 kmpkg 版本规范；
  • 依赖规则：辅助端口之间的依赖不标记为 host（区别于普通端口依赖辅助端口）。

步骤 4：创建辅助端口的 kmpkg-port-config.cmake 文件​

创建 my-helper/kmpkg-port-config.cmake，内容如下：

include_guard(GLOBAL)  # 全局包含保护

# 显式导入依赖的辅助端口配置文件
include("${CMAKE_CURRENT_LIST_DIR}/../my-other-helper/kmpkg-port-config.cmake")
# 导入当前辅助端口的函数定义文件
include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function.cmake")
  • 核心作用：
    1. 导入依赖的 my-other-helper 配置文件，使得依赖 my-helper 的端口无需显式依赖 my-other-helper 即可使用其函数；
    2. 导入自身的函数定义文件，对外暴露 my_helper_function。

步骤 5：在普通端口中使用 my-helper​

使用辅助端口的普通端口，只需在其 kmpkg.json 中添加对 my-helper 的主机依赖，无需依赖 my-other-helper。

1. 消费端 kmpkg.json（my-port/kmpkg.json）​

{
  "name": "my-port",
  "version": "1.0.0",
  "dependencies": [
    {
      "name": "my-helper",
      "host": true  // 普通端口依赖辅助端口需标记为 host
    }
  ]
}

2. 消费端 portfile.cmake（my-port/portfile.cmake）​

# 直接调用辅助端口暴露的函数
my_helper_function()

此时，my-port 构建时会自动加载 my-helper 的配置文件，成功调用 my_helper_function。