diff options
| -rw-r--r-- | files/fr/webassembly/c_to_wasm/index.md | 243 | ||||
| -rw-r--r-- | files/fr/webassembly/concepts/index.md | 146 | ||||
| -rw-r--r-- | files/fr/webassembly/exported_functions/index.md | 68 | ||||
| -rw-r--r-- | files/fr/webassembly/index.md | 168 | ||||
| -rw-r--r-- | files/fr/webassembly/loading_and_running/index.md | 104 | ||||
| -rw-r--r-- | files/fr/webassembly/using_the_javascript_api/index.md | 377 |
6 files changed, 506 insertions, 600 deletions
diff --git a/files/fr/webassembly/c_to_wasm/index.md b/files/fr/webassembly/c_to_wasm/index.md index b55618c1de..2353bba4b4 100644 --- a/files/fr/webassembly/c_to_wasm/index.md +++ b/files/fr/webassembly/c_to_wasm/index.md @@ -10,178 +10,159 @@ tags: - wasm translation_of: WebAssembly/C_to_wasm --- -<div>{{WebAssemblySidebar}}</div> +{{WebAssemblySidebar}} -<p>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="/fr/docs/Mozilla/Projects/Emscripten">Emscripten</a>. Regardons comment cela fonctionne.</p> +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 [Emscripten](/fr/docs/Mozilla/Projects/Emscripten). Regardons comment cela fonctionne. -<h2 id="Mise_en_place_de_lenvironnement_Emscripten">Mise en place de l'environnement Emscripten</h2> +## Mise en place de l'environnement Emscripten -<p>D'abord, mettons en place l'environnement requis pour le développement.</p> +D'abord, mettons en place l'environnement requis pour le développement. -<h3 id="Prérequis">Prérequis</h3> +### Prérequis -<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> +Recuperer le SDK de Emscripten en utilisant les instructions suivantes: <https://kripken.github.io/emscripten-site/docs/getting_started/downloads.html> -<h2 id="Compiler_un_exemple">Compiler un exemple</h2> +## Compiler un exemple -<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> +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: -<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> +- 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. +- Compiler vers du wasm et juste créer le Javascript. -<p>Nous verrons les deux par la suite.</p> +Nous verrons les deux par la suite. -<h3 id="Créer_le_document_HTML_et_la_glue_JavaScript">Créer le document HTML et la "glue" JavaScript</h3> +### Créer le document HTML et la "glue" JavaScript -<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> +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. -<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: +1. D'abord nous avons besoin d'un exemple à compiler. Prenez une copie du simple programme C suivant et sauvez-le dans un fichier nommé `hello.c` dans un nouveau répertoire de votre disque dur: - <pre class="brush: cpp">#include <stdio.h> + ```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> + int main(int argc, char ** argv) { + printf("Hello World\n"); + } + ``` -<p>Les options passées avec la commande sont les suivantes :</p> +2. 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 `hello.c` et exécutez la commande suivante : -<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> + ```bash + emcc hello.c -s WASM=1 -o hello.html + ``` -<p>À ce stade votre dossier source devrait contenir :</p> +Les options passées avec la commande sont les suivantes : -<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> +- `-s WASM=1` — Spécifie que nous voulons du wasm en sortie. Si nous ne spécifions pas cela, Emscripten générera juste en sortie du [asm.js](http://asmjs.org/) comme il le fait par défaut. +- `-o hello.html` — 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. -<h3 id="Exécuter_votre_exemple">Exécuter votre exemple</h3> +À ce stade votre dossier source devrait contenir : -<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> +- Un fichier de code binaire wasm (`hello.wasm`) +- Un fichier JavaScript contenant du code "glue" à traduire entre les fonctions natives C, et Java/wasm (`hello.js`) +- Un fichier HTML pour charger, compiler et instancier votre code wasm, et l'afficher dans votre navigateur (`hello.html`) -<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> +### Exécuter votre exemple -<h3 id="Utiliser_un_template_HTML_personnalisé">Utiliser un template HTML personnalisé</h3> +Maintenant, tout ce qui vous reste à faire est de charger le fichier `hello.html` 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 `javascript.options.wasm` dans *about:config*, ou dans Chrome (51+) et Opera (38+) en allant dans *chrome://flags* and en activant le flag *Experimental WebAssembly*.) -<p>Vous souhaiterez parfois utiliser un template HTML personnalisé. Voyons comment faire :</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! -<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> +### Utiliser un template HTML personnalisé - <pre class="brush: cpp">#include <stdio.h> +Vous souhaiterez parfois utiliser un template HTML personnalisé. Voyons comment faire : -int main(int argc, char ** argv) { - printf("Hello World\n"); +1. Tout d'abord, sauvegarder le code C suivant dans un fichier nommé `hello2.c`, au sein d'un nouveau dossier (vide) : -}</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> + ```cpp + #include <stdio.h> - <pre class="brush: bash">emcc -o hello2.html hello2.c -O3 -s WASM=1 --shell-file html_template/shell_minimal.html</pre> + int main(int argc, char ** argv) { + printf("Hello World\n"); - <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> +2. Cherchez le fichier `shell_minimal.html` dans le dépôt emsdk. Copiez-le dans un sous-dossier nommé `html_template` dans votre précédent nouveau dossier. +3. Naviguez maintenant jusqu'au nouveau dossier (toujours dans votre terminal disposant de l'environnement Emscripten), et exécutez la commande suivante : -<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> + ```bash + emcc -o hello2.html hello2.c -O3 -s WASM=1 --shell-file html_template/shell_minimal.html + ``` -<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> + Les options que nous avons donné sont un peu différentes cette fois : -<h3 id="Appeler_une_fonction_personnalisée_définie_en_C">Appeler une fonction personnalisée définie en C</h3> + - Nous avons spécifié `-o hello2.html`, ce qui signifie que le compilateur va générer du code JavaScript "glue" ainsi qu'un `.html`. + - Nous avons également spécifié `--shell-file html_template/shell_minimal.html` — 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. -<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> +4. 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. -<ol> - <li> - <p>Pour démarrer, sauvegardez le code suivante dans un fichier nommé <code>hello3.c</code> dans un nouveau répertoire:</p> +> **Note :** 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`-o` . Par exemple: `emcc -o hello2.js hello2.c -O3 -s WASM=1`. 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. +> +> \* 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. - <pre class="brush: cpp">#include <stdio.h> -#include <emscripten/emscripten.h> +### Appeler une fonction personnalisée définie en C -int main(int argc, char ** argv) { - printf("Hello World\n"); -} +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 `ccall()` et la déclaration `EMSCRIPTEN_KEEPALIVE` (qui ajoute vos fonctions dans la liste des fonctions exportées) . Voir [Why do functions in my C/C++ source code vanish when I compile to JavaScript, and/or I get No functions to process?](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). Regardons comment cela fonctionne. -#ifdef __cplusplus -extern "C" { -#endif +1. Pour démarrer, sauvegardez le code suivante dans un fichier nommé `hello3.c` dans un nouveau répertoire: -void EMSCRIPTEN_KEEPALIVE myFunction(int argc, char ** argv) { - printf("MyFunction Called\n"); -} + ```cpp + #include <stdio.h> + #include <emscripten/emscripten.h> -#ifdef __cplusplus -} -#endif</pre> + int main(int argc, char ** argv) { + printf("Hello World\n"); + } - <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> + #ifdef __cplusplus + extern "C" { + #endif - <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> + void EMSCRIPTEN_KEEPALIVE myFunction(int argc, char ** argv) { + printf("MyFunction Called\n"); + } - <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> + #ifdef __cplusplus + } + #endif + ``` - <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> + By default, Emscripten-generated code always just calls the `main()` function, and other functions are eliminated as dead code. Putting `EMSCRIPTEN_KEEPALIVE` before a function name stops this from happening. You also need to import the `emscripten.h` library to use `EMSCRIPTEN_KEEPALIVE`. + + > **Note :** We are including the `#ifdef` 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++. + +2. Now add `html_template/shell_minimal.html` into this new directory too, just for convenience (you'd obviously put this in a central place in your real dev environment). +3. 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.) + + ```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"]' + ``` + +4. If you load the example in your browser again, you'll see the same thing as before! +5. Now we need to run our new `myFunction()` function from JavaScript. First of all, let's add a {{htmlelement("button")}} as shown below, just above the first opening `<script type='text/javascript'>` tag. + + ```html + <button class="mybutton">Run myFunction</button> + ``` + +6. Now add the following code inside the last {{htmlelement("script")}} element (just above the closing `</script>` tag): + + ```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 + }); + ``` + +This illustrates how `ccall()` is used to call the exported function. + +## Voir aussi + +- [emscripten.org](http://emscripten.org/) — pour en apprendre plus sur Emscripten et sa large palette d'options +- [Appeler des fonctions C compilées depuis JavaScript grâce à ccall/cwrap](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) +- [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" ?](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) +- [WebAssembly sur Mozilla Research](https://research.mozilla.org/webassembly/) diff --git a/files/fr/webassembly/concepts/index.md b/files/fr/webassembly/concepts/index.md index 2d770e0eea..6dc2801da0 100644 --- a/files/fr/webassembly/concepts/index.md +++ b/files/fr/webassembly/concepts/index.md @@ -3,133 +3,115 @@ title: Concepts de WebAssembly slug: WebAssembly/Concepts translation_of: WebAssembly/Concepts --- -<div>{{WebAssemblySidebar}}</div> +{{WebAssemblySidebar}} -<p>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> +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. -<h2 id="Quest-ce_que_WebAssembly">Qu'est-ce que WebAssembly ?</h2> +## Qu'est-ce que WebAssembly ? -<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> +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>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> +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>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> +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. -<h2 id="Objectifs_de_WebAssembly">Objectifs de WebAssembly</h2> +## Objectifs de WebAssembly -<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> +WebAssembly est en cours de création en tant que standard ouvert au sein du [W3C WebAssembly Community Group](https://www.w3.org/community/webassembly/) avec les objectif suivants : -<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> +- Être rapide, efficace et portable — Le code WebAssembly peut être exécuté à une vitesse proche du natif sur plusieurs plateformes en profitant des [capacités matérielles communes](http://webassembly.org/docs/portability/#assumptions-for-efficient-execution). +- Ê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. +- 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. +- Ne pas casser le web — WebAssembly est conçu de manière à facilement s'associer aux autres technologies web et à maintenir une rétrocompatibilité. -<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> +> **Note :** WebAssembly aura également des usages en dehors du web et des environnements JavaScript (voir [Non-web embeddings](http://webassembly.org/docs/non-web/)). -<h2 id="Comment_WebAssembly_sintègre_dans_la_plateforme_web">Comment WebAssembly s'intègre dans la plateforme web ?</h2> +## Comment WebAssembly s'intègre dans la plateforme web ? -<p>La plateforme web peut s'imaginer comme composée de deux parties :</p> +La plateforme web peut s'imaginer comme composée de deux parties : -<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="/fr/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="/fr/docs/Web/API/Document_Object_Model">DOM</a>, <a href="/fr/docs/Web/API/CSS_Object_Model">CSSOM</a>, <a href="/fr/docs/Web/API/WebGL_API">WebGL</a>, <a href="/fr/docs/Web/API/IndexedDB_API">IndexedDB</a>, <a href="/fr/docs/Web/API/Web_Audio_API">Web Audio API</a>, etc.).</li> -</ul> +- Une machine virtuelle (VM) qui exécute le code de la Web app, e.g le code JavaScript qui fait tourner vos applications. +- Une ensemble de [Web APIs](/fr/docs/Web/API) que la Web app peut appeler pour contrôler les fonctionnalités des navigateurs/appareils et réaliser des actions ([DOM](/fr/docs/Web/API/Document_Object_Model), [CSSOM](/fr/docs/Web/API/CSS_Object_Model), [WebGL](/fr/docs/Web/API/WebGL_API), [IndexedDB](/fr/docs/Web/API/IndexedDB_API), [Web Audio API](/fr/docs/Web/API/Web_Audio_API), etc.). -<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> +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 [Cas d'utilisations WebAssembly](http://webassembly.org/docs/use-cases/) pour plus d'informations). -<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> +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>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> +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 : -<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> +- 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. +- 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 [priorité](http://webassembly.org/docs/high-level-goals/) de WebAssembly est de supporter les langages avec modèles de mémoire à garbage-collector dans le futur.) -<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> +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>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> +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. -<h3 id="Les_concepts_clefs_du_WebAssembly">Les concepts clefs du WebAssembly </h3> +### Les concepts clefs du WebAssembly -<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> +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. -<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="/fr/docs/Web/API/Blob">Blob</a> - peut donc être explicitement<a href="/fr/WebAssembly/Caching_modules"> mis en cache dans IndexedDB</a> ou partagé entre le contexte fenêtre et les workers (via <code><a href="/fr/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> +- **Module** : Représente un binaire WebAssembly qui a été compilé en code exécutable par le navigateur. Un module est sans état et - comme un [Blob](/fr/docs/Web/API/Blob) - peut donc être explicitement[ mis en cache dans IndexedDB](/fr/WebAssembly/Caching_modules) ou partagé entre le contexte fenêtre et les workers (via [`postMessage()`](/fr/docs/Web/API/MessagePort/postMessage)). Un module déclare des imports et exports au même titre qu'un module ES2015. +- **Mémoire** : 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. +- **Table** : 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é). +- **Instance** : 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. -<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> +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>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> +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>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> +Dans le futur, les modules WebAssembly seront chargeables comme des module ES2015 (en utilisant `<script type='module'>`), ce qui veut dire que JavaScript sera capable de récupérer, compiler et importer un module WebAssembly aussi facilement qu'un module ES2015. -<h2 id="Comment_utiliser_WebAssembly_dans_son_applicatif">Comment utiliser WebAssembly dans son applicatif ?</h2> +## Comment utiliser WebAssembly dans son applicatif ? -<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> +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>L'écosystème WebAssembly est à un stade embryonnaire ;</p> +L'écosystème WebAssembly est à un stade embryonnaire ; -<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> +D'autres outils verront sans aucun doute le jour à l'avenir. Pour le moment, il y a trois points d'entrée principaux : -<ul> - <li>Porter une application C/C++ avec <a href="/fr/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> +- Porter une application C/C++ avec [Emscripten](/fr/docs/Mozilla/Projects/Emscripten). +- Écrire ou générer WebAssembly directement au niveau assembleur. +- Écrire une application Rust et cibler WebAssembly en sortie. -<p>Parlons de ces options :</p> +Parlons de ces options : -<h3 id="Portage_depuis_le_CC">Portage depuis le C/C++</h3> +### Portage depuis le C/C++ -<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> +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><img alt="" src="emscripten-diagram.png"></p> + -<p>En résumé, le principe de fonctionnement est le suivant :</p> +En résumé, le principe de fonctionnement est le suivant : -<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> +1. 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++. +2. Emscripten transforme ensuite le résultat compilé par clang+LLVM en binaire .wasm. +3. 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. -<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> +> **Note :** Il existe des propositions future pour [ permettre au WebAssembly d'appeler directement l'API Web](http://webassembly.org/docs/gc/). -<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> +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 [SDL](https://en.wikipedia.org/wiki/Simple_DirectMedia_Layer), [OpenGL](https://en.wikipedia.org/wiki/OpenGL), [OpenAL](https://en.wikipedia.org/wiki/OpenAL), et une partie de [POSIX](https://en.wikipedia.org/wiki/POSIX). 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>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> +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>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> +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>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="/fr/docs/WebAssembly/C_to_wasm">Compiler du C/C++ en WebAssembly</a>.</p> +Vous pouvez trouver toute la documentation sur Emscripten à l'adresse [emscripten.org](http://emscripten.org), et un guide pour exploiter la chaîne de compilation et ainsi compiler votre propre application C/C++ en wasm à l'adresse [Compiler du C/C++ en WebAssembly](/fr/docs/WebAssembly/C_to_wasm). -<h3 id="Écrire_du_WebAssembly_directement">Écrire du WebAssembly directement</h3> +### Écrire du WebAssembly directement -<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> +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>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> +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 [outils de conversion texte vers binaire WebAssembly](http://webassembly.org/getting-started/advanced-tools/). -<p>Pour un guide simple sur comment réaliser ceci, regarder notre article <a href="/fr/docs/WebAssembly/Text_format_to_wasm">Convertir le WebAssembly au format text en wasm</a>.</p> +Pour un guide simple sur comment réaliser ceci, regarder notre article [Convertir le WebAssembly au format text en wasm](/fr/docs/WebAssembly/Text_format_to_wasm). -<h2 id="En_résumé">En résumé</h2> +## En résumé -<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> +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. -<h2 id="Voir_aussi">Voir aussi</h2> +## Voir aussi -<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="/fr/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="/fr/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> +- [WebAssembly articles on Mozilla Hacks blog](https://hacks.mozilla.org/category/webassembly/) +- [WebAssembly on Mozilla Research](https://research.mozilla.org/webassembly/) +- [Loading and running WebAssembly code](/fr/docs/WebAssembly/Loading_and_running)— trouvez comment charger votre propre module WebAssembly dans une page web. +- [Using the WebAssembly JavaScript API](/fr/docs/WebAssembly/Using_the_JavaScript_API) — trouvez comment utiliser les autres fonctionnalités majeures de l'API JavaScript WebAssembly. diff --git a/files/fr/webassembly/exported_functions/index.md b/files/fr/webassembly/exported_functions/index.md index 94bf4140b5..924153d611 100644 --- a/files/fr/webassembly/exported_functions/index.md +++ b/files/fr/webassembly/exported_functions/index.md @@ -3,31 +3,30 @@ title: Exported WebAssembly functions slug: WebAssembly/Exported_functions translation_of: WebAssembly/Exported_functions --- -<div>{{WebAssemblySidebar}}</div> +{{WebAssemblySidebar}} -<p>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> +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... -<h2 id="Exportée..._quoi">Exportée... quoi?</h2> +## Exportée... quoi? -<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> +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 `numbers` en `Int32`), 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>Vous pouvez exporter les fonctions WebAssembly de deux manières:</p> +Vous pouvez exporter les fonctions WebAssembly de deux manières: -<ul> - <li>Par un appel à <code><a href="/fr/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="/fr/docs/WebAssembly/API/Instance/exports">Instance.exports</a></code>.</li> -</ul> +- Par un appel à [`Table.prototype.get()`](/fr/docs/WebAssembly/API/Table/get) sur une table existante. +- Par un appel à une fonction exportée à partir de l'instance d'un module wasm via [`Instance.exports`](/fr/docs/WebAssembly/API/Instance/exports). -<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> +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. -<h2 id="Un_exemple">Un exemple</h2> +## Un exemple -<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> +Regardons un exemple pour mettre les choses au clair (tu peux le trouver sur GitHub sur [table-set.html](https://github.com/mdn/webassembly-examples/blob/master/other-examples/table-set.html); à voir également en [live ](https://mdn.github.io/webassembly-examples/other-examples/table-set.html), et check la [representation](https://github.com/mdn/webassembly-examples/blob/master/js-api-examples/table.wat) textuelle wasm): -<pre class="brush: js">var otherTable = new WebAssembly.Table({ element: "anyfunc", initial: 2 }); +```js +var otherTable = new WebAssembly.Table({ element: "anyfunc", initial: 2 }); WebAssembly.instantiateStreaming(fetch('table.wasm')) -.then(obj => { +.then(obj => { var tbl = obj.instance.exports.tbl; console.log(tbl.get(0)()); // 13 console.log(tbl.get(1)()); // 42 @@ -35,35 +34,38 @@ WebAssembly.instantiateStreaming(fetch('table.wasm')) 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> +Dans cet exemple, nous créons une table (`otherTable`) à 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>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="/fr/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> +Nous pouvons ensuite accéder aux fonctions exportées à partir du module, récupérer les références de chaque fonction via [`tbl.get()`](/fr/docs/WebAssembly/API/Table/get) et logguer le résultat de chacune d'elles dans la console. Enfin, nous utilisons `set()` avec la table `otherTable` afin de lui fournir les references aux mêmes functions que la table `tbl`. -<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> +Pour vérifier que cela à fonctionné correctement, nous récupérons les références de la table `otherTable` et imprimons également les résultats dans la console, et les résultats sont identiques aux précédents. -<h2 id="Des_fonctions_à_part_entière">Des fonctions à part entière</h2> +## Des fonctions à part entière -<p>Dans l'exemple précédent, la valeur de retour de chaque appel à <code><a href="/fr/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> +Dans l'exemple précédent, la valeur de retour de chaque appel à [`Table.prototype.get()`](/fr/docs/WebAssembly/API/Table/get) est une fonction WebAssembly exportée — exactement ce dont nous avons parlé jusqu'à maintenant. -<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> +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: -<pre class="brush: js">var testFunc = otherTable.get(0); -typeof testFunc;</pre> +```js +var testFunc = otherTable.get(0); +typeof testFunc; +``` -<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="/fr/docs/Web/JavaScript/Reference/Global_Objects/Function/call">call()</a></code>, <code><a href="/fr/docs/Web/JavaScript/Reference/Global_Objects/Function/bind">bind()</a></code>, etc. <code>testFunc.toString()</code> retourne un résultat intéressant:</p> +Vous obtiendrez le résultat `function` en valeur de retour. Cette fonction peut effectuer tout ce qu'une fonction Javascript classique peut effectuer — [`call()`](/fr/docs/Web/JavaScript/Reference/Global_Objects/Function/call), [`bind()`](/fr/docs/Web/JavaScript/Reference/Global_Objects/Function/bind), etc. `testFunc.toString()` retourne un résultat intéressant: -<pre class="brush: js">function 0() { +```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> +Cela vous donne une idée plus précise de la nature de l'emballage (wrapper-type). -<p>Some other particulars to be aware of with exported WebAssembly functions:</p> +Some other particulars to be aware of with exported WebAssembly functions: -<ul> - <li>Their <a href="/fr/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="/fr/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> +- Their [length](/fr/docs/Web/JavaScript/Reference/Global_Objects/Function/length) property is the number of declared arguments in the wasm function signature. +- Their [name](/fr/docs/Web/JavaScript/Reference/Global_Objects/Function/name) property is the `toString()` result of the function's index in the wasm module. +- 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. diff --git a/files/fr/webassembly/index.md b/files/fr/webassembly/index.md index 02b351d7b9..18784dcd32 100644 --- a/files/fr/webassembly/index.md +++ b/files/fr/webassembly/index.md @@ -7,98 +7,76 @@ tags: - wasm translation_of: WebAssembly --- -<div>{{WebAssemblySidebar}}{{SeeCompatTable}}</div> - -<p>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 id="En_résumé">En résumé</h2> - -<p>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>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>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> - -<h2 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> - -<h2 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> - - -<h2 id="Exemples">Exemples</h2> - -<ul> - <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> - -<p>{{Compat("javascript.builtins.WebAssembly")}}</p> - -<h2 id="Voir_aussi">Voir aussi</h2> - -<ul> - <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> +{{WebAssemblySidebar}}{{SeeCompatTable}} + +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. + +## En résumé + +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. + +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. + +WebAssembly est conçu comme un standard web par le [groupe communautaire du W3C pour WebAssembly](https://www.w3.org/community/webassembly/) auquel participe les différents éditeurs de navigateur. + +## Guides + +- [Les concepts de WebAssembly](/fr/docs/WebAssembly/Concepts) + - : Découvrez les concepts clés de WebAssembly : ce que c'est, son utilité, l'intégration dans le Web et comment l'utiliser. +- [Compiler du code C/C++ en WebAssembly](/fr/docs/WebAssembly/C_to_wasm) + - : Du code écrit en C/C++ peut être compilé en WebAssembly grâce à des outils tels que [Emscripten](/fr/docs/Mozilla/Projects/Emscripten). Nous voyons ici comment cela fonctionne. +- [Charger et exécuter du code WebAssembly](/fr/docs/WebAssembly/Loading_and_running) + - : Dans cet article, on aborde comment récupérer, compiler et instancier en associant l'API [WebAssembly JavaScript](/fr/docs/Web/JavaScript/Reference/Objets_globaux/WebAssembly) avec les API [Fetch](/fr/docs/Web/API/Fetch_API) ou [XHR](/fr/docs/Web/API/XMLHttpRequest). +- [Mettre en cache des modules WebAssembly compilés](/fr/docs/WebAssembly/Caching_modules) + - : 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 [IndexedDB](/fr/docs/Web/API/IndexedDB_API) pour cela. +- [Utiliser l'API JavaScript de WebAssembly](/fr/docs/WebAssembly/Using_the_JavaScript_API) + - : 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. +- [Les fonctions WebAssembly exportées](/fr/docs/WebAssembly/Exported_functions) + - : 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. +- [Comprendre le format texte WebAssembly](/fr/docs/WebAssembly/Understanding_the_text_format) + - : 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. +- [Convertir un fichier texte WebAssembly en wasm](/fr/docs/WebAssembly/Text_format_to_wasm) + - : Cet article détaille comment convertir un module WebAssembly rédigé dans un format texte en un fichier binaire .wasm. + +## Référence de l'API JavaScript + +- {{jsxref("Objets_globaux/WebAssembly", "WebAssembly")}} + - : Cet objet représente l'espace de nom encapsulant les fonctionnalités relatives à WebAssembly. +- {{jsxref("Objets_globaux/WebAssembly/Module", "WebAssembly.Module")}} + - : Un objet `WebAssembly.Module` contient du code WebAssembly, sans état, qui a déjà été compilé par le navigateur et qui peut être [partagé dans les _web workers_](/fr/docs/Web/API/Worker/postMessage), [mis en cache dans IndexedDB](/fr/docs/WebAssembly/Caching_modules) et instancié à plusieurs reprises. +- {{jsxref("Objets_globaux/WebAssembly/Instance", "WebAssembly.Instance")}} + - : Un objet `WebAssembly.Instance` est une instance exécutable (disposant d'un état) d'un `Module`. Les objets `Instance` contiennent toutes les [fonctions WebAssembly exportées](/fr/docs/WebAssembly/Exported_functions) qui permettent d'utiliser du code WebAssembly via du code JavaScript. +- {{jsxref("Objets_globaux/WebAssembly/instantiate", "WebAssembly.instantiate()")}} + - : La fonction `WebAssembly.instantiate()` représente l'API principale pour compiler et instancier le code WebAssembly. Cette méthode renvoie un `Module` ainsi que sa première `Instance`. +- {{jsxref("Objets_globaux/WebAssembly/Memory", "WebAssembly.Memory()")}} + - : Un objet ` WebAssembly.``Memory ` est un tableau {{jsxref("Objets_globaux/ArrayBuffer", "ArrayBuffer")}} redimensionnable qui contient les octets de mémoire brute auxquels on peut accéder via une `Instance`. +- {{jsxref("Objets_globaux/WebAssembly/Table", "WebAssembly.Table()")}} + - : Un objet ` WebAssembly.``Table ` est un tableau typé contenant des valeurs opaques et qui peut être redimensionné. On peut accéder aux valeurs via un objet `Instance`. +- {{jsxref("WebAssembly.CompileError()")}} + - : Crée un nouvel objet WebAssembly `CompileError`. +- {{jsxref("WebAssembly.LinkError()")}} + - : Crée un nouvel objet WebAssembly `LinkError`. +- {{jsxref("WebAssembly.RuntimeError()")}} + - : Crée un nouvel objet WebAssembly `RuntimeError`. + +## Exemples + +- [WASMSobel](https://github.com/JasonWeathersby/WASMSobel) +- Notre dépôt GitHub [webassembly-examples](https://github.com/mdn/webassembly-examples/) qui contient plusieurs exemples. + +## Spécifications + +| Spécification | État | Commentaires | +| ---------------------------------------- | ------------------------------------ | ------------------------------------------------------- | +| {{SpecName('WebAssembly JS')}} | {{Spec2('WebAssembly JS')}} | Brouillon de définition initiale pour l'API JavaScript. | + +## Compatibilité des navigateurs + +{{Compat("javascript.builtins.WebAssembly")}} + +## Voir aussi + +- [webassembly.org](http://webassembly.org/) +- [Les articles WebAssembly sur Mozilla Hacks](https://hacks.mozilla.org/category/webassembly/) ou sur [tech.mozfr.org en français](https://tech.mozfr.org/tag/WebAssembly) +- [Le groupe communautaire W3C sur WebAssembly](https://www.w3.org/community/webassembly/) +- [L'en-tête HTTP `Large-Allocation`](/fr/docs/Web/HTTP/Headers/Large-Allocation) diff --git a/files/fr/webassembly/loading_and_running/index.md b/files/fr/webassembly/loading_and_running/index.md index 2fd18151de..39e623ca37 100644 --- a/files/fr/webassembly/loading_and_running/index.md +++ b/files/fr/webassembly/loading_and_running/index.md @@ -3,66 +3,65 @@ title: Loading and running WebAssembly code slug: WebAssembly/Loading_and_running translation_of: WebAssembly/Loading_and_running --- -<div>{{WebAssemblySidebar}}</div> +{{WebAssemblySidebar}}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>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> +## Quelles sont les différentes options? -<h2 id="Quelles_sont_les_différentes_options">Quelles sont les différentes options?</h2> +Webassembly n'est pas encore intégré à `<script type='module'>` ou ES2015 `import`, autrement dit le navigateur ne peut pas récuperer les modules à l'aide de déclaration d'imports. -<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> +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 à `new Function(string)`, à la différence que dans notre cas, nous substituons une chaine de charactères par une chaine de bytes (le code source webassembly). -<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> +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>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> +Quelle est donc la démarche à suivre pour obtenir cet array buffer et le compiler ? La réponse dans les sections suivantes. -<p>Quelle est donc la démarche à suivre pour obtenir cet array buffer et le compiler ? La réponse dans les sections suivantes.</p> +## En utilisant Fetch -<h2 id="En_utilisant_Fetch">En utilisant Fetch</h2> +[Fetch](/fr/docs/Web/API/Fetch_API) est une API qui facilite la récupération de ressources sur le réseau. -<p><a href="/fr/docs/Web/API/Fetch_API">Fetch</a> est une API qui facilite la récupération de ressources sur le réseau.</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 `fetch()`, 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>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 => { +```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> +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: -<pre class="brush: js">fetch('module.wasm').then(response => +```js +fetch('module.wasm').then(response => response.arrayBuffer() -).then(bytes => +).then(bytes => WebAssembly.instantiate(bytes, importObject) -).then(results => { +).then(results => { // Do something with the results! -});</pre> - - +}); +``` -<h3 id="Aside_on_instantiate()_overloads">Aside on instantiate() overloads</h3> +### Aside on instantiate() overloads -<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> +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: -<pre class="brush: js">{ +```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="/fr/docs/Web/API/MessagePort/postMessage">postMessage()</a></code>, ou tout simplement pour créer d'autres instances.</p> -</div> +> **Note :** 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 [`postMessage()`](/fr/docs/Web/API/MessagePort/postMessage), ou tout simplement pour créer d'autres instances. -<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="/fr/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/instantiate#Second_overload_example">Second overload example</a>.</p> -</div> +> **Note :** 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 [Second overload example](/fr/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/instantiate#Second_overload_example). -<h3 id="Mise_en_marche_du_code_webassembly">Mise en marche du code webassembly</h3> +### Mise en marche du code webassembly -<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> +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: -<pre class="brush: js">WebAssembly.instantiateStreaming(fetch('myModule.wasm'), importObject) -.then(obj => { +```js +WebAssembly.instantiateStreaming(fetch('myModule.wasm'), importObject) +.then(obj => { // Call an exported function: obj.instance.exports.exported_func(); @@ -72,37 +71,34 @@ translation_of: WebAssembly/Loading_and_running // 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="/fr/docs/WebAssembly/Using_the_JavaScript_API">Using the WebAssembly JavaScript API</a>, et <a href="/fr/docs/WebAssembly/Understanding_the_text_format">Understanding WebAssembly text format</a>.</p> -</div> +> **Note :** Pour plus d'informations sur la façon dont fonctionne l'exportation au sein d'un module webassembly, lisez [Using the WebAssembly JavaScript API](/fr/docs/WebAssembly/Using_the_JavaScript_API), et [Understanding WebAssembly text format](/fr/docs/WebAssembly/Understanding_the_text_format). -<h2 id="En_utilisant_XMLHttpRequest">En utilisant XMLHttpRequest</h2> +## En utilisant XMLHttpRequest -<p><code><a href="/fr/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> +[`XMLHttpRequest`](/fr/docs/Web/API/XMLHttpRequest) est plus ancien que Fetch, mais peut toujours être utiliser afin récupérer un array buffer. En supposant que notre module se nome `simple.wasm`: -<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> +1. 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 `GET`, et y déclarer le chemin du fichier que nous souhaiter récupérer. +2. L'étape essentielle est içi de définir la réponse comme une réponse de type `'arraybuffer'` en utilisant la propriété {{domxref("XMLHttpRequest.responseType","responseType")}}. +3. Ensuite, la requête est envoyée à l'aide de la méthode {{domxref("XMLHttpRequest.send()")}}. +4. 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(). -<p>Le code final est le suivant:</p> +Le code final est le suivant: -<pre class="brush: js">request = new XMLHttpRequest(); +```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 => { + 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> +> **Note :** Vous pouvez retrouver un autre exemple sur [xhr-wasm.html](https://mdn.github.io/webassembly-examples/js-api-examples/xhr-wasm.html). diff --git a/files/fr/webassembly/using_the_javascript_api/index.md b/files/fr/webassembly/using_the_javascript_api/index.md index 7e200a4247..dc16c13041 100644 --- a/files/fr/webassembly/using_the_javascript_api/index.md +++ b/files/fr/webassembly/using_the_javascript_api/index.md @@ -3,290 +3,257 @@ title: Utiliser l'API JavaScript de WebAssembly slug: WebAssembly/Using_the_JavaScript_API translation_of: WebAssembly/Using_the_JavaScript_API --- -<div>{{WebAssemblySidebar}}</div> - -<p>Si vous avez déjà <a href="/fr/docs/WebAssembly/C_to_wasm">compilé un module depuis un autre langage en utilisant des outils comme Emscripten</a>, ou <a href="/fr/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="/fr/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="/fr/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> +{{WebAssemblySidebar}} + +Si vous avez déjà [compilé un module depuis un autre langage en utilisant des outils comme Emscripten](/fr/docs/WebAssembly/C_to_wasm), ou [chargé et éxecuté vous-même le code](/fr/docs/WebAssembly/Loading_and_running), 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. + +> **Note :** 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 [WebAssembly concepts](/fr/docs/WebAssembly/Concepts). + +## Quelques exemples simples + +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. + +> **Note :** Vous pouvez trouver des exemples de code dans notre repo GitHub [webassembly-examples](https://github.com/mdn/webassembly-examples). + +### Préparation + +1. Premièrement nous avons besoin d'un module wasm ! Récupérez notre fichier [simple.wasm](https://github.com/mdn/webassembly-examples/raw/master/js-api-examples/simple.wasm) et sauvegardez une copie dans un nouveau document sur votre machine locale. +2. Ensuite, assurez-vous d'utiliser un navigateur supportant WebAssembly. Firefox 52+ et Chrome 57+ supportent WebAssembly par défaut. +3. Pour poursuivre, créez un simple fichier nommé `index.html` dans le même dossier que votre fichier wasm (vous pouvez utiliser notre [template simple](https://github.com/mdn/webassembly-examples/blob/master/template/template.html) si vous n'en avez pas de facilement accessible). +4. Maintenant, pour nous aider à comprendre ce qui se passe ici, regardons la représentation textuelle de notre module wasm (que nous rencontrons aussi dans [Converting WebAssembly format to wasm](/fr/docs/WebAssembly/Text_format_to_wasm#A_first_look_at_the_text_format)): + + (module + (func $i (import "imports" "imported_func") (param i32)) + (func (export "exported_func") + i32.const 42 + call $i)) + +5. À la deuxième ligne, vous pouvez constater l'import d'un namespace à deux niveaux — la fonction interne `$i` est importée depuis `imports.imported_func`. 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 `<script></script>` dans votre fichier HTML, puis ajoutez le code suivant: -<h3 id="Streaming_de_notre_module_webassembly">Streaming de notre module webassembly</h3> + ```js + var importObject = { + imports: { + imported_func: function(arg) { + console.log(arg); + } + } + }; + ``` -<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> +### Streaming de notre module webassembly -<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> +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 `Module`/`Instance`, sans nécessiter la manipulation d'une réponse intermédiaire {{domxref("Response")}} en un {{domxref("ArrayBuffer")}}. -<p>Ajoutez le code suivant à votre script, en dessous du premier bloc:</p> +Cet exemple (voir notre démo sur GitHub [instantiate-streaming.html](https://github.com/mdn/webassembly-examples/blob/master/js-api-examples/instantiate-streaming.html), et également [view it live](https://mdn.github.io/webassembly-examples/js-api-examples/instantiate-streaming.html)) montre comment utiliser `instantiateStreaming()` 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. -<pre><code>WebAssembly.instantiateStreaming(fetch('simple.wasm'), importObject) -.then(obj => obj.instance.exports.exported_func());</code></pre> +Ajoutez le code suivant à votre script, en dessous du premier bloc: -<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> + WebAssembly.instantiateStreaming(fetch('simple.wasm'), importObject) + .then(obj => obj.instance.exports.exported_func()); -<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> +Le résultat net de l'ensemble du code est que l'appel à `exported_func`, notre fonction exportée Webassembly, entraîne à son tour l'appel à `imported_func` 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. -<h3 id="Chargement_de_notre_module_wasm_sans_streaming">Chargement de notre module wasm sans streaming</h3> +**Note**: 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>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> +### Chargement de notre module wasm sans streaming -<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> +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>Le code équivalent à l'exemple précédent prend la forme suivante:</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. -<pre><code>fetch('simple.wasm').then(response => - response.arrayBuffer() -).then(bytes => - WebAssembly.instantiate(bytes, importObject) -).then(results => { - results.instance.exports.exported_func(); -});</code></pre> +Le code équivalent à l'exemple précédent prend la forme suivante: -<h3 id="Visualiser_wasm_dans_loutil_de_développement">Visualiser wasm dans l'outil de développement </h3> + fetch('simple.wasm').then(response => + response.arrayBuffer() + ).then(bytes => + WebAssembly.instantiate(bytes, importObject) + ).then(results => { + results.instance.exports.exported_func(); + }); -<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> +### Visualiser wasm dans l'outil de développement -<p><img alt="" src="wasm-debug.png"></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>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> +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 [WebAssembly debugging with Firefox DevTools](https://www.youtube.com/watch?v=R1WtBkMeGds) for a video preview. -<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> +## Memory -<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> +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 [Linear Memory](http://webassembly.org/docs/semantics/#linear-memory). Cette mémoire linéaire est accessible en écriture et en lecture par des instructions [load et store ](http://webassembly.org/docs/semantics/#linear-memory-accesses)à 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>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> +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>Explorons ces concepts à travers un exemple rapide.</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. -<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> +Explorons ces concepts à travers un exemple rapide. - <pre><code>var memory = new WebAssembly.Memory({initial:10, maximum:100});</code></pre> +1. Créez une autre page HTML (copiez pour cela notre [simple template](https://github.com/mdn/webassembly-examples/blob/master/template/template.html)) et appelez la `memory.html`. Ajoutez un élement `<script></script>` à la page. +2. Maintenant ajoutez la ligne suivante en haut de votre script, afin de créer une instance mémoire: - <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> + var memory = new WebAssembly.Memory({initial:10, maximum:100}); - <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> + L'unité pour `initial` et `maximum` 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. - <pre><code>new Uint32Array(memory.buffer)[0] = 42;</code></pre> + 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>Vous pouvez retourner cette même valeur en utilisant:</p> + new Uint32Array(memory.buffer)[0] = 42; - <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> + Vous pouvez retourner cette même valeur en utilisant: -<h3 id="Redimensionner_la_mémoire">Redimensionner la mémoire</h3> + new Uint32Array(memory.buffer)[0] -<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> +3. À 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. -<pre><code>memory.grow(1);</code></pre> +### Redimensionner la mémoire -<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> +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>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> + memory.grow(1); -<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="/fr/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance/exports">Instance.prototype.exports</a></code>).</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. -<h3 id="Exemple_avancé_pour_lutilisation_mémoire">Exemple avancé pour l'utilisation mémoire</h3> +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>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> +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 `WebAssembly.Memory` afin de le passer en import à cette instance, soit en recevant un export Memory (via [`Instance.prototype.exports`](/fr/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance/exports)). -<ol> - <li> - <p>Faites une copie locale de <code>memory.wasm</code> dans le même dossier que précédement.</p> +### Exemple avancé pour l'utilisation mémoire - <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> +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 [memory.wasm.](https://github.com/mdn/webassembly-examples/raw/master/js-api-examples/memory.wasm) - <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> +1. Faites une copie locale de `memory.wasm` dans le même dossier que précédement. - <pre><code>var i32 = new Uint32Array(memory.buffer); + **Note**: Vous pouvez trouver la représentation textuelle du module sur [memory.wat](https://github.com/mdn/webassembly-examples/blob/master/js-api-examples/memory.wat). -for (var i = 0; i < 10; i++) { - i32[i] = i; -} +2. Retournez à votre fichier `memory.html`, et récupérez, compilez, et instancier votre module wasm comme précédement — Ajoutez à la fin de votre script les lignes suivantes: -var sum = results.instance.exports.accumulate(0, 10); -console.log(sum);</code></pre> - </li> -</ol> + WebAssembly.instantiateStreaming(fetch('memory.wasm'), { js: { mem: memory } }) + .then(results => { + // add code here + }); -<p>Note: vous pouvez remarquer que nous avons créé la vue {{domxref("Uint32Array")}} sur le champ buffer de l'objet Memory (<code><a href="/fr/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory/buffer">Memory.prototype.buffer</a></code>), et pas sur l'objet Memory lui même.</p> +3. Puisque ce module exporte sa mémoire, nous pouvons utiliser la fonction exportée `accumulate()` à 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 (`mem`) avec un tableau. Ajoutez les lignes suivantes à votre code à l'emplacement indiqué dans le snippet précédent. -<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> + var i32 = new Uint32Array(memory.buffer); -<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> + for (var i = 0; i < 10; i++) { + i32[i] = i; + } -<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> + var sum = results.instance.exports.accumulate(0, 10); + console.log(sum); -<h2 id="Tables">Tables</h2> +Note: vous pouvez remarquer que nous avons créé la vue {{domxref("Uint32Array")}} sur le champ buffer de l'objet Memory ([`Memory.prototype.buffer`](/fr/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory/buffer)), et pas sur l'objet Memory lui même. -<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> +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>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> +- Ils permettent de récupérer et créer le contenu mémoire initial avant ou en parrallèle de la compilation du module. +- 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. -<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> +**Note**: Vous pouvez trouver une démo complete à [memory.html](https://github.com/mdn/webassembly-examples/blob/master/js-api-examples/memory.html) (à voir également [live](https://mdn.github.io/webassembly-examples/js-api-examples/memory.html)) . -<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> +## Tables -<p>Les Tables peuvent être modifiées via <code><a href="/fr/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="/fr/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="/fr/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Table/get">Table.prototype.get()</a></code> in JavaScript, and to wasm modules.</p> +Une Table WebAssembly est un tableau de [références](<https://en.wikipedia.org/wiki/Reference_(computer_science)>) 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é. -<h3 id="Un_exemple_de_table">Un exemple de table</h3> +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>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> +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. -<ol> - <li> - <p>Faites une copie locale de <code>table.wasm</code> dans un nouveau dossier.</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><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> +Les Tables peuvent être modifiées via [`Table.prototype.set()`](/fr/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Table/set), which updates one of the values in a table, and [`Table.prototype.grow()`](/fr/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Table/grow), 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 [dynamic linking techniques](http://webassembly.org/docs/dynamic-linking/). The mutations are immediately accessible via [`Table.prototype.get()`](/fr/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Table/get) in JavaScript, and to wasm modules. - <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> +### Un exemple de table - <pre><code>var tbl = results.instance.exports.tbl; -console.log(tbl.get(0)()); // 13 -console.log(tbl.get(1)()); // 42</code></pre> - </li> -</ol> +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 [table.wasm](https://github.com/mdn/webassembly-examples/raw/master/js-api-examples/table.wasm). -<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="/fr/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> +1. Faites une copie locale de `table.wasm` dans un nouveau dossier. -<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> + **Note**: vous pouvez voir une réprésentation textuelle du module sur [table.wat](https://github.com/mdn/webassembly-examples/blob/master/js-api-examples/table.wat). -<h2 id="Globals">Globals</h2> +2. Créez une nouvelle copie du template [HTML](https://github.com/mdn/webassembly-examples/blob/master/template/template.html) dans le même dossier et nommez le `table.html`. +3. 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>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> + WebAssembly.instantiateStreaming(fetch('table.wasm')) + .then(function(results) { + // add code here + }); -<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> +4. 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: -<pre><code>const global = new WebAssembly.Global({value:'i32', mutable:true}, 0);</code></pre> + var tbl = results.instance.exports.tbl; + console.log(tbl.get(0)()); // 13 + console.log(tbl.get(1)()); // 42 -<p>Vous pouvez remarquer que ce constructeur prend deux paramètres:</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 [`Table.prototype.get()`](/fr/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Table/get), suivie d'une paire suplémentaire de parenthèses pour finaliser l'invocation de la fonction. -<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> +**Note**: Vous pouvez retoruver la démo complète sur [table.html](https://github.com/mdn/webassembly-examples/blob/master/js-api-examples/table.html) (voir également [live](https://mdn.github.io/webassembly-examples/js-api-examples/table.html)). -<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> +## Globals -<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> +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. -<pre><code>const output = document.getElementById('output'); +Pour créer une instance globale WebAssembly à partir de Javascript, vous pouvez utiliser le constructeur {{jsxref("WebAssembly.Global()")}}, de la manière suivante: -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>`; -} + const global = new WebAssembly.Global({value:'i32', mutable:true}, 0); + +Vous pouvez remarquer que ce constructeur prend deux paramètres: + +- Un objet qui comprend deux propriétés décrivant la variable globale: + + - `value`: 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 — `i32`, `i64`, `f32`, ou `f64`. + - `mutable`: un booléen definissant si la valeur est "mutable" ou non. + +- 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é. + +Finalement comment tout cela fonctionne? Dans l'exemple suivant nous définissons une variable globale "mutable" de type `i32`, avec une valeur de 0. + +La valeur de la variable globale est ensuite changée en `42` en utilisant la propriété `Global.value`, puis en `43` en utilisant cette fois la fonction exportée de l'instance du module global.wasm `incGlobal()` (cette fonction ajoute 1 à la valeur qui lui est donnée et retourne la nouvelle valeur). + + 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"); + assertEq("WebAssembly.Global exists", typeof WebAssembly.Global, "function"); -const global = new WebAssembly.Global({value:'i32', mutable:true}, 0); + 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> + 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); + }); -<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> +**Note**: Vous pouvez voir cet exemple en [live sur GitHub](https://mdn.github.io/webassembly-examples/js-api-examples/global.html); voir également le code [source](https://github.com/mdn/webassembly-examples/blob/master/js-api-examples/global.html). -<h2 id="Multiplicité">Multiplicité</h2> +## Multiplicité -<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> +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: -<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> +- 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. +- 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 [Multiple Tables and Memories](http://webassembly.org/docs/future-features/#multiple-tables-and-memories)). +- 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é. +- 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. -<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="/fr/docs/WebAssembly/Understanding_the_text_format#Mutating_tables_and_dynamic_linking">Mutating tables and dynamic linking</a>.</p> +Vous pouvez voir la mise en application du concept de multiplicité dans notre article Understanding text format — voir en particulier la section [Mutating tables and dynamic linking](/fr/docs/WebAssembly/Understanding_the_text_format#Mutating_tables_and_dynamic_linking). -<h2 id="Résumé">Résumé</h2> +## Résumé -<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> +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é. -<h2 id="A_voir_également">A voir également</h2> +## A voir également -<ul> - <li><a href="http://webassembly.org/">webassembly.org</a></li> - <li><a href="/fr/docs/WebAssembly/Concepts">WebAssembly concepts</a></li> - <li><a href="https://research.mozilla.org/webassembly/">WebAssembly on Mozilla Research</a></li> -</ul> +- [webassembly.org](http://webassembly.org/) +- [WebAssembly concepts](/fr/docs/WebAssembly/Concepts) +- [WebAssembly on Mozilla Research](https://research.mozilla.org/webassembly/) |