Proporcionar documentación de uso para los puertos

Información general

Proporcionar documentación de uso para los puertos permite a los usuarios adoptarlos fácilmente en sus proyectos. Se recomienda encarecidamente proporcionar un usage archivo dentro del directorio del puerto (ports/<port name>/usage) que describa los pasos mínimos necesarios para integrarse con un sistema de compilación.

Proporcionar un archivo de uso

Para proporcionar documentación de uso, cree un archivo de texto denominado usage en el directorio de instalación del share puerto. El método recomendado es llamar a la configure_file() función en portfile.cmake.

Por ejemplo:

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

Después de instalar los puertos, vcpkg detecta los archivos instalados ${CURRENT_PACKAGES_DIR}/share/${PORT}/usage en e imprime sus instrucciones de uso.

Formato del contenido

Proporcione instrucciones claras sobre cómo usar el paquete. El contenido debe ser conciso, bien estructurado y resaltar la integración mínima del sistema de compilación necesaria para usar la biblioteca.

Sea claro y conciso sobre cómo utilizar el paquete de forma eficaz. Evite sobrecargar a los usuarios con fragmentos de código, instrucciones de línea de comandos o detalles de configuración. En su lugar, use la "documentation" propiedad en el archivo del vcpkg.json puerto para que los usuarios puedan obtener más información sobre la biblioteca.

Use las plantillas siguientes como patrón para los usage archivos:

Paquetes con destinos de CMake:

<port> provides CMake targets:

    <instructions>

Bibliotecas de solo encabezado:

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

    <instructions>

Ejemplo de usage archivo

proj provides CMake targets:

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