FAQ sur la programmation en langage RustConsultez toutes les FAQ
Nombre d'auteurs : 1, nombre de questions : 95, dernière mise à jour : 21 juillet 2018 Ajouter une question
Cette FAQ a été réalisée pour répondre aux questions les plus fréquemment posées sur la programmation en langage Rust. Nous vous recommandons de la consulter avant de poser vos questions sur le forum Rust.
Nous tenons à souligner que cette FAQ ne garantit en aucun cas que les informations qu'elle contient sont correctes ; les auteurs font le maximum, mais l'erreur est humaine. Si vous trouvez une erreur, ou que vous souhaitez devenir rédacteur, lisez ceci.
Toute nouvelle question/réponse est la bienvenue, vous pouvez proposer vos questions réponses par e-mail (voir le lien en bas de page) au(x) responsable(s) de la rubrique Rust ou mieux en postant votre proposition à la publication.
Vous pouvez participer à l'amélioration des questions réponses en postant directement dans cette FAQ. Une validation par le(s) responsable(s) de la rubrique Rust sera requise avant que vos contributions ne soient visibles.
Sur ce, nous vous souhaitons une bonne lecture.
- Comment créer un projet avec Cargo ?
- Quel type de projet puis-je créer avec Cargo ?
- Comment compiler mon projet ?
- Peut-on générer de la documentation avec Cargo ?
- Où trouver de nouvelles bibliothèques ?
- Comment installer de nouvelles bibliothèques ?
- Comment publier sa bibliothèque faite maison ?
- Comment lancer des tests avec Cargo ?
- Comment mettre à jour mes bibliothèques ?
- Comment créer ses benchmarks avec Cargo ?
- À quoi sert benchmark_group! ?
- À quoi sert benchmark_main! ?
- Comment générer du code assembleur avec cargo ?
- Comment générer du code MIR avec cargo ?
Pour créer un nouveau projet avec Cargo, vérifiez d'abord qu'il est installé sur votre machine :
$ cargo -V
Puis :
$ cargo new nom_de_votre_repertoire
Vous devriez voir se générer un dossier avec le nom assigné dans lequel se trouvera un répertoire nommé src et un manifest nommé Cargo.toml.
Lorsque vous lancez la commande de génération (telle quelle), votre projet est généré en mode « bibliothèque », et n'est donc pas destiné à être directement exécuté.
Si vous souhaitez générer un projet en mode « exécutable », il suffit de le préciser dans la commande :
$ cargo new folder_name --bin
Par défaut, le nom du répertoire racine sera également le nom de votre bibliothèque si elle devait être identifiée par d'autres utilisateurs dans le but de la télécharger. Si vous souhaitez lui attribuer un autre nom, vous pouvez également le spécifier dans la commande :
$ cargo new folder_name --name project_name --bin
Le manifest sera modifié en conséquence.
Toutefois, si vous n'avez pas utilisé le flag --name durant la préparation de la commande, il est bien entendu toujours possible de modifier le nom de votre bibliothèque dans votre manifest.
Pour compiler votre projet, vous devez vous trouver à la racine de ce dernier.
Une fois que c'est fait, il vous suffit de lancer la commande suivante :
Code Bash : | Sélectionner tout |
$ cargo build
Il est également possible de laisser le compilateur effectuer ses optimisations.
Code Bash : | Sélectionner tout |
$ cargo build --release
Bien sûr !
Il suffit de lancer la commande $ cargo doc à la racine de votre projet.
La documentation se trouvera dans le dossier ./target/doc/…
Où est l'index de mon site ?
Il se trouve dans le répertoire portant le nom de votre projet.
Notez que si vous avez ajouté des dépendances à votre projet, cargo générera également la documentation de celles-ci (assurant alors un site uniforme et complet).
Vous pouvez trouver d'autres bibliothèques sur le site officiel de Cargo.
Il y a deux manières de faire :
- Les télécharger à partir de crate.io ;
- Les télécharger directement à partir de leur dépôt github.
C'est selon vos préférences (et surtout selon la disponibilité de la ressource).
Donc pour la première façon, rien de plus simple :
- vous cherchez la bibliothèque que vous désirez sur le site ;
- vous renseignez son nom dans votre manifest ;
- compilez ;
- c'est prêt !
Pour la seconde :
- cherchez le dépôt github de la bibliothèque désirée ;
- notez le nom que porte cette bibliothèque dans son manifest ;
- puis ajoutez cette ligne dans vos dépendances : lib_name = {git = "url du dépôt"} ;
- compilez ;
- c'est prêt !
Les procédures étant très bien expliquées sur le site de crates.io, nous vous invitons à vous rendre dans la section dédiée.
Si vous souhaitez malgré tout lire les procédures sur la FAQ, en voici une traduction :
Une fois que vous avez une bibliothèque que vous souhaiteriez partager avec le reste du monde, il est temps de la publier sur crates.io !
La publication d'un paquet est effective lorsqu'il est uploadé pour être hébergé par crates.io.
Réfléchissez avant de publier votre paquet, car sa publication est permanente.
La version publiée ne pourra jamais être écrasée par une autre, et le code ne pourra être supprimé.
En revanche, le nombre de versions publiées n'est pas limité.
Premièrement, vous allez avoir besoin d'un compte sur crates.io pour recevoir un « token » (jeton) provenant de l'API. Pour faire ceci, visitez la page d'accueil et enregistrez-vous via votre compte Github. Ensuite, rendez-vous dans vos options de compte, et lancez la commande $ cargo login suivi de votre token.
Code Bash : | Sélectionner tout |
$ cargo login abcdefghijklmnopqrstuvwxyz012345
Cette commande va informer Cargo que vous détenez un token provenant de l'API du site. (Il est enregistré dans le chemin suivant : ~/.cargo/config.)
Ce token doit rester secret et ne devrait être partagé avec personne. Si vous le perdez d'une quelconque manière, régénérez-le immédiatement.
Avant la publication du paquet
Gardez en tête que le nom de chaque paquet est alloué en respectant la règle du « premier arrivé, premier servi ». Une fois que vous avez choisi un nom, il ne pourra plus être utilisé pour un autre paquet.
Empaqueter le projet
La prochaine étape consiste à empaqueter votre projet de manière à être intelligible pour crates.io. Pour remédier à cela, nous allons utiliser la commande cargo package. Votre projet sera donc empaqueté sous le format *.crate et se trouvera dans le répertoire target/package/.
Code Bash : | Sélectionner tout |
$ cargo package
En plus de cela, la commande package est capable de vérifier l'intégrité de votre projet en dépaquetant votre *.crate et le recompiler. Si la phase de vérification se passe sans problème, rien ne devrait être affiché dans votre terminal.
Toutefois, si vous souhaitez désactiver cette vérification avant l'envoi, il vous suffit d'ajouter le flag --no-verify.
Cargo va ignorer automatiquement tous les fichiers ignorés par votre système de versionning, mais si vous voulez spécifier un type de fichiers en particulier, vous pouvez utiliser le mot-clé exclude dans votre manifest :
[Exemple tiré de la documentation officielle de l'outil]
Code text : | Sélectionner tout |
1 2 3 4 5 6 | [package] # ... exclude = [ "public/assets/*", "videos/*", ] |
La syntaxe de chaque élément dans ce tableau est ce que glob accepte. Si vous souhaitez créer une whitelist au lieu d'une blacklist, vous pouvez utiliser le mot-clé include.
[Exemple tiré de la documentation officielle de l'outil]
Code text : | Sélectionner tout |
1 2 3 4 5 6 | [package] # ... include = [ "**/*.rs", "Cargo.toml", ] |
Maintenant que nous avons un fichier *.crate prêt à y aller, il peut être uploadé sur crates.io grâce à la commande cargo publish. C'est tout, vous venez de publier votre premier paquet !
Code Bash : | Sélectionner tout |
$ cargo publish
Si vous venez à oublier de lancer la commande cargo package, cargo publish le fera à votre place et vérifiera l'intégrité de votre projet avant de lancer l'étape de publication.
Il se pourrait que la commande publish vous refuse votre première publication. Pas de panique, ce n'est pas très grave.
Votre paquet, pour être différencié des autres, doit compter un certain nombre de métadonnées pour renseigner vos futurs utilisateurs sur les tenants et aboutissants de votre projet, comme la licence par exemple.
Pour ceci, vous pouvez vous rendre ici, et ainsi visionner un exemple simple des métadonnées à renseigner.
Relancez votre procédure cargo publish, vous ne devriez plus avoir de problème.
Code toml : | Sélectionner tout |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | [package] name = "verbose_bird" version = "0.3.2" authors = ["Songbird0 <chaacygg@gmail.com>"] description = "An awesome homemade loggers pack." documentation = "https://github.com/Songbird0/Verbose_Bird/blob/master/src/README.md" homepage = "https://github.com/Songbird0/Verbose_Bird" repository = "https://github.com/Songbird0/Verbose_Bird" readme = "README.md" keywords = ["Rust", "log", "loggers", "pack"] license = "GPL-3.0" license-file = "LICENSE.md" [dependencies] |
Il se peut que vous rencontriez également des problèmes avec l'entrée « license = ... » vous informant que le nom de licence entré n'est pas valide.
Pour régler le souci rendez-vous sur opensource.org et visionner les noms raccourcis entre parenthèses de chaque licence.
Pour lancer un test avec cargo, il vous faudra utiliser l'attribut #[test] et, évidemment, la commande $ cargo test.
Voici un exemple simple de tests :
Code Rust : | Sélectionner tout |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | #[cfg(test)] mod oo_tests { struct Alice; use loggers_pack::oop::Logger; impl Logger for Alice{/*...*/} #[test] fn pack_logger_oop_info() { Alice::info("@Alice", "Hello, I'm Alice ", "Peterson !"); } #[test] fn pack_logger_oop_wan() { Alice::warn("@Alice", "Hello, I'm Alice ", "Peterson !"); } #[test] fn pack_logger_oop_error() { Alice::error("@Alice", "Hello, I'm Alice ", "Peterson !"); } #[test] fn pack_logger_oop_success() { Alice::success("@Alice", "Hello, I'm Alice ", "Peterson !"); } } |
Chaque fonction annotée par l'attribut #[test] sera compilée durant la phase de test.
La version 1.9.0 de Rust comporte un bogue au niveau des tests. Dans cette version, toutes les fonctions annotées #[test] doivent être encapsulées dans un module. Ce n'est bien entendu plus le cas en 1.12.0.
Si vous rencontrez ce problème, nous vous conseillons de mettre à jour votre compilateur jusqu'à la version stable la plus récente possible.
Pour mettre à jour vos dépendances, il vous suffit d'utiliser la commande : $ cargo update.
Vous pouvez également préciser quelle bibliothèque mettre à jour séparément en utilisation l'option $ cargo update --precise nom_dep.
Faites tout de même attention avant de mettre à jour vos dépendances. Il se pourrait que les nouvelles versions cassent la compatibilité ascendante.
Pour créer nos benchmark, donc, nous allons utiliser le paquet bencher.
Ce module était premièrement connu sous le nom de "test" puis sera rebaptisé "bencher", qui sera porté en tant que dépendance externe pour éviter les effets de bord dans les versions stables du langage.
Code : | Sélectionner tout |
1 2 3 4 5 6 7 8 9 10 11 12 | [package] name = "awesome_tests" version = "0.1.0" authors = ["Songbird0 <chaacygg@gmail.com>"] [dependencies] bencher = "0.1.1" [[bench]] name = "my_bench" harness = false |
Code Rust : | Sélectionner tout |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | #[macro_use] extern crate bencher; use bencher::Bencher; fn find_short(s: &str) -> usize { let splitting: Vec<&str> = s.split_whitespace().collect(); let mut shortest_len: usize = 0; let mut i: usize = 0; while i < splitting.len() { if i == 0 { shortest_len = splitting[0].len(); } else { if splitting[i].len() < shortest_len { shortest_len = splitting[i].len(); } } i += 1; } shortest_len } fn bench_find_short(b: &mut Bencher) { b.iter(|| find_short("Hello darkness my old friend")); } benchmark_group!(my_bench, bench_find_short); benchmark_main!(my_bench); |
La macro bencmark_group! sert a créer des « groupes » de fonctions à mesurer lors de l'exécution de la commande cargo bench.
La macro benchmark_main! permet de créer une fonction main contenant toutes les fonctions à « benchmarker ».
Admettons que vous ayez un projet nommé MyProject:
Code Bash : | Sélectionner tout |
1 2 | $ cargo new --bin MyProject Created binary (application) `MyProject` project |
Après quelques ajouts, vous avez cette structure de projet:
Code : | Sélectionner tout |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | $ tree -L 3 . . ├── Cargo.lock ├── Cargo.toml ├── src │ ├── lib.rs │ ├── main.rs │ └── mymod │ └── mod.rs └── target └── debug ├── build ├── deps ├── examples ├── incremental ├── libmyproject.d ├── libmyproject.rmeta └── native 9 directories, 7 files |
Pour afficher le code assembleur de votre source:
Code Bash : | Sélectionner tout |
1 2 3 4 5 6 7 | cargo rustc --lib -- --emit asm # ------------------- ^ # Ne surtout pas oublier `--` sans quoi l'option `--emit` ne sera pas reconnue. Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs $ MIR_PATH="$PWD/target/debug/deps" $ ls $MIR_PATH liblmyproject-67ac3e08dd1b65f4.rlib lmyproject-67ac3e08dd1b65f4.s # <- Le fichier possédant l'extension `.s` contient l'assembleur de votre projet uniquement, pas celui de l'exécutable. |
Note: Ici vous pouvez remarquer qu'il y a un 'l' devant myproject alors que le nom de la crate n'en possède pas, dans votre fichier Cargo.toml. C'est tout simplement parce que, dans ma copie de locale, j'ai à la fois un fichier lib.rs et main.rs, ce qui permet de lever l'ambiguïté à la compilation (i.e. si l'on souhaite compiler le cœur du projet ou un exécutable). Voici mon manifeste Cargo.toml:
Code Toml : | Sélectionner tout |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | [package] name = "myproject" version = "0.1.0" authors = ["Anthony Defranceschi <chaacygg@gmail.com>"] [dependencies] [lib] name = "lmyproject" # <- Vous voyez ici que nous renseignons un nom différent au projet lorsqu'il est compilé en mode bibliothèque. path = "src/lib.rs" test = true doctest = true bench = true doc = true plugin = false proc-macro = false harness = true [[bin]] name = "myproject" path = "src/main.rs" |
Quid si vous souhaitez uniquement visualiser la génération de l'assembleur de l'exécutable dans ce cas ? La procédure est différente -mais de peu- puisqu'il faut remplacer l'option --lib par --bin nom_de_votre_crate comme vous le fera gentiment remarquer le compilateur si vous omettez l'un d'entre-eux:
Code : | Sélectionner tout |
1 2 | error: extra arguments to `rustc` can only be passed to one target, consider filtering the package by passing e.g. `--lib` or `--bin NAME` to specify a single target |
Code Bash : | Sélectionner tout |
1 2 3 4 5 6 | $ cargo clean && cargo rustc --bin myproject -- --emit asm Compiling myproject v0.1.0 (file:///home/anthony/Dropbox/MyProject) Finished dev [unoptimized + debuginfo] target(s) in 1.1 secs $ ls $MIR_PATH liblmyproject-0ca57a22ba238c7c.rlib myproject-e35372111538d081.s myproject-e35372111538d081 |
L'exécutable et son assembleur ont été générés, il ne vous reste plus qu'à visualiser le résultat avec votre éditeur de texte favoris !
Admettons que vous ayez un projet nommé MyProject:
Code Bash : | Sélectionner tout |
1 2 3 | $ cargo new --bin MyProject Created binary (application) `MyProject` project |
Après quelques ajouts, vous avez cette structure de projet:
Code : | Sélectionner tout |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | $ tree -L 3 . . ├── Cargo.lock ├── Cargo.toml ├── src │ ├── lib.rs │ ├── main.rs │ └── mymod │ └── mod.rs └── target └── debug ├── build ├── deps ├── examples ├── incremental ├── libmyproject.d ├── libmyproject.rmeta └── native 9 directories, 7 files |
Pour afficher le code MIR de votre source:
Code Bash : | Sélectionner tout |
1 2 3 4 5 6 7 | cargo rustc --lib -- --emit mir # ------------------- ^ # Ne surtout pas oublier `--` sans quoi l'option `--emit` ne sera pas reconnue. Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs $ MIR_PATH="$PWD/target/debug/deps" $ ls $MIR_PATH liblmyproject-67ac3e08dd1b65f4.rlib lmyproject-67ac3e08dd1b65f4.mir |
Note: Ici vous pouvez remarquer qu'il y a un 'l' devant myproject alors que le nom de la crate n'en possède pas, dans votre fichier Cargo.toml. C'est tout simplement parce que, dans ma copie de locale, j'ai à la fois un fichier lib.rs et main.rs, ce qui permet de lever l'ambiguïté à la compilation (i.e. si l'on souhaite compiler le cœur du projet ou un exécutable). Voici mon manifeste Cargo.toml:
Code Toml : | Sélectionner tout |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | [package] name = "myproject" version = "0.1.0" authors = ["Anthony Defranceschi <chaacygg@gmail.com>"] [dependencies] [lib] name = "lmyproject" # <- Vous voyez ici que nous renseignons un nom différent au projet lorsqu'il est compilé en mode bibliothèque. path = "src/lib.rs" test = true doctest = true bench = true doc = true plugin = false proc-macro = false harness = true [[bin]] name = "myproject" path = "src/main.rs" |
Quid si vous souhaitez uniquement visualiser la génération de la MIR de l'exécutable dans ce cas ? La procédure est différente -mais de peu- puisqu'il faut remplacer l'option --lib par --bin nom_de_votre_crate comme vous le fera gentiment remarquer le compilateur si vous omettez l'un d'entre-eux:
Code : | Sélectionner tout |
1 2 | error: extra arguments to `rustc` can only be passed to one target, consider filtering the package by passing e.g. `--lib` or `--bin NAME` to specify a single target |
Code Bash : | Sélectionner tout |
1 2 3 4 5 6 | $ cargo clean && cargo rustc --bin myproject -- --emit mir Compiling myproject v0.1.0 (file:///home/foo/bar/MyProject) Finished dev [unoptimized + debuginfo] target(s) in 1.1 secs $ ls $MIR_PATH liblmyproject-0ca57a22ba238c7c.rlib myproject-c461eb7ac40f5cd7.mir myproject-c461eb7ac40f5cd7 |
L'exécutable et son code MIR ont été générés, il ne vous reste plus qu'à visualiser le résultat avec votre éditeur de texte favoris !
Proposer une nouvelle réponse sur la FAQ
Ce n'est pas l'endroit pour poser des questions, allez plutôt sur le forum de la rubrique pour çaLes sources présentées sur cette page sont libres de droits et vous pouvez les utiliser à votre convenance. Par contre, la page de présentation constitue une œuvre intellectuelle protégée par les droits d'auteur. Copyright © 2024 Developpez Developpez LLC. Tous droits réservés Developpez LLC. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents et images sans l'autorisation expresse de Developpez LLC. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.