🚧 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.

Débogage du WebAssembly généré par Rust

Cette section présente des conseils pour le débogage du WebAssembly généré par Rust.

Compiler avec des symboles de débogage

⚡ Lorsque déboguez, assurez-vous que vous compilez avec les symboles de débogage !

Si n'activez pas les symboles de débogage, la section personnalisée "name" ne sera pas présente dans le binaire compilé en .wasm, et les traces de pile auront des noms de fonctions comme wasm-function[42] plutôt que le nom de la fonction en Rust, comme wasm_jeu_de_la_vie::Univers::compter_voisines_vivantes.

Les symboles de débogage sont activés par défaut lorsqu'un utilise une compilation en mode "debug" (comme wasm-pack build --debug ou cargo build).

Avec une compilation en mode "release", les symboles de débogage ne sont pas activés par défaut. Pour activer les symboles de débogage, assurez-vous que debug = true soit bien présent dans la section [profile.release] de votre Cargo.toml :

[profile.release]
debug = true

Journaliser avec les API de console

La journalisation est un des outils les plus efficients que nous avons à notre disposition pour prouver et réfuter des hypothèses sur le comportement déficient de nos programmes. Sur le Web, la fonction console.log est une manière de journaliser les messages dans la console d'outils de développement du navigateur.

Nous pouvons utiliser la crate web-sys pour accéder aux fonctions de journalisation de console :

#![allow(unused)]
fn main() {
extern crate web_sys; // (faculatif en Rust 2018)

web_sys::console::log_1(&"Hello, world!".into());
}

Sachez aussi que la fonction console.error a la même signature que console.log, mais les outils de développement ont tendance à aussi récupérer et afficher les traces de pile à côté du message de journal lorsqu'on utilise console.error.

Documentations sur console

• Utiliser console.log avec la crate web-sys :
  • web_sys::console::log prend en argument un tableau de valeurs à journaliser
  • web_sys::console::log_1 journalise une seule valeur
  • web_sys::console::log_2 journalise deux valeurs
  • Etc ...
• Utiliser console.error avec la crate web-sys :
  • web_sys::console::error prend en argument un tableau de valeurs à journaliser
  • web_sys::console::error_1 journalise une seule valeur
  • web_sys::console::error_2 journalise deux valeurs
  • Etc ...
• L'objet console sur MDN
• Outils de Développement Firefox — Console Web
• Outils de Développement de Microsoft Edge — Console
• Débuter avec la Console de Chrome DevTools

Journaliser les paniques

La crate console_error_panic_hook journalise les paniques involontaires dans la console avec console.error. Plutôt que d'avoir des messages d'erreur abstraits, difficiles à déboguer comme le RuntimeError: unreachable executed, il vous fournit à la place un message de panique formaté par Rust.

Tout ce que vous avez besoin de faire est d'installer ce système en faisant appel à console_error_panic_hook::set_once() dans une fonction d'initialisation ou dans un code standard qui s'exécutera :

#![allow(unused)]
fn main() {
#[wasm_bindgen]
pub fn installer_systeme_journalisation_panique() {
    console_error_panic_hook::set_once();
}
}

Utiliser un débogueur

Malheureusement, le débogage pour le WebAssembly reste embryonnaire. Dans la plupart des systèmes Unix, DWARF est utilisé pour encoder les informations qu'un débogueur a besoin d'avoir pour procéder à l'inspection de la source d'un programme en cours d'exécution. Il existe aussi un format alternatif qui encode des informations similaires sous Windows. Pour l'instant, il n'y a pas d'équivalent pour WebAssembly. C'est pourquoi les débogueurs sont des outils limités pour le moment, et nous finissons par passer par des instructions WebAssembly brutes émises par le compilateur, plutôt que par le code source Rust que nous avons rédigé.

Il existe une sous-commission du groupe W3C dédiée au débogage, donc attendez-vous à ce que les choses s'améliorent à l'avenir !

Toutefois, les débogueurs restent utiles pour inspecter le JavaScript qui interagit avec notre WebAssembly, et inspecter l'état brut du wasm.

Documentations sur le débogueur

• Outils de Développement de Firefox — Débogueur
• Outils de Développement de Microsoft Edge — Débogueur
• Débuter dans le Débogage du JavaScript dans Chrome DevTools

Eviter d'avoir besoin de déboguer le WebAssembly dans un premier temps

Si le bogue concerne des interactions avec le JavaScript ou des API Web, alors écrivez des tests avec wasm-bindgen-test.

Si le bogue n'implique pas d'interactions avec JavaScript ou des API Web, alors essayez de le reproduire dans une fonction #[test] Rust traditionnelle, dans laquelle vous pouvez profiter des outils natifs de votre système d'exploitation lorsque vous déboguez. Utilisez des crates pour les tests comme quickcheck et ses cas de test qui réduisent automatiquement les cas à tester. Finalement, il vous sera plus facile de trouver et de corriger des bogues si vous pouvez les isoler dans des cas de test plus petits et qui ne nécessitent pas d'interaction avec le JavaScript.

Notez toutefois que pour pouvoir exécuter des #[test] natifs sans erreurs de compilateur et de liaison, vous aurez besoin de vous assurer que "rlib" soit bien présent dans le tableau [lib.crate-type] dans votre fichier Cargo.toml.

[lib]
crate-type = ["cdylib", "rlib"]