Add documentation for create-exe syntax

docs/dev/create-exe.md

@@ -0,0 +1,114 @@
+# 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:
+
+```sh
+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:
+
+```sh 
+wasmer create-exe [email protected] -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
+
+```sh
+# 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`:
+
+```c
+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`:
+
+```c
+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.
+
+```sh
+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
+```