Awesome

wasm-init

Work environment and code generator for WebAssembly projects

wasm-init abstracts the WebAssembly setup and compile process and aims to dramatically simplify the development workflow. <br><br>

Install

This package requires that you have Emscripten installed on your machine. You can get it like so:

git clone https://github.com/juj/emsdk.git
cd emsdk
./emsdk install sdk-incoming-64bit binaryen-master-64bit
./emsdk activate sdk-incoming-64bit binaryen-master-64bit

(Note, that the install will take a while. More information is here.)

The best way to install this module is via npm install wasm-init. <br><br>

Use

Quick Setup

• Add the following scripts to your project's package JSON:

  "scripts": {
    "wasm-init": "wasm-init",
    "compile": "wasm-compile",
    "start": "gulp" // optional for hot-reloading
  }

• npm run wasm-init minimal

• Add the relative path to the emsdk folder in your wasm.config.js file

• npm run wasm-init build

• node server and go to localhost:3000, open the console and check that WASM has loaded successfully

• make changes to your C++ file and recompile with npm run compile

  <br>

The whole story

At the heart of wasm-init is the wasm.config.js file, which takes Emscripten's compile process and breaks it down into configurable elements. To compile C++ to WASM with Emscripten, you need at bare minimum the following properties:

// wasm.config.js
module.exports = {
  emscripten_path: './../emsdk',
  inputfile: 'lib.cpp',
  outputfile: 'lib.js',
  flags: [
    '-s WASM=1',
  ],
};

emscripten_path is the relative path to the emsdk directory, from your project folder. (In the above case, we would expect Emscripten to be located in the same parent-directory as the project.) <br> <br>

Templates

These scripts make the module's functionality accessible. Be aware that npm run wasm-init will create several files and folders inside your project directory. This is your fastest route to a working project setup, however, you can also set up all the files manually, if you so desire. <br> <br>

Custom

The best way to a custom setup is to start with just the wasm.config.js file (you can generate it with npm run wasm-init minimal), and enter the emcc_path, inputfiles, outputfile, and flags according to your needs. When you run npm run wasm-init build, it will generate those files for you.

To compile, simply use npm run compile, which will take your C++ code and output a JavaScript file with Emscripten bindings, as well as the sought after .wasm file. To take advantage of wasm-init's easy loading mechanism for WebAssembly modules, you will need the wrapper file loadWASM.js. The wasm module is from there returned by a promise. Making the module accessible to your application is as easy as the following:

let m = {}
loadWASM().then(wasmModule => {
  m = wasmModule;
  m._myFunc(); // this is the call to the C++ function myFunc();
});

When you want to export individual functions from C++ to WASM, you can do this with the exported_functions property in wasm.config.js:

...
  exported_functions: [
    '_myFunc',
  ]
...

It is required to prepend the C++ function names with an underscore!, <br><br><br> If you are on board with wasm-init's automation, the quickest road to success would be: npm run wasm-init emcc_path=./../emsdk (modify path accordingly). This will set Emscripten's file path in the wasm.config.js file automatically. This will also install and compile all necessary files, including a server.js, index.js and index.html file, that are already setup to include WASM in the browser. <br> (Executing npm run wasm-init will overwrite any files that may already be there, as does npm run wasm-init build! ).

If you now run your browser (either manually or with gulp), and go to localhost:3000, open up the console, and you should see the message from the C++ file printed. <br><br>

Flags

The following flags for npm run wasm-init are usable: <br><br>

build - builds files according to instructions in wasm.config.js

minimal - only creates the wasm.config.js file

no-wrapper - no wrapper (loadWASM.js) file

no-cpp - no C++ file

no-indexjs - no index.js file

no-html - no html file

no-server - no server.js file

hot .

Note, that this will install the gulp and browser-sync packages automatically. This will also generate a gulpfile.js file, which is already setup to work with the template code.

npm run wasm-init clean

will delete the autogenerated files, except wasm.config.js .

npm run wasm-init clean-all

will delete all autogenerated files. Please use it carefully!

Collaborators: Deep Pulusani, Shahrod Khalkhali, Matthias Wagner