🚧 Attention, peinture fraîche !

Cette page a été traduite par une seule personne et n'a pas été relue et vérifiée par quelqu'un d'autre ! Les informations peuvent par exemple être erronées, être formulées maladroitement, ou contenir d'autres types de fautes.

Hello, World !

Cette section va vous expliquer comment compiler et exécuter votre premier programme en Rust et WebAssembly : une page web qui affiche une boite de dialogue "Hello, World !".

Assurez-vous que vous avez suivi les réglages avant de commencer.

Cloner le modèle de projet

Le modèle de projet est livré avec des réglages préconfigurés par défaut avec des valeurs stables, afin que vous puissiez compiler, intégrer et créer un paquet pour le Web.

Vous pouvez cloner le modèle du projet avec cette commande :

cargo generate --git https://github.com/Jimskapt/wasm-pack-template-fr

(la version anglaise originale du modèle est aussi disponible à l'adresse https://github.com/rustwasm/wasm-pack-template)

Elle devrait vous demander le nom du nouveau projet. Nous allons y renseigner "wasm-jeu-de-la-vie".

wasm-jeu-de-la-vie

Qu'est-ce qui est livré ?

Entrez dans le dossier wasm-jeu-de-la-vie du nouveau projet ...

cd wasm-jeu-de-la-vie

... et regardez son contenu :

wasm-jeu-de-la-vie/
├── Cargo.toml
├── LICENSE_APACHE
├── LICENSE_MIT
├── README.md
└── src
    ├── lib.rs
    └── utils.rs

Maintenant, analysons en détail le contenu de certains de ces fichiers.

wasm-jeu-de-la-vie/Cargo.toml

Le fichier Cargo.toml renseigne les dépendances et les métadonnées pour cargo, le gestionnaire de paquets et outil de compilation de Rust. Ce fichier est préconfiguré avec une dépendance à wasm-bindgen, quelques dépendances optionnelles que nous verrons plus tard, ainsi que la propriété crate-type bien réglé pour générer des bibliothèques en .wasm.

wasm-jeu-de-la-vie/src/lib.rs

Le fichier src/lib.rs est la racine de la crate Rust que nous compilerons en WebAssembly. Il utilise wasm-bindgen pour s'interfacer avec JavaScript. Il importe la fonction JavaScript window.alert, et exporte la fonction Rust saluer, qui affiche un message de salutation.


#![allow(unused)]
fn main() {
mod utils;

use wasm_bindgen::prelude::*;

// Lorsque la fonctionnalité `wee_alloc` est activée, nous allons utiliser
// `wee_alloc` en tant qu'allocateur global.
#[cfg(feature = "wee_alloc")]
#[global_allocator]
static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT;

#[wasm_bindgen]
extern {
    fn alert(s: &str);
}

#[wasm_bindgen]
pub fn saluer() {
    alert("Salut, wasm-jeu-de-la-vie !");
}
}

wasm-jeu-de-la-vie/src/utils.rs

Le module src/utils.rs fournit quelques outils communs pour faciliter la compilation de Rust en WebAssembly. Nous nous discuterons en détails de ces outils plus tard dans le tutoriel, en particulier lorsque nous demanderons comment déboguer notre code wasm, mais pour l'instant nous pouvons nous contenter d'ignorer ce fichier.

Compiler le projet

Nous allons utiliser wasm-pack pour orchestrer les étapes de compilation suivantes :

  • S'assurer que nous avons Rust 1.30 ou plus rĂ©cent et la cible wasm32-unknown-unknown via rustup,
  • Compiler nos sources Rust en binaires WebAssembly .wasm via cargo,
  • Utiliser wasm-bindgen pour gĂ©nĂ©rer l'API JavaScript pour utiliser notre WebAssembly gĂ©nĂ©rĂ© par Rust.

Pour faire tout cela, lancez cette commande dans le dossier du projet :

wasm-pack build

Lorsque la compilation sera achevée, nous pourrons trouver ses artefacts dans le dossier pkg, et il devrait avoir ce contenu :

pkg/
├── package.json
├── README.md
├── wasm_jeu_de_la_vie_bg.wasm
├── wasm_jeu_de_la_vie.d.ts
└── wasm_jeu_de_la_vie.js

Le fichier README.md est copié à partir de la racine du projet, mais les autres sont complètement nouveaux.

wasm-jeu-de-la-vie/pkg/wasm_jeu_de_la_vie_bg.wasm

Le fichier .wasm est le binaire WebAssembly qui est généré par le compilateur Rust à partir de nos sources Rust. Il contient les formes compilées en wasm de toutes nos fonctions et nos données. Par exemple, il a une fonction exportée saluer.

wasm-jeu-de-la-vie/pkg/wasm-jeu-de-la-vie.js

Le fichier .js est généré par wasm-bindgen et contient la glu en JavaScript pour importer le DOM et les fonctions JavaScript dans Rust et exposer une API conviviale aux fonctions en WebAssembly à destination du JavaScript. Par exemple, il existe une fonction JavaScript saluer qui englobe la fonction saluer exportée du module en WebAssembly. Pour le moment, cette glu ne fait pas grand-chose, mais lorsque nous commencerons à y envoyer des valeurs plus intéressantes qui vont et viennent entre wasm et JavaScript, cela facilitera le passage de l'un à l'autre côté.

import * as wasm from './wasm_jeu_de_la_vie_bg';

// ...

export function saluer() {
    return wasm.saluer();
}

wasm-jeu-de-la-vie/pkg/wasm_jeu_de_la_vie.d.ts

Le fichier .d.ts contient des déclarations de type TypeScript pour la glu JavaScript. Si vous utilisez TypeScript, vous pourrez faire en sorte que les appels aux fonctions en WebAssembly vérifient les types, et votre IDE pourra vous proposer de l'autocompletion et des suggestions ! Si vous n'utilisez pas le TypeScript, vous pouvez ignorer ce fichier sans problème.

export function saluer(): void;

wasm-jeu-de-la-vie/pkg/package.json

Le fichier package.json contient des métadonnées sur le paquet généré en JavaScript et en WebAssembly. Il est utilisé par npm et les packageurs JavaScript pour décrire les dépendances entre les paquets, les noms de ces paquets, leurs versions, et un tas d'autres choses. Il nous aide à nous intégrer avec les outils JavaScript et nous permet de publier notre paquet sur npm.

{
  "name": "wasm-jeu-de-la-vie",
  "collaborators": [
    "Votre nom <votre.email@exemple.com>"
  ],
  "description": null,
  "version": "0.1.0",
  "license": null,
  "repository": null,
  "files": [
    "wasm_jeu_de_la_vie_bg.wasm",
    "wasm_jeu_de_la_vie.d.ts"
  ],
  "main": "wasm_jeu_de_la_vie.js",
  "types": "wasm_jeu_de_la_vie.d.ts"
}

Tout intégrer dans une page web

Pour intégrer notre paquet wasm-jeu-de-la-vie dans une page Web et l'utiliser, nous avons avoir recours au modèle de projet JavaScript create-wasm-app-fr.

Lancez ensuite la commande suivante dans le dossier wasm-jeu-de-la-vie :

npm init wasm-app-fr www

ou, pour sa version anglaise :

npm init wasm-app www

Maintenant, notre nouveau sous-dossier wasm-jeu-de-la-vie/www contient :

wasm-jeu-de-la-vie/www/
├── bootstrap.js
├── index.html
├── index.js
├── LICENSE-APACHE
├── LICENSE-MIT
├── package.json
├── README.md
└── webpack.config.js

A nouveau, regardons certains de ces fichiers.

wasm-jeu-de-la-vie/www/package.json

Ce package.json est préconfiguré avec les dépendances webpack et webpack-dev-server, ainsi qu'une dépendance à salut-wasm-pack, qui est une version du paquet initial wasm-pack-template qui a été publié sur npm.

wasm-jeu-de-la-vie/www/webpack.config.js

Ce fichier configure webpack et son serveur de développement local. Il est préconfiguré pour que vous n'ayez pas à y toucher pour que webpack et son serveur de développement local fonctionnent correctement.

wasm-jeu-de-la-vie/www/index.html

C'est le fichier HTML racine de notre page Web. Elle ne fait pas grand-chose d'autre que de charger bootstrap.js, qui est une petite enveloppe autour de index.js.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Salut, wasm-pack !</title>
  </head>
  <body>
    <noscript>Cette page utilise du webassembly et du javascript, veuillez activer le javascript dans votre navigateur.</noscript>
    <script src="./bootstrap.js"></script>
  </body>
</html>

wasm-jeu-de-la-vie/www/index.js

Le fichier index.js est le point d'entrée central du JavaScript de notre page Web. Il importe le paquet npm salut-wasm-pack, qui contient la glu WebAssembly et JavaScript précompilée de wasm-pack-template, et qui ensuite appelle la fonction saluer de salut-wasm-pack.

import * as wasm from "salut-wasm-pack";

wasm.saluer();

Installer les dépendances

D'abord, il va falloir s'assurer que le serveur de développement local et ses dépendances sont installées en lançant npm install dans le sous-dossier wasm-jeu-de-la-vie/www :

npm install

Cette commande n'a besoin d'être exécutée une seule fois, et va installer le packageur JavaScript webpack et son serveur de développement.

Notez que webpack n'est pas nécessaire pour travailler Rust et WebAssembly, c'est juste le packageur et le serveur de développement que nous avons choisi par confort ici. Parcel et Rollup devraient aussi implémenter l'import de WebAssembly en tant que module ECMAScript. Vous pouvez aussi utiliser Rust et WebAssembly sans packageur si vous le préférez !

Utiliser notre paquet local wasm-jeu-de-la-vie dans www

Plutôt que d'utiliser le paquet hello-wasm-pack provenant de npm, nous voulons utiliser notre paquet local wasm-jeu-de-la-vie. Cela va nous permettre de développer de manière incrémentale notre programme de "Jeu de la vie".

Ouvrez wasm-jeu-de-la-vie/www/package.json et à côté de "devDependencies", ajoutez le champ "dependencies", et ajoutez-lui l'entrée "wasm-jeu-de-la-vie": "file:../pkg" :

{
  // ...
  "dependencies": {                     // Ajoutez ce bloc de trois lignes !
    "wasm-jeu-de-la-vie": "file:../pkg"
  },
  "devDependencies": {
    //...
  }
}

Ensuite, modifiez wasm-jeu-de-la-vie/www/index.js pour importer wasm-jeu-de-la-vie à la place du paquet salut-wasm-pack :

import * as wasm from "wasm-jeu-de-la-vie";

wasm.saluer();

Comme nous avons déclaré une nouvelle dépendance, nous devons l'installer :

npm install

Notre page web est maintenant prête à être servie localement !

Servir localement

Maintenant, ouvrez un nouveau terminal pour le serveur de développement. Exécuter le serveur dans un nouveau terminal nous permet de l'exécuter en arrière-plan, et ainsi ne nous empêche pas de lancer d'autres commandes en même temps. Dans le nouveau terminal, lancez cette commande dans le dossier wasm-jeu-de-la-vie/www :

npm run start

Rendez-vous à l'adresse http://localhost:8080/ avec votre navigateur web et vous devriez être accueilli par un message d'avertissement :

Capture d'écran de l'alerte "Salut, wasm-jeu-de-la-vie !" sur la page web

A chaque fois que vous allez faire des changements dans le code Rust et que vous souhaitez les intégrer dans http://localhost:8080/, relancez simplement la commande wasm-pack build dans le dossier wasm-jeu-de-la-vie.

Exercice

  • Essayez de modifier la fonction saluer dans wasm-jeu-de-la-vie/src/lib.rs pour prendre en paramètre un nom: &str qui personnalise le message d'alerte, et passez votre nom Ă  la fonction saluer Ă  l'intĂ©rieur de wasm-jeu-de-la-vie/www/index.js. Recompilez le binaire .wasm avec wasm-pack build, et ensuite rafraĂ®chissez http://localhost:8080/ dans votre navigateur web, et vous devrez voir une salutation personnalisĂ©e !
RĂ©ponse

Nouvelle version de la fonction saluer dans wasm-jeu-de-la-vie/src/lib.rs:


#![allow(unused)]
fn main() {
#[wasm_bindgen]
pub fn saluer(nom: &str) {
    alert(&format!("Salut, {} !", nom));
}
}

Nouvelle utilisation de saluer dans wasm-jeu-de-la-vie/www/index.js:

wasm.saluer("votre nom");