Generating WebAssembly with LDC
Starting with v1.11, LDC supports compiling and linking directly to WebAssembly. This page shows how to get started.
Contents
Building WebAssembly
Let's generate a .wasm file for this D code (wasm.d):
extern(C): // disable D mangling
double add(double a, double b) { return a + b; }
// seems to be the required entry point
void _start() {}
Build wasm.wasm:
ldc2 -mtriple=wasm32-unknown-unknown-wasm -betterC wasm.d
If using DUB:
dub build --compiler=ldc2 --arch=wasm32-unknown-unknown-wasm
In case LDC errors out (e.g., with unsupported -link-internally), try an official prebuilt release package.
Test in HTML page
Let's test it with a little HTML page, loading and invoking the WebAssembly via JavaScript. Generate an .html file in the same directory as the .wasm file, with the following contents:
<html>
<head>
<script>
const request = new XMLHttpRequest();
request.open('GET', 'wasm.wasm');
request.responseType = 'arraybuffer';
request.onload = () => {
console.log('response received');
const bytes = request.response;
const importObject = {};
WebAssembly.instantiate(bytes, importObject).then(result => {
console.log('instantiated');
const { exports } = result.instance;
// finally, call the add() function implemented in D:
const r = exports.add(42, -2.5);
console.log('r = ' + r);
});
};
request.send();
console.log('request sent');
</script>
</head>
<body>
Test page
</body>
</html>
Note that fetch() doesn't work for files in the local filesystem (file://), but XMLHttpRequest does in Firefox (not in Chrome though IIRC).
Open the HTML page; the JavaScript console should show:
request sent response received instantiated r = 39.5
Calling external functions
The minimal example above only calls in one direction, from JavaScript to WebAssembly. Here's how to call external functions in D:
wasm.d:
extern(C): // disable D mangling
// import a function "callback" from default import module name "env"
void callback(double a, double b, double c);
double add(double a, double b)
{
const c = a + b;
callback(a, b, c);
return c;
}
void _start() {}
Add -L-allow-undefined as linker flag to the LDC command line, otherwise LLD refuses to link due to undefined callback().
Implement the callback() function in JavaScript and specify it in importObject.env:
const callback = (a, b, c) => {
console.log(`callback from D: ${a} + ${b} = ${c}`);
};
// ...
const importObject = {
env: { callback }
};
The log should now show:
request sent response received instantiated callback from D: 42 + -2.5 = 39.5 r = 39.5
To import functions from other modules or rename imported functions, we use LDC's @llvmAttr:
import ldc.attributes;
extern(C): // disable D mangling
// import a function "add" from module name "math" and rename it to "add_numbers"
@llvmAttr("wasm-import-module", "math") @llvmAttr("wasm-import-name", "add") {
int add_numbers(int a, int b);
}
// export a function "hello"
export int hello(int a, int b, int c)
{
int s1 = add_numbers(a, b);
int s2 = add_numbers(s1, c);
return s2;
}
void _start() {}
Calling conventions
Arrays
When calling an external function from web assembly, arrays are passed as two separate arguments: the length followed by the pointer (offset into linear memory) to the array data. For example, if an external function is declared as:
void externalFunc(int a, string b, float c);
The corresponding Javascript function should be declared this way:
function externalFunc(a, bLength, bOffset, c) { ... }
The array data can be accessed from Javascript by creating the appropriate typed array over the web assembly module's linear memory. For example, a passed string can be retrieved in Javascript like this:
function externalFunc(a, bLength, bOffset, c) {
// result is the object passed by WebAssembly.instantiate to the callback.
bytes = new Uint8Array(result.instance.memory.buffer, bOffset, bLength);
str = TextDecoder('utf8').decode(bytes);
}
Non-POD parameters
Non-POD values are passed by reference to external functions. I.e., the external function will receive a pointer (offset) to the value, and must read the linear memory at that offset to retrieve the data.
Non-POD return values
Non-POD return values are implemented by passing a pointer as the first argument of the external function. I.e.,
struct MyStruct { int x; }
MyStruct externalFunc(int x);
translates to the Javascript function:
function MyStruct(resultOffset, x) {
// caller expects the return value to be stored in linear memory at offset resultOffset.
// No return statement (behaves like a void function).
}
Additional LLVM wasm features
You can list the supported LLVM features for WASM with your LDC version like SIMD or exception handling using
ldc2 -mtriple=wasm32-unknown-unknown-wasm -mattr=help
Example output: (may be outdated, run the above command yourself to get the supported features for your LDC version)
Targeting wasm32. Available CPUs for this target: bleeding-edge - Select the bleeding-edge processor. generic - Select the generic processor. mvp - Select the mvp processor. Available features for this target: atomics - Enable Atomics. bulk-memory - Enable bulk memory operations. exception-handling - Enable Wasm exception handling. multivalue - Enable multivalue blocks, instructions, and functions. mutable-globals - Enable mutable globals. nontrapping-fptoint - Enable non-trapping float-to-int conversion operators. reference-types - Enable reference types. sign-ext - Enable sign extension operators. simd128 - Enable 128-bit SIMD. tail-call - Enable tail call instructions. Use +feature to enable a feature, or -feature to disable it. For example, llc -mcpu=mycpu -mattr=+feature1,-feature2
Conditional compilation
The version identifier version(WebAssembly) is defined when compiling for a web assembly target. This can be used for conditional compilation involving web assembly targets.
Examples
- Image Dithering with WebAssembly, D and LDC by Allen Garvey, Demo
- Meta tic-tac-toe game, Demo
