Skip to content

Commit 26c0689

Browse files
committed
Update the docs for WasmEdge 0.14.0.
Signed-off-by: YiYing He <[email protected]>
1 parent d99728a commit 26c0689

File tree

115 files changed

+8239
-931
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

115 files changed

+8239
-931
lines changed

.env

+2-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
1-
WASMEDGE_VERSION='0.13.4'
1+
WASMEDGE_VERSION='0.14.0'
2+
WASMEDGE_GO_VERSION='0.13.4'

docs/contribute/installer.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,7 @@ The actual installer handles all stuff. It supports python2.7 (not tested on ear
134134
- Full Option: `--dist ubuntu20.04` or `--dist manylinux2014`
135135
- Note - the `ubuntu20.04` and `manylinux2014` values are case insensitive and only these two are currently supported.
136136
- Note - Specifying `--dist` value for `Darwin` has no effect.
137-
- Note - For `Linux` platform if the distribution matches exactly as `Ubuntu 20.04`, which is checked using `lsb_release` and python's ` platform.dist()` functionality is then set to `ubuntu20.04` if not specified, or it is used without questioning. However different release packages for WasmEdge are available only after `0.11.1` release, below which there is no effect of specifying this option.
137+
- Note - For `Linux` platform if the distribution matches exactly as `Ubuntu 20.04`, which is checked using `lsb_release` and python's `platform.dist()` functionality is then set to `ubuntu20.04` if not specified, or it is used without questioning. However different release packages for WasmEdge are available only after `0.11.1` release, below which there is no effect of specifying this option.
138138

139139
### Platform and OS
140140

docs/contribute/plugin/best_practice.md

+46-46
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,13 @@
22
sidebar_position: 6
33
---
44

5-
# Best Practice
5+
# Best Practice
66

77
When developing a WasmEdge plugin, it's important to follow best practices to ensure the plugin is well purformed, reliable, and efficient. Here are some key best practices to follow:
88

99
## Using the Latest Version of WasmEdge
1010

11-
Always use the latest version of WasmEdge to take advantage of the most recent features, improvements, and security updates.
11+
Always use the latest version of WasmEdge to take advantage of the most recent features, improvements, and security updates.
1212

1313
### Installing the Latest Version
1414

@@ -20,11 +20,10 @@ If you have existing plugins that were developed with an older version of WasmEd
2020

2121
Remember, using the latest version of WasmEdge not only ensures that you're leveraging the most recent features, but also provides the latest security updates to protect your applications.
2222

23-
2423
## Choosing the Appropriate Programming Language
2524

2625
WasmEdge plugins can be developed in several languages including [C](develop_plugin_c.md), [C++](develop_plugin_cpp.md), and [Rust](develop_plugin_rustsdk.md). The choice of language depends on the specific requirements of the plugin and the developer's expertise. The C API is recommended for most use cases due to its simplicity and wide support. However, complex plugins might benefit from the enhanced features of C++ or Rust.
27-
26+
2827
## Writing and Compiling the Plugin
2928

3029
When creating a WasmEdge plugin:
@@ -41,66 +40,66 @@ Testing is a crucial part of the plugin development process. It ensures that the
4140

4241
To run tests for the WasmEdge plugin, you'll need to follow a few steps. In this case, we'll use the `wasmedge-image` plugin as an example.
4342

44-
- **Step 1: Build the WasmEdge Runtime and WasmEdge-image Plugin**
43+
- **Step 1: Build the WasmEdge Runtime and WasmEdge-image Plugin**
4544
First, you need to build both the [build WasmEdge](../source/build_from_src.md) and the [wasmedge-image](../source/plugin/image.md) plugin.
4645

47-
- **Step 2: Run the Tests**
46+
- **Step 2: Run the Tests**
4847
The WasmEdge repository provides a set of tests for various plugins, including `wasmedge-image`. You can find the test cases in the `test/plugins/wasmedge_image` directory of the repository.
4948

50-
To run these tests, you can use the `ctest` command from the build directory:
49+
To run these tests, you can use the `ctest` command from the build directory:
5150

52-
```bash
53-
cd ../../../test/plugins/wasmedge_image
54-
mkdir build && cd build
55-
cmake ..
56-
make
57-
ctest
58-
```
51+
```bash
52+
cd ../../../test/plugins/wasmedge_image
53+
mkdir build && cd build
54+
cmake ..
55+
make
56+
ctest
57+
```
5958

60-
This will run all the unit tests and integration tests for the `wasmedge-image `plugin. These tests ensure that the plugin behaves as expected, meets the requirements, and performs optimally. They also verify that the plugin correctly integrates with the WebAssembly program and that the WebAssembly program can call the plugin's functions correctly.
59+
This will run all the unit tests and integration tests for the `wasmedge-image`plugin. These tests ensure that the plugin behaves as expected, meets the requirements, and performs optimally. They also verify that the plugin correctly integrates with the WebAssembly program and that the WebAssembly program can call the plugin's functions correctly.
6160

62-
- **Step 3: Analyze the Test Results**
61+
- **Step 3: Analyze the Test Results**
6362
After running the tests, analyze the results to identify any issues or bugs. If any test fails, you should debug the issue, fix the problem, and then rerun the tests to ensure that the fix works as expected.
6463

6564
By following these steps, you can effectively run tests for the `wasmedge-image` plugin or any other WasmEdge plugin.
6665

6766
<!-- prettier-ignore -->
6867
:::note
6968
If you want to develop your own tests follow [Writing Tests for WasmEdge Plugins](test_plugin.md) for details.
70-
:::
69+
:::
7170

7271
## Securing the Plugin
7372

7473
Security is a vital part of any software development process. It involves several aspects, including securing the code, verifying inputs, handling errors properly, and using secure coding practices. When developing a WasmEdge plugin, it's essential to follow these best practices:
7574

76-
- **Validate Inputs:** Always validate the inputs to your functions. This can prevent many types of attacks, including buffer overflow attacks and code injection attacks.
75+
- **Validate Inputs:** Always validate the inputs to your functions. This can prevent many types of attacks, including buffer overflow attacks and code injection attacks.
7776

78-
```c
79-
WasmEdge_Result Add(void *, const WasmEdge_CallingFrameContext *,
80-
const WasmEdge_Value *In, WasmEdge_Value *Out) {
81-
if (In[0].Type != WasmEdge_ValType_I32 || In[1].Type != WasmEdge_ValType_I32) {
82-
return WasmEdge_Result_Error;
83-
}
84-
// Rest of the function...
77+
```c
78+
WasmEdge_Result Add(void *, const WasmEdge_CallingFrameContext *,
79+
const WasmEdge_Value *In, WasmEdge_Value *Out) {
80+
if (In[0].Type != WasmEdge_ValType_I32 || In[1].Type != WasmEdge_ValType_I32) {
81+
return WasmEdge_Result_Error;
8582
}
86-
```
87-
88-
- **Handle Errors:** Always handle errors properly. Don't ignore return values that indicate an error, and don't continue execution after an error occurs.
89-
90-
```c
91-
WasmEdge_Result Add(void *, const WasmEdge_CallingFrameContext *,
92-
const WasmEdge_Value *In, WasmEdge_Value *Out) {
93-
// Check the input types...
94-
int32_t Val1 = WasmEdge_ValueGetI32(In[0]);
95-
int32_t Val2 = WasmEdge_ValueGetI32(In[1]);
96-
if (Val1 == INT32_MIN || Val2 == INT32_MIN) {
97-
return WasmEdge_Result_Error;
98-
}
99-
// Rest of the function...
83+
// Rest of the function...
84+
}
85+
```
86+
87+
- **Handle Errors:** Always handle errors properly. Don't ignore return values that indicate an error, and don't continue execution after an error occurs.
88+
89+
```c
90+
WasmEdge_Result Add(void *, const WasmEdge_CallingFrameContext *,
91+
const WasmEdge_Value *In, WasmEdge_Value *Out) {
92+
// Check the input types...
93+
int32_t Val1 = WasmEdge_ValueGetI32(In[0]);
94+
int32_t Val2 = WasmEdge_ValueGetI32(In[1]);
95+
if (Val1 == INT32_MIN || Val2 == INT32_MIN) {
96+
return WasmEdge_Result_Error;
10097
}
101-
```
98+
// Rest of the function...
99+
}
100+
```
102101

103-
- **Use Secure Coding Practices:** Follow secure coding practices in your chosen language. For example, avoid using unsafe functions, use strong types, and avoid using global variables.
102+
- **Use Secure Coding Practices:** Follow secure coding practices in your chosen language. For example, avoid using unsafe functions, use strong types, and avoid using global variables.
104103

105104
## Publishing the Plugin
106105

@@ -116,38 +115,39 @@ You can create a Rust library that provides a Rust interface to your plugin's fu
116115

117116
In the [wasmedge-image](../source/plugin/image.md) plugin's case, you might have something like this:
118117

119-
```rust
118+
```rust
120119
// lib.rs
121120
extern crate wasmedge_image;
122121

123122
use wasmedge_image::Image;
124123

125124
pub fn load_image(path: &str) -> Result<Image, wasmedge_image::Error> {
126-
Image::open(path)
125+
Image::open(path)
127126
}
128127
```
128+
129129
In this Rust library, a single `load_image` function is provided that calls the `open` function from the `wasmedge-image` plugin.
130130

131131
### Building the Rust Library
132132

133133
You can build your Rust library using Cargo, the Rust package manager. This will produce a `.so` file that can be loaded by the WasmEdge runtime.
134134

135-
```bash
135+
```bash
136136
cargo build --release
137137
```
138138

139139
### Packaging the Rust SDK
140140

141141
Package the Rust library and the header file into a tarball or a similar package format. This makes it easy for other developers to download and install your SDK.
142142

143-
```bash
143+
```bash
144144
tar czvf wasmedge_image_rust_sdk.tar.gz libwasmedge_image.so wasmedge_image.h
145145
```
146146

147147
With this package, other rust developers can easily use your plugin in their applications. They just need to include your header file in their code, and link against your rust library when they compile their application.
148148

149149
Now, when you're ready to publish your plugin and the corresponding SDK, can publish your plugin on the official WasmEdge [plugin repository](https://github.com/WasmEdge/WasmEdge/tree/master/plugins) by creating a pull request into it or any other repository of your choice. Make sure to include the documentation and any other resources (like test files) with your plugin.
150-
150+
151151
## Contributing to the WasmEdge Community
152152

153153
As an open-source contributor, you can share your plugin with the community by submitting it to the official [WasmEdge repository](https://github.com/WasmEdge/WasmEdge). This allows others to benefit from your work.

docs/contribute/plugin/develop_plugin_c.md

+21-21
Original file line numberDiff line numberDiff line change
@@ -95,17 +95,17 @@ WasmEdge_Result HostFuncSub(void *Data,
9595
WasmEdge_ModuleInstanceContext *
9696
CreateTestModule(const struct WasmEdge_ModuleDescriptor *Desc) {
9797
/*
98-
* The `Desc` is the const pointer to the module descriptor struct:
99-
*
100-
* typedef struct WasmEdge_ModuleDescriptor {
101-
* const char *Name;
102-
* const char *Description;
103-
* WasmEdge_ModuleInstanceContext *(*Create)(
104-
* const struct WasmEdge_ModuleDescriptor *);
105-
* } WasmEdge_ModuleDescriptor;
106-
*
107-
* Developers can get the name and description from this descriptor.
108-
*/
98+
* The `Desc` is the const pointer to the module descriptor struct:
99+
*
100+
* typedef struct WasmEdge_ModuleDescriptor {
101+
* const char *Name;
102+
* const char *Description;
103+
* WasmEdge_ModuleInstanceContext *(*Create)(
104+
* const struct WasmEdge_ModuleDescriptor *);
105+
* } WasmEdge_ModuleDescriptor;
106+
*
107+
* Developers can get the name and description from this descriptor.
108+
*/
109109
110110
/* Exported module name of this module instance. */
111111
WasmEdge_String ModuleName =
@@ -117,10 +117,10 @@ WasmEdge_Result HostFuncSub(void *Data,
117117
WasmEdge_String FuncName;
118118
WasmEdge_FunctionTypeContext *FType;
119119
WasmEdge_FunctionInstanceContext *FuncCxt;
120-
enum WasmEdge_ValType ParamTypes[2], ReturnTypes[1];
121-
ParamTypes[0] = WasmEdge_ValType_I32;
122-
ParamTypes[1] = WasmEdge_ValType_I32;
123-
ReturnTypes[0] = WasmEdge_ValType_I32;
120+
WasmEdge_ValType ParamTypes[2], ReturnTypes[1];
121+
ParamTypes[0] = WasmEdge_ValTypeGenI32();
122+
ParamTypes[1] = WasmEdge_ValTypeGenI32();
123+
ReturnTypes[0] = WasmEdge_ValTypeGenI32();
124124
125125
/* Create and add the host function instances into the module instance. */
126126
FType = WasmEdge_FunctionTypeCreate(ParamTypes, 2, ReturnTypes, 1);
@@ -148,9 +148,9 @@ WasmEdge_Result HostFuncSub(void *Data,
148148
/* The module descriptor array. There can be multiple modules in a plug-in. */
149149
static WasmEdge_ModuleDescriptor ModuleDesc[] = {{
150150
/*
151-
* Module name. This is the name for searching and creating the module
152-
* instance context by the `WasmEdge_PluginCreateModule()` API.
153-
*/
151+
* Module name. This is the name for searching and creating the module
152+
* instance context by the `WasmEdge_PluginCreateModule()` API.
153+
*/
154154
.Name = "wasmedge_plugintest_c_module",
155155
/* Module description. */
156156
.Description = "This is for the plugin tests in WasmEdge C API.",
@@ -161,9 +161,9 @@ WasmEdge_Result HostFuncSub(void *Data,
161161
/* The plug-in descriptor */
162162
static WasmEdge_PluginDescriptor Desc[] = {{
163163
/*
164-
* Plug-in name. This is the name for searching the plug-in context by the
165-
* `WasmEdge_PluginFind()` API.
166-
*/
164+
* Plug-in name. This is the name for searching the plug-in context by the
165+
* `WasmEdge_PluginFind()` API.
166+
*/
167167
.Name = "wasmedge_plugintest_c",
168168
/* Plug-in description. */
169169
.Description = "",

docs/contribute/plugin/intro.md

+1-22
Original file line numberDiff line numberDiff line change
@@ -73,25 +73,4 @@ By following this flowchart, developers can effectively load loadable plug-ins i
7373

7474
## WasmEdge Currently Released Plug-ins
7575

76-
There are several plug-in releases with the WasmEdge official releases. Please check the following table to check the release status and how to build from the source with the plug-ins.
77-
78-
| Plug-in | Rust Crate | Released Platforms | Build Steps |
79-
| --- | --- | --- | --- |
80-
| [WasmEdge-Process](../source/plugin/process.md) | [wasmedge_process_interface][] | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.10.0`) | [Build Wtih WasmEdge-Process](../source/plugin/process.md) |
81-
| [WASI-Crypto][] | [wasi-crypto][] | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.10.1`) | [Build With WASI-Crypto](../source/plugin/wasi_crypto.md) |
82-
| [WASI-NN with OpenVINO backend](../../develop/rust/wasinn/openvino.md) | [wasi-nn][] | `ubuntu 20.04 x86_64` (since `0.10.1`) | [Build With WASI-NN](../source/plugin/wasi_nn.md#build-wasmedge-with-wasi-nn-openvino-backend) |
83-
| [WASI-NN with PyTorch backend](../../develop/rust/wasinn/pytorch.md) | [wasi-nn][] | `ubuntu 20.04 x86_64` (since `0.11.1`) | [Build With WASI-NN](../source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-pytorch-backend) |
84-
| [WASI-NN with TensorFlow-Lite backend](../../develop/rust/wasinn/tensorflow_lite.md) | [wasi-nn][] | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.11.2`) | [Build With WASI-NN](../source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-tensorflow-lite-backend) |
85-
| [WasmEdge-Image](../source/plugin/image.md) | [wasmedge_tensorflow_interface][] | `manylinux2014 x86_64`, `manylinux2014 aarch64`, `ubuntu 20.04 x86_64`, `darwin x86_64`, and `darwin arm64` (since `0.13.0`) | [Build With WasmEdge-Image](../source/plugin/image.md) |
86-
| [WasmEdge-Tensorflow](../source/plugin/tensorflow.md) | [wasmedge_tensorflow_interface][] | `manylinux2014 x86_64`, `manylinux2014 aarch64`, `ubuntu 20.04 x86_64`, `darwin x86_64`, and `darwin arm64` (since `0.13.0`) | [Build With WasmEdge-Tensorflow](../source/plugin/tensorflow.md) |
87-
| [WasmEdge-TensorflowLite](../source/plugin/tensorflowlite.md) | [wasmedge_tensorflow_interface][] | `manylinux2014 x86_64`, `manylinux2014 aarch64`, `ubuntu 20.04 x86_64`, `darwin x86_64`, and `darwin arm64` (since `0.13.0`) | [Build With WasmEdge-TensorflowLite](../source/plugin/tensorflowlite.md) |
88-
89-
<!-- prettier-ignore -->
90-
:::note
91-
Due to the `OpenVINO` dependency, we only release the WASI-NN plug-in for the `OpenVINO` backend on `Ubuntu 20.04 x86_64` now. We'll work with `manylinux2014` versions in the future.
92-
:::
93-
94-
[wasmedge_process_interface]: https://crates.io/crates/wasmedge_process_interface
95-
[wasmedge_tensorflow_interface]: https://crates.io/crates/wasmedge_tensorflow_interface
96-
[wasi-crypto]: https://crates.io/crates/wasi-crypto
97-
[wasi-nn]: https://crates.io/crates/wasi-nn
76+
Users can install the [WasmEdge official released plug-ins](../../start/wasmedge/extensions/plugins.md) from the installer, or build them from source.

docs/contribute/plugin/test_plugin.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -62,4 +62,4 @@ If everything is set up correctly, this will compile your tests, run them, and r
6262

6363
Remember, testing is an iterative process. As you develop new features or fix bugs, you should also update your tests to reflect these changes. This will ensure that your plugin continues to work as expected as it evolves.
6464

65-
We hope this guide helps you get started with writing tests for your WasmEdge plugins!
65+
We hope this guide helps you get started with writing tests for your WasmEdge plugins!

docs/contribute/release.md

-4
Original file line numberDiff line numberDiff line change
@@ -58,10 +58,6 @@ sidebar_position: 9
5858

5959
Following projects will be updated with the `Alpha`, `Beta`, and `RC` pre-releases and the official release:
6060

61-
- [ ] [WasmEdge-Image](https://github.com/second-state/WasmEdge-image)
62-
- [ ] [WasmEdge-TensorFlow-Deps](https://github.com/second-state/WasmEdge-tensorflow-deps)
63-
- [ ] [WasmEdge-TensorFlow](https://github.com/second-state/WasmEdge-tensorflow)
64-
- [ ] [WasmEdge-TensorFlow-Tools](https://github.com/second-state/WasmEdge-tensorflow-tools)
6561
- [ ] [WasmEdge-Go SDK](https://github.com/second-state/WasmEdge-go)
6662
- [ ] [WasmEdge-core NAPI package](https://github.com/second-state/wasmedge-core)
6763
- [ ] [WasmEdge-extensions NAPI package](https://github.com/second-state/wasmedge-extensions)

docs/contribute/source/build_from_src.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ WasmEdge provides various tools for enabling different runtime environments for
5151
Developers can set the CMake options to customize the WasmEdge building.
5252

5353
1. `WASMEDGE_BUILD_TESTS`: build the WasmEdge tests. Default is `OFF`.
54-
2. `WASMEDGE_BUILD_AOT_RUNTIME`: build with the Ahead-of-Time compiler supporting. Default is `ON`.
54+
2. `WASMEDGE_USE_LLVM`: build with LLVM-based runtime for supporting Ahead-of-Time and Just-In-Time compiler. Default is `ON`.
5555
3. `WASMEDGE_BUILD_SHARED_LIB`: build the WasmEdge shared library (`libwasmedge.so`, `libwasmedge.dylib`, or `wasmedge.dll`). Default is `ON`.
5656
- By default, the WasmEdge shared library will link to the LLVM shared library.
5757
4. `WASMEDGE_BUILD_STATIC_LIB`: build the WasmEdge static library (`libwasmedge.a`, Linux and MacOS platforms, experimental). Default is `OFF`.
@@ -60,7 +60,7 @@ Developers can set the CMake options to customize the WasmEdge building.
6060
- For linking with `libwasmedge.a`, developers should also add the `-ldl`, `-pthread`, `-lm`, and `-lstdc++` linker options on both Linux and MacOS platforms, and `-lrt` on Linux platforms.
6161
5. `WASMEDGE_BUILD_TOOLS`: build the `wasmedge` and `wasmedgec` tools. Default is `ON`.
6262
- The `wasmedge` and `wasmedgec` tools will link to the WasmEdge shared library by default.
63-
- If this option is set as `ON` and `WASMEDGE_BUILD_AOT_RUNTIME` is set as `OFF`, the `wasmedgec` tool for the AOT compiler will not be built.
63+
- If this option is set as `ON` and `WASMEDGE_USE_LLVM` is set as `OFF`, the `wasmedgec` tool for the AOT compiler will not be built.
6464
- If this option is set as `ON` but the option `WASMEDGE_LINK_TOOLS_STATIC` is set as `OFF`, the option `WASMEDGE_BUILD_SHARED_LIB` will forcefully be set as `ON`.
6565
- If this option and the option `WASMEDGE_LINK_TOOLS_STATIC` are both set as `ON`, the `WASMEDGE_LINK_LLVM_STATIC` and `WASMEDGE_BUILD_STATIC_LIB` will both be set as `ON`, and the `wasmedge` and `wasmedgec` tools will link to the WasmEdge static library instead. In this case, the plug-ins will not work in tools.
6666
6. `WASMEDGE_BUILD_PLUGINS`: build the WasmEdge plug-ins. Default is `ON`.

0 commit comments

Comments
 (0)