LG

Cette page est en lecture seule. Vous pouvez afficher le texte source, mais ne pourrez pas le modifier. Contactez votre administrateur si vous pensez qu'il s'agit d'une erreur.
=====Téléchargement et installation et mise à jour=====
<code bash>
git clone --depth 1 https://github.com/emscripten-core/emsdk.git
cd emsdk
git pull
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh
</code>

[[https://emscripten.org/docs/getting_started/downloads.html|Download and install]]

=====Utilisations=====

Emscripten va permettre de générer un fichier ''.js'' qui va contenir le code passerelle entre le code JavaScript et le code WebAssembly qui sera dans le fichier ''.wasm''.

C'est donc un outil plutôt adapté pour créer des librairies, même s'il est possible de créer des programmes entiers avec.

[[https://pascalpares.appspot.ovh/webassembly-for-javascript-developers/|An Introduction to WebAssembly for JavaScript Developers]] {{ :prog:emscripten:an_introduction_to_webassembly_for_javascript_developers_2021-07-24_11_04_06_.html |Archive du 21/04/2021 le 24/07/2021}}

[[https://developers.google.com/web/updates/2018/03/emscripting-a-c-library|Emscripting a C library to Wasm]] {{ :prog:emscripten:emscripting_a_c_library_to_wasm_web_google_developers_8_4_2021_10_04_21_am_.html |Archive du 31/07/2020 le 04/08/2021}}
====Compilation====

[[https://emscripten.org/docs/tools_reference/emcc.html|Options de compilation]]

Liste des [[https://github.com/emscripten-core/emscripten/blob/main/src/settings.js|settings]] (''-s'').

Pour réduire la taille du wrapper:

  * ''-s ENVIRONMENT=web,worker'' : réduire les fonctionnalités en supprimant le support de node.js. Réduit très légèrement la taille du wrapper mais enlève des dépendances externes. Utile pour la mise en production dans un projet Angular. Ne doit pas être enlevé si les tests exécutés par node.js,
  * ''%%--%%closure 1 -s MODULARIZE=1'' : ''closure'' fait de la minification. Afin d'éviter les effets de bord avec d'autres variables globales en Javascript, il est forcement recommandé d'encapsuler le code dans un module,
  * ''%%--no-entry%%'' : désactive la fonction ''main'' qui est inutile si la sortie Javascript est une librairie et non une application indépendante,
  * ''-s ASSERTIONS=0'' : désactive des sécurités.

Pour réduire la taille du wasm:

  * ''-flto'' : active l'optimisation globale du lieur,
  * ''-DNDEBUG'' : désactive le debug. N'impacte pas le code emscripten mais uniquement le code utilisateur,
  * ''-Oz'' : le bytecode est optimisé pour réduire la taille.
  * ''-s MALLOC=%%'emmalloc'%%'' : utilise une version de malloc réduite en fonctionnalité mais spécifique à emscripten.

Pour le debug:
  * ''-O0'' : aucune optimisation.
  * ''-g'' : toutes les informations de débogage,
  * ''-s ASSERTIONS=2'' : toutes les assertions à l'exécution,
  * ''-s DEMANGLE_SUPPORT=1'' : affichage des symboles en cas d'affichage de la trace par le compilateur,
  * ''%%--%%emit-symbol-map'' : génère un fichier ''.map'',
  * ''-gsource-map'' : génère un ''.map'' compatible LLVM pour déboguer avec Chrome,
  * ''%%--source-map-base http://localhost:4200/assets/%%'' : codage en dur du chemin vers le fichier ''.wasm'' uploadé et non du chemin dans l'ordinateur.

Pour mémo, le tableau des résultats. La comparaison des options ''-Ox'' se fait par rapport à ''-O0''. Puis, les options suivantes s'accumulent avec l'option -Oz. Dans mon cas, ''-O2'' réduit mieux la taille que ''-Oz''. A confirmer sur de plus gros projets.

^Option^gros js^gros wasm^petit js^petit wasm^gros js^gros wasm^petit js^petit wasm^
|''-O0''|349801|888030|217442|59279|-|-|-|-|
|''-O2''|349801|841160|214892|26971|0%/0o|-5,3%/-46870o|-1,2%/-2550o|-54,5%/-32308o|
|''-O3''|349801|841966|214892|26971|0%/0o|-5,2%/-46064o|-1,2%/-2550o|-54,5%/-32308o|
|''-Os''|349801|842814|217442|34746|0%/0o|-5,1%/-45216o|0%/0o|-41,4%/-24533o|
|''-Oz''|349801|842838|217442|34739|0%/0o|-5,1%/-45192o|0%/0o|-41,4%/-24540o|
|''-s ENVIRONMENT=web,worker''|N/A|N/A|214984|34739|N/A|N/A|-1,1%/-2458o|0%/0o|
|''%%--%%closure 1''|158780|842838|118137|34739|-54,6%/-191021o|0%/0o|-45%/-96847o|0%/0o|
|''%%--%%no-entry''|158223|842838|117580|34739|-0,4%/-557o|0%/0o|-0,5%/-557o|0%/0o|
|''-flto''|158223|835253|117580|31867|0%/0o|-0,9%/-7585o|0%/0o|-8,3%/-2872o|
|''-s ASSERTIONS=0''|67927|835110|34944|31510|-57,1%/-90296o|0%/-143o|-70,3%/-82636o|-1,1%/-357o|
|''-DNDEBUG''|67927|835110|34944|31510|0%/0o|0%/0o|0%/0o|0%/0o|
|''-s INVOKE_RUN=0''|67927|835110|34944|31510|0%/0o|0%/0o|0%/0o|0%/0o|
|''-s MALLOC='emmalloc%%'%%''|67927|826803|34944|23703|0%/0o|-1%/-8307o|0%/0o|-24,8%/-7807o|

====vcpkg====

Après l'installation en utilisant le triplet ''wasm32-emscripten'', il est possible de le cumuler avec ''emcmake''.

<code bash>
source ./emsdk/emsdk_env.sh
.\vcpkg\bootstrap-vcpkg.bat
.\vcpkg\vcpkg install --triplet wasm32-emscripten spdlog
emcmake cmake -S . -B [build_directory] -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=.../emsdk/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake -DVCPKG_TARGET_TRIPLET=wasm32-emscripten -DCMAKE_TOOLCHAIN_FILE=.../vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build [build_directory]
</code>

=====Exemples=====

====Librairies====

===Une simple librairie===

  * Code source

<code c>
#include <emscripten.h>

EMSCRIPTEN_KEEPALIVE
int add(int a, int b) {
    return a + b;
}
</code>

  * Compilation

<code bash>
emcc add.c -o add.js -s EXPORT_NAME="'ModuleName'"
</code>

  * Utilisation depuis du code html

Puis on peut utiliser la fonction add depuis le code HTML en passant par la librairie JavaScript générée. Il faudra bien mettre en ligne les deux fichiers ''.js'' et ''.wasm''.

Par défaut, tous les objets exportés sont regroupés dans un objet global ''ModuleName''. La fonction est accessible depuis son nom "mangled" (''func1@a@@AAEXH@Z'' par exemple), avec l'ajout d'un préfix ''_''. [[https://docs.microsoft.com/en-us/cpp/build/reference/decorated-names?redirectedfrom=MSDN&view=msvc-160|Decorated Names]] {{ :prog:emscripten:decorated_names_microsoft_docs_04_01_2021_20_16_24_.html |Archive du 05/09/2018 le 04/01/2021}}

<code xml>
<head>
<script type="text/javascript">
  var ModuleName = {
    onRuntimeInitialized: function() {
      const a = 1.5;
      const b = 3.8;
      const ret = ModuleName._add(1.5, 3.8);
      console.log(`${a} + ${b} = ${ret}`);
    }
  };
</script>
<script type="text/javascript" src="add.js"></script>
</head>
<body>
</body>
</code>

[[https://medium.com/vacatronics/how-to-write-a-webassembly-app-in-c-c-6c560438a844|How To Write A WebAssembly App in C/C++]] {{ :prog:emscripten:how_to_write_a_webassembly_app_in_c_c_by_fernando_souza_vacatronics_nov_2020_medium_04_01_2021_20_16_32_.html |Archive du 12/11/2020 le 04/01/2021}}

[[https://emscripten.org/docs/getting_started/FAQ.html|FAQ]] {{ :prog:emscripten:emscripten_faq.rst_at_c978e1e4dbd3dd13b25853f32ed7ffab6d31a726_emscripten-core_emscripten_github_2021-03-19_04_03_58_.html |Archive du 11/01/2021 le 19/03/2021}}

====Module====

Certaines librairies imposent l'utilisation des modules ([[https://jestjs.io/fr/|jest]]).

Il faut utiliser l'option ''-s MODULARIZE=1''.

  * Utilisation en HTML

<WRAP center round info 60%>
Il faut bien mettre ''%%type="test/javascript"%%'' et pas ''%%type="module"%%''.
</WRAP>


<code xml>
<script type="text/javascript" src="add.js"></script>
<script type="text/javascript">
  ModuleName().then(async instance => {
    const a = 1.5;
    const b = 3.8;
    const ret = instance.__Z3addii(1.5, 3.8);
    console.log(`${a} + ${b} = ${ret}`);
  });
</script>
</code>

  * Utilisation avec Jest

<code javascript>
const Module = require('./add.js');

test('test name', async () => {
  return Module().then(async instance => {
    instance.__Z3addii(...);
  });
});
</code>

====Bindings====

C'est quand même plus pratique d'utiliser du style orienté objet plutôt que des symboles "mangled".

Il faut donc déclarer manuellement :
  * toutes les classes que l'on souhaite utiliser,
  * toutes les fonctions, y compris constructeur, que l'on souhaite utiliser pour chaque classe,
  * toutes les classes utilisées dans les arguments et les valeurs retours des fonctions qui seront utilisées,
  * les relations d'héritage si le type parent est utilisé pour exécuter les fonctions de l'enfant (polymorphisme).

Dans mes tests, j'ai vu que le lieur d'emscripten semble avoir du mal avec les symboles weak multiples. Il est préférable de tout mettre dans un même fichier source.

<code cpp>
EMSCRIPTEN_BINDINGS(jessica)
{
  class_<Jessica::Data::Geotechnical::IFoundationStrip>("IFoundationStrip")
      .smart_ptr<
          std::shared_ptr<Jessica::Data::Geotechnical::IFoundationStrip>>(
          "IFoundationStrip")
      .function(
          "setB",
          select_overload<std::shared_ptr<
              Jessica::Data::Geotechnical::IFoundationStrip>(double) const>(
              &Jessica::Data::Geotechnical::IFoundationStrip::B))
      .function("getB", select_overload<double() const>(
                            &Jessica::Data::Geotechnical::IFoundationStrip::B));

  class_<Jessica::Data::Geotechnical::FoundationStrip<
             Jessica::Util::Decorator::LogCall<
                 Jessica::Util::Decorator::LogDuration<
                     Jessica::Data::Geotechnical::FoundationStripImpl>>>,
         base<Jessica::Data::Geotechnical::IFoundationStrip>>(
      "FoundationStripDeco")
      .constructor<>()
      .function(
          "clone",
          &Jessica::Data::Geotechnical::FoundationStrip<
              Jessica::Util::Decorator::LogCall<
                  Jessica::Util::Decorator::LogDuration<
                      Jessica::Data::Geotechnical::FoundationStripImpl>>>::
              Clone)
      .function(
          "setB",
          select_overload<std::shared_ptr<
              Jessica::Data::Geotechnical::IFoundationStrip>(double) const>(
              &Jessica::Data::Geotechnical::FoundationStrip<
                  Jessica::Util::Decorator::LogCall<
                      Jessica::Util::Decorator::LogDuration<
                          Jessica::Data::Geotechnical::FoundationStripImpl>>>::
                  B))
      .function(
          "getB",
          select_overload<double() const>(
              &Jessica::Data::Geotechnical::FoundationStrip<
                  Jessica::Util::Decorator::LogCall<
                      Jessica::Util::Decorator::LogDuration<
                          Jessica::Data::Geotechnical::FoundationStripImpl>>>::
                  B));
}
</code>

====WebAssembly.instantiateStreaming en TypeScript====

  * Sans le wrapper ''.js''

Il est possible d'utiliser ''WebAssembly.instantiateStreaming'' pour charger le fichier ''.wasm'' sans passer par le fichier ''.js'' qui sert de wrapper.

Exemple en TypeScript. Nécessite ''npm install %%--%%save @assemblyscript/loader''.

<code javascript>
import { instantiateStreaming } from "@assemblyscript/loader";

interface MyApi extends Record<string, unknown> {
  add(a: number, b: number): number;
}

async function getWasm() {
  const imports: any = {};
  var module = instantiateStreaming<MyApi>(fetch('assets/add.wasm'), imports);
  return module;
}

@Component({
  selector: 'app-main',
  templateUrl: './main.component.html',
  styleUrls: ['./main.component.css'],
})
export class MainComponent implements OnInit {
  private exports?: MyApi;
  constructor() {
    getWasm().then((mod) => {
      this.exports = mod.exports;
      console.log(this.exports.add(2, 4));
    });
  }

  ngOnInit(): void { }
}
</code>

Mais attention, le deuxième paramètre de ''instantiateStreaming'' peut être nécessaire pour définir un environnement précis et de fonctions de callback entre wasm et javascript. C'est notamment le cas pour l'utilisation des bindings de ''EMSCRIPTEN_BINDINGS''.

Dans cette nouvelle configuration, le chargement d'un wasm va donner le message d'erreur :

  LinkError: import object field '_embind_register_class' is not a Function

Et cette fonction javascript est déclarée dans le fichier .js générée par emscripten. L'utilisation du fichier .js comme wrapper sera probablement nécessaire.

  * Avec le wrapper ''.js''

Il faut commencer par autoriser l'utilisation du code javascript.

<file javascript tsconfig.json>
{
  "compilerOptions": {
    ...,
    "allowJs": true,
    "esModuleInterop": true
  }
}
</file>

Ensuite, utiliser le code TypeScript suivant :

<file javascript main.component.ts>
import { Component, OnInit } from '@angular/core';
import * as Module from './jessica';

@Component({
  selector: 'app-main',
  templateUrl: './main.component.html',
  styleUrls: ['./main.component.css'],
})
export class MainComponent implements OnInit {
  private instance?: any;
  constructor() {
    Module.default().then(async (instance: any) => {
      this.instance = instance;
      const vert1 = new this.instance.VerticalEccentricRaw();
      const vert2 = vert1.setE(0.2);
      console.log('getE ' + vert2.getE());
    });
  }

  ngOnInit(): void {}
}
</file>

  * Compatibilité avec ''node.js''

Il est possible que le compilateur râle si on utilise des fonctionnalités de type bindings.

<WRAP center round info 60%>
Si la compatibilité avec node.js n'est pas indispensable, on peut tout simplement désactiver via l'option de compilation ''-s ENVIRONMENT=web,worker''. Cette option ne réduit pas la taille du fichier ''.wasm'' et seulement de façon marginal le ''.js'' mais cela enlève les dépendances spécifiques à ''node.js''.
</WRAP>

<code>
BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

If you want to include a polyfill, you need to:
        - add a fallback 'resolve.fallback: { "path": require.resolve("path-browserify") }'
        - install 'path-browserify'
If you don't want to include a polyfill, you can use an empty module like this:
        resolve.fallback: { "path": false }
</code>

Pour les modules ''path'', ''crypto'' et ''stream'', on peut utiliser une librairie annexe pour résoudre ce problème :

<file javascript tsconfig.json>
{
  "compilerOptions": {
    "paths": {
      "path": ["./node_modules/path-browserify"],
      "crypto": ["./node_modules/crypto-browserify"],
      "stream": ["./node_modules/stream-browserify"]
    },
  }
}
</file>

et installer les dépendances :

<code bash>
npm i path-browserify -D
npm i crypto-browserify -D
npm i stream-browserify -D
</code>

[[https://github.com/angular/angular-cli/issues/20819#issuecomment-856003399|BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.]] {{ :prog:emscripten:breaking_change_webpack_5_used_to_include_polyfills_for_node.js_core_modules_by_default._issue_20819_angular_angular-cli_2021-07-24_20_06_22_.html |Archive du 17/05/2021 le 24/07/2021}}

Apparemment, il existe un paquet qui résout tous ces problèmes en une fois : [[https://github.com/Richienb/node-polyfill-webpack-plugin|node-polyfill-webpack-plugin]]. Cela résout les problèmes pour les modules ''assert'', ''buffer'', ''console'', ''constants'', ''crypto'', ''domain'', ''events'', ''http'', ''https'', ''os'', ''path'', ''punycode'', ''process'', ''querystring'', ''stream'', ''_stream_duplex'', ''_stream_passthrough'', ''_stream_readable'', ''_stream_transform'', ''_stream_writable'', ''string_decoder'', ''sys'', ''timers'', ''tty'', ''url'', ''util'', ''vm'', ''zlib''.

Par contre, il n'existe pas de module externe pour la fonctionnalité ''fs''. Dans ce cas, le compilateur ne vous proposera pas de solution :

<code>
./projects/app-main/src/app/ui/main/jessica.js:380:30-43 - Error: Module not found: Error: Can't resolve 'fs' in '...\projects\app-main\src\app\ui\main'
</code>

Dans ce cas, il faut désactiver le module. Les fonctions associées ne fonctionneront pas.

<WRAP center round info 60%>
Il se peut que la compatibilité soient nécessaires pour les tests qui nécessitent node.js pour s'exécuter mais que TypeScript ne nécessite pas ces dépendances. Il est possible de tout désactiver pour TypeScript en les mettant tous à ''false'' dans la rubrique ''browser'' ci-dessous et sans installer les dépendances via ''npm''.
</WRAP>

<file javascript package.json>
{
  ...,
  "browser": {
    "fs": false
  }
}
</file>

[[https://github.com/angular/angular-cli/issues/8272#issuecomment-392777980|Error: Module not found: Error: Can't resolve 'fs']] {{ :prog:emscripten:error_module_not_found_error_can_t_resolve_fs_issue_8272_angular_angular-cli_2021-07-24_20_10_56_.html |Archive du 01/11/2017 le 24/07/2021}}
=====Erreurs=====

  * ''UnboundTypeError: Cannot call FoundationStripRaw.setB due to unbound types: N7Jessica4Data12Geotechnical19FoundationStripImpl4SetBE''

Ici, la fonction ''FoundationStripRaw.setB'' a besoin du type ''N7Jessica4Data12Geotechnical19FoundationStripImpl4SetBE'' (classe ''Jessica::Data::Geotechnical::FoundationStripImpl::SetB'').

Il suffit de rajouter dans ''EMSCRIPTEN_BINDINGS'' le ''%%class_<Jessica::Data::Load::VerticalEccentricImpl::SetE>("VerticalEccentricImpl_SetE")%%'' adapté si besoin.