diff options
Diffstat (limited to 'files/fr/webassembly')
| -rw-r--r-- | files/fr/webassembly/c_to_wasm/index.html | 187 | ||||
| -rw-r--r-- | files/fr/webassembly/concepts/index.html | 135 | ||||
| -rw-r--r-- | files/fr/webassembly/exported_functions/index.html | 69 | ||||
| -rw-r--r-- | files/fr/webassembly/index.html | 163 | ||||
| -rw-r--r-- | files/fr/webassembly/loading_and_running/index.html | 108 | ||||
| -rw-r--r-- | files/fr/webassembly/understanding_the_text_format/index.html | 865 | ||||
| -rw-r--r-- | files/fr/webassembly/using_the_javascript_api/index.html | 292 |
7 files changed, 1819 insertions, 0 deletions
diff --git a/files/fr/webassembly/c_to_wasm/index.html b/files/fr/webassembly/c_to_wasm/index.html new file mode 100644 index 0000000000..9c3ce1ea61 --- /dev/null +++ b/files/fr/webassembly/c_to_wasm/index.html @@ -0,0 +1,187 @@ +--- +title: Compiler un nouveau module C/C++ en WebAssembly +slug: WebAssembly/C_to_wasm +tags: + - C + - C++ + - Compilation + - Emscripten + - WebAssembly + - wasm +translation_of: WebAssembly/C_to_wasm +--- +<div>{{WebAssemblySidebar}}</div> + +<p class="summary">Quand vous avez écrit un module de code dans un langage comme le C/C++, vous pouvez ensuite le compiler en WebAssembly en utilisant un outil comme <a href="/en-US/docs/Mozilla/Projects/Emscripten">Emscripten</a>. Regardons comment cela fonctionne.</p> + +<h2 id="Mise_en_place_de_lenvironnement_Emscripten">Mise en place de l'environnement Emscripten</h2> + +<p>D'abord, mettons en place l'environnement requis pour le développement.</p> + +<h3 id="Prérequis">Prérequis</h3> + +<p>Recuperer le SDK de Emscripten en utilisant les instructions suivantes: <a href="https://kripken.github.io/emscripten-site/docs/getting_started/downloads.html">https://kripken.github.io/emscripten-site/docs/getting_started/downloads.html</a></p> + +<h2 id="Compiler_un_exemple">Compiler un exemple</h2> + +<p>Une fois l'environnement mis en place, regardons comment l'utiliser pour compiler un exemple en C via Emscripten. Il existe un certain nombre d'options disponibles quand on compile avec Emscripten, mais nous allons couvrir seulement les deux principaux scénarios:</p> + +<ul> + <li>Compiler vers du wasm et créer du HTML pour exécuter notre code plus toute la "glue" Javascript nécessaire à l'exécution du wasm dans l'environnement Web.</li> + <li>Compiler vers du wasm et juste créer le Javascript.</li> +</ul> + +<p>Nous verrons les deux par la suite.</p> + +<h3 id="Créer_le_document_HTML_et_la_glue_JavaScript">Créer le document HTML et la "glue" JavaScript</h3> + +<p>C'est le cas le plus simple que nous allons voir, pour lequel vous utiliserez Emscripten pour générer tout ce dont vous avez besoin pour exécuter votre code en WebAssembly dans le navigateur. </p> + +<ol> + <li>D'abord nous avons besoin d'un exemple à compiler. Prenez une copie du simple programme C suivant et sauvez-le dans un fichier nommé <code>hello.c</code> dans un nouveau répertoire de votre disque dur: + + <pre class="brush: cpp">#include <stdio.h> + +int main(int argc, char ** argv) { + printf("Hello World\n"); +}</pre> + </li> + <li>Maintenant, en utilisant la fenêtre terminal qui vous a servi pour entrer dans l'environnement du compilateur Emscripten, naviguez jusqu'au répertoire dans lequel se trouve votre fichier <code>hello.c</code> et exécutez la commande suivante : + <pre class="brush: bash">emcc hello.c -s WASM=1 -o hello.html</pre> + </li> +</ol> + +<p>Les options passées avec la commande sont les suivantes :</p> + +<ul> + <li><code>-s WASM=1</code> — Spécifie que nous voulons du wasm en sortie. Si nous ne spécifions pas cela, Emscripten générera juste en sortie du <a href="http://asmjs.org/">asm.js</a> comme il le fait par défaut.</li> + <li><code>-o hello.html</code> — Spécifie que nous voulons qu'Emscripten génère une page HTML (dont le nom de fichier est spécifié), le module wasm et le code "glue" en JavaScript pour une execution dans un contexte web.</li> +</ul> + +<p>À ce stade votre dossier source devrait contenir :</p> + +<ul> + <li>Un fichier de code binaire wasm (<code>hello.wasm</code>)</li> + <li>Un fichier JavaScript contenant du code "glue" à traduire entre les fonctions natives C, et Java/wasm (<code>hello.js</code>)</li> + <li>Un fichier HTML pour charger, compiler et instancier votre code wasm, et l'afficher dans votre navigateur (<code>hello.html</code>)</li> +</ul> + +<h3 id="Exécuter_votre_exemple">Exécuter votre exemple</h3> + +<p>Maintenant, tout ce qui vous reste à faire est de charger le fichier <code>hello.html</code> dans un navigateur qui supporte WebAssembly. Il est activé par défaut dans Firefox 52+, Chrome 57+ et dans la derniere version d'Opera (vous pouvez aussi executer du code wasm dans Firefox 47+ en activant le flag <code>javascript.options.wasm</code> dans <em>about:config</em>, ou dans Chrome (51+) et Opera (38+) en allant dans <em>chrome://flags</em> and en activant le flag <em>Experimental WebAssembly</em>.)</p> + +<p>Si tout a fonctionné comme prévu, vous devriez voir la sortie "Hello World" dans la console Emscripten apparaissant dans la page web et dans la console Javascript de votre navigateur. Bravo, vous venez de compiler un programme C en WebAssembly puis d'executer ce programme dans votre navigateur! </p> + +<h3 id="Utiliser_un_template_HTML_personnalisé">Utiliser un template HTML personnalisé</h3> + +<p>Vous souhaiterez parfois utiliser un template HTML personnalisé. Voyons comment faire :</p> + +<ol> + <li> + <p>Tout d'abord, sauvegarder le code C suivant dans un fichier nommé <code>hello2.c</code>, au sein d'un nouveau dossier (vide) :</p> + + <pre class="brush: cpp">#include <stdio.h> + +int main(int argc, char ** argv) { + printf("Hello World\n"); + +}</pre> + </li> + <li> + <p>Cherchez le fichier <code>shell_minimal.html</code> dans le dépôt emsdk. Copiez-le dans un sous-dossier nommé <code>html_template</code> dans votre précédent nouveau dossier.</p> + </li> + <li> + <p>Naviguez maintenant jusqu'au nouveau dossier (toujours dans votre terminal disposant de l'environnement Emscripten), et exécutez la commande suivante :</p> + + <pre class="brush: bash">emcc -o hello2.html hello2.c -O3 -s WASM=1 --shell-file html_template/shell_minimal.html</pre> + + <p>Les options que nous avons donné sont un peu différentes cette fois :</p> + + <ul> + <li>Nous avons spécifié <code>-o hello2.html</code>, ce qui signifie que le compilateur va générer du code JavaScript "glue" ainsi qu'un <code>.html</code>.</li> + <li>Nous avons également spécifié <code>--shell-file html_template/shell_minimal.html</code> — cela fournit le chemin vers le template HTML que vous souhaitez utiliser pour créer le HTML qui vous permettra d'exécuter l'exemple.</li> + </ul> + </li> + <li> + <p>Maintenant, lançons l'exemple. La commande ci-dessus aura généré hello2.html, qui aura à peu près le même contenu que le template avec un peu de code "glue" pour charger le code wasm généré, l'exéuter, etc. Ouvrez-le dans votre navigateur et vous verrez quasiment la même chose qu'avec notre dernier exemple.</p> + </li> +</ol> + +<div class="note"> +<p><strong>Note</strong>: Vous pouvez spécifier, comme sortie, juste le fichier* JavaScript "glue" au lieu de la sortie HTML en specifiant un fichier .js au lieu d'un fichier HTML dans le flag<code>-o</code> . Par exemple: <code>emcc -o hello2.js hello2.c -O3 -s WASM=1</code>. Vous pouevz ensuite votre propre fichier HTML à partir de rien bien que ce soit une approche plus compliquée. Il est généralement plus simple d'utiliser le template HTML fournit.</p> + +<p>* Emscripten necessite une grande variété de code Javascript "glue" pour gérer les allocations memoire, les fuites memoires et bien d'autres problèmes.</p> +</div> + +<h3 id="Appeler_une_fonction_personnalisée_définie_en_C">Appeler une fonction personnalisée définie en C</h3> + +<p>Si vous avez une fonction définie dans votre code C et que vous souhaitez l'appeler de Javascript, vous pouvez le faire en utilisant la fonction Emscripten <code>ccall()</code> et la déclaration <code>EMSCRIPTEN_KEEPALIVE</code> (qui ajoute vos fonctions dans la liste des fonctions exportées) . Voir <a href="https://kripken.github.io/emscripten-site/docs/getting_started/FAQ.html#why-do-functions-in-my-c-c-source-code-vanish-when-i-compile-to-javascript-and-or-i-get-no-functions-to-process">Why do functions in my C/C++ source code vanish when I compile to JavaScript, and/or I get No functions to process?</a>. Regardons comment cela fonctionne.</p> + +<ol> + <li> + <p>Pour démarrer, sauvegardez le code suivante dans un fichier nommé <code>hello3.c</code> dans un nouveau répertoire:</p> + + <pre class="brush: cpp">#include <stdio.h> +#include <emscripten/emscripten.h> + +int main(int argc, char ** argv) { + printf("Hello World\n"); +} + +#ifdef __cplusplus +extern "C" { +#endif + +void EMSCRIPTEN_KEEPALIVE myFunction(int argc, char ** argv) { + printf("MyFunction Called\n"); +} + +#ifdef __cplusplus +} +#endif</pre> + + <p>By default, Emscripten-generated code always just calls the <code>main()</code> function, and other functions are eliminated as dead code. Putting <code>EMSCRIPTEN_KEEPALIVE</code> before a function name stops this from happening. You also need to import the <code>emscripten.h</code> library to use <code>EMSCRIPTEN_KEEPALIVE</code>.</p> + + <div class="note"> + <p><strong>Note</strong>: We are including the <code>#ifdef</code> blocks so that if you are trying to include this in C++ code, the example will still work. Due to C versus C++ name mangling rules, this would otherwise break, but here we are setting it so that it treats it as an external C function if you are using C++.</p> + </div> + </li> + <li> + <p>Now add <code>html_template/shell_minimal.html</code> into this new directory too, just for convenience (you'd obviously put this in a central place in your real dev environment).</p> + </li> + <li> + <p>Now let's run the compilation step again. From inside your latest directory (and while inside your Emscripten compiler environment terminal window), compile your C code with the following command. (Note that we need to compile with NO_EXIT_RUNTIME, which is necessary as otherwise when main() exits the runtime would be shut down - necessary for proper C emulation, e.g., atexits are called - and it wouldn't be valid to call compiled code.)</p> + + <pre class="brush: bash">emcc -o hello3.html hello3.c -O3 -s WASM=1 --shell-file html_template/shell_minimal.html -s NO_EXIT_RUNTIME=1 -s EXTRA_EXPORTED_RUNTIME_METHODS='["ccall"]'</pre> + </li> + <li> + <p>If you load the example in your browser again, you'll see the same thing as before!</p> + </li> + <li> + <p>Now we need to run our new <code>myFunction()</code> function from JavaScript. First of all, let's add a {{htmlelement("button")}} as shown below, just above the first opening <code><script type='text/javascript'></code> tag.</p> + + <pre class="brush: html"><button class="mybutton">Run myFunction</button></pre> + </li> + <li> + <p>Now add the following code inside the last {{htmlelement("script")}} element (just above the closing <code></script></code> tag):</p> + + <pre class="brush: js">document.querySelector('.mybutton').addEventListener('click', function(){ + alert('check console'); + var result = Module.ccall('myFunction', // name of C function + null, // return type + null, // argument types + null); // arguments +});</pre> + </li> +</ol> + +<p>This illustrates how <code>ccall()</code> is used to call the exported function.</p> + +<h2 id="Voir_aussi">Voir aussi</h2> + +<ul> + <li><a href="http://emscripten.org/">emscripten.org</a> — pour en apprendre plus sur Emscripten et sa large palette d'options</li> + <li><a href="https://kripken.github.io/emscripten-site/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.html#calling-compiled-c-functions-from-javascript-using-ccall-cwrap">Appeler des fonctions C compilées depuis JavaScript grâce à ccall/cwrap</a></li> + <li><a href="https://kripken.github.io/emscripten-site/docs/getting_started/FAQ.html#why-do-functions-in-my-c-c-source-code-vanish-when-i-compile-to-javascript-and-or-i-get-no-functions-to-process">Pourquoi les fonctions dans mon code source C/C++ disparaissent quand je le compile dans JavaScript, et/ou je reçois une erreur "No functions to process" ?</a></li> + <li><a href="https://research.mozilla.org/webassembly/">WebAssembly sur Mozilla Research</a></li> +</ul> diff --git a/files/fr/webassembly/concepts/index.html b/files/fr/webassembly/concepts/index.html new file mode 100644 index 0000000000..a92cfd0fec --- /dev/null +++ b/files/fr/webassembly/concepts/index.html @@ -0,0 +1,135 @@ +--- +title: Concepts de WebAssembly +slug: WebAssembly/Concepts +translation_of: WebAssembly/Concepts +--- +<div>{{WebAssemblySidebar}}</div> + +<p class="summary">Cet article explique les concepts de fonctionnement de WebAssembly, y compris ses objectifs, les problèmes qu'il résout et la manière dont il s'exécute dans le moteur de rendu du navigateur.</p> + +<h2 id="Quest-ce_que_WebAssembly">Qu'est-ce que WebAssembly ?</h2> + +<p>WebAssembly est un nouveau type de code pouvant être exécuté dans les navigateurs modernes et fournissant de nouvelles fonctionnalités ainsi que des gains majeurs en performance. Il n'est pas particulièrement destiné à être écrit à la main, mais il est plutôt conçu pour être une cible de compilation efficace pour les langages source de bas niveau tels C, C ++, Rust, etc.</p> + +<p>Cela a d'énormes implications pour la plate-forme web — il fournit un moyen d'exécuter un code écrit dans divers langages sur le web à une vitesse proche du natif, avec des applications clientes exécutées sur le web qui auparavant n'auraient pas pu être réalisées.</p> + +<p>De plus, vous ne devez même pas savoir comment créer du code WebAssembly pour en profiter. Les modules WebAssembly peuvent être importés dans une application web (ou Node.js) en exposant les fonctions WebAssembly à utiliser via JavaScript. Les frameworks JavaScript pourraient utiliser WebAssembly pour conférer des avantages massifs de performance et de nouvelles fonctionnalités tout en rendant la fonctionnalité facilement accessible aux développeurs web.</p> + +<h2 id="Objectifs_de_WebAssembly">Objectifs de WebAssembly</h2> + +<p>WebAssembly est en cours de création en tant que standard ouvert au sein du <a href="https://www.w3.org/community/webassembly/">W3C WebAssembly Community Group</a> avec les objectif suivants :</p> + +<ul> + <li>Être rapide, efficace et portable — Le code WebAssembly peut être exécuté à une vitesse proche du natif sur plusieurs plateformes en profitant des <a href="http://webassembly.org/docs/portability/#assumptions-for-efficient-execution">capacités matérielles communes</a>.</li> + <li>Être lisible et débuggable — WebAssembly est un langage d'assemblage de bas niveau, mais son format de texte est lisible par l'homme (la spécification pour laquelle il est encore en cours de finalisation) et permet au code d'être écrit, lu et débuggé à la main.</li> + <li>Conserver la sécurité — WebAssembly est conçu pour être exécuté dans un environnement sûr, en sandbox. Comme d'autres codes web, il imposera les règles de même origine du navigateur, ainsi que ses politiques d'autorisations.</li> + <li>Ne pas casser le web — WebAssembly est conçu de manière à facilement s'associer aux autres technologies web et à maintenir une rétrocompatibilité.</li> +</ul> + +<div class="note"> +<p><strong>Note </strong>: WebAssembly aura également des usages en dehors du web et des environnements JavaScript (voir <a href="http://webassembly.org/docs/non-web/">Non-web embeddings</a>).</p> +</div> + +<h2 id="Comment_WebAssembly_sintègre_dans_la_plateforme_web">Comment WebAssembly s'intègre dans la plateforme web ?</h2> + +<p>La plateforme web peut s'imaginer comme composée de deux parties :</p> + +<ul> + <li>Une machine virtuelle (VM) qui exécute le code de la Web app, e.g le code JavaScript qui fait tourner vos applications.</li> + <li>Une ensemble de <a href="/en-US/docs/Web/API">Web APIs</a> que la Web app peut appeler pour contrôler les fonctionnalités des navigateurs/appareils et réaliser des actions (<a href="/en-US/docs/Web/API/Document_Object_Model">DOM</a>, <a href="/en-US/docs/Web/API/CSS_Object_Model">CSSOM</a>, <a href="/en-US/docs/Web/API/WebGL_API">WebGL</a>, <a href="/en-US/docs/Web/API/IndexedDB_API">IndexedDB</a>, <a href="/en-US/docs/Web/API/Web_Audio_API">Web Audio API</a>, etc.).</li> +</ul> + +<p>Historiquement, la VM était seulement capable de charger le JavaScript. Cela fonctionnait bien pour nous comme le JavaScript est assez puissant pour résoudre la majeure partie des problèmes que les gens rencontrent sur Internet. Nous nous sommes, cependant, confrontés à des problèmes de performances lors de l'utilisation de JavaScript pour des cas d'utilisations plus avancés comme les jeux 3D, la réalité virtuelle et augmentée, la vision artificielle, l'édition d'image/vidéo, et un nombre de domaines qui demandent des performances natives ( voir <a href="http://webassembly.org/docs/use-cases/">Cas d'utilisations WebAssembly</a> pour plus d'informations).</p> + +<p>De plus, le coût du téléchargement, du parsing et de la compilation de très grosses applications JavaScript peut être prohibitif. L'utilisation de mobiles ou d'autres plateformes à puissance réduite accentue d'autant plus l'effet de goulet d'étranglement des performances.</p> + +<p>WebAssembly est un langage différent de JavaScript, mais n'a pas pour but de le remplacer. Il faut plutôt l'envisager comme complément, travaillant "main dans la main" avec JavaScript, permettant ainsi aux développeurs WEB de prendre avantage des points forts de chacun des deux langages :</p> + +<ul> + <li>JavaScript est un langage haut niveau, flexible et suffisamment expressif pour écrire des applications web. Il possède beaucoup d'avantages — il est dynamiquement typé, ne nécessite aucune étape de compilation, et a un écosystème foisonnant qui lui fourni de puissants frameworks, bibliothèques, et autres outils.</li> + <li>WebAssembly est un langage bas niveau, de style assembleur, avec un format binaire compact qui tourne avec des performances proches du natif et fourni au langage une gestion bas niveau de la mémoire tout comme le C++ et Rust comme cible de compilation afin de pouvoir tourner sur le web. (Notez qu'une <a href="http://webassembly.org/docs/high-level-goals/">priorité</a> de WebAssembly est de supporter les langages avec modèles de mémoire à garbage-collector dans le futur.)</li> +</ul> + +<p>Avec l'apparition du WebAssembly dans les navigateurs, la machine virtuelle dont nous parlions précédemment charge et exécute deux type de code - JavaScript ET WebAssembly.</p> + +<p>Les deux différents type de code peuvent s'appeler si nécessaire — l'API WebAssembly JavaScript enveloppe le code exporté avec des fonctions JavaScript qui peuvent être appelées normalement et le code WebAssembly peut importer et appeler normalement de manière synchrone les fonctions JavaScript. En fait, l'unité de base de code WebAssembly est appelée module et est similaire par de nombreux aspects aux modules ES2015.</p> + +<h3 id="Les_concepts_clefs_du_WebAssembly">Les concepts clefs du WebAssembly </h3> + +<p>Il y a différents concepts clefs nécessaires pour comprendre comment fonctionne WebAssembly dans le navigateur. Tous ces concepts se retrouvent totalement dans l'API WebAssembly JavaScript.</p> + +<ul> + <li><strong>Module </strong>: Représente un binaire WebAssembly qui a été compilé en code exécutable par le navigateur. Un module est sans état et - comme un <a href="/en-US/docs/Web/API/Blob">Blob</a> - peut donc être explicitement<a href="/en-US/WebAssembly/Caching_modules"> mis en cache dans IndexedDB</a> ou partagé entre le contexte fenêtre et les workers (via <code><a href="/en-US/docs/Web/API/MessagePort/postMessage">postMessage()</a></code>). Un module déclare des imports et exports au même titre qu'un module ES2015.</li> + <li><strong>Mémoire </strong>: Représente un ArrayBuffer redimensionnable qui contient un tableau d'octets contiguë accessible en lecture/écriture par les instructions bas niveau d'accès mémoire du WebAssembly.</li> + <li><strong>Table</strong> : Représente un tableau typé de référence (comme par exemple des fonctions) qui ne peut pas être stocké de manière brute en mémoire (pour des raisons de sécurité et de portabilité).</li> + <li><strong>Instance </strong>: Représente un module associé avec tous les états qu'il utilise à l'exécution à savoir la mémoire, la table précédemment citée et un ensemble de données importées. Une instance est comme un module ES2015 qui a été chargée dans un contexte global avec un ensemble d'imports.</li> +</ul> + +<p>L'API JavaScript fournit aux développeurs la capacité de créer des modules, de la mémoire, des tables et instances. Pour une instance WebAssembly donnée, le code JavaScript peut appeler - de manière synchrone - ses exports qui sont accessibles comme des fonctions JavaScript normales. De façon arbitraire, toute fonction JavaScript peut aussi être appelée - de manière synchrone - par du code WebAssembly en passant ces fonctions JavaScript comme des imports à une instance WebAssembly.</p> + +<p>Vu que JavaScript a un contrôle total sur la façon de charger, compiler et exécuter du code WebAssembly, les développeurs peuvent voir le WebAssembly comme une fonctionnalité JavaScript pour générer efficacement des fonctions très rapides.</p> + +<p>Dans le futur, les modules WebAssembly seront chargeables comme des module ES2015 (en utilisant <code><script type='module'></code>), ce qui veut dire que JavaScript sera capable de récupérer, compiler et importer un module WebAssembly aussi facilement qu'un module ES2015.</p> + +<h2 id="Comment_utiliser_WebAssembly_dans_son_applicatif">Comment utiliser WebAssembly dans son applicatif ?</h2> + +<p>Précédemment nous parlions des primitives bas niveau que WebAssembly ajoute à la plateforme Web : un format binaire pour le code et une API pour charger et exécuter ce code binaire. Maintenant, parlons de comment utiliser ces primitives en pratique.</p> + +<p>L'écosystème WebAssembly est à un stade embryonnaire ;</p> + +<p>D'autres outils verront sans aucun doute le jour à l'avenir. Pour le moment, il y a trois points d'entrée principaux :</p> + +<ul> + <li>Porter une application C/C++ avec <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Emscripten">Emscripten</a>.</li> + <li>Écrire ou générer WebAssembly directement au niveau assembleur.</li> + <li>Écrire une application Rust et cibler WebAssembly en sortie.</li> +</ul> + +<p>Parlons de ces options :</p> + +<h3 id="Portage_depuis_le_CC">Portage depuis le C/C++</h3> + +<p>L'outil Emscripten est capable de prendre du code source C/C++ et de le compiler dans un module .wasm, de générer le code "glue" JavaScript nécessaire pour charger et exécuter le module et de créer un document HTML capable d'afficher les résultats d'exécution du code.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/14647/emscripten-diagram.png" style="display: block; height: 104px; margin: 0px auto; width: 764px;"></p> + +<p>En résumé, le principe de fonctionnement est le suivant :</p> + +<ol> + <li>D'abord, Emscripten alimente clang+LLVM - une chaîne de compilation open source mature empruntée par exemple à XCode sur OSX - avec le code C/C++.</li> + <li>Emscripten transforme ensuite le résultat compilé par clang+LLVM en binaire .wasm.</li> + <li>Par lui-même WebAssembly ne peut pour l'instant pas accéder directement au DOM ; Il peut seulement appeler JavaScript avec des données de type primitif entier ou flottant. Ainsi, pour accéder à toute API Web, WebAssembly a besoin d'appeler du JavaScript qui ensuite effectuera l'appel à l'API Web. C'est pourquoi Emscripten crée le document HTML et le code "passe-plat" JavaScript nécessaire pour atteindre cet objectif.</li> +</ol> + +<div class="note"> +<p><strong>Note</strong> : Il existe des propositions future pour <a href="http://webassembly.org/docs/gc/"> permettre au WebAssembly d'appeler directement l'API Web</a>.</p> +</div> + +<p>Le code "passe-plat" en JavaScript n'est pas aussi simple que vous pourriez l'imaginer. Pour le moment, Emscripten implémente des librairies C/C++ populaire comme <a href="https://en.wikipedia.org/wiki/Simple_DirectMedia_Layer">SDL</a>, <a href="https://en.wikipedia.org/wiki/OpenGL">OpenGL</a>, <a href="https://en.wikipedia.org/wiki/OpenAL">OpenAL</a>, et une partie de <a href="https://en.wikipedia.org/wiki/POSIX">POSIX</a>. Ces bibliothèques sont implémentées sous forme d'API Web et donc chacune d'entre elles requiert un peu de code JavaScript "passe-plat" pour relier WebAssembly à l'API Web sous-jacente.</p> + +<p>Ainsi le code "passe-plat" implémente les fonctionnalités de chaque librairie utilisée par le C/C++. Le code "passe-plat" contient aussi la logique pour appeler l'API JavaScript WebAssembly pour chercher, charger et exécuter le fichier .wasm.</p> + +<p>Le document HTML généré charge le fichier JavaScript contenant le code "passe-plat" et écrit stdout dans un {{htmlelement("textarea")}}. Si l'application utilise OpenGL, le HTML contient aussi un élément {{htmlelement("canvas")}} qui est utilisé comme cible de rendu. Il est vraiment simple de modifier la sortie Emscripten pour en faire l'application web que vous souhaitez.</p> + +<p>Vous pouvez trouver toute la documentation sur Emscripten à l'adresse <a href="http://emscripten.org">emscripten.org</a>, et un guide pour exploiter la chaîne de compilation et ainsi compiler votre propre application C/C++ en wasm à l'adresse <a href="https://developer.mozilla.org/en-US/docs/WebAssembly/C_to_wasm">Compiler du C/C++ en WebAssembly</a>.</p> + +<h3 id="Écrire_du_WebAssembly_directement">Écrire du WebAssembly directement</h3> + +<p>Voulez vous construire votre propre compilateur ou vos propres outils ou faire une librairie JavaScript qui génère du WebAssembly à la volée ?</p> + +<p>De la même manière que les langages assembleur physiques, le format binaire du WebAssembly a une représentation textuelle. Ces deux formats ont un fonctionnement équivalents. Vous pouvez écrire ou générer ce format à la main et ensuite le convertir au format binaire avec un des nombreux <a href="http://webassembly.org/getting-started/advanced-tools/">outils de conversion texte vers binaire WebAssembly</a>.</p> + +<p>Pour un guide simple sur comment réaliser ceci, regarder notre article <a href="https://developer.mozilla.org/en-US/docs/WebAssembly/Text_format_to_wasm">Convertir le WebAssembly au format text en wasm</a>.</p> + +<h2 id="En_résumé">En résumé</h2> + +<p>Cet article vous a donné une explication sur ce qu'est WebAssembly, pourquoi il est si utile, comment il s'intègre dans le Web et comment vous pouvez l'utiliser.</p> + +<h2 id="Voir_aussi">Voir aussi</h2> + +<ul> + <li><a href="https://hacks.mozilla.org/category/webassembly/">WebAssembly articles on Mozilla Hacks blog</a></li> + <li><a href="https://research.mozilla.org/webassembly/">WebAssembly on Mozilla Research</a></li> + <li><a href="/en-US/docs/WebAssembly/Loading_and_running">Loading and running WebAssembly code</a>— trouvez comment charger votre propre module WebAssembly dans une page web.</li> + <li><a href="/en-US/docs/WebAssembly/Using_the_JavaScript_API">Using the WebAssembly JavaScript API</a> — trouvez comment utiliser les autres fonctionnalités majeures de l'API JavaScript WebAssembly.</li> +</ul> diff --git a/files/fr/webassembly/exported_functions/index.html b/files/fr/webassembly/exported_functions/index.html new file mode 100644 index 0000000000..bac7e74c52 --- /dev/null +++ b/files/fr/webassembly/exported_functions/index.html @@ -0,0 +1,69 @@ +--- +title: Exported WebAssembly functions +slug: WebAssembly/Exported_functions +translation_of: WebAssembly/Exported_functions +--- +<div>{{WebAssemblySidebar}}</div> + +<p class="summary">Les fonctions WebAssembly exportées sont la représentation des fonctions WebAssembly dans JavaScript. Cet article décrit un plus en détail à quoi elle correspondent...</p> + +<h2 id="Exportée..._quoi">Exportée... quoi?</h2> + +<p>Les fonctions WebAssembly exportées sont simplement des emballages (wrappers) Javascript autour de fonction WebAssembly afin de les représenter dans un contexte Javascript. Lorsqu'elles sont appelées, une procédure en arrière plan est engagée afin d'obtenir une conversion des types compatible avec WebAssembly (Par exemple convertir <code>numbers</code> en <code>Int32</code>), les arguments sont transmis à la fonction au sein du module wasm, la fonction est invoquée, et enfin le résultat est à nouveau convertit et retourner à Javascript.</p> + +<p>Vous pouvez exporter les fonctions WebAssembly de deux manières:</p> + +<ul> + <li>Par un appel à <code><a href="/en-US/docs/WebAssembly/API/Table/get">Table.prototype.get()</a></code> sur une table existante.</li> + <li>Par un appel à une fonction exportée à partir de l'instance d'un module wasm via <code><a href="/en-US/docs/WebAssembly/API/Instance/exports">Instance.exports</a></code>.</li> +</ul> + +<p>Dans les deux cas, vous obtenez le même genre de wrapper pour la fonction sous jacente. Du point de vue de JavaScript, une fonction wasm est une fonction JavaScript— A la différence prés qu'elles sont encapsulées par l'instance d'une fonction exportée wasm et qu'il y a un nombre limité de façon d'y accéder.</p> + +<h2 id="Un_exemple">Un exemple</h2> + +<p>Regardons un exemple pour mettre les choses au clair (tu peux le trouver sur GitHub sur <a href="https://github.com/mdn/webassembly-examples/blob/master/other-examples/table-set.html">table-set.html</a>; à voir également en <a href="https://mdn.github.io/webassembly-examples/other-examples/table-set.html">live </a>, et check la <a href="https://github.com/mdn/webassembly-examples/blob/master/js-api-examples/table.wat">representation</a> textuelle wasm):</p> + +<pre class="brush: js">var otherTable = new WebAssembly.Table({ element: "anyfunc", initial: 2 }); + +WebAssembly.instantiateStreaming(fetch('table.wasm')) +.then(obj => { + var tbl = obj.instance.exports.tbl; + console.log(tbl.get(0)()); // 13 + console.log(tbl.get(1)()); // 42 + otherTable.set(0,tbl.get(0)); + otherTable.set(1,tbl.get(1)); + console.log(otherTable.get(0)()); + console.log(otherTable.get(1)()); +});</pre> + +<p>Dans cet exemple, nous créons une table (<code>otherTable</code>) à partir de JavaScript en utilisant le constructeur {{jsxref("WebAssembly.Table")}}, puis nous chargeons table.wasm dans notre page en utilisant la méthode {{jsxref("WebAssembly.instantiateStreaming()")}}.</p> + +<p>Nous pouvons ensuite accéder aux fonctions exportées à partir du module, récupérer les références de chaque fonction via <code><a href="/en-US/docs/WebAssembly/API/Table/get">tbl.get()</a></code> et logguer le résultat de chacune d'elles dans la console. Enfin, nous utilisons <code>set()</code> avec la table <code>otherTable</code> afin de lui fournir les references aux mêmes functions que la table <code>tbl</code>.</p> + +<p>Pour vérifier que cela à fonctionné correctement, nous récupérons les références de la table <code>otherTable</code> et imprimons également les résultats dans la console, et les résultats sont identiques aux précédents.</p> + +<h2 id="Des_fonctions_à_part_entière">Des fonctions à part entière</h2> + +<p>Dans l'exemple précédent, la valeur de retour de chaque appel à <code><a href="/en-US/docs/WebAssembly/API/Table/get">Table.prototype.get()</a></code> est une fonction WebAssembly exportée — exactement ce dont nous avons parlé jusqu'à maintenant.</p> + +<p>Il vaut la peine d'être noté que ceux sont des fonctions JavaScript à part entière, en plus d'être un emballage à des fonctions WebAssembly. Si vous chargez l'exemple ci-dessus dans un navigateur compatible avec WebAssembly, et excécutez les lignes suivantes dans votre console:</p> + +<pre class="brush: js">var testFunc = otherTable.get(0); +typeof testFunc;</pre> + +<p>Vous obtiendrez le résultat <code>function</code> en valeur de retour. Cette fonction peut effectuer tout ce qu'une fonction Javascript classique peut effectuer — <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/call">call()</a></code>, <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind">bind()</a></code>, etc. <code>testFunc.toString()</code> retourne un résultat intéressant:</p> + +<pre class="brush: js">function 0() { + [native code] +}</pre> + +<p>Cela vous donne une idée plus précise de la nature de l'emballage (wrapper-type).</p> + +<p>Some other particulars to be aware of with exported WebAssembly functions:</p> + +<ul> + <li>Their <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/length">length</a> property is the number of declared arguments in the wasm function signature.</li> + <li>Their <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/name">name</a> property is the <code>toString()</code> result of the function's index in the wasm module.</li> + <li>If you try to call a exported wasm function that takes or returns an i64 type value, it currently throws an error because JavaScript currently has no precise way to represent an i64. This may well change in the future though — a new int64 type is being considered for future standards, which could then be used by wasm.</li> +</ul> diff --git a/files/fr/webassembly/index.html b/files/fr/webassembly/index.html new file mode 100644 index 0000000000..fa7db53f05 --- /dev/null +++ b/files/fr/webassembly/index.html @@ -0,0 +1,163 @@ +--- +title: WebAssembly +slug: WebAssembly +tags: + - Landing + - WebAssembly + - wasm +translation_of: WebAssembly +--- +<div>{{WebAssemblySidebar}}{{SeeCompatTable}}</div> + +<p class="summary" dir="ltr" id="docs-internal-guid-22bb55aa-d69e-e8ef-cbc6-aafea272f684">WebAssembly est un nouveau type de code qui peut être exécuté dans un navigateur web moderne. C'est un langage bas niveau, semblable à l'assembleur permettant d'atteindre des performances proches des applications natives (par exemple écrites en C/C++) tout en fonctionnant sur le Web. WebAssembly est conçu pour fonctionner en lien avec JavaScript.</p> + +<h2 dir="ltr" id="En_résumé">En résumé</h2> + +<p dir="ltr">WebAssembly représente une avancée fondamentale de la plateforme web. Il permet d'exécuter du code (éventuellement écrit depuis différents langages) sur le Web avec des performances similaires aux applications natives.</p> + +<p dir="ltr">WebAssembly est conçu pour être utilisé de pair avec JavaScript. Grâce à l'API JavaScript WebAssembly, on peut charger des modules WebAssembly au sein d'une application JavaScript et partager des fonctionnalités entre les deux. Cela permet de tirer parti des performances de WebAssembly et de la flexibilité de JavaScript, même si on ne sait pas écrire du code WebAssembly.</p> + +<p dir="ltr">WebAssembly est conçu comme un standard web par le <a href="https://www.w3.org/community/webassembly/">groupe communautaire du W3C pour WebAssembly</a> auquel participe les différents éditeurs de navigateur.</p> + +<div class="row topicpage-table"> +<div class="section"> +<h2 dir="ltr" id="Guides">Guides</h2> + +<dl> + <dt><a href="/fr/docs/WebAssembly/Concepts">Les concepts de WebAssembly</a></dt> + <dd>Découvrez les concepts clés de WebAssembly : ce que c'est, son utilité, l'intégration dans le Web et comment l'utiliser.</dd> + <dt><a href="/fr/docs/WebAssembly/C_to_wasm">Compiler du code C/C++ en WebAssembly</a></dt> + <dd>Du code écrit en C/C++ peut être compilé en WebAssembly grâce à des outils tels que <a href="/fr/docs/Mozilla/Projects/Emscripten">Emscripten</a>. Nous voyons ici comment cela fonctionne.</dd> + <dt><a href="/fr/docs/WebAssembly/Loading_and_running">Charger et exécuter du code WebAssembly</a></dt> + <dd>Dans cet article, on aborde comment récupérer, compiler et instancier en associant l'API <a href="/fr/docs/Web/JavaScript/Reference/Objets_globaux/WebAssembly">WebAssembly JavaScript</a> avec les API <a href="/fr/docs/Web/API/Fetch_API">Fetch</a> ou <a href="/fr/docs/Web/API/XMLHttpRequest">XHR</a>.</dd> + <dt><a href="/fr/docs/WebAssembly/Caching_modules">Mettre en cache des modules WebAssembly compilés</a></dt> + <dd>La mise en cache de grands modules WebAssembly côté client permet d'améliorer les performances au démarrage. Dans cet article, on voit comment utiliser <a href="/fr/docs/Web/API/IndexedDB_API">IndexedDB</a> pour cela.</dd> + <dt><a href="/fr/docs/WebAssembly/Using_the_JavaScript_API">Utiliser l'API JavaScript de WebAssembly</a></dt> + <dd>Une fois le module WebAssembly chargé, on souhaitera l'utiliser… Dans cet article, on verra comment utiliser WebAssembly grâce à l'API JavaScript associée.</dd> + <dt><a href="/fr/docs/WebAssembly/Exported_functions">Les fonctions WebAssembly exportées</a></dt> + <dd>Les fonctions WebAssembly exportées sont les représentations JavaScript des fonctions WebAssembly qui permettent d'utiliser du code WebAssembly depuis un script JavaScript. Cet article décrit leur fonctionnement.</dd> + <dt><a href="/fr/docs/WebAssembly/Understanding_the_text_format">Comprendre le format texte WebAssembly</a></dt> + <dd>Cet article explique la composition du format texte de WebAssembly. Il s'agit d'une représentation bas-niveau du module .wasm tel que montré dans les outils de développement du navigateur.</dd> + <dt><a href="/fr/docs/WebAssembly/Text_format_to_wasm">Convertir un fichier texte WebAssembly en wasm</a></dt> + <dd>Cet article détaille comment convertir un module WebAssembly rédigé dans un format texte en un fichier binaire .wasm.</dd> +</dl> +</div> + +<div class="section"> +<h2 dir="ltr" id="Référence_de_l'API_JavaScript">Référence de l'API JavaScript</h2> + +<dl> + <dt>{{jsxref("Objets_globaux/WebAssembly", "WebAssembly")}}</dt> + <dd>Cet objet représente l'espace de nom encapsulant les fonctionnalités relatives à WebAssembly.</dd> + <dt>{{jsxref("Objets_globaux/WebAssembly/Module", "WebAssembly.Module")}}</dt> + <dd>Un objet <code>WebAssembly.Module</code> contient du code WebAssembly, sans état, qui a déjà été compilé par le navigateur et qui peut être <a href="/fr/docs/Web/API/Worker/postMessage">partagé dans les <em>web workers</em></a>, <a href="/fr/docs/WebAssembly/Caching_modules">mis en cache dans IndexedDB</a> et instancié à plusieurs reprises.</dd> + <dt>{{jsxref("Objets_globaux/WebAssembly/Instance", "WebAssembly.Instance")}}</dt> + <dd>Un objet <code>WebAssembly.Instance</code> est une instance exécutable (disposant d'un état) d'un <code>Module</code>. Les objets <code>Instance</code> contiennent toutes les <a href="/fr/docs/WebAssembly/Exported_functions">fonctions WebAssembly exportées</a> qui permettent d'utiliser du code WebAssembly via du code JavaScript.</dd> + <dt>{{jsxref("Objets_globaux/WebAssembly/instantiate", "WebAssembly.instantiate()")}}</dt> + <dd>La fonction <code>WebAssembly.instantiate()</code> représente l'API principale pour compiler et instancier le code WebAssembly. Cette méthode renvoie un <code>Module</code> ainsi que sa première <code>Instance</code>.</dd> + <dt>{{jsxref("Objets_globaux/WebAssembly/Memory", "WebAssembly.Memory()")}}</dt> + <dd>Un objet <code>WebAssembly.</code><code>Memory</code> est un tableau {{jsxref("Objets_globaux/ArrayBuffer", "ArrayBuffer")}} redimensionnable qui contient les octets de mémoire brute auxquels on peut accéder via une <code>Instance</code>.</dd> + <dt>{{jsxref("Objets_globaux/WebAssembly/Table", "WebAssembly.Table()")}}</dt> + <dd>Un objet <code>WebAssembly.</code><code>Table</code> est un tableau typé contenant des valeurs opaques et qui peut être redimensionné. On peut accéder aux valeurs via un objet <code>Instance</code>.</dd> + <dt>{{jsxref("WebAssembly.CompileError()")}}</dt> + <dd>Crée un nouvel objet WebAssembly <code>CompileError</code>.</dd> + <dt>{{jsxref("WebAssembly.LinkError()")}}</dt> + <dd>Crée un nouvel objet WebAssembly <code>LinkError</code>.</dd> + <dt>{{jsxref("WebAssembly.RuntimeError()")}}</dt> + <dd>Crée un nouvel objet WebAssembly <code>RuntimeError</code>.</dd> +</dl> +</div> +</div> + +<h2 dir="ltr" id="Exemples">Exemples</h2> + +<ul dir="ltr"> + <li><a href="https://github.com/JasonWeathersby/WASMSobel">WASMSobel</a></li> + <li>Notre dépôt GitHub <a href="https://github.com/mdn/webassembly-examples/">webassembly-examples</a> qui contient plusieurs exemples.</li> +</ul> + +<h2 id="Spécifications">Spécifications</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Spécification</th> + <th scope="col">État</th> + <th scope="col">Commentaires</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName('WebAssembly JS')}}</td> + <td>{{Spec2('WebAssembly JS')}}</td> + <td>Brouillon de définition initiale pour l'API JavaScript.</td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilité_des_navigateurs">Compatibilité des navigateurs</h2> + +<div>{{CompatibilityTable}}</div> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Fonctionnalité</th> + <th>Chrome</th> + <th>Edge</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>Support simple</td> + <td>57</td> + <td>16</td> + <td>{{CompatGeckoDesktop(52)}}<sup>[1]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>11</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Fonctionnalité</th> + <th>Chrome pour Android</th> + <th>Webview Android</th> + <th>Edge Mobile</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Support simple</td> + <td>57</td> + <td>57</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile(52)}}<sup>[1]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] WebAssembly est activé sur Firefox 52 et les versions ultérieures mais est désactivée pour <a href="https://www.mozilla.org/en-US/firefox/organizations/">Firefox 52 Extended Support Release</a> (ESR.)</p> + +<h2 id="Voir_aussi">Voir aussi</h2> + +<ul dir="ltr"> + <li><a href="http://webassembly.org/">webassembly.org</a></li> + <li><a href="https://hacks.mozilla.org/category/webassembly/">Les articles WebAssembly sur Mozilla Hacks</a> ou sur <a href="https://tech.mozfr.org/tag/WebAssembly">tech.mozfr.org en français</a></li> + <li><a href="https://www.w3.org/community/webassembly/">Le groupe communautaire W3C sur WebAssembly</a></li> + <li><a href="/fr/docs/Web/HTTP/Headers/Large-Allocation">L'en-tête HTTP <code>Large-Allocation</code></a></li> +</ul> diff --git a/files/fr/webassembly/loading_and_running/index.html b/files/fr/webassembly/loading_and_running/index.html new file mode 100644 index 0000000000..a4bffec293 --- /dev/null +++ b/files/fr/webassembly/loading_and_running/index.html @@ -0,0 +1,108 @@ +--- +title: Loading and running WebAssembly code +slug: WebAssembly/Loading_and_running +translation_of: WebAssembly/Loading_and_running +--- +<div>{{WebAssemblySidebar}}</div> + +<div>Pour utiliser webassembly au sein de javascript, votre module doit être placé en mémoire. La mise en mémoire du module précède les étapes de compiliation et d'instantiation. Cet article fournit une référence pour les différents méchanismes qui permettent de récupérer le bytecode webassembly, ainsi que des informations sur la manière de le compiler, l'instancier, et l'exécuter. </div> + +<h2 id="Quelles_sont_les_différentes_options">Quelles sont les différentes options?</h2> + +<p>Webassembly n'est pas encore intégré à <code><script type='module'></code> ou ES2015 <code>import</code>, autrement dit le navigateur ne peut pas récuperer les modules à l'aide de déclaration d'imports. </p> + +<p>Les anciennes méthodes {{jsxref("WebAssembly.compile")}}/{{jsxref("WebAssembly.instantiate")}} requièrent la création d'un {{domxref("ArrayBuffer")}} contenant le binaire de votre module webassembly sous forme d'octet brut, pour ensuite effectuer sa compilation et son instantiation. Cette approche est simialire à <code>new Function(string)</code>, à la différence que dans notre cas, nous substituons une chaine de charactères par une chaine de bytes (le code source webassembly). </p> + +<p>Les nouvelles méthodes {{jsxref("WebAssembly.compileStreaming")}}/{{jsxref("WebAssembly.instantiateStreaming")}} sont beaucoup plus efficace — elles s'applique directement sur le flux d'octets récupérer par le réseau, et ne nécessite pas l'utilisaton d'un {{domxref("ArrayBuffer")}}.</p> + +<p>Quelle est donc la démarche à suivre pour obtenir cet array buffer et le compiler ? La réponse dans les sections suivantes.</p> + +<h2 id="En_utilisant_Fetch">En utilisant Fetch</h2> + +<p><a href="/en-US/docs/Web/API/Fetch_API">Fetch</a> est une API qui facilite la récupération de ressources sur le réseau.</p> + +<p>La façon la plus rapide et la plus efficace de récupérer un module wasm (webassembly) est d'utiliser la méthode {{jsxref("WebAssembly.instantiateStreaming()")}}, qui accepte comme premier argument un appel de fonction <code>fetch()</code>, et s'occupe de récupérer, compiler, et instancier le module en une seule et même étape, en accedant directement au flux de code binaire provenant du serveur:</p> + +<pre class="brush: js">WebAssembly.instantiateStreaming(fetch('simple.wasm'), importObject) +.then(results => { + // Do something with the results! +});</pre> + +<p>L'ancienne méthode {{jsxref("WebAssembly.instantiate()")}} n'accède pas directement au flux de données. Elle nécessite une étape supplémentaire afin de convertir le byte code récupéré en {{domxref("ArrayBuffer")}}. Elle s'implemente de cette façon:</p> + +<pre class="brush: js">fetch('module.wasm').then(response => + response.arrayBuffer() +).then(bytes => + WebAssembly.instantiate(bytes, importObject) +).then(results => { + // Do something with the results! +});</pre> + + + +<h3 id="Aside_on_instantiate()_overloads">Aside on instantiate() overloads</h3> + +<p>The {{jsxref("WebAssembly.instantiate()")}} function has two overload forms — the one shown above takes the byte code to compile as an argument and returns a promise that resolves to an object containing both the compiled module object, and an instantiated instance of it. The object looks like this:</p> + +<pre class="brush: js">{ + module : Module // The newly compiled WebAssembly.Module object, + instance : Instance // A new WebAssembly.Instance of the module object +}</pre> + +<div class="note"> +<p><strong>Note</strong>: En règle générale, on ne s'intéresse qu'à l'instance, mais il peut être utile de préserver le module afin de le mettre ultérieurement en cache, de le partager avec un autre worker ou window via <code><a href="/en-US/docs/Web/API/MessagePort/postMessage">postMessage()</a></code>, ou tout simplement pour créer d'autres instances.</p> +</div> + +<div class="note"> +<p><strong>Note</strong>: Un chargement supplémentaire du module nécessite un object de type {{jsxref("WebAssembly.Module")}} comme argument, et retourne une promesse contenant directement un objet de type instance comme résultat. Voir <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/instantiate#Second_overload_example">Second overload example</a>.</p> +</div> + +<h3 id="Mise_en_marche_du_code_webassembly">Mise en marche du code webassembly</h3> + +<p>Une fois l'instance webassembly disponible au sein de Javascript, vous pouvez commencer à utiliser les fonctionnalités exportées, accessibles via la propriété {{jsxref("WebAssembly.Instance/exports", "WebAssembly.Instance.exports")}}. Votre code peut s'organsier de la manière suivante:</p> + +<pre class="brush: js">WebAssembly.instantiateStreaming(fetch('myModule.wasm'), importObject) +.then(obj => { + // Call an exported function: + obj.instance.exports.exported_func(); + + // or access the buffer contents of an exported memory: + var i32 = new Uint32Array(obj.instance.exports.memory.buffer); + + // or access the elements of an exported table: + var table = obj.instance.exports.table; + console.log(table.get(0)()); +})</pre> + +<div class="note"> +<p><strong>Note</strong>: Pour plus d'informations sur la façon dont fonctionne l'exportation au sein d'un module webassembly, lisez <a href="/en-US/docs/WebAssembly/Using_the_JavaScript_API">Using the WebAssembly JavaScript API</a>, et <a href="/en-US/docs/WebAssembly/Understanding_the_text_format">Understanding WebAssembly text format</a>.</p> +</div> + +<h2 id="En_utilisant_XMLHttpRequest">En utilisant XMLHttpRequest</h2> + +<p><code><a href="/en-US/docs/Web/API/XMLHttpRequest">XMLHttpRequest</a></code> est plus ancien que Fetch, mais peut toujours être utiliser afin récupérer un array buffer. En supposant que notre module se nome <code>simple.wasm</code>:</p> + +<ol> + <li>Créer une nouvel instance {{domxref("XMLHttpRequest()")}}, afin d'utiliser la méthode {{domxref("XMLHttpRequest.open","open()")}} nécessaire pour ouvrir une requête. Paramètrer la requête avec une méthode <code>GET</code>, et y déclarer le chemin du fichier que nous souhaiter récupérer.</li> + <li>L'étape essentielle est içi de définir la réponse comme une réponse de type <code>'arraybuffer'</code> en utilisant la propriété {{domxref("XMLHttpRequest.responseType","responseType")}}.</li> + <li>Ensuite, la requête est envoyée à l'aide de la méthode {{domxref("XMLHttpRequest.send()")}}.</li> + <li>Enfin l'event handler {{domxref("XMLHttpRequest.onload", "onload")}} se charge d'invoquer une fonction lorsque la réponse a terminé de se télécharger — au sein de cette fonction, la propriété {{domxref("XMLHttpRequest.response", "response")}} nous donne accès à un array buffer. Celui ci est fournit à notre méthode {{jsxref("WebAssembly.instantiate()")}} d'un manière similaire à ce qui est fait avec la méthode Fetch().</li> +</ol> + +<p>Le code final est le suivant:</p> + +<pre class="brush: js">request = new XMLHttpRequest(); +request.open('GET', 'simple.wasm'); +request.responseType = 'arraybuffer'; +request.send(); + +request.onload = function() { + var bytes = request.response; + WebAssembly.instantiate(bytes, importObject).then(results => { + results.instance.exports.exported_func(); + }); +};</pre> + +<div class="note"> +<p><strong>Note</strong>: Vous pouvez retrouver un autre exemple sur <a href="https://mdn.github.io/webassembly-examples/js-api-examples/xhr-wasm.html">xhr-wasm.html</a>.</p> +</div> diff --git a/files/fr/webassembly/understanding_the_text_format/index.html b/files/fr/webassembly/understanding_the_text_format/index.html new file mode 100644 index 0000000000..4a38e79ea1 --- /dev/null +++ b/files/fr/webassembly/understanding_the_text_format/index.html @@ -0,0 +1,865 @@ +--- +title: Comprendre le format texte de WebAssembly +slug: WebAssembly/Understanding_the_text_format +tags: + - JavaScript + - Texte + - WebAssembly + - wasm +translation_of: WebAssembly/Understanding_the_text_format +--- +<h2 id="drame">drame</h2> + +<p>HTML</p> + +<dl> +</dl> + +<pre class="brush: html notranslate">Contenu HTML de l'exemple</pre> + +<h3 id="CSS">CSS</h3> + +<pre class="brush: css notranslate">Contenu CSS de l'exemple +</pre> + +<h3 id="Résultat">Résultat</h3> + +<dl> + <dt>{{EmbedLiveSample}}</dt> + <dd>Afin de permettre aux humains de lire et d'éditer du code WebAssembly, il y a une représentation textuelle du format binaire wasm. C'est une forme intermédiaire conçue pour être affic<span style="display: none;"> </span><span style="display: none;"> </span>hée dans les éditeurs de texte, les outils de développeurs intégrés aux navigateurs web, etc. Cet article montre comment ce format fonctionne sur le plan syntaxique, mais aussi comment il se combine avec le code binaire sous-jacent — ainsi que l'objet JavaScript englobant qui représente wasm.</dd> + <dt><strong>Note</strong>: Ceci est potentiellement exagéré si vous êtes un développeur web cherchant uniquement à charger un module wasm dans une page pour l'utiliser dans votre code (voir <a href="https://developer.mozilla.org/fr/docs/WebAssembly/Using_the_JavaScript_API">Utilisez l'API JavaScript de WebAssembly</a>). Mais il est plus utile si, en revanche, vous voulez écrite des modules wasm pour optimiser les performances de votre librairies Javascript, ou construire votre propre compilateur WebAssembl</dt> +</dl> + +<div class="note"></div> + +<h2 id="S-expressions">S-expressions</h2> + +<p>Dans le format binaire comme dans le format textuel, l'unité de code fondamentale en WebAssembly est le module. Dans le format textuel, un module est représenté par une grosse S-expression. Les S-expressions sont un format simple et ancien pour représenter des arbres logiques, et en conséquence, nous pouvons considérer un module comme un arbre de noeuds décrivant la structure du module et de son code. A l'inverse de l'Arbre Syntaxique Abstrait d'un langage de programmation, l'arbre de WebAssembly est assez plat, et consiste pour beaucoup en une liste d'instructions.</p> + +<p>Tout d'abord, regardons à quoi ressemble une S-expression. Chaque noeud de l'arbre se situe à l'intérieur d'un couple de parenthèses — <code>( ... )</code>. Le premier label dans ces parenthèses indique le type de noeud. Ensuite, il y a une liste de noeufs ou d'attributs séparés par des espaces. Donc si l'on considère la S-expression WebAssembly suivante :</p> + +<pre class="notranslate">(module (memory 1) (func))</pre> + +<p>Celle-ci représente un arbre avec un noeud racine "module" ainsi que deux noeuds enfants, un "memory" avec l'attribut 1, ainsi qu'un noeud "func". Nous allons bientôt voir ce que ces noeuds signifient.</p> + +<h3 id="Le_plus_basique_des_modules">Le plus basique des modules</h3> + +<p>Commençons avec la version la plus simple et la plus courte possible d'un module wasm.</p> + +<pre class="notranslate">(module) (commençons avec la version la plus simple et la plus courte possible d'un module wasm.) </pre> + +<p>Celui-ci est totalement vide, mais reste un module valide.</p> + +<p>Si l'on convertit notre module en binaire (voir <a href="/en-US/docs/WebAssembly/Text_format_to_wasm">Converting WebAssembly text format to wasm</a>), nous obtenons l'en-tête de module de 8 octets, décrite dans le <a href="https://webassembly.org/docs/binary-encoding/#high-level-structure">format binaire</a>.</p> + +<pre class="notranslate">0000000: 0061 736d ; WASM_BINARY_MAGIC +0000004: 0100 0000 ; WASM_BINARY_VERSION</pre> + +<h3 id="Ajouter_des_fonctionnalités_à_votre_module">Ajouter des fonctionnalités à votre module</h3> + +<p>Un module vide n'étant clairement pas très intéressant, prenons le temps d'y ajouter du code.</p> + +<p>Tout code dans un module WebAssembly est regroupé en fonctions, qui ont la structure suivante (en pseudo-code):</p> + +<pre class="notranslate">( func <signature> <locals> <body> )</pre> + +<ul> + <li>La <strong>signature </strong>déclare les arguments de la fonction ainsi que ses valeurs de retour.</li> + <li>Les <strong>locals</strong> sont un peu comme des variables JavaScript, mais avec des type explicitement déclarés.</li> + <li>Le <strong>body</strong> est juste une liste d'instructions bas-niveau.</li> +</ul> + +<p>Donc les fonctions WebAssembly se rapprochent beaucoup des fonctions dans les autres langages, à l'exception près qu'elles sont représentées par un S-expression.</p> + +<h2 id="Signatures_et_Paramètres">Signatures et Paramètres</h2> + +<p>La signature est une séquence de déclaration des différents types d'arguments, suivie par une liste de déclarations des différents types pour les valeurs de retours. Il est important de noter que :</p> + +<ul> + <li>L'absence de (result) signifie que la fonction ne retourne rien.</li> + <li>Dans la version actuelle, il peut y avoir au plus 1 type de retour, mais cette règle <a href="https://webassembly.org/docs/future-features/#multiple-return">va être assouplie à l'avenir</a>.</li> +</ul> + + + +<div class="blockIndicator warning"> +<p>Chaque argument possède un type déclaré explicitement. Quatre types sont actuellement</p> + +<table class="standard-table"> + <caption>préparation</caption> + <thead> + <tr> + <th scope="col"> + <ul> + <li> + <div class="blockIndicator note"> + <div class="blockIndicator warning"> + <p>Mathematique</p> + </div> + </div> + </li> + </ul> + </th> + <th scope="col"> + <ul> + <li> + <div class="blockIndicator note"> + <div class="blockIndicator warning"> + <p>histoire-goegraphie</p> + </div> + </div> + </li> + </ul> + </th> + <th scope="col"> + <ul> + <li> + <div class="blockIndicator note"> + <div class="blockIndicator warning"> + <p>sciense applique </p> + </div> + </div> + </li> + </ul> + </th> + <th scope="col"> + <ul> + <li> + <div class="blockIndicator warning"> + <p>sciense naturel </p> + </div> + </li> + </ul> + </th> + <th scope="col"> + <h5 id="sect1"></h5> + </th> + <th scope="col"></th> + </tr> + </thead> + <tbody> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + </tbody> +</table> + +<blockquote> +<h5 class="brush: bash" id="disponible_dans_wasm">disponible dans wasm:</h5> +</blockquote> + +<dl> +</dl> +</div> + +<ul> + <li><code>i32</code>: Entier 32-bit</li> + <li><code>i64</code>: Entier 64-bit</li> + <li><code>f32</code>: Nombre à virgule flottante 32-bit float</li> + <li><code>f64</code>: Nombre à virgule flottante 64-bit float</li> +</ul> + +<p>Un argument seul s'écrit <code>(param i32)</code> et le type de retour s'écrit <code>(result i32)</code>, donc une fonction binaire prenant deux entiers 32-bit and et retournant un nombre à virgule flottante 64-bit s'écrirait ainsi :</p> + +<pre class="notranslate">(func (param i32) (param i32) (result f64) ... )</pre> + +<p>Après la signature, les variables locales sont listées avec leur type, par exemple <code>(local i32)</code>. Les arguments sont juste des variables locales initialisées avec avec la valeur de l'argument correspondant, passé par la fonction appelante.</p> + +<h2 id="Récupérer_et_définir_les_variables_locales_et_les_arguments">Récupérer et définir les variables locales et les arguments</h2> + +<p>Les variables locales et les arguments peuvent être lus et écrits par le corps de la fonction, via les instructions <code>get_local</code> et <code>set_local</code>.</p> + +<p>Les commandes <code>get_local</code>/<code>set_local</code> désignent l'élément à récupérer/définir par son index numérique : les arguments sont référencés en premier, par ordre de déclaration, suivis par les variables locales, par ordre de déclaration également. Donc, en considérant la fonction suivante :</p> + +<pre class="notranslate">(func (param i32) (param f32) (local f64) + get_local 0 + get_local 1 + get_local 2)</pre> + +<p>L'instruction <code>get_local 0</code> récupère l'argument i32, <code>get_local 1</code> récupère l'argument f32, et <code>get_local 2</code> récupère la variable locale f64.</p> + +<p>Il y a un hic à cette manière de procéder. Le fait d'utiliser des index numériques pour faire références à des éléments du code peut être déroutant. Le format textuel de wasm vous permet pour éviter cela de nommer les arguments, variables locales et autres éléments du code, en incluant un nom préfixé par un symbol dollar (<code>$</code>) juste avant la déclaration du type.</p> + +<p>Ainsi, vous pourriez ré-écrire la signature précédente ainsi :</p> + +<pre class="notranslate">(func (param $p1 i32) (param $p2 f32) (local $loc i32) …)</pre> + +<p>Et ensuite, vous pourriez écrire <code>get_local $p1</code> en lieu et place de <code>get_local 0</code>, etc. (Lorsque ce texte sera converti en binaire, le code de sortie contiendra uniquement l'entier)</p> + +<h2 id="Automates_à_pile">Automates à pile</h2> + +<p>Avant que nous puissions écrire le corps d'une fonction, nous devons aborder une dernière chose : <strong>les automates à pile</strong> (<em>Stack machines</em> en anglais). Bien que le navigateur compile le wasm en quelque chose de plus efficace, l'éxecution de wasm est définie par un automate à pile où l'idée de base est que chaque type d'instruction ajoute ou retire un certain nombre de valeurs <code>i32</code>/<code>i64</code>/<code>f32</code>/<code>f64</code> à une pile.</p> + +<p>Par exemple, <code>get_local</code> est destinée à ajouter sur la pile la valeur de la variable qu'elle lit, et <code>i32.add</code> retire deux valeurs <code>i32</code> (il récupère implicitement les deux précédentes valeurs ajoutée sur la pile), calcule leur somme (modulo 2^32) et ajoute la valeur i32 résultante.</p> + +<p>Lorsqu'une fonction est appelée, elle débute avec une pile vide qui est peu à peu remplie et vidée durant l'exécution du corps de la fonction. Par exemple, après l'exécution de la fonction suivante :</p> + +<pre class="notranslate">(func (param $p i32) + get_local $p + get_local $p + i32.add)</pre> + +<p>La pile contient exactement une valeur i32 — le résultat de l'expression (<code>$p + $p</code>), qui est calculé par <code>i32.add</code>. La valeur de retour d'une fonction est simplement la dernière valeur restante de la pile.</p> + +<p>Les règles de validation de WebAssembly s'assurent de l'intégrité de la pile : si vous déclarez un <code>(result f32)</code>, alors la pile doit contenir exactement un <code>f32</code> à la fin. S'il n'y a pas de type de retour, alors la pile doit être vide.</p> + +<h2 id="Notre_premier_corps_de_fonction">Notre premier corps de fonction</h2> + +<p>Comme mentionné plus haut, le corps de la fonction est simplement une liste d'instructions qui s'enchaînent lorsque la fonction est appelée. En reprenant tout ce que nous avons déjà appris, nous pouvons enfin définir un module contenant notre simple fonction :</p> + +<pre class="notranslate">(module + (func (param $lhs i32) (param $rhs i32) (result i32) + get_local $lhs + get_local $rhs + i32.add))</pre> + +<p>Cette fonction prend deux arguments, fait leur somme, et retourne le résultat.</p> + +<p>Il y a évidemment beaucoup plus de choses qui peuvent être faites au sein du corps d'une fonction, mais pour l'instant nous allons rester dans la simplicité. Vous verrez beaucoup plus d'exemples au fur et à mesure. Pour avoir la liste exhaustive du code machine disponible, consultez <a href="https://webassembly.org/docs/semantics/">cette page</a>.</p> + +<h3 id="Appeler_la_fonction">Appeler la fonction</h3> + +<p>Notre fonction ne va pas faire grand chose en soi — maintenant nous devons l'appeler. Mais comment faire ? Un peu comme un module ES2015, les fonctions wasm doivent être explicitement exportées par une déclaration <code>export</code> dans le module.</p> + +<p>A l'image des variables locales, les fonctions sont identifiées par un index, mais par commodité, elle peuvent être nommées. Commençons par cela en premier : nous allons ajouter un nom précédé d'un symbole dollar, juste après le mot-clé <code>func</code>:</p> + +<pre class="notranslate">(func $add … )</pre> + +<p>Maintenant, nous allons ajouter la déclaration d'export, qui prend cette forme :</p> + +<pre class="notranslate">(export "add" (func $add))</pre> + +<p>Ici, <code>add</code> est le nom par lequel la fonction sera identifiée dans JavaScript, tandis que <code>$add</code> correspond à la fonction WebAssembly dans le module qui sera exportée.</p> + +<p>Notre module final ressemble à ceci (pour l'instant) :</p> + +<pre class="notranslate">(module + (func $add (param $lhs i32) (param $rhs i32) (result i32) + get_local $lhs + get_local $rhs + i32.add) + (export "add" (func $add)) +)</pre> + +<p>Si vous voulez suivre l'exemple, sauvegardez le module ci-dessus dans un fichier appelé <code>add.wat</code> , puis convertissez-le en un fichier binaire appelé <code>add.wasm</code> via wabt (cf. <a href="/en-US/docs/WebAssembly/Text_format_to_wasm">Converting WebAssembly text format to wasm</a> pour plus de détails).</p> + +<p>Ensuite, nous allons charger notre binaire dans un tableau typé appelé <code>addCode</code> (comme décrit dans <a href="/en-US/docs/WebAssembly/Fetching_WebAssembly_bytecode">Fetching WebAssembly Bytecode</a>), le compiler et l'instantier, puis exécuter notre fonction <code>add</code> dans JavaScript (nous pouvons désormais obtenir <code>add()</code> dans la propriété <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance/exports">exports</a></code> de l'instance):</p> + +<pre class="brush: js notranslate">WebAssembly.instantiateStreaming(fetch('add.wasm')) +.then(obj => { + console.log(obj.instance.exports.add(1, 2)); // "3" +});</pre> + +<div class="note"> +<p><strong>Note</strong>: Vous pouvez récupérer cet exemple via GitHub : <a href="https://github.com/mdn/webassembly-examples/blob/master/understanding-text-format/add.html">add.html</a> (<a href="https://mdn.github.io/webassembly-examples/understanding-text-format/add.html">démo</a>). Voir aussi {{jsxref("WebAssembly.instantiate()")}} pour plus de détails à propos de la fonction d'instanciation, ainsi que <code><a href="https://github.com/mdn/webassembly-examples/blob/master/wasm-utils.js">wasm-utils.js</a></code> pour le code source de <code>fetchAndInstantiate()</code>.</p> +</div> + +<h2 id="Sapproprier_les_fondamentaux">S'approprier les fondamentaux</h2> + +<p>Maintenant que nous avons vu les aspects basiques, continuons sur des fonctionnalités plus avancées.</p> + +<h3 id="Appeler_des_fonctions_à_partir_dautres_fonctions_du_même_module">Appeler des fonctions à partir d'autres fonctions du même module</h3> + +<p>L'instruction <code>call</code> appelle une fonction à partir de son index ou de son nom. Par exemple, le module suivant contient deux fonctions — l'une d'entre elle retourne la valeur 42, tandis que l'autre retourne le résultat de l'appel de la première plus un:</p> + +<pre class="notranslate">(module + (func $getAnswer (result i32) + i32.const 42) + (func (export "getAnswerPlus1") (result i32) + call $getAnswer + i32.const 1 + i32.add))</pre> + +<div class="note"> +<p><strong>Note</strong>: <code>i32.const</code> définit simplement un entier 32-bit et l'ajoute à la pile. Vous pouvez remplacer <code>i32</code> par n'importe quel autre type disponible, et changer la valeur du const comme vous le souhaitez (ici, nous avons défini la valeur <code>42</code>).</p> +</div> + +<p>Dans cet exemple, vous avez sûrement remarqué la section <code>(export "getAnswerPlus1")</code> , déclarée juste après la déclaration <code>func</code> de la seconde fonction. C'est un moyen plus rapide de déclarer que nous voulons exporter cette fonction, et de définir le nom avec lequel nous voulont l'exporter.</p> + +<p>Ceci revient à inclure une déclaration de fonction séparée en dehors de la fonction, autre part dans le module, de la même façon que ce que nous avons déjà fait précédemment :</p> + +<pre class="notranslate">(export "getAnswerPlus1" (func $functionName))</pre> + +<p>Voici le code JavaScript pour appeler notre module ci-dessus :</p> + +<pre class="brush: js notranslate">WebAssembly.instantiateStreaming(fetch('call.wasm')) +.then(obj => { + console.log(obj.instance.exports.getAnswerPlus1()); // "43" +});</pre> + +<div class="note"> +<p><strong>Note</strong>: Vous pouvez récupérer cet exemple via GitHub: <a href="https://github.com/mdn/webassembly-examples/blob/master/understanding-text-format/call.html">call.html</a> (<a href="https://mdn.github.io/webassembly-examples/understanding-text-format/call.html">démo</a>). A nouveau, voir <code><a href="https://github.com/mdn/webassembly-examples/blob/master/wasm-utils.js">wasm-utils.js</a></code> pour les sources de <code>fetchAndInstantiate()</code>.</p> +</div> + +<h3 id="Importer_des_fonctions_depuis_JavaScript">Importer des fonctions depuis JavaScript</h3> + +<p>Nous avons déjà vu du JavaScript appeler des fonctions WebAssembly, mais que dites-vous d'appeler des fonctions JavaScript depuis WebAssembly ? En fait, WebAssembly n'a pas nativement connaissance de JavaScript, mais il possède une méthode générique d'import de fonctions qui peut accepter des fonctions wasm ou JavaScript. Voici un exemple :</p> + +<pre class="notranslate">(module + (import "console" "log" (func $log (param i32))) + (func (export "logIt") + i32.const 13 + call $log))</pre> + +<p>WebAssembly has a two-level namespace so the import statement here is saying that we’re asking to import the <code>log</code> function from the <code>console</code> module. You can also see that the exported <code>logIt</code> function calls the imported function using the <code>call</code> instruction we introduced above.</p> + +<p>Imported functions are just like normal functions: they have a signature that WebAssembly validation checks statically, and they are given an index and can be named and called.</p> + +<p>JavaScript functions have no notion of signature, so any JavaScript function can be passed, regardless of the import’s declared signature. Once a module declares an import, the caller of {{jsxref("WebAssembly.instantiate()")}} must pass in an import object that has the corresponding properties.</p> + +<p>For the above, we need an object (let's call it <code>importObject</code>) such that <code>importObject.console.log</code> is a JavaScript function.</p> + +<p>This would look like the following:</p> + +<pre class="brush: js notranslate">var importObject = { + console: { + log: function(arg) { + console.log(arg); + } + } +}; + +WebAssembly.instantiateStreaming(fetch('logger.wasm'), importObject) +.then(obj => { + obj.instance.exports.logIt(); +});</pre> + +<div class="note"> +<p><strong>Note</strong>: You can find this example on GitHub as <a href="https://github.com/mdn/webassembly-examples/blob/master/understanding-text-format/logger.html">logger.html</a> (<a href="https://mdn.github.io/webassembly-examples/understanding-text-format/logger.html">see it live also</a>).</p> +</div> + +<h3 id="WebAssembly_Memory">WebAssembly Memory</h3> + +<p>The above example is a pretty terrible logging function: it only prints a single integer! What if we wanted to log a text string? To deal with strings and other more complex data types, WebAssembly provides <strong>memory</strong>. According to WebAssembly, memory is just a large array of bytes that can grow over time. WebAssembly contains instructions like <code>i32.load</code> and <code>i32.store</code> for reading and writing from <a href="http://webassembly.org/docs/semantics/#linear-memory">linear memory</a>.</p> + +<p>From JavaScript’s point of view, it’s as though memory is all inside one big (resizable) {{domxref("ArrayBuffer")}}. That’s literally all that asm.js has to play with (except that it isn't resizable; see the asm.js <a href="http://asmjs.org/spec/latest/#programming-model">Programming model</a>).</p> + +<p>So a string is just a sequence of bytes somewhere inside this linear memory. Let's assume that we’ve written a suitable string of bytes to memory; how do we pass that string out to JavaScript?</p> + +<p>The key is that JavaScript can create WebAssembly linear memory instances via the {{jsxref("WebAssembly.Memory()")}} interface, and access an existing memory instance (currently you can only have one per module instance) using the associated instance methods. Memory instances have a <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory/buffer">buffer</a></code> getter, which returns an <code>ArrayBuffer</code> that points at the whole linear memory.</p> + +<p>Memory instances can also grow, for example via the <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory/grow">Memory.grow()</a></code> method in JavaScript. When growth occurs, since <code>ArrayBuffer</code>s can’t change size, the current <code>ArrayBuffer</code> is detached and a new <code>ArrayBuffer</code> is created to point to the newer, bigger memory. This means all we need to do to pass a string to JavaScript is to pass out the offset of the string in linear memory along with some way to indicate the length.</p> + +<p>While there are many different ways to encode a string’s length in the string itself (for example, C strings); for simplicity here we just pass both offset and length as parameters:</p> + +<pre class="notranslate">(import "console" "log" (func $log (param i32) (param i32)))</pre> + +<p>On the JavaScript side, we can use the <a href="/en-US/docs/Web/API/TextDecoder">TextDecoder API</a> to easily decode our bytes into a JavaScript string. (We specify <code>utf8</code> here, but many other encodings are supported.)</p> + +<pre class="brush: js notranslate">consoleLogString(offset, length) { + var bytes = new Uint8Array(memory.buffer, offset, length); + var string = new TextDecoder('utf8').decode(bytes); + console.log(string); +}</pre> + +<p>The last missing piece of the puzzle is where <code>consoleLogString</code> gets access to the WebAssembly <code>memory</code>. WebAssembly gives us a lot of flexibility here: we can either create a <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory">Memory</a></code> object in JavaScript and have the WebAssembly module import the memory, or we can have the WebAssembly module create the memory and export it to JavaScript.</p> + +<p>For simplicity, let's create it in JavaScript then import it into WebAssembly. Our <code>import</code> statement is written as follows:</p> + +<pre class="notranslate">(import "js" "mem" (memory 1))</pre> + +<p>The <code>1</code> indicates that the imported memory must have at least 1 page of memory (WebAssembly defines a page to be 64KB.)</p> + +<p>So let's see a complete module that prints the string “Hi”. In a normal compiled C program, you’d call a function to allocate some memory for the string, but since we’re just writing our own assembly here and we own the entire linear memory, we can just write the string contents into global memory using a <code>data</code> section. Data sections allow a string of bytes to be written at a given offset at instantiation time and are similar to the <code>.data</code> sections in native executable formats.</p> + +<p>Our final wasm module looks like this:</p> + +<pre class="notranslate">(module + (import "console" "log" (func $log (param i32 i32))) + (import "js" "mem" (memory 1)) + (data (i32.const 0) "Hi") + (func (export "writeHi") + i32.const 0 ;; pass offset 0 to log + i32.const 2 ;; pass length 2 to log + call $log))</pre> + +<div class="note"> +<p><strong>Note</strong>: Above, note the double semi-colon syntax (<code>;;</code>) for allowing comments in WebAssembly files.</p> +</div> + +<p>Now from JavaScript we can create a Memory with 1 page and pass it in. This results in "Hi" being printed to the console:</p> + +<pre class="brush: js notranslate">var memory = new WebAssembly.Memory({initial:1}); + +var importObj = { console: { log: consoleLogString }, js: { mem: memory } }; + +WebAssembly.instantiateStreaming(fetch('logger2.wasm'), importObject) +.then(obj => { + obj.instance.exports.writeHi(); +});</pre> + +<div class="note"> +<p><strong>Note</strong>: You can find the full source on GitHub as <a href="https://github.com/mdn/webassembly-examples/blob/master/understanding-text-format/logger2.html">logger2.html</a> (<a href="https://mdn.github.io/webassembly-examples/understanding-text-format/logger2.html">also see it live</a>).</p> +</div> + +<h3 id="WebAssembly_tables">WebAssembly tables</h3> + +<p>To finish this tour of the WebAssembly text format, let’s look at the most intricate, and often confusing, part of WebAssembly: <strong>tables</strong>. Tables are basically resizable arrays of references that can be accessed by index from WebAssembly code.</p> + +<p>To see why tables are needed, we need to first observe that the <code>call</code> instruction we saw earlier (see {{anch("Calling functions from other functions in the same module")}}) takes a static function index and thus can only ever call one function — but what if the callee is a runtime value?</p> + +<ul> + <li>In JavaScript we see this all the time: functions are first-class values.</li> + <li>In C/C++, we see this with function pointers.</li> + <li>In C++, we see this with virtual functions.</li> +</ul> + +<p>WebAssembly needed a type of call instruction to achieve this, so we gave it <code>call_indirect</code>, which takes a dynamic function operand. The problem is that the only types we have to give operands in WebAssembly are (currently) <code>i32</code>/<code>i64</code>/<code>f32</code>/<code>f64</code>.</p> + +<p>WebAssembly could add an <code>anyfunc</code> type ("any" because the type could hold functions of any signature), but unfortunately this <code>anyfunc</code> type couldn’t be stored in linear memory for security reasons. Linear memory exposes the raw contents of stored values as bytes and this would allow wasm content to arbitrarily observe and corrupt raw function addresses, which is something that cannot be allowed on the web.</p> + +<p>The solution was to store function references in a table and pass around table indices instead, which are just i32 values. <code>call_indirect</code>’s operand can therefore simply be an i32 index value.</p> + +<h4 id="Defining_a_table_in_wasm">Defining a table in wasm</h4> + +<p>So how do we place wasm functions in our table? Just like <code>data</code> sections can be used to initialize regions of linear memory with bytes, <code>elem</code> sections can be used to initialize regions of tables with functions:</p> + +<pre class="notranslate">(module + (table 2 anyfunc) + (elem (i32.const 0) $f1 $f2) + (func $f1 (result i32) + i32.const 42) + (func $f2 (result i32) + i32.const 13) + ... +)</pre> + +<ul> + <li>In <code>(table 2 anyfunc)</code>, the 2 is the initial size of the table (meaning it will store two references) and <code>anyfunc</code> declares that the element type of these references is "a function with any signature". In the current iteration of WebAssembly, this is the only allowed element type, but in the future, more element types will be added.</li> + <li>The functions (<code>func</code>) sections are just like any other declared wasm functions. These are the functions we are going to refer to in our table (for example’s sake, each one just returns a constant value). Note that the order the sections are declared in doesn’t matter here — you can declare your functions anywhere and still refer to them in your <code>elem</code> section.</li> + <li>The <code>elem</code> section can list any subset of the functions in a module, in any order, allowing duplicates. This is a list of the functions that are to be referenced by the table, in the order they are to be referenced.</li> + <li>The <code>(i32.const 0)</code> value inside the <code>elem</code> section is an offset — this needs to be declared at the start of the section, and specifies at what index in the table function references start to be populated. Here we’ve specified 0, and a size of 2 (see above), so we can fill in two references at indexes 0 and 1. If we wanted to start writing our references at offset 1, we’d have to write <code>(i32.const 1)</code>, and the table size would have to be 3.</li> +</ul> + +<div class="note"> +<p><strong>Note</strong>: Uninitialized elements are given a default throw-on-call value.</p> +</div> + +<p>In JavaScript, the equivalent calls to create such a table instance would look something like this:</p> + +<pre class="brush: js notranslate">function() { + // table section + var tbl = new WebAssembly.Table({initial:2, element:"anyfunc"}); + + // function sections: + var f1 = function() { … } + var f2 = function() { … } + + // elem section + tbl.set(0, f1); + tbl.set(1, f2); +};</pre> + +<h4 id="Using_the_table">Using the table</h4> + +<p>Moving on, now we’ve defined the table we need to use it somehow. Let's use this section of code to do so:</p> + +<pre class="notranslate">(type $return_i32 (func (result i32))) ;; if this was f32, type checking would fail +(func (export "callByIndex") (param $i i32) (result i32) + get_local $i + call_indirect (type $return_i32))</pre> + +<ul> + <li>The <code>(type $return_i32 (func (param i32)))</code> block specifies a type, with a reference name. This type is used when performing type checking of the table function reference calls later on. Here we are saying that the references need to be functions that return an <code>i32</code> as a result.</li> + <li>Next, we define a function that will be exported with the name <code>callByIndex</code>. This will take one <code>i32</code> as a parameter, which is given the argument name <code>$i</code>.</li> + <li>Inside the function, we add one value to the stack — whatever value is passed in as the parameter <code>$i</code>.</li> + <li>Finally, we use <code>call_indirect</code> to call a function from the table — it implicitly pops the value of <code>$i</code> off the stack. The net result of this is that the <code>callByIndex</code> function invokes the <code>$i</code>’th function in the table.</li> +</ul> + +<p>You could also declare the <code>call_indirect</code> parameter explicitly during the command call instead of before it, like this:</p> + +<pre class="notranslate">(call_indirect (type $return_i32) (get_local $i))</pre> + +<p>In a higher level, more expressive language like JavaScript, you could imagine doing the same thing with an array (or probably more likely, object) containing functions. The pseudo code would look something like <code>tbl[i]()</code>.</p> + +<p>So, back to the typechecking. Since WebAssembly is typechecked, and <code>anyfunc</code> means "any function signature", we have to supply the presumed signature of the callee at the callsite, hence we include the <code>$return_i32</code> type, to tell the program a function returning an <code>i32</code> is expected. If the callee doesn’t have a matching signature (say an <code>f32</code> is returned instead), a {{jsxref("WebAssembly.RuntimeError")}} is thrown.</p> + +<p>So what links the <code>call_indirect</code> to the table we are calling? The answer is that there is only one table allowed right now per module instance, and that is what <code>call_indirect</code> is implicitly calling. In the future, when multiple tables are allowed, we would also need to specify a table identifier of some kind, along the lines of</p> + +<pre class="notranslate">call_indirect $my_spicy_table (type $i32_to_void)</pre> + +<p>The full module all together looks like this, and can be found in our <a href="https://github.com/mdn/webassembly-examples/blob/master/understanding-text-format/wasm-table.wat">wasm-table.wat</a> example file:</p> + +<pre class="notranslate">(module + (table 2 anyfunc) + (func $f1 (result i32) + i32.const 42) + (func $f2 (result i32) + i32.const 13) + (elem (i32.const 0) $f1 $f2) + (type $return_i32 (func (result i32))) + (func (export "callByIndex") (param $i i32) (result i32) + get_local $i + call_indirect (type $return_i32)) +)</pre> + +<p>We load it into a webpage using the following JavaScript:</p> + +<pre class="brush: js notranslate">WebAssembly.instantiateStreaming(fetch('wasm-table.wasm')) +.then(obj => { + console.log(obj.instance.exports.callByIndex(0)); // returns 42 + console.log(obj.instance.exports.callByIndex(1)); // returns 13 + console.log(obj.instance.exports.callByIndex(2)); // returns an error, because there is no index position 2 in the table +});</pre> + +<div class="note"> +<p><strong>Note</strong>: You can find this example on GitHub as <a href="https://github.com/mdn/webassembly-examples/blob/master/understanding-text-format/wasm-table.html">wasm-table.html</a> (<a href="https://mdn.github.io/webassembly-examples/understanding-text-format/wasm-table.html">see it live also</a>).</p> +</div> + +<div class="note"> +<p><strong>Note</strong>: Just like Memory, Tables can also be created from JavaScript (see <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Table">WebAssembly.Table()</a></code>) as well as imported to/from another wasm module.</p> +</div> + +<h3 id="Mutating_tables_and_dynamic_linking">Mutating tables and dynamic linking</h3> + +<p>Because JavaScript has full access to function references, the Table object can be mutated from JavaScript by the <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Table/grow">grow()</a></code>, <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Table/get">get()</a></code> and <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Table/set">set()</a></code> methods. When WebAssembly gets <a href="http://webassembly.org/docs/gc/">reference types</a>, WebAssembly code will be able to mutate tables itself with <code>get_elem</code>/<code>set_elem</code> instructions.</p> + +<p>Because tables are mutable, they can be used to implement sophisticated load-time and run-time <a href="http://webassembly.org/docs/dynamic-linking">dynamic linking schemes</a>. When a program is dynamically linked, multiple instances share the same memory and table. This is symmetric to a native application where multiple compiled <code>.dll</code>s share a single process’s address space.</p> + +<p>To see this in action, we’ll create a single import object containing a Memory object and a Table object, and pass this same import object to multiple <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/instantiate">instantiate()</a></code> calls.</p> + +<p>Our <code>.wat</code> examples look like so:</p> + +<p><code>shared0.wat</code>:</p> + +<pre class="notranslate">(module + (import "js" "memory" (memory 1)) + (import "js" "table" (table 1 anyfunc)) + (elem (i32.const 0) $shared0func) + (func $shared0func (result i32) + i32.const 0 + i32.load) +)</pre> + +<p><code>shared1.wat</code>:</p> + +<pre class="notranslate">(module + (import "js" "memory" (memory 1)) + (import "js" "table" (table 1 anyfunc)) + (type $void_to_i32 (func (result i32))) + (func (export "doIt") (result i32) + i32.const 0 + i32.const 42 + i32.store ;; store 42 at address 0 + i32.const 0 + call_indirect (type $void_to_i32)) +)</pre> + +<p>These work as follows:</p> + +<ol> + <li>The function <code>shared0func</code> is defined in <code>shared0.wat</code>, and stored in our imported table.</li> + <li>This function creates a constant containing the value <code>0</code>, and then uses the <code>i32.load</code> command to load the value contained in the provided memory index. The index provided is <code>0</code> — again, it implicitly pops the previous value off the stack. So <code>shared0func</code> loads and returns the value stored at memory index <code>0</code>.</li> + <li>In <code>shared1.wat</code>, we export a function called <code>doIt</code> — this fucntion creates two constants containing the values <code>0</code> and <code>42</code>, then calls <code>i32.store</code> to store a provided value at a provided index of the imported memory. Again, it implicitly pops these values off the stack, so the result is that it stores the value <code>42</code> in memory index <code>0</code>,</li> + <li>In the last part of the function, we create a constant with value <code>0</code>, then call the function at this index 0 of the table, which is <code>shared0func</code>, stored there earlier by the <code>elem</code> block in <code>shared0.wat</code>.</li> + <li>When called, <code>shared0func</code> loads the <code>42</code> we stored in memory using the <code>i32.store</code> command in <code>shared1.wat</code>.</li> +</ol> + +<div class="note"> +<p><strong>Note</strong>: The above expressions again pop values from the stack implicitly, but you could declare these explicitly inside the command calls instead, for example:</p> + +<pre class="notranslate">(i32.store (i32.const 0) (i32.const 42)) +(call_indirect (type $void_to_i32) (i32.const 0))</pre> +</div> + +<p>After converting to assembly, we then use <code>shared0.wasm</code> and <code>shared1.wasm</code> in JavaScript via the following code:</p> + +<pre class="brush: js notranslate">var importObj = { + js: { + memory : new WebAssembly.Memory({ initial: 1 }), + table : new WebAssembly.Table({ initial: 1, element: "anyfunc" }) + } +}; + +Promise.all([ + WebAssembly.instantiateStreaming(fetch('shared0.wasm'), importObj), + WebAssembly.instantiateStreaming(fetch('shared1.wasm'), importObj) +]).then(function(results) { + console.log(results[1].instance.exports.doIt()); // prints 42 +});</pre> + +<p>Each of the modules that is being compiled can import the same memory and table objects and thus share the same linear memory and table "address space".</p> + +<div class="note"> +<p><strong>Note</strong>: You can find this example on GitHub as <a href="https://github.com/mdn/webassembly-examples/blob/master/understanding-text-format/shared-address-space.html">shared-address-space.html</a> (<a href="https://mdn.github.io/webassembly-examples/understanding-text-format/shared-address-space.html">see it live also</a>).</p> +</div> + +<h2 id="Summary">Summary</h2> + +<p>This finishes our high-level tour of the major components of the WebAssembly text format and how they get reflected in the WebAssembly JS API.</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li>The main thing that wasn’t included is a comprehensive list of all the instructions that can occur in function bodies. See the <a href="http://webassembly.org/docs/semantics">WebAssembly semantics</a> for a treatment of each instruction.</li> + <li>See also the <a href="https://github.com/WebAssembly/spec/blob/master/interpreter/README.md#s-expression-syntax">grammar of the text format</a> that is implemented by the spec interpreter.</li> +</ul> diff --git a/files/fr/webassembly/using_the_javascript_api/index.html b/files/fr/webassembly/using_the_javascript_api/index.html new file mode 100644 index 0000000000..7e21dc4511 --- /dev/null +++ b/files/fr/webassembly/using_the_javascript_api/index.html @@ -0,0 +1,292 @@ +--- +title: Utiliser l'API JavaScript de WebAssembly +slug: WebAssembly/Using_the_JavaScript_API +translation_of: WebAssembly/Using_the_JavaScript_API +--- +<div>{{WebAssemblySidebar}}</div> + +<p class="summary">Si vous avez déjà <a href="/en-US/docs/WebAssembly/C_to_wasm">compilé un module depuis un autre langage en utilisant des outils comme Emscripten</a>, ou <a href="/en-US/docs/WebAssembly/Loading_and_running">chargé et éxecuté vous-même le code</a>, l'étape suivante est d'en apprendre plus à propos des autres fonctionnalités de l'API JavaScript WebAssembly. Cet article vous enseigne ce que vous aurez besoin de connaître.</p> + +<div class="note"> +<p><strong>Note</strong>: Si vous n'êtes pas familier avec les concepts de base mentionnés dans cet article et vous avez besoin de plus d'explication, lisez d'abord <a href="/en-US/docs/WebAssembly/Concepts">WebAssembly concepts</a>.</p> +</div> + +<h2 id="Quelques_exemples_simples">Quelques exemples simples</h2> + +<p>Parcourons quelques exemples illustrant l'utilisation de l'API Webassembly Javascript, et en particulier la manière dont elle peut être utilisé pour charger un module wasm au sein d'une page web. </p> + +<div class="note"> +<p><strong>Note</strong>: Vous pouvez trouver des exemples de code dans notre repo GitHub <a href="https://github.com/mdn/webassembly-examples">webassembly-examples</a>.</p> +</div> + +<h3 id="Préparation">Préparation</h3> + +<ol> + <li>Premièrement nous avons besoin d'un module wasm ! Récupérez notre fichier <a href="https://github.com/mdn/webassembly-examples/raw/master/js-api-examples/simple.wasm">simple.wasm</a> et sauvegardez une copie dans un nouveau document sur votre machine locale.</li> + <li>Ensuite, assurez-vous d'utiliser un navigateur supportant WebAssembly. Firefox 52+ et Chrome 57+ supportent WebAssembly par défaut.</li> + <li>Pour poursuivre, créez un simple fichier nommé <code>index.html</code> dans le même dossier que votre fichier wasm (vous pouvez utiliser notre <a href="https://github.com/mdn/webassembly-examples/blob/master/template/template.html">template simple</a> si vous n'en avez pas de facilement accessible).</li> + <li>Maintenant, pour nous aider à comprendre ce qui se passe ici, regardons la représentation textuelle de notre module wasm (que nous rencontrons aussi dans <a href="/en-US/docs/WebAssembly/Text_format_to_wasm#A_first_look_at_the_text_format">Converting WebAssembly format to wasm</a>): + <pre>(module + (func $i (import "imports" "imported_func") (param i32)) + (func (export "exported_func") + i32.const 42 + call $i))</pre> + </li> + <li>À la deuxième ligne, vous pouvez constater l'import d'un namespace à deux niveaux — la fonction interne <code>$i</code> est importée depuis <code>imports.imported_func</code>. Dans notre JavaScript, notre namespace doit reprendre ce format à deux niveaux lors de l'écriture de l'objet à importer dans le module wasm. Pour ce faire, créez un élément <code><script></script></code> dans votre fichier HTML, puis ajoutez le code suivant: + <pre class="brush: js">var importObject = { + imports: { + imported_func: function(arg) { + console.log(arg); + } + } + };</pre> + </li> +</ol> + +<h3 id="Streaming_de_notre_module_webassembly">Streaming de notre module webassembly</h3> + +<p>Il est dorénavant possible dans Firefox 58 de compiler et instancier les modules Webassembly directement à partir des ressources initiales. Il est nécessaire dans ce cas d'utiliser les méthodes {{jsxref("WebAssembly.compileStreaming()")}} et {{jsxref("WebAssembly.instantiateStreaming()")}}. Ces méthodes en streaming sont plus facile d'utilisation que leurs contreparties synchrones, car elles traduisent directement le bytecode en instances de type <code>Module</code>/<code>Instance</code>, sans nécessiter la manipulation d'une réponse intermédiaire {{domxref("Response")}} en un {{domxref("ArrayBuffer")}}.</p> + +<p>Cet exemple (voir notre démo sur GitHub <a href="https://github.com/mdn/webassembly-examples/blob/master/js-api-examples/instantiate-streaming.html">instantiate-streaming.html</a>, et également <a href="https://mdn.github.io/webassembly-examples/js-api-examples/instantiate-streaming.html">view it live</a>) montre comment utiliser <code>instantiateStreaming()</code> pour récupérer un module wasm, le compiler, l'instancier afin d'avoir accès aux fonctions exportées qu'il contient et d'y importer des fonctions Javascript, le tout en une seule et même étape. </p> + +<p>Ajoutez le code suivant à votre script, en dessous du premier bloc:</p> + +<pre><code>WebAssembly.instantiateStreaming(fetch('simple.wasm'), importObject) +.then(obj => obj.instance.exports.exported_func());</code></pre> + +<p>Le résultat net de l'ensemble du code est que l'appel à <code>exported_func</code>, notre fonction exportée Webassembly, entraîne à son tour l'appel à <code>imported_func</code> notre fonction importée Javscript, qui logue la valeur 42 fournie à l'instance WebAssembly dans la console. Si vous sauvegardez l'exemple et chargez le code dans un navigateur qui supporte WebAssembly, vous pourrez le voir en action.</p> + +<p><strong>Note</strong>: Cet exemple interminable et tarabiscoté semble aboutir à un résultat de faible importance, il permet néanmoins d'illustrer les possibilités offertes par l'utilisation conjointe d'un code WebAssembly et d'un code Javscript dans une application web. Comme il est précisé ailleurs, l'objectif de WebAssembly n'est pas de remplacer Javascript; à vrai dire les deux sont conçus pour fonctionner de concert, chacun tirant parti des forces de l'autre.</p> + +<h3 id="Chargement_de_notre_module_wasm_sans_streaming">Chargement de notre module wasm sans streaming</h3> + +<p>Si vous ne pouvez pas ou ne souhaitez pas utiliser les méthodes en streaming décrites ci-dessus, vous pouvez utiliser à la place les méthodes synchrones {{jsxref("WebAssembly.compile")}} / {{jsxref("WebAssembly.instantiate")}}.</p> + +<p>Ces méthodes n'accèdent pas directement au bytecode, elles requièrent une étape supplémentaire afin de transformer la réponse en un {{domxref("ArrayBuffer")}} , et cela avant les étapes de compilation/instanciation du module wasm.</p> + +<p>Le code équivalent à l'exemple précédent prend la forme suivante:</p> + +<pre><code>fetch('simple.wasm').then(response => + response.arrayBuffer() +).then(bytes => + WebAssembly.instantiate(bytes, importObject) +).then(results => { + results.instance.exports.exported_func(); +});</code></pre> + +<h3 id="Visualiser_wasm_dans_loutil_de_développement">Visualiser wasm dans l'outil de développement </h3> + +<p>In Firefox 54+, the Developer Tool Debugger Panel has functionality to expose the text representation of any wasm code included in a web page. To view it, you can go to the Debugger Panel and click on the “wasm://” entry.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15823/wasm-debug.png"></p> + +<p>Starting soon in Firefox, in addition to viewing WebAssembly as text, developers will be able to debug (place breakpoints, inspect the callstack, single-step, etc.) WebAssembly using the text format. See <a href="https://www.youtube.com/watch?v=R1WtBkMeGds">WebAssembly debugging with Firefox DevTools</a> for a video preview.</p> + +<h2 id="Memory">Memory</h2> + +<p>Dans le modèle mémoire bas niveau de WebAssembly, la mémoire est représentée comme une suite continue de bytes non typés appelée <a href="http://webassembly.org/docs/semantics/#linear-memory">Linear Memory</a>. Cette mémoire linéaire est accessible en écriture et en lecture par des instructions <a href="http://webassembly.org/docs/semantics/#linear-memory-accesses">load et store </a>à l'intérieur du module. Dans ce modèle de mémoire, les instructions load et store peuvent accéder à n'importe quel byte de la mémoire linéaire, ce qui est nécessaire à une réprésentation fidèle de concepts C/C++ comme les pointeurs.</p> + +<p>Cependant contrairement à une implémentation native d'un programe C/C++ dans laquelle l'espace de mémoire disponible recouvre celle de l'ensemble du processus, la mémoire accessible par une instance particulière de WebAssembly est un espace mémoire spécifique — potentiellement très réduit — contenu dans une objet mémoire WebAssembly. Ceci permet à une application web unique d'utiliser des librairies indépendantes — Chacune d'entre elles pouvant utiliser en interne WebAssembly— avec des espaces mémoires séparés qui sont complètement isolés les uns des autres.</p> + +<p>Dans Javascript, une instance Memory peut être pensée comme un ArrayBuffer redimensionnable. De la même manière que pour les ArrayBuffers, une application web peut créer de nombreux objets Memory indépendants. Vous pouvez en créer un en utilisant le constructeur {{jsxref("WebAssembly.Memory()")}}, qui prend comme arguments la taille initiale ainsi que la taille maximale de l'espace mémoire à créer.</p> + +<p>Explorons ces concepts à travers un exemple rapide.</p> + +<ol> + <li> + <p>Créez une autre page HTML (copiez pour cela notre <a href="https://github.com/mdn/webassembly-examples/blob/master/template/template.html">simple template</a>) et appelez la <code>memory.html</code>. Ajoutez un élement <code><script></script></code> à la page.</p> + </li> + <li> + <p>Maintenant ajoutez la ligne suivante en haut de votre script, afin de créer une instance mémoire:</p> + + <pre><code>var memory = new WebAssembly.Memory({initial:10, maximum:100});</code></pre> + + <p>L'unité pour <code>initial</code> et <code>maximum</code> correspond à une page WebAssembly — soit une taille fixe de 64 KB. Cela signifie que l'instance mémoire ci-dessus à une taille initiale de 64 KB, et une taille maximum de 6.4 MB.</p> + + <p>WebAssembly memory expose ses bytes par l'intermédiaire d'un tampon getter/setter qui retourne un ArrayBuffer. Par exemple, pour écrire 42 directement dans l'espace du premier mot de la mémoire linéaire, vous pouvez faire cela:</p> + + <pre><code>new Uint32Array(memory.buffer)[0] = 42;</code></pre> + + <p>Vous pouvez retourner cette même valeur en utilisant:</p> + + <pre><code>new Uint32Array(memory.buffer)[0]</code></pre> + </li> + <li> + <p>À vous d'essayer — Enregistrez ce que vous avez rédigé jusqu'à maintenant, chargez-le dans votre navigateur, puis essayez d'entrer les deux lignes ci-dessus dans votre Javscript console.</p> + </li> +</ol> + +<h3 id="Redimensionner_la_mémoire">Redimensionner la mémoire</h3> + +<p>Une instance de mémoire peut être agrandie par appel à la méthode {{jsxref("Memory.prototype.grow()")}}, qui prend comme argument la taille de mémoire à ajouter (en unité de page WebAssembly).</p> + +<pre><code>memory.grow(1);</code></pre> + +<p>Si une valeur maximum a été fournie à la création de l'instance mémoire, les tentatives d'augmenter l'espace mémoire au delà de cette valeur maximum aboutiront à une exception de type {{jsxref("WebAssembly.RangeError")}}. Le moteur Javsacript utilise cette valeur limite supérieure pour réserver d'avance un espace mémoire suffisant, ce qui permet de rendre les redimensionnements mémoires plus efficaces.</p> + +<p>Note: En raison du caractère immuable de la longueur de byte d'un {{domxref("ArrayBuffer")}}, après une opération {{jsxref("Memory.prototype.grow()")}} réussie, le buffer getter retourne un nouvel objet ArrayBuffer (avec la nouvelle longeur de byte du buffer) et tous les objets ArrayBuffer précédents se retrouve en état "dissocié", ou déconnectés de l'espace mémoire dont ils étaient issus initialement.</p> + +<p>Tout comme les fonctions, les espaces mémoires linéaires peuvent être définis à l'intérieur du module, ou bien importés. De manière similaire aux fonctions, un module peut également exporter sa mémoire. Cela signifie que Javascript peut accéder à la mémoire d'une instance WebAssembly soit en créant un nouveau <code>WebAssembly.Memory</code> afin de le passer en import à cette instance, soit en recevant un export Memory (via <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance/exports">Instance.prototype.exports</a></code>).</p> + +<h3 id="Exemple_avancé_pour_lutilisation_mémoire">Exemple avancé pour l'utilisation mémoire</h3> + +<p>Essayons de clarifier les affirmations ci-dessus à l'aide d'un exemple plus abouti — à savoir un module WebAssembly qui importe une instance mémoire telle que définie plus tôt, et qui l'alimente d'un tableau d'entiers, pour en faire la somme totale. Vous pouvez trouver cela dans ce fichier <a href="https://github.com/mdn/webassembly-examples/raw/master/js-api-examples/memory.wasm">memory.wasm.</a></p> + +<ol> + <li> + <p>Faites une copie locale de <code>memory.wasm</code> dans le même dossier que précédement.</p> + + <p><strong>Note</strong>: Vous pouvez trouver la représentation textuelle du module sur <a href="https://github.com/mdn/webassembly-examples/blob/master/js-api-examples/memory.wat">memory.wat</a>.</p> + </li> + <li> + <p>Retournez à votre fichier <code>memory.html</code>, et récupérez, compilez, et instancier votre module wasm comme précédement — Ajoutez à la fin de votre script les lignes suivantes:</p> + + <pre><code>WebAssembly.instantiateStreaming(fetch('memory.wasm'), { js: { mem: memory } }) +.then(results => { + // add code here +});</code></pre> + </li> + <li> + <p>Puisque ce module exporte sa mémoire, nous pouvons utiliser la fonction exportée <code>accumulate()</code> à partir du champ instance (de type Instance) de la valeur de retour results du module pour créer et alimenter l'instance mémoire du module (<code>mem</code>) avec un tableau. Ajoutez les lignes suivantes à votre code à l'emplacement indiqué dans le snippet précédent.</p> + + <pre><code>var i32 = new Uint32Array(memory.buffer); + +for (var i = 0; i < 10; i++) { + i32[i] = i; +} + +var sum = results.instance.exports.accumulate(0, 10); +console.log(sum);</code></pre> + </li> +</ol> + +<p>Note: vous pouvez remarquer que nous avons créé la vue {{domxref("Uint32Array")}} sur le champ buffer de l'objet Memory (<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory/buffer">Memory.prototype.buffer</a></code>), et pas sur l'objet Memory lui même.</p> + +<p>Les imports Memory fonctionnent de la même manière que les imports fonctions, à la différence prés que les objets Memory véhiculent des valeurs au lieu de fonctions Javscripts. Les imports Memory sont utiles pour deux raisons:</p> + +<ul> + <li>Ils permettent de récupérer et créer le contenu mémoire initial avant ou en parrallèle de la compilation du module.</li> + <li>Ils permettent qu'un objet mémoire unique soit importé par des instances de modules multiples, ce qui est une fonctionnalité clef dans l'objectif d'une implémentation d'une connexion dynamique dans WebAssembly.</li> +</ul> + +<p><strong>Note</strong>: Vous pouvez trouver une démo complete à <a href="https://github.com/mdn/webassembly-examples/blob/master/js-api-examples/memory.html">memory.html</a> (à voir également <a href="https://mdn.github.io/webassembly-examples/js-api-examples/memory.html">live</a>) .</p> + +<h2 id="Tables">Tables</h2> + +<p>Une Table WebAssembly est un tableau de <a href="https://en.wikipedia.org/wiki/Reference_(computer_science)">références</a> typées redimensionnable qui peut être accédé à la fois par du code Javscript et par du code WebAssembly. Memory fournit un tableau de bytes bruts redimensionnable, mais il n'est pas prudent d'y stocker des références, car une référence est une valeur considérée comme sûre par le moteur Javascript, valeur dont les bytes ne doivent être accessibles ni en lecture, ni en écriture par le contenu pour des raisons de sécurité, de portabilité, et de stabilité.</p> + +<p>Les Tables possèdent un type, qui limite les types de références qui peuvent être contenues dans la table. Dans la version actuelle de WebAssembly, il n'existe qu'un seul type de références — functions — et de fait seul ce type de références est donc valide. Dans de prochaines versions, d'autres types de références seront ajoutés. </p> + +<p>Les références de type fonction sont nécessaires afin de compiler des languages comme C/C++ qui permettent l'implémentation de pointeurs sur fonctions. Dans une implémentation native en C/C++, un pointeur sur fonction est représenté par une adresse brute associée au code de la fonction contenue dans l'espace d'adressage virtuel du processus. Pour les raisons de sécurités mentionnées plus haut, cette référence dans WebAssembly ne peut être stockée directement en mémoire linéaire. Les références de fonctions sont stockées dans une table et leurs index, qui sont des entiers, peuvent être placés en mémoire linéaire et véhiculés de manière sûre. </p> + +<p>Lorsque l'appel à un pointeur sur fonction est nécessaire, le caller WebAssembly fournit l'index de la référence à appeler. La valeur de cet index est controlée par rapport au valeurs limites données à l'instantiation de la table (safety bounds checked), et cela avant que l'appel par référence à la fonction soit effectué. Autrement dit, les tables sont actuellement des primitives bas niveau utilisées pour compiler des fonctionnalités de language de programmation bas niveau, de manière sûre et portable.</p> + +<p>Les Tables peuvent être modifiées via <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Table/set">Table.prototype.set()</a></code>, which updates one of the values in a table, and <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Table/grow">Table.prototype.grow()</a></code>, which increases the number of values that can be stored in a table. This allows the indirectly-callable set of functions to change over time, which is necessary for <a href="http://webassembly.org/docs/dynamic-linking/">dynamic linking techniques</a>. The mutations are immediately accessible via <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Table/get">Table.prototype.get()</a></code> in JavaScript, and to wasm modules.</p> + +<h3 id="Un_exemple_de_table">Un exemple de table</h3> + +<p>Envisageons un exemple basique d'utilisation d'une table — un module WebAssembly qui crée et exporte une table contenant 2 éléments: l'élement 0 retourne 13 et l'élément 1 retourne 42. Vous retrouvez cela dans le fichier <a href="https://github.com/mdn/webassembly-examples/raw/master/js-api-examples/table.wasm">table.wasm</a>.</p> + +<ol> + <li> + <p>Faites une copie locale de <code>table.wasm</code> dans un nouveau dossier.</p> + + <p><strong>Note</strong>: vous pouvez voir une réprésentation textuelle du module sur <a href="https://github.com/mdn/webassembly-examples/blob/master/js-api-examples/table.wat">table.wat</a>.</p> + </li> + <li> + <p>Créez une nouvelle copie du template <a href="https://github.com/mdn/webassembly-examples/blob/master/template/template.html">HTML</a> dans le même dossier et nommez le <code>table.html</code>.</p> + </li> + <li> + <p>Comme précédement, récupérez, compilez, et instanciez le module wasm — ajoutez les lignes suivantes à l'intérieur d'un élement {{htmlelement("script")}} au bas du body html:</p> + + <pre><code>WebAssembly.instantiateStreaming(fetch('table.wasm')) +.then(function(results) { + // add code here +});</code></pre> + </li> + <li> + <p>Maintenant accédez aux données contenues dans la table — ajoutez les lignes suivantes dans votre code à la place indiquée dans le snippet précédent:</p> + + <pre><code>var tbl = results.instance.exports.tbl; +console.log(tbl.get(0)()); // 13 +console.log(tbl.get(1)()); // 42</code></pre> + </li> +</ol> + +<p>Ce code accède à chaque fonction référencée contenue dans la table, et l' instancie afin d'imprimer sa valeur de retour dans la console — à noter que chaque référence de fonction est obtenue à l'aide de la méthode <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Table/get">Table.prototype.get()</a></code>, suivie d'une paire suplémentaire de parenthèses pour finaliser l'invocation de la fonction.</p> + +<p><strong>Note</strong>: Vous pouvez retoruver la démo complète sur <a href="https://github.com/mdn/webassembly-examples/blob/master/js-api-examples/table.html">table.html</a> (voir également <a href="https://mdn.github.io/webassembly-examples/js-api-examples/table.html">live</a>).</p> + +<h2 id="Globals">Globals</h2> + +<p>WebAssembly fournit la capacité de créer des instances de variables globales, depuis Javascript et importable/exportable à partir d'une ou plusieurs instances de {{jsxref("WebAssembly.Module")}}. C'est très utile, car cela rend possible la mise en place d'un lien dynamique entre de multiple modules WebAssembly. </p> + +<p>Pour créer une instance globale WebAssembly à partir de Javascript, vous pouvez utiliser le constructeur {{jsxref("WebAssembly.Global()")}}, de la manière suivante:</p> + +<pre><code>const global = new WebAssembly.Global({value:'i32', mutable:true}, 0);</code></pre> + +<p>Vous pouvez remarquer que ce constructeur prend deux paramètres:</p> + +<ul> + <li>Un objet qui comprend deux propriétés décrivant la variable globale: + <ul> + <li><code>value</code>: correspond au type de donnée de la variable globale instanciée. Type de donnée qui peut être n'importe quel type compatible avec les modules WebAssembly modules — <code>i32</code>, <code>i64</code>, <code>f32</code>, ou <code>f64</code>.</li> + <li><code>mutable</code>: un booléen definissant si la valeur est "mutable" ou non.</li> + </ul> + </li> + <li>Une valeur correspondant à la valeur prise par la variable. Cela peut être n'importe quelle valeur à condition qu'elle soit compatible avec le type de donnée spécifié.</li> +</ul> + +<p>Finalement comment tout cela fonctionne? Dans l'exemple suivant nous définissons une variable globale "mutable" de type <code>i32</code>, avec une valeur de 0.</p> + +<p>La valeur de la variable globale est ensuite changée en <code>42</code> en utilisant la propriété <code>Global.value</code>, puis en <code>43</code> en utilisant cette fois la fonction exportée de l'instance du module global.wasm <code>incGlobal()</code> (cette fonction ajoute 1 à la valeur qui lui est donnée et retourne la nouvelle valeur).</p> + +<pre><code>const output = document.getElementById('output'); + +function assertEq(msg, got, expected) { + output.innerHTML += `Testing ${msg}: `; + if (got !== expected) + output.innerHTML += `FAIL!<br>Got: ${got}<br>Expected: ${expected}<br>`; + else + output.innerHTML += `SUCCESS! Got: ${got}<br>`; +} + +assertEq("WebAssembly.Global exists", typeof WebAssembly.Global, "function"); + +const global = new WebAssembly.Global({value:'i32', mutable:true}, 0); + +WebAssembly.instantiateStreaming(fetch('global.wasm'), { js: { global } }) +.then(({instance}) => { + assertEq("getting initial value from wasm", instance.exports.getGlobal(), 0); + global.value = 42; + assertEq("getting JS-updated value from wasm", instance.exports.getGlobal(), 42); + instance.exports.incGlobal(); + assertEq("getting wasm-updated value from JS", global.value, 43); +});</code></pre> + +<p><strong>Note</strong>: Vous pouvez voir cet exemple en <a href="https://mdn.github.io/webassembly-examples/js-api-examples/global.html">live sur GitHub</a>; voir également le code <a href="https://github.com/mdn/webassembly-examples/blob/master/js-api-examples/global.html">source</a>.</p> + +<h2 id="Multiplicité">Multiplicité</h2> + +<p>Maintenant que nous avons présenté l'utilisation des principaux composants de WebAssembly, il est temps de dire quelques mots sur le concept de multiplicité. Ce dernier donne à WebAssembly un certains nombre d'avantages en terme d'efficience architecturale:</p> + +<ul> + <li>Un seul et unique module peut avoir N instances, de la même manière qu'une fonction littérale peut fournir N valeurs de closure.</li> + <li>Une seule et unique instance de module peut utiliser 0-1 instance de mémoire, qui elles-mêmes fournissent "l'espace d'adressage" de l'instance. Les versions futures de WebAssembly pourraient autoriser 0-N instances de mémoire par module instancié (voir <a href="http://webassembly.org/docs/future-features/#multiple-tables-and-memories">Multiple Tables and Memories</a>).</li> + <li>Une seule et unique instance de module peut utiliser 0-1 instance de tables — cela constitue "l'espace d'adressage de fonction" de l'instance, utilisé pour des pointeurs de fonction de type C. Des versions futures de WebAssembly pourraient autoriser 0–N instance de table par module instancié.</li> + <li>Une instance mémoire ou table peut être utilisée par 0-N instances de module — ces instances partagent toutes le même espace d'adressage, rendant possible l'implémentation d'un lien dynamique.</li> +</ul> + +<p>Vous pouvez voir la mise en application du concept de multiplicité dans notre article Understanding text format — voir en particulier la section <a href="https://developer.mozilla.org/en-US/docs/WebAssembly/Understanding_the_text_format#Mutating_tables_and_dynamic_linking">Mutating tables and dynamic linking</a>.</p> + +<h2 id="Résumé">Résumé</h2> + +<p>Cet article a couvert les bases de l'utilisation de l'API WebAssembly Javascript nécessaires à l'inclusion d'un module WebAssembly dans un contexte javascript, afin d'utiliser les fonctions du module dans ce contexte, et de se familiairiser avec la manipulation de la mémoire et des tables WebAssembly. Nous avons terminé en évoquant le concept de multiplicité.</p> + +<h2 id="A_voir_également">A voir également</h2> + +<ul> + <li><a href="http://webassembly.org/">webassembly.org</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/WebAssembly/Concepts">WebAssembly concepts</a></li> + <li><a href="https://research.mozilla.org/webassembly/">WebAssembly on Mozilla Research</a></li> +</ul> |