Poskytnutí dokumentace k využití pro porty

Přehled

Poskytnutí dokumentace k používání portů umožňuje uživatelům snadno je přijmout ve svých projektech. Důrazně doporučujeme poskytnout usage soubor v adresáři portu (ports/<port name>/usage), který popisuje minimální kroky potřebné k integraci se systémem sestavení.

Zadání souboru s informacemi o využití

Pokud chcete poskytnout dokumentaci k použití, vytvořte textový soubor s názvem usage v instalačním share adresáři portu. Doporučená metoda je volat configure_file() funkci v portfile.cmake.

Příklad:

cmake

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

Po instalaci portů nástroj vcpkg zjistí soubory nainstalované do ${CURRENT_PACKAGES_DIR}/share/${PORT}/usage a vytiskne pokyny k použití.

Formát obsahu

Uveďte jasné pokyny, jak balíček používat. Obsah by měl být stručný, dobře strukturovaný a zdůraznit minimální integraci systému sestavení potřebnou k používání knihovny.

Buďte jasné a stručné o tom, jak efektivně využívat balíček. Vyhněte se zahlcení uživatelů fragmenty kódu, pokyny příkazového řádku nebo podrobnosti konfigurace. Místo toho použijte "documentation" vlastnost v souboru portuvcpkg.json, aby se uživatelé mohli dozvědět více o knihovně.

Jako vzor pro soubory usage použijte následující šablony:

Balíčky s cíli CMake:

text

<port> provides CMake targets:

    <instructions>

Knihovny jen pro záhlaví:

text

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

    <instructions>

usage Příklad souboru

text

proj provides CMake targets:

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