Cargo e Crates.io per Rust — Gestione Dipendenze e Workspace che Regge in Produzione

Perché Cargo è più di un package manager e come ti fa risparmiare tempo (e bestemmie)

Lo vediamo spesso quando un progetto Rust cresce: il Cargo.toml diventa un campo minato di dipendenze, versioni e feature. E il build, che prima era veloce, inizia a durare cinque minuti. Poi arriva il merge request che rompe tutto: una dipendenza aggiornata semver-major tira giù mezza codebase.

Noi, di Meteora Web, lavoriamo quotidianamente con stack compilati — dal backend Laravel a plugin Rust per estensioni native — e sappiamo che la gestione delle dipendenze non è un dettaglio operativo, ma una scelta architetturale. Cargo non è npm: il suo modello di risoluzione, il lock file deterministico e l’ecosistema crates.io ti danno un controllo che altri linguaggi si sognano. Ma solo se lo sai usare bene.

Questa guida è per chi già scrive Rust e vuole passare da "funziona" a "funziona in produzione senza sorprese". Parleremo di workspace, feature flags, semver reale, registri privati e trick per ridurre i tempi di compilazione.

Come funziona il resolve delle dipendenze in Cargo e perché non è come npm o composer

Se arrivi da Node.js o PHP, conosci il dramma delle risoluzioni non deterministiche o dei lock file che si scontrano. Cargo usa un risolutore basato su SAT solver (un algoritmo di soddisfacibilità booleana) che garantisce una soluzione unica e riproducibile. Il file Cargo.lock congela le versioni esatte per ogni dipendenza diretta e transitiva. Finché non lanci cargo update, il tuo build è identico su ogni macchina.

Errore comune: committare Cargo.lock solo per applicazioni binarie (es. un demone o un CLI tool), ma non per librerie. Per le librerie, il lock file andrebbe invece ignorato (lo dice anche la doc ufficiale), perché chi consumerà la tua crate userà il proprio lock. Se invece è un'applicazione binaria, committa sempre il lock — altrimenti rischi che un aggiornamento semver-patch di una dipendenza transitiva introduca una breaking change non dichiarata.

Come controllare l'albero delle dipendenze

# Albero delle dipendenze (con versioni risolte)
cargo tree

# Solo dipendenze dirette
cargo tree --depth 1

# Dipendenze duplicato (warning: spesso causa code bloat)
cargo tree -d

Questi comandi ti salvano quando sospetti che due crate includano la stessa libreria in versioni diverse. Il tuo tempo di compilazione cresce in modo quadratico con il numero di versioni duplicato.

Quali best practice per gestire le versioni in Cargo toml senza rompere tutto

Il file Cargo.toml supporta specifiche semver flessibili (es. "1.2", "^1.2.3", ">=1.0, <2.0"). La maggioranza dei crate usa ^1.2.3 (compatibile con qualsiasi versione >=1.2.3 e <2.0.0). Ma la pratica migliore è:

• Per librerie: usa range il più stretto possibile (es. ">=1.2, <1.5") per non obbligare i consumatori a versioni future che potrebbero rompersi.
• Per applicazioni: punta a versioni esatte ("=1.2.3"), così da avere build completamente deterministici. Poi aggiorni con cargo update -p nomecrate e testi.
• Attenzione a *: è una cattiva idea perché accetta qualsiasi versione, anche major. Lo vediamo su crate lasciati incustoditi: un aggiornamento semver-major e il build scoppia.

Noi, di Meteora Web, abbiamo una regola interna: ogni dipendenza deve avere una ragione di esistere (non scarichiamo crate solo per fare un .map() su un vettore). Controlliamo periodicamente cargo outdated per vedere cosa è rimasto indietro, ma non aggiorniamo mai senza prima testare su branch dedicato.

# Installa cargo-outdated
cargo install cargo-outdated
cargo outdated -R

Come organizzare workspace con crate multipli senza impazzire (e senza build lenti)

Un workspace Rust ti permette di gestire più crate in una sola directory, condividendo il lock file e le dipendenze. È la soluzione standard per progetti che includono un crate libreria e un crate binario, o per microservizi monorepo.

Errore comune: mettere tutto in un unico grande crate. Questo costringe a ricompilare tutto a ogni cambio. Con un workspace puoi separare la logica in crate più piccoli: le dipendenze cambiate raramente vengono compilate una volta sola.

Struttura workspace tipica

# Cargo.toml radice (workspace)
[workspace]
members = [
    "crates/core",
    "crates/api",
    "crates/cli",
]

# Build di un solo crate nel workspace
cargo build -p core

# Esegui test su tutto il workspace
cargo test --workspace

Consiglio operativo: separa le interfacce (trait) in crate dedicati, così i crate che dipendono solo da interfacce vengono ricompilati meno spesso. Questo accelera i tempi di sviluppo in modo drastico.

Crates io e registri privati come pubblicare e consumare crate interne

Crates.io è il registro ufficiale, ma per codice interno o closed-source non vuoi pubblicare lì. Cargo supporta registri privati (custom registry). Puoi usare cargo login con un token per autenticarti, e specificare nel Cargo.toml il registro alternativo.

Configurare un registro privato con una semplice directory

Per test veloci (sviluppo locale) puoi usare un path locale. Per team distribuiti, consigliamo di hostare un registry con Alexandrie o usare un registry basato su git (anche se meno performante). Il metodo più collaudato è sfruttare cargo vendor per scaricare le dipendenze e committarle, ma è brutto e sconsigliato se puoi usare un registry vero.

# Cargo.toml con registro privato
[registries]
my-internal = { index = "https://git.internal.com/cargo-index.git" }

[dependencies]
my-crate = { registry = "my-internal", version = "0.2" }

Pubblicare una crate interna è simile a crates.io, ma devi prima autenticarti sul registro privato con cargo login --registry my-internal e poi usare cargo publish --registry my-internal.

Noi, di Meteora Web, abbiamo costruito una piattaforma proprietaria per la gestione dei contenuti social (ne parliamo in altre guide). Per le sue parti critiche in Rust, usiamo un registry privato su un server Linux che gestiamo noi. Possedere il proprio stack batte affittarlo, anche per le dipendenze.

Feature flags come progettare API opzionali senza esplodere il build

Le feature flags in Cargo.toml permettono di attivare o disattivare gruppi di dipendenze e codici condizionali. È il modo standard per offrire funzionalità opzionali senza costringere tutti a scaricare tutto.

Esempio: un crate di logging che supporta sia output JSON che flat text. Definisci due feature, e l’utente sceglie.

[features]
default = []
json = ["serde", "serde_json"]
text = []

Poi nel codice Rust usi #[cfg(feature = "json")] o controlli a runtime con cfg!(feature = "json"). Attenzione: le feature sono additive — se due feature attivano la stessa dipendenza in versioni diverse, Cargo risolve al meglio, ma può generare conflitti. Per questo esiste la sezione di mutua esclusione (da gestire con attenzione).

Errore comune: feature con nomi troppo generici (es. default o feature1). Usa nomi descrittivi come serde-support o async-io.

Come ridurre i tempi di compilazione con Cargo quando il progetto cresce

Un problema reale nei progetti Rust medi: i tempi di compilazione. Noi abbiamo un cliente con una codebase di circa 200 dipendenze (tra dirette e transitive). Il build iniziale superava i 20 minuti. Abbiamo applicato tre tecniche:

1. Workspace ben separato: dividere la logica in crate più piccoli riduce la ricompilazione a catena.
2. Build con cargo build --release solo su CI; in sviluppo usiamo cargo check per il type checking e cargo test solo sui crate modificati.
3. Cache condivisa tra sviluppatori usando sccache (un server di cache per compilazioni). Puoi installarlo e configurare Cargo per usarlo: RUSTC_WRAPPER=sccache cargo build. Noi lo eseguiamo su un server centrale in rete locale e i tempi di build si sono quasi dimezzati.

# Installazione sccache
cargo install sccache

# Usalo
export RUSTC_WRAPPER=sccache
cargo build

Cosa fare adesso

Ecco tre azioni concrete per non tornare più indietro:

1. Analizza il tuo albero: lancia cargo tree -d nel tuo progetto. Se vedi versioni duplicate di crate come syn o quote, risolvile aggiungendo un vincolo di versione e usando cargo update -p.
2. Struttura a workspace: se hai un progetto con più binari o test, mettilo in un workspace. Inizia con cargo new workspace_name --workspace e sposta i crate esistenti.
3. Prova un registro privato: anche solo per test, configura un registry locale con cargo vendor e un path relativo. Poi se il team cresce, passa a un vero Alexandrie.

Se vuoi approfondire il linguaggio alla base, leggi la nostra guida pillar su Rust. E se il tuo progetto Rust sta diventando un incubo di build lento, contattaci: veniamo dal debugging di sistemi complessi.