wasmer/docs/dev/create-exe.md

wasmer create-exe

Motivation and Goal

The goal of create-exe is to create easily runnable executables on every operating system.

In order to speed up the compilation process, the compilation and the create-exe steps are split into three separate functions: create-obj, create-exe and gen-c-header.

By default, running create-exe is relatively simple:

wasmer create-exe myfile.wasm -o myfile.exe
./myfile.exe

When running create-exe on a wapm package that contains more than one .wasm file, the resulting executable requires a --command or -c flag to select which module to start:

wasmer create-exe wabt@0.1.0.wasmer -o wabt.exe
./wabt.exe
No --command given, available commands are:

    wabt
    wasm-interp
    wasm-strip
    wasm-validate
    wasm2wat
    wast2json
    wat2wasm

./wabt.exe -c wasm2wat --version
1.0.37 (git~v1.0.37)

create-obj

Some compilers have different advantages over other compilers, for example, the -llvm compiler emits the best code, but is the slowest to compile, the -singlepass compiler emits slow code, but is very fast to compile.

In order to cache compiled object and re-use them for recompilation, wasmer create-obj exists to cache the output of the wasm -> obj compilation

# Requires wasmer >= 3.2.0-alpha.1
wasmer create-obj myfile.wasm -llvm -o myfile.o
# Run create-exe with the cached object file
wasmer create-exe myfile.wasm --precompiled-atom=myfile:myfile.o -o myfile.exe

The WebAssembly module (atom) name specified in the --precompiled-atom flag is the .wasm filename without the extension or the module name in a multi-webassembly wapm package.

Multi-command executables

When compiling multiple .wasm atoms into one executable, it could happen that the function names generated by wasmer would clash with each other (ex. wasmer_function_1 from object1.o and wasmer_function_1 from object2.o).

Therefore, wasmer inserts a prefix for these functions, which is apparent when running wasmer gen-c-header:

wasmer gen-c-header myfile.wasm -o myfile.h
cat myfile.h

// ...

// Compiled Wasm function pointers ordered by function index: the order they
// appeared in in the Wasm module.
extern void wasmer_function_6f62a6bc5c8f8e3e12a54e2ecbc5674ccfe1c75f91d8e4dd6ebb3fec422a4d6c_0(void);
extern void wasmer_function_6f62a6bc5c8f8e3e12a54e2ecbc5674ccfe1c75f91d8e4dd6ebb3fec422a4d6c_1(void);
extern void wasmer_function_6f62a6bc5c8f8e3e12a54e2ecbc5674ccfe1c75f91d8e4dd6ebb3fec422a4d6c_2(void);

// ...

By default, this "prefix" is the Sha256 hash of the input .wasm file and can be changed with the --prefix flag on both gen-c-header and create-obj:

wasmer gen-c-header myfile.wasm -o myfile.h --prefix abc123
cat myfile.h

// ...

// Compiled Wasm function pointers ordered by function index: the order they
// appeared in in the Wasm module.
extern void wasmer_function_abc123_0(void);
extern void wasmer_function_abc123_1(void);
extern void wasmer_function_abc123_2(void);

// ...

In order to instruct create-exe to use these object files, we can use the --precompiled-atom syntax with ATOM_NAME:PREFIX:PATH_TO_FILE where PREFIX is optional and defaults to the Sha256 hash of the wasm file.

wasmer create-obj myfile.wasm -o myfile.o --prefix abc123
wasmer create-exe myfile.wasm -o myfile.exe --precompiled-atom myfile:abc123:myfile.o

The speedup is apparent when timing this command against the non-cached version:

time wasmer create-exe myfile.wasm -o myfile.exe
1,53s user 0,24s system 157% cpu 1,124 total
time wasmer create-exe myfile.wasm -o myfile.exe --precompiled-atom myfile:myfile.o
0,72s user 0,19s system 105% cpu 0,856 total