The Rust Programming Language

Hello, Cargo!

Cargo est le système de build et le gestionnaire de paquets de Rust. La plupart des Rustaceans utilisent cet outil pour gérer leurs projets Rust car Cargo géré de nombreuses tâches pour vous, comme compiler votre code, télécharger les bibliothèques dont votre code depend, et compiler ces bibliothèques. (Nous appelons les bibliothèques dont votre code a besoin des dependances.)

Les programmes Rust les plus simples, comme celui que nous avons écrit jusqu’ici, n’ont aucune dépendance. Si nous avions construit le projet “Hello, world!” avec Cargo, nous n’aurions utilise que la partie de Cargo qui géré la compilation de votre code. A mesure que vous écrirez des programmes Rust plus complexes, vous ajouterez des dépendances, et si vous demarrez un projet avec Cargo, l’ajout de dépendances sera beaucoup plus facile.

Comme la grande 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 présentés dans la section « Installation ». Si vous avez installé Rust par un autre moyen, vérifiez si Cargo est installé en entrant la commande suivante dans votre terminal :

$ cargo --version

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

Créer un projet avec Cargo

Créons un nouveau projet en utilisant Cargo et voyons en quoi il diffère de notre projet “Hello, world!” original. Retournez dans votre repertoire projects (ou la où vous avez decide de stocker votre code). Puis, sur n’importe quel système d’exploitation, exécutez la commande suivante :

$ cargo new hello_cargo
$ cd hello_cargo

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

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

Il a également initialise un nouveau dépôt Git avec un fichier .gitignore. Les fichiers Git ne seront pas générés si vous exécutez cargo new dans un dépôt Git existant ; vous pouvez forcer ce comportement en utilisant cargo new --vcs=git.

Note : Git est un système de contrôle de version courant. Vous pouvez configurer 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 l’éditeur de texte de votre choix. Il devrait ressembler au code de l’Encadre 1-2.

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

[dependencies]

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-tete de section qui indique que les instructions suivantes configurent un package. Au fur et a mesure que nous ajouterons des 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 derniere ligne, [dependencies], est le début d’une section ou vous pouvez lister les dépendances de votre projet. En Rust, les packages de code sont appelés des crates. Nous n’aurons besoin d’aucune autre crate pour ce projet, mais nous en aurons besoin dans le premier projet du Chapitre 2, et nous utiliserons alors cette section de dépendances.

Maintenant, ouvrez src/main.rs et jetez-y un coup d’oeil :

Fichier : src/main.rs rust {{#rustdoc_include ../listings/ch05-using-structs-to-structure-related-data/no-listing-03-associated-functions/src/main.rs:here}}

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

Cargo a généré un programme “Hello, world!” pour vous, exactement comme celui que nous avons écrit dans l’Encadre 1-1 ! Jusqu’ici, les differences entre notre projet et le projet généré par Cargo sont que Cargo a place le code dans le repertoire src, et que nous avons un fichier de configuration Cargo.toml dans le repertoire racine.

Cargo s’attend à ce que vos fichiers source se trouvent dans le repertoire src. Le repertoire racine du projet est reserve aux fichiers README, aux informations de licence, aux fichiers de configuration et à tout ce qui n’est pas lie à votre code. Utiliser Cargo vous aide a organiser vos projets. Il y à une place pour chaque chose, et chaque chose est à sa place.

Si vous avez demarre un projet qui n’utilise pas Cargo, comme nous l’avons fait avec le projet “Hello, world!”, vous pouvez le convertir en un projet qui utilise Cargo. Deplacez le code du projet dans le repertoire src et créez un fichier Cargo.toml appropriate. Un moyen facile d’obtenir ce fichier Cargo.toml est d’exécuter cargo init, qui le créera automatiquement pour vous.

Compiler et exécuter un projet Cargo

Voyons maintenant ce qui change lorsque nous compilons et exécutons le programme “Hello, world!” avec Cargo ! Depuis votre repertoire hello_cargo, compilez votre projet en entrant 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 (ou target\debug\hello_cargo.exe sous Windows) plutot que dans votre repertoire courant. Comme la compilation par défaut est une compilation de debogage, Cargo place le binaire dans un repertoire nomme debug. Vous pouvez exécuter l’exécutable avec cette commande :

$ ./target/debug/hello_cargo # or .\target\debug\hello_cargo.exe on Windows
Hello, world!

Si tout se passe bien, Hello, world! devrait s’afficher dans le terminal. Exécuter cargo build pour la première fois amene également Cargo a créer un nouveau fichier à la racine : Cargo.lock. Ce fichier garde la trace des versions exactes des dépendances de votre projet. Ce projet n’a pas de dépendances, donc le fichier est un peu vide. Vous n’aurez jamais besoin de modifier ce fichier manuellement ; Cargo géré 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 aussi utiliser cargo run pour compiler le code puis exécuter l’exécutable resultant, le tout 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, c’est pourquoi la plupart des développeurs utilisent cargo run.

Remarquez que cette fois, nous n’avons pas vu de sortie indiquant que Cargo compilait hello_cargo. Cargo a déterminé que les fichiers n’avaient pas change, donc il n’a pas recompile mais a simplement exécute le binaire. Si vous aviez modifié votre code source, Cargo aurait recompile 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 s’assurer qu’il compilé, 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 d’exécutable ? Souvent, cargo check est beaucoup plus rapide que cargo build car il saute l’étape de production d’un exécutable. Si vous vérifiez continuellement votre travail pendant que vous écrivez le code, utiliser cargo check accelerera le processus pour savoir si votre projet compilé toujours ! C’est pourquoi de nombreux Rustaceans exécutent cargo check periodiquement pendant qu’ils écrivent leur programme pour s’assurer qu’il compilé. Ensuite, ils exécutent cargo build lorsqu’ils sont prêts à utiliser l’exécutable.

Récapitulons ce que nous avons appris jusqu’ici 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 de 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 stocké dans le répertoire target/debug.

Un avantage supplementaire de l’utilisation de Cargo est que les commandes sont les mêmes quel que soit le système d’exploitation sur lequel vous travaillez. Donc, à partir de maintenant, nous ne fournirons plus d’instructions spécifiques pour Linux et macOS par rapport a Windows.

Compiler pour la publication

Lorsque votre projet est enfin prêt pour la publication, vous pouvez utiliser cargo build --release pour le compiler avec des optimisations. Cette commande créera un exécutable dans target/release au lieu de target/debug. Les optimisations rendent votre code Rust plus rapide, mais les activer allonge le temps de compilation de votre programme. C’est pourquoi il y a deux profils différents : un pour le développement, quand vous voulez recompiler rapidement et souvent, et un autre pour construire le programme final que vous donnerez à un utilisateur, qui ne sera pas recompile frequemment et qui s’exécutera aussi vite que possible. Si vous mesurez les performances de votre code, assurez-vous d’exécuter cargo build --release et de tester avec l’exécutable dans target/release.

Tirer parti des conventions de Cargo

Pour les projets simples, Cargo n’apporte pas beaucoup de valeur ajoutée par rapport à la simple utilisation de rustc, mais il prouvera sa valeur a mesure que vos programmes deviendront plus complexes. Une fois que les programmes s’etendent à plusieurs fichiers ou nécessitent 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éjà une grande partie des outils réels que vous utiliserez tout au long de votre parcours avec Rust. En fait, pour travailler sur n’importe quel projet existant, vous pouvez utiliser les commandes suivantes pour recuperer le code avec Git, accéder au repertoire du projet et compiler :

$ git clone example.org/someproject
$ cd someproject
$ cargo build

Pour plus d’informations sur Cargo, consultez sa documentation.

Résumé

Vous avez déjà pris un excellent départ dans votre parcours Rust ! Dans ce chapitre, vous avez appris à :

• Installer la dernière version stable de Rust en utilisant rustup.
• Mettre à jour vers une version plus récente de Rust.
• Ouvrir la documentation installée localement.
• Écrire et exécuter un programme Hello, world! en utilisant directement rustc.
• Créer et exécuter un nouveau projet en utilisant les conventions de Cargo.

C’est le moment ideal pour construire un programme plus consequent afin de vous habituer a lire et écrire du code Rust. Ainsi, au Chapitre 2, nous construirons un programme de jeu de devinettes. Si vous preferez commencer par apprendre comment les concepts de programmation courants fonctionnent en Rust, consultez le Chapitre 3 puis revenez au Chapitre 2.