Corso Gratuito di Programmazione Rust Lezione 051 – Pubblicare una Crate su Crates.io

SE VUOI PRENDERE LA CERTIFICAZIONE PER QUESTO CORSO CLICCA QUI

Pubblicare una Crate su Crates.io

Abbiamo utilizzato pacchetti da crates.io come dipendenze del nostro progetto, ma puoi anche condividere il tuo codice con altre persone pubblicando i tuoi pacchetti. Il registro delle crate su crates.io distribuisce il codice sorgente dei tuoi pacchetti, quindi ospita principalmente codice open source.

Rust e Cargo hanno funzionalità che rendono il tuo pacchetto pubblicato più facile da trovare e utilizzare per le persone. Parleremo di alcune di queste funzionalità in seguito e poi spiegheremo come pubblicare un pacchetto.

Scrivere Commenti di Documentazione Utili

Documentare accuratamente i tuoi pacchetti aiuterà gli altri utenti a sapere come e quando usarli, quindi vale la pena investire tempo nella scrittura della documentazione. Abbiamo discusso nel Capitolo 3 come commentare il codice Rust usando due barre oblique, //. Rust ha anche un particolare tipo di commento per la documentazione, chiamato comodamente commento di documentazione, che genera documentazione HTML. L’HTML visualizza il contenuto dei commenti di documentazione per gli elementi di API pubblica destinati ai programmatori interessati a sapere come utilizzare la tua crate rispetto a come è implementata la tua crate.

I commenti di documentazione usano tre barre oblique, ///, invece di due e supportano la notazione Markdown per formattare il testo. Posiziona i commenti di documentazione proprio prima dell’elemento che stanno documentando.

Commentare Elementi Contenuti

Lo stile di commento di documentazione //! aggiunge documentazione all’elemento che contiene i commenti anziché agli elementi che seguono i commenti. Di solito usiamo questi commenti di documentazione all’interno del file di root della crate (src/lib.rs per convenzione) o all’interno di un modulo per documentare la crate o il modulo nel suo complesso.

Per esempio, per aggiungere documentazione che descrive lo scopo della crate my_crate che contiene la funzione add_one, aggiungiamo commenti di documentazione che iniziano con //! all’inizio del file src/lib.rs, come mostrato nel Listing 14-2:

rust

//! # My Crate
//!
//! `my_crate` è una collezione di utilità per rendere più conveniente l'esecuzione di determinati calcoli.


Esportare un’API Pubblica Conveniente con pub use

La struttura della tua API pubblica è una considerazione importante quando pubblichi una crate. Le persone che usano la tua crate sono meno familiari con la struttura rispetto a te e potrebbero avere difficoltà a trovare i pezzi che desiderano utilizzare se la tua crate ha una grande gerarchia di moduli.

Il buon senso suggerisce di usare le dichiarazioni pub use per esportare gli elementi al livello superiore.

Impostare un Account Crates.io

Prima di poter pubblicare qualsiasi crate, devi creare un account su crates.io e ottenere un token API. Per farlo, visita la home page su crates.io e accedi tramite un account GitHub. (Al momento l’account GitHub è un requisito, ma il sito potrebbe supportare altri modi per creare un account in futuro.) Una volta effettuato l’accesso, visita le impostazioni del tuo account su https://crates.io/me/ e recupera la tua chiave API. Quindi esegui il comando cargo login con la tua chiave API, in questo modo:

shell

$ cargo login abcdefghijklmnopqrstuvwxyz012345


Aggiungere Metadati a una Nuova Crate

Prima di pubblicare, dovrai aggiungere alcuni metadati nella sezione [package] del file Cargo.toml della crate.

La tua crate avrà bisogno di un nome univoco. Mentre stai lavorando su una crate localmente, puoi dare un nome alla crate come preferisci. Tuttavia, i nomi delle crate su crates.io vengono assegnati in base al principio del primo arrivato, primo servito. Una volta che un nome di crate viene preso, nessun altro può pubblicare una crate con quel nome. Prima di provare a pubblicare una crate, cerca il nome che desideri utilizzare. Se il nome è già stato usato, dovrai trovare un altro nome e modificare il campo name nel file Cargo.toml sotto la sezione [package] per utilizzare il nuovo nome per la pubblicazione, così:

toml

[package]
name = "guessing_game"


Anche se hai scelto un nome univoco, quando esegui cargo publish per pubblicare la crate in questo punto, otterrai un avviso e poi un errore.

shell

$ cargo publish
Updating crates.io index
warning: manifest has no description, license, license-file, documentation, homepage or repository.
See https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata for more info.
--snip--
error: failed to publish to registry at https://crates.io

Caused by:
the remote server responded with an error: missing or empty metadata fields: description, license. Please see https://doc.rust-lang.org/cargo/reference/manifest.html for how to upload metadata


Pubblicare su Crates.io

Ora che hai creato un account, salvato il tuo token API, scelto un nome per la tua crate e specificato i metadati richiesti, sei pronto per pubblicare! La pubblicazione di una crate carica una versione specifica su crates.io per essere utilizzata da altri.

Fai attenzione, perché una pubblicazione è permanente. La versione non può mai essere sovrascritta e il codice non può essere eliminato. Un obiettivo principale di crates.io è agire come un archivio permanente di codice in modo che le build di tutti i progetti che dipendono dalle crate da crates.io continueranno a funzionare. Consentire la cancellazione delle versioni renderebbe impossibile raggiungere tale obiettivo. Tuttavia, non c’è limite al numero di versioni di crate che puoi pubblicare.

Esegui di nuovo il comando cargo publish. Dovrebbe avere successo ora.