Introduction
Les programmes Rust réels réutilisent souvent des bibliothèques spécialisées au lieu de réimplémenter chaque fonctionnalité. Une bibliothèque Rust publiée s'appelle une crate, et une crate utilisée par votre paquet est une dépendance. Choisir et ajouter une dépendance de manière sûre fait partie du développement Rust courant.
Dans ce laboratoire, vous allez ajouter l'analyseur de ligne de commande clap à un programme de salutations préparé. Vous effectuerez deux petites modifications du code source, observerez l'aide et la validation générées automatiquement, puis découvrirez les rôles différents de Cargo.toml et Cargo.lock. La dépendance est téléchargée à l'avance pendant la configuration afin que votre première compilation reste rapide, mais c'est à vous de l'ajouter au projet de l'apprenant.
Ajouter la dépendance avec Cargo
Dans cette étape, vous allez ajouter clap au paquet préparé et examiner la modification du manifeste effectuée par Cargo.
Le projet se trouve dans /home/labex/project/hello-cli. Accédez-y avant d'exécuter des commandes Cargo :
cd /home/labex/project/hello-cli
Ouvrez le manifeste du paquet avec nano :
nano Cargo.toml
Cargo.toml décrit le paquet et ses dépendances directes. La table [dependencies] vide signifie que ce projet utilise actuellement uniquement la bibliothèque standard de Rust. Appuyez sur Ctrl+X pour quitter nano sans modifier le fichier.
La commande cargo add met à jour la table des dépendances de manière sûre. Ajoutez clap en version 4.6.7 et activez sa fonctionnalité derive :
cargo add clap@4.6.7 --features derive
Une fonctionnalité active une partie facultative d'une crate. Ici, derive active les macros qui transforment les structures et les énumérations Rust en analyseurs de ligne de commande. Cargo affiche les fonctionnalités activées avec + et les fonctionnalités désactivées avec - ; les fonctionnalités désactivées ne sont pas des erreurs.
Ouvrez de nouveau le manifeste :
nano Cargo.toml
La table des dépendances contient maintenant une ligne de cette forme :
clap = { version = "4.6.7", features = ["derive"] }
La version constitue une exigence de compatibilité. Cargo peut sélectionner une version 4.x compatible plus récente, tandis que les versions exactes sélectionnées sont enregistrées séparément dans Cargo.lock. Appuyez sur Ctrl+X pour fermer nano.
Dériver un analyseur de ligne de commande
Dans cette étape, vous allez relier la structure Cli à clap à l'aide d'une macro derive et de métadonnées de commande.
Ouvrez le fichier source préparé :
nano src/main.rs
Vous avez déjà utilisé #[derive(Debug)] dans le cours pour débutants. Une macro derive demande à une crate de générer l'implémentation d'un trait à partir de la structure d'un type. Remplacez le premier commentaire TODO au-dessus de struct Cli par ces deux lignes :
#[derive(Parser)]
#[command(version, about = "Create a friendly greeting")]
#[derive(Parser)] génère le comportement d'analyse. L'attribut #[command(...)] fournit des informations sur l'ensemble de la commande : version lit la version du paquet dans Cargo.toml, et about fournit une brève description.
Enregistrez avec Ctrl+O, appuyez sur Entrée, puis quittez avec Ctrl+X. Vérifiez le programme sans l'exécuter :
cargo check
La première vérification compile clap et ses crates de prise en charge ; plusieurs lignes Compiling et Checking peuvent donc s'afficher. Une dernière ligne commençant par Finished signifie que la dépendance et l'analyseur généré se compilent correctement ensemble.
Demandez maintenant l'aide du programme. Le séparateur -- distingue les options de Cargo des arguments transmis à votre programme :
cargo run --quiet -- --help
La sortie contient la description, une valeur obligatoire <NAME> ainsi que les options d'aide et de version générées automatiquement :
Create a friendly greeting
Usage: hello-cli <NAME>
...
Vous avez défini la structure des données ; clap en a déduit une aide cohérente et la validation des arguments.
Ajouter une option de répétition facultative
Dans cette étape, vous allez ajouter une option typée et utiliser la valeur analysée dans une petite boucle.
Exécutez d'abord la commande avec un seul nom positionnel :
cargo run --quiet -- Ada
Hello, Ada!
name: String devient une valeur positionnelle obligatoire, car il ne possède aucun attribut #[arg(...)]. Ouvrez de nouveau le fichier source :
nano src/main.rs
Remplacez le deuxième commentaire TODO dans Cli par :
/// Number of greetings to print
#[arg(short, long, default_value_t = 1)]
times: u8,
Le commentaire de documentation devient le texte d'aide. short crée -t, long crée --times et default_value_t = 1 fournit une valeur par défaut typée lorsque l'option est absente. Comme le champ est de type u8, clap rejette également les valeurs qui ne sont pas des entiers non signés valides sur 8 bits.
Remplacez le dernier commentaire TODO et l'unique ligne println! par :
for _ in 0..cli.times {
println!("Hello, {}!", cli.name);
}
Le caractère de soulignement indique que le compteur de la boucle n'est volontairement pas utilisé. Enregistrez le fichier, quittez nano, puis exécutez trois salutations :
cargo run --quiet -- Ada --times 3
Hello, Ada!
Hello, Ada!
Hello, Ada!
Essayez également une valeur invalide :
cargo run --quiet -- Ada --times many
Cette commande doit échouer. clap affiche une erreur expliquant que many n'est pas un u8 valide, puis se termine avec un code différent de zéro avant que main n'utilise une valeur invalide.
Examiner et réutiliser le graphe de dépendances verrouillé
Dans cette étape, vous allez examiner le graphe des dépendances résolu par Cargo et vérifier que le fichier de verrouillage permet de le reproduire sans accès au réseau.
clap est votre dépendance directe, mais elle utilise elle-même d'autres crates de prise en charge. Affichez le premier niveau du graphe résolu :
cargo tree --depth 1
La version de correctif exacte peut être plus récente que l'exigence compatible indiquée dans Cargo.toml. La structure importante est la suivante :
hello-cli v0.1.0 (...)
└── clap v4...
Ouvrez le fichier de verrouillage généré :
nano Cargo.lock
Cargo.lock contient des données générées ; vous ne devez donc normalement pas le modifier manuellement. Il enregistre les versions exactes et les sommes de contrôle sélectionnées par Cargo pour l'ensemble du graphe. Pour une application comme cette CLI, conservez le fichier de verrouillage avec le projet afin que vos coéquipiers et les compilations automatisées puissent réutiliser la même résolution. Appuyez sur Ctrl+X pour fermer nano.
Exigez maintenant à la fois le fichier de verrouillage existant et le cache local des crates :
cargo check --locked --offline
--locked refuse de modifier Cargo.lock. --offline empêche tout accès au réseau. Une dernière ligne Finished prouve que ce projet peut être vérifié à partir du graphe de dépendances déjà téléchargé, sans résoudre silencieusement d'autres versions.
Résumé
Vous avez ajouté une dépendance directe de crate avec Cargo, activé une fonctionnalité facultative, dérivé un analyseur clap typé et observé l'aide ainsi que la validation automatiques. Vous avez également distingué l'exigence de compatibilité de Cargo.toml du graphe exact des dépendances de Cargo.lock, puis vérifié que ce graphe verrouillé fonctionne hors ligne.
