Introduction

Ce livre est un travail personnel.

J’ai choisi de le publier et de le partager pour « faire ma part ».

La consultation de ce livre est « en don libre ».

Oui, vous pouvez

Si vous souhaitez m’encourager ou m’aider, vous pouvez.

• effectuer un don.
  • Il vous suffit de me contacter, je vous communiquerai mes coordonnées bancaires.
• me proposer un travail rémunéré salarié
  • sédentaire
  • en télétravail
  • ou dans un bureau
    • si ce n’est pas dans une grande agglomération
    • si c’est au Nord de la France (Bretagne, Normandie, Nord)
      • ou plus au Nord (l’Irlande me plairait tout particulièrement)
  • que vous soyez :
    • une entreprise ;
    • une administration ;
    • une association ou
    • un·e particulier·e.

Mes sites concernant Rust

• Apprendre et maîtriser Rust
• Apprendre Rust par l’exemple
• Rust en vrac
• Trucs et astuces Rust

mdBook

• Apprendre et maîtriser mdBook

Bonne lecture

Si vous rencontriez des erreurs, si vous souhaitiez suggérer des ajouts, ou pour toute autre démarche constructive et pertinente, n’hésitez pas à me contacter.

Merci.

Marc JESTIN,
éco-citoyen du monde
https://marcjestin.fr

Avertissement

Ce livre mdbook est à l’étape du projet de création et dans son format brouillon (draft) pour le moment.

Il peut comporter des défauts ou des erreurs et sa forme comme son contenu évoluent continuellement.

Merci de votre compréhension.

Si vous souhaitez m’apporter votre soutien ou votre concours pour ce projet, vous pouvez me contacter.

Marc JESTIN
éco-citoyen du monde
https://marcjestin.fr

Conseils de lecture

Ce livre est réalisé avec mdbook, l’outil de documentation de la communauté Rust.

Zoom d’affichage

Les sites web modernes ont la fâcheuse habitude de gaspiller de l’espace disponible et d’user nos organes visuels prématurémement.

Je vous recommande vivement de régler le zoom d’affichage pour un confort optimal.
Niveau de zoom à mon avis confortable :

• 150 % pour un moniteur 1920 x 1080 ;
• 180 % pour un moniteur 2560 x 1440 ;
• 240 % pour un moniteur 3840 x 2160.

Nos yeux et nos oreilles sont précieux (et les dégâts que nous leur causons sont irréversibles) :
PRÉSERVONS-LES !

Blocs de codes

mdBook permet de disposer d’un outil avec des blocs de codes Rust interactifs riches.

Tous les blocs de codes sont copiables directement ou avec le bouton ad hoc.

Nous pouvons en plus :

• les éditer (modifier) en nous plaçant dans le code et en supprimant ou saisissant du code ;
  • un bouton permet de remettre le code dans son état d’origine si besoin ;
• les compiler (ou obtenir les messages d’avertissement et d’erreur du compilateur) et / ou
• lorsque c’est prévu pour, observer leurs produits d’exécution affichages.

Lorsque des codes comportent des exemples d’erreurs qui ne passent pas à la compilation, ces parties sont commentées. Décommentez-les, cliquez sur le bouton pour compiler et / ou exécuter, et lisez les retours du compilateur que vous obtenez à l’écran.

Vous pouvez également tout à loisir modifier le code et faire vos propres essais.

Exemple

Exercez-vous avec ce bloc simple :

• retirez les // à gauche de x += 1; puis
• cliquez sur « Run this code » (flèche « play »).
• Cliquez sur le bouton pour rétablir le code (Undo changes) puis
• cliquez sur « Run this code » (flèche « play ») à nouveau.

fn main() {
    let x = 7;
    // x += 1;  // Erreur à la compilation
}

Nota : les boutons interactifs apparaissent

• lorsque nous survolons le bloc de code avec notre souris ou
• lorsque nous touchons l’écran une première fois dans la zone du bloc de code (écrans tactiles de tablettes et d’ordiphones).

Note à propos des limitations

Certains comportements ne sont pas possibles avec l’espace de jeu (playground) Rust qui est utilisé pour ce faire.

C’est la raison pour laquelle certains codes retournent des erreurs de compilation sur le site alors qu’ils sont opérationnels « en conditions réelles ». C’est très rare, mais cela arrive (codes liés aux macros procédurales en fin de livre).

Dans de tels cas, copiez-collez le code dans une machine où Rust est installé pour les tester.

Lecture à deux niveaux

Vous croiserez parfois des blocs comme celui-ci :

Nota :

• Cliquez sur le bloc « Compléments de lecture (avancés) » pour le développer.
• Cliquez à nouveau pour le réduire.

Utilisation des outils de mdbook

Prenez le temps d’interagir avec les espaces de ce site pour savoir ce que vous pouvez faire :

• parcours facilité
  • « tourner la page à droite » (flèche sur le côté droit) ;
  • « tourner la page à gauche » (flèche sur le côté gauche) ;
• options de l’inteface
  • masquer la barre latérale (hamburger) ;
  • modifier le thème d’affichage (pinceau) ;
  • rechercher (loupe) ;
• imprimer
  • vous pouvez produire une version imprimable du contenu de l’ensemble de ce livre (imprimante à droite).
    • en perdant toutefois toute l’interactivité des blocs de code…
    • que vous pouvez enregistrer au format pdf pour le parcourir hors connexion par exemple.

https://apprendre-rust-par-l-exemple.marcjestin.fr/conseils_de_lecture.html?highlight=ceci%20est%20un%20test#zoom-daffichage

https://apprendre-rust-par-l-exemple.marcjestin.fr/conseils_de_lecture.html

Utiliser examples/

Il peut être pratique de savoir écrire et exécuter des petits bouts de programmes Rust indépendants pour les compiler et exécuter avec cargo run.

Il existe une petite astuce dans Rust bien pratique : les programmes exemples.

L’usage premier de ces programmes est de montrer des usages de bibliothèques écrites en Rust.

Nous pouvons nous servir de cette fonctionnalité native pour écrire des bouts de programmes indépendants dans un projet commun Rust.

Fonctionnement des exemples

Il suffit de créer un dossier examples/ à la racine du projet et d’y écrire un code source Rust de programme mon_premier_exemple.rs. Ce programme doit comporter une fonction fn main().

Ceci fait, la commande

cargo run --example mon_premier_exemple # (sans le .rs)

compile (si nécessaire) et exécute le programme ainsi créé.

Mise en application

Nous écrivons le code source examples/mon_premier_exemple.rs suivant :

fn main() {
    println!("Ceci est mon premier exemple.");
}

puis nous l’exécutons.

Astuce : pour saisir le nom du code à compiler et exécuter, nous pouvons nous servir de l’autocomplétion du shell (touche tabulation).

Optimisation de code

Rust propose deux options de compilation :

• debug : option utilisée par défaut, plus rapide ;
• release : option recommandée pour la production des programmes, plus lente car le compilateur modifie certains comportements et réalise des optimisations de code.

Nous pouvons déjà utiliser l’option --release de cargo avec nos programmes exemples. Ce sera bien pratique pour tester différentes stratégies algorithmiques et leurs performances : nous verrons alors que les versions debug et les versions release ne se comportent pas de la même manière.

cargo run --release --example mon_premier_exemple # (sans le .rs)

Utiliser examples/ pour des tests (exemples) documentaires

En principe, Rust prévoit qu’il n’y a qu’un seul fichier librairie dans un projet (crate), par défaut le fichier src/lib.rs.

Nous pouvons toutefois effectuer des tests sur des bouts de codes de librairies et de tests documentaires indépendants en suivant le protocole suivant.

Paramétrage dans Cargo.toml

[lib]

[[example]]
name = "lib_exemple"
path = "examples/lib_exemple/lib.rs"
crate-type = ["lib"]
doctest = true

Fichier src/lib.rs

#![allow(unused)]
fn main() {
#[doc(hidden)]
#[path = "../examples/lib_exemple/lib.rs"]
pub mod lib_exemple;
}

Nous déclarons le module avec le chemin vers notre fichier isolé. Pour éviter les conflits et / ou pour éviter qu’il ne soit publié avec la documentation de l’API du projet en cours, nous le déclarons caché pour la documentation.

Fichier examples/lib_exemple/lib.rs

#![allow(unused)]
fn main() {
/// ```
/// use rust_divers::lib_exemple::ajouter;
/// 
/// let a: i32 = 5_i32;
/// let b: i32 = 2_i32;
/// let resultat: i32 = ajouter(a, b);
/// assert_eq!(resultat, 7_i32);
/// ```
pub fn ajouter(a: i32, b: i32) -> i32 {
    a + b // Expression de retour (pas de point-virgule)
}
}

Nous nous servons de la syntaxe habituelle pour les exemples documentaires de Rust.

Au niveau de l’import (use) :

• rust_divers est le nom du projet,
• lib_exemple est le nom de la librairie tel que nous l’avons défini dans src/lib.rs et
• ajouter est le nom de la fonction sur laquelle porte notre exemple (et test unitaire).

Exécution

La commande habituelle

cardo test --doc

exécute le test contenu dans examples/lib_exemple/lib.rs.

Retour :

   Compiling rust-divers v0.1.0 (/home/user/mesprojets/rust-divers)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.00s
   Doc-tests rust_divers

running 1 test
test src/../examples/lib_exemple/lib.rs - lib_exemple_test::ajouter (line 1) ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

all doctests ran in 0.60s; merged doctests compilation took 0.59s

À propos

mdBook

Ce site est construit avec mdBook, l’outil de documentation externe de la communauté Rust.

Auteur

Je m’appelle Marc JESTIN.

J’ai 55 ans, je réside actuellement en FRANCE à SURGÈRES (17).

Pour en savoir plus ou pour me contacter, rendez-vous sur

https://marcjestin.fr

Mes sites au sujet de Rust

• Apprendre et maîtriser Rust
• Apprendre Rust par l’exemple
• Rust en vrac
• Trucs et astuces Rust

mdBook

• Apprendre et maîtriser mdBook