cargo

Cargo : le système de build et le gestionnaire de paquets de Rust

Cet article explique comment fonctionne Cargo — le système de build et le gestionnaire de paquets standard de Rust — et s'adresse aux développeurs qui souhaitent configurer, compiler, tester et gérer des projets Rust.

Prérequis

- Rust installé via `rustup` (version 1.70 ou supérieure recommandée) - Connaissances de base de la ligne de commande - Accès à crates.io pour télécharger les dépendances (connexion internet)

Vérifiez votre version de Rust avec :

rustc --version
cargo --version

Étapes

1. Créer un nouveau projet

Utilisez `cargo init` pour démarrer un projet dans le dossier courant :

cargo init --bin

Pour une bibliothèque, utilisez `--lib` :

cargo init --lib

Cela génère un fichier `Cargo.toml` et un fichier source (`src/main.rs` pour les binaires, `src/lib.rs` pour les bibliothèques). Le fichier `Cargo.toml` définit toutes les métadonnées du projet et les dépendances.

2. Ajouter des dépendances

Recherchez les crates disponibles sur crates.io :

cargo search serde

Ajoutez une dépendance en l'ajoutant directement au fichier `Cargo.toml` :

[dependencies]
serde = "1.0"

Cargo télécharge, compile et met la crate à disposition dans votre projet. La version dans `Cargo.toml` suit le versionnage sémantique — Cargo sélectionne automatiquement la version compatible la plus récente.

3. Compiler le projet

Construisez votre projet en mode debug :

cargo build

Cargo appelle en interne `rustc` et traite toutes les dépendances. Pour une build de production optimisée :

cargo build --release

Le drapeau `--release` active des optimisations qui produisent un code plus rapide et plus compact.

4. Exécuter les tests

Rust dispose d'un support de test intégré. Exécutez tous les tests :

cargo test

Filtrez les tests par nom :

cargo test test_name

Limitez le nombre de threads de test simultanés pour déboguer les courses de données ou gérer la charge système :

cargo test -- --test-threads=1

Pour les workspaces contenant plusieurs packages :

cargo test --workspace

5. Passer des options de compilation directement

Utilisez `cargo rustc` pour passer des options spécifiques directement à `rustc` :

cargo rustc -- -C target-cpu=native

Cette commande optimise le code pour le processeur exact sur lequel vous compilez.

6. Retour continu avec des outils

Installez `bacon` pour des vérifications automatiques lors des modifications de code :

cargo install bacon
bacon

Bacon exécute en continu `cargo check` lorsque vous modifiez des fichiers et fournit un retour direct sur les erreurs de type et les problèmes de compilation. Des outils similaires peuvent également exécuter automatiquement `cargo test` ou `cargo clippy`.

7. Consulter la documentation hors ligne

Ouvrez la documentation officielle de Rust localement :

rustup doc

Cela donne accès au livre The Rust Programming Language, au livre Cargo et à la référence Rust — tous disponibles hors ligne.

8. Choisir une toolchain spécifique par dossier

Utilisez `rustup override` pour sélectionner une version spécifique de Rust ou une nightly build par projet :

rustup override set nightly

Cela est nécessaire lorsque différents projets dépendent de versions différentes de Rust. Supprimez l'override avec :

rustup override unset

Vérification

Vérifiez que tout fonctionne correctement :

cargo build
cargo test

Une build réussie produit un fichier exécutable dans `target/debug/` (ou `target/release/` après `--release`). Les tests rapportent le nombre de tests réussis et échoués. Examinez la structure de votre projet :

ls -la
cat Cargo.toml

Problèmes fréquents

1. Dépendance introuvable

Problème : `cargo build` signale « no matching package found » ou une erreur réseau.

Solution : Vérifiez votre connexion internet et que la crate existe sur crates.io. Mettez à jour votre index de registre local :

cargo update

2. Conflit de versions entre dépendances

Problème : Deux crates exigent des versions différentes et incompatibles de la même dépendance.

Solution : Examinez l'arbre des dépendances :

cargo tree

Adaptez les exigences de version dans `Cargo.toml` ou utilisez `cargo update -p <package>` pour passer à une version compatible.

3. La build échoue avec « linker not found »

Problème : Votre système ne dispose pas du linker C dont Rust a besoin.

Solution : Installez les outils de build essentiels pour votre système d'exploitation. Sur Ubuntu/Debian :

sudo apt install build-essential

Sur macOS :

xcode-select --install

Cargo n'est pas un outil isolé — il constitue l'épine dorsale de chaque workflow Rust, du premier `cargo init` au déploiement de binaires optimisés. L'intégration avec rustup, crates.io et le compilateur permet de gérer des projets sans devoir comprendre la complexité sous-jacente des systèmes de build. À mesure que vos projets évoluent vers des workspaces, la compilation croisée ou des toolchains personnalisées, Cargo se révèle évolutif — mais la question n'est pas ce que Cargo peut faire, mais quel workflow vous construisez autour.