为你的端口提供使用文档

概述

为端口提供使用文档能让用户轻松将其集成到自己的项目中。我们强烈建议在端口目录（ports/<端口名称>/）下创建一个 usage 文件，描述与构建系统集成所需的最小步骤。

提供 usage 文件

要添加使用文档，需创建一个名为 usage 的文本文件，并将其安装到端口的 share 目录下。推荐的方式是在 portfile.cmake 中调用 file(INSTALL ...) 函数：

示例：

file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")

用户安装端口后，kmpkg 会自动检测 ${CURRENT_PACKAGES_DIR}/share/${PORT}/usage 路径下的文件，并在安装完成后打印其中的使用说明。

内容格式

使用文档应清晰说明如何使用该包，内容需简洁、结构化，重点突出集成到构建系统的最小必要步骤。

避免使用过多代码片段、命令行指令或配置细节让用户感到冗余。若需提供更详细的信息，可通过端口 kmpkg.json 文件中的 "documentation" 属性 指向官方文档，方便用户深入学习。

可参考以下模板编写 usage 文件：

带 CMake 目标的包：

<端口名> 提供 CMake 目标：

  <具体使用指令>

仅头文件库：

<端口名> 是仅头文件库，可通过以下 CMake 方式使用：

  <具体使用指令>

usage 文件示例

proj 提供 CMake 目标：

  find_package(PROJ CONFIG REQUIRED)
  target_link_libraries(main PRIVATE PROJ::proj)