Cargo : Gestionnaire de construction et de packages de Rust

Introduction

Bienvenue dans Hello, Cargo. Ce laboratoire est une partie du Rust Book. Vous pouvez pratiquer vos compétences Rust dans LabEx.

Dans ce laboratoire, nous allons découvrir Cargo, le système de construction et le gestionnaire de packages de Rust, qui simplifie les tâches telles que la construction du code, la gestion des dépendances et le téléchargement de bibliothèques pour les projets Rust.

Hello, Cargo

Cargo est le système de construction et le gestionnaire de packages de Rust. La plupart des Rustaceens utilisent cet outil pour gérer leurs projets Rust car Cargo gère de nombreuses tâches pour vous, telles que la construction de votre code, le téléchargement des bibliothèques dont votre code dépend et la construction de ces bibliothèques. (Nous appelons les bibliothèques dont votre code a besoin dépendances.)

Les programmes Rust les plus simples, comme celui que nous avons écrit jusqu'à présent, n'ont pas de dépendances. Si nous avions construit le projet "Hello, world!" avec Cargo, il n'utiliserait que la partie de Cargo qui gère la construction de votre code. Lorsque vous écrivez des programmes Rust plus complexes, vous ajouterez des dépendances, et si vous commencez un projet en utilisant Cargo, ajouter des dépendances sera beaucoup plus facile.

Parce que la vaste majorité des projets Rust utilisent Cargo, le reste de ce livre suppose que vous utilisez également Cargo. Cargo est installé avec Rust si vous avez utilisé les installateurs officiels discutés dans "Installation". Si vous avez installé Rust par d'autres moyens, vérifiez si Cargo est installé en tapant la commande suivante dans votre terminal :

cargo --version

Si vous voyez un numéro de version, vous l'avez! Si vous voyez une erreur, telle que command not found, consultez la documentation de votre méthode d'installation pour déterminer comment installer Cargo séparément.

Création d'un projet avec Cargo

Créeons un nouveau projet avec Cargo et examinons en quoi il diffère de notre projet original "Hello, world!". Revoyez dans votre répertoire project (ou n'importe où vous avez décidé de stocker votre code). Ensuite, sur n'importe quel système d'exploitation, exécutez les commandes suivantes :

cd ~/project
cargo new hello_cargo
cd hello_cargo

La première commande crée un nouveau répertoire et un nouveau projet appelé hello_cargo. Nous avons nommé notre projet hello_cargo, et Cargo crée ses fichiers dans un répertoire du même nom.

Entrez dans le répertoire hello_cargo et liste les fichiers. Vous verrez que Cargo a généré deux fichiers et un répertoire pour nous : un fichier Cargo.toml et un répertoire src contenant un fichier main.rs.

Il a également initialisé un nouveau référentiel Git ainsi qu'un fichier .gitignore. Les fichiers Git ne seront pas générés si vous exécutez cargo new dans un référentiel Git existant ; vous pouvez contourner ce comportement en utilisant cargo new --vcs=git.

Note : Git est un système de contrôle de version courant. Vous pouvez modifier cargo new pour utiliser un autre système de contrôle de version ou aucun système de contrôle de version en utilisant le drapeau --vcs. Exécutez cargo new --help pour voir les options disponibles.

Ouvrez Cargo.toml dans votre éditeur de texte favori. Il devrait ressembler au code de la Liste 1-2.

Nom de fichier : Cargo.toml

[package]
name = "hello_cargo"
version = "0.1.0"
edition = "2021"

[dependencies]

Liste 1-2 : Contenu de Cargo.toml généré par cargo new

Ce fichier est au format TOML (Tom's Obvious, Minimal Language), qui est le format de configuration de Cargo.

La première ligne, [package], est un en-tête de section qui indique que les déclarations suivantes configurent un package. Lorsque nous ajouterons plus d'informations à ce fichier, nous ajouterons d'autres sections.

Les trois lignes suivantes définissent les informations de configuration dont Cargo a besoin pour compiler votre programme : le nom, la version et l'édition de Rust à utiliser. Nous parlerons de la clé edition dans l'Annexe E.

La dernière ligne, [dependencies], est le début d'une section où vous pouvez lister toutes les dépendances de votre projet. En Rust, les packages de code sont appelés crates. Nous n'aurons pas besoin d'autres crates pour ce projet, mais nous en aurons besoin dans le premier projet du Chapitre 2, donc nous utiliserons cette section de dépendances alors.

Maintenant, ouvrez src/main.rs et regardez :

Nom de fichier : src/main.rs

fn main() {
    println!("Hello, world!");
}

Cargo a généré un programme "Hello, world!" pour vous, tout comme celui que nous avons écrit dans la Liste 1-1! Jusqu'à présent, les différences entre notre projet et le projet généré par Cargo sont que Cargo a placé le code dans le répertoire src et que nous avons un fichier de configuration Cargo.toml dans le répertoire supérieur.

Cargo s'attend à ce que vos fichiers sources se trouvent à l'intérieur du répertoire src. Le répertoire racine du projet est juste pour les fichiers README, les informations de licence, les fichiers de configuration et tout autre élément non lié à votre code. Utiliser Cargo vous aide à organiser vos projets. Il y a un endroit pour tout, et tout est à sa place.

Si vous avez commencé un projet qui ne utilise pas Cargo, comme nous l'avons fait avec le projet "Hello, world!", vous pouvez le convertir en un projet qui utilise Cargo. Déplacez le code du projet dans le répertoire src et créez un fichier Cargo.toml approprié.

Compilation et exécution d'un projet Cargo

Maintenant, examinons ce qui est différent lorsque nous compilons et exécutons le programme "Hello, world!" avec Cargo! Depuis votre répertoire hello_cargo, compilez votre projet en tapant la commande suivante :

$ cargo build
   Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 2.85 secs

Cette commande crée un fichier exécutable dans target/debug/hello_cargo plutôt que dans votre répertoire actuel. Parce que la compilation par défaut est une compilation de débogage, Cargo place le binaire dans un répertoire nommé debug. Vous pouvez exécuter l'exécutable avec cette commande :

$./target/debug/hello_cargo
Hello, world!

Si tout se passe bien, Hello, world! devrait s'afficher dans le terminal. L'exécution de cargo build pour la première fois entraîne également la création d'un nouveau fichier au niveau supérieur : Cargo.lock. Ce fichier suit les versions exactes des dépendances de votre projet. Ce projet n'a pas de dépendances, donc le fichier est un peu sparse. Vous n'aurez jamais besoin de modifier manuellement ce fichier ; Cargo gère son contenu pour vous.

Nous venons de compiler un projet avec cargo build et de l'exécuter avec ./target/debug/hello_cargo, mais nous pouvons également utiliser cargo run pour compiler le code puis exécuter l'exécutable résultant en une seule commande :

$ cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
     Running `target/debug/hello_cargo`
Hello, world!

Utiliser cargo run est plus pratique que de devoir se souvenir d'exécuter cargo build puis d'utiliser le chemin complet vers le binaire, donc la plupart des développeurs utilisent cargo run.

Remarquez que cette fois-ci, nous n'avons pas vu de sortie indiquant que Cargo compilait hello_cargo. Cargo a déterminé que les fichiers n'avaient pas été modifiés, donc il n'a pas reconstruit mais a simplement exécuté le binaire. Si vous aviez modifié votre code source, Cargo aurait reconstruit le projet avant de l'exécuter, et vous auriez vu cette sortie :

$ cargo run
   Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.33 secs
     Running `target/debug/hello_cargo`
Hello, world!

Cargo fournit également une commande appelée cargo check. Cette commande vérifie rapidement votre code pour vous assurer qu'il se compile mais ne produit pas d'exécutable :

$ cargo check
   Checking hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs

Pourquoi ne voudriez-vous pas un exécutable? Souvent, cargo check est beaucoup plus rapide que cargo build car elle saute l'étape de production d'un exécutable. Si vous vérifiez constamment votre travail pendant que vous écrivez le code, utiliser cargo check accélérera le processus de vérification si votre projet se compile toujours! En conséquence, de nombreux Rustaceans exécutent cargo check régulièrement pendant qu'ils écrivent leur programme pour s'assurer qu'il se compile. Ensuite, ils exécutent cargo build lorsqu'ils sont prêts à utiliser l'exécutable.

Récapitulons ce que nous avons appris jusqu'à présent sur Cargo :

• Nous pouvons créer un projet en utilisant cargo new.
• Nous pouvons compiler un projet en utilisant cargo build.
• Nous pouvons compiler et exécuter un projet en une seule étape en utilisant cargo run.
• Nous pouvons compiler un projet sans produire un binaire pour vérifier les erreurs en utilisant cargo check.
• Au lieu de sauvegarder le résultat de la compilation dans le même répertoire que notre code, Cargo le stocke dans le répertoire target/debug.

Un avantage supplémentaire d'utiliser Cargo est que les commandes sont les mêmes peu importe le système d'exploitation sur lequel vous travaillez. Ainsi, à partir de maintenant, nous ne fournirons plus d'instructions spécifiques pour Linux et macOS par rapport à Windows.

Compilation pour la version de production

Lorsque votre projet est finalement prêt à être publié, vous pouvez utiliser cargo build --release pour le compiler avec des optimisations.

cargo build --release

Cette commande créera un exécutable dans target/release au lieu de target/debug. Les optimisations font en sorte que votre code Rust s'exécute plus rapidement, mais les activer augmente le temps nécessaire pour compiler votre programme. C'est pourquoi il existe deux profils différents : l'un pour le développement, lorsque vous voulez reconstruire rapidement et souvent, et l'autre pour la construction du programme final que vous donnerez à un utilisateur qui ne sera pas reconstruit plusieurs fois et qui devra s'exécuter le plus rapidement possible. Si vous effectuez des tests de performance de votre code, assurez-vous d'exécuter cargo build --release et de faire des tests de performance avec l'exécutable dans target/release.

Cargo, une convention

Avec de simples projets, Cargo ne procure pas beaucoup de valeur par rapport à l'utilisation simple de rustc, mais sa valeur se révèlera au fur et à mesure que vos programmes deviendront plus complexes. Une fois que les programmes deviennent composés de plusieurs fichiers ou ont besoin d'une dépendance, il est beaucoup plus facile de laisser Cargo coordonner la compilation.

Même si le projet hello_cargo est simple, il utilise désormais beaucoup des outils réels que vous utiliserez pour le reste de votre carrière Rust. En fait, pour travailler sur n'importe quel projet existant, vous pouvez utiliser les commandes suivantes pour récupérer le code avec Git, accéder au répertoire de ce projet et compiler :

git clone example.org/someproject
cd someproject
cargo build

Pour en savoir plus sur Cargo, consultez sa documentation sur https://doc.rust-lang.org/cargo.

Sommaire

Félicitations! Vous avez terminé le laboratoire Hello, Cargo. Vous pouvez pratiquer d'autres laboratoires sur LabEx pour améliorer vos compétences.