Condividi tramite

Fornire la documentazione sull'utilizzo per le porte

  • Articolo

Panoramica

La documentazione sull'utilizzo per le porte consente agli utenti di adottarli facilmente nei progetti. È consigliabile fornire un usage file all'interno della directory della porta (ports/<port name>/usage) che descrive i passaggi minimi necessari per l'integrazione con un sistema di compilazione.

Specifica di un file di utilizzo

Per fornire la documentazione sull'utilizzo, creare un file di testo denominato usage nella directory di installazione della share porta. Il metodo consigliato consiste nel chiamare la configure_file() funzione in portfile.cmake.

Ad esempio:

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

Dopo l'installazione delle porte, vcpkg rileva i file installati ${CURRENT_PACKAGES_DIR}/share/${PORT}/usage in e stampa le istruzioni di utilizzo.

Formato contenuto

Fornire istruzioni chiare su come usare il pacchetto. Il contenuto deve essere conciso, ben strutturato e enfatizzare l'integrazione minima del sistema di compilazione necessaria per usare la libreria.

Essere chiari e concisi su come utilizzare il pacchetto in modo efficace. Evitare di sovraccaricare gli utenti con frammenti di codice, istruzioni della riga di comando o dettagli di configurazione. Usare invece la "documentation" proprietà nel file della vcpkg.json porta in modo che gli utenti possano ottenere altre informazioni sulla libreria.

Usare i modelli seguenti come modello per i usage file:

Pacchetti con destinazioni CMake:

<port> provides CMake targets:

    <instructions>

Librerie solo intestazioni:

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

    <instructions>

Esempio di usage file

proj provides CMake targets:

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