Skip to content

Commit

Permalink
Update the docs for WasmEdge 0.14.0.
Browse files Browse the repository at this point in the history
Signed-off-by: YiYing He <[email protected]>
  • Loading branch information
q82419 committed May 24, 2024
1 parent d99728a commit 26c0689
Show file tree
Hide file tree
Showing 115 changed files with 8,239 additions and 931 deletions.
3 changes: 2 additions & 1 deletion .env
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
WASMEDGE_VERSION='0.13.4'
WASMEDGE_VERSION='0.14.0'
WASMEDGE_GO_VERSION='0.13.4'
2 changes: 1 addition & 1 deletion docs/contribute/installer.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ The actual installer handles all stuff. It supports python2.7 (not tested on ear
- Full Option: `--dist ubuntu20.04` or `--dist manylinux2014`
- Note - the `ubuntu20.04` and `manylinux2014` values are case insensitive and only these two are currently supported.
- Note - Specifying `--dist` value for `Darwin` has no effect.
- 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.
- 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.

### Platform and OS

Expand Down
92 changes: 46 additions & 46 deletions docs/contribute/plugin/best_practice.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@
sidebar_position: 6
---

# Best Practice
# Best Practice

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:

## Using the Latest Version of WasmEdge

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

### Installing the Latest Version

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

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.


## Choosing the Appropriate Programming Language

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.

## Writing and Compiling the Plugin

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

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.

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

- **Step 2: Run the Tests**
- **Step 2: Run the Tests**
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.

To run these tests, you can use the `ctest` command from the build directory:
To run these tests, you can use the `ctest` command from the build directory:

```bash
cd ../../../test/plugins/wasmedge_image
mkdir build && cd build
cmake ..
make
ctest
```
```bash
cd ../../../test/plugins/wasmedge_image
mkdir build && cd build
cmake ..
make
ctest
```

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

- **Step 3: Analyze the Test Results**
- **Step 3: Analyze the Test Results**
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.

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

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

## Securing the Plugin

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:

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

```c
WasmEdge_Result Add(void *, const WasmEdge_CallingFrameContext *,
const WasmEdge_Value *In, WasmEdge_Value *Out) {
if (In[0].Type != WasmEdge_ValType_I32 || In[1].Type != WasmEdge_ValType_I32) {
return WasmEdge_Result_Error;
}
// Rest of the function...
```c
WasmEdge_Result Add(void *, const WasmEdge_CallingFrameContext *,
const WasmEdge_Value *In, WasmEdge_Value *Out) {
if (In[0].Type != WasmEdge_ValType_I32 || In[1].Type != WasmEdge_ValType_I32) {
return WasmEdge_Result_Error;
}
```

- **Handle Errors:** Always handle errors properly. Don't ignore return values that indicate an error, and don't continue execution after an error occurs.

```c
WasmEdge_Result Add(void *, const WasmEdge_CallingFrameContext *,
const WasmEdge_Value *In, WasmEdge_Value *Out) {
// Check the input types...
int32_t Val1 = WasmEdge_ValueGetI32(In[0]);
int32_t Val2 = WasmEdge_ValueGetI32(In[1]);
if (Val1 == INT32_MIN || Val2 == INT32_MIN) {
return WasmEdge_Result_Error;
}
// Rest of the function...
// Rest of the function...
}
```
- **Handle Errors:** Always handle errors properly. Don't ignore return values that indicate an error, and don't continue execution after an error occurs.
```c
WasmEdge_Result Add(void *, const WasmEdge_CallingFrameContext *,
const WasmEdge_Value *In, WasmEdge_Value *Out) {
// Check the input types...
int32_t Val1 = WasmEdge_ValueGetI32(In[0]);
int32_t Val2 = WasmEdge_ValueGetI32(In[1]);
if (Val1 == INT32_MIN || Val2 == INT32_MIN) {
return WasmEdge_Result_Error;
}
```
// Rest of the function...
}
```

- **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.
- **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.

## Publishing the Plugin

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

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

```rust
```rust
// lib.rs
extern crate wasmedge_image;

use wasmedge_image::Image;

pub fn load_image(path: &str) -> Result<Image, wasmedge_image::Error> {
Image::open(path)
Image::open(path)
}
```

In this Rust library, a single `load_image` function is provided that calls the `open` function from the `wasmedge-image` plugin.

### Building the Rust Library

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.

```bash
```bash
cargo build --release
```

### Packaging the Rust SDK

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.

```bash
```bash
tar czvf wasmedge_image_rust_sdk.tar.gz libwasmedge_image.so wasmedge_image.h
```

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.

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.

## Contributing to the WasmEdge Community

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.
Expand Down
42 changes: 21 additions & 21 deletions docs/contribute/plugin/develop_plugin_c.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,17 +95,17 @@ WasmEdge_Result HostFuncSub(void *Data,
WasmEdge_ModuleInstanceContext *
CreateTestModule(const struct WasmEdge_ModuleDescriptor *Desc) {
/*
* The `Desc` is the const pointer to the module descriptor struct:
*
* typedef struct WasmEdge_ModuleDescriptor {
* const char *Name;
* const char *Description;
* WasmEdge_ModuleInstanceContext *(*Create)(
* const struct WasmEdge_ModuleDescriptor *);
* } WasmEdge_ModuleDescriptor;
*
* Developers can get the name and description from this descriptor.
*/
* The `Desc` is the const pointer to the module descriptor struct:
*
* typedef struct WasmEdge_ModuleDescriptor {
* const char *Name;
* const char *Description;
* WasmEdge_ModuleInstanceContext *(*Create)(
* const struct WasmEdge_ModuleDescriptor *);
* } WasmEdge_ModuleDescriptor;
*
* Developers can get the name and description from this descriptor.
*/
/* Exported module name of this module instance. */
WasmEdge_String ModuleName =
Expand All @@ -117,10 +117,10 @@ WasmEdge_Result HostFuncSub(void *Data,
WasmEdge_String FuncName;
WasmEdge_FunctionTypeContext *FType;
WasmEdge_FunctionInstanceContext *FuncCxt;
enum WasmEdge_ValType ParamTypes[2], ReturnTypes[1];
ParamTypes[0] = WasmEdge_ValType_I32;
ParamTypes[1] = WasmEdge_ValType_I32;
ReturnTypes[0] = WasmEdge_ValType_I32;
WasmEdge_ValType ParamTypes[2], ReturnTypes[1];
ParamTypes[0] = WasmEdge_ValTypeGenI32();
ParamTypes[1] = WasmEdge_ValTypeGenI32();
ReturnTypes[0] = WasmEdge_ValTypeGenI32();
/* Create and add the host function instances into the module instance. */
FType = WasmEdge_FunctionTypeCreate(ParamTypes, 2, ReturnTypes, 1);
Expand Down Expand Up @@ -148,9 +148,9 @@ WasmEdge_Result HostFuncSub(void *Data,
/* The module descriptor array. There can be multiple modules in a plug-in. */
static WasmEdge_ModuleDescriptor ModuleDesc[] = {{
/*
* Module name. This is the name for searching and creating the module
* instance context by the `WasmEdge_PluginCreateModule()` API.
*/
* Module name. This is the name for searching and creating the module
* instance context by the `WasmEdge_PluginCreateModule()` API.
*/
.Name = "wasmedge_plugintest_c_module",
/* Module description. */
.Description = "This is for the plugin tests in WasmEdge C API.",
Expand All @@ -161,9 +161,9 @@ WasmEdge_Result HostFuncSub(void *Data,
/* The plug-in descriptor */
static WasmEdge_PluginDescriptor Desc[] = {{
/*
* Plug-in name. This is the name for searching the plug-in context by the
* `WasmEdge_PluginFind()` API.
*/
* Plug-in name. This is the name for searching the plug-in context by the
* `WasmEdge_PluginFind()` API.
*/
.Name = "wasmedge_plugintest_c",
/* Plug-in description. */
.Description = "",
Expand Down
23 changes: 1 addition & 22 deletions docs/contribute/plugin/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,25 +73,4 @@ By following this flowchart, developers can effectively load loadable plug-ins i

## WasmEdge Currently Released Plug-ins

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.

| Plug-in | Rust Crate | Released Platforms | Build Steps |
| --- | --- | --- | --- |
| [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) |
| [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) |
| [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) |
| [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) |
| [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) |
| [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) |
| [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) |
| [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) |

<!-- prettier-ignore -->
:::note
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.
:::

[wasmedge_process_interface]: https://crates.io/crates/wasmedge_process_interface
[wasmedge_tensorflow_interface]: https://crates.io/crates/wasmedge_tensorflow_interface
[wasi-crypto]: https://crates.io/crates/wasi-crypto
[wasi-nn]: https://crates.io/crates/wasi-nn
Users can install the [WasmEdge official released plug-ins](../../start/wasmedge/extensions/plugins.md) from the installer, or build them from source.
2 changes: 1 addition & 1 deletion docs/contribute/plugin/test_plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,4 +62,4 @@ If everything is set up correctly, this will compile your tests, run them, and r

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.

We hope this guide helps you get started with writing tests for your WasmEdge plugins!
We hope this guide helps you get started with writing tests for your WasmEdge plugins!
4 changes: 0 additions & 4 deletions docs/contribute/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,10 +58,6 @@ sidebar_position: 9

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

- [ ] [WasmEdge-Image](https://github.com/second-state/WasmEdge-image)
- [ ] [WasmEdge-TensorFlow-Deps](https://github.com/second-state/WasmEdge-tensorflow-deps)
- [ ] [WasmEdge-TensorFlow](https://github.com/second-state/WasmEdge-tensorflow)
- [ ] [WasmEdge-TensorFlow-Tools](https://github.com/second-state/WasmEdge-tensorflow-tools)
- [ ] [WasmEdge-Go SDK](https://github.com/second-state/WasmEdge-go)
- [ ] [WasmEdge-core NAPI package](https://github.com/second-state/wasmedge-core)
- [ ] [WasmEdge-extensions NAPI package](https://github.com/second-state/wasmedge-extensions)
4 changes: 2 additions & 2 deletions docs/contribute/source/build_from_src.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ WasmEdge provides various tools for enabling different runtime environments for
Developers can set the CMake options to customize the WasmEdge building.

1. `WASMEDGE_BUILD_TESTS`: build the WasmEdge tests. Default is `OFF`.
2. `WASMEDGE_BUILD_AOT_RUNTIME`: build with the Ahead-of-Time compiler supporting. Default is `ON`.
2. `WASMEDGE_USE_LLVM`: build with LLVM-based runtime for supporting Ahead-of-Time and Just-In-Time compiler. Default is `ON`.
3. `WASMEDGE_BUILD_SHARED_LIB`: build the WasmEdge shared library (`libwasmedge.so`, `libwasmedge.dylib`, or `wasmedge.dll`). Default is `ON`.
- By default, the WasmEdge shared library will link to the LLVM shared library.
4. `WASMEDGE_BUILD_STATIC_LIB`: build the WasmEdge static library (`libwasmedge.a`, Linux and MacOS platforms, experimental). Default is `OFF`.
Expand All @@ -60,7 +60,7 @@ Developers can set the CMake options to customize the WasmEdge building.
- 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.
5. `WASMEDGE_BUILD_TOOLS`: build the `wasmedge` and `wasmedgec` tools. Default is `ON`.
- The `wasmedge` and `wasmedgec` tools will link to the WasmEdge shared library by default.
- 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.
- 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.
- 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`.
- 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.
6. `WASMEDGE_BUILD_PLUGINS`: build the WasmEdge plug-ins. Default is `ON`.
Expand Down
Loading

0 comments on commit 26c0689

Please sign in to comment.