通过

为端口提供使用情况文档

  • 项目

概述

为端口提供使用文档可让用户在项目中轻松采用这些文档。 强烈建议在端口的目录 (ports/<port name>/usage) 中提供 usage 文件来描述与版本系统集成必须的最少步骤。

提供使用情况文件

若要提供使用情况文档，请在端口的 share 安装目录中创建名为“usage”的文本文件。 建议方法是在 portfile.cmake 中调用 configure_file() 函数。

例如：

configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" "${CURRENT_PACKAGES_DIR}/share/${PORT}/usage" COPYONLY)

安装端口后，vcpkg 会检测安装到 ${CURRENT_PACKAGES_DIR}/share/${PORT}/usage 的文件并输出其使用说明。

内容格式

提供有关如何使用包的明确说明。 内容应做到简洁，结构清晰，并且重点突出要使用库所需的最小版本系统集成。

介绍如何有效利用包时，要做到简洁明了。 避免将一大堆代码片段、命令行指令或配置详细信息，一股脑地摆在用户面前。 请改为使用端口 vcpkg.json 文件中的 "documentation" 属性，让用户可以详细了解库。

使用以下模板作为 usage 文件的模式：

具有 CMake 目标的包：

<port> provides CMake targets:

    <instructions>

仅标头库：

<port> is header-only and can be used from CMake via:

    <instructions>

usage 文件示例

proj provides CMake targets:

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