for node.js

An experimental, minimal toolkit and runtime on top of node to produce and run WebAssembly modules.

To run compiled .wasm files, you'll either need a recent version of your browser with WebAssembly enabled or node.js 8 nightly - but you probably already know that.

Motivation

Prevalent WebAssembly tooling provides compilation to WebAssembly from a C/C++ perspective with a focus on porting existing code. Because of that, it usually produces a lot of extra code that isn't needed alongside a module that is solely trying to complement JavaScript. This package, on the other hand, tries to keep the support library and the generated modules as small as possible by specifically targeting WebAssembly (in the browser) only.

PRs welcome!

Example

Write your module as a C program:

// program.c
#include <webassembly.h>

export int add(int a, int b) {
  return a + b;
}

Compile it to wasm:

$> wa-compile -o program.wasm program.c

Run it:

// program.js
require("webassembly")
  .load("program.wasm")
  .then(module => {
    console.log("1 + 2 = " + module.exports.add(1, 2));
  });

Installation

$> npm install webassembly

Installing the package automatically downloads prebuilt binaries for either Windows (win32-x64) or Linux (linux-x64).

Toolkit

WebAssembly functionality is provided by a C header. A small JavaScript support library (distributions) provides the browser runtime.

Calling webassembly.load(file: string, [options: LoadOptions]): Promise<IModule> returns a promise for a module instance:

• module.exports contains exported functions
• module.memory references the memory instance
• module.env references the environment used

Available LoadOptions:

• imports: Object specifies imported functions
• initialMemory: number specifies the initial amount of memory in 64k pages (defaults to 1)
• maximumMemory: number specifies the maximum amount of memory in 64k pages that the module is allowed to grow to (optional)

C features available out of the box:

• Various standard types (integers, booleans, floats) and corresponding constants
• import and export defines to mark your imports and exports
• console methods become console_log etc. and Math becomes Math_abs etc.
• malloc, free, realloc and calloc (dlmalloc)
• memcpy, memmove, memalign, memset and strlen (musl)

Malloc and friends can be explicitly exported to JS by defining EXPORT_<FUNCNAME>, i.e. #define EXPORT_MALLOC.

Console functions accept the following string substitutions with variable arguments:

Subst.	C type	Description
%i	int / int32_t	Signed 32 bit integer
%u	unsigned int / uint32_t	Unsigned 32 bit integer
%f	float	32 bit float
%d	double	64 bit double
%s	char *	String (zero terminated)

For now, math is (mostly) performed on 64 bit IEEE754 floating point operands as provided by the browser.

On the JS side of things, the memory instance (module.memory) has additional mixed in utility methods for convenient memory access:

• memory.getInt(ptr: number): number gets the signed 32 bit integer at the specified address (aligned to 4 bytes)
• memory.getUint(ptr: number): number gets the unsigned 32 bit integer at the specified address (aligned to 4 bytes)
• memory.getFloat(ptr: number): number gets the 32 bit float at the specified address (aligned to 4 bytes)
• memory.getDouble(ptr: number): number gets the 64 bit double at the specified address (aligned to 8 bytes)
• memory.getString(ptr: number): string gets the zero terminated string literal at the specified address

The underlying typed array views are also available for direct use. Just make sure to access them directly on the memory instance because they are updated when the program memory grows.

• memory.U8: Uint8Array
• memory.U32: Uint32Array
• memory.S32: Int32Array
• memory.F32: Float32Array
• memory.F64: Float64Array

Command line

The wa-compile utility (also callable as wa compile, wa comp, wa c) compiles C code to a WebAssembly module.

  -o, --out      Specifies the .wasm output file. Defaults to input file with .wasm extension.
  -d, --debug    Prints debug information to stderr.
  -q, --quiet    Suppresses informatory output.
  -h, --headers  Includes the specified headers directory. Multiple are possible.
  -i, --include  Includes the specified file. Multiple are possible.

  Module configuration:

  -s, --stack    Specifies the stack size. Defaults to 10000.
  -m, --main     Calls the specified function on start.

usage: wa-compile [options] program.c

The wa-disassemble utility (also callable as wa disassemble, wa dis, wa d) decompiles a WebAssembly module to text format.

  -o, --out      Specifies the .wast output file. Defaults to input file with .wast extension.
  -d, --debug    Prints debug information to stderr.
  -q, --quiet    Suppresses informatory output.

usage: wa-disassemble [options] program.wasm

The wa-assemble utility (also callable as wa assemble, wa as, wa a) assembles WebAssembly text format to a module.

  -o, --out      Specifies the .wasm output file. Defaults to input file with .wasm extension.
  -d, --debug    Prints debug information to stderr.
  -q, --quiet    Suppresses informatory output.

usage: wa-assemble [options] program.wast

Command line utilites can also be used programmatically by providing command line arguments and a callback to their respective main functions:

var compiler = require("webassembly/cli/compiler"); // or assembler, disassembler

compiler.main([
  "-o", "program.wasm",
  "program.c"
], function(err, filename) {
  if (err)
    throw err;
  console.log("saved to: " + filename);
});

IDE integration

Anything should work as long as you are able to configure it, even notepad.

I am using:

• Visual Studio Code (example Ctrl+Shift+B task)
• with C/C++ for Visual Studio Code (example config)

License: BSD 3-Clause License. Includes parts of musl (MIT License) and binaryen (Apache License, Version 2.0). WebAssembly logo by Carlos Baraza (CC0 1.0 Universal).