Fournir la documentation d’utilisation de vos ports

Vue d’ensemble

Fournir la documentation d’utilisation pour les ports permet aux utilisateurs de les adopter facilement dans leurs projets. Nous encourageons vivement à fournir un usage fichier dans le répertoire du port (ports/<port name>/usage) qui décrit les étapes minimales nécessaires à l’intégration à un système de génération.

Fourniture d’un fichier d’utilisation

Pour fournir une documentation d’utilisation, créez un fichier texte nommé usage dans le répertoire d’installation du share port. La méthode recommandée consiste à appeler la configure_file() fonction dans portfile.cmake.

Par exemple :

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

Après avoir installé des ports, vcpkg détecte les fichiers installés et ${CURRENT_PACKAGES_DIR}/share/${PORT}/usage imprime leurs instructions d’utilisation.

Format du contenu

Fournissez des instructions claires sur l’utilisation du package. Le contenu doit être concis, bien structuré et mettre en évidence l’intégration minimale du système de génération requise pour utiliser la bibliothèque.

Soyez clair et concis sur la façon d’utiliser efficacement le package. Évitez d’accabler les utilisateurs avec des extraits de code, des instructions de ligne de commande ou des détails de configuration. Utilisez plutôt la "documentation" propriété dans le fichier du vcpkg.json port pour que les utilisateurs puissent en savoir plus sur votre bibliothèque.

Utilisez les modèles suivants comme modèle pour vos usage fichiers :

Packages avec des cibles CMake :

<port> provides CMake targets:

    <instructions>

Bibliothèques en-tête uniquement :

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

    <instructions>

Exemple de usage fichier

proj provides CMake targets:

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