Fornisci la documentazione sull'utilizzo delle porte

Informazioni generali

Fornire una documentazione di utilizzo accurata per le porte consente agli utenti di adottarli facilmente nei progetti. vcpkg genera automaticamente informazioni sull'utilizzo controllando i file installati da una porta. Fornire un file personalizzato usage solo quando le informazioni sull'utilizzo generate non sono corrette o incomplete.

Dopo aver installato una porta, eseguire vcpkg print-usage per esaminare le informazioni sull'utilizzo:

vcpkg print-usage <port>:<triplet>

Se la porta installa già un file personalizzato usage , è possibile usare --generated per controllare cosa genera vcpkg senza tale file:

vcpkg print-usage --generated <port>:<triplet>

Affermazione dell'utilizzo generato

Quando le informazioni sull'utilizzo generate sono corrette, installare un file di marcatore vuoto usage-accurate :

file(TOUCH "${CURRENT_PACKAGES_DIR}/share/${PORT}/usage-accurate")

Questo marcatore afferma che le istruzioni generate sono accurate, quindi vcpkg omette l'avviso che le istruzioni vengono generate in modo euristico e potrebbero non essere corrette.

Prima di aggiungere il marcatore, è possibile usare --affirm per visualizzare in anteprima l'output generato senza l'avviso:

vcpkg print-usage --generated --affirm <port>:<triplet>

Fornitura di un file di utilizzo

Quando le informazioni sull'utilizzo generate non descrivono correttamente come utilizzare il pacchetto, creare un file di testo denominato usage nella directory delle porte e installarlo nella directory della share porta. Il metodo consigliato consiste nel chiamare la file(INSTALL ...) funzione in portfile.cmake.

Per esempio:

file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")

Dopo l'installazione di una porta, vcpkg rileva il file installato ${CURRENT_PACKAGES_DIR}/share/${PORT}/usage in e stampa le istruzioni invece di generare informazioni sull'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 saperne di più sulla tua libreria.

Usare i modelli seguenti come modello per i usage file:

Pacchetti con obiettivi CMake:

<port> provides CMake targets:

  <instructions>

Librerie a sole 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)