WAMR vmcore is the runtime library set that loads and runs Wasm modules. This guide walks you through building the WAMR vmcore.

References:

• how to build iwasm: build for Linux, Windows, macOS, and more
• Blog: Introduction to WAMR running modes

Include the script runtime_lib.cmake from build-scripts into your CMakeLists.txt to pull vmcore into your build:

include (${WAMR_ROOT_DIR}/build-scripts/runtime_lib.cmake)
add_library(vmlib ${WAMR_RUNTIME_LIB_SOURCE})

Then make three decisions, in this order:

1. The running mode. The WAMR Interpreter and AOT must be enabled at least one of them: WAMR_BUILD_INTERP for the interpreter (add WAMR_BUILD_FAST_INTERP to use the fast interpreter instead of the classic one), WAMR_BUILD_AOT for AOT, and WAMR_BUILD_FAST_JIT / WAMR_BUILD_JIT for the JIT modes. See Configure interpreters, Configure AOT, Configure Fast JIT and Configure LLVM JIT. The platform comes along with it: set WAMR_BUILD_PLATFORM when it cannot be derived from the host.

2. The feature switches. All switches are listed in All compilation flags below, and each switch has its own section.

3. The order. Every WAMR_BUILD_xxx assignment must come before include (runtime_lib.cmake), and that includes the running mode and the platform. runtime_lib.cmake includes config_common.cmake at its end, and that file fills in the defaults, derives the dependent switches and turns the switches into the -DWASM_ENABLE_xxx compiler macros. A switch that is assigned after the include is not seen by any of that logic.

Here is a minimum workable example that shows the order:

cmake_minimum_required (VERSION 3.14)
project (iwasm_embed LANGUAGES C)

set (WAMR_ROOT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/wamr)

# 1. The running mode, and the platform if it is not the default
set (WAMR_BUILD_PLATFORM "linux")
set (WAMR_BUILD_INTERP 1)

# 2. Any other switch, still before the include
set (WAMR_BUILD_SIMD 1)

# 3. Pull the vmcore in
include (${WAMR_ROOT_DIR}/build-scripts/runtime_lib.cmake)
add_library (vmlib ${WAMR_RUNTIME_LIB_SOURCE})

# Wrong: the assignment happens after config_common.cmake already ran, so
# WASM_ENABLE_SIMD is not defined by this value
include (${WAMR_ROOT_DIR}/build-scripts/runtime_lib.cmake)
set (WAMR_BUILD_SIMD 1)

The same rule applies to the product-mini platform files and to the top-level CMakeLists.txt: a switch that a platform assigns after its runtime_lib.cmake include overrides the derived value without going through the defaults, the derived switches or the unsupported_combination.cmake checks. The Wasm specification presets WAMR_BUILD_WASM_SPEC1/2/3 are ordinary switches in this respect. The switches can also be passed on the cmake command line instead of a CMakeLists.txt.

Privileged Features are powerful options that can boost performance or add capabilities but lower security by compromising isolation. Use them with care and test thoroughly.

The compilation flags (WAMR_* CMake variables) are resolved in two steps. The top-level CMakeLists.txt of each build entry (and each product-mini platform file) sets each flag for its platform, including that entry's default; cmake -D changes the value it gives. config_common.cmake then applies the flag's own default when it is undefined, handles dependencies and derived values, and translates each flag into a compiler macro (-DWASM_ENABLE_*=1 or =0). For example, WAMR_BUILD_AOT turns on WASM_ENABLE_AOT, and enabling WAMR_BUILD_MEMORY64 also turns on WASM_DISABLE_HW_BOUND_CHECK/WASM_DISABLE_STACK_HW_BOUND_CHECK. config.h gives each macro a fallback default with #ifndef, for builds that do not go through build-scripts (for example NuttX wamr.mk, esp-idf, Zephyr). Every macro needs a default there, and code tests it with #if <MACRO> != 0. #ifdef, #ifndef and defined() are always true for a macro that is defined as 0, so code guarded that way never turns off. -Wundef reports a macro used in #if without a value.

The defaults below are guaranteed by build-scripts itself (config_common.cmake and runtime_lib.cmake) when the vmcore is built through runtime_lib.cmake, regardless of platform — as long as the option is not explicitly set by the user. Defaults supplied by the top-level build entry (the repository root CMakeLists.txt or the product-mini platform files) are out of scope here and are covered by the note below.

On by default (unless disabled):

Conditional defaults (auto-on only when the listed prerequisite is enabled; the prerequisites themselves are usually set by the top-level build entry):

• WAMR_BUILD_PLATFORM: set the target platform. Match the platform folder name under core/shared/platform.

• WAMR_BUILD_TARGET: set the target CPU architecture. Supported targets: X86_64, X86_32, AARCH64, ARM, THUMB, XTENSA, ARC, RISCV32, RISCV64, and MIPS.

  • For ARM and THUMB, use <arch>[<sub-arch>][_VFP]. <sub-arch> is the ARM sub-architecture. _VFP means arguments and returns use VFP coprocessor registers s0-s15 (d0-d7). Both are optional, for example ARMV7, ARMV7_VFP, THUMBV7, or THUMBV7_VFP.
  • For AARCH64, use <arch>[<sub-arch>]. VFP is on by default. <sub-arch> is optional, for example AARCH64, AARCH64V8, or AARCH64V8.1.
  • For RISCV64, use <arch>[_abi]. _abi is optional. Supported: RISCV64, RISCV64_LP64D, and RISCV64_LP64. RISCV64 and RISCV64_LP64D both use LP64D (LP64 with hardware floating-point for FLEN=64). RISCV64_LP64 uses LP64 (integer calling convention only; no hardware floating-point calling convention).
  • For RISCV32, use <arch>[_abi]. _abi is optional. Supported: RISCV32, RISCV32_ILP32D, RISCV32_ILP32F, and RISCV32_ILP32. RISCV32 and RISCV32_ILP32D both use ILP32D (ILP32 with hardware floating-point for FLEN=64). RISCV32_ILP32F uses ILP32F (ILP32 with hardware floating-point for FLEN=32). RISCV32_ILP32 uses ILP32 (integer calling convention only).

cmake -DWAMR_BUILD_PLATFORM=linux -DWAMR_BUILD_TARGET=ARM

• WAMR_BUILD_INTERP=1/0: turn the WASM interpreter on or off.

• WAMR_BUILD_FAST_INTERP=1/0: pick the fast or the classic interpreter. build-scripts defaults it to 0, the classic interpreter; most build entries, including every product-mini platform, set it to 1.

• WAMR_BUILD_AOT=1/0: turn AOT on or off. Defaults to on.
• WAMR_BUILD_WAMR_COMPILER=1/0. It is used to wasm loader and compilation to indictate compiler mode.

Comparing with fast JIT, LLVM JIT covers more architectures and produces better optimized code, but takes longer on cold start.

• WAMR_BUILD_JIT=1/0: turn LLVM JIT on or off. Defaults to off.
• WAMR_BUILD_LAZY_JIT=1/0: turn lazy JIT on or off. Derived from the running mode: on when LLVM JIT or fast JIT is enabled, off otherwise. Setting it explicitly overrides the derived value. With lazy JIT, functions are compiled in background threads before they are called, which can reduce startup time for large modules.

The fast JIT is a lightweight JIT that emits code quickly and tunes hot functions.

• WAMR_BUILD_FAST_JIT=1/0: turn Fast JIT on or off. Defaults to off.
• WAMR_BUILD_FAST_JIT_DUMP=1/0: dump fast JIT compiled code to stdout for debugging. Defaults to off.

Use fast jit as the first tier and LLVM JIT as the second tier.

• With WAMR_BUILD_FAST_JIT=1 and WAMR_BUILD_JIT=1, you get multi-tier JIT. Defaults to off.

• WAMR_BUILD_LIBC_BUILTIN=1/0: build the built-in libc subset for WASM apps. Defaults to on.

• WAMR_BUILD_LIBC_WASI=1/0: build the WASI libc subset for WASM apps. Defaults to on.

• WAMR_BUILD_LIBC_UVWASI=1/0 (Experiment): build the WASI libc subset for WASM apps using uvwasi. Defaults to off.

• WAMR_BUILD_LIBC_EMCC=1/0: build the emcc-compatible libc subset for WASM apps. Defaults to off.

• WAMR_BUILD_MULTI_MODULE=1/0, default to off.

• WAMR_BUILD_MINI_LOADER=1/0, default to off.

• WAMR_BUILD_SHARED_MEMORY=1/0, default to off.

• WAMR_BUILD_BULK_MEMORY=1/0, default to on.

• WAMR_BUILD_MEMORY64=1/0, default to off.

• WAMR_BUILD_THREAD_MGR=1/0, default to off.

• WAMR_BUILD_LIB_PTHREAD=1/0, default to off.

• WAMR_BUILD_LIB_PTHREAD_SEMAPHORE=1/0, default to off.

• WAMR_BUILD_LIB_WASI_THREADS=1/0, default to off.

• WAMR_BUILD_WASI_NN=1/0, default to off.
• WAMR_BUILD_WASI_NN_LLAMACPP=1/0, default to off.
• WAMR_BUILD_WASI_NN_ONNX=1/0, default to off.
• WAMR_BUILD_WASI_NN_OPENVINO=1/0, default to off.
• WAMR_BUILD_WASI_NN_TFLITE=1/0, default to off.

• WAMR_BUILD_WASI_NN_ENABLE_GPU=1/0, default to off.

• WAMR_BUILD_WASI_NN_ENABLE_EXTERNAL_DELEGATE=1/0, default to off.

• WAMR_BUILD_WASI_NN_EXTERNAL_DELEGATE_PATH=Path to the external delegate shared library (for example libedgetpu.so.1.0 for Coral USB).

• WAMR_BUILD_WASI_EPHEMERAL_NN=1/0, default to on.

• WAMR_DISABLE_HW_BOUND_CHECK=1/0, default to on if the platform supports it. Otherwise, software boundary checks are used.

• WAMR_DISABLE_STACK_HW_BOUND_CHECK=1/0, default to on if the platform supports it; same rule as WAMR_DISABLE_HW_BOUND_CHECK. Otherwise, software boundary checks are used.

• WAMR_DISABLE_WAKEUP_BLOCKING_OP=1/0, default to on when the platform supports it.

• WAMR_BUILD_TAIL_CALL=1/0, default to off. Supported in classic-interpreter, fast-interpreter, AOT and LLVM JIT modes.

• WAMR_BUILD_SIMD=1/0, default to on.

SIMD is supported in AOT, LLVM JIT, and fast-interpreter modes. In fast-interpreter mode, SIMD operations are implemented with the SIMDe (SIMD Everywhere) library, which is fetched and enabled automatically — no extra flag is needed.

The SIMDe library is pulled in automatically when both WAMR_BUILD_SIMD and WAMR_BUILD_FAST_INTERP are enabled (except on Windows, where SIMDe is not supported). WAMR_BUILD_SIMDE/WAMR_BUILD_LIB_SIMDE are not user switches and do not need to be set.

• WAMR_BUILD_EXCE_HANDLING=1/0, default to off.

• WAMR_BUILD_GC=1/0, default to off.
• WAMR_BUILD_GC_HEAP_VERIFY=1/0, default to off. When enabled, verifies the heap during free.

• WAMR_BUILD_STRINGREF=1/0, defaults to whatever WAMR_BUILD_GC is.
• WAMR_STRINGREF_IMPL_SOURCE=STUB/<path>: the stringref implementation to link against, STUB for the builtin one. Defaults to STUB when stringref is on.

• WAMR_BUILD_GC_HEAP_SIZE_DEFAULT=n, default to 128 kB (131072).

• WAMR_BUILD_MULTI_MEMORY=1/0, default to off.

• WAMR_BUILD_CUSTOM_NAME_SECTION=1/0: load function names from the custom name section. Default is off.

• WAMR_BUILD_AOT_STACK_FRAME=1/0, default to off.

• WAMR_BUILD_DUMP_CALL_STACK=1/0, default to off.

• WAMR_BUILD_MEMORY_PROFILING=1/0, default to off.

• WAMR_BUILD_MEMORY_TRACING=1/0, default to off.

• WAMR_BUILD_PERF_PROFILING=1/0, default to off.

• WAMR_BUILD_GLOBAL_HEAP_POOL=1/0, default to off for iwasm apps except on Alios and Zephyr.
• WAMR_BUILD_GLOBAL_HEAP_SIZE=n, default to 10 MB (10485760) for iwasm apps, except Alios (256 kB), Riot (256 kB), and Zephyr (128 kB).

• WAMR_APP_THREAD_STACK_SIZE_MAX=n, default to 8 MB (8388608).

• WAMR_BH_VPRINTF=<vprintf_callback>, default to off.

int my_vprintf(const char *format, va_list ap)
{
    /* output to pre-opened file stream */
    FILE *my_file = ...;
    return vfprintf(my_file, format, ap);
    /* or output to pre-opened file descriptor */
    int my_fd = ...;
    return vdprintf(my_fd, format, ap);
    /* or output to string buffer and print the string */
    char buf[128];
    vsnprintf(buf, sizeof(buf), format, ap);
    return my_printf("%s", buf);
}

void my_log(uint32 log_level, const char *file, int line, const char *fmt, ...)
{
    /* Usage of custom logger */
}

• WAMR_BUILD_REF_TYPES=1/0, default to on.

• WAMR_DISABLE_APP_ENTRY=1/0, default to off.

• WAMR_BUILD_DEBUG_INTERP=1/0, default to off.
• WAMR_BUILD_DEBUG_AOT=1/0, default to off.
• WAMR_BUILD_DYNAMIC_AOT_DEBUG=1/0, default to off.

• WAMR_BUILD_LOAD_CUSTOM_SECTION=1/0, default to off.

• WAMR_BUILD_STACK_GUARD_SIZE=n, default to N/A when not set.

• WAMR_DISABLE_WRITE_GS_BASE=1/0, default to on if the platform supports it.

• WAMR_BUILD_ALLOC_WITH_USAGE=1/0, default to off.
• WAMR_BUILD_ALLOC_WITH_USER_DATA=1/0, default to off.

• WAMR_BUILD_STATIC_PGO=1/0, default to off.

• WAMR_BUILD_LINUX_PERF=1/0: enable linux perf support to generate flamegraphs for wasm app performance. Default is off.

• WAMR_BUILD_MODULE_INST_CONTEXT=1/0: enable module instance context APIs so the embedder can set one or more contexts for a wasm module instance. Default is off, but it is turned on automatically when WASI libc (WAMR_BUILD_LIBC_WASI/WAMR_BUILD_LIBC_UVWASI) or WAMR_BUILD_WASI_NN is enabled (so it is on in default iwasm builds).

    wasm_runtime_create_context_key
    wasm_runtime_destroy_context_key
    wasm_runtime_set_context
    wasm_runtime_set_context_spread
    wasm_runtime_get_context

• WAMR_BUILD_QUICK_AOT_ENTRY=1/0: register quick call entries to speed up AOT/JIT function calls. Derived from the running mode: on when AOT or LLVM JIT is enabled, off otherwise. Setting it explicitly overrides the derived value. Non-CMake builds say it in their own build files, next to their AOT sources: product-mini/platforms/alios-things/aos.mk, the CONFIG_INTERPRETERS_WAMR_AOT_QUICK_ENTRY option of product-mini/platforms/nuttx/wamr.mk, and build-scripts/SConscript_config (rt-thread).

• WAMR_BUILD_AOT_INTRINSICS=1/0: turn on AOT intrinsic functions. Derived from the running mode: on when AOT is enabled, off otherwise. Setting it explicitly overrides the derived value. AOT code can call these when wamrc uses --disable-llvm-intrinsics or --enable-builtin-intrinsics=<intr1,intr2,...>. Non-CMake builds say it in their own build files, next to their AOT sources: product-mini/platforms/alios-things/aos.mk, the CONFIG_INTERPRETERS_WAMR_AOT block of product-mini/platforms/nuttx/wamr.mk, and build-scripts/SConscript_config (rt-thread).

• WAMR_BUILD_EXTENDED_CONST_EXPR=1/0, default to off. It is also enabled automatically when WAMR_BUILD_LIME1 is on.

• WAMR_BUILD_BULK_MEMORY_OPT=1/0, default to off. Enabled automatically when WAMR_BUILD_BULK_MEMORY or WAMR_BUILD_LIME1 is on.

• WAMR_BUILD_CALL_INDIRECT_OVERLONG=1/0, default to off, but it is enabled automatically when reference types (WAMR_BUILD_REF_TYPES, default on) are on. The minimal Lime1 feature set also enables it.

• WAMR_BUILD_LIME1=1/0, default to off.

• WAMR_BUILD_WASM_SPEC1=1/0, default to off. Wasm 1.0 preset.
• WAMR_BUILD_WASM_SPEC2=1/0, default to off. Wasm 2.0 preset.
• WAMR_BUILD_WASM_SPEC3=1/0, default to off. Not supported yet, see below.

The three switches turn one Wasm specification version into a single option.

A preset states which proposals a version requires and which ones it excludes. It owns the switches it turns on, and it turns off the excluded ones ahead of the compatibility defaults, so a version is a version no matter what the build entry point ships by default (see features enabled by default).

A preset describes a complete feature set, so it has two directions:

• a feature the preset does not exclude, asked for on top of it, is kept: -DWAMR_BUILD_WASM_SPEC2=1 -DWAMR_BUILD_TAIL_CALL=1 builds Wasm 2.0 plus tail call;
• a feature the preset excludes is turned off even when the caller turned it on, and configure prints a warning saying whether that value came from -D/a CMake preset or from an entry point's own default. Wasm 1.0 and Lime1 exclude bulk memory, reference types and SIMD.

Drop the preset if you want to be sure nothing else is on, or check the "About Wasm Proposals" status that config_common.cmake prints.

WAMR_BUILD_WASM_SPEC2 does not imply WAMR_BUILD_WASM_SPEC1, and setting both fails the configure step: each one is a complete feature set rather than a layer on top of the other.

• WAMR_BUILD_WASM_SPEC3 is not supported yet. WAMR does not implement Wasm 3.0 completely, so a Wasm 3.0 preset would not be a Wasm 3.0 runtime. Setting WAMR_BUILD_WASM_SPEC3=1 is a configuration error: it fails the configure step with the list of missing and limited Wasm 3.0 proposals, and applies no preset at all. Setting it to 0 does nothing and configure continues as usual. Build the Wasm 3.0 features you need individually on top of WAMR_BUILD_WASM_SPEC2=1, for example -DWAMR_BUILD_TAIL_CALL=1; each one has its own section below that documents its running mode support.

A preset and WAMR_BUILD_LIME1 are mutually exclusive: LIME1 is a profile of its own, so setting any WAMR_BUILD_WASM_SPEC<N> together with WAMR_BUILD_LIME1 fails the configure step.

WAMR_BUILD_WASM_SPEC2=1 is also rejected by unsupported_combination.cmake in the running modes that SIMD does not support:

cmake .. -DWAMR_BUILD_WASM_SPEC2=1 -DWAMR_BUILD_FAST_INTERP=0 -DWAMR_BUILD_AOT=0
# Unsupported build configuration: SIMD + CLASSIC_INTERP

• WAMR_CONFIGURABLE_BOUNDS_CHECKS=1/0, default to off.

• WAMR_BUILD_SHARED_HEAP=1/0, default to off.

   wasm_runtime_create_shared_heap
   wasm_runtime_attach_shared_heap
   wasm_runtime_detach_shared_heap
   wasm_runtime_shared_heap_malloc
   wasm_runtime_shared_heap_free

   void *shared_heap_malloc();
   void shared_heap_free(void *ptr);

• WAMR_BUILD_SHRUNK_MEMORY=1/0, default to on.

• WAMR_BUILD_INSTRUCTION_METERING=1/0, default to off.

• WAMR_BUILD_BRANCH_HINTS=1/0, default to disable if not set

• WAMR_BUILD_INVOKE_NATIVE_GENERAL=1/0, default to off.

By default, WAMR uses architecture-specific calling conventions to call native functions from WASM modules. When this feature is enabled, WAMR uses a general calling convention that works on all architectures but is slower. The details are in iwasm_common.cmake

• WAMR_BH_LOG=<log_callback>, default to off.

• WAMR_BUILD_AOT_VALIDATOR=1/0, default to off.

• WAMR_BUILD_COPY_CALL_STACK=1/0, default to off.

• WAMR_BUILD_LIB_RATS=1/0, default to off.

librats is a C library designed to facilitate remote attestation for secure computing environments. It provides a framework for attesting the integrity of computing environments remotely, enabling trust establishment between different Trusted Execution Environments (TEEs).

• WAMR_BUILD_SANITIZER=[ubsan|asan|tsan|posan], default is empty

Use one or more of the following sanitizers when building WAMR with sanitizer support: AddressSanitizer, UndefinedBehaviorSanitizer, ThreadSanitizer, or Pointer-Overflow Sanitizer.

• WAMR_BUILD_SGX_IPFS=1/0, default to off.

• WAMR_BUILD_SPEC_TEST=1/0, default to off.

• WAMR_BUILD_WASM_CACHE=1/0, default to off.

• WAMR_TEST_GC=1/0, default to off.

It is used to test garbage collection related APIs and features. Refer to iwasm_gc.cmake for details.

It is used to cache loaded wasm modules in memory to speed up module instantiation only in wasm-c-api.

You can mix settings. For example, to disable the interpreter, enable AOT and WASI, run:

cmake .. -DWAMR_BUILD_INTERP=0 -DWAMR_BUILD_AOT=1 -DWAMR_BUILD_LIBC_WASI=1 -DWAMR_BUILD_PLATFORM=linux

To enable the interpreter, disable AOT and WASI, and target X86_32, run:

cmake .. -DWAMR_BUILD_INTERP=1 -DWAMR_BUILD_AOT=0 -DWAMR_BUILD_LIBC_WASI=0 -DWAMR_BUILD_TARGET=X86_32

When enabling SIMD for fast interpreter mode, turn on both SIMD and the SIMDe library:

cmake .. -DWAMR_BUILD_INTERP=1 -DWAMR_BUILD_FAST_INTERP=1 -DWAMR_BUILD_SIMD=1 -DWAMR_BUILD_LIB_SIMDE=1

For Valgrind, start with these and add more as needed:

  #...
  -DCMAKE_BUILD_TYPE=Debug \
  -DWAMR_DISABLE_HW_BOUND_CHECK=0 \
  -DWAMR_DISABLE_WRITE_GS_BASE=0
  #...

To build the minimal Lime1 feature set, just ask for it: LIME1 turns on bulk-memory-opt, call-indirect-overlong and extended constant expressions, and turns off bulk memory, reference types and SIMD. Naming the three =0 explicitly is still accepted and does not warn:

cmake .. -DWAMR_BUILD_LIME1=1

To build for a whole Wasm specification version, use the preset switches. A preset turns the excluded switches off ahead of the compatibility defaults, so the command below is a Wasm 1.0 build whatever the entry point ships by default.

# Wasm 1.0
cmake .. -DWAMR_BUILD_WASM_SPEC1=1

# Wasm 2.0 (the interpreter mode must be a mode that supports SIMD)
cmake .. -DWAMR_BUILD_WASM_SPEC2=1 -DWAMR_BUILD_INTERP=1 -DWAMR_BUILD_FAST_INTERP=1

# Wasm 3.0 has no preset yet: WAMR_BUILD_WASM_SPEC3=1 fails the configure step.
# Ask for the individual Wasm 3.0 features instead, for example:
cmake .. -DWAMR_BUILD_WASM_SPEC2=1 -DWAMR_BUILD_TAIL_CALL=1 -DWAMR_BUILD_GC=1

See Wasm specification version preset for what each version enables and for the parts of Wasm 3.0 that WAMR does not implement.

• WAMR_BUILD_LOG=1/0, default to on. Turns the runtime log system (WASM_ENABLE_LOG) on or off. The macro is read by the product-mini executables rather than by the vmcore, so turning it off mainly shrinks iwasm itself.

• WAMR_BUILD_OPCODE_COUNTER=1/0, default to off. Counts the executed opcodes. Only has an effect when WAMR_BUILD_FAST_INTERP is on, which is the only place the macro is read.

• WAMR_BUILD_WORD_ALIGN_READ=1/0, default to off. Reads the AOT file through word aligned accesses, for targets that fault on unaligned loads.

• WAMR_BUILD_BASE_LIB=1/0, default to off.
• WAMR_BUILD_APP_FRAMEWORK=1/0, default to off.

• WAMR_BUILD_FUZZ_TEST=1/0, default to off. Caps the memory allocator so the runtime stays inside the memory budget of a fuzzing host. Only meant for the fuzzing targets under tests/fuzz.