From 682323dc1869bc45e93202a0f31e2c56d13dab37 Mon Sep 17 00:00:00 2001 From: YiYing He Date: Thu, 1 Oct 2026 19:05:59 +0800 Subject: [PATCH] docs: update docs to 0.17.2 Update the WasmEdge version, the AOT run mode requirement for the shared library format, the read-only preopen option, the OpenCV 5 requirement of the OpenCVMini plug-in, and the system blake3 note. Assisted-by: Claude (Anthropic) Signed-off-by: YiYing He --- .env | 2 +- docs/contribute/source/build_from_src.md | 5 +++++ .../source/plugin/wasmedge_opencvmini.md | 16 +++++++-------- docs/embed/c/intro.md | 10 ++++++++-- docs/embed/c/reference/latest.md | 20 +++++++++++++++++-- docs/embed/c/reference/upgrade_to_0.17.0.md | 7 ++++++- docs/start/build-and-run/aot.md | 17 ++++++++++------ docs/start/build-and-run/cli.md | 7 +++++-- docs/start/getting-started/quick_start.md | 4 ++-- docs/start/install.md | 6 +++--- docs/start/wasmedge/extensions/plugins.md | 2 +- .../embed/c/reference/upgrade_to_0.17.0.md | 7 ++++++- 12 files changed, 74 insertions(+), 29 deletions(-) diff --git a/.env b/.env index dea8f0f5..c154e081 100644 --- a/.env +++ b/.env @@ -1,2 +1,2 @@ -WASMEDGE_VERSION='0.17.0' +WASMEDGE_VERSION='0.17.2' WASMEDGE_GO_VERSION='0.14.0' \ No newline at end of file diff --git a/docs/contribute/source/build_from_src.md b/docs/contribute/source/build_from_src.md index 189f9d10..0d1bcc82 100644 --- a/docs/contribute/source/build_from_src.md +++ b/docs/contribute/source/build_from_src.md @@ -89,6 +89,11 @@ Developers can set the CMake options to customize the WasmEdge building. 18. `WASMEDGE_PLUGIN_TENSORFLOWLITE`: build the WasmEdge TensorFlow-Lite plug-in (Linux and MacOS platforms only). Default is `OFF`. - This option is useless if the option `WASMEDGE_BUILD_PLUGINS` is set as `OFF`. + +:::note +Since WasmEdge `0.17.2`, the build uses the system `blake3` library when it is available, and falls back to the vendored copy otherwise. Developers can set `-DCMAKE_DISABLE_FIND_PACKAGE_blake3=ON` to force the vendored copy. When the option `WASMEDGE_BUILD_STATIC_LIB` is set as `ON`, the vendored copy is always used. +::: + ## Build WasmEdge with Plug-ins Developers can follow the steps to build WasmEdge with plug-ins from source. diff --git a/docs/contribute/source/plugin/wasmedge_opencvmini.md b/docs/contribute/source/plugin/wasmedge_opencvmini.md index 7bd9dd37..79b279f6 100644 --- a/docs/contribute/source/plugin/wasmedge_opencvmini.md +++ b/docs/contribute/source/plugin/wasmedge_opencvmini.md @@ -8,20 +8,20 @@ The WasmEdge-OpenCVMini plug-in exposes a subset of [OpenCV](https://opencv.org/ ## Prerequisites -Install OpenCV 4 on your system. +Since WasmEdge `0.17.2`, the plug-in requires OpenCV 5. Please install OpenCV 5 on your system. -For Ubuntu 20.04: +For macOS: ```bash -sudo apt update -sudo apt install -y libopencv-dev +brew install opencv@5 ``` -For macOS: +For Linux, the `libopencv-dev` package of most distributions still provides OpenCV 4. Please build and install OpenCV 5 from the [OpenCV source](https://github.com/opencv/opencv) instead. -```bash -brew install opencv -``` + +:::note +For WasmEdge `0.17.1` and earlier versions, the plug-in requires OpenCV 4, which can be installed by `sudo apt install -y libopencv-dev` on Ubuntu or `brew install opencv` on macOS. +::: ## Build WasmEdge with WasmEdge-OpenCVMini Plug-in diff --git a/docs/embed/c/intro.md b/docs/embed/c/intro.md index ff3cb7b7..ebf20fb2 100644 --- a/docs/embed/c/intro.md +++ b/docs/embed/c/intro.md @@ -101,7 +101,13 @@ $ ./test_wasmedge_compiler fibonacci.wasm fibonacci_aot.wasm [2021-07-02 11:08:08.706] [info] compile done ``` -The compiled WASM file can be used as a WASM input for the WasmEdge runner. The following is the comparison of the interpreter mode and the AOT mode: +The compiled WASM file can be used as a WASM input for the WasmEdge runner. Since `0.17.0`, the AOT-compiled code is only loaded when the run mode is AOT, so please add the following line before `WasmEdge_VMCreate()` in `test_wasmedge.c` and rebuild it: + +```c +WasmEdge_ConfigureSetRunMode(ConfCxt, WasmEdge_RunMode_AOT); +``` + +The following is the comparison of the interpreter mode and the AOT mode: ```bash $ time ./test_wasmedge fibonacci.wasm @@ -121,7 +127,7 @@ sys 0m0.011s ## API References -- [0.17.0](reference/latest.md) +- [0.17.2](reference/latest.md) - [0.16.3](reference/0.16.x.md) - [0.15.1](reference/0.15.x.md) - [0.14.1](reference/0.14.x.md) diff --git a/docs/embed/c/reference/latest.md b/docs/embed/c/reference/latest.md index 22dda1d9..36f22b9a 100644 --- a/docs/embed/c/reference/latest.md +++ b/docs/embed/c/reference/latest.md @@ -2,7 +2,7 @@ sidebar_position: 1 --- -# C API 0.17.0 Documentation +# C API 0.17.2 Documentation [WasmEdge C API](https://github.com/WasmEdge/WasmEdge/blob/master/include/api/wasmedge/wasmedge.h) denotes an interface to access the WasmEdge runtime at version `{{ wasmedge_version }}`. The following are the guides to working with the C APIs of WasmEdge. @@ -875,7 +875,12 @@ The configuration context, `WasmEdge_ConfigureContext`, manages the configuratio }; ``` - Only `WasmEdge_RunMode_AOT` loads AOT custom sections from universal WASM, or `dlopen` shared-library WASM artifacts. In the other modes, AOT data is ignored, and shared-library inputs are re-loaded as plain WASM after extracting their embedded bytes. + Only `WasmEdge_RunMode_AOT` loads AOT custom sections from universal WASM, or `dlopen` shared-library WASM artifacts. In the other modes, the AOT custom sections in universal WASM are ignored, and shared-library inputs are rejected with the `WasmEdge_ErrCode_MalformedMagic` error. + + + :::note + In the `0.17.0` and `0.17.1` releases, shared-library inputs in the non-AOT modes were re-loaded as plain WASM after extracting their embedded bytes. Since the `0.17.2` release, they are rejected instead. Please set the run mode to `WasmEdge_RunMode_AOT` to load the AOT-compiled shared libraries. + ::: ```c WasmEdge_ConfigureContext *ConfCxt = WasmEdge_ConfigureCreate(); @@ -3333,6 +3338,17 @@ $ ./a.out [2021-07-02 11:08:08.706] [info] compile done ``` +To execute the compiled WASM in AOT mode, developers should set the [run mode](#configurations) to `WasmEdge_RunMode_AOT` in the configure context for creating the VM or loader context. With the default interpreter run mode, the AOT custom sections in universal WASM are ignored, and the shared library format is rejected. + +```c +WasmEdge_ConfigureContext *ConfCxt = WasmEdge_ConfigureCreate(); +WasmEdge_ConfigureSetRunMode(ConfCxt, WasmEdge_RunMode_AOT); +WasmEdge_VMContext *VMCxt = WasmEdge_VMCreate(ConfCxt, NULL); +/* ... Run the "fibonacci-aot.wasm" with the VM context. */ +WasmEdge_VMDelete(VMCxt); +WasmEdge_ConfigureDelete(ConfCxt); +``` + ### Compiler Options Developers can set options for AOT compilers such as optimization level and output format: diff --git a/docs/embed/c/reference/upgrade_to_0.17.0.md b/docs/embed/c/reference/upgrade_to_0.17.0.md index 16cad48e..e05c57cd 100644 --- a/docs/embed/c/reference/upgrade_to_0.17.0.md +++ b/docs/embed/c/reference/upgrade_to_0.17.0.md @@ -123,7 +123,12 @@ enum WasmEdge_RunMode { }; ``` -Only `WasmEdge_RunMode_AOT` loads AOT custom sections from universal WASM, or `dlopen`s shared-library WASM artifacts. In the other modes, AOT data is ignored, and shared-library inputs are re-loaded as plain WASM after extracting their embedded bytes. +Only `WasmEdge_RunMode_AOT` loads AOT custom sections from universal WASM, or `dlopen`s shared-library WASM artifacts. In the other modes, the AOT custom sections in universal WASM are ignored, and shared-library inputs are rejected with the `WasmEdge_ErrCode_MalformedMagic` error. + + +:::note +In the `0.17.0` and `0.17.1` releases, shared-library inputs in the non-AOT modes were re-loaded as plain WASM after extracting their embedded bytes. Since the `0.17.2` release, they are rejected instead. Developers who load the AOT-compiled shared libraries (`.so`, `.dylib`, or `.dll`) should set the run mode to `WasmEdge_RunMode_AOT`. +::: ```c WasmEdge_ConfigureContext *ConfCxt = WasmEdge_ConfigureCreate(); diff --git a/docs/start/build-and-run/aot.md b/docs/start/build-and-run/aot.md index 3dd79a52..86899f44 100644 --- a/docs/start/build-and-run/aot.md +++ b/docs/start/build-and-run/aot.md @@ -16,7 +16,7 @@ USAGE ... ``` -The `wasmedge compile` command can compile WebAssembly into native machine code (i.e., the AOT compiler). For the pure WebAssembly, the `wasmedge` tool will execute the WASM in interpreter mode. After compiling with the `wasmedge compile` AOT compiler, the `wasmedge` tool can execute the WASM in AOT mode, which is much faster. +The `wasmedge compile` command can compile WebAssembly into native machine code (i.e., the AOT compiler). For the pure WebAssembly, the `wasmedge` tool will execute the WASM in interpreter mode. After compiling with the `wasmedge compile` AOT compiler, the `wasmedge` tool can execute the WASM in AOT mode with the `--run-mode=aot` option, which is much faster. ## Options @@ -108,10 +108,10 @@ The output will be: [2022-09-09 14:22:10.600] [info] compile done ``` -Then you can execute the output file with `wasmedge` and measure the execution time: +Then you can execute the output file with `wasmedge` in AOT mode and measure the execution time: ```bash -time wasmedge --reactor fibonacci_aot.wasm fib 30 +time wasmedge --run-mode=aot --reactor fibonacci_aot.wasm fib 30 ``` The output will be: @@ -144,7 +144,7 @@ sys 0m0.012s By default, the `wasmedge compile` AOT compiler tool could wrap the AOT-compiled native binary into a custom section in the origin WASM file. We call this the universal WASM binary format. -This AOT-compiled WASM file is compatible with any WebAssembly runtime. However, when this WASM file is executed by the WasmEdge runtime, WasmEdge will extract the native binary from the custom section and execute it in AOT mode. +This AOT-compiled WASM file is compatible with any WebAssembly runtime. However, when this WASM file is executed by the WasmEdge runtime in the AOT run mode, WasmEdge will extract the native binary from the custom section and execute it in AOT mode. In the other run modes (the default is interpreter), the custom section is ignored and the WASM is executed as a normal WASM file. :::note @@ -153,7 +153,7 @@ On MacOS platforms, the universal WASM format will `bus error` in execution. By ```bash wasmedge compile app.wasm app_aot.wasm -wasmedge app_aot.wasm +wasmedge --run-mode=aot app_aot.wasm ``` ## Output Format: Shared Library @@ -164,5 +164,10 @@ This AOT-compiled WASM file is only for WasmEdge use and cannot be used by other ```bash wasmedge compile app.wasm app_aot.so -wasmedge app_aot.so +wasmedge --run-mode=aot app_aot.so ``` + + +:::note +Since `0.17.2`, the shared library format is only loadable in the AOT run mode. Executing it without `--run-mode=aot` will fail in loading. +::: diff --git a/docs/start/build-and-run/cli.md b/docs/start/build-and-run/cli.md index b1a4bf1c..27c36d49 100644 --- a/docs/start/build-and-run/cli.md +++ b/docs/start/build-and-run/cli.md @@ -11,7 +11,7 @@ The `wasmedge` binary is a command line interface (CLI) program that runs WebAss - If the WebAssembly program contains a `main()` function, `wasmedge` would execute it as a standalone program in the command mode. - If the WebAssembly program contains one or more exported public functions, `wasmedge` could invoke individual functions in the reactor mode. -By default, the `wasmedge` will execute WebAssembly programs in interpreter mode and execute the AOT-compiled `.so`, `.dylib`, `.dll`, or `.wasm` (universal output format) in AOT mode. If you want to accelerate the WASM execution, we recommend to [compile the WebAssembly with the AOT compiler](aot.md) first. +By default, the `wasmedge` will execute WebAssembly programs in interpreter mode. If you want to accelerate the WASM execution, we recommend to [compile the WebAssembly with the AOT compiler](aot.md) first, and then execute the AOT-compiled `.so`, `.dylib`, `.dll`, or `.wasm` (universal output format) in AOT mode with the `--run-mode=aot` option. :::note @@ -50,7 +50,7 @@ SUBCOMMANDS ... ``` -The `wasmedge` CLI tool will execute the wasm file in ahead-of-time(AOT) mode or interpreter mode. If the file has been compiled with `wasmedge compile`, then WasmEdge will execute it in AOT mode, otherwise, WasmEdge will execute it in interpreter mode. +The `wasmedge` CLI tool will execute the wasm file in interpreter mode by default. If the file has been compiled with `wasmedge compile` and the `--run-mode=aot` option is given, then WasmEdge will execute it in ahead-of-time(AOT) mode. ## Options @@ -64,6 +64,7 @@ The options of the `wasmedge` CLI tool are as follows: - If an exported function names `_initialize`, the function will be executed with the empty parameter at first. 4. _(Optional)_ `--dir`: Bind directories into WASI virtual filesystem. - Use `--dir guest_path:host_path` to bind the host path into the guest path in WASI virtual system. + - Use `--dir guest_path:host_path:readonly` to bind the host path in read-only mode. The default permission is `readwrite`. 5. _(Optional)_ `--env`: Assign the environment variables in WASI. - Use `--env ENV_NAME=VALUE` to assign the environment variable. 6. _(Optional)_ Statistics information: @@ -78,6 +79,8 @@ The options of the `wasmedge` CLI tool are as follows: - Use `--memory-page-limit PAGE_COUNT` to set the limitation of pages(as size of 64 KiB) in every memory instance. 8. _(Optional)_ Execution mode: - Use `--run-mode=` to select the WASM execution engine (case-insensitive, default `interpreter`). Available since `0.17.0`. + - Only `--run-mode=aot` executes the AOT-compiled code. In the other modes, the AOT-compiled code in the universal WASM format is ignored. + - Since `0.17.2`, the AOT-compiled shared libraries (`.so`, `.dylib`, or `.dll`) are only loadable with `--run-mode=aot`, and are rejected in the other modes. - DEPRECATED: Use `--force-interpreter` to forcibly run WASM in interpreter mode. Use `--run-mode=interpreter` instead. - DEPRECATED: Use `--enable-jit` to enable Just-In-Time compiler for running WASM. Use `--run-mode=jit` instead. 9. _(Optional)_ WebAssembly proposals: diff --git a/docs/start/getting-started/quick_start.md b/docs/start/getting-started/quick_start.md index fa729869..bd88fb17 100644 --- a/docs/start/getting-started/quick_start.md +++ b/docs/start/getting-started/quick_start.md @@ -48,11 +48,11 @@ $ wasmedge hello.wasm Hello WasmEdge! ``` -Use the AoT compiler `wasmedgec` to get much better performance. +Use the AoT compiler `wasmedgec` and run in AOT mode to get much better performance. ```bash $ wasmedgec hello.wasm hello_aot.wasm -$ wasmedge hello_aot.wasm +$ wasmedge --run-mode=aot hello_aot.wasm Hello WasmEdge! ``` diff --git a/docs/start/install.md b/docs/start/install.md index 39238749..c5941f32 100644 --- a/docs/start/install.md +++ b/docs/start/install.md @@ -98,7 +98,7 @@ The following lists are the WasmEdge official released plug-ins. Users can insta | Ffmpeg | `wasmedge_ffmpeg` | Linux (`x86_64`, `aarch64`), MacOS (`x86_64`, `arm64`) | Since `0.14.0` | | | Image | `wasmedge_image` | Linux (`x86_64`, `aarch64`), MacOS (`x86_64`, `arm64`) | Since `0.13.0` | | | LLM | `wasmedge_llmc` | Linux (`x86_64`, `aarch64`) | Since `0.14.1` | | -| OpenCV mini | `wasmedge_opencvmini` | Linux (`x86_64`, `aarch64`), MacOS (`x86_64`, `arm64`) | Since `0.13.3` | | +| OpenCV mini | `wasmedge_opencvmini` | Linux (`x86_64`, `aarch64`), MacOS (`x86_64`, `arm64`) | Since `0.13.3` | Since `0.17.2`, only released on MacOS `arm64`. | | Process | `wasmedge_process` | Linux (`x86_64`, `aarch64`) | Since `0.10.0` | | | Stable Diffusion | `wasmedge_stablediffusion` | Linux (`x86_64`, `aarch64`), MacOS (`x86_64`, `arm64`) | Since `0.14.1` | | | TensorFlow | `wasmedge_tensorflow` | Linux (`x86_64`, `aarch64`), MacOS (`x86_64`, `arm64`) | Since `0.13.0` | [Dependency](#tensorflow-dependencies) installed automatically by installer. | @@ -139,10 +139,10 @@ If you install into the `$HOME/.wasmedge` directory, you will have the following - The `wasmedge` tool is the standard WasmEdge runtime. You can use it from the CLI. - Execute a WASM file: `wasmedge --dir .:. app.wasm` - - The `wasmedgec` tool is the ahead-of-time (AOT) compiler to compile a `.wasm` file into a native `.so` file (or `.dylib` on MacOS, `.dll` on Windows, or `.wasm` as the universal WASM format on all platforms). The `wasmedge` can then execute the output file. + - The `wasmedgec` tool is the ahead-of-time (AOT) compiler to compile a `.wasm` file into a native `.so` file (or `.dylib` on MacOS, `.dll` on Windows, or `.wasm` as the universal WASM format on all platforms). The `wasmedge` can then execute the output file with the `--run-mode=aot` option. - Compile a WASM file into a AOT-compiled WASM: `wasmedgec app.wasm app.so` - - Execute the WASM in AOT mode: `wasmedge --dir .:. app.so` + - Execute the WASM in AOT mode: `wasmedge --run-mode=aot --dir .:. app.so` :::note diff --git a/docs/start/wasmedge/extensions/plugins.md b/docs/start/wasmedge/extensions/plugins.md index 38cc29f1..fb92ced8 100644 --- a/docs/start/wasmedge/extensions/plugins.md +++ b/docs/start/wasmedge/extensions/plugins.md @@ -27,7 +27,7 @@ The following lists are the WasmEdge official released plug-ins. Users can insta | [WasmEdge-FFmpeg](../../../contribute/source/plugin/wasmedge_ffmpeg.md) | FFmpeg-based audio and video processing for WebAssembly applications. | `manylinux2014 (x86_64, aarch64)`
`ubuntu 20.04 (x86_64)`
`darwin (x86_64, arm64)`
(since `0.14.0`) | Rust | [Steps](../../../contribute/source/plugin/wasmedge_ffmpeg.md) | | [WasmEdge-Image](../../../contribute/source/plugin/image.md) | A native library to manipulate images for AI inference tasks. | `manylinux2014 (x86_64, aarch64)`
`ubuntu 20.04 (x86_64)`
`darwin (x86_64, arm64)`
(since `0.13.0`) | [Rust](https://crates.io/crates/wasmedge_tensorflow_interface) (0.3.0) | [Steps](../../../contribute/source/plugin/image.md) | | WasmEdge-LLMC | | `manylinux2014 (x86_64, aarch64)`
`ubuntu 20.04 (x86_64)`
(since `0.14.1`) | | | -| [WasmEdge-OpenCVMini](../../../contribute/source/plugin/wasmedge_opencvmini.md) | A subset of OpenCV utility functions for image/video pre- and post-processing in AI workloads. | `manylinux2014 (x86_64, aarch64)`
`ubuntu 20.04 (x86_64)`
`darwin (x86_64, arm64)`
(since `0.13.3`) | Rust | [Steps](../../../contribute/source/plugin/wasmedge_opencvmini.md) | +| [WasmEdge-OpenCVMini](../../../contribute/source/plugin/wasmedge_opencvmini.md) | A subset of OpenCV utility functions for image/video pre- and post-processing in AI workloads. | `manylinux2014 (x86_64, aarch64)`
`ubuntu 20.04 (x86_64)`
`darwin (x86_64, arm64)`
(since `0.13.3`)
`darwin (arm64)` only
(since `0.17.2`) | Rust | [Steps](../../../contribute/source/plugin/wasmedge_opencvmini.md) | | [WasmEdge-Process](../../../contribute/source/plugin/process.md) | Allows WebAssembly programs to execute native commands in the host operating system. It supports passing arguments, environment variables, `STDIN`/`STDOUT` pipes, and security policies for host access. | `manylinux2014 (x86_64, aarch64)`
`ubuntu 20.04 (x86_64)`
(since `0.10.0`) | [Rust](https://crates.io/crates/wasmedge_process_interface) | [Steps](../../../contribute/source/plugin/process.md) | | [WasmEdge-StableDiffusion](../../../contribute/source/plugin/wasmedge_stablediffusion.md) | Image generation and inference using Stable Diffusion models. | `manylinux2014 (x86_64, aarch64)`
`ubuntu 20.04 (x86_64)`
`darwin (x86_64, arm64)`
(since `0.14.1`) | Rust | [Steps](../../../contribute/source/plugin/wasmedge_stablediffusion.md) | | [WasmEdge-Tensorflow](../../../contribute/source/plugin/tensorflow.md) | A native library for inferring TensorFlow models.| `manylinux2014 (x86_64, aarch64)`
`ubuntu 20.04 (x86_64)`
`darwin (x86_64, arm64)`
(since `0.13.0`) | [Rust](https://crates.io/crates/wasmedge_tensorflow_interface) (0.3.0) | [Steps](../../../contribute/source/plugin/tensorflow.md) | diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/embed/c/reference/upgrade_to_0.17.0.md b/i18n/zh/docusaurus-plugin-content-docs/current/embed/c/reference/upgrade_to_0.17.0.md index 16cad48e..e05c57cd 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/embed/c/reference/upgrade_to_0.17.0.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/embed/c/reference/upgrade_to_0.17.0.md @@ -123,7 +123,12 @@ enum WasmEdge_RunMode { }; ``` -Only `WasmEdge_RunMode_AOT` loads AOT custom sections from universal WASM, or `dlopen`s shared-library WASM artifacts. In the other modes, AOT data is ignored, and shared-library inputs are re-loaded as plain WASM after extracting their embedded bytes. +Only `WasmEdge_RunMode_AOT` loads AOT custom sections from universal WASM, or `dlopen`s shared-library WASM artifacts. In the other modes, the AOT custom sections in universal WASM are ignored, and shared-library inputs are rejected with the `WasmEdge_ErrCode_MalformedMagic` error. + + +:::note +In the `0.17.0` and `0.17.1` releases, shared-library inputs in the non-AOT modes were re-loaded as plain WASM after extracting their embedded bytes. Since the `0.17.2` release, they are rejected instead. Developers who load the AOT-compiled shared libraries (`.so`, `.dylib`, or `.dll`) should set the run mode to `WasmEdge_RunMode_AOT`. +::: ```c WasmEdge_ConfigureContext *ConfCxt = WasmEdge_ConfigureCreate();