Fornecer documentação de uso para suas portas

Visão geral

O fornecimento de documentação de uso para portas permite que os usuários as adotem facilmente em seus projetos. É altamente recomendável fornecer um usage arquivo dentro do diretório da porta (ports/<port name>/usage) que descreva as etapas mínimas necessárias para a integração com um sistema de compilação.

Fornecendo um arquivo de uso

Para fornecer documentação de uso, crie um arquivo de texto nomeado usage no diretório de share instalação da porta. O método recomendado é chamar a configure_file() função em portfile.cmake.

Por exemplo:

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

Depois de instalar as portas, o vcpkg detecta os arquivos instalados ${CURRENT_PACKAGES_DIR}/share/${PORT}/usage e imprime suas instruções de uso.

Formato de conteúdo

Forneça instruções claras sobre como usar o pacote. O conteúdo deve ser conciso, bem estruturado e enfatizar a integração mínima do sistema de compilação necessária para usar a biblioteca.

Seja claro e conciso sobre como utilizar o pacote de forma eficaz. Evite sobrecarregar os usuários com trechos de código, instruções de linha de comando ou detalhes de configuração. Em vez disso, use a "documentation" propriedade no arquivo da vcpkg.json porta para que os usuários possam saber mais sobre sua biblioteca.

Use os seguintes modelos como um padrão para seus usage arquivos:

Pacotes com destinos CMake:

<port> provides CMake targets:

    <instructions>

Bibliotecas somente de cabeçalho:

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

    <instructions>

Exemplo de usage arquivo

proj provides CMake targets:

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