Cargo & dépendances

mon_projet/
├── Cargo.toml        ← le manifeste : nom, version, dépendances, features
├── Cargo.lock        ← versions exactes retenues (généré, ne pas éditer à la main)
├── src/
│   ├── main.rs       ← point d'entrée d'un binaire
│   ├── lib.rs        ← racine d'une bibliothèque (optionnel)
│   └── bin/
│       └── outil.rs  ← binaire supplémentaire
├── tests/            ← tests d'intégration
├── examples/         ← exemples exécutables (cargo run --example nom)
├── benches/          ← benchmarks
├── build.rs          ← script exécuté avant la compilation (optionnel)
└── target/           ← résultats de compilation (à ne pas versionner)

Cargo trouve tout seul ces fichiers par leur emplacement : aucune déclaration n'est nécessaire tant qu'on suit cette structure.

[package]
name = "mon_projet"
version = "0.1.0"
edition = "2024"
rust-version = "1.85"
authors = ["Ton Nom <[email protected]>"]
description = "Une courte description"
license = "MIT OR Apache-2.0"
repository = "https://github.com/moi/mon_projet"
readme = "README.md"
keywords = ["web", "framework"]
categories = ["web-programming::http-server"]

[package]
name = "runique"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true

Voir la section 10.

[dependencies]
# Forme courte : une version depuis crates.io
serde_json = "1.0"

# Forme table en ligne : version + options
serde = { version = "1.0", features = ["derive"] }

# Sans les features par défaut, puis on choisit
imagesize = { version = "0.15", default-features = false, features = ["heif"] }

# Optionnelle : compilée seulement si une feature la demande
sea-orm = { version = "2.0", optional = true }

# Depuis git (branche, tag ou commit)
ma_crate = { git = "https://github.com/user/ma_crate" }
ma_crate2 = { git = "https://github.com/user/ma_crate", branch = "dev" }
ma_crate3 = { git = "https://github.com/user/ma_crate", tag = "v1.2.0" }
ma_crate4 = { git = "https://github.com/user/ma_crate", rev = "a1b2c3d" }

# Depuis un dossier local
utils = { path = "../utils" }

# Local pendant le développement, crates.io à la publication
derive_form = { path = "../derive_form", version = "4.0.0" }

# Renommer une dépendance : on l'utilise sous le nom `json` dans le code
json = { package = "serde_json", version = "1.0" }

cargo add serde --features derive        # [dependencies]
cargo add tokio -F full                  # -F est l'abréviation de --features
cargo add pretty_assertions --dev        # [dev-dependencies]
cargo add cc --build                     # [build-dependencies]
cargo add sea-orm --optional             # optional = true
cargo add imagesize --no-default-features -F heif
cargo add utils --path ../utils
cargo remove serde

cargo add écrit la dernière version compatible avec ton rust-version.

sea-orm = "=2.0.4"

Épingler sert quand une crate casse la compatibilité sans changer son chiffre de rupture (cela arrive), ou quand deux crates doivent rester alignées exactement (sea-orm et sea-orm-migration). Le prix : ta crate ne pourra pas cohabiter avec une autre qui demande sea-orm = "2.0.5", car Cargo ne peut pas choisir une version qui satisfait les deux.

[dev-dependencies]
pretty_assertions = "1.4"
reqwest = { version = "0.13", features = ["json"] }

Utilisées uniquement par les tests, les exemples et les benchmarks. Elles ne sont jamais compilées dans la bibliothèque livrée, et ne sont pas téléchargées par ceux qui dépendent de ta crate.

Utilité supplémentaire : activer une feature seulement pour les tests.

[dependencies]
runique = { version = "4.0", features = ["postgres"] }

[dev-dependencies]
runique = { version = "4.0", features = ["test-utils"] }

Pendant cargo test, les deux déclarations sont fusionnées : postgres et test-utils sont actives. En cargo build, seule postgres l'est.

[build-dependencies]
cc = "1.0"
toml = "1"

Utilisées par build.rs, un programme compilé et exécuté avant ta crate (générer du code, compiler du C, lire un fichier de configuration). Elles ne sont pas disponibles dans src/. Si tu as besoin de la même crate dans les deux, déclare-la dans les deux sections (Runique le fait pour toml).

[target.'cfg(unix)'.dependencies]
libc = "0.2"

[target.'cfg(windows)'.dependencies]
windows-sys = "0.59"

[target.'cfg(target_arch = "wasm32")'.dependencies]
getrandom = { version = "0.3", features = ["wasm_js"] }

Ne sont compilées que pour la plateforme cible. Le code qui s'en sert se protège par le même #[cfg(unix)].

[patch.crates-io]
sea-orm = { git = "https://github.com/SeaQL/sea-orm", branch = "master" }

Remplace sea-orm partout dans l'arbre, y compris quand c'est une dépendance indirecte. À quoi ça sert : tester un correctif pas encore publié. Ne vaut que pour le projet racine (ignoré quand ta crate est utilisée comme dépendance).

# Cargo.toml racine
[workspace.dependencies]
time = "=0.3.55"

Cette ligne ne force rien tant qu'aucun membre n'écrit time.workspace = true. Pour épingler une dépendance indirecte (que tu n'utilises pas toi-même), il faut la déclarer directement dans le membre concerné : c'est ce que fait Runique pour time, sinon cargo install reprendrait une version plus récente incompatible avec cookie.

[features]
default = ["json"]                    # 1. d'autres features de ta crate
json = ["dep:serde_json"]             # 2. une dépendance optionnelle
derive = ["serde/derive"]             # 3. une feature d'une dépendance
full = ["json", "derive", "async"]    # groupe de features
async = ["dep:tokio", "tokio/rt"]     # combinaison
admin = []                            # 4. rien d'autre : seulement du code sous #[cfg]

[dependencies]
serde = "1.0"
serde_json = { version = "1.0", optional = true }
tokio = { version = "1", optional = true }

[features]
default = ["orm"]

Activée automatiquement sauf si l'utilisateur écrit default-features = false (ou --no-default-features). Garde-la petite : tout ce qui y figure sera compilé chez tous tes utilisateurs, et ils ne peuvent la retirer qu'en bloc.

[dependencies]
serde_json = { version = "1.0", optional = true }

Écriture 1 — sans dep: : Cargo crée automatiquement une feature nommée serde_json. Les utilisateurs peuvent l'activer directement (features = ["serde_json"]), et ce nom fait partie de ton API publique.

[features]
json = ["serde_json"]       # json active la feature implicite serde_json

Écriture 2 — avec dep: (Rust 1.60+) : la feature implicite n'est plus créée. Seul json est visible.

[features]
json = ["dep:serde_json"]

La seconde forme est préférable : tu choisis les noms exposés, et tu peux remplacer serde_json par une autre crate sans casser personne. Runique l'utilise : orm = ["dep:sea-orm", "dep:sea-orm-migration"].

[features]
serde = ["dep:serde", "chrono?/serde"]

[dependencies]
serde = { version = "1.0", optional = true }
chrono = { version = "0.4", optional = true }

• "chrono/serde" active serde de chrono et force la compilation de chrono.
• "chrono?/serde" active serde de chrono seulement si chrono est déjà activé par ailleurs.

À quoi ça sert : « si tu utilises les dates, rends-les sérialisables », sans imposer les dates à qui ne veut que serde.

[dependencies]
runique = { version = "4.0", features = ["postgres", "admin"] }

cargo build --features "json,async"      # features du package courant
cargo build -F json -F async             # idem
cargo build --features runique/admin     # feature d'une dépendance, depuis la ligne de commande
cargo build --all-features               # toutes (attention : section 9)
cargo build --no-default-features        # aucune feature par défaut
cargo build --no-default-features -F json

#[cfg(feature = "json")]
pub mod json {
    pub fn parse(input: &str) -> serde_json::Value {
        serde_json::from_str(input).unwrap_or_default()
    }
}

#[cfg(feature = "admin")]
pub fn with_admin(self) -> Self { self }

Sans la feature, le module n'existe pas : il n'est ni compilé, ni vérifié, ni présent dans le binaire. Un utilisateur qui appelle mon_projet::json::parse sans la feature obtient « cannot find module json ».

Conséquence directe : une erreur dans un bloc #[cfg(feature = "x")] n'apparaît que si tu compiles avec x. Il faut donc tester chaque combinaison qui compte (c'est pourquoi la CI de Runique compile plusieurs lots de features).

#[cfg(all(feature = "postgres", feature = "admin"))]
fn a() {}

#[cfg(any(feature = "sqlite", feature = "postgres"))]
fn b() {}

#[cfg(not(feature = "admin"))]
fn c() {}

#[cfg(all(unix, not(test)))]
fn d() {}

fn moteur() -> &'static str {
    if cfg!(feature = "postgres") {
        "postgres"
    } else {
        "sqlite"
    }
}

cfg!(...) est remplacé à la compilation par true ou false. Contrairement à #[cfg], les deux branches sont compilées et doivent donc être valides même quand la feature est absente. On ne peut pas y appeler une fonction qui n'existe que sous la feature.

#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Point {
    pub x: i32,
    pub y: i32,
}

Point n'implémente Serialize que si l'utilisateur active serde. À quoi ça sert : proposer l'intégration avec une crate sans l'imposer.

#[cfg(feature = "orm")]
use sea_orm::DatabaseConnection;

pub struct Moteur {
    pub nom: String,
    #[cfg(feature = "orm")]
    pub db: DatabaseConnection,
}

Attention : un champ ou une variante d'enum sous #[cfg] change la forme du type. Un code utilisateur qui construit Moteur { nom } cessera de compiler le jour où quelqu'un d'autre dans l'arbre active orm (section 8). Pour un type public, préfère un champ toujours présent, ou un constructeur.

[package.metadata.docs.rs]
features = ["all-databases"]
# ou : all-features = true

docs.rs compile ta documentation avec ces features ; sans cette section, seules les features par défaut sont documentées et tout le code sous #[cfg(feature)] est absent de la doc.

[package]
edition = "2024"      # resolver 3 par défaut

# Dans un workspace, il se déclare à la racine :
[workspace]
resolver = "3"

Un workspace virtuel (racine sans [package]) n'a pas d'édition : il faut y écrire resolver explicitement, sinon Cargo reprend le resolver 1 et affiche un avertissement.

cargo tree                       # arbre des dépendances
cargo tree -i serde              # qui dépend de serde (arbre inversé)
cargo tree -e features           # affiche les features activées sur chaque arête
cargo tree -e features -i serde  # qui active quelle feature de serde
cargo tree -d                    # crates en plusieurs versions
cargo tree --no-default-features -F postgres   # l'arbre pour une combinaison précise

#[cfg(all(feature = "postgres", feature = "sqlite"))]
compile_error!("les features `postgres` et `sqlite` sont exclusives : choisis un seul moteur");

Le build s'arrête avec un message clair, au lieu d'un comportement incohérent ou d'une erreur de type obscure.

Runique fait exactement cela pour sqlite, postgres et mysql, avec une échappatoire explicite :

#[cfg(all(
    not(doc),
    not(feature = "all-databases"),
    feature = "postgres",
    feature = "sqlite"
))]
compile_error!("features `postgres` and `sqlite` are mutually exclusive");

• not(doc) : cargo doc et docs.rs peuvent documenter tous les moteurs ;
• all-databases : une feature qu'il faut demander par son nom, pour les outils qui parlent aux trois moteurs.

# Cargo.toml racine (workspace virtuel : pas de [package])
[workspace]
members = [
    "runique/runique_dsl",
    "runique/derive_form",
    "runique",
    "demo-app",
]
resolver = "3"

[workspace.package]
version = "4.0.0"
edition = "2024"
rust-version = "1.94"
license = "MIT"

[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
derive_form = { path = "runique/derive_form", version = "4.0.0" }

members accepte des jokers (members = ["crates/*"]) et exclude retire des dossiers.

# runique/Cargo.toml
[package]
name = "runique"
version.workspace = true
edition.workspace = true

[dependencies]
serde.workspace = true
# Hériter et ajouter : les features s'ajoutent à celles du workspace
tokio = { workspace = true, features = ["test-util"] }
# Hériter et rendre optionnelle
sea-orm = { workspace = true, optional = true }
derive_form.workspace = true

Ce qu'on peut ajouter à une dépendance héritée : features (ajoutées), optional. On ne peut pas changer la version ni retirer une feature.

# Implicite : src/lib.rs, src/main.rs, src/bin/*.rs, examples/*.rs sont trouvés seuls.

# Explicite : nom ou chemin différent
[lib]
name = "runique"
path = "src/lib.rs"

[[bin]]
name = "runique"
path = "src/bin/runique.rs"

[[example]]
name = "demo"
required-features = ["admin"]

[[bin]] (double crochet) est un tableau : on peut en déclarer plusieurs.

[[bin]]
name = "outil-admin"
required-features = ["admin"]

Le binaire n'est compilé que si la feature est active. Sans elle, cargo build l'ignore sans erreur.

[profile.release]
opt-level = 3          # 0, 1, 2, 3, "s" (taille), "z" (taille minimale)
lto = "fat"            # optimisation à l'édition de liens : binaire plus rapide, compilation plus lente
codegen-units = 1      # moins de parallélisme, meilleure optimisation
strip = true           # retire les symboles : binaire plus petit
panic = "abort"        # pas de déroulement de pile : plus petit, mais plus de catch_unwind
debug = false

[profile.dev]
opt-level = 0
debug = true
incremental = true

[profile.dev.package."*"]
opt-level = 2

Toutes les dépendances sont optimisées, ton code reste en opt-level = 0 (compilation rapide). À quoi ça sert : certaines crates sont inutilisables en debug. Le hachage argon2 d'un mot de passe peut prendre plusieurs secondes sans optimisation et quelques dizaines de millisecondes avec.

[profile.profiling]
inherits = "release"
debug = true

cargo build --profile profiling

fn main() {
    // Valeur lue à l'exécution : avec une constante écrite en dur,
    // le compilateur détecterait le dépassement et refuserait de compiler.
    let x: u8 = std::env::args().count() as u8 + 254;
    let y = x + 1;     // dev : panique "attempt to add with overflow"
                       // release : vaut 0 (enroulement), sans erreur
}

Les profils n'appartiennent qu'au projet racine : ceux déclarés dans tes dépendances sont ignorés.

[lints.rust]
unsafe_code = "forbid"
missing_docs = "warn"

[lints.clippy]
unwrap_used = "warn"
pedantic = { level = "warn", priority = -1 }
module_name_repetitions = "allow"

# racine
[workspace.lints.clippy]
unwrap_used = "warn"

# membre
[lints]
workspace = true

cargo new mon_projet          # nouveau binaire
cargo new ma_lib --lib        # nouvelle bibliothèque
cargo init                    # dans un dossier existant

cargo check                   # analyse et vérifie les types sans produire de binaire : le plus rapide
cargo build                   # compile en debug
cargo build --release         # compile en release
cargo run -- arg1 arg2        # compile, exécute, passe les arguments après --

cargo test                    # tous les tests
cargo test nom_du_test        # tests dont le nom contient ce texte
cargo test -- --nocapture     # afficher les println! des tests

cargo clippy --all-targets -- -D warnings   # linter, avertissements en erreurs
cargo fmt                     # formater
cargo fmt --check             # vérifier sans modifier (CI)

cargo doc --open              # documentation locale
cargo tree                    # arbre des dépendances
cargo update                  # mettre à jour Cargo.lock
cargo clean                   # vider target/

cargo install ripgrep         # installer un binaire publié
cargo install --path .        # installer le binaire du projet courant

cargo login <ton_token>       # une fois
cargo package --list          # fichiers qui seront envoyés
cargo publish --dry-run       # vérifie que le paquet compile seul
cargo publish

a = "1.2"                                        # >=1.2.0, <2.0.0
b = "0.3"                                        # >=0.3.0, <0.4.0
c = "=2.0.4"                                     # exactement
d = { version = "1", features = ["x"] }
e = { version = "1", default-features = false }
f = { version = "1", optional = true }
g = { path = "../g", version = "1" }
h = { git = "https://...", tag = "v1" }
i = { package = "vrai_nom", version = "1" }      # renommage
j.workspace = true

[features]
default = ["a"]
a = []                       # code sous #[cfg(feature = "a")]
b = ["dep:crate_opt"]        # dépendance optionnelle sans feature implicite
c = ["serde/derive"]         # feature d'une dépendance
d = ["chrono?/serde"]        # seulement si chrono est déjà actif

#[cfg(feature = "a")]            // le code disparaît sans la feature
if cfg!(feature = "a") { }       // compilé dans tous les cas, valeur fixée
#[cfg_attr(feature = "s", derive(serde::Serialize))]
#[cfg(all(feature = "x", feature = "y"))]
compile_error!("x et y sont exclusives");