Cargo, crates et éditions : comment un projet Rust est construit et versionné

Ce que c'est

Un crate est l'unité de compilation : une bibliothèque ou un binaire. Un package est un répertoire contenant un manifeste Cargo.toml qui porte [package] (nom, version, édition), [dependencies] et, éventuellement, des cibles, des fonctionnalités (features) et des membres de workspace. Les exigences de version utilisent par défaut la sémantique du caret, que documente le livre de Cargo : "1.2.3" signifie >=1.2.3, <2.0.0, et pour les versions 0.x la composante non nulle la plus à gauche doit correspondre, si bien que "0.2.3" signifie >=0.2.3, <0.3.0. La documentation du résolveur indique que Cargo unifie les versions de dépendances lorsqu'elles sont compatibles au sens SemVer et, lorsque seules des versions incompatibles sont disponibles pour deux exigences, résout et construit deux versions différentes. Cargo.lock enregistre les versions exactes d'une résolution réussie. La FAQ de Cargo indique que le fichier de verrouillage donne des builds déterministes à des moments différents et sur des systèmes différents, mais n'affecte pas les consommateurs du package ; seul Cargo.toml le fait. Les éditions (2015, 2018, 2021, 2024) regroupent des changements de langage rétro-incompatibles ; le guide des éditions précise qu'elles sont activées à volonté crate par crate et que des crates d'éditions différentes doivent interopérer de façon transparente avec celles compilées avec d'autres éditions.

Pourquoi c'est important

Pour qui vient de pip ou npm, ce qui surprend est que le fichier de verrouillage d'une bibliothèque n'a aucune importance pour ses utilisateurs, que deux versions d'un même crate peuvent coexister dans un binaire (leurs types sont distincts et ne s'unifient pas), et que le langage lui-même dispose d'un commutateur de version distinct de la version du compilateur, choisi dans le manifeste.

Comment l'appliquer

• cargo new, cargo add serde, cargo build, cargo test, cargo run ; cargo update déplace le fichier de verrouillage dans les plages autorisées ; cargo build --release pour des builds optimisées.
• Exécuter cargo fmt et cargo clippy en intégration continue ; les lints de Clippy signalent de nombreux schémas de débutant avant qu'un relecteur n'ait à le faire.
• Pour une bibliothèque, garder les plages de [dependencies] aussi larges que raisonnable ; pour une application, valider (commit) Cargo.lock et le mettre à jour délibérément. cargo install sélectionne les dernières dépendances sauf si --locked est passé, comme le note la FAQ.
• Migrer les éditions avec cargo fix --edition, un crate à la fois ; le guide indique que les migrations automatiques ne sont pas parfaites et que des cas particuliers peuvent nécessiter des changements manuels.
• Utiliser un workspace pour plusieurs crates liés, afin qu'ils partagent un seul fichier de verrouillage et un seul répertoire de cibles.

Pièges

Deux versions d'un même crate se compilent sans problème jusqu'à ce qu'un type de l'une soit passé à une API attendant l'autre ; le message d'erreur nomme deux types au nom identique. cargo update ne dit rien des changements de comportement à l'intérieur d'une plage compatible. Une dépendance 0.x traite chaque incrément mineur comme une rupture, si bien que "0.7" ne choisira jamais 0.8.