doc/build_wamr.md
WAMR vmcore is the runtime library set that loads and runs Wasm modules. This guide walks you through building the WAMR vmcore.
References:
Include the script runtime_lib.cmake from build-scripts into your CMakeLists.txt to pull vmcore into your build.
# add this into your CMakeLists.txt
include (${WAMR_ROOT_DIR}/build-scripts/runtime_lib.cmake)
add_library(vmlib ${WAMR_RUNTIME_LIB_SOURCE})
The runtime_lib.cmake script exposes variables that control WAMR runtime features. Set them in CMakeLists.txt or pass them on the cmake command line.
# Set flags in CMakeLists.txt
set(WAMR_BUILD_AOT 1)
set(WAMR_BUILD_JIT 0)
set(WAMR_BUILD_LIBC_BUILTIN 1)
set(WAMR_BUILD_LIBC_WASI 1)
# Include the runtime lib script
include (${WAMR_ROOT_DIR}/build-scripts/runtime_lib.cmake)
add_library(vmlib ${WAMR_RUNTIME_LIB_SOURCE})
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.
Above compilation flags map to macros in config.h. For example, WAMR_BUILD_AOT maps to WAMR_BUILD_AOT in config.h. The build system sets these macros automatically based on your CMake settings. If your build doesn't set those flags, default values in config.h apply.
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.
<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.<arch>[<sub-arch>]. VFP is on by default. <sub-arch> is optional, for example AARCH64, AARCH64V8, or AARCH64V8.1.<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).<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 fast (default) or classic interpreter.
[!NOTE] The fast interpreter runs ~2X faster than classic interpreter, but consumes about 2X memory to hold the pre-compiled code.
Comparing with fast JIT, LLVM JIT covers more architectures and produces better optimized code, but takes longer on cold start.
The fast JIT is a lightweight JIT that emits code quickly and tunes hot functions.
[!WARNING] It currently covers only a few architectures (x86_64).
Use fast jit as the first tier and LLVM JIT as the second tier.
[!WARNING] It currently covers only a few architectures (x86_64).
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.
[!WARNING] WAMR is not a secure sandbox on every platform. On platforms where WAMR_BUILD_LIBC_WASI is unsupported (for example Windows), you can try the uvwasi-based WASI via WAMR_BUILD_LIBC_UVWASI, but it is unsafe.
[!NOTE] See Multiple Modules as Dependencies for details.
[!WARNING] The multi-module feature is not supported in fast-jit or llvm-jit modes.
[!NOTE] The mini loader skips integrity checks on the WASM binary. Make sure the file is valid yourself.
[!WARNING] This is a privileged feature that compromises security. Use it only when you trust the WASM binary source.
[!WARNING] Supported only in classic interpreter mode and AOT mode.
[!NOTE] When you enable lib pthread, required features such as
shared memoryandthread managerare enabled automatically. See WAMR pthread library for details.
[!NOTE] This depends on
lib-pthreadand turns it on automatically.
[!NOTE] Enabling lib wasi-threads also enables its dependencies
shared memoryandthread manager. See wasi-threads and Introduction to WAMR WASI threads for details.
[!NOTE] Using WAMR_BUILD_WASI_NN without WAMR_BUILD_WASI_EPHEMERAL_NN is deprecated and may be removed later. Please enable WAMR_BUILD_WASI_EPHEMERAL_NN too. See WASI-NN for details.
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).
wasi_ephemeral_nn module support[!NOTE] By default only linux/darwin/android/windows/vxworks 64-bit platforms enable this hardware trap boundary check. On 32-bit platforms it is off even if the flag is 0. The wamrc tool omits boundary check instructions in AOT code for all 64-bit targets except SGX to improve speed. The boundary check covers linear memory access and native stack access unless
WAMR_DISABLE_STACK_HW_BOUND_CHECKis set.
WAMR_DISABLE_HW_BOUND_CHECK. Otherwise, software boundary checks are used.[!NOTE] If hardware trap boundary checks are off (or
WAMR_DISABLE_HW_BOUND_CHECKis 1), native stack boundary checks are also off regardless ofWAMR_DISABLE_STACK_HW_BOUND_CHECK. If hardware trap boundary checks are on, this setting decides whether the native stack check is on.
[!NOTE] This feature lets blocking threads terminate asynchronously. If you disable it, blocking threads may never finish when asked to exit.
SIMDE (SIMD Everywhere) implements SIMD operations in fast interpreter mode.
[!WARNING] Supported in AOT, JIT, and fast-interpreter modes with the SIMDe library.
[!NOTE] When enabled, SIMDe (SIMD Everywhere) implements SIMD operations in fast interpreter mode.
[!NOTE] Current implementation supports only Legacy Wasm exception handling proposal, not the latest version.
[!WARNING] Exception handling currently works only in classic interpreter mode.
[!WARNING] Current implentation of Garbage Collection(GC) is not fully compliant with the Wasm GC proposal and Wasm 3.0 specification. There are still few known limitations:
exnandnoexntypes are not supported.- nested structs and arrays are not fully supported.
Garbage collection is not supported in fast-jit mode and multi-tier-jit mode.
[!WARNING] Multi memory is supported only in classic interpreter mode.
[!NOTE] When enabled, AOT or JIT stack frames (similar to classic interpreter frames but storing only what is needed) are built during calls. Add
--enable-dump-call-stackto wamrc when compiling AOT modules.
[!NOTE] When enabled, the runtime dumps the call stack on exceptions.
- In interpreter mode, names come first from the custom name section. If that section is absent or disabled, names come from import/export sections.
- In AOT/JIT mode, names come from the import/export section. Export as many functions as possible (for
wasi-sdkyou can use-Wl,--export-all) when compiling the wasm module, and add--enable-dump-call-stack --emit-custom-sections=nameto wamrc when compiling the AOT module.
[!NOTE] When enabled, call
void wasm_runtime_dump_mem_consumption(wasm_exec_env_t exec_env)to dump memory usage. Currently only module, module_instance, and exec_env memory are measured; other components such aswasi-ctx,multi-module, andthread-managerare not included. See Memory usage estimation for a module.
[!NOTE] When enabled, call
void wasm_runtime_dump_perf_profiling(wasm_module_inst_t module_inst)to dump per-function performance. Function name lookup follows the same order as the dump call stack feature. See Tune the performance of running wasm/aot file.
[!NOTE] When enabled, WAMR uses a big global heap for runtime and wasm apps instead of allocating memory from the system directly. This can reduce memory fragmentation and improve performance when many small allocations happen. The global heap is allocated at startup. WAMR_BUILD_GLOBAL_HEAP_POOL applies to iwasm apps in
product-mini. For your own host app, setmem_alloc_typetoAlloc_With_Poolif you want to use a global heap. The global heap is described in Memory model and memory usage tunning. WAMR_BUILD_GLOBAL_HEAP_SIZE applies to iwasm apps inproduct-mini. For your host app, setmem_alloc_option.poolwith the size you want for the global heap. The global heap is described in Memory model and memory usage tunning.
[!NOTE] AOT boundary checks with hardware traps may use large stacks because the OS can grow stacks lazily when a guard page is hit. Use this setting to cap total stack use, for example
-DWAMR_APP_THREAD_STACK_SIZE_MAX=131072(128 KB).
[!NOTE] If you provide
vprintf_callback,os_printf()andos_vprintf()on Linux, Darwin, Windows, VxWorks, Android, and esp-idf, plus WASI libc output, call your callback instead of libcvprintf(). Example outside the runtime lib:Cint 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); }Then run
cmake -DWAMR_BH_VPRINTF=my_vprintf .., or add the compiler macroBH_VPRINTF=my_vprintf(for exampleadd_definitions(-DBH_VPRINTF=my_vprintf)in CMakeLists.txt). See basic sample for an example.
[!NOTE] If you provide
log_callback, WAMR logs go there. Example:Cvoid my_log(uint32 log_level, const char *file, int line, const char *fmt, ...) { /* Usage of custom logger */ }See basic sample for an example.
[!NOTE] The WAMR application entry (
core/iwasm/common/wasm_application.c) wraps common steps to instantiate and run wasm functions and print results. These use platform APIs. this flag to skip the file if your platform lacks those APIs. Do not enable this flag when buildingproduct-mini.
[!NOTE] Source debugging needs extra setup. See source_debugging.md and WAMR source debugging basic.
[!NOTE] By default, custom sections are ignored.
WAMR_BUILD_LOAD_CUSTOM_SECTIONso the embedder can read them viawasm_runtime_get_custom_section. IfWAMR_BUILD_CUSTOM_NAME_SECTIONis on, the custom name section is consumed by the runtime and unavailable to the embedder. For AoT files, pass--emit-custom-sectionsto wamrc to keep the sections; otherwise they are dropped.
[!NOTE] By default, stack guard size is 1K (1024) or 24K when uvwasi is enabled.
[!NOTE] By default only linux x86-64 enables this. On 32-bit platforms it stays off even if set to 0. On linux x86-64, writing the linear memory base to the GS segment can speed up linear memory access for LLVM AOT/JIT when
--enable-segue=[<flags>]is passed towamrcoriwasm.See segue optimization for wamrc when generating the aot file for details.
[!NOTE] By default, the system allocates linear memory. With this on and
Alloc_With_Allocatorselected, you can provide your own allocator.
[!NOTE] See Use the AOT static PGO method.
[!NOTE] See Use linux-perf.
wasm_runtime_create_context_key
wasm_runtime_destroy_context_key
wasm_runtime_set_context
wasm_runtime_set_context_spread
wasm_runtime_get_context
[!NOTE] See wasm_export.h for details.
[!NOTE] See Refine callings to AOT/JIT functions from host native.
--disable-llvm-intrinsics or --enable-builtin-intrinsics=<intr1,intr2,...>.[!NOTE] See Tuning the XIP intrinsic functions.
[!NOTE] See Extended Constant Expressions.
[!NOTE] See bulk-memory-opt.
[!NOTE] See call-indirect-overlong.
[!NOTE] See Lime1.
[!WARNING] When enabled, you can run
iwasm --disable-bounds-checksto turn off memory access boundary checks in interpreter mode. This is a privileged feature; use it carefully.
[!NOTE] When enabled, you can create and attach shared heaps, and the following APIs become available:
Cwasm_runtime_create_shared_heap wasm_runtime_attach_shared_heap wasm_runtime_detach_shared_heap wasm_runtime_shared_heap_malloc wasm_runtime_shared_heap_freeA wasm app can call these to use the shared heap attached to its module instance:
Cvoid *shared_heap_malloc(); void shared_heap_free(void *ptr);
[!WARNING] The shared-heap feature is not supported in fast-jit mode.
[!NOTE] When enabled, this reduces memory by shrinking linear memory, especially when
memory.growis unused and memory needs are predictable.
[!NOTE] This limits the number of instructions a wasm module instance can run. Call
wasm_runtime_set_instruction_count_limit(...)beforewasm_runtime_call_*(...)to enforce the cap.
[!WARNING] This is only supported in classic interpreter mode.
[!NOTE] Enabling this feature allows the runtime to utilize branch hints for better performance during aot/jit execution.
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
[!NOTE] By default, WAMR believes AOT files are valid and unforged.
[!NOTE] Unlike dump call stack, which prints the call stack on exceptions, this feature lets the embedder copy the call stack programmatically via
wasm_runtime_dump_call_stack_to_buf().
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).
[!WARNING] This is for Intel SGX platforms only.
Use one or more of the following sanitizers when building WAMR with sanitizer support: AddressSanitizer, UndefinedBehaviorSanitizer, ThreadSanitizer, or Pointer-Overflow Sanitizer.
[!WARNING] This is for Intel SGX platforms only.
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 enable the minimal Lime1 feature set, turn off features that are on by default such as bulk memory and reference types:
cmake .. -DWAMR_BUILD_LIME1=1 -DWAMR_BUILD_BULK_MEMORY=0 -DWAMR_BUILD_REF_TYPES=0 -DDWAMR_BUILD_SIMD=0