Skip to content

Commit 654a796

Browse files
lum1n0uslum1n0us
committed
docs: enhance build documentation with detailed compilation flags and configuration options
1 parent f81d079 commit 654a796

1 file changed

Lines changed: 104 additions & 8 deletions

File tree

‎doc/build_wamr.md‎

Lines changed: 104 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ References:
77
- [how to build iwasm](../product-mini/README.md): building different target platforms such as Linux, Windows, Mac etc
88
- [Blog: Introduction to WAMR running modes](https://bytecodealliance.github.io/wamr.dev/blog/introduction-to-wamr-running-modes/)
99

10-
## WAMR vmcore cmake building configurations
10+
## building configurations
1111

1212
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.
1313

@@ -19,7 +19,93 @@ add_library(vmlib ${WAMR_RUNTIME_LIB_SOURCE})
1919

2020
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.
2121

22-
Please refer to [a full list of configuration options](./tired_support.md#appendix-all-compilation-flags).
22+
### All compilation flags
23+
24+
| Description | Compilation flags | Tiered | Default | on Ubuntu |
25+
| ------------------------------------ | -------------------------------------------------------------------------------------------------------- | ------ | ------- | --------- |
26+
| Maximum stack size for app threads | [WAMR_APP_THREAD_STACK_SIZE_MAX](#set-maximum-app-thread-stack-size) | B | ND[^1] | |
27+
| Host defined logging | [WAMR_BH_LOG](#wamr_bh_log) | B | ND | |
28+
| Host defined vprintf | [WAMR_BH_VPRINTF](#set-vprintf-callback) | B | ND | |
29+
| Allocation with usage tracking | [WAMR_BUILD_ALLOC_WITH_USAGE](#user-defined-linear-memory-allocator) | B | ND | |
30+
| Allocation with user data | [WAMR_BUILD_ALLOC_WITH_USER_DATA](#user-defined-linear-memory-allocator) | B | ND | |
31+
| AoT compilation | [WAMR_BUILD_AOT](#configure-aot) | A | ND | 1 |
32+
| AoT intrinsics | [WAMR_BUILD_AOT_INTRINSICS](#enable-aot-intrinsics) | A | 1[^2] | |
33+
| AoT stack frame | [WAMR_BUILD_AOT_STACK_FRAME](#enable-aot-stack-frame-feature) | A | ND | |
34+
| AoT validator | [WAMR_BUILD_AOT_VALIDATOR]() | B | ND | |
35+
| bulk memory | [WAMR_BUILD_BULK_MEMORY](#enable-bulk-memory-feature) | A | 1 | |
36+
| copy call stack | WAMR_BUILD_COPY_CALL_STACK | B | ND | |
37+
| custom name section | [WAMR_BUILD_CUSTOM_NAME_SECTION](#configure-debug) | B | ND | |
38+
| debug AoT | WAMR_BUILD_DEBUG_AOT | C | ND | |
39+
| debug interpreter | [WAMR_BUILD_DEBUG_INTERP](#enable-source-debugging-features) | B | ND | |
40+
| dump call stack | [WAMR_BUILD_DUMP_CALL_STACK](#enable-dump-call-stack-feature) | B | ND | |
41+
| dynamic AoT debugging | WAMR_BUILD_DYNAMIC_AOT_DEBUG | C | ND | |
42+
| exception handling | [WAMR_BUILD_EXCE_HANDLING](#enable-exception-handling) | C | 0 | |
43+
| extended constant expressions | [WAMR_BUILD_EXTENDED_CONST_EXPR](#enable-extended-constant-expression) | A | 0 | |
44+
| fast interpreter | [WAMR_BUILD_FAST_INTERP](#configure-interpreters) | A | ND | 1 |
45+
| fast JIT | [WAMR_BUILD_FAST_JIT](#configure-fast-jit) | B | ND | |
46+
| fast JIT dump | WAMR_BUILD_FAST_JIT_DUMP | B | ND | |
47+
| garbage collection | [WAMR_BUILD_GC](#enable-garbage-collection) | B | 0 | |
48+
| garbage collection heap verification | WAMR_BUILD_GC_HEAP_VERIFY | B | ND | |
49+
| global heap pool | [WAMR_BUILD_GLOBAL_HEAP_POOL](#enable-the-global-heap) | A | ND | |
50+
| global heap size | [WAMR_BUILD_GLOBAL_HEAP_SIZE](#set-the-global-heap-size) | A | ND | |
51+
| instruction metering | [WAMR_BUILD_INSTRUCTION_METERING](#instruction-metering) | C | ND | |
52+
| interpreter | [WAMR_BUILD_INTERP](#configure-interpreters) | A | ND | 1 |
53+
| native general invocation | WAMR_BUILD_INVOKE_NATIVE_GENERAL | B | ND | |
54+
| JIT compilation | [WAMR_BUILD_JIT](#configure-llvm-jit) | B | ND | |
55+
| lazy JIT compilation | WAMR_BUILD_LAZY_JIT | B | 1[^3] | |
56+
| libc builtin functions | [WAMR_BUILD_LIBC_BUILTIN](#configure-libc) | A | ND | 1 |
57+
| libc emcc compatibility | WAMR_BUILD_LIBC_EMCC | C | ND | |
58+
| libc uvwasi compatibility | [WAMR_BUILD_LIBC_UVWASI](#configure-libc) | C | ND | |
59+
| wasi libc | [WAMR_BUILD_LIBC_WASI](#configure-libc) | A | ND | 1 |
60+
| pthread library | [WAMR_BUILD_LIB_PTHREAD](#enable-lib-pthread) | B | ND | |
61+
| pthread semaphore support | [WAMR_BUILD_LIB_PTHREAD_SEMAPHORE](#enable-lib-pthread-semaphore) | B | ND | |
62+
| RATS library | WAMR_BUILD_LIB_RATS | C | ND | |
63+
| wasi threads | [WAMR_BUILD_LIB_WASI_THREADS](#enable-lib-wasi-threads) | B | ND | |
64+
| Linux performance counters | [WAMR_BUILD_LINUX_PERF](#enable-linux-perf-support) | B | ND | |
65+
| LIME1 runtime | [WAMR_BUILD_LIME1](#enable-lime1-target) | A | NO | |
66+
| loading custom sections | [WAMR_BUILD_LOAD_CUSTOM_SECTION](#enable-load-wasm-custom-sections) | A | ND | |
67+
| memory64 support | [WAMR_BUILD_MEMORY64](#enable-memory64-feature) | A | 0 | |
68+
| memory profiling | [WAMR_BUILD_MEMORY_PROFILING](#enable-memory-profiling-experiment) | B | ND | |
69+
| mini loader | [WAMR_BUILD_MINI_LOADER](#enable-wasm-mini-loader) | B | ND | |
70+
| module instance context | [WAMR_BUILD_MODULE_INST_CONTEXT](#module-instance-context-apis) | B | ND | 1 |
71+
| multi-memory support | [WAMR_BUILD_MULTI_MEMORY](#enable-multi-memory) | C | 0 | |
72+
| multi-module support | [WAMR_BUILD_MULTI_MODULE](#enable-multi-module-feature) | B | ND | |
73+
| performance profiling | [WAMR_BUILD_PERF_PROFILING](#enable-performance-profiling-experiment) | B | ND | |
74+
| Default platform | [WAMR_BUILD_PLATFORM](#configure-platform-and-architecture) | - | ND | linux |
75+
| quick AOT entry | [WAMR_BUILD_QUICK_AOT_ENTRY](#enable-quick-aotjti-entries) | A | 1[^4] | |
76+
| reference types | [WAMR_BUILD_REF_TYPES](#enable-reference-types-feature) | A | ND | 1 |
77+
| sanitizer | WAMR_BUILD_SANITIZER | B | ND | |
78+
| SGX IPFS support | WAMR_BUILD_SGX_IPFS | C | ND | |
79+
| shared heap | [WAMR_BUILD_SHARED_HEAP](#shared-heap-among-wasm-apps-and-host-native) | A | ND | |
80+
| shared memory | [WAMR_BUILD_SHARED_MEMORY](#enable-shared-memory-feature) | A | 0 | 1 |
81+
| shrunk memory | [WAMR_BUILD_SHRUNK_MEMORY](#shrunk-the-memory-usage) | A | ND | 1 |
82+
| SIMD support | [WAMR_BUILD_SIMD](#enable-128-bit-simd-feature) | A | ND | 1 |
83+
| SIMD E extensions | WAMR_BUILD_SIMDE | A | ND | 1 |
84+
| spec test | WAMR_BUILD_SPEC_TEST | A | ND | |
85+
| Stack guard size | [WAMR_BUILD_STACK_GUARD_SIZE](#stack-guard-size) | B | ND | |
86+
| Static PGO | [WAMR_BUILD_STATIC_PGO](#enable-running-pgoprofile-guided-optimization-instrumented-aot-file) | B | ND | |
87+
| String reference support | [WAMR_BUILD_STRINGREF](#configure-debug) | B | 0 | |
88+
| Tail call optimization | [WAMR_BUILD_TAIL_CALL](#enable-tail-call-feature) | A | 0 | 1 |
89+
| Default target architecture | [WAMR_BUILD_TARGET](#configure-platform-and-architecture) | - | ND | X86-64 |
90+
| Thread manager | [WAMR_BUILD_THREAD_MGR](#enable-thread-manager) | A | ND | |
91+
| WAMR compiler | WAMR_BUILD_WAMR_COMPILER | A | ND | |
92+
| WASI ephemeral NN | [WAMR_BUILD_WASI_EPHEMERAL_NN](#enable-lib-wasi-nn-with-wasi_ephemeral_nn-module-support) | B | ND | |
93+
| WASI NN | [WAMR_BUILD_WASI_NN](#enable-lib-wasi-nn) | B | ND | |
94+
| external delegate for WASI NN | [WAMR_BUILD_WASI_NN_ENABLE_EXTERNAL_DELEGATE](#enable-lib-wasi-nn-external-delegate-mode) | B | ND | |
95+
| GPU support for WASI NN | [WAMR_BUILD_WASI_NN_ENABLE_GPU](#enable-lib-wasi-nn-gpu-mode) | B | ND | |
96+
| External delegate path for WASI NN | [WAMR_BUILD_WASI_NN_EXTERNAL_DELEGATE_PATH](#enable-lib-wasi-nn-external-delegate-mode) | B | ND | |
97+
| LLAMA CPP for WASI NN | WAMR_BUILD_WASI_NN_LLAMACPP | B | ND | |
98+
| ONNX for WASI NN | WAMR_BUILD_WASI_NN_ONNX | B | ND | |
99+
| OpenVINO for WASI NN | WAMR_BUILD_WASI_NN_OPENVINO | B | ND | |
100+
| TFLite for WASI NN | WAMR_BUILD_WASI_NN_TFLITE | B | ND | |
101+
| WASM cache | WAMR_BUILD_WASM_CACHE | B | ND | |
102+
| Configurable bounds checks | [WAMR_CONFIGURABLE_BOUNDS_CHECKS](#configurable-memory-access-boundary-check) | C | ND | |
103+
| Disable app entry | [WAMR_DISABLE_APP_ENTRY](#exclude-wamr-application-entry-functions) | A | ND | |
104+
| Disable hardware bound check | [WAMR_DISABLE_HW_BOUND_CHECK](#disable-boundary-check-with-hardware-trap) | A | ND | |
105+
| Disable stack hardware bound check | [WAMR_DISABLE_STACK_HW_BOUND_CHECK](#disable-native-stack-boundary-check-with-hardware-trap) | A | ND | |
106+
| Disable wakeup blocking operation | [WAMR_DISABLE_WAKEUP_BLOCKING_OP](#disable-async-wakeup-of-blocking-operation) | B | ND | |
107+
| Disable write GS base | [WAMR_DISABLE_WRITE_GS_BASE](#disable-writing-the-linear-memory-base-address-to-x86-gs-segment-register) | B | ND | |
108+
| Test garbage collection | WAMR_TEST_GC | B | ND | |
23109

24110
### **Configure platform and architecture**
25111

@@ -44,12 +130,23 @@ cmake -DWAMR_BUILD_PLATFORM=linux -DWAMR_BUILD_TARGET=ARM
44130
> [!NOTE]
45131
> the fast interpreter runs ~2X faster than classic interpreter, but consumes about 2X memory to hold the pre-compiled code.
46132
47-
### **Configure AOT and JITs**
133+
### **Configure AOT**
48134

49135
- **WAMR_BUILD_AOT**=1/0, enable AOT or not, default to enable if not set
136+
137+
### **Configure LLVM JIT**
138+
50139
- **WAMR_BUILD_JIT**=1/0, enable LLVM JIT or not, default to disable if not set
140+
141+
### **Configure Fast JIT**
142+
143+
the fast JIT is a lightweight JIT compiler which generates machine code quickly with optimizations for hot functions. Only covers few architectures (x86_64) currently.
144+
51145
- **WAMR_BUILD_FAST_JIT**=1/0, enable Fast JIT or not, default to disable if not set
52-
- **WAMR_BUILD_FAST_JIT**=1 and **WAMR_BUILD_JIT**=1, enable Multi-tier JIT, default to disable if not set
146+
147+
> [!NOTE]
148+
>
149+
> - **WAMR_BUILD_FAST_JIT**=1 and **WAMR_BUILD_JIT**=1, enable Multi-tier JIT, default to disable if not set
53150
54151
### **Configure LIBC**
55152

@@ -251,16 +348,14 @@ cmake -DWAMR_BUILD_PLATFORM=linux -DWAMR_BUILD_TARGET=ARM
251348

252349
- **WAMR_BUILD_GLOBAL_HEAP_POOL**=1/0, default to disable if not set for all _iwasm_ applications, except for the platforms Alios and Zephyr.
253350

254-
> [!NOTE]
255-
> **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`.
351+
> [!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`.
256352
> The global heap is defined in the documentation [Memory model and memory usage tunning](memory_tune.md).
257353
258354
### **Set the global heap size**
259355

260356
- **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).
261357

262-
> [!NOTE]
263-
> **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.
358+
> [!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.
264359
> The global heap is defined in the documentation [Memory model and memory usage tunning](memory_tune.md).
265360
266361
### **Set maximum app thread stack size**
@@ -357,6 +452,7 @@ cmake -DWAMR_BUILD_PLATFORM=linux -DWAMR_BUILD_TARGET=ARM
357452
### **User defined linear memory allocator**
358453
359454
- **WAMR_BUILD_ALLOC_WITH_USAGE**=1/0, default to disable if not set
455+
- **WAMR_BUILD_ALLOC_WITH_USER_DATA**=1/0, default to disable if not set
360456
361457
> [!NOTE]
362458
> 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.

0 commit comments

Comments
 (0)