wasm-micro-runtime/doc/build_wasm_app.md

Build WASM app

You can write a simple test.c as the first sample.

#include <stdio.h>
#include <stdlib.h>

int main(int argc, char **argv)
{
    char *buf;

    printf("Hello world!\n");

    buf = malloc(1024);
    if (!buf) {
        printf("malloc buf failed\n");
        return -1;
    }

    printf("buf ptr: %p\n", buf);

    sprintf(buf, "%s", "1234\n");
    printf("buf: %s", buf);

    free(buf);
    return 0;
}

There are several methods to build a WASM binary. They are the clang compiler, Docker, Emscripten and so on.

Use clang compiler

The recommended method to build a WASM binary is to use clang compiler clang-8. You can refer to apt.llvm.org for the detailed instructions. Here are referenced steps to install clang-8 in Ubuntu 16.04 and Ubuntu 18.04.

(1) Add source to your system source list from llvm website

For Ubuntu 16.04, add the following lines to /etc/apt/sources.list:

deb http://apt.llvm.org/xenial/ llvm-toolchain-xenial main
deb-src http://apt.llvm.org/xenial/ llvm-toolchain-xenial main
# 8
deb http://apt.llvm.org/xenial/ llvm-toolchain-xenial-8 main
deb-src http://apt.llvm.org/xenial/ llvm-toolchain-xenial-8 main
# 9
deb http://apt.llvm.org/xenial/ llvm-toolchain-xenial-9 main
deb-src http://apt.llvm.org/xenial/ llvm-toolchain-xenial-9 main

For Ubuntu 18.04, add the following lines to /etc/apt/sources.list:

# i386 not available
deb http://apt.llvm.org/bionic/ llvm-toolchain-bionic main
deb-src http://apt.llvm.org/bionic/ llvm-toolchain-bionic main
# 8
deb http://apt.llvm.org/bionic/ llvm-toolchain-bionic-8 main
deb-src http://apt.llvm.org/bionic/ llvm-toolchain-bionic-8 main
# 9
deb http://apt.llvm.org/bionic/ llvm-toolchain-bionic-9 main
deb-src http://apt.llvm.org/bionic/ llvm-toolchain-bionic-9 main

(2) Download and install clang-8 tool-chain using following commands:

sudo wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key|sudo apt-key add -
# Fingerprint: 6084 F3CF 814B 57C1 CF12 EFD5 15CF 4D18 AF4F 7421
sudo apt-get update
sudo apt-get install llvm-8 lld-8 clang-8

(3) Create a soft link under /usr/bin:

cd /usr/bin
sudo ln -s wasm-ld-8 wasm-ld

(4) Use the clang-8 command below to build the WASM C source code into the WASM binary.

clang-8 --target=wasm32 -O3 \
        -z stack-size=4096 -Wl,--initial-memory=65536 \
        -Wl,--allow-undefined,--export=main \
        -Wl,--strip-all,--no-entry -nostdlib \
        -o test.wasm test.c

You will get test.wasm which is the WASM app binary.

Use cmake

If you have a cmake project, you can cross compile your project by using the toolchain provided by WAMR, the compiler used by WAMR toolchain is clang-8.

We can generate a CMakeLists.txt file for test.c:

cmake_minimum_required (VERSION 3.5)
project(hello_world)
add_executable(hello_world test.c)

It is quite simple to build this project by cmake:

mkdir build && cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=$WAMR_ROOT/test-tools/toolchain/wamr_toolchain.cmake
make

You will get hello_world which is the WASM app binary.

For more details about wamr toolchain, please refer to test-tools/toolchain.

Use wasi-sdk

To build a wasm application with wasi support, wasi-sdk is required. Download the wasi-sdk and extract the archive, then you can use it to build your application:

/path/to/wasi-sdk/bin/clang test.c -o test.wasm

You will get test.wasm which is the WASM app binary.

Using Docker

Another method availble is using Docker. We assume you've already configured Docker (see Platform section above) and have a running interactive shell. Currently the Dockerfile only supports compiling apps with clang, with Emscripten planned for the future.

Use the clang-8 command below to build the WASM C source code into the WASM binary.

clang-8 --target=wasm32 -O3 \
        -z stack-size=4096 -Wl,--initial-memory=65536 \
        -Wl,--allow-undefined,--export=main \
        -Wl,--strip-all,--no-entry -nostdlib \
        -o test.wasm test.c

You will get test.wasm which is the WASM app binary.

Use Emscripten tool

The last method to build a WASM binary is to use Emscripten tool emcc. Assuming you are using Linux, you may install emcc from Emscripten EMSDK following the steps below:

git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest-fastcomp
./emsdk activate latest-fastcomp

The Emscripten website provides other installation methods beyond Linux.

Use the emcc command below to build the WASM C source code into the WASM binary.

cd emsdk
source emsdk_env.sh     (or add it to ~/.bashrc if you don't want to run it each time)
cd <dir of test.c>
EMCC_ONLY_FORCED_STDLIBS=1 emcc -g -O3 -s WASM=1 -s ERROR_ON_UNDEFINED_SYMBOLS=0 \
          -s TOTAL_MEMORY=65536 -s TOTAL_STACK=4096 \
          -s ASSERTIONS=1 -s STACK_OVERFLOW_CHECK=2 \
          -s "EXPORTED_FUNCTIONS=['_main']" -o test.wasm test.c

You will get test.wasm which is the WASM app binary.

Run WASM app

Assume you are using Linux, the command to run the test.wasm is:

cd iwasm/products/linux/build
./iwasm test.wasm

You will get the following output:

Hello world!
buf ptr: 0x400002b0
buf: 1234

If you would like to run the test app on Zephyr, we have embedded a test sample into its OS image. You will need to execute:

ninja run