diff --git a/doc/build_wamr.md b/doc/build_wamr.md index 2cb3f45aaa..916110d754 100644 --- a/doc/build_wamr.md +++ b/doc/build_wamr.md @@ -1,35 +1,141 @@ # Build WAMR vmcore -WAMR vmcore is a set of runtime libraries for loading and running Wasm modules. This document introduces how to build the WAMR vmcore. +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](../product-mini/README.md): building different target platforms such as Linux, Windows, Mac etc +- [how to build iwasm](../product-mini/README.md): build for Linux, Windows, macOS, and more - [Blog: Introduction to WAMR running modes](https://bytecodealliance.github.io/wamr.dev/blog/introduction-to-wamr-running-modes/) -## WAMR vmcore cmake building configurations +## building configurations -By including the script `runtime_lib.cmake` under folder [build-scripts](../build-scripts) in CMakeList.txt, it is easy to use vmcore to build host software with cmake. +Drop the script `runtime_lib.cmake` from [build-scripts](../build-scripts) into your CMakeLists.txt to pull vmcore into your build. ```cmake -# add this into your CMakeList.txt +# add this into your CMakeLists.txt include (${WAMR_ROOT_DIR}/build-scripts/runtime_lib.cmake) add_library(vmlib ${WAMR_RUNTIME_LIB_SOURCE}) ``` -The script `runtime_lib.cmake` defines a number of variables for configuring the WAMR runtime features. You can set these variables in your CMakeList.txt or pass the configurations from cmake command line. +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. -Please refer to [a full list of configuration options](./tired_support.md#appendix-all-compilation-flags). +```cmake +# 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}) +``` + +### All compilation flags + +| Compilation flags | Description | +| -------------------------------------------------------------------------------------------------------- | ------------------------------------ | +| [WAMR_APP_THREAD_STACK_SIZE_MAX](#set-maximum-app-thread-stack-size) | Maximum stack size for app threads | +| [WAMR_BH_LOG](#host-defined-log) | Host defined logging | +| [WAMR_BH_VPRINTF](#host-defined-vprintf) | Host defined vprintf | +| [WAMR_BUILD_ALLOC_WITH_USAGE](#user-defined-linear-memory-allocator) | Allocation with usage tracking | +| [WAMR_BUILD_ALLOC_WITH_USER_DATA](#user-defined-linear-memory-allocator) | Allocation with user data | +| [WAMR_BUILD_AOT](#configure-aot) | AoT compilation(wamrc) | +| [WAMR_BUILD_AOT](#configure-aot) | AoT runtime | +| [WAMR_BUILD_AOT_INTRINSICS](#aot-intrinsics) | AoT intrinsics | +| [WAMR_BUILD_AOT_STACK_FRAME](#aot-stack-frame-feature) | AoT stack frame | +| [WAMR_BUILD_AOT_VALIDATOR](#aot-validator) | AoT validator | +| [WAMR_BUILD_BULK_MEMORY](#bulk-memory-feature) | bulk memory | +| [WAMR_BUILD_COPY_CALL_STACK](#copy-call-stack) | copy call stack | +| [WAMR_BUILD_CUSTOM_NAME_SECTION](#name-section) | name section | +| [WAMR_BUILD_DEBUG_AOT](#source-debugging-features) | debug AoT | +| [WAMR_BUILD_DEBUG_INTERP](#source-debugging-features) | debug interpreter | +| [WAMR_BUILD_DUMP_CALL_STACK](#dump-call-stack-feature) | dump call stack | +| [WAMR_BUILD_DYNAMIC_AOT_DEBUG](#source-debugging-features) | dynamic AoT debugging | +| [WAMR_BUILD_EXCE_HANDLING](#exception-handling) | exception handling | +| [WAMR_BUILD_EXTENDED_CONST_EXPR](#extended-constant-expression) | extended constant expressions | +| [WAMR_BUILD_FAST_INTERP](#configure-interpreters) | fast interpreter | +| [WAMR_BUILD_FAST_JIT](#configure-fast-jit) | fast JIT | +| [WAMR_BUILD_FAST_JIT_DUMP](#configure-fast-jit) | fast JIT dump | +| [WAMR_BUILD_GC](#garbage-collection) | garbage collection | +| [WAMR_BUILD_GC_HEAP_VERIFY](#garbage-collection) | garbage collection heap verification | +| [WAMR_BUILD_GC_HEAP_SIZE_DEFAULT](garbage-collection) | default garbage collection heap size | +| [WAMR_BUILD_GLOBAL_HEAP_POOL](#a-pre-allocation-for-runtime-and-wasm-apps) | global heap pool | +| [WAMR_BUILD_GLOBAL_HEAP_SIZE](#a-pre-allocation-for-runtime-and-wasm-apps) | global heap size | +| [WAMR_BUILD_INSTRUCTION_METERING](#instruction-metering) | instruction metering | +| [WAMR_BUILD_INTERP](#configure-interpreters) | interpreter | +| [WAMR_BUILD_INVOKE_NATIVE_GENERAL](#invoke-general-ffi) | FFI general | +| [WAMR_BUILD_JIT](#configure-llvm-jit) | JIT compilation | +| [WAMR_BUILD_LAZY_JIT](#configure-llvm-jit) | lazy JIT compilation | +| [WAMR_BUILD_LIBC_BUILTIN](#configure-libc) | libc builtin functions | +| [WAMR_BUILD_LIBC_EMCC](#configure-libc) | libc emcc compatibility | +| [WAMR_BUILD_LIBC_UVWASI](#configure-libc) | libc uvwasi compatibility | +| [WAMR_BUILD_LIBC_WASI](#configure-libc) | wasi libc | +| [WAMR_BUILD_LIB_PTHREAD](#lib-pthread) | pthread library | +| [WAMR_BUILD_LIB_PTHREAD_SEMAPHORE](#lib-pthread-semaphore) | pthread semaphore support | +| [WAMR_BUILD_LIB_RATS](#librats) | RATS library | +| [WAMR_BUILD_LIB_WASI_THREADS](#lib-wasi-threads) | wasi threads | +| [WAMR_BUILD_LINUX_PERF](#linux-perf-support) | Linux performance counters | +| [WAMR_BUILD_LIME1](#lime1-target) | LIME1 runtime | +| [WAMR_BUILD_LOAD_CUSTOM_SECTION](#load-wasm-custom-sections) | loading custom sections | +| [WAMR_BUILD_MEMORY64](#memory64-feature) | memory64 support | +| [WAMR_BUILD_MEMORY_PROFILING](#memory-profiling-experiment) | memory profiling | +| [WAMR_BUILD_MINI_LOADER](#wasm-mini-loader) :warning: :exclamation: | mini loader | +| [WAMR_BUILD_MODULE_INST_CONTEXT](#module-instance-context-apis) | module instance context | +| [WAMR_BUILD_MULTI_MEMORY](#multi-memory) | multi-memory support | +| [WAMR_BUILD_MULTI_MODULE](#multi-module-feature) | multi-module support | +| [WAMR_BUILD_PERF_PROFILING](#performance-profiling-experiment) | performance profiling | +| [WAMR_BUILD_PLATFORM](#configure-platform-and-architecture) | Default platform | +| [WAMR_BUILD_QUICK_AOT_ENTRY](#quick-aotjti-entries) | quick AOT entry | +| [WAMR_BUILD_REF_TYPES](#reference-types-feature) | reference types | +| [WAMR_BUILD_SANITIZER](#sanitizer) | sanitizer | +| [WAMR_BUILD_SGX_IPFS](#intel-protected-file-system) | Intel Protected File System support | +| [WAMR_BUILD_SHARED_HEAP](#shared-heap-among-wasm-apps-and-host-native) | shared heap | +| [WAMR_BUILD_SHARED_MEMORY](shared-memory-feature) | shared memory | +| [WAMR_BUILD_SHRUNK_MEMORY](#shrunk-the-memory-usage) | shrunk memory | +| [WAMR_BUILD_SIMD](#128-bit-simd-feature) | SIMD support | +| [WAMR_BUILD_SIMDE](#128-bit-simd-feature) | SIMD E extensions | +| [WAMR_BUILD_SPEC_TEST](#support-spec-test) | spec test | +| [WAMR_BUILD_STACK_GUARD_SIZE](#stack-guard-size) | Stack guard size | +| [WAMR_BUILD_STATIC_PGO](running-pgoprofile-guided-optimization-instrumented-aot-file) | Static PGO | +| [WAMR_BUILD_STRINGREF](#garbage-collection) | String reference support | +| [WAMR_BUILD_TAIL_CALL](#tail-call-feature) | Tail call optimization | +| [WAMR_BUILD_TARGET](#configure-platform-and-architecture) | Default target architecture | +| [WAMR_BUILD_THREAD_MGR](#thread-manager) | Thread manager | +| [WAMR_BUILD_WAMR_COMPILER](#configure-aot) | WAMR compiler | +| [WAMR_BUILD_WASI_EPHEMERAL_NN](#lib-wasi-nn-with-wasi_ephemeral_nn-module-support) | WASI ephemeral NN | +| [WAMR_BUILD_WASI_NN](#lib-wasi-nn) | WASI NN | +| [WAMR_BUILD_WASI_NN_EXTERNAL_DELEGATE_PATH](#lib-wasi-nn-external-delegate-mode) | External delegate path for WASI NN | +| [WAMR_BUILD_WASI_NN_ENABLE_GPU](#lib-wasi-nn-gpu-mode) | GPU support for WASI NN | +| [WAMR_BUILD_WASI_NN_LLAMACPP](#lib-wasi-nn) | LLAMA CPP for WASI NN | +| [WAMR_BUILD_WASI_NN_ONNX](#lib-wasi-nn) | ONNX for WASI NN | +| [WAMR_BUILD_WASI_NN_OPENVINO](#lib-wasi-nn) | OpenVINO for WASI NN | +| [WAMR_BUILD_WASI_NN_TFLITE](#lib-wasi-nn) | TFLite for WASI NN | +| [WAMR_BUILD_WASM_CACHE](#wasm-cache) | WASM cache | +| [WAMR_CONFIGURABLE_BOUNDS_CHECKS](#configurable-memory-access-boundary-check) :warning: :exclamation: | Configurable bounds checks | +| [WAMR_DISABLE_APP_ENTRY](#exclude-wamr-application-entry-functions) | Disable app entry | +| [WAMR_DISABLE_HW_BOUND_CHECK](#disable-boundary-check-with-hardware-trap) | Disable hardware bound check | +| [WAMR_DISABLE_STACK_HW_BOUND_CHECK](#disable-native-stack-boundary-check-with-hardware-trap) | Disable stack hardware bound check | +| [WAMR_DISABLE_WAKEUP_BLOCKING_OP](#disable-async-wakeup-of-blocking-operation) | Disable wakeup blocking operation | +| [WAMR_DISABLE_WRITE_GS_BASE](#disable-writing-the-linear-memory-base-address-to-x86-gs-segment-register) | Disable write GS base | +| [WAMR_TEST_GC](#test-garbage-collection) | Test garbage collection | + +### **Privileged Features** :warning: :exclamation: + +_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. + +### **[config.h](../core/config.h)** + +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. ### **Configure platform and architecture** -- **WAMR_BUILD_PLATFORM**: set the target platform. It can be set to any platform name (folder name) under folder [core/shared/platform](../core/shared/platform). +- **WAMR_BUILD_PLATFORM**: set the target platform. Match the platform folder name under [core/shared/platform](../core/shared/platform). -- **WAMR_BUILD_TARGET**: set the target CPU architecture. Current supported targets are: X86_64, X86_32, AARCH64, ARM, THUMB, XTENSA, ARC, RISCV32, RISCV64 and MIPS. - - For ARM and THUMB, the format is \\[\]\[\_VFP], where \ is the ARM sub-architecture and the "\_VFP" suffix means using VFP coprocessor registers s0-s15 (d0-d7) for passing arguments or returning results in standard procedure-call. Both \ and "\_VFP" are optional, e.g. ARMV7, ARMV7_VFP, THUMBV7, THUMBV7_VFP and so on. - - For AARCH64, the format is\[\], VFP is enabled by default. \ is optional, e.g. AARCH64, AARCH64V8, AARCH64V8.1 and so on. - - For RISCV64, the format is \[_abi], where "\_abi" is optional, currently the supported formats are RISCV64, RISCV64_LP64D and RISCV64_LP64: RISCV64 and RISCV64_LP64D are identical, using [LP64D](https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-cc.adoc#named-abis) as abi (LP64 with hardware floating-point calling convention for FLEN=64). And RISCV64_LP64 uses [LP64](https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-cc.adoc#named-abis) as abi (Integer calling-convention only, and hardware floating-point calling convention is not used). - - For RISCV32, the format is \[_abi], where "\_abi" is optional, currently the supported formats are RISCV32, RISCV32_ILP32D, RISCV32_ILP32F and RISCV32_ILP32: RISCV32 and RISCV32_ILP32D are identical, using [ILP32D](https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-cc.adoc#named-abis) as abi (ILP32 with hardware floating-point calling convention for FLEN=64). RISCV32_ILP32F uses [ILP32F](https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-cc.adoc#named-abis) as abi (ILP32 with hardware floating-point calling convention for FLEN=32). And RISCV32_ILP32 uses [ILP32](https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-cc.adoc#named-abis) as abi (Integer calling-convention only, and hardware floating-point calling convention is not used). +- **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 `[][_VFP]`. `` 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 `[]`. VFP is on by default. `` is optional, for example AARCH64, AARCH64V8, or AARCH64V8.1. + - For RISCV64, use `[_abi]`. `_abi` is optional. Supported: RISCV64, RISCV64_LP64D, and RISCV64_LP64. RISCV64 and RISCV64_LP64D both use [LP64D](https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-cc.adoc#named-abis) (LP64 with hardware floating-point for FLEN=64). RISCV64_LP64 uses [LP64](https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-cc.adoc#named-abis) (integer calling convention only; no hardware floating-point calling convention). + - For RISCV32, use `[_abi]`. `_abi` is optional. Supported: RISCV32, RISCV32_ILP32D, RISCV32_ILP32F, and RISCV32_ILP32. RISCV32 and RISCV32_ILP32D both use [ILP32D](https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-cc.adoc#named-abis) (ILP32 with hardware floating-point for FLEN=64). RISCV32_ILP32F uses [ILP32F](https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-cc.adoc#named-abis) (ILP32 with hardware floating-point for FLEN=32). RISCV32_ILP32 uses [ILP32](https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-cc.adoc#named-abis) (integer calling convention only). ```bash cmake -DWAMR_BUILD_PLATFORM=linux -DWAMR_BUILD_TARGET=ARM @@ -37,245 +143,270 @@ cmake -DWAMR_BUILD_PLATFORM=linux -DWAMR_BUILD_TARGET=ARM ### **Configure interpreters** -- **WAMR_BUILD_INTERP**=1/0: enable or disable WASM interpreter +- **WAMR_BUILD_INTERP**=1/0: turn the WASM interpreter on or off. -- **WAMR_BUILD_FAST_INTERP**=1/0: build fast (default) or classic WASM interpreter. +- **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. +> The fast interpreter runs about twice as fast as the classic one, and uses about twice the memory for the precompiled code. + +### **Configure AOT** + +- **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. + +### **Configure LLVM JIT** + +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. Defaults to off. With lazy JIT, functions are compiled in background threads before they are called, which can reduce startup time for large modules. -### **Configure AOT and JITs** +### **Configure Fast JIT** -- **WAMR_BUILD_AOT**=1/0, enable AOT or not, default to enable if not set -- **WAMR_BUILD_JIT**=1/0, enable LLVM JIT or not, default to disable if not set -- **WAMR_BUILD_FAST_JIT**=1/0, enable Fast JIT or not, default to disable if not set -- **WAMR_BUILD_FAST_JIT**=1 and **WAMR_BUILD_JIT**=1, enable Multi-tier JIT, default to disable if not set +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. + +> [!WARNING] +> It currently covers only a few architectures (x86_64). + +### **Configure Multi-tier JIT** + +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. + +> [!WARNING] +> It currently covers only a few architectures (x86_64). ### **Configure LIBC** -- **WAMR_BUILD_LIBC_BUILTIN**=1/0, build the built-in libc subset for WASM app, default to enable if not set +- **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](https://github.com/WebAssembly/WASI) libc subset for WASM apps. Defaults to on. -- **WAMR_BUILD_LIBC_WASI**=1/0, build the [WASI](https://github.com/WebAssembly/WASI) libc subset for WASM app, default to enable if not set +- **WAMR_BUILD_LIBC_UVWASI**=1/0 (Experiment): build the WASI libc subset for WASM apps using [uvwasi](https://github.com/nodejs/uvwasi). Defaults to off. -- **WAMR_BUILD_LIBC_UVWASI**=1/0 (Experiment), build the [WASI](https://github.com/WebAssembly/WASI) libc subset for WASM app based on [uvwasi](https://github.com/nodejs/uvwasi) implementation, default to disable if not set +- **WAMR_BUILD_LIBC_EMCC**=1/0: build the emcc-compatible libc subset for WASM apps. Defaults to off. > [!WARNING] -> WAMR doesn't support a safe sandbox on all platforms. For platforms that do not support **WAMR_BUILD_LIBC_WASI**, e.g. Windows, developers can try using an unsafe uvwasi-based WASI implementation by using **WAMR_BUILD_LIBC_UVWASI**. +> 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. -### **Enable Multi-Module feature** +### **Multi-Module feature** -- **WAMR_BUILD_MULTI_MODULE**=1/0, default to disable if not set +- **WAMR_BUILD_MULTI_MODULE**=1/0, default to off. > [!NOTE] -> See [Multiple Modules as Dependencies](./multi_module.md) for more details. +> See [Multiple Modules as Dependencies](./multi_module.md) for details. > [!WARNING] -> Currently, the multi-module feature is not supported in fast-jit and llvm-jit modes. +> The multi-module feature is not supported in fast-jit or llvm-jit modes. -### **Enable WASM mini loader** +### **WASM mini loader** -- **WAMR_BUILD_MINI_LOADER**=1/0, default to disable if not set +- **WAMR_BUILD_MINI_LOADER**=1/0, default to off. > [!NOTE] -> the mini loader doesn't check the integrity of the WASM binary file, developer must ensure that the WASM file is well-formed. +> The mini loader skips integrity checks on the WASM binary. Make sure the file is valid yourself. -### **Enable shared memory feature** +> [!WARNING] +> This is a [privileged feature](#privileged-features) that compromises security. Use it only when you trust the WASM binary source. + +### **shared memory feature** -- **WAMR_BUILD_SHARED_MEMORY**=1/0, default to disable if not set +- **WAMR_BUILD_SHARED_MEMORY**=1/0, default to off. -### **Enable bulk memory feature** +### **bulk memory feature** -- **WAMR_BUILD_BULK_MEMORY**=1/0, default to disable if not set +- **WAMR_BUILD_BULK_MEMORY**=1/0, default to off. -### **Enable memory64 feature** +### **memory64 feature** -- **WAMR_BUILD_MEMORY64**=1/0, default to disable if not set +- **WAMR_BUILD_MEMORY64**=1/0, default to off. > [!WARNING] -> Currently, the memory64 feature is only supported in classic interpreter running mode and AOT mode. +> Supported only in classic interpreter mode and AOT mode. -### **Enable thread manager** +### **thread manager** -- **WAMR_BUILD_THREAD_MGR**=1/0, default to disable if not set +- **WAMR_BUILD_THREAD_MGR**=1/0, default to off. -### **Enable lib-pthread** +### **lib-pthread** -- **WAMR_BUILD_LIB_PTHREAD**=1/0, default to disable if not set +- **WAMR_BUILD_LIB_PTHREAD**=1/0, default to off. > [!NOTE] -> The dependent feature of lib pthread such as the `shared memory` and `thread manager` will be enabled automatically. -> See [WAMR pthread library](./pthread_library.md) for more details. +> When you enable lib pthread, required features such as `shared memory` and `thread manager` are enabled automatically. See [WAMR pthread library](./pthread_library.md) for details. -### **Enable lib-pthread-semaphore** +### **lib-pthread-semaphore** -- **WAMR_BUILD_LIB_PTHREAD_SEMAPHORE**=1/0, default to disable if not set +- **WAMR_BUILD_LIB_PTHREAD_SEMAPHORE**=1/0, default to off. > [!NOTE] -> This feature depends on `lib-pthread`, it will be enabled automatically if this feature is enabled. +> This depends on `lib-pthread` and turns it on automatically. -### **Enable lib wasi-threads** +### **lib wasi-threads** -- **WAMR_BUILD_LIB_WASI_THREADS**=1/0, default to disable if not set +- **WAMR_BUILD_LIB_WASI_THREADS**=1/0, default to off. > [!NOTE] -> The dependent feature of lib wasi-threads such as the `shared memory` and `thread manager` will be enabled automatically. -> See [wasi-threads](./pthread_impls.md#wasi-threads-new) and [Introduction to WAMR WASI threads](https://bytecodealliance.github.io/wamr.dev/blog/introduction-to-wamr-wasi-threads) for more details. +> Enabling lib wasi-threads also enables its dependencies `shared memory` and `thread manager`. See [wasi-threads](./pthread_impls.md#wasi-threads-new) and [Introduction to WAMR WASI threads](https://bytecodealliance.github.io/wamr.dev/blog/introduction-to-wamr-wasi-threads) for details. -### **Enable lib wasi-nn** +### **lib wasi-nn** -- **WAMR_BUILD_WASI_NN**=1/0, default to disable if not set +- **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. > [!NOTE] -> WAMR_BUILD_WASI_NN without WAMR_BUILD_WASI_EPHEMERAL_NN is deprecated and will likely be removed in future versions of WAMR. Please consider to enable WAMR_BUILD_WASI_EPHEMERAL_NN as well. -> See [WASI-NN](../core/iwasm/libraries/wasi-nn) for more details. +> 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](../core/iwasm/libraries/wasi-nn) for details. -### **Enable lib wasi-nn GPU mode** +### **lib wasi-nn GPU mode** -- **WAMR_BUILD_WASI_NN_ENABLE_GPU**=1/0, default to disable if not set +- **WAMR_BUILD_WASI_NN_ENABLE_GPU**=1/0, default to off. -### **Enable lib wasi-nn external delegate mode** +### **lib wasi-nn external delegate mode** -- **WAMR_BUILD_WASI_NN_ENABLE_EXTERNAL_DELEGATE**=1/0, default to disable if not set +- **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 (e.g. `libedgetpu.so.1.0` for Coral USB) +- **WAMR_BUILD_WASI_NN_EXTERNAL_DELEGATE_PATH**=Path to the external delegate shared library (for example `libedgetpu.so.1.0` for Coral USB). -### **Enable lib wasi-nn with `wasi_ephemeral_nn` module support** +### **lib wasi-nn with `wasi_ephemeral_nn` module support** -- **WAMR_BUILD_WASI_EPHEMERAL_NN**=1/0, default to enable if not set +- **WAMR_BUILD_WASI_EPHEMERAL_NN**=1/0, default to on. ### **Disable boundary check with hardware trap** -- **WAMR_DISABLE_HW_BOUND_CHECK**=1/0, default to enable if not set and supported by platform +- **WAMR_DISABLE_HW_BOUND_CHECK**=1/0, default to on if the platform supports it. Otherwise, software boundary checks are used. > [!NOTE] -> by default only platform [linux/darwin/android/windows/vxworks 64-bit](https://github.com/bytecodealliance/wasm-micro-runtime/blob/5fb5119239220b0803e7045ca49b0a29fe65e70e/core/shared/platform/linux/platform_internal.h#L81) will enable the boundary check with hardware trap feature, for 32-bit platforms it's automatically disabled even when the flag is set to 0, and the wamrc tool will generate AOT code without boundary check instructions in all 64-bit targets except SGX to improve performance. The boundary check includes linear memory access boundary and native stack access boundary, if `WAMR_DISABLE_STACK_HW_BOUND_CHECK` below isn't set. +> By default only [linux/darwin/android/windows/vxworks 64-bit](https://github.com/bytecodealliance/wasm-micro-runtime/blob/5fb5119239220b0803e7045ca49b0a29fe65e70e/core/shared/platform/linux/platform_internal.h#L81) 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_CHECK` is set. ### **Disable native stack boundary check with hardware trap** -- **WAMR_DISABLE_STACK_HW_BOUND_CHECK**=1/0, default to enable if not set and supported by platform, same as `WAMR_DISABLE_HW_BOUND_CHECK`. +- **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. > [!NOTE] -> When boundary check with hardware trap is disabled, or `WAMR_DISABLE_HW_BOUND_CHECK` is set to 1, the native stack boundary check with hardware trap will be disabled too, no matter what value is set to `WAMR_DISABLE_STACK_HW_BOUND_CHECK`. And when boundary check with hardware trap is enabled, the status of this feature is set according to the value of `WAMR_DISABLE_STACK_HW_BOUND_CHECK`. +> If hardware trap boundary checks are off (or `WAMR_DISABLE_HW_BOUND_CHECK` is 1), native stack boundary checks are also off regardless of `WAMR_DISABLE_STACK_HW_BOUND_CHECK`. If hardware trap boundary checks are on, this setting decides whether the native stack check is on. ### **Disable async wakeup of blocking operation** -- **WAMR_DISABLE_WAKEUP_BLOCKING_OP**=1/0, default to enable if supported by the platform +- **WAMR_DISABLE_WAKEUP_BLOCKING_OP**=1/0, default to on when the platform supports it. > [!NOTE] -> The feature helps async termination of blocking threads. If you disable it, the runtime can wait for termination of blocking threads possibly forever. +> This feature lets blocking threads terminate asynchronously. If you disable it, blocking threads may never finish when asked to exit. + +### **tail call feature** -### **Enable tail call feature** +- **WAMR_BUILD_TAIL_CALL**=1/0, default to off. -- **WAMR_BUILD_TAIL_CALL**=1/0, default to disable if not set +### **128-bit SIMD feature** -### **Enable 128-bit SIMD feature** +- **WAMR_BUILD_SIMD**=1/0, default to on. +- **WAMR_BUILD_SIMDE**=1/0, default to off. -- **WAMR_BUILD_SIMD**=1/0, default to enable if not set +SIMDE (SIMD Everywhere) implements SIMD operations in fast interpreter mode. > [!WARNING] -> supported in AOT mode, JIT mode, and fast-interpreter mode with SIMDe library. +> Supported in AOT, JIT, and fast-interpreter modes with the SIMDe library. -### **Enable SIMDe library for SIMD in fast interpreter** +### **SIMDe library for SIMD in fast interpreter** -- **WAMR_BUILD_LIB_SIMDE**=1/0, default to disable if not set +- **WAMR_BUILD_LIB_SIMDE**=1/0, default to off. > [!NOTE] -> If enabled, SIMDe (SIMD Everywhere) library will be used to implement SIMD operations in fast interpreter mode. +> When enabled, SIMDe (SIMD Everywhere) implements SIMD operations in fast interpreter mode. -### **Enable Exception Handling** +### **Exception Handling** -- **WAMR_BUILD_EXCE_HANDLING**=1/0, default to disable if not set +- **WAMR_BUILD_EXCE_HANDLING**=1/0, default to off. + +> [!NOTE] +> Current implementation supports only Legacy Wasm exception handling proposal, not the latest version. > [!WARNING] -> Currently, the exception handling feature is only supported in classic interpreter running mode. +> Exception handling currently works only in classic interpreter mode. -### **Enable Garbage Collection** +### **Garbage Collection** -- **WAMR_BUILD_GC**=1/0, default to disable if not set +- **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, default to off. > [!WARNING] -> Currently, the exception handling feature is not supported in fast-jit running mode. +> Garbage collection is not supported in fast-jit mode and multi-tier-jit mode. ### **Set the Garbage Collection heap size** -- **WAMR_BUILD_GC_HEAP_SIZE_DEFAULT**=n, default to 128 kB (131072) if not set +- **WAMR_BUILD_GC_HEAP_SIZE_DEFAULT**=n, default to 128 kB (131072). -### **Enable Multi Memory** +### **Multi Memory** -- **WAMR_BUIL_MULTI_MEMORY**=1/0, default to disable if not set +- **WAMR_BUIL_MULTI_MEMORY**=1/0, default to off. > [!WARNING] -> Currently, the multi memory feature is only supported in classic interpreter running mode. +> Multi memory is supported only in classic interpreter mode. -### **Configure Debug** +### **Name Section** -- **WAMR_BUILD_CUSTOM_NAME_SECTION**=1/0, load the function name from custom name section, default to disable if not set +- **WAMR_BUILD_CUSTOM_NAME_SECTION**=1/0: load function names from the custom name section. Default is off. -### **Enable AOT stack frame feature** +### **AOT stack frame feature** -- **WAMR_BUILD_AOT_STACK_FRAME**=1/0, default to disable if not set +- **WAMR_BUILD_AOT_STACK_FRAME**=1/0, default to off. > [!NOTE] -> if it is enabled, the AOT or JIT stack frames (like stack frame of classic interpreter but only necessary data is committed) will be created for AOT or JIT mode in function calls. And please add `--enable-dump-call-stack` option to wamrc during compiling AOT module. - -### **Enable dump call stack feature** - -- **WAMR_BUILD_DUMP_CALL_STACK**=1/0, default to disable if not set - -> [!NOTE] -> if it is enabled, the call stack will be dumped when exception occurs. -> -> - For interpreter mode, the function names are firstly extracted from _custom name section_, if this section doesn't exist or the feature is not enabled, then the name will be extracted from the import/export sections -> - For AOT/JIT mode, the function names are extracted from import/export section, please export as many functions as possible (for `wasi-sdk` you can use `-Wl,--export-all`) when compiling wasm module, and add `--enable-dump-call-stack --emit-custom-sections=name` option to wamrc during compiling AOT module. +> 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-stack` to wamrc when compiling AOT modules. -### **Enable memory profiling (Experiment)** +### **dump call stack feature** -- **WAMR_BUILD_MEMORY_PROFILING**=1/0, default to disable if not set +- **WAMR_BUILD_DUMP_CALL_STACK**=1/0, default to off. > [!NOTE] -> if it is enabled, developer can use API `void wasm_runtime_dump_mem_consumption(wasm_exec_env_t exec_env)` to dump the memory consumption info. -> Currently we only profile the memory consumption of module, module_instance and exec_env, the memory consumed by other components such as `wasi-ctx`, `multi-module` and `thread-manager` are not included. +> When enabled, the runtime dumps the call stack on exceptions. > -> Also refer to [Memory usage estimation for a module](./memory_usage.md). +> - 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-sdk` you can use `-Wl,--export-all`) when compiling the wasm module, and add `--enable-dump-call-stack --emit-custom-sections=name` to wamrc when compiling the AOT module. -### **Enable performance profiling (Experiment)** +### **memory profiling (Experiment)** -- **WAMR_BUILD_PERF_PROFILING**=1/0, default to disable if not set +- **WAMR_BUILD_MEMORY_PROFILING**=1/0, default to off. > [!NOTE] -> if it is enabled, developer can use API `void wasm_runtime_dump_perf_profiling(wasm_module_inst_t module_inst)` to dump the performance consumption info. Currently we only profile the performance consumption of each WASM function. -> The function name searching sequence is the same with dump call stack feature. -> Also refer to [Tune the performance of running wasm/aot file](./perf_tune.md). +> 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 as `wasi-ctx`, `multi-module`, and `thread-manager` are not included. See [Memory usage estimation for a module](./memory_usage.md). -### **Enable the global heap** +### **performance profiling (Experiment)** -- **WAMR_BUILD_GLOBAL_HEAP_POOL**=1/0, default to disable if not set for all _iwasm_ applications, except for the platforms Alios and Zephyr. +- **WAMR_BUILD_PERF_PROFILING**=1/0, default to off. > [!NOTE] -> **WAMR_BUILD_GLOBAL_HEAP_POOL** is used in the _iwasm_ applications provided in the directory `product-mini`. When writing your own host application using WAMR, if you want to use a global heap and allocate memory from it, you must set the initialization argument `mem_alloc_type` to `Alloc_With_Pool`. -> The global heap is defined in the documentation [Memory model and memory usage tunning](memory_tune.md). +> 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](./perf_tune.md). -### **Set the global heap size** +### **A pre-allocation for runtime and wasm apps** -- **WAMR_BUILD_GLOBAL_HEAP_SIZE**=n, default to 10 MB (10485760) if not set for all _iwasm_ applications, except for the platforms Alios (256 kB), Riot (256 kB) and Zephyr (128 kB). +- **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). > [!NOTE] -> **WAMR_BUILD_GLOBAL_HEAP_SIZE** is used in the _iwasm_ applications provided in the directory `product-mini`. When writing your own host application using WAMR, if you want to set the amount of memory dedicated to the global heap pool, you must set the initialization argument `mem_alloc_option.pool` with the appropriate values. -> The global heap is defined in the documentation [Memory model and memory usage tunning](memory_tune.md). +> 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, set `mem_alloc_type` to `Alloc_With_Pool` if you want to use a global heap. The global heap is described in [Memory model and memory usage tunning](memory_tune.md). **WAMR_BUILD_GLOBAL_HEAP_SIZE** applies to _iwasm_ apps in `product-mini`. For your host app, set `mem_alloc_option.pool` with the size you want for the global heap. The global heap is described in [Memory model and memory usage tunning](memory_tune.md). ### **Set maximum app thread stack size** -- **WAMR_APP_THREAD_STACK_SIZE_MAX**=n, default to 8 MB (8388608) if not set +- **WAMR_APP_THREAD_STACK_SIZE_MAX**=n, default to 8 MB (8388608). > [!NOTE] -> the AOT boundary check with hardware trap mechanism might consume large stack since the OS may lazily grow the stack mapping as a guard page is hit, we may use this configuration to reduce the total stack usage, e.g. -DWAMR_APP_THREAD_STACK_SIZE_MAX=131072 (128 KB). +> 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). -### **Set vprintf callback** +### **Host defined vprintf** -- **WAMR_BH_VPRINTF**=, default to disable if not set +- **WAMR_BH_VPRINTF**=, default to off. > [!NOTE] -> if the vprintf_callback function is provided by developer, the os_printf() and os_vprintf() in Linux, Darwin, Windows, VxWorks, Android and esp-idf platforms, besides WASI Libc output will call the callback function instead of libc vprintf() function to redirect the stdout output. For example, developer can define the callback function like below outside runtime lib: +> If you provide `vprintf_callback`, `os_printf()` and `os_vprintf()` on Linux, Darwin, Windows, VxWorks, Android, and esp-idf, plus WASI libc output, call your callback instead of libc `vprintf()`. Example outside the runtime lib: > > ```C > int my_vprintf(const char *format, va_list ap) @@ -293,12 +424,12 @@ cmake -DWAMR_BUILD_PLATFORM=linux -DWAMR_BUILD_TARGET=ARM > } > ``` > -> and then use `cmake -DWAMR_BH_VPRINTF=my_vprintf ..` to pass the callback function, or add `BH_VPRINTF=my_vprintf` macro for the compiler, e.g. add line `add_definitions(-DBH_VPRINTF=my_vprintf)` in CMakeLists.txt. See [basic sample](../samples/basic/src/main.c) for a usage example. +> Then run `cmake -DWAMR_BH_VPRINTF=my_vprintf ..`, or add the compiler macro `BH_VPRINTF=my_vprintf` (for example `add_definitions(-DBH_VPRINTF=my_vprintf)` in CMakeLists.txt). See [basic sample](../samples/basic/src/main.c) for an example. -### **WAMR_BH_LOG**=, default to disable if not set +### **WAMR_BH_LOG**=, default to off. > [!NOTE] -> if the log_callback function is provided by the developer, WAMR logs are redirected to such callback. For example: +> If you provide `log_callback`, WAMR logs go there. Example: > > ```C > void my_log(uint32 log_level, const char *file, int line, const char *fmt, ...) @@ -307,77 +438,76 @@ cmake -DWAMR_BUILD_PLATFORM=linux -DWAMR_BUILD_TARGET=ARM > } > ``` > -> See [basic sample](../samples/basic/src/main.c) for a usage example. +> See [basic sample](../samples/basic/src/main.c) for an example. -### **Enable reference types feature** +### **reference types feature** -- **WAMR_BUILD_REF_TYPES**=1/0, default to enable if not set +- **WAMR_BUILD_REF_TYPES**=1/0, default to on. ### **Exclude WAMR application entry functions** -- **WAMR_DISABLE_APP_ENTRY**=1/0, default to disable if not set +- **WAMR_DISABLE_APP_ENTRY**=1/0, default to off. > [!NOTE] -> The WAMR application entry (`core/iwasm/common/wasm_application.c`) encapsulate some common process to instantiate, execute the wasm functions and print the results. Some platform related APIs are used in these functions, so you can enable this flag to exclude this file if your platform doesn't support those APIs. -> _Don't enable this flag if you are building `product-mini`_ +> 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 building `product-mini`._ -### **Enable source debugging features** +### **source debugging features** -- **WAMR_BUILD_DEBUG_INTERP**=1/0, default to 0 if not set +- **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. > [!NOTE] -> There are some other setup required by source debugging, please refer to [source_debugging.md](./source_debugging.md) and [WAMR source debugging basic](https://bytecodealliance.github.io/wamr.dev/blog/wamr-source-debugging-basic) for more details. +> Source debugging needs extra setup. See [source_debugging.md](./source_debugging.md) and [WAMR source debugging basic](https://bytecodealliance.github.io/wamr.dev/blog/wamr-source-debugging-basic). -### **Enable load wasm custom sections** +### **load wasm custom sections** -- **WAMR_BUILD_LOAD_CUSTOM_SECTION**=1/0, default to disable if not set +- **WAMR_BUILD_LOAD_CUSTOM_SECTION**=1/0, default to off. > [!NOTE] -> By default, the custom sections are ignored. If the embedder wants to get custom sections from `wasm_module_t`, then `WAMR_BUILD_LOAD_CUSTOM_SECTION` should be enabled, and then `wasm_runtime_get_custom_section` can be used to get a custom section by name. -> -> If `WAMR_BUILD_CUSTOM_NAME_SECTION` is enabled, then the `custom name section` will be treated as a special section and consumed by the runtime, not available to the embedder. -> For AoT file, must use `--emit-custom-sections` to specify which sections need to be emitted into AoT file, otherwise all custom sections will be ignored. +> By default, custom sections are ignored. `WAMR_BUILD_LOAD_CUSTOM_SECTION` so the embedder can read them via `wasm_runtime_get_custom_section`. If `WAMR_BUILD_CUSTOM_NAME_SECTION` is on, the custom name section is consumed by the runtime and unavailable to the embedder. For AoT files, pass `--emit-custom-sections` to wamrc to keep the sections; otherwise they are dropped. ### **Stack guard size** -- **WAMR_BUILD_STACK_GUARD_SIZE**=n, default to N/A if not set. +- **WAMR_BUILD_STACK_GUARD_SIZE**=n, default to N/A when not set. > [!NOTE] -> By default, the stack guard size is 1K (1024) or 24K (if uvwasi enabled). +> By default, stack guard size is 1K (1024) or 24K when uvwasi is enabled. ### **Disable writing the linear memory base address to x86 GS segment register** -- **WAMR_DISABLE_WRITE_GS_BASE**=1/0, default to enable if not set and supported by platform +- **WAMR_DISABLE_WRITE_GS_BASE**=1/0, default to on if the platform supports it. > [!NOTE] -> by default only platform [linux x86-64](https://github.com/bytecodealliance/wasm-micro-runtime/blob/5fb5119239220b0803e7045ca49b0a29fe65e70e/core/shared/platform/linux/platform_internal.h#L67) will enable this feature, for 32-bit platforms it's automatically disabled even when the flag is set to 0. In linux x86-64, writing the linear memory base address to x86 GS segment register may be used to speedup the linear memory access for LLVM AOT/JIT, when `--enable-segue=[]` option is added for `wamrc` or `iwasm`. - -> See [Enable segue optimization for wamrc when generating the aot file](./perf_tune.md#3-enable-segue-optimization-for-wamrc-when-generating-the-aot-file) for more details. +> By default only [linux x86-64](https://github.com/bytecodealliance/wasm-micro-runtime/blob/5fb5119239220b0803e7045ca49b0a29fe65e70e/core/shared/platform/linux/platform_internal.h#L67) 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=[]` is passed to `wamrc` or `iwasm`. +> +> See [segue optimization for wamrc when generating the aot file](./perf_tune.md#3-enable-segue-optimization-for-wamrc-when-generating-the-aot-file) for details. ### **User defined linear memory allocator** -- **WAMR_BUILD_ALLOC_WITH_USAGE**=1/0, default to disable if not set +- **WAMR_BUILD_ALLOC_WITH_USAGE**=1/0, default to off. +- **WAMR_BUILD_ALLOC_WITH_USER_DATA**=1/0, default to off. > [!NOTE] -> by default, the linear memory is allocated by system. when it's set to 1 and Alloc_With_Allocator is selected, it will be allocated by customer. +> By default, the system allocates linear memory. With this on and `Alloc_With_Allocator` selected, you can provide your own allocator. -### **Enable running PGO(Profile-Guided Optimization) instrumented AOT file** +### **running PGO(Profile-Guided Optimization) instrumented AOT file** -- **WAMR_BUILD_STATIC_PGO**=1/0, default to disable if not set +- **WAMR_BUILD_STATIC_PGO**=1/0, default to off. > [!NOTE] -> See [Use the AOT static PGO method](./perf_tune.md#5-use-the-aot-static-pgo-method) for more details. +> See [Use the AOT static PGO method](./perf_tune.md#5-use-the-aot-static-pgo-method). -### **Enable linux perf support** +### **linux perf support** -- **WAMR_BUILD_LINUX_PERF**=1/0, enable linux perf support to generate the flamegraph to analyze the performance of a wasm application, default to disable if not set +- **WAMR_BUILD_LINUX_PERF**=1/0: enable linux perf support to generate flamegraphs for wasm app performance. Default is off. > [!NOTE] -> See [Use linux-perf](./perf_tune.md#7-use-linux-perf) for more details. +> See [Use linux-perf](./perf_tune.md#7-use-linux-perf). -### **Enable module instance context APIs** +### **module instance context APIs** -- **WAMR_BUILD_MODULE_INST_CONTEXT**=1/0, enable module instance context APIs which can set one or more contexts created by the embedder for a wasm module instance, default to enable if not set: +- **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 on. ```C wasm_runtime_create_context_key @@ -388,78 +518,63 @@ cmake -DWAMR_BUILD_PLATFORM=linux -DWAMR_BUILD_TARGET=ARM ``` > [!NOTE] -> See [wasm_export.h](../core/iwasm/include/wasm_export.h) for more details. +> See [wasm_export.h](../core/iwasm/include/wasm_export.h) for details. -### **Enable quick AOT/JTI entries** +### **quick AOT/JTI entries** -- **WAMR_BUILD_QUICK_AOT_ENTRY**=1/0, enable registering quick call entries to speedup the aot/jit func call process, default to enable if not set +- **WAMR_BUILD_QUICK_AOT_ENTRY**=1/0: register quick call entries to speed up AOT/JIT function calls. Default is on. > [!NOTE] -> See [Refine callings to AOT/JIT functions from host native](./perf_tune.md#83-refine-callings-to-aotjit-functions-from-host-native) for more details. +> See [Refine callings to AOT/JIT functions from host native](./perf_tune.md#83-refine-callings-to-aotjit-functions-from-host-native). -### **Enable AOT intrinsics** +### **AOT intrinsics** -- **WAMR_BUILD_AOT_INTRINSICS**=1/0, enable the AOT intrinsic functions, default to enable if not set. These functions can be called from the AOT code when `--disable-llvm-intrinsics` flag or `--enable-builtin-intrinsics=` flag is used by wamrc to generate the AOT file. +- **WAMR_BUILD_AOT_INTRINSICS**=1/0: turn on AOT intrinsic functions. Default is on. AOT code can call these when wamrc uses `--disable-llvm-intrinsics` or `--enable-builtin-intrinsics=`. > [!NOTE] -> See [Tuning the XIP intrinsic functions](./xip.md#tuning-the-xip-intrinsic-functions) for more details. +> See [Tuning the XIP intrinsic functions](./xip.md#tuning-the-xip-intrinsic-functions). -### **Enable extended constant expression** +### **extended constant expression** -- **WAMR_BUILD_EXTENDED_CONST_EXPR**=1/0, default to disable if not set. +- **WAMR_BUILD_EXTENDED_CONST_EXPR**=1/0, default to off. > [!NOTE] -> See [Extended Constant Expressions](https://github.com/WebAssembly/extended-const/blob/main/proposals/extended-const/Overview.md) for more details. +> See [Extended Constant Expressions](https://github.com/WebAssembly/extended-const/blob/main/proposals/extended-const/Overview.md). -### **Enable bulk-memory-opt** +### **bulk-memory-opt** -- **WAMR_BUILD_BULK_MEMORY_OPT**=1/0, default to disable if not set. +- **WAMR_BUILD_BULK_MEMORY_OPT**=1/0, default to off. > [!NOTE] -> See [bulk-memory-opt](https://github.com/WebAssembly/tool-conventions/blob/main/Lime.md#bulk-memory-opt) for more details. +> See [bulk-memory-opt](https://github.com/WebAssembly/tool-conventions/blob/main/Lime.md#bulk-memory-opt). -### **Enable call-indirect-overlong** +### **call-indirect-overlong** -- **WAMR_BUILD_CALL_INDIRECT_OVERLONG**=1/0, default to disable if not set. +- **WAMR_BUILD_CALL_INDIRECT_OVERLONG**=1/0, default to off. > [!NOTE] -> See [call-indirect-overlong](https://github.com/WebAssembly/tool-conventions/blob/main/Lime.md#call-indirect-overlong) for more details. +> See [call-indirect-overlong](https://github.com/WebAssembly/tool-conventions/blob/main/Lime.md#call-indirect-overlong). -### **Enable Lime1 target** +### **Lime1 target** -- **WAMR_BUILD_LIME1**=1/0, default to disable if not set. +- **WAMR_BUILD_LIME1**=1/0, default to off. > [!NOTE] -> See [Lime1](https://github.com/WebAssembly/tool-conventions/blob/main/Lime.md#lime1) for more details. +> See [Lime1](https://github.com/WebAssembly/tool-conventions/blob/main/Lime.md#lime1). ### **Configurable memory access boundary check** -- **WAMR_CONFIGURABLE_BOUNDS_CHECKS**=1/0, default to disable if not set - -> [!NOTE] -> If it is enabled, allow to run `iwasm --disable-bounds-checks` to disable the memory access boundary checks for interpreter mode. +- **WAMR_CONFIGURABLE_BOUNDS_CHECKS**=1/0, default to off. -### **Module instance context APIs** - -- **WAMR_BUILD_MODULE_INST_CONTEXT**=1/0, default to disable if not set - -> [!NOTE] -> If it is enabled, allow to set one or more contexts created by embedder for a module instance, the below APIs are provided: -> -> ```C -> wasm_runtime_create_context_key -> wasm_runtime_destroy_context_key -> wasm_runtime_set_context -> wasm_runtime_set_context_spread -> wasm_runtime_get_context -> ``` +> [!WARNING] +> When enabled, you can run `iwasm --disable-bounds-checks` to turn off memory access boundary checks in interpreter mode. This is a [privileged feature](#privileged-features); use it carefully. ### **Shared heap among wasm apps and host native** -- **WAMR_BUILD_SHARED_HEAP**=1/0, default to disable if not set +- **WAMR_BUILD_SHARED_HEAP**=1/0, default to off. > [!NOTE] -> If it is enabled, allow to create one or more shared heaps, and attach one to a module instance, the belows APIs ared provided: +> When enabled, you can create and attach shared heaps, and the following APIs become available: > > ```C > wasm_runtime_create_shared_heap @@ -469,7 +584,7 @@ cmake -DWAMR_BUILD_PLATFORM=linux -DWAMR_BUILD_TARGET=ARM > wasm_runtime_shared_heap_free > ``` > -> And the wasm app can calls below APIs to allocate/free memory from/to the shared heap if it is attached to the app's module instance: +> A wasm app can call these to use the shared heap attached to its module instance: > > ```C > void *shared_heap_malloc(); @@ -477,44 +592,109 @@ cmake -DWAMR_BUILD_PLATFORM=linux -DWAMR_BUILD_TARGET=ARM > ``` > [!WARNING] -> Currently, the shared-heap feature is not supported in fast-jit mode. +> The shared-heap feature is not supported in fast-jit mode. ### **Shrunk the memory usage** -- **WAMR_BUILD_SHRUNK_MEMORY**=1/0, default to enable if not set +- **WAMR_BUILD_SHRUNK_MEMORY**=1/0, default to on. > [!NOTE] -> When enabled, this feature will reduce memory usage by decreasing the size of the linear memory, particularly when the `memory.grow` opcode is not used and memory usage is somewhat predictable. +> When enabled, this reduces memory by shrinking linear memory, especially when `memory.grow` is unused and memory needs are predictable. -## **Instruction metering** +### **Instruction metering** -- **WAMR_BUILD_INSTRUCTION_METERING**=1/0, default to disable if not set +- **WAMR_BUILD_INSTRUCTION_METERING**=1/0, default to off. > [!NOTE] -> Enabling this feature allows limiting the number of instructions a wasm module instance can execute. Use the `wasm_runtime_set_instruction_count_limit(...)` API before calling `wasm_runtime_call_*(...)` APIs to enforce this limit. +> This limits the number of instructions a wasm module instance can run. Call `wasm_runtime_set_instruction_count_limit(...)` before `wasm_runtime_call_*(...)` to enforce the cap. + +> [!WARNING] +> This is only supported in classic interpreter mode. + +### **Invoke general FFI** + +- **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](../core/iwasm/common/iwasm_common.cmake) + +### **Host defined log** + +- **WAMR_BH_LOG**=, default to off. + +### **AOT Validator** + +- **WAMR_BUILD_AOT_VALIDATOR**=1/0, default to off. + +> [!NOTE] +> By default, WAMR believes AOT files are valid and unforged. + +### **Copy Call Stack** + +- **WAMR_BUILD_COPY_CALL_STACK**=1/0, default to off. + +> [!NOTE] +> Unlike [dump call stack](dump-call-stack-feature), 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** + +- **WAMR_BUILD_LIB_RATS**=1/0, default to off. + +> [librats](https://github.com/inclavare-containers/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. + +### **Sanitizer** + +- **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. + +### **Intel Protected File System** + +- **WAMR_BUILD_SGX_IPFS**=1/0, default to off. + +> [!WARNING] +> This is for Intel SGX platforms only. + +### **Support spec test** + +- **WAMR_BUILD_SPEC_TEST**=1/0, default to off. + +### **WASM Cache** + +- **WAMR_BUILD_WASM_CACHE**=1/0, default to off. + +### **Test Garbage Collection** + +- **WAMR_TEST_GC**=1/0, default to off. + +It is used to test garbage collection related APIs and features. Refer to [iwasm_gc.cmake](../core/iwasm/common/gc/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. -## **Combination of configurations:** +## **Combination of configurations** -We can combine the configurations. For example, if we want to disable interpreter, enable AOT and WASI, we can run command: +You can mix settings. For example, to disable the interpreter, enable AOT and WASI, run: ```Bash cmake .. -DWAMR_BUILD_INTERP=0 -DWAMR_BUILD_AOT=1 -DWAMR_BUILD_LIBC_WASI=1 -DWAMR_BUILD_PLATFORM=linux ``` -Or if we want to enable interpreter, disable AOT and WASI, and build as X86_32, we can run command: +To enable the interpreter, disable AOT and WASI, and target X86_32, run: ```Bash 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, you'll need to enable both SIMD and the SIMDe library: +When enabling SIMD for fast interpreter mode, turn on both SIMD and the SIMDe library: ```Bash cmake .. -DWAMR_BUILD_INTERP=1 -DWAMR_BUILD_FAST_INTERP=1 -DWAMR_BUILD_SIMD=1 -DWAMR_BUILD_LIB_SIMDE=1 ``` -For Valgrind, begin with the following configurations and add additional ones as needed: +For Valgrind, start with these and add more as needed: ```Bash #... @@ -524,8 +704,7 @@ For Valgrind, begin with the following configurations and add additional ones as #... ``` -To enable the minimal Lime1 feature set, we need to disable some features that are on by default, such as -bulk memory and reference types: +To enable the minimal Lime1 feature set, turn off features that are on by default such as bulk memory and reference types: ```Bash cmake .. -DWAMR_BUILD_LIME1=1 -DWAMR_BUILD_BULK_MEMORY=0 -DWAMR_BUILD_REF_TYPES=0 -DDWAMR_BUILD_SIMD=0 diff --git a/doc/tiered_support.md b/doc/tiered_support.md index 565d347b29..6382dfb3fb 100644 --- a/doc/tiered_support.md +++ b/doc/tiered_support.md @@ -1,196 +1,163 @@ -# Tiered Supported - -**Tier definitions** - -- **A — Production Ready:** fully tested and stable. -- **B — Almost Production Ready:** partially tested; close to production. -- **C — Experimental / Not Production Ready:** unfinished or volatile. - -The condition _tested_ mentioned above specifically refers to whether there are enough tests in CI. - -## Architecture Support - -| Architecture | Tier | -| ------------ | ----- | -| **x86-64** | **A** | -| **x86-32** | **A** | -| AArch64 | B | -| ARC | B | -| ARM | B | -| RISCV32 | B | -| RISCV64 | B | -| THUMB | B | -| XTENSA | B | -| MIPS | C | - -## OS / Platform Support - -| Platform | Tier | -| ------------------ | ----- | -| **NuttX** | **A** | -| **Ubuntu** | **A** | -| Android | B | -| macOS | B | -| Windows | B | -| Zephyr | B | -| AliOS-Things | C | -| Cosmopolitan | C | -| ESP-IDF (FreeRTOS) | C | -| FreeBSD | C | -| iOS | C | -| RT-Thread | C | -| RIOT | C | -| VxWorks | C | - -## WebAssembly Proposal Support - -> During configuration, It is able to disable or enable the following features by setting the corresponding flags (see Appendix). It is also possible to check features status in the configuration output. - -| WASM Proposal / Extension | Tier | -| -------------------------------------- | ----------- | -| **Bulk Memory** | A | -| **Extended Constant Expressions** | A | -| **Import/Export of Mutable Globals** | A | -| **Memory64** | A | -| **Multi-value** | A | -| **Non-trapping float-to-int** | A | -| **Reference Types** | A | -| **Shared Memory (Threads)** | A | -| **SIMD (128-bit)** | A | -| **Sign-extension Operators** | A | -| GC (Garbage Collection) | B | -| Stringref | B | -| Tail Calls | B | -| Multi-memory | C | -| Legacy Exception Handling | C | -| Branch Hinting | Unsupported | -| Custom Annotation Syntax (text format) | Unsupported | -| Exception Handling (new spec) | Unsupported | -| JS String Builtins | Unsupported | -| Relaxed SIMD | Unsupported | - -# WAMR-Specific Feature Support - -> During configuration, It is able to disable or enable the following features by setting the corresponding flags (see Appendix). It is also possible to check features status in the configuration output. - -| WAMR Feature | Tier | -| --------------------------------- | ---- | -| **AoT (wamrc)** | A | -| **AOT intrinsics** | A | -| **Fast Interpreter** | A | -| **Interpreter (classic)** | A | -| **Libc builtin** | A | -| **Libc WASI** | A | -| **Quick AOT/JIT entries** | A | -| **Shrunk memory** | A | -| **Wakeup of blocking operations** | A | -| **WASM C API** | A | -| Fast JIT | B | -| LLVM ORC JIT | B | -| Memory profiling | B | -| Module instance context[^7] | B | -| Multi-module | B | -| Perf profiling | B | -| Pthread | B | -| Shared heap | B | -| WASI threads | B | -| WASI-NN (neural network APIs) | B | -| Debug Interpreter | B | -| Debug AOT | C | -| Tier-up (Fast JIT → LLVM JIT) | C | - ---- - -# Appendix: All compilation flags - -| Compilation flags | Tiered | Default | on Ubuntu | -| ------------------------------------------- | ------ | ------- | --------- | -| WAMR_APP_THREAD_STACK_SIZE_MAX | B | ND[^1] | | -| WAMR_BH_LOG | B | ND | | -| WAMR_BH_VPRINTF | B | ND | | -| WAMR_BUILD_ALLOC_WITH_USAGE | B | ND | | -| WAMR_BUILD_ALLOC_WITH_USER_DATA | B | ND | | -| WAMR_BUILD_AOT | A | ND | 1 | -| WAMR_BUILD_AOT_INTRINSICS | A | 1[^2] | | -| WAMR_BUILD_AOT_STACK_FRAME | A | ND | | -| WAMR_BUILD_AOT_VALIDATOR | B | ND | | -| WAMR_BUILD_BULK_MEMORY | A | 1 | | -| WAMR_BUILD_COPY_CALL_STACK | B | ND | | -| WAMR_BUILD_CUSTOM_NAME_SECTION | B | ND | | -| WAMR_BUILD_DEBUG_AOT | C | ND | | -| WAMR_BUILD_DEBUG_INTERP | B | ND | | -| WAMR_BUILD_DUMP_CALL_STACK | B | ND | | -| WAMR_BUILD_DYNAMIC_AOT_DEBUG | C | ND | | -| WAMR_BUILD_EXCE_HANDLING | C | 0 | | -| WAMR_BUILD_EXTENDED_CONST_EXPR | A | 0 | | -| WAMR_BUILD_FAST_INTERP | A | ND | 1 | -| WAMR_BUILD_FAST_JIT | B | ND | | -| WAMR_BUILD_FAST_JIT_DUMP | B | ND | | -| WAMR_BUILD_GC | B | 0 | | -| WAMR_BUILD_GC_HEAP_VERIFY | B | ND | | -| WAMR_BUILD_GLOBAL_HEAP_POOL | A | ND | | -| WAMR_BUILD_GLOBAL_HEAP_SIZE | A | ND | | -| WAMR_BUILD_INSTRUCTION_METERING | C | ND | | -| WAMR_BUILD_INTERP | A | ND | 1 | -| WAMR_BUILD_INVOKE_NATIVE_GENERAL | B | ND | | -| WAMR_BUILD_JIT | B | ND | | -| WAMR_BUILD_LAZY_JIT | B | 1[^3] | | -| WAMR_BUILD_LIBC_BUILTIN | A | ND | 1 | -| WAMR_BUILD_LIBC_EMCC | C | ND | | -| WAMR_BUILD_LIBC_UVWASI | C | ND | | -| WAMR_BUILD_LIBC_WASI | A | ND | 1 | -| WAMR_BUILD_LIB_PTHREAD | B | ND | | -| WAMR_BUILD_LIB_PTHREAD_SEMAPHORE | B | ND | | -| WAMR_BUILD_LIB_RATS | C | ND | | -| WAMR_BUILD_LIB_WASI_THREADS | B | ND | | -| WAMR_BUILD_LINUX_PERF | B | ND | | -| WAMR_BUILD_LIME1 | A | NO | | -| WAMR_BUILD_LOAD_CUSTOM_SECTION | A | ND | | -| WAMR_BUILD_MEMORY64 | A | 0 | | -| WAMR_BUILD_MEMORY_PROFILING | B | ND | | -| WAMR_BUILD_MINI_LOADER | B | ND | | -| WAMR_BUILD_MODULE_INST_CONTEXT | B | ND | 1 | -| WAMR_BUILD_MULTI_MEMORY | C | 0 | | -| WAMR_BUILD_MULTI_MODULE | B | ND | | -| WAMR_BUILD_PERF_PROFILING | B | ND | | -| WAMR_BUILD_PLATFORM | - | ND | linux | -| WAMR_BUILD_QUICK_AOT_ENTRY | A | 1[^4] | | -| WAMR_BUILD_REF_TYPES | A | ND | 1 | -| WAMR_BUILD_SANITIZER | B | ND | | -| WAMR_BUILD_SGX_IPFS | C | ND | | -| WAMR_BUILD_SHARED_HEAP | A | ND | | -| WAMR_BUILD_SHARED_MEMORY | A | 0 | 1 | -| WAMR_BUILD_SHRUNK_MEMORY | A | ND | 1 | -| WAMR_BUILD_SIMD | A | ND | 1 | -| WAMR_BUILD_SIMDE | A | ND | 1 | -| WAMR_BUILD_SPEC_TEST | A | ND | | -| WAMR_BUILD_STACK_GUARD_SIZE | B | ND | | -| WAMR_BUILD_STATIC_PGO | B | ND | | -| WAMR_BUILD_STRINGREF | B | 0 | | -| WAMR_BUILD_TAIL_CALL | A | 0 | 1 | -| WAMR_BUILD_TARGET | - | ND | X86-64 | -| WAMR_BUILD_THREAD_MGR | A | ND | | -| WAMR_BUILD_WAMR_COMPILER | A | ND | | -| WAMR_BUILD_WASI_EPHEMERAL_NN | B | ND | | -| WAMR_BUILD_WASI_NN | B | ND | | -| WAMR_BUILD_WASI_NN_ENABLE_EXTERNAL_DELEGATE | B | ND | | -| WAMR_BUILD_WASI_NN_ENABLE_GPU | B | ND | | -| WAMR_BUILD_WASI_NN_EXTERNAL_DELEGATE_PATH | B | ND | | -| WAMR_BUILD_WASI_NN_LLAMACPP | B | ND | | -| WAMR_BUILD_WASI_NN_ONNX | B | ND | | -| WAMR_BUILD_WASI_NN_OPENVINO | B | ND | | -| WAMR_BUILD_WASI_NN_TFLITE | B | ND | | -| WAMR_BUILD_WASI_TEST | B | ND | | -| WAMR_BUILD_WASM_CACHE | B | ND | | -| WAMR_CONFIGURABLE_BOUNDS_CHECKS | C | ND | | -| WAMR_DISABLE_APP_ENTRY | A | ND | | -| WAMR_DISABLE_HW_BOUND_CHECK | A | ND | | -| WAMR_DISABLE_STACK_HW_BOUND_CHECK | A | ND | | -| WAMR_DISABLE_WAKEUP_BLOCKING_OP | B | ND | | -| WAMR_DISABLE_WRITE_GS_BASE | B | ND | | -| WAMR_TEST_GC | B | ND | | - -[^1]: _ND_ represents _not defined_ -[^2]: active if `WAMR_BUILD_AOT` is 1 -[^3]: active if `WAMR_BUILD_FAST_JIT` or `WAMR_BUILD_JIT1` is 1 -[^4]: active if `WAMR_BUILD_AOT` or `WAMR_BUILD_JIT` is 1 +# Tiered Support + +## Tier A + +This tier is the highest level of support. Features and targets in this tier are fully supported, actively maintained, and regularly tested. Users can expect prompt assistance and comprehensive documentation for any issues or questions related to these features. Users can rely on Tier A features for production environments. Targets in this tier usually have been used in products. + +## Tier B + +This tier represents a moderate level of support. Features and targets in this tier are generally supported and maintained, but may not receive the same level of attention as Tier A. While efforts are made to ensure stability, users may encounter occasional issues that are not immediately addressed. Documentation may be less comprehensive compared to Tier A. Users are encouraged to report any issues they encounter, but response times may vary. + +## Tier C + +This tier indicates a basic level of support. Features and targets in this tier are considered experimental or less stable. They may not be actively maintained, and users should be prepared for potential issues or limitations. Documentation may be minimal or outdated. Users opting to use Tier C features do so at their own risk and should be prepared to troubleshoot issues independently. These features are typically not recommended for production use. + +> [!NOTE] +> +> - **actively maintained** and **fully supported**. users can expect timely assistance, comprehensive documentation, and regular updates for any issues or questions related to these features. +> - **regularly tested**. means there are automated tests in CI that run on a regular basis to ensure the stability and functionality of these features. + +## Labels + +**Target** refers to the specific hardware architecture or operating system that the runtime can be compiled for and run on. + +**Runtime Extensions** are features that extend the runtime capabilities of the system beyond the core WebAssembly specification. These extensions may include optimizations, additional APIs, or other enhancements that improve performance, usability, or functionality. + +**Portability** indicates the ability of the runtime to operate across different platforms or environments without requiring significant modifications. This includes compatibility with various operating systems, hardware architectures, and development frameworks. + +# TierA + +| Description | Compilation Flags | Labels | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------ | +| aarch64-unknown-nuttx-eabi | N/A | Target | +| i386-pc-linux-gnu | N/A | Target | +| x86_64-pc-linux-gnu | N/A | Target | +| x86_64-apple-darwin | N/A | Target | +| x86_64-none-linux-gnu | N/A | Target | +| Linux Compatibility | N/A | Portability | +| AoT runtime | [WAMR_BUILD_AOT](./build_wamr.md#configure-aot) | Running mode | +| Fast Interpreter | [WAMR_BUILD_FAST_INTERP](./build_wamr.md#configure-interpreters) | Running mode | +| Classic Interpreter | [WAMR_BUILD_INTERP](./build_wamr.md#configure-interpreters) | Running mode | +| AoT compilation (wamrc) | [WAMR_BUILD_WAMR_COMPILER](./build_wamr.md#configure-aot) | Compiler | +| Bulk Memory | [WAMR_BUILD_BULK_MEMORY](./build_wamr.md#bulk-memory-feature) | Wasm Proposal | +| Name section | [WAMR_BUILD_CUSTOM_NAME_SECTION](./build_wamr.md#name-section) | Wasm Proposal | +| Extended Constant Expressions | [WAMR_BUILD_EXTENDED_CONST_EXPR](./build_wamr.md#extended-constant-expression) | Wasm Proposal | +| Non-trapping float-to-int | ALWAYS ON. Can not be disabled | Wasm Proposal | +| Import/Export of Mutable Globals | ALWAYS ON. Can not be disabled | Wasm Proposal | +| Multi-value | ALWAYS ON. Can not be disabled | Wasm Proposal | +| AOT intrinsics | [WAMR_BUILD_AOT_INTRINSICS](./build_wamr.md#aot-intrinsics) | Runtime Extensions | +| AoT stack frame | [WAMR_BUILD_AOT_STACK_FRAME](./build_wamr.md#aot-stack-frame-feature) | Runtime Extensions | +| Global heap pool | [WAMR_BUILD_GLOBAL_HEAP_POOL](./build_wamr.md#a-pre-allocation-for-runtime-and-wasm-apps) | Runtime Extensions | +| Global heap size | [WAMR_BUILD_GLOBAL_HEAP_SIZE](./build_wamr.md#a-pre-allocation-for-runtime-and-wasm-apps) | Runtime Extensions | +| Libc builtin | [WAMR_BUILD_LIBC_BUILTIN](./build_wamr.md#configure-libc) | Runtime Extensions | +| WASI LIBC | [WAMR_BUILD_LIBC_WASI](./build_wamr.md#configure-libc) | Wasm Proposal | +| WASI threads | [WAMR_BUILD_LIB_WASI_THREADS](./build_wamr.md#lib-wasi-threads) | Wasm Proposal | +| Custom sections | [WAMR_BUILD_LOAD_CUSTOM_SECTION](./build_wamr.md#load-wasm-custom-sections) | Wasm Proposal | +| Memory64 | [WAMR_BUILD_MEMORY64](./build_wamr.md#memory64-feature) | Wasm Proposal | +| Quick AOT/JIT entries | [WAMR_BUILD_QUICK_AOT_ENTRY](./build_wamr.md#configure-aot) | Runtime Extensions | +| Reference Types | [WAMR_BUILD_REF_TYPES](./build_wamr.md#reference-types-feature) | Wasm Proposal | +| Threads | [WAMR_BUILD_SHARED_MEMORY](./build_wamr.md#shared-memory-feature) | Wasm Proposal | +| Shrunk memory | [WAMR_BUILD_SHRUNK_MEMORY](./build_wamr.md#shrunk-the-memory-usage) | Runtime Extensions | +| SIMD (128-bit) | [WAMR_BUILD_SIMD](./build_wamr.md#128-bit-simd-feature) | Wasm Proposal | +| Thread manager | [WAMR_BUILD_THREAD_MGR](./build_wamr.md#thread-manager) | Runtime Extensions | +| App entry | [WAMR_DISABLE_APP_ENTRY](./build_wamr.md#exclude-wamr-application-entry-functions) | Runtime Extensions | +| hardware bound check | [WAMR_DISABLE_HW_BOUND_CHECK](./build_wamr.md#disable-boundary-check-with-hardware-trap) | Runtime Extensions | +| stack hardware bound check | [WAMR_DISABLE_STACK_HW_BOUND_CHECK](./build_wamr.md#disable-native-stack-boundary-check-with-hardware-trap) | Runtime Extensions | +| Wakeup blocking operation | [WAMR_DISABLE_WAKEUP_BLOCKING_OP](./build_wamr.md#disable-async-wakeup-of-blocking-operation) | Runtime Extensions | + +# TierB + +| Description | Compilation Flags | Labels | +| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------ | +| arc-unknown-none-elf | N/A | Target | +| x86_64-pc-windows-msvc | N/A | Target | +| mips-unknown-elf | N/A | Target | +| mips64-unknown-elf | N/A | Target | +| Darwin Compatibility | N/A | Portability | +| ESP-IDF Compatibility | N/A | Portability | +| Nuttx Compatibility | N/A | Portability | +| SGX Compatibility | N/A | Portability | +| Zephyr Compatibility | N/A | Portability | +| GC (Garbage Collection) | [WAMR_BUILD_GC](./build_wamr.md#garbage-collection) | Wasm Proposal | +| Stringref | [WAMR_BUILD_STRINGREF](./build_wamr.md#garbage-collection) | Wasm Proposal | +| Tail Calls | [WAMR_BUILD_TAIL_CALL](./build_wamr.md#tail-call-feature) | Wasm Proposal | +| Per Instance running mode | ALWAYS ON. Can not be disabled | Runtime Extensions | +| Maximum stack size for app threads | [WAMR_APP_THREAD_STACK_SIZE_MAX](./build_wamr.md#set-maximum-app-thread-stack-size) | Runtime Extensions | +| Host defined logging | [WAMR_BH_LOG](./build_wamr.md#host-defined-log) | Runtime Extensions | +| Host defined vprintf | [WAMR_BH_vprintf](./build_wamr.md#host-defined-vprintf) | Runtime Extensions | +| Allocation with usage tracking | [WAMR_BUILD_ALLOC_WITH_USAGE](./build_wamr.md#user-defined-linear-memory-allocator) | Runtime Extensions | +| Allocation with user data | [WAMR_BUILD_ALLOC_WITH_USER_DATA](./build_wamr.md#user-defined-linear-memory-allocator) | Runtime Extensions | +| Bulk-memory-opt | [WAMR_BUILD_BULK_MEMORY_OPT](./build_wamr.md#bulk-memory-opt) | Runtime Extensions | +| Call-indirect-overlong | [WAMR_BUILD_CALL_INDIRECT_OVERLONG](./build_wamr.md#call-indirect-overlong) | Runtime Extensions | +| Copy Call Stack | [WAMR_BUILD_COPY_CALL_STACK](./build_wamr.md#copy-call-stack) | Runtime Extensions | +| Debug Interpreter | [WAMR_BUILD_DEBUG_INTERP](./build_wamr.md#configure-debug) | Runtime Extensions | +| Dump call stack | [WAMR_BUILD_DUMP_CALL_STACK](./build_wamr.md#dump-call-stack-feature) | Runtime Extensions | +| Garbage Collection Heap Verify | [WAMR_BUILD_GC_HEAP_VERIFY](./build_wamr.md#garbage-collection) | Runtime Extensions | +| Native General Invocation | [WAMR_BUILD_INVOKE_NATIVE_GENERAL](./build_wamr.md#invoke-general-ffi) | Runtime Extensions | +| Lazy JIT Compilation | [WAMR_BUILD_LAZY_JIT](./build_wamr.md#configure-llvm-jit) | Runtime Extensions | +| Pthread | [WAMR_BUILD_LIB_PTHREAD](./build_wamr.md#lib-pthread) | Runtime Extensions | +| Pthread Semaphore Support | [WAMR_BUILD_LIB_PTHREAD_SEMAPHORE](./build_wamr.md#lib-pthread-semaphore) | Runtime Extensions | +| Lime1 runtime | [WAMR_BUILD_LIME1](./build_wamr.md#lime1-target) | Runtime Extensions | +| Linux Performance Counters | [WAMR_BUILD_LINUX_PERF](./build_wamr.md#linux-perf-support) | Runtime Extensions | +| Memory profiling | [WAMR_BUILD_MEMORY_PROFILING](./build_wamr.md#memory-profiling-experiment) | Runtime Extensions | +| Module instance context | [WAMR_BUILD_MODULE_INST_CONTEXT](./build_wamr.md#module-instance-context-apis) | Runtime Extensions | +| Multi-module | [WAMR_BUILD_MULTI_MODULE](./build_wamr.md#multi-module-feature) | Runtime Extensions | +| Perf profiling | [WAMR_BUILD_PERF_PROFILING](./build_wamr.md#performance-profiling-experiment) | Runtime Extensions | +| Shared heap | [WAMR_BUILD_SHARED_HEAP](./build_wamr.md#shared-heap-among-wasm-apps-and-host-native) | Runtime Extensions | +| Stack Guard Size | [WAMR_BUILD_STACK_GUARD_SIZE](./build_wamr.md#stack-guard-size) | Runtime Extensions | +| WASI-NN (neural network APIs) | [WAMR_BUILD_WASI_NN](./build_wamr.md#lib-wasi-nn) | Runtime Extensions | +| External Delegate for WASI NN | [WAMR_BUILD_WASI_NN_ENABLE_EXTERNAL_DELEGATE](./build_wamr.md#lib-wasi-nn-external-delegate-mode) | Runtime Extensions | +| GPU Support for WASI NN | [WAMR_BUILD_WASI_NN_ENABLE_GPU](./build_wamr.md#lib-wasi-nn-gpu-mode) | Runtime Extensions | +| External Delegate Path for WASI NN | [WAMR_BUILD_WASI_NN_EXTERNAL_DELEGATE_PATH](./build_wamr.md#lib-wasi-nn-external-delegate-mode) | Runtime Extensions | +| LLAMA CPP for WASI NN | [WAMR_BUILD_WASI_NN_LLAMACPP](./build_wamr.md#lib-wasi-nn) | Runtime Extensions | +| ONNX for WASI NN | [WAMR_BUILD_WASI_NN_ONNX](./build_wamr.md#lib-wasi-nn) | Runtime Extensions | +| OpenVINO for WASI NN | [WAMR_BUILD_WASI_NN_OPENVINO](./build_wamr.md#lib-wasi-nn) | Runtime Extensions | +| TFLite for WASI NN | [WAMR_BUILD_WASI_NN_TFLITE](./build_wamr.md#lib-wasi-nn) | Runtime Extensions | +| Configurable bounds checks | [WAMR_CONFIGURABLE_BOUNDS_CHECKS](./build_wamr.md#configurable-memory-access-boundary-check) | Runtime Extensions | +| Write GS base | [WAMR_DISABLE_WRITE_GS_BASE](./build_wamr.md#disable-writing-the-linear-memory-base-address-to-x86-gs-segment-register) | Runtime Extensions | + +# TierC + +| Description | Compilation Flags | Labels | +| ------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------ | +| aarch64-apple-ios | N/A | Target | +| arm-none-eabi | N/A | Target | +| i386-unknown-elf | N/A | Target | +| i386-wrs-vxworks | N/A | Target | +| riscv32-esp-elf | N/A | Target | +| riscv32-unknown-elf | N/A | Target | +| riscv64-unknown-elf | N/A | Target | +| x86_64-linux-android | N/A | Target | +| x86_64-linux-cosmo | N/A | Target | +| x86_64-unknown-freebsd | N/A | Target | +| x86_64-wrs-vxworks | N/A | Target | +| xtensa-esp32-elf | N/A | Target | +| AliOS compatibility | N/A | Portability | +| Android Compatibility | N/A | Portability | +| Cosmo Compatibility | N/A | Portability | +| FreeBSD Compatibility | N/A | Portability | +| iOS Compatibility | N/A | Portability | +| RIOT OS Compatibility | N/A | Portability | +| RT-Thread Compatibility | N/A | Portability | +| VxWorks Compatibility | N/A | Portability | +| Windows Compatibility | N/A | Portability | +| Legacy Exception Handling | [WAMR_BUILD_EXCE_HANDLING](./build_wamr.md#exception-handling) | Wasm Proposal | +| Multi-memory | [WAMR_BUILD_MULTI_MEMORY](./build_wamr.md#multi-memory) | Wasm Proposal | +| Multi-tier JIT | [Combination of flags](./build_wamr.md#configure-multi-tier-jit) | Runtime Extensions | +| AoT Validator | [WAMR_BUILD_AOT_VALIDATOR](./build_wamr.md#aot-validator) | Runtime Extensions | +| Bulk-memory-opt | [WAMR_BUILD_BULK_MEMORY_OPT](./build_wamr.md#bulk-memory-opt) | Runtime Extensions | +| Call-indirect-overlong | [WAMR_BUILD_CALL_INDIRECT_OVERLONG](./build_wamr.md#call-indirect-overlong) | Runtime Extensions | +| Debug AOT | [WAMR_BUILD_DEBUG_AOT](./build_wamr.md#configure-debug) | Runtime Extensions | +| Dynamic AoT debugging | [WAMR_BUILD_DYNAMIC_AOT_DEBUG](./build_wamr.md#configure-debug) | Runtime Extensions | +| Fast JIT | [WAMR_BUILD_FAST_JIT](./build_wamr.md#configure-aot-and-jits) | Runtime Extensions | +| Fast JIT Dump | [WAMR_BUILD_FAST_JIT_DUMP](./build_wamr.md#configure-fast-jit) | Runtime Extensions | +| Instruction Metering | [WAMR_BUILD_INSTRUCTION_METERING](./build_wamr.md#instruction-metering) | Runtime Extensions | +| Libc EMCC Compatibility | [WAMR_BUILD_LIBC_EMCC](./build_wamr.md#libc-emcc) | Runtime Extensions | +| Libc UVWASI Compatibility | [WAMR_BUILD_LIBC_UVWASI](./build_wamr.md#libc-uvwasi) | Runtime Extensions | +| RATS Library | [WAMR_BUILD_LIB_RATS](./build_wamr.md#librats) | Runtime Extensions | +| Mini Loader | [WAMR_BUILD_MINI_LOADER](./build_wamr.md#wasm-mini-loader) | Runtime Extensions | +| SGX IPFS Support | [WAMR_BUILD_SGX_IPFS](./build_wamr.md#intel-protected-file-system) | Runtime Extensions | +| Static PGO | [WAMR_BUILD_STATIC_PGO](./build_wamr.md#running-pgoprofile-guided-optimization-instrumented-aot-file) | Runtime Extensions | +| WASI Ephemeral NN | [WAMR_BUILD_WASI_EPHEMERAL_NN](./build_wamr.md#lib-wasi-nn-with-wasi_ephemeral_nn-module-support) | Runtime Extensions | +| WASM cache | [WAMR_BUILD_WASM_CACHE](./build_wamr.md#wasm-cache) | Runtime Extensions | +| Test garbage collection | [WAMR_TEST_GC](./build_wamr.md#test-garbage-collection) | Runtime Extensions |