From 2da1beca1cf18735a5d218981a69680391e59677 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Mon, 12 Jun 2023 16:23:53 +0600 Subject: [PATCH 01/20] added plugin requirement Signed-off-by: Mahfuza --- docs/contribute/plugin/_category_.json | 2 +- docs/contribute/plugin/develop_plugin_c.md | 2 +- docs/contribute/plugin/develop_plugin_cpp.md | 2 +- docs/contribute/plugin/plugin_requirement.md | 177 +++++++++++++++++++ 4 files changed, 180 insertions(+), 3 deletions(-) create mode 100644 docs/contribute/plugin/plugin_requirement.md diff --git a/docs/contribute/plugin/_category_.json b/docs/contribute/plugin/_category_.json index 68e107565..565c053ce 100644 --- a/docs/contribute/plugin/_category_.json +++ b/docs/contribute/plugin/_category_.json @@ -3,6 +3,6 @@ "position": 3, "link": { "type": "generated-index", - "description": "we will learn how to the WasmEdge Plugin System." + "description": "we will learn how to develop the WasmEdge Plugin System." } } diff --git a/docs/contribute/plugin/develop_plugin_c.md b/docs/contribute/plugin/develop_plugin_c.md index 02db9c11e..1853be0ee 100644 --- a/docs/contribute/plugin/develop_plugin_c.md +++ b/docs/contribute/plugin/develop_plugin_c.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 --- # Develop WasmEdge Plug-in in C API diff --git a/docs/contribute/plugin/develop_plugin_cpp.md b/docs/contribute/plugin/develop_plugin_cpp.md index 9bc08fcb8..62e50e3a8 100644 --- a/docs/contribute/plugin/develop_plugin_cpp.md +++ b/docs/contribute/plugin/develop_plugin_cpp.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 --- # Develop WasmEdge Plug-in in C++ API diff --git a/docs/contribute/plugin/plugin_requirement.md b/docs/contribute/plugin/plugin_requirement.md new file mode 100644 index 000000000..b4af0a560 --- /dev/null +++ b/docs/contribute/plugin/plugin_requirement.md @@ -0,0 +1,177 @@ +--- +sidebar_position: 2 +--- + +# Requirements for developing WasmEdge plugin + +By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. There are some steps needs to be followed for developing WasmEdge Plugin: + +## Choose a programming language + +The first step in developing a WasmEdge plugin is to choose the programming language one wants to use. Currently, C, C++, and Rust are supported by the WasmEdge runtime. + +- **C:** For developing the WasmEdge plug-in in C API, please [install WasmEdge](/develop/build-and-run/install.md) first. + +- **C++:** For developing the WasmEdge plug-in in internal C++, developers should [build WasmEdge from source](../source/build_from_src.md) before starting. On the other hand, to build a plugin using internal C++, they should build WasmEdge from source. + +- **Rust:** Rust is another option that has gained popularity due to its safety features and performance. It is a systems programming language designed for safe, concurrent, and fast execution. + +The choice of programming language will depend on the developer's familiarity and skill with the language. However, C and C++ are popular choices for developers who want to create high-performance plugins with low-level control over system resources. Rust is another popular choice for its safety features and performance. + +> We recommend developers to develop plug-ins in WasmEdge [C API](develop_plugin_c.md). + +## Set up the development environment + +To set up your development environment for WasmEdge plugin development, follow these steps: + +- **Install a WasmEdge runtime**: Choose a runtime environment that can execute WebAssembly modules. Options include WasmEdge, WASM3, or WAVM, depending on your requirements. + +- **Install a compatible compiler**: Install a compiler that can compile your chosen programming language into WebAssembly bytecode. For example, LLVM or GCC can be used for compiling C and C++ code, while Rust has its own built-in compiler. + +- **Install necessary tools and dependencies**: Install the required tools, such as a text editor, a debugger, and a build system. Additionally, ensure you have the necessary runtime headers and libraries. + +Setting up the development environment is crucial to ensure you can create and test WasmEdge plugins effectively. + +## Create a WasmEdge plugin project + +To create a WasmEdge plugin project, follow these steps: + +- **Set up the project directory structure**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your own structure. To create a project directory structure, you can use the following commands: + +```bash +mkdir myplugin +cd myplugin +mkdir src include build +``` + +- **Add any necessary configuration files**: Add configuration files specifying the plugin name, version, and dependencies. For C/C++, this might include a CMakeLists.txt file. + +- **Add any necessary libraries or dependencies**: Include any required libraries or dependencies for your plugin, such as the WasmEdge runtime library.. + +This project will serve as the foundation for developing the WasmEdge plugin and will contain the necessary files and directories. + +### Define the plugin API + +The plugin API is a set of functions that the WasmEdge runtime will call to interact with the plugin. The specific functions that are required in the plugin API depend on the features that your plugin provides. + +- **Define the interaction between the plugin and the WasmEdge runtime**: Specify how the plugin will receive input and provide output to the runtime. + +- **Provide a set of functions that the runtime can call to perform specific tasks**: Define functions that the plugin will expose to the runtime, such as initialization, execution, and cleanup functions. + +This is an essential step in developing a WasmEdge plugin. + +## Implement the plugin API + +The plugin API is implemented in the `main` file. The specific implementation of each function depends on the features that your plugin provides. + +- **Write the code for each of the functions defined in the API**: Implement the initialization, execution, cleanup functions, and any other functions required by the plugin. + +- **Ensure that they are correctly integrated with the WasmEdge runtime**: Enable communication between the functions and the runtime, and handle any errors appropriately. For example, if you are implementing an initialization function in C++, you might include the following code: + +```cpp +#include "wasmedge/wasmedge.h" + +extern "C" { + WasmEdge_Result initialize(const WasmEdge_ConfigureContext *Conf) { + // Plugin initialization code + return WasmEdge_Result_Success; + } +} +``` + +After defining the plugin API, the next step is to implement it. + +## Compile the WasmEdge plugin + +Once you have implemented the plugin API, you can compile the plugin using the following steps: + +- **Compile the plugin code**: Use the installed compiler to compile the plugin code into WebAssembly bytecode. To compile the plugin code, you can use the following command: + +```bash +clang --target=wasm32 -O3 -nostdlib \ + -Wl,--export-all -Wl,--allow-undefined \ + -o build/myplugin.wasm src/myplugin.c +``` + +- **Link it with the necessary libraries and dependencies**: Link the bytecode with any required libraries or dependencies, such as the WasmEdge runtime library. For example, if you are using the WasmEdge C API in your plugin, you might include the following linker flags: + +``` +-L/usr/local/lib -lwasmedgeC +``` + +- **Create the binary that can be loaded and executed by the WasmEdge runtime**: Generate the binary file that can be loaded and executed by the WasmEdge runtime, such as a shared object file for Linux or a dynamic-link library for Windows. For example, to create a shared object file on Linux, you can run the following command: + +```bash +clang -shared -o build/myplugin.so build/myplugin.wasm +``` + +## Test and debug the plugin + +Once you have compiled the plugin, you can test it using the following steps: + +- **Test the plugin with WasmEdge**: Load and execute the plugin using the WasmEdge runtime, and ensure it works as expected. To test the plugin with WasmEdge, you can use the following command: + +```bash +wasmedge --dir=./build myplugin.so +``` + +- **Debug any issues**: To launch a debugger for a WasmEdge binary file, run the following command: + +```bash +wasmedge debug my-plugin.wasm +``` + +This will launch a debugger for the WasmEdge binary file, and allow you to step through the code and inspect the values of variables. + +Finally, compile the WasmEdge plugin. + +```mermaid +graph TD; + A[Choose a Programming Language] --> B[Set Up Development Environment] + B --> C[Create WasmEdge Plugin Project] + C --> D[Define Plugin API] + D --> E[Implement Plugin API] + E --> F[Compile WasmEdge Plugin] + F --> G[Link with Libraries and Dependencies] + G --> H[Create Binary] + H --> I[Load and Execute Plugin] + I --> J[Testing and Debugging] + J --> K[Documentation and Deployment] + K --> L[Finalize and Release Plugin] + + subgraph Plugin Development Loop + J --> D + K --> J + L --> K + end + + style A fill:#F6D55C,stroke:#000000,stroke-width:2px; + style B fill:#F6D55C,stroke:#000000,stroke-width:2px; + style C fill:#F6D55C,stroke:#000000,stroke-width:2px; + style D fill:#F6D55C,stroke:#000000,stroke-width:2px; + style E fill:#F6D55C,stroke:#000000,stroke-width:2px; + style F fill:#F6D55C,stroke:#000000,stroke-width:2px; + style G fill:#F6D55C,stroke:#000000,stroke-width:2px; + style H fill:#F6D55C,stroke:#000000,stroke-width:2px; + style I fill:#F6D55C,stroke:#000000,stroke-width:2px; + style J fill:#F6D55C,stroke:#000000,stroke-width:2px; + style K fill:#F6D55C,stroke:#000000,stroke-width:2px; + style L fill:#F6D55C,stroke:#000000,stroke-width:2px; + style M fill:#F6D55C,stroke:#000000,stroke-width:2px; + + M[Test and Debug the Plugin] --> J + +``` + +> For existing plugins, please refer to their respective [documentation pages](/contribute/source/plugin) for specific instructions. + +## Additional Resources + +Here are some additional resources that can help you during the development of WasmEdge plugins: + +- [WasmEdge Plugin Examples](https://github.com/WasmEdge/WasmEdge/tree/main/example/plugins): Explore a collection of example plugins to learn more about their implementation. +- [WasmEdge Plugin Development Guide](https://docs.wasmedge.org/contribute/source/plugin): Refer to the official WasmEdge documentation for detailed instructions on developing plugins. +- [WasmEdge GitHub Repository](https://github.com/WasmEdge/WasmEdge): Visit the official WasmEdge GitHub repository for the latest updates, issues, and discussions related to plugin development. +- [WasmEdge Community Forum](https://forum.wasmedge.org/): Join the WasmEdge community forum to connect with other developers and get assistance with your plugin development questions. + +Feel free to explore these resources to enhance your understanding and proficiency in developing WasmEdge plugins. From 916f66afe59a835e480020bb74e2ef7f2e0c49d6 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Mon, 12 Jun 2023 16:38:54 +0600 Subject: [PATCH 02/20] updating front color in flowchart Signed-off-by: Mahfuza --- docs/contribute/plugin/plugin_requirement.md | 33 +++++++++++--------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/docs/contribute/plugin/plugin_requirement.md b/docs/contribute/plugin/plugin_requirement.md index b4af0a560..02b70ec03 100644 --- a/docs/contribute/plugin/plugin_requirement.md +++ b/docs/contribute/plugin/plugin_requirement.md @@ -2,7 +2,7 @@ sidebar_position: 2 --- -# Requirements for developing WasmEdge plugin +# Requirements for Developing WasmEdge Plugin By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. There are some steps needs to be followed for developing WasmEdge Plugin: @@ -125,7 +125,10 @@ This will launch a debugger for the WasmEdge binary file, and allow you to step Finally, compile the WasmEdge plugin. +Here is a flowchart describing all the steps mentioned above - + ```mermaid + graph TD; A[Choose a Programming Language] --> B[Set Up Development Environment] B --> C[Create WasmEdge Plugin Project] @@ -145,24 +148,26 @@ graph TD; L --> K end - style A fill:#F6D55C,stroke:#000000,stroke-width:2px; - style B fill:#F6D55C,stroke:#000000,stroke-width:2px; - style C fill:#F6D55C,stroke:#000000,stroke-width:2px; - style D fill:#F6D55C,stroke:#000000,stroke-width:2px; - style E fill:#F6D55C,stroke:#000000,stroke-width:2px; - style F fill:#F6D55C,stroke:#000000,stroke-width:2px; - style G fill:#F6D55C,stroke:#000000,stroke-width:2px; - style H fill:#F6D55C,stroke:#000000,stroke-width:2px; - style I fill:#F6D55C,stroke:#000000,stroke-width:2px; - style J fill:#F6D55C,stroke:#000000,stroke-width:2px; - style K fill:#F6D55C,stroke:#000000,stroke-width:2px; - style L fill:#F6D55C,stroke:#000000,stroke-width:2px; - style M fill:#F6D55C,stroke:#000000,stroke-width:2px; + style A fill:#9B5DE5,stroke:#000000,stroke-width:2px; + style B fill:#9B5DE5,stroke:#000000,stroke-width:2px; + style C fill:#9B5DE5,stroke:#000000,stroke-width:2px; + style D fill:#9B5DE5,stroke:#000000,stroke-width:2px; + style E fill:#9B5DE5,stroke:#000000,stroke-width:2px; + style F fill:#9B5DE5,stroke:#000000,stroke-width:2px; + style G fill:#9B5DE5,stroke:#000000,stroke-width:2px; + style H fill:#9B5DE5,stroke:#000000,stroke-width:2px; + style I fill:#9B5DE5,stroke:#000000,stroke-width:2px; + style J fill:#9B5DE5,stroke:#000000,stroke-width:2px; + style K fill:#9B5DE5,stroke:#000000,stroke-width:2px; + style L fill:#9B5DE5,stroke:#000000,stroke-width:2px; + style M fill:#9B5DE5,stroke:#000000,stroke-width:2px; M[Test and Debug the Plugin] --> J ``` +This flowchart illustrates the process of developing a WasmEdge plugin, showcasing the steps involved from choosing a programming language to finalizing and releasing the plugin. + > For existing plugins, please refer to their respective [documentation pages](/contribute/source/plugin) for specific instructions. ## Additional Resources From a8c5a3b66d4f59056ea5d93f5cf97c3fc4a92558 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Thu, 15 Jun 2023 10:18:48 +0600 Subject: [PATCH 03/20] update the content Signed-off-by: Mahfuza --- docs/contribute/plugin/plugin_requirement.md | 378 +++++++++++++------ 1 file changed, 266 insertions(+), 112 deletions(-) diff --git a/docs/contribute/plugin/plugin_requirement.md b/docs/contribute/plugin/plugin_requirement.md index 02b70ec03..1936430bc 100644 --- a/docs/contribute/plugin/plugin_requirement.md +++ b/docs/contribute/plugin/plugin_requirement.md @@ -4,106 +4,316 @@ sidebar_position: 2 # Requirements for Developing WasmEdge Plugin -By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. There are some steps needs to be followed for developing WasmEdge Plugin: +By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. Here is a flowchart showing all the steps needed for developing WasmEdge Plugin - -## Choose a programming language +```mermaid +graph TD; +A(Choose programming language) --> B(Install WasmEdge) +A --> C(Build WasmEdge from source) +A --> D(Install Rust) +B --> E(Set up development environment) +C --> E +D --> E +E --> F(Create project directory) +E --> G(Add configuration files) +E --> H(Install necessary tools and dependencies) +E --> I(Enable specific backends or components) +E --> J(Write plugin code) +E --> K(Build plugin) +F --> L(Define plugin API) +K --> L +L --> M(Compile WasmEdge plugin) +M --> N(Test and debug plugin) + +``` + +This flowchart illustrates the process of developing a WasmEdge plugin, showcasing the steps involved from choosing a programming language to finalizing and releasing the plugin. + +> For existing plugins, please refer to their respective [documentation pages](/contribute/source/plugin) for specific instructions. + +## Choose programming language The first step in developing a WasmEdge plugin is to choose the programming language one wants to use. Currently, C, C++, and Rust are supported by the WasmEdge runtime. -- **C:** For developing the WasmEdge plug-in in C API, please [install WasmEdge](/develop/build-and-run/install.md) first. +- **C:** Developers who choose to develop WasmEdge plugins using the C API need to install WasmEdge before starting the development process. Detailed instructions on installing WasmEdge can be found in the [install WasmEdge](/develop/build-and-run/install.md) guide. -- **C++:** For developing the WasmEdge plug-in in internal C++, developers should [build WasmEdge from source](../source/build_from_src.md) before starting. On the other hand, to build a plugin using internal C++, they should build WasmEdge from source. +- **C++:** For developers interested in developing WasmEdge plugins using the internal C++ API, they should first build WasmEdge from source. The process for building WasmEdge from source is outlined in th [build WasmEdge from source](../source/build_from_src.md) before starting.Once WasmEdge is successfully built, they can proceed with developing plugins using the internal C++ API. -- **Rust:** Rust is another option that has gained popularity due to its safety features and performance. It is a systems programming language designed for safe, concurrent, and fast execution. +- **Rust:** To develop WasmEdge plugins using Rust, developers need to have Rust installed on their system. Instructions for installing Rust can be found in the [e Rust Setup Guide](/develop/rust/setup.md). Once Rust is installed, developers can start developing WasmEdge plugins using the Rust programming language. -The choice of programming language will depend on the developer's familiarity and skill with the language. However, C and C++ are popular choices for developers who want to create high-performance plugins with low-level control over system resources. Rust is another popular choice for its safety features and performance. +The choice of programming language depends on the developer's familiarity and skill with the language. C and C++ are commonly chosen for their low-level control over system resources and the ability to create high-performance plugins. Rust, on the other hand, is known for its safety features and performance. -> We recommend developers to develop plug-ins in WasmEdge [C API](develop_plugin_c.md). +> It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plugin development. ## Set up the development environment -To set up your development environment for WasmEdge plugin development, follow these steps: +To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - -- **Install a WasmEdge runtime**: Choose a runtime environment that can execute WebAssembly modules. Options include WasmEdge, WASM3, or WAVM, depending on your requirements. +- **Install a WasmEdge runtime**: You can download the latest version of WasmEdge from [GitHub repository](https://github.com/wasmEdge/wasmEdge). Here are the installation instructions for different operating system for [installing WasmEdge](/develop/build-and-run/install.md). -- **Install a compatible compiler**: Install a compiler that can compile your chosen programming language into WebAssembly bytecode. For example, LLVM or GCC can be used for compiling C and C++ code, while Rust has its own built-in compiler. +- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your own plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. + + To see a list of supported plugins and their specific install commands, see the [Install WasmEdge plugins and dependencies](develop/build-and-run/install/#install-wasmedge-plugins-and-dependencies) section. + +- **Install a compatible compiler**: The following compilers can be used to compile C and C++ code into WebAssembly bytecode: -- **Install necessary tools and dependencies**: Install the required tools, such as a text editor, a debugger, and a build system. Additionally, ensure you have the necessary runtime headers and libraries. + - LLVM: `sudo apt-get install llvm` + - GCC: `sudo apt-get install gcc` -Setting up the development environment is crucial to ensure you can create and test WasmEdge plugins effectively. + Rust has its own built-in compiler, which can be installed using rustup: + + ```bash + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + source $HOME/.cargo/env + ``` + +- **Install necessary tools and dependencies**: You can use any text editor or IDE of your choice to write code. Here are some popular options: + + - [Visual Studio Code](https://code.visualstudio.com/) + - [Atom](https://atom.io/) + - [Sublime Text](https://www.sublimetext.com/) + + For debugging, you can use GDB, LLDB, or other debuggers that support WebAssembly. To install GDB, run `sudo apt-get install gdb`. + +- **Enable specific backends or additional components (if applicable):** Some plugins may require enabling specific backends or additional components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: + + - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) + - [TensorFlow Lite](../../build-and-run/install#wasi-nn-plugin-with-tensorflow-lite) + - [PyTorch 1.8.2 LTS](https://pytorch.org/get-started/locally/) + +By following these steps, you can set up the development environment for creating WasmEdge plugins effectively. This will allow you to develop, test, and debug your plugins in a Linux environment. ## Create a WasmEdge plugin project To create a WasmEdge plugin project, follow these steps: -- **Set up the project directory structure**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your own structure. To create a project directory structure, you can use the following commands: +- **Set up the project directory**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your own structure. To create a project directory structure, use the following commands: -```bash -mkdir myplugin -cd myplugin -mkdir src include build -``` + ```bash + mkdir myplugin + cd myplugin + mkdir src include build + ``` + +- **Add configuration files**: Add configuration files specifying the plugin name, version, and dependencies. The specific files and their content depend on the chosen programming language and build system. + + - For C/C++ plugins, create a `CMakeLists.txt` file in the root directory with the necessary configuration to specify the plugin name, version, and dependencies. The `find_package(WasmEdge REQUIRED)` line locates the WasmEdge runtime library and makes it available for the project. + + ```cmake + cmake_minimum_required(VERSION 3.14) + project(myplugin VERSION 0.1.0) -- **Add any necessary configuration files**: Add configuration files specifying the plugin name, version, and dependencies. For C/C++, this might include a CMakeLists.txt file. + find_package(WasmEdge REQUIRED) -- **Add any necessary libraries or dependencies**: Include any required libraries or dependencies for your plugin, such as the WasmEdge runtime library.. + add_library(myplugin SHARED src/myplugin.cpp) + target_compile_features(myplugin PUBLIC cxx_std_11) + target_include_directories(myplugin PUBLIC include) + target_link_libraries(myplugin PRIVATE ${WASMEDGE_LIBRARIES}) + set_target_properties(myplugin PROPERTIES PREFIX "") + ``` -This project will serve as the foundation for developing the WasmEdge plugin and will contain the necessary files and directories. + - For Rust plugins, create a `Cargo.toml` file in the root directory with the necessary configuration to specify the plugin name, version, and dependencies. The `wasmedge-runtime` dependency is added with the appropriate version and features. -### Define the plugin API + ```toml + [package] + name = "myplugin" + version = "0.1.0" + edition = "2018" + + [lib] + crate-type = ["cdylib"] + + [dependencies] + wasmedge-runtime = { version = ">=0.9", features = ["cranelift"] } + ``` + +- **Add any necessary libraries or dependencies**: Include any required libraries or dependencies for your plugin. Modify the configuration files created in the previous step to include the necessary dependencies. For example, in the `CMakeLists.txt` file, use the `find_package` command to locate the WasmEdge runtime library and link it to your plugin. + +- **Write the plugin code**: Start writing your plugin code in the `src` directory. Create one or more source files that define the functionality of your plugin. For example, in C++, you might create `myplugin.cpp` file with following code: + + ```cpp + #include + + extern "C" { + WasmEdge_Result initializePlugin() { + // Plugin initialization code + return WasmEdge_Result_Success; + } + + WasmEdge_Result finalizePlugin() { + // Plugin finalization code + return WasmEdge_Result_Success; + } + } + + ``` + + Modify the above code according to your plugin's functionality. In this example, the plugin defines two external functions, `initializePlugin` and `finalizePlugin`, which are the entry points for the plugin's initialization and finalization code. + +- **Build your plugin**: Depending on your build system, use the appropriate commands to build the plugin. + + - For C/C++ plugins, run the following commands from the `build` directory: + + ```bash + cd build + cmake .. + make + ``` + + - For Rust plugins, run the following commands from the project root directory: + + ```bash + cargo build --release --target wasm32-wasi + wasm-bindgen target/wasm32-wasi/release/myplugin.wasm --out-dir . + ``` + + These commands will generate the plugin binary based on the provided configuration. + +Your compiled plugin should be located in the `build` directory for C/C++ or in the project root directory for Rust. + +By following these steps, you will have a WasmEdge plugin project set up with the necessary directory structure, configuration files, and initial code. You can continue developing your plugin by adding functionality and implementing the desired behavior. + +## Define the plugin API The plugin API is a set of functions that the WasmEdge runtime will call to interact with the plugin. The specific functions that are required in the plugin API depend on the features that your plugin provides. -- **Define the interaction between the plugin and the WasmEdge runtime**: Specify how the plugin will receive input and provide output to the runtime. +- **Specify interaction**: Specify how the plugin will receive input and provide output to the runtime. This can be done through function parameters, return values, or other means of communication. + +- **Provide functions**: Define functions that the plugin will expose to the runtime, such as initialization, execution, and cleanup functions. These functions should perform specific tasks related to the plugin's functionality. + +### Define the plugin API for C/C++ + +Here's an example of how to define the plugin API for a C/C++ WasmEdge plugin: + +- **Create a header file for your plugin**: In the include directory, create a header file (e.g., `myplugin.h`) that declares the plugin API functions. For example: + + ```c + #pragma once -- **Provide a set of functions that the runtime can call to perform specific tasks**: Define functions that the plugin will expose to the runtime, such as initialization, execution, and cleanup functions. + #include -This is an essential step in developing a WasmEdge plugin. + class MyPlugin { + public: + MyPlugin(); + ~MyPlugin(); -## Implement the plugin API + void init(); + void execute(uint32_t input); + void cleanup(); + }; + ``` -The plugin API is implemented in the `main` file. The specific implementation of each function depends on the features that your plugin provides. +- **Implement the plugin API functions**: In your plugin's source file (e.g., `src/myplugin.cpp`), implement the declared API functions. For example: -- **Write the code for each of the functions defined in the API**: Implement the initialization, execution, cleanup functions, and any other functions required by the plugin. + ```c + #include "myplugin.h" + #include -- **Ensure that they are correctly integrated with the WasmEdge runtime**: Enable communication between the functions and the runtime, and handle any errors appropriately. For example, if you are implementing an initialization function in C++, you might include the following code: + class MyPlugin : public wasmedge::Plugin { + public: + MyPlugin() { + // Initialization code + } -```cpp -#include "wasmedge/wasmedge.h" + ~MyPlugin() { + // Cleanup code + } -extern "C" { - WasmEdge_Result initialize(const WasmEdge_ConfigureContext *Conf) { - // Plugin initialization code - return WasmEdge_Result_Success; + void init() override { + // Initialization code + } + + void execute(uint32_t input) override { + // Execution code + } + + void cleanup() override { + // Cleanup code + } + }; + ``` + +- **Expose the plugin API functions**: In the myplugin.cpp file, you'll also need to expose the plugin API functions to the WasmEdge runtime using the `wasm_export_ prefix`. For example: + + ```c + extern "C" { + void wasm_export_myplugin_init(const struct wasm_export_myplugin_init_args_t* args) { + // Initialization code + } + + void wasm_export_myplugin_execute(const struct wasm_export_myplugin_execute_args_t* args) { + // Execution code + } + + void wasm_export_myplugin_cleanup(const struct wasm_export_myplugin_cleanup_args_t* args) { + // Cleanup code + } } -} -``` + ``` + +By following these steps, you can define the plugin API for a C/C++ WasmEdge plugin. + +### Define the plugin API for RUST + +For Rust, you would define the plugin API using Rust's traits and methods. + +For example, in `myplugin.rs`: -After defining the plugin API, the next step is to implement it. + ```toml + use wasmedge::core::plugin::{Plugin, PluginExecuteArgs, PluginInitArgs, PluginCleanupArgs}; + + pub struct MyPlugin; + + impl Plugin for MyPlugin { + fn init(&mut self) { + // Initialization code + } + + fn execute(&mut self, input: u32) { + // Execution code + } + + fn cleanup(&mut self) { + // Cleanup code + } + } + ``` + +Then, you would expose the plugin API functions to the WasmEdge runtime using the `wasm_export_ prefix`, similar to the C/C++ example. + +By defining the plugin API, you can establish a clear interface between your plugin and the WasmEdge runtime, making it easier to develop and maintain your plugin. ## Compile the WasmEdge plugin Once you have implemented the plugin API, you can compile the plugin using the following steps: -- **Compile the plugin code**: Use the installed compiler to compile the plugin code into WebAssembly bytecode. To compile the plugin code, you can use the following command: +- **Compile the plugin code**: Use the installed compiler to compile the plugin code into WebAssembly bytecode. Replace `myplugin.c` with the name of your plugin's source file, and build `myplugin.wasm` with the desired output path and filename. -```bash -clang --target=wasm32 -O3 -nostdlib \ + ```bash + clang --target=wasm32 -O3 -nostdlib \ -Wl,--export-all -Wl,--allow-undefined \ -o build/myplugin.wasm src/myplugin.c -``` + ``` -- **Link it with the necessary libraries and dependencies**: Link the bytecode with any required libraries or dependencies, such as the WasmEdge runtime library. For example, if you are using the WasmEdge C API in your plugin, you might include the following linker flags: + This command compiles the plugin code into WebAssembly bytecode using the Clang compiler. Adjust the compiler flags as needed for your specific requirements. -``` --L/usr/local/lib -lwasmedgeC -``` +- **Link with necessary dependencies**: If your plugin depends on external libraries or the WasmEdge runtime, you need to link them with the bytecode. For example, if you are using the WasmEdge C API in your plugin, include the following linker flags: -- **Create the binary that can be loaded and executed by the WasmEdge runtime**: Generate the binary file that can be loaded and executed by the WasmEdge runtime, such as a shared object file for Linux or a dynamic-link library for Windows. For example, to create a shared object file on Linux, you can run the following command: + ```bash + -L/usr/local/lib -lwasmedgeC + ``` -```bash -clang -shared -o build/myplugin.so build/myplugin.wasm -``` + Modify these flags to match the location and name of the required libraries on your system. + +- **Create the binary for execution**: Generate the binary file that can be loaded and executed by the WasmEdge runtime. The specific command depends on the target platform and the desired output format. For example, to create a shared object file (`.so`) on Linux, use the following command: + + ```bash + clang -shared -o build/myplugin.so build/myplugin.wasm + ``` + + Adjust the output path and filename as needed for your project. + +By following these steps, you can compile your WasmEdge plugin and create a binary that can be loaded and executed by the WasmEdge runtime. ## Test and debug the plugin @@ -111,72 +321,16 @@ Once you have compiled the plugin, you can test it using the following steps: - **Test the plugin with WasmEdge**: Load and execute the plugin using the WasmEdge runtime, and ensure it works as expected. To test the plugin with WasmEdge, you can use the following command: -```bash -wasmedge --dir=./build myplugin.so -``` + ```bash + wasmedge --dir=./build myplugin.so + ``` - **Debug any issues**: To launch a debugger for a WasmEdge binary file, run the following command: -```bash -wasmedge debug my-plugin.wasm -``` + ```bash + wasmedge debug my-plugin.wasm + ``` This will launch a debugger for the WasmEdge binary file, and allow you to step through the code and inspect the values of variables. Finally, compile the WasmEdge plugin. - -Here is a flowchart describing all the steps mentioned above - - -```mermaid - -graph TD; - A[Choose a Programming Language] --> B[Set Up Development Environment] - B --> C[Create WasmEdge Plugin Project] - C --> D[Define Plugin API] - D --> E[Implement Plugin API] - E --> F[Compile WasmEdge Plugin] - F --> G[Link with Libraries and Dependencies] - G --> H[Create Binary] - H --> I[Load and Execute Plugin] - I --> J[Testing and Debugging] - J --> K[Documentation and Deployment] - K --> L[Finalize and Release Plugin] - - subgraph Plugin Development Loop - J --> D - K --> J - L --> K - end - - style A fill:#9B5DE5,stroke:#000000,stroke-width:2px; - style B fill:#9B5DE5,stroke:#000000,stroke-width:2px; - style C fill:#9B5DE5,stroke:#000000,stroke-width:2px; - style D fill:#9B5DE5,stroke:#000000,stroke-width:2px; - style E fill:#9B5DE5,stroke:#000000,stroke-width:2px; - style F fill:#9B5DE5,stroke:#000000,stroke-width:2px; - style G fill:#9B5DE5,stroke:#000000,stroke-width:2px; - style H fill:#9B5DE5,stroke:#000000,stroke-width:2px; - style I fill:#9B5DE5,stroke:#000000,stroke-width:2px; - style J fill:#9B5DE5,stroke:#000000,stroke-width:2px; - style K fill:#9B5DE5,stroke:#000000,stroke-width:2px; - style L fill:#9B5DE5,stroke:#000000,stroke-width:2px; - style M fill:#9B5DE5,stroke:#000000,stroke-width:2px; - - M[Test and Debug the Plugin] --> J - -``` - -This flowchart illustrates the process of developing a WasmEdge plugin, showcasing the steps involved from choosing a programming language to finalizing and releasing the plugin. - -> For existing plugins, please refer to their respective [documentation pages](/contribute/source/plugin) for specific instructions. - -## Additional Resources - -Here are some additional resources that can help you during the development of WasmEdge plugins: - -- [WasmEdge Plugin Examples](https://github.com/WasmEdge/WasmEdge/tree/main/example/plugins): Explore a collection of example plugins to learn more about their implementation. -- [WasmEdge Plugin Development Guide](https://docs.wasmedge.org/contribute/source/plugin): Refer to the official WasmEdge documentation for detailed instructions on developing plugins. -- [WasmEdge GitHub Repository](https://github.com/WasmEdge/WasmEdge): Visit the official WasmEdge GitHub repository for the latest updates, issues, and discussions related to plugin development. -- [WasmEdge Community Forum](https://forum.wasmedge.org/): Join the WasmEdge community forum to connect with other developers and get assistance with your plugin development questions. - -Feel free to explore these resources to enhance your understanding and proficiency in developing WasmEdge plugins. From 75013d470a263cebd002f4378f4ffc7f11d04839 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Sun, 18 Jun 2023 11:31:50 +0600 Subject: [PATCH 04/20] updated choosing programming language Signed-off-by: Mahfuza --- docs/contribute/plugin/plugin_requirement.md | 30 ++++++++++++++------ 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/docs/contribute/plugin/plugin_requirement.md b/docs/contribute/plugin/plugin_requirement.md index 1936430bc..937b199a4 100644 --- a/docs/contribute/plugin/plugin_requirement.md +++ b/docs/contribute/plugin/plugin_requirement.md @@ -8,9 +8,9 @@ By developing a plugin, one can extend the functionality of WasmEdge and customi ```mermaid graph TD; -A(Choose programming language) --> B(Install WasmEdge) -A --> C(Build WasmEdge from source) -A --> D(Install Rust) +A(Choose programming language) --> B(C API) +A --> C(C++ API) +A --> D(Rust API) B --> E(Set up development environment) C --> E D --> E @@ -33,17 +33,29 @@ This flowchart illustrates the process of developing a WasmEdge plugin, showcasi ## Choose programming language -The first step in developing a WasmEdge plugin is to choose the programming language one wants to use. Currently, C, C++, and Rust are supported by the WasmEdge runtime. +The first step in developing a WasmEdge plugin is to choose the programming language one wants to use. Currently, C, C++, and Rust are supported by the WasmEdge runtime. Depending on your preferred language, you can follow the specific instructions provided on separate pages: -- **C:** Developers who choose to develop WasmEdge plugins using the C API need to install WasmEdge before starting the development process. Detailed instructions on installing WasmEdge can be found in the [install WasmEdge](/develop/build-and-run/install.md) guide. +- **C:** + + - **Install WasmEdge**: Developers using the C API should install WasmEdge before starting the development process. Follow the [install WasmEdge](/develop/build-and-run/install.md) guide for detailed instructions. + + - **Develop the plugin**: Once WasmEdge is installed, you can proceed with developing your plugin using the WasmEdge [C API](develop_plugin_c.md). + +- **C++**: -- **C++:** For developers interested in developing WasmEdge plugins using the internal C++ API, they should first build WasmEdge from source. The process for building WasmEdge from source is outlined in th [build WasmEdge from source](../source/build_from_src.md) before starting.Once WasmEdge is successfully built, they can proceed with developing plugins using the internal C++ API. + - **Build WasmEdge from source**: Developers interested in using the internal C++ API should build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. -- **Rust:** To develop WasmEdge plugins using Rust, developers need to have Rust installed on their system. Instructions for installing Rust can be found in the [e Rust Setup Guide](/develop/rust/setup.md). Once Rust is installed, developers can start developing WasmEdge plugins using the Rust programming language. + - **Develop the plugin**: After building WasmEdge, you can develop your plugin using the internal [C++ API](develop_plugin_cpp.md). -The choice of programming language depends on the developer's familiarity and skill with the language. C and C++ are commonly chosen for their low-level control over system resources and the ability to create high-performance plugins. Rust, on the other hand, is known for its safety features and performance. +- **Rust**: + + - **Install Rust**: To develop WasmEdge plugins using Rust, you need to have Rust installed on your system. You can refer to the [Rust Setup Guide](/develop/rust/setup.md) for instructions on installing Rust. + + - **Develop the plugin**: Once Rust is installed, you can start developing WasmEdge plugins using the Rust programming language. -> It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plugin development. +> It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plugin development because of the support, compatibility and flexibility provided by the WasmEdge runtime. + +The choice of programming language depends on the developer's familiarity and skill with the language. C and C++ are commonly chosen for their low-level control over system resources and the ability to create high-performance plugins. Rust, on the other hand, is known for its safety features and performance. ## Set up the development environment From bf2b6321da94086907ad82e23b99c9e14d08b1c1 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Sun, 18 Jun 2023 16:41:15 +0600 Subject: [PATCH 05/20] updating side_bar position Signed-off-by: Mahfuza --- docs/contribute/plugin/develop_plugin_c.md | 2 +- docs/contribute/plugin/develop_plugin_cpp.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contribute/plugin/develop_plugin_c.md b/docs/contribute/plugin/develop_plugin_c.md index 1853be0ee..b31f9fe52 100644 --- a/docs/contribute/plugin/develop_plugin_c.md +++ b/docs/contribute/plugin/develop_plugin_c.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 --- # Develop WasmEdge Plug-in in C API diff --git a/docs/contribute/plugin/develop_plugin_cpp.md b/docs/contribute/plugin/develop_plugin_cpp.md index 62e50e3a8..5623e0ce8 100644 --- a/docs/contribute/plugin/develop_plugin_cpp.md +++ b/docs/contribute/plugin/develop_plugin_cpp.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 --- # Develop WasmEdge Plug-in in C++ API From 52162091ba330d3fcd1d6003b835c4b7fea27336 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Sun, 25 Jun 2023 11:31:07 +0600 Subject: [PATCH 06/20] updated structure Signed-off-by: Mahfuza --- .../Develop Plugin in C/_category_.json | 8 + .../Develop Plugin in C/plugin_development.md | 292 +++++++++++++++ .../Develop Plugin in CPP/_category_.json | 8 + .../plugin_development.md | 292 +++++++++++++++ docs/contribute/plugin/_category_.json | 3 +- docs/contribute/plugin/develop_plugin_c.md | 199 ---------- docs/contribute/plugin/develop_plugin_cpp.md | 2 +- docs/contribute/plugin/plugin_requirement.md | 348 ------------------ 8 files changed, 603 insertions(+), 549 deletions(-) create mode 100644 docs/contribute/plugin/Develop Plugin in C/_category_.json create mode 100644 docs/contribute/plugin/Develop Plugin in C/plugin_development.md create mode 100644 docs/contribute/plugin/Develop Plugin in CPP/_category_.json create mode 100644 docs/contribute/plugin/Develop Plugin in CPP/plugin_development.md delete mode 100644 docs/contribute/plugin/develop_plugin_c.md delete mode 100644 docs/contribute/plugin/plugin_requirement.md diff --git a/docs/contribute/plugin/Develop Plugin in C/_category_.json b/docs/contribute/plugin/Develop Plugin in C/_category_.json new file mode 100644 index 000000000..b370377a1 --- /dev/null +++ b/docs/contribute/plugin/Develop Plugin in C/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "WasmEdge Plugin System in C", + "position": 2, + "link": { + "type": "generated-index", + "description": "We will learn how to develop the WasmEdge Plugin System in C Language." + } +} diff --git a/docs/contribute/plugin/Develop Plugin in C/plugin_development.md b/docs/contribute/plugin/Develop Plugin in C/plugin_development.md new file mode 100644 index 000000000..cd6eb573d --- /dev/null +++ b/docs/contribute/plugin/Develop Plugin in C/plugin_development.md @@ -0,0 +1,292 @@ +--- +sidebar_position: 2 +--- + +# Develop WasmEdge Plug-in in C API + +By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's own building and releasing process. +Here is a flowchart showing all the steps needed for developing WasmEdge Plugin - + +```mermaid +graph TD; +B[Developing WasmEdge Plugin in C] +B --> E(Set up development environment) +E --> F(Create project directory) +E --> G(Add configuration files) +E --> H(Install necessary tools and dependencies) +E --> I(Enable specific backends or components) +E --> J(Write plugin code) +E --> K(Build plugin) +F --> L(Define plugin API) +K --> L +L --> M(Compile WasmEdge plugin) +M --> N(Test and debug plugin) + +``` + +This flowchart illustrates the process of developing a WasmEdge plugin, showcasing the steps involved from choosing a programming language to finalizing and releasing the plugin. + +> For existing plugins, please refer to their respective [documentation pages](/contribute/source/plugin) for specific instructions. + +## Set up the development environment + +To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - + +- **Install a WasmEdge runtime**: You can download the latest version of WasmEdge from [GitHub repository](https://github.com/wasmEdge/wasmEdge). Here are the installation instructions for different operating system for [installing WasmEdge](/develop/build-and-run/install.md). + +- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your own plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. + + To see a list of supported plugins and their specific install commands, see the [Install WasmEdge plugins and dependencies](develop/build-and-run/install/#install-wasmedge-plugins-and-dependencies) section. + +- **Install a compatible compiler**: The following compilers can be used to compile C code into WebAssembly bytecode: + + - LLVM: `sudo apt-get install llvm` + - GCC: `sudo apt-get install gcc` + +- **Install necessary tools and dependencies**: You can use any text editor or IDE of your choice to write code. Here are some popular options: + + - [Visual Studio Code](https://code.visualstudio.com/) + - [Atom](https://atom.io/) + - [Sublime Text](https://www.sublimetext.com/) + + For debugging, you can use GDB, LLDB, or other debuggers that support WebAssembly. To install GDB, run `sudo apt-get install gdb`. + +- **Enable specific backends or additional components (if applicable):** Some plugins may require enabling specific backends or additional components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: + + - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) + - [TensorFlow Lite](../../build-and-run/install#wasi-nn-plugin-with-tensorflow-lite) + - [PyTorch 1.8.2 LTS](https://pytorch.org/get-started/locally/) + +By following these steps, you can set up the development environment for creating WasmEdge plugins effectively. This will allow you to develop, test, and debug your plugins in a Linux environment. + +## Create a WasmEdge plugin project + +To create a WasmEdge plugin project, follow these steps: + +- **Set up the project directory**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your own structure. To create a project directory structure, use the following commands: + + ```bash + mkdir myplugin + cd myplugin + mkdir src include build + ``` + +- **Add configuration files**: Add configuration files specifying the plugin name, version, and dependencies. The specific files and their content depend on the chosen programming language and build system. + + Create a `CMakeLists.txt` file in the root directory with the necessary configuration to specify the plugin name, version, and dependencies. The `find_package(WasmEdge REQUIRED)` line locates the WasmEdge runtime library and makes it available for the project. + + ```cmake + cmake_minimum_required(VERSION 3.14) + project(myplugin VERSION 0.1.0) + + find_package(WasmEdge REQUIRED) + + add_library(myplugin SHARED src/myplugin.cpp) + target_compile_features(myplugin PUBLIC cxx_std_11) + target_include_directories(myplugin PUBLIC include) + target_link_libraries(myplugin PRIVATE ${WASMEDGE_LIBRARIES}) + set_target_properties(myplugin PROPERTIES PREFIX "") + ``` + +- **Add any necessary libraries or dependencies**: Include any required libraries or dependencies for your plugin. Modify the configuration files created in the previous step to include the necessary dependencies. For example, in the `CMakeLists.txt` file, use the `find_package` command to locate the WasmEdge runtime library and link it to your plugin. + +## Write the plugin code + +To create a plug-in with host functions and modules, follow these steps: + +- **Implement host function definitions**: In this step, you need to define the host functions that will be imported when instantiating the WASM module. These functions will perform specific operations and return results. + + Therefore, developers can implement their plug-in host functions first, as the same as the [host functions in WasmEdge C API](/embed/c/reference/0.12.0.md#host-functions). + +> For the more details about the [external data](/embed/c/host_function.md#host-data) and [calling frame context](/embed/c/host_function.md#calling-frame-context), please refer to the host function guide. + + Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers respectively: + + ```c + #include + + /* The host function definitions. */ + + /* The host function to add 2 int32_t numbers. */ + WasmEdge_Result HostFuncAdd(void *Data, + const WasmEdge_CallingFrameContext *CallFrameCxt, + const WasmEdge_Value *In, WasmEdge_Value *Out) { + int32_t Val1 = WasmEdge_ValueGetI32(In[0]); + int32_t Val2 = WasmEdge_ValueGetI32(In[1]); + Out[0] = WasmEdge_ValueGenI32(Val1 + Val2); + return WasmEdge_Result_Success; + } + + /* The host function to sub 2 int32_t numbers. */ + WasmEdge_Result HostFuncSub(void *Data, + const WasmEdge_CallingFrameContext *CallFrameCxt, + const WasmEdge_Value *In, WasmEdge_Value *Out) { + int32_t Val1 = WasmEdge_ValueGetI32(In[0]); + int32_t Val2 = WasmEdge_ValueGetI32(In[1]); + Out[0] = WasmEdge_ValueGenI32(Val1 - Val2); + return WasmEdge_Result_Success; + } + ``` + +- **Implement the module creation functions**: In this step, you need to implement the module creation function that creates an instance of the module. This function will be called when the plugin is loaded. + + Here's an example of a module creation function named `CreateTestModule`: + + ```c + /* The creation function of creating the module instance. */ + 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 the description from this descriptor. + */ + + /* Exported module name of this module instance. */ + WasmEdge_String ModuleName = + WasmEdge_StringCreateByCString("wasmedge_plugintest_c_module"); + WasmEdge_ModuleInstanceContext *Mod = + WasmEdge_ModuleInstanceCreate(ModuleName); + WasmEdge_StringDelete(ModuleName); + + 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; + + /* Create and add the host function instances into the module instance. */ + FType = WasmEdge_FunctionTypeCreate(ParamTypes, 2, ReturnTypes, 1); + FuncName = WasmEdge_StringCreateByCString("add"); + FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncAdd, NULL, 0); + WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); + WasmEdge_StringDelete(FuncName); + FuncName = WasmEdge_StringCreateByCString("sub"); + FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncSub, NULL, 0); + WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); + WasmEdge_StringDelete(FuncName); + WasmEdge_FunctionTypeDelete(FType); + + return Mod; + } + ``` + + There can be several module instances in a plug-in shared library. Here in above code snippet take a module named as `wasmedge_plugintest_c_module` for the example. + +- **Supply the plugin descriptions**- In this step, you need to provide the descriptions of the plugin and the modules it contains. These descriptions will be used for searching and creating the plugin and module instances. + + Here's an example of the plugin and module descriptors: + + ```c + /* 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. + */ + .Name = "wasmedge_plugintest_c_module", + /* Module description. */ + .Description = "This is for the plugin tests in WasmEdge C API.", + /* Creation function pointer. */ + .Create = CreateTestModule, + }}; + + /* 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. + */ + .Name = "wasmedge_plugintest_c", + /* Plug-in description. */ + .Description = "", + /* Plug-in API version. */ + .APIVersion = WasmEdge_Plugin_CurrentAPIVersion, + /* Plug-in version. Developers can define the version of this plug-in. */ + .Version = + { + .Major = 0, + .Minor = 1, + .Patch = 0, + .Build = 0, + }, + /* Module count in this plug-in. */ + .ModuleCount = 1, + /* Plug-in option description count in this plug-in (Work in progress). */ + .ProgramOptionCount = 0, + /* Pointer to the module description array. */ + .ModuleDescriptions = ModuleDesc, + /* Pointer to the plug-in option description array (Work in progress). */ + .ProgramOptions = NULL, + }}; + ``` + + These descriptions define the name, description, version, and creation function of the plugin, as well as the name and description of the module it contains. + +Remember to implement any additional functions or structures that your plugin requires to fulfill its functionality. + +By following these steps and implementing the necessary functions and descriptors, you can create a plug-in with host functions and modules in WasmEdge C API. You can continue developing your plugin by adding functionality and implementing the desired behavior. + +## Build your plugin + +To build the WasmEdge plug-in shared library, you have two options: building it directly using the compiler or using CMake. Here are the instructions for both methods: + +- **Build with Command**: if you choose to build the plug-in using the command line, run the following command in terminal: + + This command compiles the `myplugin.c` file into a shared library named `libwasmedgePluginTest.so`. The `-std=c11` flag sets the C language standard to C11, and the `-DWASMEDGE_PLUGIN` flag defines the WASMEDGE_PLUGIN macro, which can be used in your code. + +- **Build with CMake**: If you prefer to use CMake to build the plug-in, create a `CMakeLists.txt` file in the root directory of your project and add the following content to the CMakeLists.txt file: + + ```cmake + add_library(wasmedgePluginTest + SHARED + myplugin.c + ) + + set_target_properties(wasmedgePluginTest PROPERTIES + C_STANDARD 11 + ) + + target_compile_options(wasmedgePluginTest + PUBLIC + -DWASMEDGE_PLUGIN + ) + + target_link_libraries(wasmedgePluginTest + PRIVATE + wasmedge + ) + ``` + + This CMake configuration sets up a build target called `wasmedgePluginTest`. It compiles the `myplugin.c` file into a shared library. The `C_STANDARD 11` property sets the C language standard to C11. The `target_compile_options` command defines the `WASMEDGE_PLUGIN` macro using the `-DWASMEDGE_PLUGIN` flag. Finally, the `target_link_libraries` command links the wasmedge library to the plug-in. + +Once you have set up either the command-line build or the CMake build, you can execute the corresponding build command or generate build files using CMake. This will compile your plug-in source code and produce the shared library file `(libwasmedgePluginTest.so)`. + +## Test and debug the plugin + +Once you have compiled the plugin, you can test it using the following steps: + +- **Test the plugin with WasmEdge**: Load and execute the plugin using the WasmEdge runtime, and ensure it works as expected. To test the plugin with WasmEdge, you can use the following command: + + ```bash + wasmedge --dir=./build myplugin.so + ``` + +- **Debug any issues**: To launch a debugger for a WasmEdge binary file, run the following command: + + ```bash + wasmedge debug my-plugin.wasm + ``` + +This will launch a debugger for the WasmEdge binary file, and allow you to step through the code and inspect the values of variables. + +Finally, compile the WasmEdge plugin. diff --git a/docs/contribute/plugin/Develop Plugin in CPP/_category_.json b/docs/contribute/plugin/Develop Plugin in CPP/_category_.json new file mode 100644 index 000000000..e59ba2ded --- /dev/null +++ b/docs/contribute/plugin/Develop Plugin in CPP/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "WasmEdge Plugin System in C++", + "position": 3, + "link": { + "type": "generated-index", + "description": "We will learn how to develop the WasmEdge Plugin System in C++ Language." + } +} diff --git a/docs/contribute/plugin/Develop Plugin in CPP/plugin_development.md b/docs/contribute/plugin/Develop Plugin in CPP/plugin_development.md new file mode 100644 index 000000000..cd6eb573d --- /dev/null +++ b/docs/contribute/plugin/Develop Plugin in CPP/plugin_development.md @@ -0,0 +1,292 @@ +--- +sidebar_position: 2 +--- + +# Develop WasmEdge Plug-in in C API + +By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's own building and releasing process. +Here is a flowchart showing all the steps needed for developing WasmEdge Plugin - + +```mermaid +graph TD; +B[Developing WasmEdge Plugin in C] +B --> E(Set up development environment) +E --> F(Create project directory) +E --> G(Add configuration files) +E --> H(Install necessary tools and dependencies) +E --> I(Enable specific backends or components) +E --> J(Write plugin code) +E --> K(Build plugin) +F --> L(Define plugin API) +K --> L +L --> M(Compile WasmEdge plugin) +M --> N(Test and debug plugin) + +``` + +This flowchart illustrates the process of developing a WasmEdge plugin, showcasing the steps involved from choosing a programming language to finalizing and releasing the plugin. + +> For existing plugins, please refer to their respective [documentation pages](/contribute/source/plugin) for specific instructions. + +## Set up the development environment + +To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - + +- **Install a WasmEdge runtime**: You can download the latest version of WasmEdge from [GitHub repository](https://github.com/wasmEdge/wasmEdge). Here are the installation instructions for different operating system for [installing WasmEdge](/develop/build-and-run/install.md). + +- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your own plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. + + To see a list of supported plugins and their specific install commands, see the [Install WasmEdge plugins and dependencies](develop/build-and-run/install/#install-wasmedge-plugins-and-dependencies) section. + +- **Install a compatible compiler**: The following compilers can be used to compile C code into WebAssembly bytecode: + + - LLVM: `sudo apt-get install llvm` + - GCC: `sudo apt-get install gcc` + +- **Install necessary tools and dependencies**: You can use any text editor or IDE of your choice to write code. Here are some popular options: + + - [Visual Studio Code](https://code.visualstudio.com/) + - [Atom](https://atom.io/) + - [Sublime Text](https://www.sublimetext.com/) + + For debugging, you can use GDB, LLDB, or other debuggers that support WebAssembly. To install GDB, run `sudo apt-get install gdb`. + +- **Enable specific backends or additional components (if applicable):** Some plugins may require enabling specific backends or additional components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: + + - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) + - [TensorFlow Lite](../../build-and-run/install#wasi-nn-plugin-with-tensorflow-lite) + - [PyTorch 1.8.2 LTS](https://pytorch.org/get-started/locally/) + +By following these steps, you can set up the development environment for creating WasmEdge plugins effectively. This will allow you to develop, test, and debug your plugins in a Linux environment. + +## Create a WasmEdge plugin project + +To create a WasmEdge plugin project, follow these steps: + +- **Set up the project directory**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your own structure. To create a project directory structure, use the following commands: + + ```bash + mkdir myplugin + cd myplugin + mkdir src include build + ``` + +- **Add configuration files**: Add configuration files specifying the plugin name, version, and dependencies. The specific files and their content depend on the chosen programming language and build system. + + Create a `CMakeLists.txt` file in the root directory with the necessary configuration to specify the plugin name, version, and dependencies. The `find_package(WasmEdge REQUIRED)` line locates the WasmEdge runtime library and makes it available for the project. + + ```cmake + cmake_minimum_required(VERSION 3.14) + project(myplugin VERSION 0.1.0) + + find_package(WasmEdge REQUIRED) + + add_library(myplugin SHARED src/myplugin.cpp) + target_compile_features(myplugin PUBLIC cxx_std_11) + target_include_directories(myplugin PUBLIC include) + target_link_libraries(myplugin PRIVATE ${WASMEDGE_LIBRARIES}) + set_target_properties(myplugin PROPERTIES PREFIX "") + ``` + +- **Add any necessary libraries or dependencies**: Include any required libraries or dependencies for your plugin. Modify the configuration files created in the previous step to include the necessary dependencies. For example, in the `CMakeLists.txt` file, use the `find_package` command to locate the WasmEdge runtime library and link it to your plugin. + +## Write the plugin code + +To create a plug-in with host functions and modules, follow these steps: + +- **Implement host function definitions**: In this step, you need to define the host functions that will be imported when instantiating the WASM module. These functions will perform specific operations and return results. + + Therefore, developers can implement their plug-in host functions first, as the same as the [host functions in WasmEdge C API](/embed/c/reference/0.12.0.md#host-functions). + +> For the more details about the [external data](/embed/c/host_function.md#host-data) and [calling frame context](/embed/c/host_function.md#calling-frame-context), please refer to the host function guide. + + Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers respectively: + + ```c + #include + + /* The host function definitions. */ + + /* The host function to add 2 int32_t numbers. */ + WasmEdge_Result HostFuncAdd(void *Data, + const WasmEdge_CallingFrameContext *CallFrameCxt, + const WasmEdge_Value *In, WasmEdge_Value *Out) { + int32_t Val1 = WasmEdge_ValueGetI32(In[0]); + int32_t Val2 = WasmEdge_ValueGetI32(In[1]); + Out[0] = WasmEdge_ValueGenI32(Val1 + Val2); + return WasmEdge_Result_Success; + } + + /* The host function to sub 2 int32_t numbers. */ + WasmEdge_Result HostFuncSub(void *Data, + const WasmEdge_CallingFrameContext *CallFrameCxt, + const WasmEdge_Value *In, WasmEdge_Value *Out) { + int32_t Val1 = WasmEdge_ValueGetI32(In[0]); + int32_t Val2 = WasmEdge_ValueGetI32(In[1]); + Out[0] = WasmEdge_ValueGenI32(Val1 - Val2); + return WasmEdge_Result_Success; + } + ``` + +- **Implement the module creation functions**: In this step, you need to implement the module creation function that creates an instance of the module. This function will be called when the plugin is loaded. + + Here's an example of a module creation function named `CreateTestModule`: + + ```c + /* The creation function of creating the module instance. */ + 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 the description from this descriptor. + */ + + /* Exported module name of this module instance. */ + WasmEdge_String ModuleName = + WasmEdge_StringCreateByCString("wasmedge_plugintest_c_module"); + WasmEdge_ModuleInstanceContext *Mod = + WasmEdge_ModuleInstanceCreate(ModuleName); + WasmEdge_StringDelete(ModuleName); + + 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; + + /* Create and add the host function instances into the module instance. */ + FType = WasmEdge_FunctionTypeCreate(ParamTypes, 2, ReturnTypes, 1); + FuncName = WasmEdge_StringCreateByCString("add"); + FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncAdd, NULL, 0); + WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); + WasmEdge_StringDelete(FuncName); + FuncName = WasmEdge_StringCreateByCString("sub"); + FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncSub, NULL, 0); + WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); + WasmEdge_StringDelete(FuncName); + WasmEdge_FunctionTypeDelete(FType); + + return Mod; + } + ``` + + There can be several module instances in a plug-in shared library. Here in above code snippet take a module named as `wasmedge_plugintest_c_module` for the example. + +- **Supply the plugin descriptions**- In this step, you need to provide the descriptions of the plugin and the modules it contains. These descriptions will be used for searching and creating the plugin and module instances. + + Here's an example of the plugin and module descriptors: + + ```c + /* 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. + */ + .Name = "wasmedge_plugintest_c_module", + /* Module description. */ + .Description = "This is for the plugin tests in WasmEdge C API.", + /* Creation function pointer. */ + .Create = CreateTestModule, + }}; + + /* 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. + */ + .Name = "wasmedge_plugintest_c", + /* Plug-in description. */ + .Description = "", + /* Plug-in API version. */ + .APIVersion = WasmEdge_Plugin_CurrentAPIVersion, + /* Plug-in version. Developers can define the version of this plug-in. */ + .Version = + { + .Major = 0, + .Minor = 1, + .Patch = 0, + .Build = 0, + }, + /* Module count in this plug-in. */ + .ModuleCount = 1, + /* Plug-in option description count in this plug-in (Work in progress). */ + .ProgramOptionCount = 0, + /* Pointer to the module description array. */ + .ModuleDescriptions = ModuleDesc, + /* Pointer to the plug-in option description array (Work in progress). */ + .ProgramOptions = NULL, + }}; + ``` + + These descriptions define the name, description, version, and creation function of the plugin, as well as the name and description of the module it contains. + +Remember to implement any additional functions or structures that your plugin requires to fulfill its functionality. + +By following these steps and implementing the necessary functions and descriptors, you can create a plug-in with host functions and modules in WasmEdge C API. You can continue developing your plugin by adding functionality and implementing the desired behavior. + +## Build your plugin + +To build the WasmEdge plug-in shared library, you have two options: building it directly using the compiler or using CMake. Here are the instructions for both methods: + +- **Build with Command**: if you choose to build the plug-in using the command line, run the following command in terminal: + + This command compiles the `myplugin.c` file into a shared library named `libwasmedgePluginTest.so`. The `-std=c11` flag sets the C language standard to C11, and the `-DWASMEDGE_PLUGIN` flag defines the WASMEDGE_PLUGIN macro, which can be used in your code. + +- **Build with CMake**: If you prefer to use CMake to build the plug-in, create a `CMakeLists.txt` file in the root directory of your project and add the following content to the CMakeLists.txt file: + + ```cmake + add_library(wasmedgePluginTest + SHARED + myplugin.c + ) + + set_target_properties(wasmedgePluginTest PROPERTIES + C_STANDARD 11 + ) + + target_compile_options(wasmedgePluginTest + PUBLIC + -DWASMEDGE_PLUGIN + ) + + target_link_libraries(wasmedgePluginTest + PRIVATE + wasmedge + ) + ``` + + This CMake configuration sets up a build target called `wasmedgePluginTest`. It compiles the `myplugin.c` file into a shared library. The `C_STANDARD 11` property sets the C language standard to C11. The `target_compile_options` command defines the `WASMEDGE_PLUGIN` macro using the `-DWASMEDGE_PLUGIN` flag. Finally, the `target_link_libraries` command links the wasmedge library to the plug-in. + +Once you have set up either the command-line build or the CMake build, you can execute the corresponding build command or generate build files using CMake. This will compile your plug-in source code and produce the shared library file `(libwasmedgePluginTest.so)`. + +## Test and debug the plugin + +Once you have compiled the plugin, you can test it using the following steps: + +- **Test the plugin with WasmEdge**: Load and execute the plugin using the WasmEdge runtime, and ensure it works as expected. To test the plugin with WasmEdge, you can use the following command: + + ```bash + wasmedge --dir=./build myplugin.so + ``` + +- **Debug any issues**: To launch a debugger for a WasmEdge binary file, run the following command: + + ```bash + wasmedge debug my-plugin.wasm + ``` + +This will launch a debugger for the WasmEdge binary file, and allow you to step through the code and inspect the values of variables. + +Finally, compile the WasmEdge plugin. diff --git a/docs/contribute/plugin/_category_.json b/docs/contribute/plugin/_category_.json index 3d29fcfbe..f78ce6216 100644 --- a/docs/contribute/plugin/_category_.json +++ b/docs/contribute/plugin/_category_.json @@ -4,4 +4,5 @@ "link": { "type": "generated-index", "description": "we will learn how to develop the WasmEdge Plugin System." - } \ No newline at end of file + } +} \ No newline at end of file diff --git a/docs/contribute/plugin/develop_plugin_c.md b/docs/contribute/plugin/develop_plugin_c.md deleted file mode 100644 index b31f9fe52..000000000 --- a/docs/contribute/plugin/develop_plugin_c.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -sidebar_position: 4 ---- - -# Develop WasmEdge Plug-in in C API - -WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's own building and releasing process. - -## Prerequisites - -For developing the WasmEdge plug-in in C API, please [install WasmEdge](/develop/build-and-run/install.md) first. - -## Example - -Assume that the plug-in example is in the file `testplugin.c`. - -### Host Functions - -The goal of the plug-in is to provide the host functions which can be imported when instantiating WASM. - -Therefore, developers can implement their plug-in host functions first, as the same as the [host functions in WasmEdge C API](/embed/c/reference/0.12.0.md#host-functions). - -> For the more details about the [external data](/embed/c/host_function.md#host-data) and [calling frame context](/embed/c/host_function.md#calling-frame-context), please refer to the host function guide. - -```c -#include - -/* The host function definitions. */ - -/* The host function to add 2 int32_t numbers. */ -WasmEdge_Result HostFuncAdd(void *Data, - const WasmEdge_CallingFrameContext *CallFrameCxt, - const WasmEdge_Value *In, WasmEdge_Value *Out) { - int32_t Val1 = WasmEdge_ValueGetI32(In[0]); - int32_t Val2 = WasmEdge_ValueGetI32(In[1]); - Out[0] = WasmEdge_ValueGenI32(Val1 + Val2); - return WasmEdge_Result_Success; -} - -/* The host function to sub 2 int32_t numbers. */ -WasmEdge_Result HostFuncSub(void *Data, - const WasmEdge_CallingFrameContext *CallFrameCxt, - const WasmEdge_Value *In, WasmEdge_Value *Out) { - int32_t Val1 = WasmEdge_ValueGetI32(In[0]); - int32_t Val2 = WasmEdge_ValueGetI32(In[1]); - Out[0] = WasmEdge_ValueGenI32(Val1 - Val2); - return WasmEdge_Result_Success; -} -``` - -### Host Modules - -Then developers should implement the module creation functions. - -Noticed that there can be several module instances in a plug-in shared library. Here take a module named as `wasmedge_plugintest_c_module` for the example. - -```c -/* The creation function of creating the module instance. */ -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 the description from this descriptor. - */ - - /* Exported module name of this module instance. */ - WasmEdge_String ModuleName = - WasmEdge_StringCreateByCString("wasmedge_plugintest_c_module"); - WasmEdge_ModuleInstanceContext *Mod = - WasmEdge_ModuleInstanceCreate(ModuleName); - WasmEdge_StringDelete(ModuleName); - - 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; - - /* Create and add the host function instances into the module instance. */ - FType = WasmEdge_FunctionTypeCreate(ParamTypes, 2, ReturnTypes, 1); - FuncName = WasmEdge_StringCreateByCString("add"); - FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncAdd, NULL, 0); - WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); - WasmEdge_StringDelete(FuncName); - FuncName = WasmEdge_StringCreateByCString("sub"); - FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncSub, NULL, 0); - WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); - WasmEdge_StringDelete(FuncName); - WasmEdge_FunctionTypeDelete(FType); - - return Mod; -} -``` - -### Plug-in Descriptions - -For constructing the plug-in, developers should supply the descriptions of this plug-in and the modules. - -```c -/* 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. - */ - .Name = "wasmedge_plugintest_c_module", - /* Module description. */ - .Description = "This is for the plugin tests in WasmEdge C API.", - /* Creation function pointer. */ - .Create = CreateTestModule, -}}; - -/* 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. - */ - .Name = "wasmedge_plugintest_c", - /* Plug-in description. */ - .Description = "", - /* Plug-in API version. */ - .APIVersion = WasmEdge_Plugin_CurrentAPIVersion, - /* Plug-in version. Developers can define the version of this plug-in. */ - .Version = - { - .Major = 0, - .Minor = 1, - .Patch = 0, - .Build = 0, - }, - /* Module count in this plug-in. */ - .ModuleCount = 1, - /* Plug-in option description count in this plug-in (Work in progress). */ - .ProgramOptionCount = 0, - /* Pointer to the module description array. */ - .ModuleDescriptions = ModuleDesc, - /* Pointer to the plug-in option description array (Work in progress). */ - .ProgramOptions = NULL, -}}; -``` - -### Plug-in Options - -WORK IN PROGRESS. This section is reserved for the feature in the future. - -### Implement the Get Descriptor API - -The final step is to implement the `WasmEdge_Plugin_GetDescriptor()` API to return the plug-in descriptor. - -```c -WASMEDGE_CAPI_PLUGIN_EXPORT const WasmEdge_PluginDescriptor * -WasmEdge_Plugin_GetDescriptor(void) { - return &Desc; -} -``` - -## Build - -To build the plug-in shared library, developers can choose to build stand-alone by the compiler or use cmake. - -### Build with Command - -```bash -clang -shared -std=c11 -DWASMEDGE_PLUGIN testplugin.c -lwasmedge -o libwasmedgePluginTest.so -``` - -### Build in CMake - -```cmake -add_library(wasmedgePluginTest - SHARED - testplugin.c -) - -set_target_properties(wasmedgePluginTest PROPERTIES - C_STANDARD 11 -) - -target_compile_options(wasmedgePluginTest - PUBLIC - -DWASMEDGE_PLUGIN -) - -target_link_libraries(wasmedgePluginTest - PRIVATE - wasmedge -) -``` diff --git a/docs/contribute/plugin/develop_plugin_cpp.md b/docs/contribute/plugin/develop_plugin_cpp.md index 5623e0ce8..9bc08fcb8 100644 --- a/docs/contribute/plugin/develop_plugin_cpp.md +++ b/docs/contribute/plugin/develop_plugin_cpp.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 3 --- # Develop WasmEdge Plug-in in C++ API diff --git a/docs/contribute/plugin/plugin_requirement.md b/docs/contribute/plugin/plugin_requirement.md deleted file mode 100644 index 937b199a4..000000000 --- a/docs/contribute/plugin/plugin_requirement.md +++ /dev/null @@ -1,348 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Requirements for Developing WasmEdge Plugin - -By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. Here is a flowchart showing all the steps needed for developing WasmEdge Plugin - - -```mermaid -graph TD; -A(Choose programming language) --> B(C API) -A --> C(C++ API) -A --> D(Rust API) -B --> E(Set up development environment) -C --> E -D --> E -E --> F(Create project directory) -E --> G(Add configuration files) -E --> H(Install necessary tools and dependencies) -E --> I(Enable specific backends or components) -E --> J(Write plugin code) -E --> K(Build plugin) -F --> L(Define plugin API) -K --> L -L --> M(Compile WasmEdge plugin) -M --> N(Test and debug plugin) - -``` - -This flowchart illustrates the process of developing a WasmEdge plugin, showcasing the steps involved from choosing a programming language to finalizing and releasing the plugin. - -> For existing plugins, please refer to their respective [documentation pages](/contribute/source/plugin) for specific instructions. - -## Choose programming language - -The first step in developing a WasmEdge plugin is to choose the programming language one wants to use. Currently, C, C++, and Rust are supported by the WasmEdge runtime. Depending on your preferred language, you can follow the specific instructions provided on separate pages: - -- **C:** - - - **Install WasmEdge**: Developers using the C API should install WasmEdge before starting the development process. Follow the [install WasmEdge](/develop/build-and-run/install.md) guide for detailed instructions. - - - **Develop the plugin**: Once WasmEdge is installed, you can proceed with developing your plugin using the WasmEdge [C API](develop_plugin_c.md). - -- **C++**: - - - **Build WasmEdge from source**: Developers interested in using the internal C++ API should build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. - - - **Develop the plugin**: After building WasmEdge, you can develop your plugin using the internal [C++ API](develop_plugin_cpp.md). - -- **Rust**: - - - **Install Rust**: To develop WasmEdge plugins using Rust, you need to have Rust installed on your system. You can refer to the [Rust Setup Guide](/develop/rust/setup.md) for instructions on installing Rust. - - - **Develop the plugin**: Once Rust is installed, you can start developing WasmEdge plugins using the Rust programming language. - -> It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plugin development because of the support, compatibility and flexibility provided by the WasmEdge runtime. - -The choice of programming language depends on the developer's familiarity and skill with the language. C and C++ are commonly chosen for their low-level control over system resources and the ability to create high-performance plugins. Rust, on the other hand, is known for its safety features and performance. - -## Set up the development environment - -To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - - -- **Install a WasmEdge runtime**: You can download the latest version of WasmEdge from [GitHub repository](https://github.com/wasmEdge/wasmEdge). Here are the installation instructions for different operating system for [installing WasmEdge](/develop/build-and-run/install.md). - -- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your own plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. - - To see a list of supported plugins and their specific install commands, see the [Install WasmEdge plugins and dependencies](develop/build-and-run/install/#install-wasmedge-plugins-and-dependencies) section. - -- **Install a compatible compiler**: The following compilers can be used to compile C and C++ code into WebAssembly bytecode: - - - LLVM: `sudo apt-get install llvm` - - GCC: `sudo apt-get install gcc` - - Rust has its own built-in compiler, which can be installed using rustup: - - ```bash - curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - source $HOME/.cargo/env - ``` - -- **Install necessary tools and dependencies**: You can use any text editor or IDE of your choice to write code. Here are some popular options: - - - [Visual Studio Code](https://code.visualstudio.com/) - - [Atom](https://atom.io/) - - [Sublime Text](https://www.sublimetext.com/) - - For debugging, you can use GDB, LLDB, or other debuggers that support WebAssembly. To install GDB, run `sudo apt-get install gdb`. - -- **Enable specific backends or additional components (if applicable):** Some plugins may require enabling specific backends or additional components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: - - - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) - - [TensorFlow Lite](../../build-and-run/install#wasi-nn-plugin-with-tensorflow-lite) - - [PyTorch 1.8.2 LTS](https://pytorch.org/get-started/locally/) - -By following these steps, you can set up the development environment for creating WasmEdge plugins effectively. This will allow you to develop, test, and debug your plugins in a Linux environment. - -## Create a WasmEdge plugin project - -To create a WasmEdge plugin project, follow these steps: - -- **Set up the project directory**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your own structure. To create a project directory structure, use the following commands: - - ```bash - mkdir myplugin - cd myplugin - mkdir src include build - ``` - -- **Add configuration files**: Add configuration files specifying the plugin name, version, and dependencies. The specific files and their content depend on the chosen programming language and build system. - - - For C/C++ plugins, create a `CMakeLists.txt` file in the root directory with the necessary configuration to specify the plugin name, version, and dependencies. The `find_package(WasmEdge REQUIRED)` line locates the WasmEdge runtime library and makes it available for the project. - - ```cmake - cmake_minimum_required(VERSION 3.14) - project(myplugin VERSION 0.1.0) - - find_package(WasmEdge REQUIRED) - - add_library(myplugin SHARED src/myplugin.cpp) - target_compile_features(myplugin PUBLIC cxx_std_11) - target_include_directories(myplugin PUBLIC include) - target_link_libraries(myplugin PRIVATE ${WASMEDGE_LIBRARIES}) - set_target_properties(myplugin PROPERTIES PREFIX "") - ``` - - - For Rust plugins, create a `Cargo.toml` file in the root directory with the necessary configuration to specify the plugin name, version, and dependencies. The `wasmedge-runtime` dependency is added with the appropriate version and features. - - ```toml - [package] - name = "myplugin" - version = "0.1.0" - edition = "2018" - - [lib] - crate-type = ["cdylib"] - - [dependencies] - wasmedge-runtime = { version = ">=0.9", features = ["cranelift"] } - ``` - -- **Add any necessary libraries or dependencies**: Include any required libraries or dependencies for your plugin. Modify the configuration files created in the previous step to include the necessary dependencies. For example, in the `CMakeLists.txt` file, use the `find_package` command to locate the WasmEdge runtime library and link it to your plugin. - -- **Write the plugin code**: Start writing your plugin code in the `src` directory. Create one or more source files that define the functionality of your plugin. For example, in C++, you might create `myplugin.cpp` file with following code: - - ```cpp - #include - - extern "C" { - WasmEdge_Result initializePlugin() { - // Plugin initialization code - return WasmEdge_Result_Success; - } - - WasmEdge_Result finalizePlugin() { - // Plugin finalization code - return WasmEdge_Result_Success; - } - } - - ``` - - Modify the above code according to your plugin's functionality. In this example, the plugin defines two external functions, `initializePlugin` and `finalizePlugin`, which are the entry points for the plugin's initialization and finalization code. - -- **Build your plugin**: Depending on your build system, use the appropriate commands to build the plugin. - - - For C/C++ plugins, run the following commands from the `build` directory: - - ```bash - cd build - cmake .. - make - ``` - - - For Rust plugins, run the following commands from the project root directory: - - ```bash - cargo build --release --target wasm32-wasi - wasm-bindgen target/wasm32-wasi/release/myplugin.wasm --out-dir . - ``` - - These commands will generate the plugin binary based on the provided configuration. - -Your compiled plugin should be located in the `build` directory for C/C++ or in the project root directory for Rust. - -By following these steps, you will have a WasmEdge plugin project set up with the necessary directory structure, configuration files, and initial code. You can continue developing your plugin by adding functionality and implementing the desired behavior. - -## Define the plugin API - -The plugin API is a set of functions that the WasmEdge runtime will call to interact with the plugin. The specific functions that are required in the plugin API depend on the features that your plugin provides. - -- **Specify interaction**: Specify how the plugin will receive input and provide output to the runtime. This can be done through function parameters, return values, or other means of communication. - -- **Provide functions**: Define functions that the plugin will expose to the runtime, such as initialization, execution, and cleanup functions. These functions should perform specific tasks related to the plugin's functionality. - -### Define the plugin API for C/C++ - -Here's an example of how to define the plugin API for a C/C++ WasmEdge plugin: - -- **Create a header file for your plugin**: In the include directory, create a header file (e.g., `myplugin.h`) that declares the plugin API functions. For example: - - ```c - #pragma once - - #include - - class MyPlugin { - public: - MyPlugin(); - ~MyPlugin(); - - void init(); - void execute(uint32_t input); - void cleanup(); - }; - ``` - -- **Implement the plugin API functions**: In your plugin's source file (e.g., `src/myplugin.cpp`), implement the declared API functions. For example: - - ```c - #include "myplugin.h" - #include - - class MyPlugin : public wasmedge::Plugin { - public: - MyPlugin() { - // Initialization code - } - - ~MyPlugin() { - // Cleanup code - } - - void init() override { - // Initialization code - } - - void execute(uint32_t input) override { - // Execution code - } - - void cleanup() override { - // Cleanup code - } - }; - ``` - -- **Expose the plugin API functions**: In the myplugin.cpp file, you'll also need to expose the plugin API functions to the WasmEdge runtime using the `wasm_export_ prefix`. For example: - - ```c - extern "C" { - void wasm_export_myplugin_init(const struct wasm_export_myplugin_init_args_t* args) { - // Initialization code - } - - void wasm_export_myplugin_execute(const struct wasm_export_myplugin_execute_args_t* args) { - // Execution code - } - - void wasm_export_myplugin_cleanup(const struct wasm_export_myplugin_cleanup_args_t* args) { - // Cleanup code - } - } - ``` - -By following these steps, you can define the plugin API for a C/C++ WasmEdge plugin. - -### Define the plugin API for RUST - -For Rust, you would define the plugin API using Rust's traits and methods. - -For example, in `myplugin.rs`: - - ```toml - use wasmedge::core::plugin::{Plugin, PluginExecuteArgs, PluginInitArgs, PluginCleanupArgs}; - - pub struct MyPlugin; - - impl Plugin for MyPlugin { - fn init(&mut self) { - // Initialization code - } - - fn execute(&mut self, input: u32) { - // Execution code - } - - fn cleanup(&mut self) { - // Cleanup code - } - } - ``` - -Then, you would expose the plugin API functions to the WasmEdge runtime using the `wasm_export_ prefix`, similar to the C/C++ example. - -By defining the plugin API, you can establish a clear interface between your plugin and the WasmEdge runtime, making it easier to develop and maintain your plugin. - -## Compile the WasmEdge plugin - -Once you have implemented the plugin API, you can compile the plugin using the following steps: - -- **Compile the plugin code**: Use the installed compiler to compile the plugin code into WebAssembly bytecode. Replace `myplugin.c` with the name of your plugin's source file, and build `myplugin.wasm` with the desired output path and filename. - - ```bash - clang --target=wasm32 -O3 -nostdlib \ - -Wl,--export-all -Wl,--allow-undefined \ - -o build/myplugin.wasm src/myplugin.c - ``` - - This command compiles the plugin code into WebAssembly bytecode using the Clang compiler. Adjust the compiler flags as needed for your specific requirements. - -- **Link with necessary dependencies**: If your plugin depends on external libraries or the WasmEdge runtime, you need to link them with the bytecode. For example, if you are using the WasmEdge C API in your plugin, include the following linker flags: - - ```bash - -L/usr/local/lib -lwasmedgeC - ``` - - Modify these flags to match the location and name of the required libraries on your system. - -- **Create the binary for execution**: Generate the binary file that can be loaded and executed by the WasmEdge runtime. The specific command depends on the target platform and the desired output format. For example, to create a shared object file (`.so`) on Linux, use the following command: - - ```bash - clang -shared -o build/myplugin.so build/myplugin.wasm - ``` - - Adjust the output path and filename as needed for your project. - -By following these steps, you can compile your WasmEdge plugin and create a binary that can be loaded and executed by the WasmEdge runtime. - -## Test and debug the plugin - -Once you have compiled the plugin, you can test it using the following steps: - -- **Test the plugin with WasmEdge**: Load and execute the plugin using the WasmEdge runtime, and ensure it works as expected. To test the plugin with WasmEdge, you can use the following command: - - ```bash - wasmedge --dir=./build myplugin.so - ``` - -- **Debug any issues**: To launch a debugger for a WasmEdge binary file, run the following command: - - ```bash - wasmedge debug my-plugin.wasm - ``` - -This will launch a debugger for the WasmEdge binary file, and allow you to step through the code and inspect the values of variables. - -Finally, compile the WasmEdge plugin. From 54def63170b865e05765d7098d2a8349d6b0c4a9 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Wed, 5 Jul 2023 11:03:31 +0600 Subject: [PATCH 07/20] updating changes Signed-off-by: Mahfuza --- .vscode/settings.json | 8 +- .../Develop Plugin in C/_category_.json | 2 +- .../Develop Plugin in C/plugin_development.md | 4 +- .../Develop Plugin in CPP/_category_.json | 2 +- .../plugin_development.md | 15 +- .../Develop Plugin in Rust/_category_.json | 8 + .../plugin_development.md | 292 ++++++++++++++++++ 7 files changed, 319 insertions(+), 12 deletions(-) create mode 100644 docs/contribute/plugin/Develop Plugin in Rust/_category_.json create mode 100644 docs/contribute/plugin/Develop Plugin in Rust/plugin_development.md diff --git a/.vscode/settings.json b/.vscode/settings.json index 40b89c812..286e3a616 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,3 +1,9 @@ { - "cSpell.words": ["bytecode", "CNCF", "Emscripten", "wasmedge"] + "cSpell.words": [ + "bytecode", + "CNCF", + "Emscripten", + "wasmedge" + ], + "docwriter.style": "Auto-detect" } diff --git a/docs/contribute/plugin/Develop Plugin in C/_category_.json b/docs/contribute/plugin/Develop Plugin in C/_category_.json index b370377a1..b6cce3b0f 100644 --- a/docs/contribute/plugin/Develop Plugin in C/_category_.json +++ b/docs/contribute/plugin/Develop Plugin in C/_category_.json @@ -1,5 +1,5 @@ { - "label": "WasmEdge Plugin System in C", + "label": "WasmEdge Plugin in C", "position": 2, "link": { "type": "generated-index", diff --git a/docs/contribute/plugin/Develop Plugin in C/plugin_development.md b/docs/contribute/plugin/Develop Plugin in C/plugin_development.md index cd6eb573d..a52cb590f 100644 --- a/docs/contribute/plugin/Develop Plugin in C/plugin_development.md +++ b/docs/contribute/plugin/Develop Plugin in C/plugin_development.md @@ -98,7 +98,7 @@ To create a plug-in with host functions and modules, follow these steps: Therefore, developers can implement their plug-in host functions first, as the same as the [host functions in WasmEdge C API](/embed/c/reference/0.12.0.md#host-functions). -> For the more details about the [external data](/embed/c/host_function.md#host-data) and [calling frame context](/embed/c/host_function.md#calling-frame-context), please refer to the host function guide. + > For the more details about the [external data](/embed/c/host_function.md#host-data) and [calling frame context](/embed/c/host_function.md#calling-frame-context), please refer to the host function guide. Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers respectively: @@ -236,6 +236,8 @@ Remember to implement any additional functions or structures that your plugin re By following these steps and implementing the necessary functions and descriptors, you can create a plug-in with host functions and modules in WasmEdge C API. You can continue developing your plugin by adding functionality and implementing the desired behavior. +- **Plugin option** - *WORK IN PROGRESS. This section is reserved for the feature in the future.* + ## Build your plugin To build the WasmEdge plug-in shared library, you have two options: building it directly using the compiler or using CMake. Here are the instructions for both methods: diff --git a/docs/contribute/plugin/Develop Plugin in CPP/_category_.json b/docs/contribute/plugin/Develop Plugin in CPP/_category_.json index e59ba2ded..9a7e427e2 100644 --- a/docs/contribute/plugin/Develop Plugin in CPP/_category_.json +++ b/docs/contribute/plugin/Develop Plugin in CPP/_category_.json @@ -1,5 +1,5 @@ { - "label": "WasmEdge Plugin System in C++", + "label": "WasmEdge Plugin in C++", "position": 3, "link": { "type": "generated-index", diff --git a/docs/contribute/plugin/Develop Plugin in CPP/plugin_development.md b/docs/contribute/plugin/Develop Plugin in CPP/plugin_development.md index cd6eb573d..0875b2e4d 100644 --- a/docs/contribute/plugin/Develop Plugin in CPP/plugin_development.md +++ b/docs/contribute/plugin/Develop Plugin in CPP/plugin_development.md @@ -2,14 +2,17 @@ sidebar_position: 2 --- -# Develop WasmEdge Plug-in in C API +# Develop WasmEdge Plug-in in C++ API By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's own building and releasing process. + +> It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plugin development because of the support, compatibility and flexibility provided by the WasmEdge runtime. + Here is a flowchart showing all the steps needed for developing WasmEdge Plugin - ```mermaid graph TD; -B[Developing WasmEdge Plugin in C] +B[Developing WasmEdge Plugin in C++] B --> E(Set up development environment) E --> F(Create project directory) E --> G(Add configuration files) @@ -32,13 +35,13 @@ This flowchart illustrates the process of developing a WasmEdge plugin, showcasi To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - -- **Install a WasmEdge runtime**: You can download the latest version of WasmEdge from [GitHub repository](https://github.com/wasmEdge/wasmEdge). Here are the installation instructions for different operating system for [installing WasmEdge](/develop/build-and-run/install.md). +- **Build WasmEdge from source**- For developing WasmEdge plugin in C++ language, you will need to build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. - **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your own plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. To see a list of supported plugins and their specific install commands, see the [Install WasmEdge plugins and dependencies](develop/build-and-run/install/#install-wasmedge-plugins-and-dependencies) section. -- **Install a compatible compiler**: The following compilers can be used to compile C code into WebAssembly bytecode: +- **Install a compatible compiler**: The following compilers can be used to compile C++ code into WebAssembly bytecode: - LLVM: `sudo apt-get install llvm` - GCC: `sudo apt-get install gcc` @@ -96,10 +99,6 @@ To create a plug-in with host functions and modules, follow these steps: - **Implement host function definitions**: In this step, you need to define the host functions that will be imported when instantiating the WASM module. These functions will perform specific operations and return results. - Therefore, developers can implement their plug-in host functions first, as the same as the [host functions in WasmEdge C API](/embed/c/reference/0.12.0.md#host-functions). - -> For the more details about the [external data](/embed/c/host_function.md#host-data) and [calling frame context](/embed/c/host_function.md#calling-frame-context), please refer to the host function guide. - Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers respectively: ```c diff --git a/docs/contribute/plugin/Develop Plugin in Rust/_category_.json b/docs/contribute/plugin/Develop Plugin in Rust/_category_.json new file mode 100644 index 000000000..f464cdef4 --- /dev/null +++ b/docs/contribute/plugin/Develop Plugin in Rust/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "WasmEdge Plugin in Rust", + "position": 3, + "link": { + "type": "generated-index", + "description": "We will learn how to develop the WasmEdge Plugin System in Rust Language." + } +} diff --git a/docs/contribute/plugin/Develop Plugin in Rust/plugin_development.md b/docs/contribute/plugin/Develop Plugin in Rust/plugin_development.md new file mode 100644 index 000000000..cd6eb573d --- /dev/null +++ b/docs/contribute/plugin/Develop Plugin in Rust/plugin_development.md @@ -0,0 +1,292 @@ +--- +sidebar_position: 2 +--- + +# Develop WasmEdge Plug-in in C API + +By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's own building and releasing process. +Here is a flowchart showing all the steps needed for developing WasmEdge Plugin - + +```mermaid +graph TD; +B[Developing WasmEdge Plugin in C] +B --> E(Set up development environment) +E --> F(Create project directory) +E --> G(Add configuration files) +E --> H(Install necessary tools and dependencies) +E --> I(Enable specific backends or components) +E --> J(Write plugin code) +E --> K(Build plugin) +F --> L(Define plugin API) +K --> L +L --> M(Compile WasmEdge plugin) +M --> N(Test and debug plugin) + +``` + +This flowchart illustrates the process of developing a WasmEdge plugin, showcasing the steps involved from choosing a programming language to finalizing and releasing the plugin. + +> For existing plugins, please refer to their respective [documentation pages](/contribute/source/plugin) for specific instructions. + +## Set up the development environment + +To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - + +- **Install a WasmEdge runtime**: You can download the latest version of WasmEdge from [GitHub repository](https://github.com/wasmEdge/wasmEdge). Here are the installation instructions for different operating system for [installing WasmEdge](/develop/build-and-run/install.md). + +- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your own plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. + + To see a list of supported plugins and their specific install commands, see the [Install WasmEdge plugins and dependencies](develop/build-and-run/install/#install-wasmedge-plugins-and-dependencies) section. + +- **Install a compatible compiler**: The following compilers can be used to compile C code into WebAssembly bytecode: + + - LLVM: `sudo apt-get install llvm` + - GCC: `sudo apt-get install gcc` + +- **Install necessary tools and dependencies**: You can use any text editor or IDE of your choice to write code. Here are some popular options: + + - [Visual Studio Code](https://code.visualstudio.com/) + - [Atom](https://atom.io/) + - [Sublime Text](https://www.sublimetext.com/) + + For debugging, you can use GDB, LLDB, or other debuggers that support WebAssembly. To install GDB, run `sudo apt-get install gdb`. + +- **Enable specific backends or additional components (if applicable):** Some plugins may require enabling specific backends or additional components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: + + - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) + - [TensorFlow Lite](../../build-and-run/install#wasi-nn-plugin-with-tensorflow-lite) + - [PyTorch 1.8.2 LTS](https://pytorch.org/get-started/locally/) + +By following these steps, you can set up the development environment for creating WasmEdge plugins effectively. This will allow you to develop, test, and debug your plugins in a Linux environment. + +## Create a WasmEdge plugin project + +To create a WasmEdge plugin project, follow these steps: + +- **Set up the project directory**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your own structure. To create a project directory structure, use the following commands: + + ```bash + mkdir myplugin + cd myplugin + mkdir src include build + ``` + +- **Add configuration files**: Add configuration files specifying the plugin name, version, and dependencies. The specific files and their content depend on the chosen programming language and build system. + + Create a `CMakeLists.txt` file in the root directory with the necessary configuration to specify the plugin name, version, and dependencies. The `find_package(WasmEdge REQUIRED)` line locates the WasmEdge runtime library and makes it available for the project. + + ```cmake + cmake_minimum_required(VERSION 3.14) + project(myplugin VERSION 0.1.0) + + find_package(WasmEdge REQUIRED) + + add_library(myplugin SHARED src/myplugin.cpp) + target_compile_features(myplugin PUBLIC cxx_std_11) + target_include_directories(myplugin PUBLIC include) + target_link_libraries(myplugin PRIVATE ${WASMEDGE_LIBRARIES}) + set_target_properties(myplugin PROPERTIES PREFIX "") + ``` + +- **Add any necessary libraries or dependencies**: Include any required libraries or dependencies for your plugin. Modify the configuration files created in the previous step to include the necessary dependencies. For example, in the `CMakeLists.txt` file, use the `find_package` command to locate the WasmEdge runtime library and link it to your plugin. + +## Write the plugin code + +To create a plug-in with host functions and modules, follow these steps: + +- **Implement host function definitions**: In this step, you need to define the host functions that will be imported when instantiating the WASM module. These functions will perform specific operations and return results. + + Therefore, developers can implement their plug-in host functions first, as the same as the [host functions in WasmEdge C API](/embed/c/reference/0.12.0.md#host-functions). + +> For the more details about the [external data](/embed/c/host_function.md#host-data) and [calling frame context](/embed/c/host_function.md#calling-frame-context), please refer to the host function guide. + + Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers respectively: + + ```c + #include + + /* The host function definitions. */ + + /* The host function to add 2 int32_t numbers. */ + WasmEdge_Result HostFuncAdd(void *Data, + const WasmEdge_CallingFrameContext *CallFrameCxt, + const WasmEdge_Value *In, WasmEdge_Value *Out) { + int32_t Val1 = WasmEdge_ValueGetI32(In[0]); + int32_t Val2 = WasmEdge_ValueGetI32(In[1]); + Out[0] = WasmEdge_ValueGenI32(Val1 + Val2); + return WasmEdge_Result_Success; + } + + /* The host function to sub 2 int32_t numbers. */ + WasmEdge_Result HostFuncSub(void *Data, + const WasmEdge_CallingFrameContext *CallFrameCxt, + const WasmEdge_Value *In, WasmEdge_Value *Out) { + int32_t Val1 = WasmEdge_ValueGetI32(In[0]); + int32_t Val2 = WasmEdge_ValueGetI32(In[1]); + Out[0] = WasmEdge_ValueGenI32(Val1 - Val2); + return WasmEdge_Result_Success; + } + ``` + +- **Implement the module creation functions**: In this step, you need to implement the module creation function that creates an instance of the module. This function will be called when the plugin is loaded. + + Here's an example of a module creation function named `CreateTestModule`: + + ```c + /* The creation function of creating the module instance. */ + 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 the description from this descriptor. + */ + + /* Exported module name of this module instance. */ + WasmEdge_String ModuleName = + WasmEdge_StringCreateByCString("wasmedge_plugintest_c_module"); + WasmEdge_ModuleInstanceContext *Mod = + WasmEdge_ModuleInstanceCreate(ModuleName); + WasmEdge_StringDelete(ModuleName); + + 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; + + /* Create and add the host function instances into the module instance. */ + FType = WasmEdge_FunctionTypeCreate(ParamTypes, 2, ReturnTypes, 1); + FuncName = WasmEdge_StringCreateByCString("add"); + FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncAdd, NULL, 0); + WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); + WasmEdge_StringDelete(FuncName); + FuncName = WasmEdge_StringCreateByCString("sub"); + FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncSub, NULL, 0); + WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); + WasmEdge_StringDelete(FuncName); + WasmEdge_FunctionTypeDelete(FType); + + return Mod; + } + ``` + + There can be several module instances in a plug-in shared library. Here in above code snippet take a module named as `wasmedge_plugintest_c_module` for the example. + +- **Supply the plugin descriptions**- In this step, you need to provide the descriptions of the plugin and the modules it contains. These descriptions will be used for searching and creating the plugin and module instances. + + Here's an example of the plugin and module descriptors: + + ```c + /* 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. + */ + .Name = "wasmedge_plugintest_c_module", + /* Module description. */ + .Description = "This is for the plugin tests in WasmEdge C API.", + /* Creation function pointer. */ + .Create = CreateTestModule, + }}; + + /* 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. + */ + .Name = "wasmedge_plugintest_c", + /* Plug-in description. */ + .Description = "", + /* Plug-in API version. */ + .APIVersion = WasmEdge_Plugin_CurrentAPIVersion, + /* Plug-in version. Developers can define the version of this plug-in. */ + .Version = + { + .Major = 0, + .Minor = 1, + .Patch = 0, + .Build = 0, + }, + /* Module count in this plug-in. */ + .ModuleCount = 1, + /* Plug-in option description count in this plug-in (Work in progress). */ + .ProgramOptionCount = 0, + /* Pointer to the module description array. */ + .ModuleDescriptions = ModuleDesc, + /* Pointer to the plug-in option description array (Work in progress). */ + .ProgramOptions = NULL, + }}; + ``` + + These descriptions define the name, description, version, and creation function of the plugin, as well as the name and description of the module it contains. + +Remember to implement any additional functions or structures that your plugin requires to fulfill its functionality. + +By following these steps and implementing the necessary functions and descriptors, you can create a plug-in with host functions and modules in WasmEdge C API. You can continue developing your plugin by adding functionality and implementing the desired behavior. + +## Build your plugin + +To build the WasmEdge plug-in shared library, you have two options: building it directly using the compiler or using CMake. Here are the instructions for both methods: + +- **Build with Command**: if you choose to build the plug-in using the command line, run the following command in terminal: + + This command compiles the `myplugin.c` file into a shared library named `libwasmedgePluginTest.so`. The `-std=c11` flag sets the C language standard to C11, and the `-DWASMEDGE_PLUGIN` flag defines the WASMEDGE_PLUGIN macro, which can be used in your code. + +- **Build with CMake**: If you prefer to use CMake to build the plug-in, create a `CMakeLists.txt` file in the root directory of your project and add the following content to the CMakeLists.txt file: + + ```cmake + add_library(wasmedgePluginTest + SHARED + myplugin.c + ) + + set_target_properties(wasmedgePluginTest PROPERTIES + C_STANDARD 11 + ) + + target_compile_options(wasmedgePluginTest + PUBLIC + -DWASMEDGE_PLUGIN + ) + + target_link_libraries(wasmedgePluginTest + PRIVATE + wasmedge + ) + ``` + + This CMake configuration sets up a build target called `wasmedgePluginTest`. It compiles the `myplugin.c` file into a shared library. The `C_STANDARD 11` property sets the C language standard to C11. The `target_compile_options` command defines the `WASMEDGE_PLUGIN` macro using the `-DWASMEDGE_PLUGIN` flag. Finally, the `target_link_libraries` command links the wasmedge library to the plug-in. + +Once you have set up either the command-line build or the CMake build, you can execute the corresponding build command or generate build files using CMake. This will compile your plug-in source code and produce the shared library file `(libwasmedgePluginTest.so)`. + +## Test and debug the plugin + +Once you have compiled the plugin, you can test it using the following steps: + +- **Test the plugin with WasmEdge**: Load and execute the plugin using the WasmEdge runtime, and ensure it works as expected. To test the plugin with WasmEdge, you can use the following command: + + ```bash + wasmedge --dir=./build myplugin.so + ``` + +- **Debug any issues**: To launch a debugger for a WasmEdge binary file, run the following command: + + ```bash + wasmedge debug my-plugin.wasm + ``` + +This will launch a debugger for the WasmEdge binary file, and allow you to step through the code and inspect the values of variables. + +Finally, compile the WasmEdge plugin. From 19784d1c111ad773e706e16a92724b90e9ce9306 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Wed, 12 Jul 2023 20:33:47 +0600 Subject: [PATCH 08/20] final update Signed-off-by: Mahfuza --- .vscode/settings.json | 7 +- .../Develop Plugin in C/_category_.json | 8 - .../Develop Plugin in C/plugin_development.md | 294 ----- .../Develop Plugin in CPP/_category_.json | 8 - .../plugin_development.md | 291 ----- .../Develop Plugin in Rust/_category_.json | 8 - .../plugin_development.md | 292 ----- docs/contribute/plugin/_category_.json | 14 +- docs/contribute/plugin/develop_plugin_c.md | 360 +++--- docs/contribute/plugin/develop_plugin_cpp.md | 115 +- .../plugin/develop_plugin_rustsdk.md | 59 +- docs/contribute/plugin/intro.md | 97 +- docusaurus.config.js | 8 +- package-lock.json | 1080 +++++++++++++++++ package.json | 1 + 15 files changed, 1529 insertions(+), 1113 deletions(-) delete mode 100644 docs/contribute/plugin/Develop Plugin in C/_category_.json delete mode 100644 docs/contribute/plugin/Develop Plugin in C/plugin_development.md delete mode 100644 docs/contribute/plugin/Develop Plugin in CPP/_category_.json delete mode 100644 docs/contribute/plugin/Develop Plugin in CPP/plugin_development.md delete mode 100644 docs/contribute/plugin/Develop Plugin in Rust/_category_.json delete mode 100644 docs/contribute/plugin/Develop Plugin in Rust/plugin_development.md diff --git a/.vscode/settings.json b/.vscode/settings.json index 286e3a616..323c8ce0a 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,9 +1,4 @@ { - "cSpell.words": [ - "bytecode", - "CNCF", - "Emscripten", - "wasmedge" - ], + "cSpell.words": ["bytecode", "CNCF", "Emscripten", "wasmedge"], "docwriter.style": "Auto-detect" } diff --git a/docs/contribute/plugin/Develop Plugin in C/_category_.json b/docs/contribute/plugin/Develop Plugin in C/_category_.json deleted file mode 100644 index b6cce3b0f..000000000 --- a/docs/contribute/plugin/Develop Plugin in C/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "WasmEdge Plugin in C", - "position": 2, - "link": { - "type": "generated-index", - "description": "We will learn how to develop the WasmEdge Plugin System in C Language." - } -} diff --git a/docs/contribute/plugin/Develop Plugin in C/plugin_development.md b/docs/contribute/plugin/Develop Plugin in C/plugin_development.md deleted file mode 100644 index a52cb590f..000000000 --- a/docs/contribute/plugin/Develop Plugin in C/plugin_development.md +++ /dev/null @@ -1,294 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Develop WasmEdge Plug-in in C API - -By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's own building and releasing process. -Here is a flowchart showing all the steps needed for developing WasmEdge Plugin - - -```mermaid -graph TD; -B[Developing WasmEdge Plugin in C] -B --> E(Set up development environment) -E --> F(Create project directory) -E --> G(Add configuration files) -E --> H(Install necessary tools and dependencies) -E --> I(Enable specific backends or components) -E --> J(Write plugin code) -E --> K(Build plugin) -F --> L(Define plugin API) -K --> L -L --> M(Compile WasmEdge plugin) -M --> N(Test and debug plugin) - -``` - -This flowchart illustrates the process of developing a WasmEdge plugin, showcasing the steps involved from choosing a programming language to finalizing and releasing the plugin. - -> For existing plugins, please refer to their respective [documentation pages](/contribute/source/plugin) for specific instructions. - -## Set up the development environment - -To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - - -- **Install a WasmEdge runtime**: You can download the latest version of WasmEdge from [GitHub repository](https://github.com/wasmEdge/wasmEdge). Here are the installation instructions for different operating system for [installing WasmEdge](/develop/build-and-run/install.md). - -- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your own plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. - - To see a list of supported plugins and their specific install commands, see the [Install WasmEdge plugins and dependencies](develop/build-and-run/install/#install-wasmedge-plugins-and-dependencies) section. - -- **Install a compatible compiler**: The following compilers can be used to compile C code into WebAssembly bytecode: - - - LLVM: `sudo apt-get install llvm` - - GCC: `sudo apt-get install gcc` - -- **Install necessary tools and dependencies**: You can use any text editor or IDE of your choice to write code. Here are some popular options: - - - [Visual Studio Code](https://code.visualstudio.com/) - - [Atom](https://atom.io/) - - [Sublime Text](https://www.sublimetext.com/) - - For debugging, you can use GDB, LLDB, or other debuggers that support WebAssembly. To install GDB, run `sudo apt-get install gdb`. - -- **Enable specific backends or additional components (if applicable):** Some plugins may require enabling specific backends or additional components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: - - - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) - - [TensorFlow Lite](../../build-and-run/install#wasi-nn-plugin-with-tensorflow-lite) - - [PyTorch 1.8.2 LTS](https://pytorch.org/get-started/locally/) - -By following these steps, you can set up the development environment for creating WasmEdge plugins effectively. This will allow you to develop, test, and debug your plugins in a Linux environment. - -## Create a WasmEdge plugin project - -To create a WasmEdge plugin project, follow these steps: - -- **Set up the project directory**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your own structure. To create a project directory structure, use the following commands: - - ```bash - mkdir myplugin - cd myplugin - mkdir src include build - ``` - -- **Add configuration files**: Add configuration files specifying the plugin name, version, and dependencies. The specific files and their content depend on the chosen programming language and build system. - - Create a `CMakeLists.txt` file in the root directory with the necessary configuration to specify the plugin name, version, and dependencies. The `find_package(WasmEdge REQUIRED)` line locates the WasmEdge runtime library and makes it available for the project. - - ```cmake - cmake_minimum_required(VERSION 3.14) - project(myplugin VERSION 0.1.0) - - find_package(WasmEdge REQUIRED) - - add_library(myplugin SHARED src/myplugin.cpp) - target_compile_features(myplugin PUBLIC cxx_std_11) - target_include_directories(myplugin PUBLIC include) - target_link_libraries(myplugin PRIVATE ${WASMEDGE_LIBRARIES}) - set_target_properties(myplugin PROPERTIES PREFIX "") - ``` - -- **Add any necessary libraries or dependencies**: Include any required libraries or dependencies for your plugin. Modify the configuration files created in the previous step to include the necessary dependencies. For example, in the `CMakeLists.txt` file, use the `find_package` command to locate the WasmEdge runtime library and link it to your plugin. - -## Write the plugin code - -To create a plug-in with host functions and modules, follow these steps: - -- **Implement host function definitions**: In this step, you need to define the host functions that will be imported when instantiating the WASM module. These functions will perform specific operations and return results. - - Therefore, developers can implement their plug-in host functions first, as the same as the [host functions in WasmEdge C API](/embed/c/reference/0.12.0.md#host-functions). - - > For the more details about the [external data](/embed/c/host_function.md#host-data) and [calling frame context](/embed/c/host_function.md#calling-frame-context), please refer to the host function guide. - - Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers respectively: - - ```c - #include - - /* The host function definitions. */ - - /* The host function to add 2 int32_t numbers. */ - WasmEdge_Result HostFuncAdd(void *Data, - const WasmEdge_CallingFrameContext *CallFrameCxt, - const WasmEdge_Value *In, WasmEdge_Value *Out) { - int32_t Val1 = WasmEdge_ValueGetI32(In[0]); - int32_t Val2 = WasmEdge_ValueGetI32(In[1]); - Out[0] = WasmEdge_ValueGenI32(Val1 + Val2); - return WasmEdge_Result_Success; - } - - /* The host function to sub 2 int32_t numbers. */ - WasmEdge_Result HostFuncSub(void *Data, - const WasmEdge_CallingFrameContext *CallFrameCxt, - const WasmEdge_Value *In, WasmEdge_Value *Out) { - int32_t Val1 = WasmEdge_ValueGetI32(In[0]); - int32_t Val2 = WasmEdge_ValueGetI32(In[1]); - Out[0] = WasmEdge_ValueGenI32(Val1 - Val2); - return WasmEdge_Result_Success; - } - ``` - -- **Implement the module creation functions**: In this step, you need to implement the module creation function that creates an instance of the module. This function will be called when the plugin is loaded. - - Here's an example of a module creation function named `CreateTestModule`: - - ```c - /* The creation function of creating the module instance. */ - 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 the description from this descriptor. - */ - - /* Exported module name of this module instance. */ - WasmEdge_String ModuleName = - WasmEdge_StringCreateByCString("wasmedge_plugintest_c_module"); - WasmEdge_ModuleInstanceContext *Mod = - WasmEdge_ModuleInstanceCreate(ModuleName); - WasmEdge_StringDelete(ModuleName); - - 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; - - /* Create and add the host function instances into the module instance. */ - FType = WasmEdge_FunctionTypeCreate(ParamTypes, 2, ReturnTypes, 1); - FuncName = WasmEdge_StringCreateByCString("add"); - FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncAdd, NULL, 0); - WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); - WasmEdge_StringDelete(FuncName); - FuncName = WasmEdge_StringCreateByCString("sub"); - FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncSub, NULL, 0); - WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); - WasmEdge_StringDelete(FuncName); - WasmEdge_FunctionTypeDelete(FType); - - return Mod; - } - ``` - - There can be several module instances in a plug-in shared library. Here in above code snippet take a module named as `wasmedge_plugintest_c_module` for the example. - -- **Supply the plugin descriptions**- In this step, you need to provide the descriptions of the plugin and the modules it contains. These descriptions will be used for searching and creating the plugin and module instances. - - Here's an example of the plugin and module descriptors: - - ```c - /* 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. - */ - .Name = "wasmedge_plugintest_c_module", - /* Module description. */ - .Description = "This is for the plugin tests in WasmEdge C API.", - /* Creation function pointer. */ - .Create = CreateTestModule, - }}; - - /* 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. - */ - .Name = "wasmedge_plugintest_c", - /* Plug-in description. */ - .Description = "", - /* Plug-in API version. */ - .APIVersion = WasmEdge_Plugin_CurrentAPIVersion, - /* Plug-in version. Developers can define the version of this plug-in. */ - .Version = - { - .Major = 0, - .Minor = 1, - .Patch = 0, - .Build = 0, - }, - /* Module count in this plug-in. */ - .ModuleCount = 1, - /* Plug-in option description count in this plug-in (Work in progress). */ - .ProgramOptionCount = 0, - /* Pointer to the module description array. */ - .ModuleDescriptions = ModuleDesc, - /* Pointer to the plug-in option description array (Work in progress). */ - .ProgramOptions = NULL, - }}; - ``` - - These descriptions define the name, description, version, and creation function of the plugin, as well as the name and description of the module it contains. - -Remember to implement any additional functions or structures that your plugin requires to fulfill its functionality. - -By following these steps and implementing the necessary functions and descriptors, you can create a plug-in with host functions and modules in WasmEdge C API. You can continue developing your plugin by adding functionality and implementing the desired behavior. - -- **Plugin option** - *WORK IN PROGRESS. This section is reserved for the feature in the future.* - -## Build your plugin - -To build the WasmEdge plug-in shared library, you have two options: building it directly using the compiler or using CMake. Here are the instructions for both methods: - -- **Build with Command**: if you choose to build the plug-in using the command line, run the following command in terminal: - - This command compiles the `myplugin.c` file into a shared library named `libwasmedgePluginTest.so`. The `-std=c11` flag sets the C language standard to C11, and the `-DWASMEDGE_PLUGIN` flag defines the WASMEDGE_PLUGIN macro, which can be used in your code. - -- **Build with CMake**: If you prefer to use CMake to build the plug-in, create a `CMakeLists.txt` file in the root directory of your project and add the following content to the CMakeLists.txt file: - - ```cmake - add_library(wasmedgePluginTest - SHARED - myplugin.c - ) - - set_target_properties(wasmedgePluginTest PROPERTIES - C_STANDARD 11 - ) - - target_compile_options(wasmedgePluginTest - PUBLIC - -DWASMEDGE_PLUGIN - ) - - target_link_libraries(wasmedgePluginTest - PRIVATE - wasmedge - ) - ``` - - This CMake configuration sets up a build target called `wasmedgePluginTest`. It compiles the `myplugin.c` file into a shared library. The `C_STANDARD 11` property sets the C language standard to C11. The `target_compile_options` command defines the `WASMEDGE_PLUGIN` macro using the `-DWASMEDGE_PLUGIN` flag. Finally, the `target_link_libraries` command links the wasmedge library to the plug-in. - -Once you have set up either the command-line build or the CMake build, you can execute the corresponding build command or generate build files using CMake. This will compile your plug-in source code and produce the shared library file `(libwasmedgePluginTest.so)`. - -## Test and debug the plugin - -Once you have compiled the plugin, you can test it using the following steps: - -- **Test the plugin with WasmEdge**: Load and execute the plugin using the WasmEdge runtime, and ensure it works as expected. To test the plugin with WasmEdge, you can use the following command: - - ```bash - wasmedge --dir=./build myplugin.so - ``` - -- **Debug any issues**: To launch a debugger for a WasmEdge binary file, run the following command: - - ```bash - wasmedge debug my-plugin.wasm - ``` - -This will launch a debugger for the WasmEdge binary file, and allow you to step through the code and inspect the values of variables. - -Finally, compile the WasmEdge plugin. diff --git a/docs/contribute/plugin/Develop Plugin in CPP/_category_.json b/docs/contribute/plugin/Develop Plugin in CPP/_category_.json deleted file mode 100644 index 9a7e427e2..000000000 --- a/docs/contribute/plugin/Develop Plugin in CPP/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "WasmEdge Plugin in C++", - "position": 3, - "link": { - "type": "generated-index", - "description": "We will learn how to develop the WasmEdge Plugin System in C++ Language." - } -} diff --git a/docs/contribute/plugin/Develop Plugin in CPP/plugin_development.md b/docs/contribute/plugin/Develop Plugin in CPP/plugin_development.md deleted file mode 100644 index 0875b2e4d..000000000 --- a/docs/contribute/plugin/Develop Plugin in CPP/plugin_development.md +++ /dev/null @@ -1,291 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Develop WasmEdge Plug-in in C++ API - -By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's own building and releasing process. - -> It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plugin development because of the support, compatibility and flexibility provided by the WasmEdge runtime. - -Here is a flowchart showing all the steps needed for developing WasmEdge Plugin - - -```mermaid -graph TD; -B[Developing WasmEdge Plugin in C++] -B --> E(Set up development environment) -E --> F(Create project directory) -E --> G(Add configuration files) -E --> H(Install necessary tools and dependencies) -E --> I(Enable specific backends or components) -E --> J(Write plugin code) -E --> K(Build plugin) -F --> L(Define plugin API) -K --> L -L --> M(Compile WasmEdge plugin) -M --> N(Test and debug plugin) - -``` - -This flowchart illustrates the process of developing a WasmEdge plugin, showcasing the steps involved from choosing a programming language to finalizing and releasing the plugin. - -> For existing plugins, please refer to their respective [documentation pages](/contribute/source/plugin) for specific instructions. - -## Set up the development environment - -To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - - -- **Build WasmEdge from source**- For developing WasmEdge plugin in C++ language, you will need to build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. - -- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your own plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. - - To see a list of supported plugins and their specific install commands, see the [Install WasmEdge plugins and dependencies](develop/build-and-run/install/#install-wasmedge-plugins-and-dependencies) section. - -- **Install a compatible compiler**: The following compilers can be used to compile C++ code into WebAssembly bytecode: - - - LLVM: `sudo apt-get install llvm` - - GCC: `sudo apt-get install gcc` - -- **Install necessary tools and dependencies**: You can use any text editor or IDE of your choice to write code. Here are some popular options: - - - [Visual Studio Code](https://code.visualstudio.com/) - - [Atom](https://atom.io/) - - [Sublime Text](https://www.sublimetext.com/) - - For debugging, you can use GDB, LLDB, or other debuggers that support WebAssembly. To install GDB, run `sudo apt-get install gdb`. - -- **Enable specific backends or additional components (if applicable):** Some plugins may require enabling specific backends or additional components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: - - - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) - - [TensorFlow Lite](../../build-and-run/install#wasi-nn-plugin-with-tensorflow-lite) - - [PyTorch 1.8.2 LTS](https://pytorch.org/get-started/locally/) - -By following these steps, you can set up the development environment for creating WasmEdge plugins effectively. This will allow you to develop, test, and debug your plugins in a Linux environment. - -## Create a WasmEdge plugin project - -To create a WasmEdge plugin project, follow these steps: - -- **Set up the project directory**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your own structure. To create a project directory structure, use the following commands: - - ```bash - mkdir myplugin - cd myplugin - mkdir src include build - ``` - -- **Add configuration files**: Add configuration files specifying the plugin name, version, and dependencies. The specific files and their content depend on the chosen programming language and build system. - - Create a `CMakeLists.txt` file in the root directory with the necessary configuration to specify the plugin name, version, and dependencies. The `find_package(WasmEdge REQUIRED)` line locates the WasmEdge runtime library and makes it available for the project. - - ```cmake - cmake_minimum_required(VERSION 3.14) - project(myplugin VERSION 0.1.0) - - find_package(WasmEdge REQUIRED) - - add_library(myplugin SHARED src/myplugin.cpp) - target_compile_features(myplugin PUBLIC cxx_std_11) - target_include_directories(myplugin PUBLIC include) - target_link_libraries(myplugin PRIVATE ${WASMEDGE_LIBRARIES}) - set_target_properties(myplugin PROPERTIES PREFIX "") - ``` - -- **Add any necessary libraries or dependencies**: Include any required libraries or dependencies for your plugin. Modify the configuration files created in the previous step to include the necessary dependencies. For example, in the `CMakeLists.txt` file, use the `find_package` command to locate the WasmEdge runtime library and link it to your plugin. - -## Write the plugin code - -To create a plug-in with host functions and modules, follow these steps: - -- **Implement host function definitions**: In this step, you need to define the host functions that will be imported when instantiating the WASM module. These functions will perform specific operations and return results. - - Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers respectively: - - ```c - #include - - /* The host function definitions. */ - - /* The host function to add 2 int32_t numbers. */ - WasmEdge_Result HostFuncAdd(void *Data, - const WasmEdge_CallingFrameContext *CallFrameCxt, - const WasmEdge_Value *In, WasmEdge_Value *Out) { - int32_t Val1 = WasmEdge_ValueGetI32(In[0]); - int32_t Val2 = WasmEdge_ValueGetI32(In[1]); - Out[0] = WasmEdge_ValueGenI32(Val1 + Val2); - return WasmEdge_Result_Success; - } - - /* The host function to sub 2 int32_t numbers. */ - WasmEdge_Result HostFuncSub(void *Data, - const WasmEdge_CallingFrameContext *CallFrameCxt, - const WasmEdge_Value *In, WasmEdge_Value *Out) { - int32_t Val1 = WasmEdge_ValueGetI32(In[0]); - int32_t Val2 = WasmEdge_ValueGetI32(In[1]); - Out[0] = WasmEdge_ValueGenI32(Val1 - Val2); - return WasmEdge_Result_Success; - } - ``` - -- **Implement the module creation functions**: In this step, you need to implement the module creation function that creates an instance of the module. This function will be called when the plugin is loaded. - - Here's an example of a module creation function named `CreateTestModule`: - - ```c - /* The creation function of creating the module instance. */ - 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 the description from this descriptor. - */ - - /* Exported module name of this module instance. */ - WasmEdge_String ModuleName = - WasmEdge_StringCreateByCString("wasmedge_plugintest_c_module"); - WasmEdge_ModuleInstanceContext *Mod = - WasmEdge_ModuleInstanceCreate(ModuleName); - WasmEdge_StringDelete(ModuleName); - - 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; - - /* Create and add the host function instances into the module instance. */ - FType = WasmEdge_FunctionTypeCreate(ParamTypes, 2, ReturnTypes, 1); - FuncName = WasmEdge_StringCreateByCString("add"); - FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncAdd, NULL, 0); - WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); - WasmEdge_StringDelete(FuncName); - FuncName = WasmEdge_StringCreateByCString("sub"); - FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncSub, NULL, 0); - WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); - WasmEdge_StringDelete(FuncName); - WasmEdge_FunctionTypeDelete(FType); - - return Mod; - } - ``` - - There can be several module instances in a plug-in shared library. Here in above code snippet take a module named as `wasmedge_plugintest_c_module` for the example. - -- **Supply the plugin descriptions**- In this step, you need to provide the descriptions of the plugin and the modules it contains. These descriptions will be used for searching and creating the plugin and module instances. - - Here's an example of the plugin and module descriptors: - - ```c - /* 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. - */ - .Name = "wasmedge_plugintest_c_module", - /* Module description. */ - .Description = "This is for the plugin tests in WasmEdge C API.", - /* Creation function pointer. */ - .Create = CreateTestModule, - }}; - - /* 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. - */ - .Name = "wasmedge_plugintest_c", - /* Plug-in description. */ - .Description = "", - /* Plug-in API version. */ - .APIVersion = WasmEdge_Plugin_CurrentAPIVersion, - /* Plug-in version. Developers can define the version of this plug-in. */ - .Version = - { - .Major = 0, - .Minor = 1, - .Patch = 0, - .Build = 0, - }, - /* Module count in this plug-in. */ - .ModuleCount = 1, - /* Plug-in option description count in this plug-in (Work in progress). */ - .ProgramOptionCount = 0, - /* Pointer to the module description array. */ - .ModuleDescriptions = ModuleDesc, - /* Pointer to the plug-in option description array (Work in progress). */ - .ProgramOptions = NULL, - }}; - ``` - - These descriptions define the name, description, version, and creation function of the plugin, as well as the name and description of the module it contains. - -Remember to implement any additional functions or structures that your plugin requires to fulfill its functionality. - -By following these steps and implementing the necessary functions and descriptors, you can create a plug-in with host functions and modules in WasmEdge C API. You can continue developing your plugin by adding functionality and implementing the desired behavior. - -## Build your plugin - -To build the WasmEdge plug-in shared library, you have two options: building it directly using the compiler or using CMake. Here are the instructions for both methods: - -- **Build with Command**: if you choose to build the plug-in using the command line, run the following command in terminal: - - This command compiles the `myplugin.c` file into a shared library named `libwasmedgePluginTest.so`. The `-std=c11` flag sets the C language standard to C11, and the `-DWASMEDGE_PLUGIN` flag defines the WASMEDGE_PLUGIN macro, which can be used in your code. - -- **Build with CMake**: If you prefer to use CMake to build the plug-in, create a `CMakeLists.txt` file in the root directory of your project and add the following content to the CMakeLists.txt file: - - ```cmake - add_library(wasmedgePluginTest - SHARED - myplugin.c - ) - - set_target_properties(wasmedgePluginTest PROPERTIES - C_STANDARD 11 - ) - - target_compile_options(wasmedgePluginTest - PUBLIC - -DWASMEDGE_PLUGIN - ) - - target_link_libraries(wasmedgePluginTest - PRIVATE - wasmedge - ) - ``` - - This CMake configuration sets up a build target called `wasmedgePluginTest`. It compiles the `myplugin.c` file into a shared library. The `C_STANDARD 11` property sets the C language standard to C11. The `target_compile_options` command defines the `WASMEDGE_PLUGIN` macro using the `-DWASMEDGE_PLUGIN` flag. Finally, the `target_link_libraries` command links the wasmedge library to the plug-in. - -Once you have set up either the command-line build or the CMake build, you can execute the corresponding build command or generate build files using CMake. This will compile your plug-in source code and produce the shared library file `(libwasmedgePluginTest.so)`. - -## Test and debug the plugin - -Once you have compiled the plugin, you can test it using the following steps: - -- **Test the plugin with WasmEdge**: Load and execute the plugin using the WasmEdge runtime, and ensure it works as expected. To test the plugin with WasmEdge, you can use the following command: - - ```bash - wasmedge --dir=./build myplugin.so - ``` - -- **Debug any issues**: To launch a debugger for a WasmEdge binary file, run the following command: - - ```bash - wasmedge debug my-plugin.wasm - ``` - -This will launch a debugger for the WasmEdge binary file, and allow you to step through the code and inspect the values of variables. - -Finally, compile the WasmEdge plugin. diff --git a/docs/contribute/plugin/Develop Plugin in Rust/_category_.json b/docs/contribute/plugin/Develop Plugin in Rust/_category_.json deleted file mode 100644 index f464cdef4..000000000 --- a/docs/contribute/plugin/Develop Plugin in Rust/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "WasmEdge Plugin in Rust", - "position": 3, - "link": { - "type": "generated-index", - "description": "We will learn how to develop the WasmEdge Plugin System in Rust Language." - } -} diff --git a/docs/contribute/plugin/Develop Plugin in Rust/plugin_development.md b/docs/contribute/plugin/Develop Plugin in Rust/plugin_development.md deleted file mode 100644 index cd6eb573d..000000000 --- a/docs/contribute/plugin/Develop Plugin in Rust/plugin_development.md +++ /dev/null @@ -1,292 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Develop WasmEdge Plug-in in C API - -By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's own building and releasing process. -Here is a flowchart showing all the steps needed for developing WasmEdge Plugin - - -```mermaid -graph TD; -B[Developing WasmEdge Plugin in C] -B --> E(Set up development environment) -E --> F(Create project directory) -E --> G(Add configuration files) -E --> H(Install necessary tools and dependencies) -E --> I(Enable specific backends or components) -E --> J(Write plugin code) -E --> K(Build plugin) -F --> L(Define plugin API) -K --> L -L --> M(Compile WasmEdge plugin) -M --> N(Test and debug plugin) - -``` - -This flowchart illustrates the process of developing a WasmEdge plugin, showcasing the steps involved from choosing a programming language to finalizing and releasing the plugin. - -> For existing plugins, please refer to their respective [documentation pages](/contribute/source/plugin) for specific instructions. - -## Set up the development environment - -To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - - -- **Install a WasmEdge runtime**: You can download the latest version of WasmEdge from [GitHub repository](https://github.com/wasmEdge/wasmEdge). Here are the installation instructions for different operating system for [installing WasmEdge](/develop/build-and-run/install.md). - -- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your own plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. - - To see a list of supported plugins and their specific install commands, see the [Install WasmEdge plugins and dependencies](develop/build-and-run/install/#install-wasmedge-plugins-and-dependencies) section. - -- **Install a compatible compiler**: The following compilers can be used to compile C code into WebAssembly bytecode: - - - LLVM: `sudo apt-get install llvm` - - GCC: `sudo apt-get install gcc` - -- **Install necessary tools and dependencies**: You can use any text editor or IDE of your choice to write code. Here are some popular options: - - - [Visual Studio Code](https://code.visualstudio.com/) - - [Atom](https://atom.io/) - - [Sublime Text](https://www.sublimetext.com/) - - For debugging, you can use GDB, LLDB, or other debuggers that support WebAssembly. To install GDB, run `sudo apt-get install gdb`. - -- **Enable specific backends or additional components (if applicable):** Some plugins may require enabling specific backends or additional components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: - - - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) - - [TensorFlow Lite](../../build-and-run/install#wasi-nn-plugin-with-tensorflow-lite) - - [PyTorch 1.8.2 LTS](https://pytorch.org/get-started/locally/) - -By following these steps, you can set up the development environment for creating WasmEdge plugins effectively. This will allow you to develop, test, and debug your plugins in a Linux environment. - -## Create a WasmEdge plugin project - -To create a WasmEdge plugin project, follow these steps: - -- **Set up the project directory**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your own structure. To create a project directory structure, use the following commands: - - ```bash - mkdir myplugin - cd myplugin - mkdir src include build - ``` - -- **Add configuration files**: Add configuration files specifying the plugin name, version, and dependencies. The specific files and their content depend on the chosen programming language and build system. - - Create a `CMakeLists.txt` file in the root directory with the necessary configuration to specify the plugin name, version, and dependencies. The `find_package(WasmEdge REQUIRED)` line locates the WasmEdge runtime library and makes it available for the project. - - ```cmake - cmake_minimum_required(VERSION 3.14) - project(myplugin VERSION 0.1.0) - - find_package(WasmEdge REQUIRED) - - add_library(myplugin SHARED src/myplugin.cpp) - target_compile_features(myplugin PUBLIC cxx_std_11) - target_include_directories(myplugin PUBLIC include) - target_link_libraries(myplugin PRIVATE ${WASMEDGE_LIBRARIES}) - set_target_properties(myplugin PROPERTIES PREFIX "") - ``` - -- **Add any necessary libraries or dependencies**: Include any required libraries or dependencies for your plugin. Modify the configuration files created in the previous step to include the necessary dependencies. For example, in the `CMakeLists.txt` file, use the `find_package` command to locate the WasmEdge runtime library and link it to your plugin. - -## Write the plugin code - -To create a plug-in with host functions and modules, follow these steps: - -- **Implement host function definitions**: In this step, you need to define the host functions that will be imported when instantiating the WASM module. These functions will perform specific operations and return results. - - Therefore, developers can implement their plug-in host functions first, as the same as the [host functions in WasmEdge C API](/embed/c/reference/0.12.0.md#host-functions). - -> For the more details about the [external data](/embed/c/host_function.md#host-data) and [calling frame context](/embed/c/host_function.md#calling-frame-context), please refer to the host function guide. - - Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers respectively: - - ```c - #include - - /* The host function definitions. */ - - /* The host function to add 2 int32_t numbers. */ - WasmEdge_Result HostFuncAdd(void *Data, - const WasmEdge_CallingFrameContext *CallFrameCxt, - const WasmEdge_Value *In, WasmEdge_Value *Out) { - int32_t Val1 = WasmEdge_ValueGetI32(In[0]); - int32_t Val2 = WasmEdge_ValueGetI32(In[1]); - Out[0] = WasmEdge_ValueGenI32(Val1 + Val2); - return WasmEdge_Result_Success; - } - - /* The host function to sub 2 int32_t numbers. */ - WasmEdge_Result HostFuncSub(void *Data, - const WasmEdge_CallingFrameContext *CallFrameCxt, - const WasmEdge_Value *In, WasmEdge_Value *Out) { - int32_t Val1 = WasmEdge_ValueGetI32(In[0]); - int32_t Val2 = WasmEdge_ValueGetI32(In[1]); - Out[0] = WasmEdge_ValueGenI32(Val1 - Val2); - return WasmEdge_Result_Success; - } - ``` - -- **Implement the module creation functions**: In this step, you need to implement the module creation function that creates an instance of the module. This function will be called when the plugin is loaded. - - Here's an example of a module creation function named `CreateTestModule`: - - ```c - /* The creation function of creating the module instance. */ - 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 the description from this descriptor. - */ - - /* Exported module name of this module instance. */ - WasmEdge_String ModuleName = - WasmEdge_StringCreateByCString("wasmedge_plugintest_c_module"); - WasmEdge_ModuleInstanceContext *Mod = - WasmEdge_ModuleInstanceCreate(ModuleName); - WasmEdge_StringDelete(ModuleName); - - 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; - - /* Create and add the host function instances into the module instance. */ - FType = WasmEdge_FunctionTypeCreate(ParamTypes, 2, ReturnTypes, 1); - FuncName = WasmEdge_StringCreateByCString("add"); - FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncAdd, NULL, 0); - WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); - WasmEdge_StringDelete(FuncName); - FuncName = WasmEdge_StringCreateByCString("sub"); - FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncSub, NULL, 0); - WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); - WasmEdge_StringDelete(FuncName); - WasmEdge_FunctionTypeDelete(FType); - - return Mod; - } - ``` - - There can be several module instances in a plug-in shared library. Here in above code snippet take a module named as `wasmedge_plugintest_c_module` for the example. - -- **Supply the plugin descriptions**- In this step, you need to provide the descriptions of the plugin and the modules it contains. These descriptions will be used for searching and creating the plugin and module instances. - - Here's an example of the plugin and module descriptors: - - ```c - /* 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. - */ - .Name = "wasmedge_plugintest_c_module", - /* Module description. */ - .Description = "This is for the plugin tests in WasmEdge C API.", - /* Creation function pointer. */ - .Create = CreateTestModule, - }}; - - /* 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. - */ - .Name = "wasmedge_plugintest_c", - /* Plug-in description. */ - .Description = "", - /* Plug-in API version. */ - .APIVersion = WasmEdge_Plugin_CurrentAPIVersion, - /* Plug-in version. Developers can define the version of this plug-in. */ - .Version = - { - .Major = 0, - .Minor = 1, - .Patch = 0, - .Build = 0, - }, - /* Module count in this plug-in. */ - .ModuleCount = 1, - /* Plug-in option description count in this plug-in (Work in progress). */ - .ProgramOptionCount = 0, - /* Pointer to the module description array. */ - .ModuleDescriptions = ModuleDesc, - /* Pointer to the plug-in option description array (Work in progress). */ - .ProgramOptions = NULL, - }}; - ``` - - These descriptions define the name, description, version, and creation function of the plugin, as well as the name and description of the module it contains. - -Remember to implement any additional functions or structures that your plugin requires to fulfill its functionality. - -By following these steps and implementing the necessary functions and descriptors, you can create a plug-in with host functions and modules in WasmEdge C API. You can continue developing your plugin by adding functionality and implementing the desired behavior. - -## Build your plugin - -To build the WasmEdge plug-in shared library, you have two options: building it directly using the compiler or using CMake. Here are the instructions for both methods: - -- **Build with Command**: if you choose to build the plug-in using the command line, run the following command in terminal: - - This command compiles the `myplugin.c` file into a shared library named `libwasmedgePluginTest.so`. The `-std=c11` flag sets the C language standard to C11, and the `-DWASMEDGE_PLUGIN` flag defines the WASMEDGE_PLUGIN macro, which can be used in your code. - -- **Build with CMake**: If you prefer to use CMake to build the plug-in, create a `CMakeLists.txt` file in the root directory of your project and add the following content to the CMakeLists.txt file: - - ```cmake - add_library(wasmedgePluginTest - SHARED - myplugin.c - ) - - set_target_properties(wasmedgePluginTest PROPERTIES - C_STANDARD 11 - ) - - target_compile_options(wasmedgePluginTest - PUBLIC - -DWASMEDGE_PLUGIN - ) - - target_link_libraries(wasmedgePluginTest - PRIVATE - wasmedge - ) - ``` - - This CMake configuration sets up a build target called `wasmedgePluginTest`. It compiles the `myplugin.c` file into a shared library. The `C_STANDARD 11` property sets the C language standard to C11. The `target_compile_options` command defines the `WASMEDGE_PLUGIN` macro using the `-DWASMEDGE_PLUGIN` flag. Finally, the `target_link_libraries` command links the wasmedge library to the plug-in. - -Once you have set up either the command-line build or the CMake build, you can execute the corresponding build command or generate build files using CMake. This will compile your plug-in source code and produce the shared library file `(libwasmedgePluginTest.so)`. - -## Test and debug the plugin - -Once you have compiled the plugin, you can test it using the following steps: - -- **Test the plugin with WasmEdge**: Load and execute the plugin using the WasmEdge runtime, and ensure it works as expected. To test the plugin with WasmEdge, you can use the following command: - - ```bash - wasmedge --dir=./build myplugin.so - ``` - -- **Debug any issues**: To launch a debugger for a WasmEdge binary file, run the following command: - - ```bash - wasmedge debug my-plugin.wasm - ``` - -This will launch a debugger for the WasmEdge binary file, and allow you to step through the code and inspect the values of variables. - -Finally, compile the WasmEdge plugin. diff --git a/docs/contribute/plugin/_category_.json b/docs/contribute/plugin/_category_.json index f78ce6216..996f1807c 100644 --- a/docs/contribute/plugin/_category_.json +++ b/docs/contribute/plugin/_category_.json @@ -1,8 +1,8 @@ { - "label": "WasmEdge Plugin System", - "position": 3, - "link": { - "type": "generated-index", - "description": "we will learn how to develop the WasmEdge Plugin System." - } -} \ No newline at end of file + "label": "WasmEdge Plugin System", + "position": 3, + "link": { + "type": "generated-index", + "description": "we will learn how to develop the WasmEdge Plugin System." + } +} diff --git a/docs/contribute/plugin/develop_plugin_c.md b/docs/contribute/plugin/develop_plugin_c.md index 8783e4076..4b8fb0b5d 100644 --- a/docs/contribute/plugin/develop_plugin_c.md +++ b/docs/contribute/plugin/develop_plugin_c.md @@ -4,27 +4,84 @@ sidebar_position: 2 # Develop WasmEdge Plug-in in C API -WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's own building and releasing process. +By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's own building and releasing process. Here is a flowchart showing all the steps needed for developing WasmEdge Plugin - + +```mermaid +graph LR; +A[Developing WasmEdge Plugin in C] +A --> B(Set up the development environment) +A --> C(Create a WasmEdge plugin project) +A --> D(Write the plugin code) +A --> E(Build the plugin) +A --> F(Test and debug the plugin) +B --> E +C --> D +D --> E +``` + +This flowchart illustrates the process of developing a WasmEdge plugin, showcasing the steps involved from choosing a programming language to finalizing and releasing the plugin. + +## Set up the development environment + +To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - + +- **Install a WasmEdge runtime**: You can download the latest version of WasmEdge from [GitHub repository](https://github.com/wasmEdge/wasmEdge). Here are the installation instructions for different operating system for [installing WasmEdge](/develop/build-and-run/install.md). +- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your own plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. + + To see a list of supported plugins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plugins and dependencies section. + +- **Install a compatible compiler**: The following compilers can be used to compile C code into WebAssembly bytecode: + + - LLVM: `sudo apt-get install llvm` + - GCC: `sudo apt-get install gcc` + +- **Install necessary tools and dependencies**: You can use any text editor or IDE of your choice to write code. Here are some popular options: + + - [Visual Studio Code](https://code.visualstudio.com/) + - [Atom](https://atom.io/) + - [Sublime Text](https://www.sublimetext.com/) + + For debugging, you can use GDB, LLDB, or other debuggers that support WebAssembly. To install GDB, run `sudo apt-get install gdb`. + +- **Enable specific backends or additional components (if applicable):** Some plugins may require enabling specific backends or additional components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: -## Prerequisites + - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) + - [TensorFlow Lite](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-tensorflow-lite-backend) + - [PyTorch 1.8.2 LTS](https://pytorch.org/get-started/locally/) -For developing the WasmEdge plug-in in C API, please [install WasmEdge](/develop/build-and-run/install.md) first. +By following these steps, you can set up the development environment for creating WasmEdge plugins effectively. This will allow you to develop, test, and debug your plugins in a Linux environment. -## Example +## Create a WasmEdge plugin project -Assume that the plug-in example is in the file `testplugin.c`. +To create a WasmEdge plugin project, follow these steps: -### Host Functions +- **Set up the project directory**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your own structure. To create a project directory structure, use the following commands: -The goal of the plug-in is to provide the host functions which can be imported when instantiating WASM. + ```bash + mkdir testplugin + cd testplugin + mkdir src include build + ``` -Therefore, developers can implement their plug-in host functions first, as the same as the [host functions in WasmEdge C API](/embed/c/reference/latest.md#host-functions). +- **Add configuration files**: Add configuration files specifying the plugin name, version, and dependencies. The specific files and their content depend on the chosen programming language and build system. + +- **Add any necessary libraries or dependencies**: Include any required libraries or dependencies for your plugin. Modify the configuration files created in the previous step to include the necessary dependencies. + +## Write the plugin code + +To create a plug-in with host functions and modules, follow these steps: + +- **Implement host function definitions**: In this step, you need to define the host functions that will be imported when instantiating the WASM module. These functions will perform specific operations and return results. + + Therefore, developers can implement their plug-in host functions first, as the same as the [host functions in WasmEdge C API](/embed/c/reference/latest.md#host-functions). :::note For the more details about the [external data](/embed/c/host_function.md#host-data) and [calling frame context](/embed/c/host_function.md#calling-frame-context), please refer to the host function guide. ::: +Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers respectively: + ```c #include @@ -51,152 +108,147 @@ WasmEdge_Result HostFuncSub(void *Data, } ``` -### Host Modules - -Then developers should implement the module creation functions. - -Noticed that there can be several module instances in a plug-in shared library. Here take a module named as `wasmedge_plugintest_c_module` for the example. - -```c -/* The creation function of creating the module instance. */ -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 the description from this descriptor. - */ - - /* Exported module name of this module instance. */ - WasmEdge_String ModuleName = - WasmEdge_StringCreateByCString("wasmedge_plugintest_c_module"); - WasmEdge_ModuleInstanceContext *Mod = - WasmEdge_ModuleInstanceCreate(ModuleName); - WasmEdge_StringDelete(ModuleName); - - 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; - - /* Create and add the host function instances into the module instance. */ - FType = WasmEdge_FunctionTypeCreate(ParamTypes, 2, ReturnTypes, 1); - FuncName = WasmEdge_StringCreateByCString("add"); - FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncAdd, NULL, 0); - WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); - WasmEdge_StringDelete(FuncName); - FuncName = WasmEdge_StringCreateByCString("sub"); - FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncSub, NULL, 0); - WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); - WasmEdge_StringDelete(FuncName); - WasmEdge_FunctionTypeDelete(FType); - - return Mod; -} -``` +- **Implement the module creation functions**: In this step, you need to implement the module creation function that creates an instance of the module. This function will be called when the plugin is loaded. -### Plug-in Descriptions + Here's an example of a module creation function named `CreateTestModule`: -For constructing the plug-in, developers should supply the descriptions of this plug-in and the modules. - -```c -/* 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. - */ - .Name = "wasmedge_plugintest_c_module", - /* Module description. */ - .Description = "This is for the plugin tests in WasmEdge C API.", - /* Creation function pointer. */ - .Create = CreateTestModule, -}}; - -/* The plug-in descriptor */ -static WasmEdge_PluginDescriptor Desc[] = {{ + ```c + /* The creation function of creating the module instance. */ + WasmEdge_ModuleInstanceContext * + CreateTestModule(const struct WasmEdge_ModuleDescriptor *Desc) { /* - * 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 = "", - /* Plug-in API version. */ - .APIVersion = WasmEdge_Plugin_CurrentAPIVersion, - /* Plug-in version. Developers can define the version of this plug-in. */ - .Version = - { - .Major = 0, - .Minor = 1, - .Patch = 0, - .Build = 0, - }, - /* Module count in this plug-in. */ - .ModuleCount = 1, - /* Plug-in option description count in this plug-in (Work in progress). */ - .ProgramOptionCount = 0, - /* Pointer to the module description array. */ - .ModuleDescriptions = ModuleDesc, - /* Pointer to the plug-in option description array (Work in progress). */ - .ProgramOptions = NULL, -}}; -``` - -### Plug-in Options - -WORK IN PROGRESS. This section is reserved for the feature in the future. - -### Implement the Get Descriptor API - -The final step is to implement the `WasmEdge_Plugin_GetDescriptor()` API to return the plug-in descriptor. - -```c -WASMEDGE_CAPI_PLUGIN_EXPORT const WasmEdge_PluginDescriptor * -WasmEdge_Plugin_GetDescriptor(void) { - return &Desc; -} -``` - -## Build - -To build the plug-in shared library, developers can choose to build stand-alone by the compiler or use cmake. - -### Build with Command - -```bash -clang -shared -std=c11 -DWASMEDGE_PLUGIN testplugin.c -lwasmedge -o libwasmedgePluginTest.so -``` - -### Build in CMake - -```cmake -add_library(wasmedgePluginTest - SHARED - testplugin.c -) - -set_target_properties(wasmedgePluginTest PROPERTIES - C_STANDARD 11 -) - -target_compile_options(wasmedgePluginTest - PUBLIC - -DWASMEDGE_PLUGIN -) - -target_link_libraries(wasmedgePluginTest - PRIVATE - wasmedge -) -``` + * 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 the description from this descriptor. + */ + + /* Exported module name of this module instance. */ + WasmEdge_String ModuleName = + WasmEdge_StringCreateByCString("wasmedge_plugintest_c_module"); + WasmEdge_ModuleInstanceContext *Mod = + WasmEdge_ModuleInstanceCreate(ModuleName); + WasmEdge_StringDelete(ModuleName); + + 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; + + /* Create and add the host function instances into the module instance. */ + FType = WasmEdge_FunctionTypeCreate(ParamTypes, 2, ReturnTypes, 1); + FuncName = WasmEdge_StringCreateByCString("add"); + FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncAdd, NULL, 0); + WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); + WasmEdge_StringDelete(FuncName); + FuncName = WasmEdge_StringCreateByCString("sub"); + FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncSub, NULL, 0); + WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); + WasmEdge_StringDelete(FuncName); + WasmEdge_FunctionTypeDelete(FType); + + return Mod; + } + ``` + + There can be several module instances in a plug-in shared library. Here in above code snippet take a module named as `wasmedge_plugintest_c_module` for the example. + +- **Supply the plugin descriptions**- In this step, you need to provide the descriptions of the plugin and the modules it contains. These descriptions will be used for searching and creating the plugin and module instances. + + Here's an example of the plugin and module descriptors: + + ```c + /* 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. + */ + .Name = "wasmedge_plugintest_c_module", + /* Module description. */ + .Description = "This is for the plugin tests in WasmEdge C API.", + /* Creation function pointer. */ + .Create = CreateTestModule, + }}; + + /* 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. + */ + .Name = "wasmedge_plugintest_c", + /* Plug-in description. */ + .Description = "", + /* Plug-in API version. */ + .APIVersion = WasmEdge_Plugin_CurrentAPIVersion, + /* Plug-in version. Developers can define the version of this plug-in. */ + .Version = + { + .Major = 0, + .Minor = 1, + .Patch = 0, + .Build = 0, + }, + /* Module count in this plug-in. */ + .ModuleCount = 1, + /* Plug-in option description count in this plug-in (Work in progress). */ + .ProgramOptionCount = 0, + /* Pointer to the module description array. */ + .ModuleDescriptions = ModuleDesc, + /* Pointer to the plug-in option description array (Work in progress). */ + .ProgramOptions = NULL, + }}; + ``` + + These descriptions define the name, description, version, and creation function of the plugin, as well as the name and description of the module it contains. + +Remember to implement any additional functions or structures that your plugin requires to fulfill its functionality. + +By following these steps and implementing the necessary functions and descriptors, you can create a plug-in with host functions and modules in WasmEdge C API. You can continue developing your plugin by adding functionality and implementing the desired behavior. + +- **Plugin option** - _WORK IN PROGRESS. This section is reserved for the feature in the future._ + +## Build your plugin + +To build the WasmEdge plug-in shared library, you have two options: building it directly using the compiler or using CMake. Here are the instructions for both methods: + +- **Build with Command**: if you choose to build the plug-in using the command line, run the following command in terminal: + + This command compiles the `testplugin.c` file into a shared library named `libwasmedgePluginTest.so`. The `-std=c11` flag sets the C language standard to C11, and the `-DWASMEDGE_PLUGIN` flag defines the WASMEDGE_PLUGIN macro, which can be used in your code. + +- **Build with CMake**: If you prefer to use CMake to build the plug-in, create a `CMakeLists.txt` file in the root directory of your project and add the following content to the CMakeLists.txt file: + + ```cmake + add_library(wasmedgePluginTest + SHARED + testplugin.c + ) + + set_target_properties(wasmedgePluginTest PROPERTIES + C_STANDARD 11 + ) + + target_compile_options(wasmedgePluginTest + PUBLIC + -DWASMEDGE_PLUGIN + ) + + target_link_libraries(wasmedgePluginTest + PRIVATE + wasmedge + ) + ``` + + This CMake configuration sets up a build target called `wasmedgePluginTest`. It compiles the `testplugin.c` file into a shared library. The `C_STANDARD 11` property sets the C language standard to C11. The `target_compile_options` command defines the `WASMEDGE_PLUGIN` macro using the `-DWASMEDGE_PLUGIN` flag. Finally, the `target_link_libraries` command links the wasmedge library to the plug-in. + +Once you have set up either the command-line build or the CMake build, you can execute the corresponding build command or generate build files using CMake. This will compile your plug-in source code and produce the shared library file `(libwasmedgePluginTest.so)`. diff --git a/docs/contribute/plugin/develop_plugin_cpp.md b/docs/contribute/plugin/develop_plugin_cpp.md index a4a639194..905c6f66c 100644 --- a/docs/contribute/plugin/develop_plugin_cpp.md +++ b/docs/contribute/plugin/develop_plugin_cpp.md @@ -4,22 +4,99 @@ sidebar_position: 3 # Develop WasmEdge Plug-in in C++ API +By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's own building and releasing process. + :::note -We recommend developers to [develop plug-ins in WasmEdge C API](develop_plugin_c.md). +It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plugin development because of the support, compatibility and flexibility provided by the WasmEdge runtime. ::: -## Prerequisites +Here is a flowchart showing all the steps needed for developing WasmEdge Plugin - + +```mermaid +graph TD; +A[Develop WasmEdge Plugin in C++ API] +A --> B(Set up development environment) +B --> C(Create project directory) +C --> D(Add configuration files) +D --> E(Install necessary tools and dependencies) +E --> F(Enable specific backends or components) +F --> G(Write plugin code) +G --> H(Build plugin) +C --> I(Define plugin API) +H --> I +I --> J(Compile WasmEdge plugin) +J --> K(Test and debug plugin) +``` + +This flowchart illustrates the process of developing a WasmEdge plugin, showcasing the steps involved from choosing a programming language to finalizing and releasing the plugin. + +## Set up development environment + +To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - + +- **Build WasmEdge from source**: For developing WasmEdge plugin in C++ language, you will need to build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. +- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your own plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. + + To see a list of supported plugins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plugins and dependencies section. + +- **Install a compatible compiler**: The following compilers can be used to compile C++ code into WebAssembly bytecode: + + - LLVM: `sudo apt-get install llvm` + - GCC: `sudo apt-get install gcc` + +- **Install necessary tools and dependencies**: You can use any text editor or IDE of your choice to write code. Here are some popular options: + + - [Visual Studio Code](https://code.visualstudio.com/) + - [Atom](https://atom.io/) + - [Sublime Text](https://www.sublimetext.com/) + + For debugging, you can use GDB, LLDB, or other debuggers that support WebAssembly. To install GDB, run `sudo apt-get install gdb`. + +- **Enable specific backends or additional components (if applicable):** Some plugins may require enabling specific backends or additional components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: + + - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) + - [TensorFlow Lite](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-tensorflow-lite-backend) + - [PyTorch 1.8.2 LTS](https://pytorch.org/get-started/locally/) + +By following these steps, you can set up the development environment for creating WasmEdge plugins effectively. This will allow you to develop, test, and debug your plugins in a Linux environment. -For developing the WasmEdge plug-in in internal C++, developers should [build WasmEdge from source](../source/build_from_src.md). +## Create a WasmEdge plug-in project -## Example +To create a WasmEdge plugin project, follow these steps: -Assume that the plug-in example is in the file `testplugin.h` and `testplugin.cpp`. +- **Set up the project directory**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your own structure. To create a project directory structure, use the following commands: -### Host Functions and Modules + ```bash + mkdir testplugin + cd testplugin + mkdir src include build + ``` -The goal of the plug-in is to provide the host functions which can be imported when instantiating WASM. Therefore, developers should implement their plug-in host functions in WasmEdge internal C++ first. Assume that the host function implementations are in the `testplugin.h`. +- **Add configuration files**: Add configuration files specifying the plugin name, version, and dependencies. The specific files and their content depend on the chosen programming language and build system. + + Create a `CMakeLists.txt` file in the root directory with the necessary configuration to specify the plugin name, version, and dependencies. The `find_package(WasmEdge REQUIRED)` line locates the WasmEdge runtime library and makes it available for the project. + + ```cmake + cmake_minimum_required(VERSION 3.14) + project(testplugin VERSION 0.1.0) + + find_package(WasmEdge REQUIRED) + + add_library(testplugin SHARED src/testplugin.cpp) + target_compile_features(testplugin PUBLIC cxx_std_11) + target_include_directories(testplugin PUBLIC include) + target_link_libraries(testplugin PRIVATE ${WASMEDGE_LIBRARIES}) + set_target_properties(testplugin PROPERTIES PREFIX "") + ``` + +- **Add necessary libraries or dependencies**: Include any required libraries or dependencies for your plugin. Modify the configuration files created in the previous step to include the necessary dependencies. For example, in the `CMakeLists.txt` file, use the `find_package` command to locate the WasmEdge runtime library and link it to your plugin. + +## Write plugin code + +To create a plug-in with host functions and modules, follow these steps: + +- **Host Functions and Modules**: The goal of the plug-in is to provide the host functions which can be imported when instantiating WASM. Therefore, developers should implement their plug-in host functions in WasmEdge internal C++ first. Assume that the host function implementations are in the `testplugin.h`. ```cpp #pragma once @@ -93,9 +170,7 @@ private: } // namespace WasmEdge ``` -### Creation Functions for Modules - -Then developers should implement the module creation functions. Assume that the following implementations are all in the `testplugin.cpp`. +- **Creation Functions for Modules**: Then developers should implement the module creation functions. Assume that the following implementations are all in the `testplugin.cpp`. ```cpp #include "testplugin.h" @@ -116,9 +191,7 @@ create(const Plugin::PluginModule::ModuleDescriptor *) noexcept { } // namespace WasmEdge ``` -### Plug-in Descriptions - -For constructing the plug-in, developers should supply the descriptions of this plug-in and the modules. +- **Plug-in Descriptions**: For constructing the plug-in, developers should supply the descriptions of this plug-in and the modules. ```cpp namespace WasmEdge { @@ -161,13 +234,9 @@ Plugin::Plugin::PluginDescriptor Descriptor{ } // namespace WasmEdge ``` -### Plug-in Options - -WORK IN PROGRESS. This section is reserved for the feature in the future. +- **Plug-in Options**: WORK IN PROGRESS. This section is reserved for the feature in the future. -### Implement the Plug-in Descriptor Registration - -The final step is to implement the `Plugin::PluginRegister` initialization with the plug-in descriptor. +- **Implement Plug-in Descriptor Registration**: The final step is to implement the `Plugin::PluginRegister` initialization with the plug-in descriptor. ```cpp namespace WasmEdge { @@ -179,7 +248,11 @@ Plugin::PluginRegister WasmEdgePluginTestEnv::Register(&Descriptor); } // namespace WasmEdge ``` -## Build +Remember to implement any additional functions or structures that your plugin requires to fulfill its functionality. + +By following these steps and implementing the necessary functions and descriptors, you can create a plug-in with host functions and modules in WasmEdge C++ API. You can continue developing your plugin by adding functionality and implementing the desired behavior. + +## Build plugin To build the plug-in shared library, developers should build in cmake with the WasmEdge source. @@ -233,4 +306,4 @@ else() endif() ``` -Then you can [follow the guide to build from source](../source/os/linux.md). +Follow the guide to [build WasmEdge from source](../source/os/linux.md), according to your specific operating system (e.g., Linux). This will include building the plug-in shared library along with WasmEdge. diff --git a/docs/contribute/plugin/develop_plugin_rustsdk.md b/docs/contribute/plugin/develop_plugin_rustsdk.md index 35f27d070..700c98edd 100644 --- a/docs/contribute/plugin/develop_plugin_rustsdk.md +++ b/docs/contribute/plugin/develop_plugin_rustsdk.md @@ -1,10 +1,53 @@ +--- +sidebar_position: 4 +--- + # Develop WasmEdge Plug-in in Rust SDK with witc -Once you complete C++ plugin code, you can use witc[^1] to generate Rust Plugin SDK +By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. WasmEdge provides a Rust based API for registering extension modules and host functions. + + +:::note +It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plugin development because of the support, compatibility and flexibility provided by the WasmEdge runtime. +::: + +## Set up the development environment + +To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - + +- **Build WasmEdge from source**: For developing WasmEdge plugin in C++ language, you will need to build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. Once you complete C++ plugin code, you can use witc[^1] to generate Rust Plugin SDK. +- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your own plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. + + To see a list of supported plugins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plugins and dependencies section. + +- **Install a compatible compiler**: Rust has its own built-in compiler, which can be installed using rustup: + + ```bash + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + source $HOME/.cargo/env + ``` -## Example wasmedge_opencvmini +- **Install necessary tools and dependencies**: You can use any text editor or IDE of your choice to write code. Here are some popular options: -Consider you get a file `wasmedge_opencvmini.wit` with below content + - [Visual Studio Code](https://code.visualstudio.com/) + - [Atom](https://atom.io/) + - [Sublime Text](https://www.sublimetext.com/) + + For debugging, you can use GDB, LLDB, or other debuggers that support WebAssembly. To install GDB, run `sudo apt-get install gdb`. + +- **Enable specific backends or additional components (if applicable):** Some plugins may require enabling specific backends or additional components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: + + - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) + - [TensorFlow Lite](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-tensorflow-lite-backend) + - [PyTorch 1.8.2 LTS](https://pytorch.org/get-started/locally/) + +By following these steps, you can set up the development environment for creating WasmEdge plugins effectively. This will allow you to develop, test, and debug your plugins in a Linux environment. + +## Write the plugin code + +To develop a WasmEdge Plug-in in Rust using the witc tool, you can follow these steps: + +- **Generate Rust Plugin Code**: Consider you have a file named wasmedge_opencvmini.wit with the following content: ```wit imdecode: func(buf: list) -> u32 @@ -12,25 +55,25 @@ imshow: func(window-name: string, mat-key: u32) -> unit waitkey: func(delay: u32) -> unit ``` -Using witc can generate Rust plugin code for it +You can use the witc tool to generate Rust plugin code for it by running the following command: ```shell witc plugin wasmedge_opencvmini.wit ``` -Now, you will create a SDK crate by +- **Create SDK Crate**: Now, you need to create an SDK crate for your plugin. Run the following command to create a new crate named opencvmini-sdk: ```shell cargo new --lib opencvmini-sdk && cd opencvmini-sdk ``` -witc put rust code to stdout, therefore, you might like to create a new module file for generated code +- **Create Module File**: The witc tool puts the Rust code to stdout. To capture the generated code, create a new module file named src/generated.rs and run the following command: ```shell witc plugin wasmedge_opencvmini.wit > src/generated.rs ``` -Finally, you write down `mod generated` in `src/lib.rs` to access the code, and write some wrappers +- **Write Wrapper Functions**: In the `src/lib.rs` file of your crate, write the following code of `mod generated` to access the generated code and create wrapper functions: ```rust mod generated; @@ -46,4 +89,6 @@ pub fn waitkey(delay: u32) -> () { } ``` +This code imports the generated module and provides safe wrapper functions for each generated function. + [^1]: diff --git a/docs/contribute/plugin/intro.md b/docs/contribute/plugin/intro.md index b5ef26365..c6d5f4824 100644 --- a/docs/contribute/plugin/intro.md +++ b/docs/contribute/plugin/intro.md @@ -4,34 +4,99 @@ sidebar_position: 1 # WasmEdge Plug-in System Introduction -While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, developers should implement the host functions before compilation. +While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, developers should implement the host functions before compilation. However, for more flexible and dynamic extension of the host functions, WasmEdge provides a plug-in architecture to load the plug-in shared library. -For the other solutions, WasmEdge provides the plug-in architecture to load the plug-in shared library for easier extending of the host functions. +A WasmEdge plugin is a software component that extends the functionality of the WasmEdge runtime. Currently, developers can follow the guides to implement the plug-ins in [C API](develop_plugin_c.md) (recommended) or [C++](develop_plugin_cpp.md). With the help of the WasmEdge SDKs in the supported languages, developers can load and register the host functions from the plug-in shared libraries, allowing them to seamlessly integrate the plugins into the WasmEdge runtime as if they were part of the core runtime. -With developing the plug-ins, WasmEdge SDKs in the supported languages can load and register the host functions from the plug-in shared libraries. +```mermaid +graph LR + A((Host Application)) -- Loads --> B((Plugin Shared Library)) + B -- Registers --> C((Wasmedge Runtime)) +``` -In current, developers can follow the guides to implement the plug-ins in [C API (recommended)](develop_plugin_c.md) or [C++](develop_plugin_cpp.md). +In this diagram, the _Host Application_ represents the application or environment where the Wasmedge runtime is embedded or used. The _Plugin Shared Library_ refers to the library containing the plugin code and functions that extend the functionality of the Wasmedge runtime. The _Wasmedge Runtime_ represents the runtime environment that executes WebAssembly modules, including the core runtime and any registered plugins. + +## Usages of WasmEdge Plugin + +WasmEdge plugins can be used in various scenarios, such as high-performance domain-specific languages, cloud-native JavaScript runtime, edge computing, serverless, SaaS, service mesh, and blockchain applications. Moreover, WasmEdge plugins can be used in microservices, providing a lightweight, secure, and high-performance runtime compatible with frameworks like Dapr and Kubernetes. + +In addition, WasmEdge plugins can support serverless functions for SaaS applications, allowing users to extend and customize their experience without operating their own API callback servers. They can also be embedded into smart device applications as middleware runtime, rendering interactive content on the UI, connecting to native device drivers, and accessing specialized hardware feature. WasmEdge plugins can be used for managing application state, exchanging dynamic data (e.g., strings and arrays) with Wasm programs, and providing native host functions to manipulate data. + +## Benefits of Using WasmEdge Plugin + +WasmEdge plugins are designed to extend the functionality of the WasmEdge runtime, and can be useful for developers and end-users in several ways: + +- **Versatility:** WasmEdge plugins can be developed in multiple programming languages that can compile to WebAssembly, allowing developers to write plugins in the language they're most comfortable with. + +- **Customization:** WasmEdge plugins can be customized to suit the specific needs of a project. Developers can create plugins that integrate with other systems or tools, or that provide unique functionality that's not available in the core WasmEdge runtime. + +- **Performance:** WasmEdge plugins are designed to work seamlessly with the core runtime, minimizing overhead and maximizing performance. This means that they can provide additional functionality without sacrificing performance. + +- **Ease of use:** WasmEdge plugins are easy to use and integrate with the WasmEdge runtime. Developers can simply load the plugin into the runtime and use its functions as if they were part of the core runtime. + +- **Scalability:** WasmEdge plugins can be used to scale applications by offloading compute-intensive tasks to edge devices. This can reduce the load on central servers and improve performance. + +- **Security:** WasmEdge plugins run in a sandboxed environment, which helps to reduce the risk of security vulnerabilities. Additionally, plugins can be digitally signed to ensure authenticity and integrity. + +WasmEdge plugins can provide developers and users with a versatile, customizable, high-performance, and secure way to extend the functionality of the WasmEdge runtime. WasmEdge plugins can also improve scalability and ease of use, making it easier to build and deploy complex applications on edge devices. ## Loadable Plug-in -Loadable plugin is a standalone `.so`/`.dylib`/`.dll` file that WasmEdge can load during runtime environment, and provide modules to be imported. +Loadable plugins are standalone shared libraries (`.so`/`.dylib`/`.dll` files) that can be loaded by the WasmEdge runtime environment at runtime. These plugins can provide additional functionality to the WasmEdge runtime environment, such as new modules that can be imported by WebAssembly modules. + +### Creating Loadable Plug-in + +To create a loadable plugin for WasmEdge, developers can use the WasmEdge Plugin SDK, which provides a set of Rust, C and C++ APIs for creating and registering plugins. The SDK also includes [example code](https://github.com/WasmEdge/WasmEdge/tree/master/examples/plugin/get-string) that demonstrates how to create a simple plugin that returns a string. By following the provided examples and leveraging the SDK's APIs, developers can easily build custom plugins tailored to their specific needs. + +### Loading plug-in from paths + +To make use of the loadable plugins, developers need to load them from specific paths into the WasmEdge runtime environment. The loading process involves the following steps: + +- Loadable plugins can be loaded from default paths by calling the `WasmEdge_PluginLoadWithDefaultPaths()` API. The default paths include: + + - The path specified in the environment variable `WASMEDGE_PLUGIN_PATH`. + - The `../plugin/` directory relative to the WasmEdge installation path. + - The `./wasmedge/` directory located under the library path if WasmEdge is installed in a system directory such as `/usr` and `/usr/local`. + +- If the plugins are located in a specific path or directory, developers can use the `WasmEdge_PluginLoadFromPath("PATH_TO_PLUGIN/plugin.so")` API to load the plugins from that particular location. + +The WasmEdge runtime environment will search for the loadable plugins in the specified paths and load them if found. + +The following flowchart shows the process of loading loadable plugins into the WasmEdge runtime environment from specific paths: + +```mermaid +graph LR + A((Start)) --> B(Loadable Plugins) + B --> C{Load Plugins} + C --> D[Load from Default Paths] + C --> E[Load from Specific Path] + C --> F[Load from Specific Directory] + D --> G{Is Plugin Found?} + E --> G + F --> G + G -- Yes --> H(Load Plugin) + H --> I(End) + G -- No --> I +``` + +The flowchart shows the process of loading loadable plugins into the WasmEdge runtime environment. The process involves searching for plugins in default paths, a specific path, or a specific directory. If a plugin is found in any of these locations, it is loaded into the runtime environment. The flowchart enables developers to easily load plugins and extend the capabilities of the WasmEdge runtime. -Please [refer to the plugin example code](https://github.com/WasmEdge/WasmEdge/tree/master/examples/plugin/get-string). +By following this flowchart, developers can effectively load loadable plugins into the WasmEdge runtime environment from specific paths, expanding the runtime's functionality according to their requirements. ## 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 source with the plug-ins. -| Plug-in | Rust Crate | Released Platforms | Build Steps | -| --- | --- | --- | --- | -| WasmEdge-Process | [wasmedge_process_interface][] | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.10.0`) | [Build Wtih WasmEdge-Process](/contribute/source/plugin/process) | -| [WASI-Crypto][] | [wasi-crypto][] | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.10.1`) | [Build With WASI-Crypto](/contribute/source/plugin/wasi_crypto) | -| [WASI-NN with OpenVINO backend](/develop/rust/ai_inference/openvino) | [wasi-nn][] | `ubuntu 20.04 x86_64` (since `0.10.1`) | [Build With WASI-NN](/contribute/source/plugin/wasi_nn#get-wasmedge-with-wasi-nn-plug-in-openvino-backend) | -| [WASI-NN with PyTorch backend](/develop/rust/ai_inference/pytorch) | [wasi-nn][] | `ubuntu 20.04 x86_64` (since `0.11.1`) | [Build With WASI-NN](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-pytorch-backend) | -| [WASI-NN with TensorFlow-Lite backend](/develop/rust/ai_inference/pytorch) | [wasi-nn][] | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.11.2`) | [Build With WASI-NN](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-tensorflow-lite-backend) | -| WasmEdge-Image | [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](/contribute/source/plugin/image) | -| WasmEdge-Tensorflow | [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](/contribute/source/plugin/tensorflow) | -| WasmEdge-TensorflowLite | [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](/contribute/source/plugin/tensorflowlite) | +| Plug-in | Rust Crate | Description | Released Platforms | Build Steps | +| --- | --- | --- | --- | --- | +| WasmEdge-Process | [wasmedge_process_interface][] | WasmEdge-Process is a utility plugin for the WasmEdge Runtime, providing functionality related to process handling. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.10.0`) | [Build Wtih WasmEdge-Process](/contribute/source/plugin/process) | +| [WASI-Crypto][] | [wasi-crypto][] | WASI-Crypto is a module that provides a set of APIs for cryptographic operations and key management. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.10.1`) | [Build With WASI-Crypto](/contribute/source/plugin/wasi_crypto) | +| [WASI-NN with OpenVINO backend](/develop/rust/ai_inference/openvino) | [wasi-nn][] | WASI-NN with OpenVINO backend is a machine learning-oriented module for WebAssembly. | `ubuntu 20.04 x86_64` (since `0.10.1`) | [Build With WASI-NN](/contribute/source/plugin/wasi_nn#get-wasmedge-with-wasi-nn-plug-in-openvino-backend) | +| [WASI-NN with PyTorch backend](/develop/rust/ai_inference/pytorch) | [wasi-nn][] | WASI-NN with PyTorch backend allows running of PyTorch models in WebAssembly. | `ubuntu 20.04 x86_64` (since `0.11.1`) | [Build With WASI-NN](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-pytorch-backend) | +| [WASI-NN with TensorFlow-Lite backend](/develop/rust/ai_inference/pytorch) | [wasi-nn][] | WASI-NN with TensorFlow-Lite backend allows running of TensorFlow-Lite models in WebAssembly. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.11.2`) | [Build With WASI-NN](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-tensorflow-lite-backend) | +| WasmEdge-Image | [wasmedge_tensorflow_interface][] | WasmEdge-Image is a plugin that provides image processing and manipulation capabilities in WasmEdge. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, `ubuntu 20.04 x86_64`, `darwin x86_64`, and `darwin arm64` (since `0.13.0`) | [Build With WasmEdge-Image](/contribute/source/plugin/image) | +| WasmEdge-Tensorflow | [wasmedge_tensorflow_interface][] | WasmEdge-Tensorflow integrates TensorFlow with WasmEdge for running machine learning models. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, `ubuntu 20.04 x86_64`, `darwin x86_64`, and `darwin arm64` (since `0.13.0`) | [Build With WasmEdge-Tensorflow](/contribute/source/plugin/tensorflow) | +| WasmEdge-TensorflowLite | [wasmedge_tensorflow_interface][] | WasmEdge-TensorflowLite is a plugin for running TensorFlow Lite models in WasmEdge. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, `ubuntu 20.04 x86_64`, `darwin x86_64`, and `darwin arm64` (since `0.13.0`) | [Build With WasmEdge-TensorflowLite](/contribute/source/plugin/tensorflowlite) | :::note diff --git a/docusaurus.config.js b/docusaurus.config.js index 9a3b76acf..3ba5a3c85 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -215,4 +215,10 @@ const config = { }), }; -module.exports = config; +module.exports = { + ...config, + markdown: { + mermaid: true, + }, + themes: ['@docusaurus/theme-mermaid'], + }; \ No newline at end of file diff --git a/package-lock.json b/package-lock.json index 1de47f150..b6f7eda13 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10,6 +10,7 @@ "dependencies": { "@docusaurus/core": "^2.4.0", "@docusaurus/preset-classic": "^2.4.0", + "@docusaurus/theme-mermaid": "^2.4.1", "@easyops-cn/docusaurus-search-local": "^0.35.0", "@mdx-js/react": "^1.6.22", "@node-rs/jieba": "^1.7.0", @@ -1999,6 +2000,11 @@ "node": ">=6.9.0" } }, + "node_modules/@braintree/sanitize-url": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/@braintree/sanitize-url/-/sanitize-url-6.0.2.tgz", + "integrity": "sha512-Tbsj02wXCbqGmzdnXNk0SOF19ChhRU70BsroIi4Pm6Ehp56in6vch94mfbdQ17DozxkL3BAVjbZ4Qc1a0HFRAg==" + }, "node_modules/@colors/colors": { "version": "1.5.0", "resolved": "https://registry.npmjs.org/@colors/colors/-/colors-1.5.0.tgz", @@ -2709,6 +2715,28 @@ "react-dom": "^16.8.4 || ^17.0.0" } }, + "node_modules/@docusaurus/theme-mermaid": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/@docusaurus/theme-mermaid/-/theme-mermaid-2.4.1.tgz", + "integrity": "sha512-cM0ImKIqZfjmlaC+uAjep39kNBvb1bjz429QBHGs32maob4+UnRzVPPpCUCltyPVb4xjG5h1Tyq4pHzhtIikqA==", + "dependencies": { + "@docusaurus/core": "2.4.1", + "@docusaurus/module-type-aliases": "2.4.1", + "@docusaurus/theme-common": "2.4.1", + "@docusaurus/types": "2.4.1", + "@docusaurus/utils-validation": "2.4.1", + "@mdx-js/react": "^1.6.22", + "mermaid": "^9.2.2", + "tslib": "^2.4.0" + }, + "engines": { + "node": ">=16.14" + }, + "peerDependencies": { + "react": "^16.8.4 || ^17.0.0", + "react-dom": "^16.8.4 || ^17.0.0" + } + }, "node_modules/@docusaurus/theme-search-algolia": { "version": "2.4.1", "resolved": "https://registry.npmjs.org/@docusaurus/theme-search-algolia/-/theme-search-algolia-2.4.1.tgz", @@ -6342,6 +6370,14 @@ "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz", "integrity": "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==" }, + "node_modules/cose-base": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/cose-base/-/cose-base-1.0.3.tgz", + "integrity": "sha512-s9whTXInMSgAp/NVXVNuVxVKzGH2qck3aQlVHxDCdAEPgtMKwc4Wq6/QKhgdEdgbLSi9rBTAcPoRa6JpiG4ksg==", + "dependencies": { + "layout-base": "^1.0.0" + } + }, "node_modules/cosmiconfig": { "version": "7.1.0", "resolved": "https://registry.npmjs.org/cosmiconfig/-/cosmiconfig-7.1.0.tgz", @@ -6710,12 +6746,462 @@ "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.1.2.tgz", "integrity": "sha512-I7K1Uu0MBPzaFKg4nI5Q7Vs2t+3gWWW648spaF+Rg7pI9ds18Ugn+lvg4SHczUdKlHI5LWBXyqfS8+DufyBsgQ==" }, + "node_modules/cytoscape": { + "version": "3.25.0", + "resolved": "https://registry.npmjs.org/cytoscape/-/cytoscape-3.25.0.tgz", + "integrity": "sha512-7MW3Iz57mCUo6JQCho6CmPBCbTlJr7LzyEtIkutG255HLVd4XuBg2I9BkTZLI/e4HoaOB/BiAzXuQybQ95+r9Q==", + "dependencies": { + "heap": "^0.2.6", + "lodash": "^4.17.21" + }, + "engines": { + "node": ">=0.10" + } + }, + "node_modules/cytoscape-cose-bilkent": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/cytoscape-cose-bilkent/-/cytoscape-cose-bilkent-4.1.0.tgz", + "integrity": "sha512-wgQlVIUJF13Quxiv5e1gstZ08rnZj2XaLHGoFMYXz7SkNfCDOOteKBE6SYRfA9WxxI/iBc3ajfDoc6hb/MRAHQ==", + "dependencies": { + "cose-base": "^1.0.0" + }, + "peerDependencies": { + "cytoscape": "^3.2.0" + } + }, + "node_modules/cytoscape-fcose": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/cytoscape-fcose/-/cytoscape-fcose-2.2.0.tgz", + "integrity": "sha512-ki1/VuRIHFCzxWNrsshHYPs6L7TvLu3DL+TyIGEsRcvVERmxokbf5Gdk7mFxZnTdiGtnA4cfSmjZJMviqSuZrQ==", + "dependencies": { + "cose-base": "^2.2.0" + }, + "peerDependencies": { + "cytoscape": "^3.2.0" + } + }, + "node_modules/cytoscape-fcose/node_modules/cose-base": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/cose-base/-/cose-base-2.2.0.tgz", + "integrity": "sha512-AzlgcsCbUMymkADOJtQm3wO9S3ltPfYOFD5033keQn9NJzIbtnZj+UdBJe7DYml/8TdbtHJW3j58SOnKhWY/5g==", + "dependencies": { + "layout-base": "^2.0.0" + } + }, + "node_modules/cytoscape-fcose/node_modules/layout-base": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/layout-base/-/layout-base-2.0.1.tgz", + "integrity": "sha512-dp3s92+uNI1hWIpPGH3jK2kxE2lMjdXdr+DH8ynZHpd6PUlH6x6cbuXnoMmiNumznqaNO31xu9e79F0uuZ0JFg==" + }, + "node_modules/d3": { + "version": "7.8.5", + "resolved": "https://registry.npmjs.org/d3/-/d3-7.8.5.tgz", + "integrity": "sha512-JgoahDG51ncUfJu6wX/1vWQEqOflgXyl4MaHqlcSruTez7yhaRKR9i8VjjcQGeS2en/jnFivXuaIMnseMMt0XA==", + "dependencies": { + "d3-array": "3", + "d3-axis": "3", + "d3-brush": "3", + "d3-chord": "3", + "d3-color": "3", + "d3-contour": "4", + "d3-delaunay": "6", + "d3-dispatch": "3", + "d3-drag": "3", + "d3-dsv": "3", + "d3-ease": "3", + "d3-fetch": "3", + "d3-force": "3", + "d3-format": "3", + "d3-geo": "3", + "d3-hierarchy": "3", + "d3-interpolate": "3", + "d3-path": "3", + "d3-polygon": "3", + "d3-quadtree": "3", + "d3-random": "3", + "d3-scale": "4", + "d3-scale-chromatic": "3", + "d3-selection": "3", + "d3-shape": "3", + "d3-time": "3", + "d3-time-format": "4", + "d3-timer": "3", + "d3-transition": "3", + "d3-zoom": "3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-array": { + "version": "3.2.4", + "resolved": "https://registry.npmjs.org/d3-array/-/d3-array-3.2.4.tgz", + "integrity": "sha512-tdQAmyA18i4J7wprpYq8ClcxZy3SC31QMeByyCFyRt7BVHdREQZ5lpzoe5mFEYZUWe+oq8HBvk9JjpibyEV4Jg==", + "dependencies": { + "internmap": "1 - 2" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-axis": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-axis/-/d3-axis-3.0.0.tgz", + "integrity": "sha512-IH5tgjV4jE/GhHkRV0HiVYPDtvfjHQlQfJHs0usq7M30XcSBvOotpmH1IgkcXsO/5gEQZD43B//fc7SRT5S+xw==", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-brush": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-brush/-/d3-brush-3.0.0.tgz", + "integrity": "sha512-ALnjWlVYkXsVIGlOsuWH1+3udkYFI48Ljihfnh8FZPF2QS9o+PzGLBslO0PjzVoHLZ2KCVgAM8NVkXPJB2aNnQ==", + "dependencies": { + "d3-dispatch": "1 - 3", + "d3-drag": "2 - 3", + "d3-interpolate": "1 - 3", + "d3-selection": "3", + "d3-transition": "3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-chord": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-chord/-/d3-chord-3.0.1.tgz", + "integrity": "sha512-VE5S6TNa+j8msksl7HwjxMHDM2yNK3XCkusIlpX5kwauBfXuyLAtNg9jCp/iHH61tgI4sb6R/EIMWCqEIdjT/g==", + "dependencies": { + "d3-path": "1 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-color": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-color/-/d3-color-3.1.0.tgz", + "integrity": "sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-contour": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/d3-contour/-/d3-contour-4.0.2.tgz", + "integrity": "sha512-4EzFTRIikzs47RGmdxbeUvLWtGedDUNkTcmzoeyg4sP/dvCexO47AaQL7VKy/gul85TOxw+IBgA8US2xwbToNA==", + "dependencies": { + "d3-array": "^3.2.0" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-delaunay": { + "version": "6.0.4", + "resolved": "https://registry.npmjs.org/d3-delaunay/-/d3-delaunay-6.0.4.tgz", + "integrity": "sha512-mdjtIZ1XLAM8bm/hx3WwjfHt6Sggek7qH043O8KEjDXN40xi3vx/6pYSVTwLjEgiXQTbvaouWKynLBiUZ6SK6A==", + "dependencies": { + "delaunator": "5" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-dispatch": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-dispatch/-/d3-dispatch-3.0.1.tgz", + "integrity": "sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-drag": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-drag/-/d3-drag-3.0.0.tgz", + "integrity": "sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==", + "dependencies": { + "d3-dispatch": "1 - 3", + "d3-selection": "3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-dsv": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-dsv/-/d3-dsv-3.0.1.tgz", + "integrity": "sha512-UG6OvdI5afDIFP9w4G0mNq50dSOsXHJaRE8arAS5o9ApWnIElp8GZw1Dun8vP8OyHOZ/QJUKUJwxiiCCnUwm+Q==", + "dependencies": { + "commander": "7", + "iconv-lite": "0.6", + "rw": "1" + }, + "bin": { + "csv2json": "bin/dsv2json.js", + "csv2tsv": "bin/dsv2dsv.js", + "dsv2dsv": "bin/dsv2dsv.js", + "dsv2json": "bin/dsv2json.js", + "json2csv": "bin/json2dsv.js", + "json2dsv": "bin/json2dsv.js", + "json2tsv": "bin/json2dsv.js", + "tsv2csv": "bin/dsv2dsv.js", + "tsv2json": "bin/dsv2json.js" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-dsv/node_modules/commander": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-7.2.0.tgz", + "integrity": "sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw==", + "engines": { + "node": ">= 10" + } + }, + "node_modules/d3-dsv/node_modules/iconv-lite": { + "version": "0.6.3", + "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz", + "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==", + "dependencies": { + "safer-buffer": ">= 2.1.2 < 3.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/d3-ease": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-ease/-/d3-ease-3.0.1.tgz", + "integrity": "sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-fetch": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-fetch/-/d3-fetch-3.0.1.tgz", + "integrity": "sha512-kpkQIM20n3oLVBKGg6oHrUchHM3xODkTzjMoj7aWQFq5QEM+R6E4WkzT5+tojDY7yjez8KgCBRoj4aEr99Fdqw==", + "dependencies": { + "d3-dsv": "1 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-force": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-force/-/d3-force-3.0.0.tgz", + "integrity": "sha512-zxV/SsA+U4yte8051P4ECydjD/S+qeYtnaIyAs9tgHCqfguma/aAQDjo85A9Z6EKhBirHRJHXIgJUlffT4wdLg==", + "dependencies": { + "d3-dispatch": "1 - 3", + "d3-quadtree": "1 - 3", + "d3-timer": "1 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-format": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-format/-/d3-format-3.1.0.tgz", + "integrity": "sha512-YyUI6AEuY/Wpt8KWLgZHsIU86atmikuoOmCfommt0LYHiQSPjvX2AcFc38PX0CBpr2RCyZhjex+NS/LPOv6YqA==", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-geo": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-geo/-/d3-geo-3.1.0.tgz", + "integrity": "sha512-JEo5HxXDdDYXCaWdwLRt79y7giK8SbhZJbFWXqbRTolCHFI5jRqteLzCsq51NKbUoX0PjBVSohxrx+NoOUujYA==", + "dependencies": { + "d3-array": "2.5.0 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-hierarchy": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/d3-hierarchy/-/d3-hierarchy-3.1.2.tgz", + "integrity": "sha512-FX/9frcub54beBdugHjDCdikxThEqjnR93Qt7PvQTOHxyiNCAlvMrHhclk3cD5VeAaq9fxmfRp+CnWw9rEMBuA==", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-interpolate": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-interpolate/-/d3-interpolate-3.0.1.tgz", + "integrity": "sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==", + "dependencies": { + "d3-color": "1 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-path": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-path/-/d3-path-3.1.0.tgz", + "integrity": "sha512-p3KP5HCf/bvjBSSKuXid6Zqijx7wIfNW+J/maPs+iwR35at5JCbLUT0LzF1cnjbCHWhqzQTIN2Jpe8pRebIEFQ==", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-polygon": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-polygon/-/d3-polygon-3.0.1.tgz", + "integrity": "sha512-3vbA7vXYwfe1SYhED++fPUQlWSYTTGmFmQiany/gdbiWgU/iEyQzyymwL9SkJjFFuCS4902BSzewVGsHHmHtXg==", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-quadtree": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-quadtree/-/d3-quadtree-3.0.1.tgz", + "integrity": "sha512-04xDrxQTDTCFwP5H6hRhsRcb9xxv2RzkcsygFzmkSIOJy3PeRJP7sNk3VRIbKXcog561P9oU0/rVH6vDROAgUw==", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-random": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-random/-/d3-random-3.0.1.tgz", + "integrity": "sha512-FXMe9GfxTxqd5D6jFsQ+DJ8BJS4E/fT5mqqdjovykEB2oFbTMDVdg1MGFxfQW+FBOGoB++k8swBrgwSHT1cUXQ==", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-scale": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/d3-scale/-/d3-scale-4.0.2.tgz", + "integrity": "sha512-GZW464g1SH7ag3Y7hXjf8RoUuAFIqklOAq3MRl4OaWabTFJY9PN/E1YklhXLh+OQ3fM9yS2nOkCoS+WLZ6kvxQ==", + "dependencies": { + "d3-array": "2.10.0 - 3", + "d3-format": "1 - 3", + "d3-interpolate": "1.2.0 - 3", + "d3-time": "2.1.1 - 3", + "d3-time-format": "2 - 4" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-scale-chromatic": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-scale-chromatic/-/d3-scale-chromatic-3.0.0.tgz", + "integrity": "sha512-Lx9thtxAKrO2Pq6OO2Ua474opeziKr279P/TKZsMAhYyNDD3EnCffdbgeSYN5O7m2ByQsxtuP2CSDczNUIZ22g==", + "dependencies": { + "d3-color": "1 - 3", + "d3-interpolate": "1 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-selection": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz", + "integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-shape": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/d3-shape/-/d3-shape-3.2.0.tgz", + "integrity": "sha512-SaLBuwGm3MOViRq2ABk3eLoxwZELpH6zhl3FbAoJ7Vm1gofKx6El1Ib5z23NUEhF9AsGl7y+dzLe5Cw2AArGTA==", + "dependencies": { + "d3-path": "^3.1.0" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-time": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-time/-/d3-time-3.1.0.tgz", + "integrity": "sha512-VqKjzBLejbSMT4IgbmVgDjpkYrNWUYJnbCGo874u7MMKIWsILRX+OpX/gTk8MqjpT1A/c6HY2dCA77ZN0lkQ2Q==", + "dependencies": { + "d3-array": "2 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-time-format": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/d3-time-format/-/d3-time-format-4.1.0.tgz", + "integrity": "sha512-dJxPBlzC7NugB2PDLwo9Q8JiTR3M3e4/XANkreKSUxF8vvXKqm1Yfq4Q5dl8budlunRVlUUaDUgFt7eA8D6NLg==", + "dependencies": { + "d3-time": "1 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-timer": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-timer/-/d3-timer-3.0.1.tgz", + "integrity": "sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-transition": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-transition/-/d3-transition-3.0.1.tgz", + "integrity": "sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w==", + "dependencies": { + "d3-color": "1 - 3", + "d3-dispatch": "1 - 3", + "d3-ease": "1 - 3", + "d3-interpolate": "1 - 3", + "d3-timer": "1 - 3" + }, + "engines": { + "node": ">=12" + }, + "peerDependencies": { + "d3-selection": "2 - 3" + } + }, + "node_modules/d3-zoom": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-zoom/-/d3-zoom-3.0.0.tgz", + "integrity": "sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==", + "dependencies": { + "d3-dispatch": "1 - 3", + "d3-drag": "2 - 3", + "d3-interpolate": "1 - 3", + "d3-selection": "2 - 3", + "d3-transition": "2 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/dagre-d3-es": { + "version": "7.0.9", + "resolved": "https://registry.npmjs.org/dagre-d3-es/-/dagre-d3-es-7.0.9.tgz", + "integrity": "sha512-rYR4QfVmy+sR44IBDvVtcAmOReGBvRCWDpO2QjYwqgh9yijw6eSHBqaPG/LIOEy7aBsniLvtMW6pg19qJhq60w==", + "dependencies": { + "d3": "^7.8.2", + "lodash-es": "^4.17.21" + } + }, "node_modules/damerau-levenshtein": { "version": "1.0.8", "resolved": "https://registry.npmjs.org/damerau-levenshtein/-/damerau-levenshtein-1.0.8.tgz", "integrity": "sha512-sdQSFB7+llfUcQHUQO3+B8ERRj0Oa4w9POWMI/puGtuf7gFywGmkaLCElnudfTiKZV+NvHqL0ifzdrI8Ro7ESA==", "dev": true }, + "node_modules/dayjs": { + "version": "1.11.9", + "resolved": "https://registry.npmjs.org/dayjs/-/dayjs-1.11.9.tgz", + "integrity": "sha512-QvzAURSbQ0pKdIye2txOzNaHmxtUBXerpY0FJsFXUMKbIZeFm5ht1LS/jFsrncjnmtv8HsG0W2g6c0zUjZWmpA==" + }, "node_modules/debug": { "version": "4.3.4", "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.4.tgz", @@ -6982,6 +7468,14 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/delaunator": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/delaunator/-/delaunator-5.0.0.tgz", + "integrity": "sha512-AyLvtyJdbv/U1GkiS6gUUzclRoAY4Gs75qkMygJJhU75LW4DNuSF2RMzpxs9jw9Oz1BobHjTdkG3zdP55VxAqw==", + "dependencies": { + "robust-predicates": "^3.0.0" + } + }, "node_modules/depd": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz", @@ -7159,6 +7653,11 @@ "url": "https://github.com/fb55/domhandler?sponsor=1" } }, + "node_modules/dompurify": { + "version": "2.4.3", + "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-2.4.3.tgz", + "integrity": "sha512-q6QaLcakcRjebxjg8/+NP+h0rPfatOgOzc46Fst9VAA3jF2ApfKBNKMzdP4DYTqtUMXSCd5pRS/8Po/OmoCHZQ==" + }, "node_modules/domutils": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/domutils/-/domutils-3.1.0.tgz", @@ -7236,6 +7735,11 @@ "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.421.tgz", "integrity": "sha512-wZOyn3s/aQOtLGAwXMZfteQPN68kgls2wDAnYOA8kCjBvKVrW5RwmWVspxJYTqrcN7Y263XJVsC66VCIGzDO3g==" }, + "node_modules/elkjs": { + "version": "0.8.2", + "resolved": "https://registry.npmjs.org/elkjs/-/elkjs-0.8.2.tgz", + "integrity": "sha512-L6uRgvZTH+4OF5NE/MBbzQx/WYpru1xCBE9respNj6qznEewGUIfhzmm7horWWxbNO2M0WckQypGctR8lH79xQ==" + }, "node_modules/emoji-regex": { "version": "9.2.2", "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz", @@ -9424,6 +9928,11 @@ "he": "bin/he" } }, + "node_modules/heap": { + "version": "0.2.7", + "resolved": "https://registry.npmjs.org/heap/-/heap-0.2.7.tgz", + "integrity": "sha512-2bsegYkkHO+h/9MGbn6KWcE45cHZgPANo5LXF7EvWdT0yT2EguSVO1nDgU5c8+ZOPwp2vMNa7YFsJhVcDR9Sdg==" + }, "node_modules/history": { "version": "4.10.1", "resolved": "https://registry.npmjs.org/history/-/history-4.10.1.tgz", @@ -9997,6 +10506,14 @@ "node": ">= 0.4" } }, + "node_modules/internmap": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/internmap/-/internmap-2.0.3.tgz", + "integrity": "sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg==", + "engines": { + "node": ">=12" + } + }, "node_modules/interpret": { "version": "1.4.0", "resolved": "https://registry.npmjs.org/interpret/-/interpret-1.4.0.tgz", @@ -10839,6 +11356,11 @@ "json-buffer": "3.0.0" } }, + "node_modules/khroma": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/khroma/-/khroma-2.0.0.tgz", + "integrity": "sha512-2J8rDNlQWbtiNYThZRvmMv5yt44ZakX+Tz5ZIp/mN1pt4snn+m030Va5Z4v8xA0cQFDXBwO/8i42xL4QPsVk3g==" + }, "node_modules/kind-of": { "version": "6.0.3", "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz", @@ -10912,6 +11434,11 @@ "shell-quote": "^1.7.3" } }, + "node_modules/layout-base": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/layout-base/-/layout-base-1.0.2.tgz", + "integrity": "sha512-8h2oVEZNktL4BH2JCOI90iD1yXwL6iNW7KcCKT2QZgQJR2vbqDsldCTPRU9NifTCqHZci57XvQQ15YTu+sTYPg==" + }, "node_modules/leven": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/leven/-/leven-3.1.0.tgz", @@ -11187,6 +11714,11 @@ "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==" }, + "node_modules/lodash-es": { + "version": "4.17.21", + "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.21.tgz", + "integrity": "sha512-mKnC+QJ9pWVzv+C4/U3rRsHapFfHvQFoFB92e52xeyGMcX6/OlIl78je1u8vePzYZSkkogMPJ2yjxxsb89cxyw==" + }, "node_modules/lodash.curry": { "version": "4.1.1", "resolved": "https://registry.npmjs.org/lodash.curry/-/lodash.curry-4.1.1.tgz", @@ -12189,6 +12721,37 @@ "node": ">= 8" } }, + "node_modules/mermaid": { + "version": "9.4.3", + "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-9.4.3.tgz", + "integrity": "sha512-TLkQEtqhRSuEHSE34lh5bCa94KATCyluAXmFnNI2PRZwOpXFeqiJWwZl+d2CcemE1RS6QbbueSSq9QIg8Uxcyw==", + "dependencies": { + "@braintree/sanitize-url": "^6.0.0", + "cytoscape": "^3.23.0", + "cytoscape-cose-bilkent": "^4.1.0", + "cytoscape-fcose": "^2.1.0", + "d3": "^7.4.0", + "dagre-d3-es": "7.0.9", + "dayjs": "^1.11.7", + "dompurify": "2.4.3", + "elkjs": "^0.8.2", + "khroma": "^2.0.0", + "lodash-es": "^4.17.21", + "non-layered-tidy-tree-layout": "^2.0.2", + "stylis": "^4.1.2", + "ts-dedent": "^2.2.0", + "uuid": "^9.0.0", + "web-worker": "^1.2.0" + } + }, + "node_modules/mermaid/node_modules/uuid": { + "version": "9.0.0", + "resolved": "https://registry.npmjs.org/uuid/-/uuid-9.0.0.tgz", + "integrity": "sha512-MXcSTerfPa4uqyzStbRoTgt5XIe3x5+42+q1sDuy3R5MDk66URdLMOZe5aPX/SQd+kuYAh0FdP/pO28IkQyTeg==", + "bin": { + "uuid": "dist/bin/uuid" + } + }, "node_modules/methods": { "version": "1.1.2", "resolved": "https://registry.npmjs.org/methods/-/methods-1.1.2.tgz", @@ -12942,6 +13505,11 @@ "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.12.tgz", "integrity": "sha512-QzsYKWhXTWx8h1kIvqfnC++o0pEmpRQA/aenALsL2F4pqNVr7YzcdMlDij5WBnwftRbJCNJL/O7zdKaxKPHqgQ==" }, + "node_modules/non-layered-tidy-tree-layout": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/non-layered-tidy-tree-layout/-/non-layered-tidy-tree-layout-2.0.2.tgz", + "integrity": "sha512-gkXMxRzUH+PB0ax9dUN0yYF0S25BqeAYqhgMaLUFmpXLEk7Fcu8f4emJuOAY0V8kjDICxROIKsTAKsV/v355xw==" + }, "node_modules/normalize-package-data": { "version": "3.0.3", "resolved": "https://registry.npmjs.org/normalize-package-data/-/normalize-package-data-3.0.3.tgz", @@ -14827,6 +15395,18 @@ "resolved": "https://registry.npmjs.org/react-lifecycles-compat/-/react-lifecycles-compat-3.0.4.tgz", "integrity": "sha512-fBASbA6LnOU9dOU2eW7aQ8xmYBSXUIWr+UmF9b1efZBazGNO+rcXT/icdKnYm2pTwcRylVUYwW7H1PHfLekVzA==" }, + "node_modules/react-loadable": { + "version": "5.5.0", + "resolved": "https://registry.npmjs.org/react-loadable/-/react-loadable-5.5.0.tgz", + "integrity": "sha512-C8Aui0ZpMd4KokxRdVAm2bQtI03k2RMRNzOB+IipV3yxFTSVICv7WoUr5L9ALB5BmKO1iHgZtWM8EvYG83otdg==", + "peer": true, + "dependencies": { + "prop-types": "^15.5.0" + }, + "peerDependencies": { + "react": "*" + } + }, "node_modules/react-loadable-ssr-addon-v5-slorber": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/react-loadable-ssr-addon-v5-slorber/-/react-loadable-ssr-addon-v5-slorber-1.0.1.tgz", @@ -18123,6 +18703,11 @@ "url": "https://github.com/sponsors/isaacs" } }, + "node_modules/robust-predicates": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/robust-predicates/-/robust-predicates-3.0.2.tgz", + "integrity": "sha512-IXgzBWvWQwE6PrDI05OvmXUIruQTcoMDzRsOd5CDvHCVLcLHMTSYvOK5Cm46kWqlV3yAbuSpBZdJ5oP5OUoStg==" + }, "node_modules/rtl-detect": { "version": "1.0.4", "resolved": "https://registry.npmjs.org/rtl-detect/-/rtl-detect-1.0.4.tgz", @@ -18173,6 +18758,11 @@ "queue-microtask": "^1.2.2" } }, + "node_modules/rw": { + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/rw/-/rw-1.3.3.tgz", + "integrity": "sha512-PdhdWy89SiZogBLaw42zdeqtRJ//zFd2PgQavcICDUgJT5oW10QCRKbJ6bg4r0/UY2M6BWd5tkxuGFRvCkgfHQ==" + }, "node_modules/rxjs": { "version": "7.8.1", "resolved": "https://registry.npmjs.org/rxjs/-/rxjs-7.8.1.tgz", @@ -19184,6 +19774,11 @@ "node": ">=8" } }, + "node_modules/stylis": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/stylis/-/stylis-4.3.0.tgz", + "integrity": "sha512-E87pIogpwUsUwXw7dNyU4QDjdgVMy52m+XEOPEKUn161cCzWjjhPSQhByfd1CcNvrOLnXQ6OnnZDwnJrz/Z4YQ==" + }, "node_modules/supports-color": { "version": "5.5.0", "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", @@ -19702,6 +20297,14 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/ts-dedent": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/ts-dedent/-/ts-dedent-2.2.0.tgz", + "integrity": "sha512-q5W7tVM71e2xjHZTlgfTDoPF/SmqKG5hddq9SzR49CH2hayqRKJtQ4mtRlSxKaJlR/+9rEM+mnBHf7I2/BQcpQ==", + "engines": { + "node": ">=6.10" + } + }, "node_modules/tsconfig-paths": { "version": "3.14.2", "resolved": "https://registry.npmjs.org/tsconfig-paths/-/tsconfig-paths-3.14.2.tgz", @@ -20715,6 +21318,11 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/web-worker": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/web-worker/-/web-worker-1.2.0.tgz", + "integrity": "sha512-PgF341avzqyx60neE9DD+XS26MMNMoUQRz9NOZwW32nPQrF6p77f1htcnjBSEV8BGMKZ16choqUG4hyI0Hx7mA==" + }, "node_modules/webidl-conversions": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz", @@ -22871,6 +23479,11 @@ "to-fast-properties": "^2.0.0" } }, + "@braintree/sanitize-url": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/@braintree/sanitize-url/-/sanitize-url-6.0.2.tgz", + "integrity": "sha512-Tbsj02wXCbqGmzdnXNk0SOF19ChhRU70BsroIi4Pm6Ehp56in6vch94mfbdQ17DozxkL3BAVjbZ4Qc1a0HFRAg==" + }, "@colors/colors": { "version": "1.5.0", "resolved": "https://registry.npmjs.org/@colors/colors/-/colors-1.5.0.tgz", @@ -23390,6 +24003,21 @@ "utility-types": "^3.10.0" } }, + "@docusaurus/theme-mermaid": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/@docusaurus/theme-mermaid/-/theme-mermaid-2.4.1.tgz", + "integrity": "sha512-cM0ImKIqZfjmlaC+uAjep39kNBvb1bjz429QBHGs32maob4+UnRzVPPpCUCltyPVb4xjG5h1Tyq4pHzhtIikqA==", + "requires": { + "@docusaurus/core": "2.4.1", + "@docusaurus/module-type-aliases": "2.4.1", + "@docusaurus/theme-common": "2.4.1", + "@docusaurus/types": "2.4.1", + "@docusaurus/utils-validation": "2.4.1", + "@mdx-js/react": "^1.6.22", + "mermaid": "^9.2.2", + "tslib": "^2.4.0" + } + }, "@docusaurus/theme-search-algolia": { "version": "2.4.1", "resolved": "https://registry.npmjs.org/@docusaurus/theme-search-algolia/-/theme-search-algolia-2.4.1.tgz", @@ -26021,6 +26649,14 @@ "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz", "integrity": "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==" }, + "cose-base": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/cose-base/-/cose-base-1.0.3.tgz", + "integrity": "sha512-s9whTXInMSgAp/NVXVNuVxVKzGH2qck3aQlVHxDCdAEPgtMKwc4Wq6/QKhgdEdgbLSi9rBTAcPoRa6JpiG4ksg==", + "requires": { + "layout-base": "^1.0.0" + } + }, "cosmiconfig": { "version": "7.1.0", "resolved": "https://registry.npmjs.org/cosmiconfig/-/cosmiconfig-7.1.0.tgz", @@ -26265,12 +26901,344 @@ "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.1.2.tgz", "integrity": "sha512-I7K1Uu0MBPzaFKg4nI5Q7Vs2t+3gWWW648spaF+Rg7pI9ds18Ugn+lvg4SHczUdKlHI5LWBXyqfS8+DufyBsgQ==" }, + "cytoscape": { + "version": "3.25.0", + "resolved": "https://registry.npmjs.org/cytoscape/-/cytoscape-3.25.0.tgz", + "integrity": "sha512-7MW3Iz57mCUo6JQCho6CmPBCbTlJr7LzyEtIkutG255HLVd4XuBg2I9BkTZLI/e4HoaOB/BiAzXuQybQ95+r9Q==", + "requires": { + "heap": "^0.2.6", + "lodash": "^4.17.21" + } + }, + "cytoscape-cose-bilkent": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/cytoscape-cose-bilkent/-/cytoscape-cose-bilkent-4.1.0.tgz", + "integrity": "sha512-wgQlVIUJF13Quxiv5e1gstZ08rnZj2XaLHGoFMYXz7SkNfCDOOteKBE6SYRfA9WxxI/iBc3ajfDoc6hb/MRAHQ==", + "requires": { + "cose-base": "^1.0.0" + } + }, + "cytoscape-fcose": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/cytoscape-fcose/-/cytoscape-fcose-2.2.0.tgz", + "integrity": "sha512-ki1/VuRIHFCzxWNrsshHYPs6L7TvLu3DL+TyIGEsRcvVERmxokbf5Gdk7mFxZnTdiGtnA4cfSmjZJMviqSuZrQ==", + "requires": { + "cose-base": "^2.2.0" + }, + "dependencies": { + "cose-base": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/cose-base/-/cose-base-2.2.0.tgz", + "integrity": "sha512-AzlgcsCbUMymkADOJtQm3wO9S3ltPfYOFD5033keQn9NJzIbtnZj+UdBJe7DYml/8TdbtHJW3j58SOnKhWY/5g==", + "requires": { + "layout-base": "^2.0.0" + } + }, + "layout-base": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/layout-base/-/layout-base-2.0.1.tgz", + "integrity": "sha512-dp3s92+uNI1hWIpPGH3jK2kxE2lMjdXdr+DH8ynZHpd6PUlH6x6cbuXnoMmiNumznqaNO31xu9e79F0uuZ0JFg==" + } + } + }, + "d3": { + "version": "7.8.5", + "resolved": "https://registry.npmjs.org/d3/-/d3-7.8.5.tgz", + "integrity": "sha512-JgoahDG51ncUfJu6wX/1vWQEqOflgXyl4MaHqlcSruTez7yhaRKR9i8VjjcQGeS2en/jnFivXuaIMnseMMt0XA==", + "requires": { + "d3-array": "3", + "d3-axis": "3", + "d3-brush": "3", + "d3-chord": "3", + "d3-color": "3", + "d3-contour": "4", + "d3-delaunay": "6", + "d3-dispatch": "3", + "d3-drag": "3", + "d3-dsv": "3", + "d3-ease": "3", + "d3-fetch": "3", + "d3-force": "3", + "d3-format": "3", + "d3-geo": "3", + "d3-hierarchy": "3", + "d3-interpolate": "3", + "d3-path": "3", + "d3-polygon": "3", + "d3-quadtree": "3", + "d3-random": "3", + "d3-scale": "4", + "d3-scale-chromatic": "3", + "d3-selection": "3", + "d3-shape": "3", + "d3-time": "3", + "d3-time-format": "4", + "d3-timer": "3", + "d3-transition": "3", + "d3-zoom": "3" + } + }, + "d3-array": { + "version": "3.2.4", + "resolved": "https://registry.npmjs.org/d3-array/-/d3-array-3.2.4.tgz", + "integrity": "sha512-tdQAmyA18i4J7wprpYq8ClcxZy3SC31QMeByyCFyRt7BVHdREQZ5lpzoe5mFEYZUWe+oq8HBvk9JjpibyEV4Jg==", + "requires": { + "internmap": "1 - 2" + } + }, + "d3-axis": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-axis/-/d3-axis-3.0.0.tgz", + "integrity": "sha512-IH5tgjV4jE/GhHkRV0HiVYPDtvfjHQlQfJHs0usq7M30XcSBvOotpmH1IgkcXsO/5gEQZD43B//fc7SRT5S+xw==" + }, + "d3-brush": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-brush/-/d3-brush-3.0.0.tgz", + "integrity": "sha512-ALnjWlVYkXsVIGlOsuWH1+3udkYFI48Ljihfnh8FZPF2QS9o+PzGLBslO0PjzVoHLZ2KCVgAM8NVkXPJB2aNnQ==", + "requires": { + "d3-dispatch": "1 - 3", + "d3-drag": "2 - 3", + "d3-interpolate": "1 - 3", + "d3-selection": "3", + "d3-transition": "3" + } + }, + "d3-chord": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-chord/-/d3-chord-3.0.1.tgz", + "integrity": "sha512-VE5S6TNa+j8msksl7HwjxMHDM2yNK3XCkusIlpX5kwauBfXuyLAtNg9jCp/iHH61tgI4sb6R/EIMWCqEIdjT/g==", + "requires": { + "d3-path": "1 - 3" + } + }, + "d3-color": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-color/-/d3-color-3.1.0.tgz", + "integrity": "sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==" + }, + "d3-contour": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/d3-contour/-/d3-contour-4.0.2.tgz", + "integrity": "sha512-4EzFTRIikzs47RGmdxbeUvLWtGedDUNkTcmzoeyg4sP/dvCexO47AaQL7VKy/gul85TOxw+IBgA8US2xwbToNA==", + "requires": { + "d3-array": "^3.2.0" + } + }, + "d3-delaunay": { + "version": "6.0.4", + "resolved": "https://registry.npmjs.org/d3-delaunay/-/d3-delaunay-6.0.4.tgz", + "integrity": "sha512-mdjtIZ1XLAM8bm/hx3WwjfHt6Sggek7qH043O8KEjDXN40xi3vx/6pYSVTwLjEgiXQTbvaouWKynLBiUZ6SK6A==", + "requires": { + "delaunator": "5" + } + }, + "d3-dispatch": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-dispatch/-/d3-dispatch-3.0.1.tgz", + "integrity": "sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==" + }, + "d3-drag": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-drag/-/d3-drag-3.0.0.tgz", + "integrity": "sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==", + "requires": { + "d3-dispatch": "1 - 3", + "d3-selection": "3" + } + }, + "d3-dsv": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-dsv/-/d3-dsv-3.0.1.tgz", + "integrity": "sha512-UG6OvdI5afDIFP9w4G0mNq50dSOsXHJaRE8arAS5o9ApWnIElp8GZw1Dun8vP8OyHOZ/QJUKUJwxiiCCnUwm+Q==", + "requires": { + "commander": "7", + "iconv-lite": "0.6", + "rw": "1" + }, + "dependencies": { + "commander": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-7.2.0.tgz", + "integrity": "sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw==" + }, + "iconv-lite": { + "version": "0.6.3", + "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz", + "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==", + "requires": { + "safer-buffer": ">= 2.1.2 < 3.0.0" + } + } + } + }, + "d3-ease": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-ease/-/d3-ease-3.0.1.tgz", + "integrity": "sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==" + }, + "d3-fetch": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-fetch/-/d3-fetch-3.0.1.tgz", + "integrity": "sha512-kpkQIM20n3oLVBKGg6oHrUchHM3xODkTzjMoj7aWQFq5QEM+R6E4WkzT5+tojDY7yjez8KgCBRoj4aEr99Fdqw==", + "requires": { + "d3-dsv": "1 - 3" + } + }, + "d3-force": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-force/-/d3-force-3.0.0.tgz", + "integrity": "sha512-zxV/SsA+U4yte8051P4ECydjD/S+qeYtnaIyAs9tgHCqfguma/aAQDjo85A9Z6EKhBirHRJHXIgJUlffT4wdLg==", + "requires": { + "d3-dispatch": "1 - 3", + "d3-quadtree": "1 - 3", + "d3-timer": "1 - 3" + } + }, + "d3-format": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-format/-/d3-format-3.1.0.tgz", + "integrity": "sha512-YyUI6AEuY/Wpt8KWLgZHsIU86atmikuoOmCfommt0LYHiQSPjvX2AcFc38PX0CBpr2RCyZhjex+NS/LPOv6YqA==" + }, + "d3-geo": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-geo/-/d3-geo-3.1.0.tgz", + "integrity": "sha512-JEo5HxXDdDYXCaWdwLRt79y7giK8SbhZJbFWXqbRTolCHFI5jRqteLzCsq51NKbUoX0PjBVSohxrx+NoOUujYA==", + "requires": { + "d3-array": "2.5.0 - 3" + } + }, + "d3-hierarchy": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/d3-hierarchy/-/d3-hierarchy-3.1.2.tgz", + "integrity": "sha512-FX/9frcub54beBdugHjDCdikxThEqjnR93Qt7PvQTOHxyiNCAlvMrHhclk3cD5VeAaq9fxmfRp+CnWw9rEMBuA==" + }, + "d3-interpolate": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-interpolate/-/d3-interpolate-3.0.1.tgz", + "integrity": "sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==", + "requires": { + "d3-color": "1 - 3" + } + }, + "d3-path": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-path/-/d3-path-3.1.0.tgz", + "integrity": "sha512-p3KP5HCf/bvjBSSKuXid6Zqijx7wIfNW+J/maPs+iwR35at5JCbLUT0LzF1cnjbCHWhqzQTIN2Jpe8pRebIEFQ==" + }, + "d3-polygon": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-polygon/-/d3-polygon-3.0.1.tgz", + "integrity": "sha512-3vbA7vXYwfe1SYhED++fPUQlWSYTTGmFmQiany/gdbiWgU/iEyQzyymwL9SkJjFFuCS4902BSzewVGsHHmHtXg==" + }, + "d3-quadtree": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-quadtree/-/d3-quadtree-3.0.1.tgz", + "integrity": "sha512-04xDrxQTDTCFwP5H6hRhsRcb9xxv2RzkcsygFzmkSIOJy3PeRJP7sNk3VRIbKXcog561P9oU0/rVH6vDROAgUw==" + }, + "d3-random": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-random/-/d3-random-3.0.1.tgz", + "integrity": "sha512-FXMe9GfxTxqd5D6jFsQ+DJ8BJS4E/fT5mqqdjovykEB2oFbTMDVdg1MGFxfQW+FBOGoB++k8swBrgwSHT1cUXQ==" + }, + "d3-scale": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/d3-scale/-/d3-scale-4.0.2.tgz", + "integrity": "sha512-GZW464g1SH7ag3Y7hXjf8RoUuAFIqklOAq3MRl4OaWabTFJY9PN/E1YklhXLh+OQ3fM9yS2nOkCoS+WLZ6kvxQ==", + "requires": { + "d3-array": "2.10.0 - 3", + "d3-format": "1 - 3", + "d3-interpolate": "1.2.0 - 3", + "d3-time": "2.1.1 - 3", + "d3-time-format": "2 - 4" + } + }, + "d3-scale-chromatic": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-scale-chromatic/-/d3-scale-chromatic-3.0.0.tgz", + "integrity": "sha512-Lx9thtxAKrO2Pq6OO2Ua474opeziKr279P/TKZsMAhYyNDD3EnCffdbgeSYN5O7m2ByQsxtuP2CSDczNUIZ22g==", + "requires": { + "d3-color": "1 - 3", + "d3-interpolate": "1 - 3" + } + }, + "d3-selection": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz", + "integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==" + }, + "d3-shape": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/d3-shape/-/d3-shape-3.2.0.tgz", + "integrity": "sha512-SaLBuwGm3MOViRq2ABk3eLoxwZELpH6zhl3FbAoJ7Vm1gofKx6El1Ib5z23NUEhF9AsGl7y+dzLe5Cw2AArGTA==", + "requires": { + "d3-path": "^3.1.0" + } + }, + "d3-time": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-time/-/d3-time-3.1.0.tgz", + "integrity": "sha512-VqKjzBLejbSMT4IgbmVgDjpkYrNWUYJnbCGo874u7MMKIWsILRX+OpX/gTk8MqjpT1A/c6HY2dCA77ZN0lkQ2Q==", + "requires": { + "d3-array": "2 - 3" + } + }, + "d3-time-format": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/d3-time-format/-/d3-time-format-4.1.0.tgz", + "integrity": "sha512-dJxPBlzC7NugB2PDLwo9Q8JiTR3M3e4/XANkreKSUxF8vvXKqm1Yfq4Q5dl8budlunRVlUUaDUgFt7eA8D6NLg==", + "requires": { + "d3-time": "1 - 3" + } + }, + "d3-timer": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-timer/-/d3-timer-3.0.1.tgz", + "integrity": "sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==" + }, + "d3-transition": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-transition/-/d3-transition-3.0.1.tgz", + "integrity": "sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w==", + "requires": { + "d3-color": "1 - 3", + "d3-dispatch": "1 - 3", + "d3-ease": "1 - 3", + "d3-interpolate": "1 - 3", + "d3-timer": "1 - 3" + } + }, + "d3-zoom": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-zoom/-/d3-zoom-3.0.0.tgz", + "integrity": "sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==", + "requires": { + "d3-dispatch": "1 - 3", + "d3-drag": "2 - 3", + "d3-interpolate": "1 - 3", + "d3-selection": "2 - 3", + "d3-transition": "2 - 3" + } + }, + "dagre-d3-es": { + "version": "7.0.9", + "resolved": "https://registry.npmjs.org/dagre-d3-es/-/dagre-d3-es-7.0.9.tgz", + "integrity": "sha512-rYR4QfVmy+sR44IBDvVtcAmOReGBvRCWDpO2QjYwqgh9yijw6eSHBqaPG/LIOEy7aBsniLvtMW6pg19qJhq60w==", + "requires": { + "d3": "^7.8.2", + "lodash-es": "^4.17.21" + } + }, "damerau-levenshtein": { "version": "1.0.8", "resolved": "https://registry.npmjs.org/damerau-levenshtein/-/damerau-levenshtein-1.0.8.tgz", "integrity": "sha512-sdQSFB7+llfUcQHUQO3+B8ERRj0Oa4w9POWMI/puGtuf7gFywGmkaLCElnudfTiKZV+NvHqL0ifzdrI8Ro7ESA==", "dev": true }, + "dayjs": { + "version": "1.11.9", + "resolved": "https://registry.npmjs.org/dayjs/-/dayjs-1.11.9.tgz", + "integrity": "sha512-QvzAURSbQ0pKdIye2txOzNaHmxtUBXerpY0FJsFXUMKbIZeFm5ht1LS/jFsrncjnmtv8HsG0W2g6c0zUjZWmpA==" + }, "debug": { "version": "4.3.4", "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.4.tgz", @@ -26457,6 +27425,14 @@ "slash": "^3.0.0" } }, + "delaunator": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/delaunator/-/delaunator-5.0.0.tgz", + "integrity": "sha512-AyLvtyJdbv/U1GkiS6gUUzclRoAY4Gs75qkMygJJhU75LW4DNuSF2RMzpxs9jw9Oz1BobHjTdkG3zdP55VxAqw==", + "requires": { + "robust-predicates": "^3.0.0" + } + }, "depd": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz", @@ -26584,6 +27560,11 @@ "domelementtype": "^2.3.0" } }, + "dompurify": { + "version": "2.4.3", + "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-2.4.3.tgz", + "integrity": "sha512-q6QaLcakcRjebxjg8/+NP+h0rPfatOgOzc46Fst9VAA3jF2ApfKBNKMzdP4DYTqtUMXSCd5pRS/8Po/OmoCHZQ==" + }, "domutils": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/domutils/-/domutils-3.1.0.tgz", @@ -26648,6 +27629,11 @@ "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.421.tgz", "integrity": "sha512-wZOyn3s/aQOtLGAwXMZfteQPN68kgls2wDAnYOA8kCjBvKVrW5RwmWVspxJYTqrcN7Y263XJVsC66VCIGzDO3g==" }, + "elkjs": { + "version": "0.8.2", + "resolved": "https://registry.npmjs.org/elkjs/-/elkjs-0.8.2.tgz", + "integrity": "sha512-L6uRgvZTH+4OF5NE/MBbzQx/WYpru1xCBE9respNj6qznEewGUIfhzmm7horWWxbNO2M0WckQypGctR8lH79xQ==" + }, "emoji-regex": { "version": "9.2.2", "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz", @@ -28265,6 +29251,11 @@ "resolved": "https://registry.npmjs.org/he/-/he-1.2.0.tgz", "integrity": "sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw==" }, + "heap": { + "version": "0.2.7", + "resolved": "https://registry.npmjs.org/heap/-/heap-0.2.7.tgz", + "integrity": "sha512-2bsegYkkHO+h/9MGbn6KWcE45cHZgPANo5LXF7EvWdT0yT2EguSVO1nDgU5c8+ZOPwp2vMNa7YFsJhVcDR9Sdg==" + }, "history": { "version": "4.10.1", "resolved": "https://registry.npmjs.org/history/-/history-4.10.1.tgz", @@ -28696,6 +29687,11 @@ "side-channel": "^1.0.4" } }, + "internmap": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/internmap/-/internmap-2.0.3.tgz", + "integrity": "sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg==" + }, "interpret": { "version": "1.4.0", "resolved": "https://registry.npmjs.org/interpret/-/interpret-1.4.0.tgz", @@ -29261,6 +30257,11 @@ "json-buffer": "3.0.0" } }, + "khroma": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/khroma/-/khroma-2.0.0.tgz", + "integrity": "sha512-2J8rDNlQWbtiNYThZRvmMv5yt44ZakX+Tz5ZIp/mN1pt4snn+m030Va5Z4v8xA0cQFDXBwO/8i42xL4QPsVk3g==" + }, "kind-of": { "version": "6.0.3", "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz", @@ -29322,6 +30323,11 @@ "shell-quote": "^1.7.3" } }, + "layout-base": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/layout-base/-/layout-base-1.0.2.tgz", + "integrity": "sha512-8h2oVEZNktL4BH2JCOI90iD1yXwL6iNW7KcCKT2QZgQJR2vbqDsldCTPRU9NifTCqHZci57XvQQ15YTu+sTYPg==" + }, "leven": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/leven/-/leven-3.1.0.tgz", @@ -29518,6 +30524,11 @@ "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==" }, + "lodash-es": { + "version": "4.17.21", + "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.21.tgz", + "integrity": "sha512-mKnC+QJ9pWVzv+C4/U3rRsHapFfHvQFoFB92e52xeyGMcX6/OlIl78je1u8vePzYZSkkogMPJ2yjxxsb89cxyw==" + }, "lodash.curry": { "version": "4.1.1", "resolved": "https://registry.npmjs.org/lodash.curry/-/lodash.curry-4.1.1.tgz", @@ -30288,6 +31299,36 @@ "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz", "integrity": "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==" }, + "mermaid": { + "version": "9.4.3", + "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-9.4.3.tgz", + "integrity": "sha512-TLkQEtqhRSuEHSE34lh5bCa94KATCyluAXmFnNI2PRZwOpXFeqiJWwZl+d2CcemE1RS6QbbueSSq9QIg8Uxcyw==", + "requires": { + "@braintree/sanitize-url": "^6.0.0", + "cytoscape": "^3.23.0", + "cytoscape-cose-bilkent": "^4.1.0", + "cytoscape-fcose": "^2.1.0", + "d3": "^7.4.0", + "dagre-d3-es": "7.0.9", + "dayjs": "^1.11.7", + "dompurify": "2.4.3", + "elkjs": "^0.8.2", + "khroma": "^2.0.0", + "lodash-es": "^4.17.21", + "non-layered-tidy-tree-layout": "^2.0.2", + "stylis": "^4.1.2", + "ts-dedent": "^2.2.0", + "uuid": "^9.0.0", + "web-worker": "^1.2.0" + }, + "dependencies": { + "uuid": { + "version": "9.0.0", + "resolved": "https://registry.npmjs.org/uuid/-/uuid-9.0.0.tgz", + "integrity": "sha512-MXcSTerfPa4uqyzStbRoTgt5XIe3x5+42+q1sDuy3R5MDk66URdLMOZe5aPX/SQd+kuYAh0FdP/pO28IkQyTeg==" + } + } + }, "methods": { "version": "1.1.2", "resolved": "https://registry.npmjs.org/methods/-/methods-1.1.2.tgz", @@ -30729,6 +31770,11 @@ "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.12.tgz", "integrity": "sha512-QzsYKWhXTWx8h1kIvqfnC++o0pEmpRQA/aenALsL2F4pqNVr7YzcdMlDij5WBnwftRbJCNJL/O7zdKaxKPHqgQ==" }, + "non-layered-tidy-tree-layout": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/non-layered-tidy-tree-layout/-/non-layered-tidy-tree-layout-2.0.2.tgz", + "integrity": "sha512-gkXMxRzUH+PB0ax9dUN0yYF0S25BqeAYqhgMaLUFmpXLEk7Fcu8f4emJuOAY0V8kjDICxROIKsTAKsV/v355xw==" + }, "normalize-package-data": { "version": "3.0.3", "resolved": "https://registry.npmjs.org/normalize-package-data/-/normalize-package-data-3.0.3.tgz", @@ -32021,6 +33067,15 @@ "resolved": "https://registry.npmjs.org/react-lifecycles-compat/-/react-lifecycles-compat-3.0.4.tgz", "integrity": "sha512-fBASbA6LnOU9dOU2eW7aQ8xmYBSXUIWr+UmF9b1efZBazGNO+rcXT/icdKnYm2pTwcRylVUYwW7H1PHfLekVzA==" }, + "react-loadable": { + "version": "5.5.0", + "resolved": "https://registry.npmjs.org/react-loadable/-/react-loadable-5.5.0.tgz", + "integrity": "sha512-C8Aui0ZpMd4KokxRdVAm2bQtI03k2RMRNzOB+IipV3yxFTSVICv7WoUr5L9ALB5BmKO1iHgZtWM8EvYG83otdg==", + "peer": true, + "requires": { + "prop-types": "^15.5.0" + } + }, "react-loadable-ssr-addon-v5-slorber": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/react-loadable-ssr-addon-v5-slorber/-/react-loadable-ssr-addon-v5-slorber-1.0.1.tgz", @@ -34788,6 +35843,11 @@ "glob": "^7.1.3" } }, + "robust-predicates": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/robust-predicates/-/robust-predicates-3.0.2.tgz", + "integrity": "sha512-IXgzBWvWQwE6PrDI05OvmXUIruQTcoMDzRsOd5CDvHCVLcLHMTSYvOK5Cm46kWqlV3yAbuSpBZdJ5oP5OUoStg==" + }, "rtl-detect": { "version": "1.0.4", "resolved": "https://registry.npmjs.org/rtl-detect/-/rtl-detect-1.0.4.tgz", @@ -34818,6 +35878,11 @@ "queue-microtask": "^1.2.2" } }, + "rw": { + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/rw/-/rw-1.3.3.tgz", + "integrity": "sha512-PdhdWy89SiZogBLaw42zdeqtRJ//zFd2PgQavcICDUgJT5oW10QCRKbJ6bg4r0/UY2M6BWd5tkxuGFRvCkgfHQ==" + }, "rxjs": { "version": "7.8.1", "resolved": "https://registry.npmjs.org/rxjs/-/rxjs-7.8.1.tgz", @@ -35610,6 +36675,11 @@ "stylelint-config-recommended": "^9.0.0" } }, + "stylis": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/stylis/-/stylis-4.3.0.tgz", + "integrity": "sha512-E87pIogpwUsUwXw7dNyU4QDjdgVMy52m+XEOPEKUn161cCzWjjhPSQhByfd1CcNvrOLnXQ6OnnZDwnJrz/Z4YQ==" + }, "supports-color": { "version": "5.5.0", "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", @@ -35982,6 +37052,11 @@ "resolved": "https://registry.npmjs.org/trough/-/trough-1.0.5.tgz", "integrity": "sha512-rvuRbTarPXmMb79SmzEp8aqXNKcK+y0XaB298IXueQ8I2PsrATcPBCSPyK/dDNa2iWOhKlfNnOjdAOTBU/nkFA==" }, + "ts-dedent": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/ts-dedent/-/ts-dedent-2.2.0.tgz", + "integrity": "sha512-q5W7tVM71e2xjHZTlgfTDoPF/SmqKG5hddq9SzR49CH2hayqRKJtQ4mtRlSxKaJlR/+9rEM+mnBHf7I2/BQcpQ==" + }, "tsconfig-paths": { "version": "3.14.2", "resolved": "https://registry.npmjs.org/tsconfig-paths/-/tsconfig-paths-3.14.2.tgz", @@ -36688,6 +37763,11 @@ "resolved": "https://registry.npmjs.org/web-namespaces/-/web-namespaces-1.1.4.tgz", "integrity": "sha512-wYxSGajtmoP4WxfejAPIr4l0fVh+jeMXZb08wNc0tMg6xsfZXj3cECqIK0G7ZAqUq0PP8WlMDtaOGVBTAWztNw==" }, + "web-worker": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/web-worker/-/web-worker-1.2.0.tgz", + "integrity": "sha512-PgF341avzqyx60neE9DD+XS26MMNMoUQRz9NOZwW32nPQrF6p77f1htcnjBSEV8BGMKZ16choqUG4hyI0Hx7mA==" + }, "webidl-conversions": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz", diff --git a/package.json b/package.json index e425f273a..f0255fafe 100644 --- a/package.json +++ b/package.json @@ -31,6 +31,7 @@ "dependencies": { "@docusaurus/core": "^2.4.0", "@docusaurus/preset-classic": "^2.4.0", + "@docusaurus/theme-mermaid": "^2.4.1", "@easyops-cn/docusaurus-search-local": "^0.35.0", "@mdx-js/react": "^1.6.22", "@node-rs/jieba": "^1.7.0", From 87c93739703cfed81a15e89d71e9be6abc17adf4 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Thu, 13 Jul 2023 17:58:14 +0600 Subject: [PATCH 09/20] updating as per review Signed-off-by: Mahfuza --- .vscode/settings.json | 5 +- docs/contribute/plugin/develop_plugin_c.md | 67 ++-- docs/contribute/plugin/develop_plugin_cpp.md | 363 ++++++++---------- .../plugin/develop_plugin_rustsdk.md | 82 ++-- 4 files changed, 228 insertions(+), 289 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 323c8ce0a..a3b8eabea 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,4 +1,3 @@ { - "cSpell.words": ["bytecode", "CNCF", "Emscripten", "wasmedge"], - "docwriter.style": "Auto-detect" -} + "cSpell.words": ["bytecode", "CNCF", "Emscripten", "wasmedge"] +} \ No newline at end of file diff --git a/docs/contribute/plugin/develop_plugin_c.md b/docs/contribute/plugin/develop_plugin_c.md index 4b8fb0b5d..6f399d62c 100644 --- a/docs/contribute/plugin/develop_plugin_c.md +++ b/docs/contribute/plugin/develop_plugin_c.md @@ -30,19 +30,6 @@ To start developing WasmEdge plugins, it is essential to set up the development To see a list of supported plugins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plugins and dependencies section. -- **Install a compatible compiler**: The following compilers can be used to compile C code into WebAssembly bytecode: - - - LLVM: `sudo apt-get install llvm` - - GCC: `sudo apt-get install gcc` - -- **Install necessary tools and dependencies**: You can use any text editor or IDE of your choice to write code. Here are some popular options: - - - [Visual Studio Code](https://code.visualstudio.com/) - - [Atom](https://atom.io/) - - [Sublime Text](https://www.sublimetext.com/) - - For debugging, you can use GDB, LLDB, or other debuggers that support WebAssembly. To install GDB, run `sudo apt-get install gdb`. - - **Enable specific backends or additional components (if applicable):** Some plugins may require enabling specific backends or additional components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) @@ -80,33 +67,33 @@ To create a plug-in with host functions and modules, follow these steps: For the more details about the [external data](/embed/c/host_function.md#host-data) and [calling frame context](/embed/c/host_function.md#calling-frame-context), please refer to the host function guide. ::: -Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers respectively: - -```c -#include - -/* The host function definitions. */ - -/* The host function to add 2 int32_t numbers. */ -WasmEdge_Result HostFuncAdd(void *Data, - const WasmEdge_CallingFrameContext *CallFrameCxt, - const WasmEdge_Value *In, WasmEdge_Value *Out) { - int32_t Val1 = WasmEdge_ValueGetI32(In[0]); - int32_t Val2 = WasmEdge_ValueGetI32(In[1]); - Out[0] = WasmEdge_ValueGenI32(Val1 + Val2); - return WasmEdge_Result_Success; -} - -/* The host function to sub 2 int32_t numbers. */ -WasmEdge_Result HostFuncSub(void *Data, - const WasmEdge_CallingFrameContext *CallFrameCxt, - const WasmEdge_Value *In, WasmEdge_Value *Out) { - int32_t Val1 = WasmEdge_ValueGetI32(In[0]); - int32_t Val2 = WasmEdge_ValueGetI32(In[1]); - Out[0] = WasmEdge_ValueGenI32(Val1 - Val2); - return WasmEdge_Result_Success; -} -``` + Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers respectively: + + ```c + #include + + /* The host function definitions. */ + + /* The host function to add 2 int32_t numbers. */ + WasmEdge_Result HostFuncAdd(void *Data, + const WasmEdge_CallingFrameContext *CallFrameCxt, + const WasmEdge_Value *In, WasmEdge_Value *Out) { + int32_t Val1 = WasmEdge_ValueGetI32(In[0]); + int32_t Val2 = WasmEdge_ValueGetI32(In[1]); + Out[0] = WasmEdge_ValueGenI32(Val1 + Val2); + return WasmEdge_Result_Success; + } + + /* The host function to sub 2 int32_t numbers. */ + WasmEdge_Result HostFuncSub(void *Data, + const WasmEdge_CallingFrameContext *CallFrameCxt, + const WasmEdge_Value *In, WasmEdge_Value *Out) { + int32_t Val1 = WasmEdge_ValueGetI32(In[0]); + int32_t Val2 = WasmEdge_ValueGetI32(In[1]); + Out[0] = WasmEdge_ValueGenI32(Val1 - Val2); + return WasmEdge_Result_Success; + } + ``` - **Implement the module creation functions**: In this step, you need to implement the module creation function that creates an instance of the module. This function will be called when the plugin is loaded. diff --git a/docs/contribute/plugin/develop_plugin_cpp.md b/docs/contribute/plugin/develop_plugin_cpp.md index 905c6f66c..4e8ed3cd2 100644 --- a/docs/contribute/plugin/develop_plugin_cpp.md +++ b/docs/contribute/plugin/develop_plugin_cpp.md @@ -36,23 +36,11 @@ This flowchart illustrates the process of developing a WasmEdge plugin, showcasi To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - - **Build WasmEdge from source**: For developing WasmEdge plugin in C++ language, you will need to build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. + - **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your own plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. To see a list of supported plugins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plugins and dependencies section. -- **Install a compatible compiler**: The following compilers can be used to compile C++ code into WebAssembly bytecode: - - - LLVM: `sudo apt-get install llvm` - - GCC: `sudo apt-get install gcc` - -- **Install necessary tools and dependencies**: You can use any text editor or IDE of your choice to write code. Here are some popular options: - - - [Visual Studio Code](https://code.visualstudio.com/) - - [Atom](https://atom.io/) - - [Sublime Text](https://www.sublimetext.com/) - - For debugging, you can use GDB, LLDB, or other debuggers that support WebAssembly. To install GDB, run `sudo apt-get install gdb`. - - **Enable specific backends or additional components (if applicable):** Some plugins may require enabling specific backends or additional components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) @@ -73,24 +61,7 @@ To create a WasmEdge plugin project, follow these steps: mkdir src include build ``` -- **Add configuration files**: Add configuration files specifying the plugin name, version, and dependencies. The specific files and their content depend on the chosen programming language and build system. - - Create a `CMakeLists.txt` file in the root directory with the necessary configuration to specify the plugin name, version, and dependencies. The `find_package(WasmEdge REQUIRED)` line locates the WasmEdge runtime library and makes it available for the project. - - ```cmake - cmake_minimum_required(VERSION 3.14) - project(testplugin VERSION 0.1.0) - - find_package(WasmEdge REQUIRED) - - add_library(testplugin SHARED src/testplugin.cpp) - target_compile_features(testplugin PUBLIC cxx_std_11) - target_include_directories(testplugin PUBLIC include) - target_link_libraries(testplugin PRIVATE ${WASMEDGE_LIBRARIES}) - set_target_properties(testplugin PROPERTIES PREFIX "") - ``` - -- **Add necessary libraries or dependencies**: Include any required libraries or dependencies for your plugin. Modify the configuration files created in the previous step to include the necessary dependencies. For example, in the `CMakeLists.txt` file, use the `find_package` command to locate the WasmEdge runtime library and link it to your plugin. +- **Add necessary libraries or dependencies**: Include any required libraries or dependencies for your plugin. Modify the configuration files created in the previous step to include the necessary dependencies. ## Write plugin code @@ -98,141 +69,141 @@ To create a plug-in with host functions and modules, follow these steps: - **Host Functions and Modules**: The goal of the plug-in is to provide the host functions which can be imported when instantiating WASM. Therefore, developers should implement their plug-in host functions in WasmEdge internal C++ first. Assume that the host function implementations are in the `testplugin.h`. -```cpp -#pragma once - -#include "plugin/plugin.h" - -#include -#include - -namespace WasmEdge { -namespace Host { - -// The environment class. For the register object. -class WasmEdgePluginTestEnv { -public: - WasmEdgePluginTestEnv() noexcept = default; - - static Plugin::PluginRegister Register; -}; - -// The host function base template class. For inheriting the environment class -// reference. -template -class WasmEdgePluginTestFunc : public Runtime::HostFunction { -public: - WasmEdgePluginTestFunc(WasmEdgePluginTestEnv &HostEnv) - : Runtime::HostFunction(0), Env(HostEnv) {} - -protected: - WasmEdgePluginTestEnv &Env; -}; - -// The host function to add 2 int32_t numbers. -class WasmEdgePluginTestFuncAdd - : public WasmEdgePluginTestFunc { -public: - WasmEdgePluginTestFuncAdd(WasmEdgePluginTestEnv &HostEnv) - : WasmEdgePluginTestFunc(HostEnv) {} - Expect body(const Runtime::CallingFrame &, uint32_t A, uint32_t B) { - return A + B; - } -}; - -// The host function to sub 2 int32_t numbers. -class WasmEdgePluginTestFuncSub - : public WasmEdgePluginTestFunc { -public: - WasmEdgePluginTestFuncSub(WasmEdgePluginTestEnv &HostEnv) - : WasmEdgePluginTestFunc(HostEnv) {} - Expect body(const Runtime::CallingFrame &, uint32_t A, uint32_t B) { - return A - B; - } -}; - -// The host module class. There can be several modules in a plug-in. -class WasmEdgePluginTestModule : public Runtime::Instance::ModuleInstance { -public: - WasmEdgePluginTestModule() - : Runtime::Instance::ModuleInstance("wasmedge_plugintest_cpp_module") { - addHostFunc("add", std::make_unique(Env)); - addHostFunc("sub", std::make_unique(Env)); - } - - WasmEdgePluginTestEnv &getEnv() { return Env; } - -private: - WasmEdgePluginTestEnv Env; -}; - -} // namespace Host -} // namespace WasmEdge -``` + ```cpp + #pragma once + + #include "plugin/plugin.h" + + #include + #include + + namespace WasmEdge { + namespace Host { + + // The environment class. For the register object. + class WasmEdgePluginTestEnv { + public: + WasmEdgePluginTestEnv() noexcept = default; + + static Plugin::PluginRegister Register; + }; + + // The host function base template class. For inheriting the environment class + // reference. + template + class WasmEdgePluginTestFunc : public Runtime::HostFunction { + public: + WasmEdgePluginTestFunc(WasmEdgePluginTestEnv &HostEnv) + : Runtime::HostFunction(0), Env(HostEnv) {} + + protected: + WasmEdgePluginTestEnv &Env; + }; + + // The host function to add 2 int32_t numbers. + class WasmEdgePluginTestFuncAdd + : public WasmEdgePluginTestFunc { + public: + WasmEdgePluginTestFuncAdd(WasmEdgePluginTestEnv &HostEnv) + : WasmEdgePluginTestFunc(HostEnv) {} + Expect body(const Runtime::CallingFrame &, uint32_t A, uint32_t B) { + return A + B; + } + }; + + // The host function to sub 2 int32_t numbers. + class WasmEdgePluginTestFuncSub + : public WasmEdgePluginTestFunc { + public: + WasmEdgePluginTestFuncSub(WasmEdgePluginTestEnv &HostEnv) + : WasmEdgePluginTestFunc(HostEnv) {} + Expect body(const Runtime::CallingFrame &, uint32_t A, uint32_t B) { + return A - B; + } + }; + + // The host module class. There can be several modules in a plug-in. + class WasmEdgePluginTestModule : public Runtime::Instance::ModuleInstance { + public: + WasmEdgePluginTestModule() + : Runtime::Instance::ModuleInstance("wasmedge_plugintest_cpp_module") { + addHostFunc("add", std::make_unique(Env)); + addHostFunc("sub", std::make_unique(Env)); + } + + WasmEdgePluginTestEnv &getEnv() { return Env; } + + private: + WasmEdgePluginTestEnv Env; + }; + + } // namespace Host + } // namespace WasmEdge + ``` - **Creation Functions for Modules**: Then developers should implement the module creation functions. Assume that the following implementations are all in the `testplugin.cpp`. -```cpp -#include "testplugin.h" + ```cpp + #include "testplugin.h" -namespace WasmEdge { -namespace Host { -namespace { + namespace WasmEdge { + namespace Host { + namespace { -Runtime::Instance::ModuleInstance * -create(const Plugin::PluginModule::ModuleDescriptor *) noexcept { - // There can be several modules in a plug-in. For that, developers should - // implement several `create` functions for each module. - return new WasmEdgePluginTestModule; -} + Runtime::Instance::ModuleInstance * + create(const Plugin::PluginModule::ModuleDescriptor *) noexcept { + // There can be several modules in a plug-in. For that, developers should + // implement several `create` functions for each module. + return new WasmEdgePluginTestModule; + } -} // namespace -} // namespace Host -} // namespace WasmEdge -``` + } // namespace + } // namespace Host + } // namespace WasmEdge + ``` - **Plug-in Descriptions**: For constructing the plug-in, developers should supply the descriptions of this plug-in and the modules. -```cpp -namespace WasmEdge { -namespace Host { -namespace { - -Plugin::Plugin::PluginDescriptor Descriptor{ - // Plug-in name. This is the name for searching the plug-in context by the - // `WasmEdge_PluginFind()` C API. - .Name = "wasmedge_plugintest_cpp", - // Plug-in description. - .Description = "", - // Plug-in API version. - .APIVersion = Plugin::Plugin::CurrentAPIVersion, - // Plug-in version. - .Version = {0, 10, 0, 0}, - // Module count in this plug-in. - .ModuleCount = 1, - // Pointer to module description array. - .ModuleDescriptions = - // The module descriptor array. - (Plugin::PluginModule::ModuleDescriptor[]){ - { - // Module name. This is the name for searching and creating the - // module instance context by the - // `WasmEdge_PluginCreateModule()` C API. - .Name = "wasmedge_plugintest_cpp_module", - // Module description. - .Description = "This is for the plugin tests in WasmEdge.", - // Creation function pointer. - .Create = create, - }, - }, - // Plug-in options (Work in progress). - .AddOptions = nullptr, -}; - -} // namespace -} // namespace Host -} // namespace WasmEdge -``` + ```cpp + namespace WasmEdge { + namespace Host { + namespace { + + Plugin::Plugin::PluginDescriptor Descriptor{ + // Plug-in name. This is the name for searching the plug-in context by the + // `WasmEdge_PluginFind()` C API. + .Name = "wasmedge_plugintest_cpp", + // Plug-in description. + .Description = "", + // Plug-in API version. + .APIVersion = Plugin::Plugin::CurrentAPIVersion, + // Plug-in version. + .Version = {0, 10, 0, 0}, + // Module count in this plug-in. + .ModuleCount = 1, + // Pointer to module description array. + .ModuleDescriptions = + // The module descriptor array. + (Plugin::PluginModule::ModuleDescriptor[]){ + { + // Module name. This is the name for searching and creating the + // module instance context by the + // `WasmEdge_PluginCreateModule()` C API. + .Name = "wasmedge_plugintest_cpp_module", + // Module description. + .Description = "This is for the plugin tests in WasmEdge.", + // Creation function pointer. + .Create = create, + }, + }, + // Plug-in options (Work in progress). + .AddOptions = nullptr, + }; + + } // namespace + } // namespace Host + } // namespace WasmEdge + ``` - **Plug-in Options**: WORK IN PROGRESS. This section is reserved for the feature in the future. @@ -256,54 +227,50 @@ By following these steps and implementing the necessary functions and descriptor To build the plug-in shared library, developers should build in cmake with the WasmEdge source. -Assume that the folder `test` is created under the `/plugins`. - -Add this line in the `/plugins/CMakeLists.txt`: +- Assume that the folder named `test` is created under the `/plugins`. Add this line in the `/plugins/CMakeLists.txt`: -```cmake -add_subdirectory(test) -``` + ```cmake + add_subdirectory(test) + ``` -Copy the `testplugin.h` and `testplugin.cpp` into the `/plugins/test` directory. +- Copy the `testplugin.h` and `testplugin.cpp` into the `/plugins/test` directory. And then edit the file `/plugins/test/CMakeLists.txt`: -And then edit the file `/plugins/test/CMakeLists.txt`: + ```cmake + wasmedge_add_library(wasmedgePluginTest + SHARED + testplugin.cpp + ) -```cmake -wasmedge_add_library(wasmedgePluginTest - SHARED - testplugin.cpp -) + target_compile_options(wasmedgePluginTest + PUBLIC + -DWASMEDGE_PLUGIN + ) -target_compile_options(wasmedgePluginTest - PUBLIC - -DWASMEDGE_PLUGIN -) + if(CMAKE_SYSTEM_NAME MATCHES "Darwin") + target_link_options(wasmedgePluginTest + PUBLIC + -Wl,-U,__ZN8WasmEdge6Plugin14PluginRegisterC1EPKNS0_6Plugin16PluginDescriptorE + -Wl,-U,__ZN8WasmEdge6Plugin14PluginRegisterD1Ev + ) + endif() -if(CMAKE_SYSTEM_NAME MATCHES "Darwin") - target_link_options(wasmedgePluginTest + target_include_directories(wasmedgePluginTest PUBLIC - -Wl,-U,__ZN8WasmEdge6Plugin14PluginRegisterC1EPKNS0_6Plugin16PluginDescriptorE - -Wl,-U,__ZN8WasmEdge6Plugin14PluginRegisterD1Ev - ) -endif() - -target_include_directories(wasmedgePluginTest - PUBLIC - $ - ${CMAKE_CURRENT_SOURCE_DIR} -) - -if(WASMEDGE_LINK_PLUGINS_STATIC) - target_link_libraries(wasmedgePluginTest - PRIVATE - wasmedgeCAPI - ) -else() - target_link_libraries(wasmedgePluginTest - PRIVATE - wasmedge_shared + $ + ${CMAKE_CURRENT_SOURCE_DIR} ) -endif() -``` + + if(WASMEDGE_LINK_PLUGINS_STATIC) + target_link_libraries(wasmedgePluginTest + PRIVATE + wasmedgeCAPI + ) + else() + target_link_libraries(wasmedgePluginTest + PRIVATE + wasmedge_shared + ) + endif() + ``` Follow the guide to [build WasmEdge from source](../source/os/linux.md), according to your specific operating system (e.g., Linux). This will include building the plug-in shared library along with WasmEdge. diff --git a/docs/contribute/plugin/develop_plugin_rustsdk.md b/docs/contribute/plugin/develop_plugin_rustsdk.md index 700c98edd..df24c4827 100644 --- a/docs/contribute/plugin/develop_plugin_rustsdk.md +++ b/docs/contribute/plugin/develop_plugin_rustsdk.md @@ -16,25 +16,11 @@ It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.m To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - - **Build WasmEdge from source**: For developing WasmEdge plugin in C++ language, you will need to build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. Once you complete C++ plugin code, you can use witc[^1] to generate Rust Plugin SDK. + - **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your own plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. To see a list of supported plugins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plugins and dependencies section. -- **Install a compatible compiler**: Rust has its own built-in compiler, which can be installed using rustup: - - ```bash - curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - source $HOME/.cargo/env - ``` - -- **Install necessary tools and dependencies**: You can use any text editor or IDE of your choice to write code. Here are some popular options: - - - [Visual Studio Code](https://code.visualstudio.com/) - - [Atom](https://atom.io/) - - [Sublime Text](https://www.sublimetext.com/) - - For debugging, you can use GDB, LLDB, or other debuggers that support WebAssembly. To install GDB, run `sudo apt-get install gdb`. - - **Enable specific backends or additional components (if applicable):** Some plugins may require enabling specific backends or additional components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) @@ -47,48 +33,48 @@ By following these steps, you can set up the development environment for creatin To develop a WasmEdge Plug-in in Rust using the witc tool, you can follow these steps: -- **Generate Rust Plugin Code**: Consider you have a file named wasmedge_opencvmini.wit with the following content: +- **Generate Rust Plugin Code**: Consider you have a file named `wasmedge_opencvmini.wit` with the following content: -```wit -imdecode: func(buf: list) -> u32 -imshow: func(window-name: string, mat-key: u32) -> unit -waitkey: func(delay: u32) -> unit -``` + ```wit + imdecode: func(buf: list) -> u32 + imshow: func(window-name: string, mat-key: u32) -> unit + waitkey: func(delay: u32) -> unit + ``` -You can use the witc tool to generate Rust plugin code for it by running the following command: + You can use the witc tool to generate Rust plugin code for it by running the following command: -```shell -witc plugin wasmedge_opencvmini.wit -``` + ```shell + witc plugin wasmedge_opencvmini.wit + ``` -- **Create SDK Crate**: Now, you need to create an SDK crate for your plugin. Run the following command to create a new crate named opencvmini-sdk: +- **Create SDK Crate**: Now, you need to create an SDK crate for your plugin. Run the following command to create a new crate named `opencvmini-sdk`: -```shell -cargo new --lib opencvmini-sdk && cd opencvmini-sdk -``` + ```shell + cargo new --lib opencvmini-sdk && cd opencvmini-sdk + ``` -- **Create Module File**: The witc tool puts the Rust code to stdout. To capture the generated code, create a new module file named src/generated.rs and run the following command: +- **Create Module File**: The witc tool puts the Rust code to stdout. To capture the generated code, create a new module file named `src/generated.rs` and run the following command: -```shell -witc plugin wasmedge_opencvmini.wit > src/generated.rs -``` + ```shell + witc plugin wasmedge_opencvmini.wit > src/generated.rs + ``` - **Write Wrapper Functions**: In the `src/lib.rs` file of your crate, write the following code of `mod generated` to access the generated code and create wrapper functions: -```rust -mod generated; - -pub fn imdecode(buf: &[u8]) -> u32 { - unsafe { generated::imdecode(buf.as_ptr(), buf.len()) } -} -pub fn imshow(window_name: &str, mat_key: u32) -> () { - unsafe { generated::imshow(window_name.as_ptr(), window_name.len(), mat_key) } -} -pub fn waitkey(delay: u32) -> () { - unsafe { generated::waitkey(delay) } -} -``` - -This code imports the generated module and provides safe wrapper functions for each generated function. + ```rust + mod generated; + + pub fn imdecode(buf: &[u8]) -> u32 { + unsafe { generated::imdecode(buf.as_ptr(), buf.len()) } + } + pub fn imshow(window_name: &str, mat_key: u32) -> () { + unsafe { generated::imshow(window_name.as_ptr(), window_name.len(), mat_key) } + } + pub fn waitkey(delay: u32) -> () { + unsafe { generated::waitkey(delay) } + } + ``` + + This code imports the generated module and provides safe wrapper functions for each generated function. [^1]: From e30cc245367d513a298e99cd5534535b33f9e105 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Tue, 25 Jul 2023 13:31:57 +0600 Subject: [PATCH 10/20] rebase and fixed typo Signed-off-by: Mahfuza --- .vscode/settings.json | 2 +- docs/contribute/plugin/_category_.json | 2 +- docs/contribute/plugin/develop_plugin_c.md | 18 +++++++++--------- docs/contribute/plugin/develop_plugin_cpp.md | 14 +++++++------- .../plugin/develop_plugin_rustsdk.md | 8 ++++---- docs/contribute/plugin/intro.md | 12 ++++++------ 6 files changed, 28 insertions(+), 28 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index a3b8eabea..40b89c812 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,3 +1,3 @@ { "cSpell.words": ["bytecode", "CNCF", "Emscripten", "wasmedge"] -} \ No newline at end of file +} diff --git a/docs/contribute/plugin/_category_.json b/docs/contribute/plugin/_category_.json index 996f1807c..689216fdc 100644 --- a/docs/contribute/plugin/_category_.json +++ b/docs/contribute/plugin/_category_.json @@ -3,6 +3,6 @@ "position": 3, "link": { "type": "generated-index", - "description": "we will learn how to develop the WasmEdge Plugin System." + "description": "we will learn how to develop the plug-in of WasmEdge." } } diff --git a/docs/contribute/plugin/develop_plugin_c.md b/docs/contribute/plugin/develop_plugin_c.md index 6f399d62c..2323f43d7 100644 --- a/docs/contribute/plugin/develop_plugin_c.md +++ b/docs/contribute/plugin/develop_plugin_c.md @@ -4,7 +4,7 @@ sidebar_position: 2 # Develop WasmEdge Plug-in in C API -By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's own building and releasing process. Here is a flowchart showing all the steps needed for developing WasmEdge Plugin - +By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's building and releasing process. Here is a flowchart showing all the steps needed for developing WasmEdge Plugin - ```mermaid graph LR; @@ -25,8 +25,8 @@ This flowchart illustrates the process of developing a WasmEdge plugin, showcasi To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - -- **Install a WasmEdge runtime**: You can download the latest version of WasmEdge from [GitHub repository](https://github.com/wasmEdge/wasmEdge). Here are the installation instructions for different operating system for [installing WasmEdge](/develop/build-and-run/install.md). -- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your own plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. +- **Install a WasmEdge runtime**: You can download the latest version of WasmEdge from [GitHub repository](https://github.com/wasmEdge/wasmEdge). Here are the installation instructions for a different operating system for [installing WasmEdge](/develop/build-and-run/install.md). +- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. To see a list of supported plugins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plugins and dependencies section. @@ -42,7 +42,7 @@ By following these steps, you can set up the development environment for creatin To create a WasmEdge plugin project, follow these steps: -- **Set up the project directory**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your own structure. To create a project directory structure, use the following commands: +- **Set up the project directory**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your structure. To create a project directory structure, use the following commands: ```bash mkdir testplugin @@ -60,11 +60,11 @@ To create a plug-in with host functions and modules, follow these steps: - **Implement host function definitions**: In this step, you need to define the host functions that will be imported when instantiating the WASM module. These functions will perform specific operations and return results. - Therefore, developers can implement their plug-in host functions first, as the same as the [host functions in WasmEdge C API](/embed/c/reference/latest.md#host-functions). + Therefore, developers can implement their plug-in host functions first, the same as the [host functions in WasmEdge C API](/embed/c/reference/latest.md#host-functions). :::note -For the more details about the [external data](/embed/c/host_function.md#host-data) and [calling frame context](/embed/c/host_function.md#calling-frame-context), please refer to the host function guide. +For more details about the [external data](/embed/c/host_function.md#host-data) and [calling frame context](/embed/c/host_function.md#calling-frame-context), please refer to the host function guide. ::: Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers respectively: @@ -113,7 +113,7 @@ For the more details about the [external data](/embed/c/host_function.md#host-da * const struct WasmEdge_ModuleDescriptor *); * } WasmEdge_ModuleDescriptor; * - * Developers can get the name and the description from this descriptor. + * Developers can get the name and description from this descriptor. */ /* Exported module name of this module instance. */ @@ -147,7 +147,7 @@ For the more details about the [external data](/embed/c/host_function.md#host-da } ``` - There can be several module instances in a plug-in shared library. Here in above code snippet take a module named as `wasmedge_plugintest_c_module` for the example. + There can be several module instances in a plug-in shared library. Here in the above code snippet take a module named `wasmedge_plugintest_c_module` for the example. - **Supply the plugin descriptions**- In this step, you need to provide the descriptions of the plugin and the modules it contains. These descriptions will be used for searching and creating the plugin and module instances. @@ -209,7 +209,7 @@ By following these steps and implementing the necessary functions and descriptor To build the WasmEdge plug-in shared library, you have two options: building it directly using the compiler or using CMake. Here are the instructions for both methods: -- **Build with Command**: if you choose to build the plug-in using the command line, run the following command in terminal: +- **Build with Command**: if you choose to build the plug-in using the command line, run the following command in the terminal: This command compiles the `testplugin.c` file into a shared library named `libwasmedgePluginTest.so`. The `-std=c11` flag sets the C language standard to C11, and the `-DWASMEDGE_PLUGIN` flag defines the WASMEDGE_PLUGIN macro, which can be used in your code. diff --git a/docs/contribute/plugin/develop_plugin_cpp.md b/docs/contribute/plugin/develop_plugin_cpp.md index 4e8ed3cd2..2f2c5e345 100644 --- a/docs/contribute/plugin/develop_plugin_cpp.md +++ b/docs/contribute/plugin/develop_plugin_cpp.md @@ -4,11 +4,11 @@ sidebar_position: 3 # Develop WasmEdge Plug-in in C++ API -By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's own building and releasing process. +By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's building and releasing process. :::note -It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plugin development because of the support, compatibility and flexibility provided by the WasmEdge runtime. +It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plugin development because of the support, compatibility, and flexibility provided by the WasmEdge runtime. ::: Here is a flowchart showing all the steps needed for developing WasmEdge Plugin - @@ -31,13 +31,13 @@ J --> K(Test and debug plugin) This flowchart illustrates the process of developing a WasmEdge plugin, showcasing the steps involved from choosing a programming language to finalizing and releasing the plugin. -## Set up development environment +## Set up a development environment To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - - **Build WasmEdge from source**: For developing WasmEdge plugin in C++ language, you will need to build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. -- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your own plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. +- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. To see a list of supported plugins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plugins and dependencies section. @@ -53,7 +53,7 @@ By following these steps, you can set up the development environment for creatin To create a WasmEdge plugin project, follow these steps: -- **Set up the project directory**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your own structure. To create a project directory structure, use the following commands: +- **Set up the project directory**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your structure. To create a project directory structure, use the following commands: ```bash mkdir testplugin @@ -141,7 +141,7 @@ To create a plug-in with host functions and modules, follow these steps: } // namespace WasmEdge ``` -- **Creation Functions for Modules**: Then developers should implement the module creation functions. Assume that the following implementations are all in the `testplugin.cpp`. +- **Creation Functions for Modules**: Then developers should implement the module creation functions. Assume the following implementations are all in the `testplugin.cpp`. ```cpp #include "testplugin.h" @@ -225,7 +225,7 @@ By following these steps and implementing the necessary functions and descriptor ## Build plugin -To build the plug-in shared library, developers should build in cmake with the WasmEdge source. +To build the plug-in shared library, developers should build in CMake with the WasmEdge source. - Assume that the folder named `test` is created under the `/plugins`. Add this line in the `/plugins/CMakeLists.txt`: diff --git a/docs/contribute/plugin/develop_plugin_rustsdk.md b/docs/contribute/plugin/develop_plugin_rustsdk.md index df24c4827..2f9626b22 100644 --- a/docs/contribute/plugin/develop_plugin_rustsdk.md +++ b/docs/contribute/plugin/develop_plugin_rustsdk.md @@ -4,20 +4,20 @@ sidebar_position: 4 # Develop WasmEdge Plug-in in Rust SDK with witc -By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit the specific needs. WasmEdge provides a Rust based API for registering extension modules and host functions. +By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit specific needs. WasmEdge provides a Rust-based API for registering extension modules and host functions. :::note -It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plugin development because of the support, compatibility and flexibility provided by the WasmEdge runtime. +It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plugin development because of the support, compatibility, and flexibility provided by the WasmEdge runtime. ::: ## Set up the development environment To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - -- **Build WasmEdge from source**: For developing WasmEdge plugin in C++ language, you will need to build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. Once you complete C++ plugin code, you can use witc[^1] to generate Rust Plugin SDK. +- **Build WasmEdge from source**: For developing WasmEdge plugin in C++ language, you will need to build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. Once you complete the C++ plugin code, you can use witc[^1] to generate Rust Plugin SDK. -- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your own plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. +- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. To see a list of supported plugins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plugins and dependencies section. diff --git a/docs/contribute/plugin/intro.md b/docs/contribute/plugin/intro.md index c6d5f4824..7cde124ec 100644 --- a/docs/contribute/plugin/intro.md +++ b/docs/contribute/plugin/intro.md @@ -4,7 +4,7 @@ sidebar_position: 1 # WasmEdge Plug-in System Introduction -While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, developers should implement the host functions before compilation. However, for more flexible and dynamic extension of the host functions, WasmEdge provides a plug-in architecture to load the plug-in shared library. +While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, developers should implement the host functions before compilation. However, for a more flexible and dynamic extension of the host functions, WasmEdge provides a plug-in architecture to load the plug-in shared library. A WasmEdge plugin is a software component that extends the functionality of the WasmEdge runtime. Currently, developers can follow the guides to implement the plug-ins in [C API](develop_plugin_c.md) (recommended) or [C++](develop_plugin_cpp.md). With the help of the WasmEdge SDKs in the supported languages, developers can load and register the host functions from the plug-in shared libraries, allowing them to seamlessly integrate the plugins into the WasmEdge runtime as if they were part of the core runtime. @@ -20,7 +20,7 @@ In this diagram, the _Host Application_ represents the application or environmen WasmEdge plugins can be used in various scenarios, such as high-performance domain-specific languages, cloud-native JavaScript runtime, edge computing, serverless, SaaS, service mesh, and blockchain applications. Moreover, WasmEdge plugins can be used in microservices, providing a lightweight, secure, and high-performance runtime compatible with frameworks like Dapr and Kubernetes. -In addition, WasmEdge plugins can support serverless functions for SaaS applications, allowing users to extend and customize their experience without operating their own API callback servers. They can also be embedded into smart device applications as middleware runtime, rendering interactive content on the UI, connecting to native device drivers, and accessing specialized hardware feature. WasmEdge plugins can be used for managing application state, exchanging dynamic data (e.g., strings and arrays) with Wasm programs, and providing native host functions to manipulate data. +In addition, WasmEdge plugins can support serverless functions for SaaS applications, allowing users to extend and customize their experience without operating their API callback servers. They can also be embedded into smart device applications as middleware runtime, rendering interactive content on the UI, connecting to native device drivers, and accessing specialized hardware features. WasmEdge plugins can be used for managing application state, exchanging dynamic data (e.g., strings and arrays) with Wasm programs, and providing native host functions to manipulate data. ## Benefits of Using WasmEdge Plugin @@ -46,7 +46,7 @@ Loadable plugins are standalone shared libraries (`.so`/`.dylib`/`.dll` files) t ### Creating Loadable Plug-in -To create a loadable plugin for WasmEdge, developers can use the WasmEdge Plugin SDK, which provides a set of Rust, C and C++ APIs for creating and registering plugins. The SDK also includes [example code](https://github.com/WasmEdge/WasmEdge/tree/master/examples/plugin/get-string) that demonstrates how to create a simple plugin that returns a string. By following the provided examples and leveraging the SDK's APIs, developers can easily build custom plugins tailored to their specific needs. +To create a loadable plugin for WasmEdge, developers can use the WasmEdge Plugin SDK, which provides a set of Rust, C, and C++ APIs for creating and registering plugins. The SDK also includes [example code](https://github.com/WasmEdge/WasmEdge/tree/master/examples/plugin/get-string) that demonstrates how to create a simple plugin that returns a string. By following the provided examples and leveraging the SDK's APIs, developers can easily build custom plugins tailored to their specific needs. ### Loading plug-in from paths @@ -56,7 +56,7 @@ To make use of the loadable plugins, developers need to load them from specific - The path specified in the environment variable `WASMEDGE_PLUGIN_PATH`. - The `../plugin/` directory relative to the WasmEdge installation path. - - The `./wasmedge/` directory located under the library path if WasmEdge is installed in a system directory such as `/usr` and `/usr/local`. + - The `./wasmedge/` directory is located under the library path if WasmEdge is installed in a system directory such as `/usr` and `/usr/local`. - If the plugins are located in a specific path or directory, developers can use the `WasmEdge_PluginLoadFromPath("PATH_TO_PLUGIN/plugin.so")` API to load the plugins from that particular location. @@ -85,11 +85,11 @@ By following this flowchart, developers can effectively load loadable plugins in ## 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 source with the 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 | Description | Released Platforms | Build Steps | | --- | --- | --- | --- | --- | -| WasmEdge-Process | [wasmedge_process_interface][] | WasmEdge-Process is a utility plugin for the WasmEdge Runtime, providing functionality related to process handling. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.10.0`) | [Build Wtih WasmEdge-Process](/contribute/source/plugin/process) | +| WasmEdge-Process | [wasmedge_process_interface][] | WasmEdge-Process is a utility plugin for the WasmEdge Runtime, providing functionality related to process handling. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.10.0`) | [Build With WasmEdge-Process](/contribute/source/plugin/process) | | [WASI-Crypto][] | [wasi-crypto][] | WASI-Crypto is a module that provides a set of APIs for cryptographic operations and key management. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.10.1`) | [Build With WASI-Crypto](/contribute/source/plugin/wasi_crypto) | | [WASI-NN with OpenVINO backend](/develop/rust/ai_inference/openvino) | [wasi-nn][] | WASI-NN with OpenVINO backend is a machine learning-oriented module for WebAssembly. | `ubuntu 20.04 x86_64` (since `0.10.1`) | [Build With WASI-NN](/contribute/source/plugin/wasi_nn#get-wasmedge-with-wasi-nn-plug-in-openvino-backend) | | [WASI-NN with PyTorch backend](/develop/rust/ai_inference/pytorch) | [wasi-nn][] | WASI-NN with PyTorch backend allows running of PyTorch models in WebAssembly. | `ubuntu 20.04 x86_64` (since `0.11.1`) | [Build With WASI-NN](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-pytorch-backend) | From 2a4f5c06a853fc4c894b577f87bafe4b0a1b3125 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Tue, 25 Jul 2023 20:01:53 +0600 Subject: [PATCH 11/20] fix typo Signed-off-by: Mahfuza --- docs/contribute/plugin/develop_plugin_c.md | 58 +++++++++---------- docs/contribute/plugin/develop_plugin_cpp.md | 52 ++++++++--------- .../plugin/develop_plugin_rustsdk.md | 22 +++---- docs/contribute/plugin/intro.md | 56 +++++++++--------- 4 files changed, 94 insertions(+), 94 deletions(-) diff --git a/docs/contribute/plugin/develop_plugin_c.md b/docs/contribute/plugin/develop_plugin_c.md index 2323f43d7..0a144ebad 100644 --- a/docs/contribute/plugin/develop_plugin_c.md +++ b/docs/contribute/plugin/develop_plugin_c.md @@ -4,45 +4,45 @@ sidebar_position: 2 # Develop WasmEdge Plug-in in C API -By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's building and releasing process. Here is a flowchart showing all the steps needed for developing WasmEdge Plugin - +By developing a plug-in, one can extend the functionality of WasmEdge and customize it to suit specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plug-in API allows such extensions to be incorporated into WasmEdge's building and releasing process. Here is a flowchart showing all the steps needed for developing WasmEdge Plug-in - ```mermaid graph LR; -A[Developing WasmEdge Plugin in C] +A[Developing WasmEdge Plug-in in C] A --> B(Set up the development environment) -A --> C(Create a WasmEdge plugin project) +A --> C(Create a WasmEdge plug-in project) A --> D(Write the plugin code) A --> E(Build the plugin) -A --> F(Test and debug the plugin) +A --> F(Test and debug the plug-in) B --> E C --> D D --> E ``` -This flowchart illustrates the process of developing a WasmEdge plugin, showcasing the steps involved from choosing a programming language to finalizing and releasing the plugin. +This flowchart illustrates developing a WasmEdge plug-in, showcasing the steps from choosing a programming language to finalizing and releasing the plug-in. ## Set up the development environment -To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - +To start developing WasmEdge plug-ins, it is essential to correctly set up the development environment. This section provides step-by-step instructions for WasmEdge plug-in development - - **Install a WasmEdge runtime**: You can download the latest version of WasmEdge from [GitHub repository](https://github.com/wasmEdge/wasmEdge). Here are the installation instructions for a different operating system for [installing WasmEdge](/develop/build-and-run/install.md). -- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. +- **Install WasmEdge with plug-ins (optional)**: Installing WasmEdge with existing plug-ins can provide additional functionality and be a reference for your plug-in development. If you want to utilize or test the compatibility of your new plug-in with existing plug-ins, you can install them using the provided installer script. The installed plug-ins will be available for your development environment. - To see a list of supported plugins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plugins and dependencies section. + To see a list of supported plug-ins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plug-ins and dependencies section. -- **Enable specific backends or additional components (if applicable):** Some plugins may require enabling specific backends or additional components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: +- **Enable specific backends or additional components (if applicable):** Some plug-ins may require enabling specific backends or other components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) - [TensorFlow Lite](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-tensorflow-lite-backend) - [PyTorch 1.8.2 LTS](https://pytorch.org/get-started/locally/) -By following these steps, you can set up the development environment for creating WasmEdge plugins effectively. This will allow you to develop, test, and debug your plugins in a Linux environment. +Following these steps, you can set up the development environment for effectively creating WasmEdge plug-ins, allowing you to develop, test, and debug your plug-ins in a Linux environment. -## Create a WasmEdge plugin project +## Create a WasmEdge plug-in project -To create a WasmEdge plugin project, follow these steps: +To create a WasmEdge plug-in project, follow these steps: -- **Set up the project directory**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your structure. To create a project directory structure, use the following commands: +- **Set up the project directory**: Create a directory structure for your plug-in project. You can use a standard structure for the chosen language or create your structure. To create a project directory structure, use the following commands: ```bash mkdir testplugin @@ -50,24 +50,24 @@ To create a WasmEdge plugin project, follow these steps: mkdir src include build ``` -- **Add configuration files**: Add configuration files specifying the plugin name, version, and dependencies. The specific files and their content depend on the chosen programming language and build system. +- **Add configuration files**: Add configuration files specifying the plug-in name, version, and dependencies. The specific files and content depend on the chosen programming language and build system. -- **Add any necessary libraries or dependencies**: Include any required libraries or dependencies for your plugin. Modify the configuration files created in the previous step to include the necessary dependencies. +- **Add any necessary libraries or dependencies**: Include any required libraries or dependencies for your plug-in. Modify the configuration files created in the previous step to include the required dependencies. -## Write the plugin code +## Write the plug-in code To create a plug-in with host functions and modules, follow these steps: -- **Implement host function definitions**: In this step, you need to define the host functions that will be imported when instantiating the WASM module. These functions will perform specific operations and return results. +- **Implement host function definitions**: In this step, you must define the host functions that will be imported when instantiating the WASM module. These functions will perform specific operations and return results. - Therefore, developers can implement their plug-in host functions first, the same as the [host functions in WasmEdge C API](/embed/c/reference/latest.md#host-functions). + Therefore, developers can first implement their plug-in host functions, like the [host functions in WasmEdge C API](/embed/c/reference/latest.md#host-functions). :::note For more details about the [external data](/embed/c/host_function.md#host-data) and [calling frame context](/embed/c/host_function.md#calling-frame-context), please refer to the host function guide. ::: - Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers respectively: + Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers, respectively: ```c #include @@ -95,7 +95,7 @@ For more details about the [external data](/embed/c/host_function.md#host-data) } ``` -- **Implement the module creation functions**: In this step, you need to implement the module creation function that creates an instance of the module. This function will be called when the plugin is loaded. +- **Implement the module creation functions**: In this step, you need to implement the module creation function that creates an instance of the module. This function will be called when the plug-in is loaded. Here's an example of a module creation function named `CreateTestModule`: @@ -147,11 +147,11 @@ For more details about the [external data](/embed/c/host_function.md#host-data) } ``` - There can be several module instances in a plug-in shared library. Here in the above code snippet take a module named `wasmedge_plugintest_c_module` for the example. + There can be several module instances in a plug-in shared library. Here in the above code snippet, take a module named `wasmedge_plugintest_c_module` for the example. -- **Supply the plugin descriptions**- In this step, you need to provide the descriptions of the plugin and the modules it contains. These descriptions will be used for searching and creating the plugin and module instances. +- **Supply the plug-in descriptions**- In this step, you need to provide the descriptions of the plug-in and the modules it contains. These descriptions will be used for searching and creating the plug-in and module instances. - Here's an example of the plugin and module descriptors: + Here's an example of the plug-in and module descriptors: ```c /* The module descriptor array. There can be multiple modules in a plug-in. */ @@ -197,17 +197,17 @@ For more details about the [external data](/embed/c/host_function.md#host-data) }}; ``` - These descriptions define the name, description, version, and creation function of the plugin, as well as the name and description of the module it contains. + These descriptions define the name, description, version, and creation function of the plug-in and the name and description of the module it contains. -Remember to implement any additional functions or structures that your plugin requires to fulfill its functionality. +Remember to implement any additional functions or structures your plug-in requires to fulfill its functionality. -By following these steps and implementing the necessary functions and descriptors, you can create a plug-in with host functions and modules in WasmEdge C API. You can continue developing your plugin by adding functionality and implementing the desired behavior. +Following these steps and implementing the necessary functions and descriptors, you can create a plug-in with host functions and modules in WasmEdge C API. You can continue developing your plug-in by adding functionality and implementing the desired behavior. - **Plugin option** - _WORK IN PROGRESS. This section is reserved for the feature in the future._ -## Build your plugin +## Build your plug-in -To build the WasmEdge plug-in shared library, you have two options: building it directly using the compiler or using CMake. Here are the instructions for both methods: +To build the WasmEdge plug-in shared library, you have two options: build it directly using the compiler or CMake. Here are the instructions for both methods: - **Build with Command**: if you choose to build the plug-in using the command line, run the following command in the terminal: @@ -238,4 +238,4 @@ To build the WasmEdge plug-in shared library, you have two options: building it This CMake configuration sets up a build target called `wasmedgePluginTest`. It compiles the `testplugin.c` file into a shared library. The `C_STANDARD 11` property sets the C language standard to C11. The `target_compile_options` command defines the `WASMEDGE_PLUGIN` macro using the `-DWASMEDGE_PLUGIN` flag. Finally, the `target_link_libraries` command links the wasmedge library to the plug-in. -Once you have set up either the command-line build or the CMake build, you can execute the corresponding build command or generate build files using CMake. This will compile your plug-in source code and produce the shared library file `(libwasmedgePluginTest.so)`. +Once you have set up either the command-line build or the CMake build, you can execute the corresponding build command or generate build files using CMake, which will compile your plug-in source code and produce the shared library file `(libwasmedgePluginTest.so)`. diff --git a/docs/contribute/plugin/develop_plugin_cpp.md b/docs/contribute/plugin/develop_plugin_cpp.md index 2f2c5e345..4df9a5c06 100644 --- a/docs/contribute/plugin/develop_plugin_cpp.md +++ b/docs/contribute/plugin/develop_plugin_cpp.md @@ -4,14 +4,14 @@ sidebar_position: 3 # Develop WasmEdge Plug-in in C++ API -By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's building and releasing process. +By developing a plug-in, one can extend the functionality of WasmEdge and customize it to suit specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plug-in API allows such extensions to be incorporated into WasmEdge's building and releasing process. :::note -It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plugin development because of the support, compatibility, and flexibility provided by the WasmEdge runtime. +It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plug-in development because of the support, compatibility, and flexibility the WasmEdge runtime provides. ::: -Here is a flowchart showing all the steps needed for developing WasmEdge Plugin - +Here is a flowchart showing all the steps needed for developing WasmEdge Plug-in - ```mermaid graph TD; @@ -29,31 +29,31 @@ I --> J(Compile WasmEdge plugin) J --> K(Test and debug plugin) ``` -This flowchart illustrates the process of developing a WasmEdge plugin, showcasing the steps involved from choosing a programming language to finalizing and releasing the plugin. +This flowchart illustrates developing a WasmEdge plug-in, showcasing the steps from choosing a programming language to finalizing and releasing the plug-in. ## Set up a development environment -To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - +To start developing WasmEdge plug-ins, it is essential to correctly set up the development environment. This section provides step-by-step instructions for WasmEdge plug-in development - -- **Build WasmEdge from source**: For developing WasmEdge plugin in C++ language, you will need to build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. +- **Build WasmEdge from source**: For developing the WasmEdge plug-in in C++, you must build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. -- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. +- **Install WasmEdge with plug-ins (optional)**: Installing WasmEdge with existing plug-ins can provide additional functionality and be a reference for your plug-in development. If you want to utilize or test the compatibility of your new plug-in with existing plug-ins, you can install them using the provided installer script. The installed plug-ins will be available for your development environment. - To see a list of supported plugins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plugins and dependencies section. + To see a list of supported plug-ins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plug-ins and dependencies section. -- **Enable specific backends or additional components (if applicable):** Some plugins may require enabling specific backends or additional components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: +- **Enable specific backends or additional components (if applicable):** Some plug-ins may require enabling specific backends or other components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) - [TensorFlow Lite](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-tensorflow-lite-backend) - [PyTorch 1.8.2 LTS](https://pytorch.org/get-started/locally/) -By following these steps, you can set up the development environment for creating WasmEdge plugins effectively. This will allow you to develop, test, and debug your plugins in a Linux environment. +Following these steps, you can set up the development environment for effectively creating WasmEdge plug-ins, allowing you to develop, test, and debug your plug-ins in a Linux environment. ## Create a WasmEdge plug-in project -To create a WasmEdge plugin project, follow these steps: +To create a WasmEdge plug-in project, follow these steps: -- **Set up the project directory**: Create a directory structure for your plugin project. You can use a standard structure for the chosen language, or create your structure. To create a project directory structure, use the following commands: +- **Set up the project directory**: Create a directory structure for your plug-in project. You can use a standard structure for the chosen language or create your structure. To create a project directory structure, use the following commands: ```bash mkdir testplugin @@ -61,18 +61,18 @@ To create a WasmEdge plugin project, follow these steps: mkdir src include build ``` -- **Add necessary libraries or dependencies**: Include any required libraries or dependencies for your plugin. Modify the configuration files created in the previous step to include the necessary dependencies. +- **Add necessary libraries or dependencies**: Include any required libraries or dependencies for your plug-in. Modify the configuration files created in the previous step to include the required dependencies. -## Write plugin code +## Write plug-in code To create a plug-in with host functions and modules, follow these steps: -- **Host Functions and Modules**: The goal of the plug-in is to provide the host functions which can be imported when instantiating WASM. Therefore, developers should implement their plug-in host functions in WasmEdge internal C++ first. Assume that the host function implementations are in the `testplugin.h`. +- **Host Functions and Modules**: The plug-in aims to provide the host functions that can be imported when instantiating WASM. Therefore, developers should first implement their plug-in host functions in WasmEdge internal C++. Assume that the host function implementations are in the `testplugin.h`. ```cpp #pragma once - #include "plugin/plugin.h" + #include "plug-in/plug-in.h" #include #include @@ -170,14 +170,14 @@ To create a plug-in with host functions and modules, follow these steps: namespace { Plugin::Plugin::PluginDescriptor Descriptor{ - // Plug-in name. This is the name for searching the plug-in context by the + //Plug-in name - for searching the plug-in context by the // `WasmEdge_PluginFind()` C API. .Name = "wasmedge_plugintest_cpp", - // Plug-in description. + //Plug-in description. .Description = "", - // Plug-in API version. + //Plug-in API version. .APIVersion = Plugin::Plugin::CurrentAPIVersion, - // Plug-in version. + //Plug-in version. .Version = {0, 10, 0, 0}, // Module count in this plug-in. .ModuleCount = 1, @@ -196,7 +196,7 @@ To create a plug-in with host functions and modules, follow these steps: .Create = create, }, }, - // Plug-in options (Work in progress). + //Plug-in options (Work in progress). .AddOptions = nullptr, }; @@ -219,15 +219,15 @@ Plugin::PluginRegister WasmEdgePluginTestEnv::Register(&Descriptor); } // namespace WasmEdge ``` -Remember to implement any additional functions or structures that your plugin requires to fulfill its functionality. +Remember to implement any additional functions or structures your plug-in requires to fulfill its functionality. -By following these steps and implementing the necessary functions and descriptors, you can create a plug-in with host functions and modules in WasmEdge C++ API. You can continue developing your plugin by adding functionality and implementing the desired behavior. +Following these steps and implementing the necessary functions and descriptors, you can create a plug-in with host functions and modules in WasmEdge C++ API. You can continue developing your plug-in by adding functionality and implementing the desired behavior. -## Build plugin +## Build plug-in To build the plug-in shared library, developers should build in CMake with the WasmEdge source. -- Assume that the folder named `test` is created under the `/plugins`. Add this line in the `/plugins/CMakeLists.txt`: +- Assume that the' test' folder is created under the `/plug-ins`. Add this line in the `/plugins/CMakeLists.txt`: ```cmake add_subdirectory(test) @@ -273,4 +273,4 @@ To build the plug-in shared library, developers should build in CMake with the W endif() ``` -Follow the guide to [build WasmEdge from source](../source/os/linux.md), according to your specific operating system (e.g., Linux). This will include building the plug-in shared library along with WasmEdge. +Follow the guide to [build WasmEdge from source](../source/os/linux.md), according to your specific operating system (e.g., Linux), which will include building the plug-in shared library along with WasmEdge. diff --git a/docs/contribute/plugin/develop_plugin_rustsdk.md b/docs/contribute/plugin/develop_plugin_rustsdk.md index 2f9626b22..65995c005 100644 --- a/docs/contribute/plugin/develop_plugin_rustsdk.md +++ b/docs/contribute/plugin/develop_plugin_rustsdk.md @@ -4,32 +4,32 @@ sidebar_position: 4 # Develop WasmEdge Plug-in in Rust SDK with witc -By developing a plugin, one can extend the functionality of WasmEdge and customize it to suit specific needs. WasmEdge provides a Rust-based API for registering extension modules and host functions. +By developing a plug-in, one can extend the functionality of WasmEdge and customize it to suit specific needs. WasmEdge provides a Rust-based API for registering extension modules and host functions. :::note -It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plugin development because of the support, compatibility, and flexibility provided by the WasmEdge runtime. +It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plug-in development because of the support, compatibility, and flexibility the WasmEdge runtime provides. ::: ## Set up the development environment -To start developing WasmEdge plugins, it is essential to set up the development environment properly. This section provides step-by-step instructions for WasmEdge plugin development - +To start developing WasmEdge plug-ins, it is essential to properly set up the development environment. This section provides step-by-step instructions for WasmEdge plug-in development - -- **Build WasmEdge from source**: For developing WasmEdge plugin in C++ language, you will need to build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. Once you complete the C++ plugin code, you can use witc[^1] to generate Rust Plugin SDK. +- **Build WasmEdge from source**: For developing the WasmEdge plug-in in C++, you must build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. Once you complete the C++ plug-in code, you can use witc[^1] to generate Rust Plug-in SDK. -- **Install WasmEdge with plugins (optional)**: Installing WasmEdge with existing plugins can provide you with additional functionality and serve as a reference for your plugin development. If you want to utilize or test the compatibility of your new plugin with existing plugins, you can install them using the provided installer script. The installed plugins will be available for your development environment. +- **Install WasmEdge with plug-ins (optional)**: Installing WasmEdge with existing plug-ins can provide additional functionality and be a reference for your plug-in development. If you want to utilize or test the compatibility of your new plug-in with existing plug-ins, you can install them using the provided installer script. The installed plug-ins will be available for your development environment. - To see a list of supported plugins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plugins and dependencies section. + To see a list of supported plug-ins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plug-ins and dependencies section. -- **Enable specific backends or additional components (if applicable):** Some plugins may require enabling specific backends or additional components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: +- **Enable specific backends or additional components (if applicable):** Some plug-ins may require enabling specific backends or other components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) - [TensorFlow Lite](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-tensorflow-lite-backend) - [PyTorch 1.8.2 LTS](https://pytorch.org/get-started/locally/) -By following these steps, you can set up the development environment for creating WasmEdge plugins effectively. This will allow you to develop, test, and debug your plugins in a Linux environment. +Following these steps, you can set up the development environment for effectively creating WasmEdge plug-ins, allowing you to develop, test, and debug your plug-ins in a Linux environment. -## Write the plugin code +## Write the plug-in code To develop a WasmEdge Plug-in in Rust using the witc tool, you can follow these steps: @@ -41,13 +41,13 @@ To develop a WasmEdge Plug-in in Rust using the witc tool, you can follow these waitkey: func(delay: u32) -> unit ``` - You can use the witc tool to generate Rust plugin code for it by running the following command: + You can use the witc tool to generate Rust plug-in code for it by running the following command: ```shell witc plugin wasmedge_opencvmini.wit ``` -- **Create SDK Crate**: Now, you need to create an SDK crate for your plugin. Run the following command to create a new crate named `opencvmini-sdk`: +- **Create SDK Crate**: You need to create an SDK crate for your plug-in. Run the following command to create a new crate named `opencvmini-sdk`: ```shell cargo new --lib opencvmini-sdk && cd opencvmini-sdk diff --git a/docs/contribute/plugin/intro.md b/docs/contribute/plugin/intro.md index 7cde124ec..51b638758 100644 --- a/docs/contribute/plugin/intro.md +++ b/docs/contribute/plugin/intro.md @@ -6,7 +6,7 @@ sidebar_position: 1 While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, developers should implement the host functions before compilation. However, for a more flexible and dynamic extension of the host functions, WasmEdge provides a plug-in architecture to load the plug-in shared library. -A WasmEdge plugin is a software component that extends the functionality of the WasmEdge runtime. Currently, developers can follow the guides to implement the plug-ins in [C API](develop_plugin_c.md) (recommended) or [C++](develop_plugin_cpp.md). With the help of the WasmEdge SDKs in the supported languages, developers can load and register the host functions from the plug-in shared libraries, allowing them to seamlessly integrate the plugins into the WasmEdge runtime as if they were part of the core runtime. +A WasmEdge plug-in is a software component that extends the functionality of the WasmEdge runtime. Currently, developers can follow the guides to implement the plug-ins in [C API](develop_plugin_c.md) (recommended) or [C++](develop_plugin_cpp.md). With the help of the WasmEdge SDKs in the supported languages, developers can load and register the host functions from the plug-in shared libraries, allowing them to seamlessly integrate the plug-ins into the WasmEdge runtime as if they were part of the core runtime. ```mermaid graph LR @@ -14,55 +14,55 @@ graph LR B -- Registers --> C((Wasmedge Runtime)) ``` -In this diagram, the _Host Application_ represents the application or environment where the Wasmedge runtime is embedded or used. The _Plugin Shared Library_ refers to the library containing the plugin code and functions that extend the functionality of the Wasmedge runtime. The _Wasmedge Runtime_ represents the runtime environment that executes WebAssembly modules, including the core runtime and any registered plugins. +In this diagram, the _Host Application_ represents the application or environment where the Wasmedge runtime is embedded or used. The _Plug-in Shared Library_ refers to the library containing the plug-in code and functions that extend the functionality of the Wasmedge runtime. The _Wasmedge Runtime_ represents the runtime environment that executes WebAssembly modules, including the core runtime and any registered plug-ins. -## Usages of WasmEdge Plugin +## Usages of WasmEdge Plug-in -WasmEdge plugins can be used in various scenarios, such as high-performance domain-specific languages, cloud-native JavaScript runtime, edge computing, serverless, SaaS, service mesh, and blockchain applications. Moreover, WasmEdge plugins can be used in microservices, providing a lightweight, secure, and high-performance runtime compatible with frameworks like Dapr and Kubernetes. +WasmEdge plug-ins can be used in various scenarios, such as high-performance domain-specific languages, cloud-native JavaScript runtime, edge computing, serverless, SaaS, service mesh, and blockchain applications. Moreover, WasmEdge plug-ins can be used in microservices, providing a lightweight, secure, high-performance runtime compatible with frameworks like Dapr and Kubernetes. -In addition, WasmEdge plugins can support serverless functions for SaaS applications, allowing users to extend and customize their experience without operating their API callback servers. They can also be embedded into smart device applications as middleware runtime, rendering interactive content on the UI, connecting to native device drivers, and accessing specialized hardware features. WasmEdge plugins can be used for managing application state, exchanging dynamic data (e.g., strings and arrays) with Wasm programs, and providing native host functions to manipulate data. +In addition, WasmEdge plug-ins can support serverless functions for SaaS applications, allowing users to extend and customize their experience without operating their API callback servers. They can also be embedded into innovative device applications as middleware runtime, rendering interactive content on the UI, connecting to native device drivers, and accessing specialized hardware features. WasmEdge plug-ins can manage application state, exchange dynamic data (e.g., strings and arrays) with Wasm programs, and provide native host functions to manipulate data. -## Benefits of Using WasmEdge Plugin +## Benefits of Using WasmEdge Plug-in -WasmEdge plugins are designed to extend the functionality of the WasmEdge runtime, and can be useful for developers and end-users in several ways: +WasmEdge plug-ins are designed to extend the functionality of the WasmEdge runtime and can be helpful for developers and end-users in several ways: -- **Versatility:** WasmEdge plugins can be developed in multiple programming languages that can compile to WebAssembly, allowing developers to write plugins in the language they're most comfortable with. +- **Versatility:** WasmEdge plug-ins can be developed in multiple programming languages that can compile to WebAssembly, allowing developers to write plug-ins in the most comfortable language. -- **Customization:** WasmEdge plugins can be customized to suit the specific needs of a project. Developers can create plugins that integrate with other systems or tools, or that provide unique functionality that's not available in the core WasmEdge runtime. +- **Customization:** WasmEdge plug-ins can be customized to suit the specific needs of a project. Developers can create plug-ins that integrate with other systems or tools or provide unique functionality unavailable in the core WasmEdge runtime. -- **Performance:** WasmEdge plugins are designed to work seamlessly with the core runtime, minimizing overhead and maximizing performance. This means that they can provide additional functionality without sacrificing performance. +- **Performance:** WasmEdge plug-ins are designed to work seamlessly with the core runtime, minimizing overhead and maximizing performance, which means they can provide additional functionality without sacrificing performance. -- **Ease of use:** WasmEdge plugins are easy to use and integrate with the WasmEdge runtime. Developers can simply load the plugin into the runtime and use its functions as if they were part of the core runtime. +- **Ease of use:** WasmEdge plug-ins are easy to use and integrate with the WasmEdge runtime. Developers can load the plug-in into the runtime and use its functions as part of the core runtime. -- **Scalability:** WasmEdge plugins can be used to scale applications by offloading compute-intensive tasks to edge devices. This can reduce the load on central servers and improve performance. +- **Scalability:** WasmEdge plug-ins can scale applications by offloading compute-intensive tasks to edge devices, reducing the load on central servers and improving performance. -- **Security:** WasmEdge plugins run in a sandboxed environment, which helps to reduce the risk of security vulnerabilities. Additionally, plugins can be digitally signed to ensure authenticity and integrity. +- **Security:** WasmEdge plug-ins run in a sandboxed environment, which helps to reduce the risk of security vulnerabilities. Additionally, plug-ins can be digitally signed to ensure authenticity and integrity. -WasmEdge plugins can provide developers and users with a versatile, customizable, high-performance, and secure way to extend the functionality of the WasmEdge runtime. WasmEdge plugins can also improve scalability and ease of use, making it easier to build and deploy complex applications on edge devices. +WasmEdge plug-ins can provide developers and users with a versatile, customizable, high-performance, and secure way to extend the functionality of the WasmEdge runtime. WasmEdge plug-ins can also improve scalability and ease of use, making it easier to build and deploy complex applications on edge devices. ## Loadable Plug-in -Loadable plugins are standalone shared libraries (`.so`/`.dylib`/`.dll` files) that can be loaded by the WasmEdge runtime environment at runtime. These plugins can provide additional functionality to the WasmEdge runtime environment, such as new modules that can be imported by WebAssembly modules. +Loadable plug-ins are standalone shared libraries (`.so`/`.dylib`/`.dll` files) that the WasmEdge runtime environment can load at runtime. These plug-ins can provide additional functionality to the WasmEdge runtime environment, such as new modules that can be imported by WebAssembly modules. ### Creating Loadable Plug-in -To create a loadable plugin for WasmEdge, developers can use the WasmEdge Plugin SDK, which provides a set of Rust, C, and C++ APIs for creating and registering plugins. The SDK also includes [example code](https://github.com/WasmEdge/WasmEdge/tree/master/examples/plugin/get-string) that demonstrates how to create a simple plugin that returns a string. By following the provided examples and leveraging the SDK's APIs, developers can easily build custom plugins tailored to their specific needs. +To create a loadable plug-in for WasmEdge, developers can use the WasmEdge Plug-in SDK, which provides a set of Rust, C, and C++ APIs for creating and registering plug-ins. The SDK also includes [example code](https://github.com/WasmEdge/WasmEdge/tree/master/examples/plugin/get-string) that demonstrates creating a simple plug-in that returns a string. By following the provided examples and leveraging the SDK's APIs, developers can quickly build custom plug-ins tailored to their specific needs. ### Loading plug-in from paths -To make use of the loadable plugins, developers need to load them from specific paths into the WasmEdge runtime environment. The loading process involves the following steps: +To use the loadable plug-ins, developers need to load them from specific paths into the WasmEdge runtime environment. The loading process involves the following steps: -- Loadable plugins can be loaded from default paths by calling the `WasmEdge_PluginLoadWithDefaultPaths()` API. The default paths include: +- Loadable plug-ins can be loaded from default paths by calling the `WasmEdge_PluginLoadWithDefaultPaths()` API. The default paths include: - The path specified in the environment variable `WASMEDGE_PLUGIN_PATH`. - - The `../plugin/` directory relative to the WasmEdge installation path. + - The `../plug-in/` directory relative to the WasmEdge installation path. - The `./wasmedge/` directory is located under the library path if WasmEdge is installed in a system directory such as `/usr` and `/usr/local`. -- If the plugins are located in a specific path or directory, developers can use the `WasmEdge_PluginLoadFromPath("PATH_TO_PLUGIN/plugin.so")` API to load the plugins from that particular location. +- If the plug-ins are located in a specific path or directory, developers can use the `WasmEdge_PluginLoadFromPath("PATH_TO_PLUGIN/plug-in.so")` API to load the plug-ins from that particular location. -The WasmEdge runtime environment will search for the loadable plugins in the specified paths and load them if found. +The WasmEdge runtime environment will search for the loadable plug-ins in the specified paths and load them if found. -The following flowchart shows the process of loading loadable plugins into the WasmEdge runtime environment from specific paths: +The following flowchart shows the process of loading loadable plug-ins into the WasmEdge runtime environment from specific paths: ```mermaid graph LR @@ -79,9 +79,9 @@ graph LR G -- No --> I ``` -The flowchart shows the process of loading loadable plugins into the WasmEdge runtime environment. The process involves searching for plugins in default paths, a specific path, or a specific directory. If a plugin is found in any of these locations, it is loaded into the runtime environment. The flowchart enables developers to easily load plugins and extend the capabilities of the WasmEdge runtime. +The flowchart shows loading loadable plug-ins into the WasmEdge runtime environment. The process involves searching for plug-ins in default paths, a specific path, or a specific directory. If a plug-in is found in any of these locations, it is loaded into the runtime environment. The flowchart enables developers to quickly load plug-ins and extend the capabilities of the WasmEdge runtime. -By following this flowchart, developers can effectively load loadable plugins into the WasmEdge runtime environment from specific paths, expanding the runtime's functionality according to their requirements. +By following this flowchart, developers can effectively load loadable plug-ins into the WasmEdge runtime environment from specific paths, expanding the runtime's functionality according to their requirements. ## WasmEdge Currently Released Plug-ins @@ -89,14 +89,14 @@ There are several plug-in releases with the WasmEdge official releases. Please c | Plug-in | Rust Crate | Description | Released Platforms | Build Steps | | --- | --- | --- | --- | --- | -| WasmEdge-Process | [wasmedge_process_interface][] | WasmEdge-Process is a utility plugin for the WasmEdge Runtime, providing functionality related to process handling. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.10.0`) | [Build With WasmEdge-Process](/contribute/source/plugin/process) | -| [WASI-Crypto][] | [wasi-crypto][] | WASI-Crypto is a module that provides a set of APIs for cryptographic operations and key management. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.10.1`) | [Build With WASI-Crypto](/contribute/source/plugin/wasi_crypto) | +| WasmEdge-Process | [wasmedge_process_interface][] | WasmEdge-Process is a utility plug-in for the WasmEdge Runtime, providing functionality related to process handling. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.10.0`) | [Build With WasmEdge-Process](/contribute/source/plugin/process) | +| [WASI-Crypto][] | [wasi-crypto][] | WASI-Crypto is a module that provides a set of APIs for cryptographic operations and key management. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.10.1`) | [Build With WASI-Crypto](/contribute/source/plug-in/wasi_crypto) | | [WASI-NN with OpenVINO backend](/develop/rust/ai_inference/openvino) | [wasi-nn][] | WASI-NN with OpenVINO backend is a machine learning-oriented module for WebAssembly. | `ubuntu 20.04 x86_64` (since `0.10.1`) | [Build With WASI-NN](/contribute/source/plugin/wasi_nn#get-wasmedge-with-wasi-nn-plug-in-openvino-backend) | | [WASI-NN with PyTorch backend](/develop/rust/ai_inference/pytorch) | [wasi-nn][] | WASI-NN with PyTorch backend allows running of PyTorch models in WebAssembly. | `ubuntu 20.04 x86_64` (since `0.11.1`) | [Build With WASI-NN](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-pytorch-backend) | | [WASI-NN with TensorFlow-Lite backend](/develop/rust/ai_inference/pytorch) | [wasi-nn][] | WASI-NN with TensorFlow-Lite backend allows running of TensorFlow-Lite models in WebAssembly. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.11.2`) | [Build With WASI-NN](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-tensorflow-lite-backend) | -| WasmEdge-Image | [wasmedge_tensorflow_interface][] | WasmEdge-Image is a plugin that provides image processing and manipulation capabilities in WasmEdge. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, `ubuntu 20.04 x86_64`, `darwin x86_64`, and `darwin arm64` (since `0.13.0`) | [Build With WasmEdge-Image](/contribute/source/plugin/image) | +| WasmEdge-Image | [wasmedge_tensorflow_interface][] | WasmEdge-Image is a plug-in that provides image processing and manipulation capabilities in WasmEdge. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, `ubuntu 20.04 x86_64`, `darwin x86_64`, and `darwin arm64` (since `0.13.0`) | [Build With WasmEdge-Image](/contribute/source/plugin/image) | | WasmEdge-Tensorflow | [wasmedge_tensorflow_interface][] | WasmEdge-Tensorflow integrates TensorFlow with WasmEdge for running machine learning models. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, `ubuntu 20.04 x86_64`, `darwin x86_64`, and `darwin arm64` (since `0.13.0`) | [Build With WasmEdge-Tensorflow](/contribute/source/plugin/tensorflow) | -| WasmEdge-TensorflowLite | [wasmedge_tensorflow_interface][] | WasmEdge-TensorflowLite is a plugin for running TensorFlow Lite models in WasmEdge. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, `ubuntu 20.04 x86_64`, `darwin x86_64`, and `darwin arm64` (since `0.13.0`) | [Build With WasmEdge-TensorflowLite](/contribute/source/plugin/tensorflowlite) | +| WasmEdge-TensorflowLite | [wasmedge_tensorflow_interface][] | WasmEdge-TensorflowLite is a plug-in for running TensorFlow Lite models in WasmEdge. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, `ubuntu 20.04 x86_64`, `darwin x86_64`, and `darwin arm64` (since `0.13.0`) | [Build With WasmEdge-TensorflowLite](/contribute/source/plugin/tensorflowlite) | :::note From 36abeadc0d8c51ea443d65dee1d298bce469fc19 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Sun, 30 Jul 2023 16:10:26 +0600 Subject: [PATCH 12/20] updating as per review Signed-off-by: Mahfuza --- docs/contribute/plugin/_category_.json | 2 +- docs/contribute/plugin/develop_plugin_c.md | 13 +------ docs/contribute/plugin/develop_plugin_cpp.md | 37 ++++++------------- .../plugin/develop_plugin_rustsdk.md | 12 +----- docs/contribute/plugin/intro.md | 30 +++++++-------- 5 files changed, 29 insertions(+), 65 deletions(-) diff --git a/docs/contribute/plugin/_category_.json b/docs/contribute/plugin/_category_.json index 689216fdc..d5890d316 100644 --- a/docs/contribute/plugin/_category_.json +++ b/docs/contribute/plugin/_category_.json @@ -3,6 +3,6 @@ "position": 3, "link": { "type": "generated-index", - "description": "we will learn how to develop the plug-in of WasmEdge." + "description": "We will learn how to develop the plug-ins for WasmEdge." } } diff --git a/docs/contribute/plugin/develop_plugin_c.md b/docs/contribute/plugin/develop_plugin_c.md index 0a144ebad..8cbf7633e 100644 --- a/docs/contribute/plugin/develop_plugin_c.md +++ b/docs/contribute/plugin/develop_plugin_c.md @@ -25,18 +25,9 @@ This flowchart illustrates developing a WasmEdge plug-in, showcasing the steps f To start developing WasmEdge plug-ins, it is essential to correctly set up the development environment. This section provides step-by-step instructions for WasmEdge plug-in development - -- **Install a WasmEdge runtime**: You can download the latest version of WasmEdge from [GitHub repository](https://github.com/wasmEdge/wasmEdge). Here are the installation instructions for a different operating system for [installing WasmEdge](/develop/build-and-run/install.md). -- **Install WasmEdge with plug-ins (optional)**: Installing WasmEdge with existing plug-ins can provide additional functionality and be a reference for your plug-in development. If you want to utilize or test the compatibility of your new plug-in with existing plug-ins, you can install them using the provided installer script. The installed plug-ins will be available for your development environment. +**Install a WasmEdge runtime**: You can download the latest version of WasmEdge from [GitHub repository](https://github.com/wasmEdge/wasmEdge). Follow the instructions in the [installation guide](../../start/install.md) for your specific operating system. - To see a list of supported plug-ins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plug-ins and dependencies section. - -- **Enable specific backends or additional components (if applicable):** Some plug-ins may require enabling specific backends or other components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: - - - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) - - [TensorFlow Lite](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-tensorflow-lite-backend) - - [PyTorch 1.8.2 LTS](https://pytorch.org/get-started/locally/) - -Following these steps, you can set up the development environment for effectively creating WasmEdge plug-ins, allowing you to develop, test, and debug your plug-ins in a Linux environment. +After installing WasmEdge, you need to set up the build environment. If you're using Linux or other platforms, you can follow the instructions in the [build environment setup guide](../source/os/linux.md). ## Create a WasmEdge plug-in project diff --git a/docs/contribute/plugin/develop_plugin_cpp.md b/docs/contribute/plugin/develop_plugin_cpp.md index 4df9a5c06..60eee0f48 100644 --- a/docs/contribute/plugin/develop_plugin_cpp.md +++ b/docs/contribute/plugin/develop_plugin_cpp.md @@ -35,19 +35,9 @@ This flowchart illustrates developing a WasmEdge plug-in, showcasing the steps f To start developing WasmEdge plug-ins, it is essential to correctly set up the development environment. This section provides step-by-step instructions for WasmEdge plug-in development - -- **Build WasmEdge from source**: For developing the WasmEdge plug-in in C++, you must build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. +**Build WasmEdge from source**: For developing the WasmEdge plug-in in C++, you must build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. -- **Install WasmEdge with plug-ins (optional)**: Installing WasmEdge with existing plug-ins can provide additional functionality and be a reference for your plug-in development. If you want to utilize or test the compatibility of your new plug-in with existing plug-ins, you can install them using the provided installer script. The installed plug-ins will be available for your development environment. - - To see a list of supported plug-ins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plug-ins and dependencies section. - -- **Enable specific backends or additional components (if applicable):** Some plug-ins may require enabling specific backends or other components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: - - - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) - - [TensorFlow Lite](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-tensorflow-lite-backend) - - [PyTorch 1.8.2 LTS](https://pytorch.org/get-started/locally/) - -Following these steps, you can set up the development environment for effectively creating WasmEdge plug-ins, allowing you to develop, test, and debug your plug-ins in a Linux environment. +After installing WasmEdge, you need to set up the build environment. If you're using Linux or other platforms, you can follow the instructions in the [build environment setup guide](../source/os/linux.md). ## Create a WasmEdge plug-in project @@ -236,41 +226,38 @@ To build the plug-in shared library, developers should build in CMake with the W - Copy the `testplugin.h` and `testplugin.cpp` into the `/plugins/test` directory. And then edit the file `/plugins/test/CMakeLists.txt`: ```cmake - wasmedge_add_library(wasmedgePluginTest + wasmedge_add_library(wasmedgePluginWasiLogging SHARED + env.cpp + func.cpp + module.cpp testplugin.cpp ) - target_compile_options(wasmedgePluginTest + target_compile_options(wasmedgePluginWasiLogging PUBLIC -DWASMEDGE_PLUGIN ) - if(CMAKE_SYSTEM_NAME MATCHES "Darwin") - target_link_options(wasmedgePluginTest - PUBLIC - -Wl,-U,__ZN8WasmEdge6Plugin14PluginRegisterC1EPKNS0_6Plugin16PluginDescriptorE - -Wl,-U,__ZN8WasmEdge6Plugin14PluginRegisterD1Ev - ) - endif() - - target_include_directories(wasmedgePluginTest + target_include_directories(wasmedgePluginWasiLogging PUBLIC $ ${CMAKE_CURRENT_SOURCE_DIR} ) if(WASMEDGE_LINK_PLUGINS_STATIC) - target_link_libraries(wasmedgePluginTest + target_link_libraries(wasmedgePluginWasiLogging PRIVATE wasmedgeCAPI ) else() - target_link_libraries(wasmedgePluginTest + target_link_libraries(wasmedgePluginWasiLogging PRIVATE wasmedge_shared ) endif() + + install(TARGETS wasmedgePluginWasiLogging DESTINATION ${CMAKE_INSTALL_LIBDIR}/wasmedge) ``` Follow the guide to [build WasmEdge from source](../source/os/linux.md), according to your specific operating system (e.g., Linux), which will include building the plug-in shared library along with WasmEdge. diff --git a/docs/contribute/plugin/develop_plugin_rustsdk.md b/docs/contribute/plugin/develop_plugin_rustsdk.md index 65995c005..43d5634b4 100644 --- a/docs/contribute/plugin/develop_plugin_rustsdk.md +++ b/docs/contribute/plugin/develop_plugin_rustsdk.md @@ -17,17 +17,7 @@ To start developing WasmEdge plug-ins, it is essential to properly set up the de - **Build WasmEdge from source**: For developing the WasmEdge plug-in in C++, you must build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. Once you complete the C++ plug-in code, you can use witc[^1] to generate Rust Plug-in SDK. -- **Install WasmEdge with plug-ins (optional)**: Installing WasmEdge with existing plug-ins can provide additional functionality and be a reference for your plug-in development. If you want to utilize or test the compatibility of your new plug-in with existing plug-ins, you can install them using the provided installer script. The installed plug-ins will be available for your development environment. - - To see a list of supported plug-ins and their specific install commands, see the [Install WasmEdge](develop/build-and-run/install) plug-ins and dependencies section. - -- **Enable specific backends or additional components (if applicable):** Some plug-ins may require enabling specific backends or other components to extend their functionality. The following links provide instructions for enabling specific backends in WasmEdge: - - - [OpenVINO™](https://docs.openvino.ai/2021.4/openvino_docs_install_guides_installing_openvino_linux.html#)(2021) - - [TensorFlow Lite](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-tensorflow-lite-backend) - - [PyTorch 1.8.2 LTS](https://pytorch.org/get-started/locally/) - -Following these steps, you can set up the development environment for effectively creating WasmEdge plug-ins, allowing you to develop, test, and debug your plug-ins in a Linux environment. +After installing WasmEdge, you need to set up the build environment. If you're using Linux or other platforms, you can follow the instructions in the [build environment setup guide](../source/os/linux.md). ## Write the plug-in code diff --git a/docs/contribute/plugin/intro.md b/docs/contribute/plugin/intro.md index 51b638758..6d4616288 100644 --- a/docs/contribute/plugin/intro.md +++ b/docs/contribute/plugin/intro.md @@ -14,7 +14,7 @@ graph LR B -- Registers --> C((Wasmedge Runtime)) ``` -In this diagram, the _Host Application_ represents the application or environment where the Wasmedge runtime is embedded or used. The _Plug-in Shared Library_ refers to the library containing the plug-in code and functions that extend the functionality of the Wasmedge runtime. The _Wasmedge Runtime_ represents the runtime environment that executes WebAssembly modules, including the core runtime and any registered plug-ins. +In this diagram, the *Host Application* represents the application or environment where the WasmEdge runtime is embedded or used. The *Plugin Shared Library* refers to the library that provides portable host modules and host functions for WASM extension. The *WasmEdge Runtime* represents the runtime environment that executes WebAssembly modules, including the core runtime and any registered plugins. ## Usages of WasmEdge Plug-in @@ -26,17 +26,13 @@ In addition, WasmEdge plug-ins can support serverless functions for SaaS applica WasmEdge plug-ins are designed to extend the functionality of the WasmEdge runtime and can be helpful for developers and end-users in several ways: -- **Versatility:** WasmEdge plug-ins can be developed in multiple programming languages that can compile to WebAssembly, allowing developers to write plug-ins in the most comfortable language. - - **Customization:** WasmEdge plug-ins can be customized to suit the specific needs of a project. Developers can create plug-ins that integrate with other systems or tools or provide unique functionality unavailable in the core WasmEdge runtime. - **Performance:** WasmEdge plug-ins are designed to work seamlessly with the core runtime, minimizing overhead and maximizing performance, which means they can provide additional functionality without sacrificing performance. - **Ease of use:** WasmEdge plug-ins are easy to use and integrate with the WasmEdge runtime. Developers can load the plug-in into the runtime and use its functions as part of the core runtime. -- **Scalability:** WasmEdge plug-ins can scale applications by offloading compute-intensive tasks to edge devices, reducing the load on central servers and improving performance. - -- **Security:** WasmEdge plug-ins run in a sandboxed environment, which helps to reduce the risk of security vulnerabilities. Additionally, plug-ins can be digitally signed to ensure authenticity and integrity. +- **Scalability:** Developers can compile their compute-intensive functions into host functions and package them into a plug-in to provide the better performance as running in native code. WasmEdge plug-ins can provide developers and users with a versatile, customizable, high-performance, and secure way to extend the functionality of the WasmEdge runtime. WasmEdge plug-ins can also improve scalability and ease of use, making it easier to build and deploy complex applications on edge devices. @@ -55,7 +51,7 @@ To use the loadable plug-ins, developers need to load them from specific paths i - Loadable plug-ins can be loaded from default paths by calling the `WasmEdge_PluginLoadWithDefaultPaths()` API. The default paths include: - The path specified in the environment variable `WASMEDGE_PLUGIN_PATH`. - - The `../plug-in/` directory relative to the WasmEdge installation path. + - The `./plug-in/` directory relative to the WasmEdge installation path. - The `./wasmedge/` directory is located under the library path if WasmEdge is installed in a system directory such as `/usr` and `/usr/local`. - If the plug-ins are located in a specific path or directory, developers can use the `WasmEdge_PluginLoadFromPath("PATH_TO_PLUGIN/plug-in.so")` API to load the plug-ins from that particular location. @@ -87,16 +83,16 @@ By following this flowchart, developers can effectively load loadable plug-ins i 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 | Description | Released Platforms | Build Steps | -| --- | --- | --- | --- | --- | -| WasmEdge-Process | [wasmedge_process_interface][] | WasmEdge-Process is a utility plug-in for the WasmEdge Runtime, providing functionality related to process handling. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.10.0`) | [Build With WasmEdge-Process](/contribute/source/plugin/process) | -| [WASI-Crypto][] | [wasi-crypto][] | WASI-Crypto is a module that provides a set of APIs for cryptographic operations and key management. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.10.1`) | [Build With WASI-Crypto](/contribute/source/plug-in/wasi_crypto) | -| [WASI-NN with OpenVINO backend](/develop/rust/ai_inference/openvino) | [wasi-nn][] | WASI-NN with OpenVINO backend is a machine learning-oriented module for WebAssembly. | `ubuntu 20.04 x86_64` (since `0.10.1`) | [Build With WASI-NN](/contribute/source/plugin/wasi_nn#get-wasmedge-with-wasi-nn-plug-in-openvino-backend) | -| [WASI-NN with PyTorch backend](/develop/rust/ai_inference/pytorch) | [wasi-nn][] | WASI-NN with PyTorch backend allows running of PyTorch models in WebAssembly. | `ubuntu 20.04 x86_64` (since `0.11.1`) | [Build With WASI-NN](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-pytorch-backend) | -| [WASI-NN with TensorFlow-Lite backend](/develop/rust/ai_inference/pytorch) | [wasi-nn][] | WASI-NN with TensorFlow-Lite backend allows running of TensorFlow-Lite models in WebAssembly. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, and `ubuntu 20.04 x86_64` (since `0.11.2`) | [Build With WASI-NN](/contribute/source/plugin/wasi_nn#build-wasmedge-with-wasi-nn-tensorflow-lite-backend) | -| WasmEdge-Image | [wasmedge_tensorflow_interface][] | WasmEdge-Image is a plug-in that provides image processing and manipulation capabilities in WasmEdge. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, `ubuntu 20.04 x86_64`, `darwin x86_64`, and `darwin arm64` (since `0.13.0`) | [Build With WasmEdge-Image](/contribute/source/plugin/image) | -| WasmEdge-Tensorflow | [wasmedge_tensorflow_interface][] | WasmEdge-Tensorflow integrates TensorFlow with WasmEdge for running machine learning models. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, `ubuntu 20.04 x86_64`, `darwin x86_64`, and `darwin arm64` (since `0.13.0`) | [Build With WasmEdge-Tensorflow](/contribute/source/plugin/tensorflow) | -| WasmEdge-TensorflowLite | [wasmedge_tensorflow_interface][] | WasmEdge-TensorflowLite is a plug-in for running TensorFlow Lite models in WasmEdge. | `manylinux2014 x86_64`, `manylinux2014 aarch64`, `ubuntu 20.04 x86_64`, `darwin x86_64`, and `darwin arm64` (since `0.13.0`) | [Build With WasmEdge-TensorflowLite](/contribute/source/plugin/tensorflowlite) | +| Plug-in | Rust Crate | Released Platforms | Build Steps | +| --- | --- | --- | --- | +| WasmEdge-Process | [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 | [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 | [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 | [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) | :::note From c328d3d13208e49128472890b05e95e9dd3488d9 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Mon, 31 Jul 2023 11:21:31 +0600 Subject: [PATCH 13/20] update format Signed-off-by: Mahfuza --- docs/contribute/plugin/develop_plugin_c.md | 56 +++++++++---------- docs/contribute/plugin/develop_plugin_cpp.md | 2 +- .../plugin/develop_plugin_rustsdk.md | 4 +- docs/contribute/plugin/intro.md | 2 +- 4 files changed, 32 insertions(+), 32 deletions(-) diff --git a/docs/contribute/plugin/develop_plugin_c.md b/docs/contribute/plugin/develop_plugin_c.md index 8cbf7633e..b7d47b332 100644 --- a/docs/contribute/plugin/develop_plugin_c.md +++ b/docs/contribute/plugin/develop_plugin_c.md @@ -27,7 +27,7 @@ To start developing WasmEdge plug-ins, it is essential to correctly set up the d **Install a WasmEdge runtime**: You can download the latest version of WasmEdge from [GitHub repository](https://github.com/wasmEdge/wasmEdge). Follow the instructions in the [installation guide](../../start/install.md) for your specific operating system. -After installing WasmEdge, you need to set up the build environment. If you're using Linux or other platforms, you can follow the instructions in the [build environment setup guide](../source/os/linux.md). +After installing WasmEdge, you need to set up the build environment. If you're using Linux or other platforms, you can follow the instructions in the [build environment setup guide](../source/os/linux.md). ## Create a WasmEdge plug-in project @@ -58,33 +58,33 @@ To create a plug-in with host functions and modules, follow these steps: For more details about the [external data](/embed/c/host_function.md#host-data) and [calling frame context](/embed/c/host_function.md#calling-frame-context), please refer to the host function guide. ::: - Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers, respectively: - - ```c - #include - - /* The host function definitions. */ - - /* The host function to add 2 int32_t numbers. */ - WasmEdge_Result HostFuncAdd(void *Data, - const WasmEdge_CallingFrameContext *CallFrameCxt, - const WasmEdge_Value *In, WasmEdge_Value *Out) { - int32_t Val1 = WasmEdge_ValueGetI32(In[0]); - int32_t Val2 = WasmEdge_ValueGetI32(In[1]); - Out[0] = WasmEdge_ValueGenI32(Val1 + Val2); - return WasmEdge_Result_Success; - } - - /* The host function to sub 2 int32_t numbers. */ - WasmEdge_Result HostFuncSub(void *Data, - const WasmEdge_CallingFrameContext *CallFrameCxt, - const WasmEdge_Value *In, WasmEdge_Value *Out) { - int32_t Val1 = WasmEdge_ValueGetI32(In[0]); - int32_t Val2 = WasmEdge_ValueGetI32(In[1]); - Out[0] = WasmEdge_ValueGenI32(Val1 - Val2); - return WasmEdge_Result_Success; - } - ``` +Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers, respectively: + +```c +#include + +/* The host function definitions. */ + +/* The host function to add 2 int32_t numbers. */ +WasmEdge_Result HostFuncAdd(void *Data, + const WasmEdge_CallingFrameContext *CallFrameCxt, + const WasmEdge_Value *In, WasmEdge_Value *Out) { + int32_t Val1 = WasmEdge_ValueGetI32(In[0]); + int32_t Val2 = WasmEdge_ValueGetI32(In[1]); + Out[0] = WasmEdge_ValueGenI32(Val1 + Val2); + return WasmEdge_Result_Success; +} + +/* The host function to sub 2 int32_t numbers. */ +WasmEdge_Result HostFuncSub(void *Data, + const WasmEdge_CallingFrameContext *CallFrameCxt, + const WasmEdge_Value *In, WasmEdge_Value *Out) { + int32_t Val1 = WasmEdge_ValueGetI32(In[0]); + int32_t Val2 = WasmEdge_ValueGetI32(In[1]); + Out[0] = WasmEdge_ValueGenI32(Val1 - Val2); + return WasmEdge_Result_Success; +} +``` - **Implement the module creation functions**: In this step, you need to implement the module creation function that creates an instance of the module. This function will be called when the plug-in is loaded. diff --git a/docs/contribute/plugin/develop_plugin_cpp.md b/docs/contribute/plugin/develop_plugin_cpp.md index 60eee0f48..a3b0a5464 100644 --- a/docs/contribute/plugin/develop_plugin_cpp.md +++ b/docs/contribute/plugin/develop_plugin_cpp.md @@ -37,7 +37,7 @@ To start developing WasmEdge plug-ins, it is essential to correctly set up the d **Build WasmEdge from source**: For developing the WasmEdge plug-in in C++, you must build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. -After installing WasmEdge, you need to set up the build environment. If you're using Linux or other platforms, you can follow the instructions in the [build environment setup guide](../source/os/linux.md). +After installing WasmEdge, you need to set up the build environment. If you're using Linux or other platforms, you can follow the instructions in the [build environment setup guide](../source/os/linux.md). ## Create a WasmEdge plug-in project diff --git a/docs/contribute/plugin/develop_plugin_rustsdk.md b/docs/contribute/plugin/develop_plugin_rustsdk.md index 43d5634b4..c6c4d0eda 100644 --- a/docs/contribute/plugin/develop_plugin_rustsdk.md +++ b/docs/contribute/plugin/develop_plugin_rustsdk.md @@ -16,8 +16,8 @@ It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.m To start developing WasmEdge plug-ins, it is essential to properly set up the development environment. This section provides step-by-step instructions for WasmEdge plug-in development - - **Build WasmEdge from source**: For developing the WasmEdge plug-in in C++, you must build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. Once you complete the C++ plug-in code, you can use witc[^1] to generate Rust Plug-in SDK. - -After installing WasmEdge, you need to set up the build environment. If you're using Linux or other platforms, you can follow the instructions in the [build environment setup guide](../source/os/linux.md). + +After installing WasmEdge, you need to set up the build environment. If you're using Linux or other platforms, you can follow the instructions in the [build environment setup guide](../source/os/linux.md). ## Write the plug-in code diff --git a/docs/contribute/plugin/intro.md b/docs/contribute/plugin/intro.md index 6d4616288..b8db00214 100644 --- a/docs/contribute/plugin/intro.md +++ b/docs/contribute/plugin/intro.md @@ -14,7 +14,7 @@ graph LR B -- Registers --> C((Wasmedge Runtime)) ``` -In this diagram, the *Host Application* represents the application or environment where the WasmEdge runtime is embedded or used. The *Plugin Shared Library* refers to the library that provides portable host modules and host functions for WASM extension. The *WasmEdge Runtime* represents the runtime environment that executes WebAssembly modules, including the core runtime and any registered plugins. +In this diagram, the _Host Application_ represents the application or environment where the WasmEdge runtime is embedded or used. The _Plugin Shared Library_ refers to the library that provides portable host modules and host functions for WASM extension. The _WasmEdge Runtime_ represents the runtime environment that executes WebAssembly modules, including the core runtime and any registered plugins. ## Usages of WasmEdge Plug-in From 5d5b2c65c50c3a39f24140c5f8666b24025046f2 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Mon, 31 Jul 2023 15:37:30 +0600 Subject: [PATCH 14/20] added rust in intro Signed-off-by: Mahfuza --- docs/contribute/plugin/intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/plugin/intro.md b/docs/contribute/plugin/intro.md index b8db00214..9d8de20fa 100644 --- a/docs/contribute/plugin/intro.md +++ b/docs/contribute/plugin/intro.md @@ -6,7 +6,7 @@ sidebar_position: 1 While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, developers should implement the host functions before compilation. However, for a more flexible and dynamic extension of the host functions, WasmEdge provides a plug-in architecture to load the plug-in shared library. -A WasmEdge plug-in is a software component that extends the functionality of the WasmEdge runtime. Currently, developers can follow the guides to implement the plug-ins in [C API](develop_plugin_c.md) (recommended) or [C++](develop_plugin_cpp.md). With the help of the WasmEdge SDKs in the supported languages, developers can load and register the host functions from the plug-in shared libraries, allowing them to seamlessly integrate the plug-ins into the WasmEdge runtime as if they were part of the core runtime. +A WasmEdge plug-in is a software component that extends the functionality of the WasmEdge runtime. Currently, developers can follow the guides to implement the plug-ins in [C API](develop_plugin_c.md) (recommended), [C++](develop_plugin_cpp.md) and [Rust](develop_plugin_rustsdk.md). With the help of the WasmEdge SDKs in the supported languages, developers can load and register the host functions from the plug-in shared libraries, allowing them to seamlessly integrate the plug-ins into the WasmEdge runtime as if they were part of the core runtime. ```mermaid graph LR From 7289e7feed1dc5ee2356e1d772b22ece9a264ef9 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Mon, 31 Jul 2023 15:43:27 +0600 Subject: [PATCH 15/20] update reference Signed-off-by: Mahfuza --- docs/contribute/plugin/develop_plugin_c.md | 2 +- docs/contribute/plugin/develop_plugin_cpp.md | 2 +- docs/contribute/plugin/develop_plugin_rustsdk.md | 8 ++++++++ 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/contribute/plugin/develop_plugin_c.md b/docs/contribute/plugin/develop_plugin_c.md index b7d47b332..6e1fbd485 100644 --- a/docs/contribute/plugin/develop_plugin_c.md +++ b/docs/contribute/plugin/develop_plugin_c.md @@ -4,7 +4,7 @@ sidebar_position: 2 # Develop WasmEdge Plug-in in C API -By developing a plug-in, one can extend the functionality of WasmEdge and customize it to suit specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plug-in API allows such extensions to be incorporated into WasmEdge's building and releasing process. Here is a flowchart showing all the steps needed for developing WasmEdge Plug-in - +By developing a plug-in, one can extend the functionality of WasmEdge and customize it to suit specific needs. WasmEdge provides a C based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plug-in API allows such extensions to be incorporated into WasmEdge's building and releasing process. Here is a flowchart showing all the steps needed for developing WasmEdge Plug-in - ```mermaid graph LR; diff --git a/docs/contribute/plugin/develop_plugin_cpp.md b/docs/contribute/plugin/develop_plugin_cpp.md index a3b0a5464..347038bb8 100644 --- a/docs/contribute/plugin/develop_plugin_cpp.md +++ b/docs/contribute/plugin/develop_plugin_cpp.md @@ -4,7 +4,7 @@ sidebar_position: 3 # Develop WasmEdge Plug-in in C++ API -By developing a plug-in, one can extend the functionality of WasmEdge and customize it to suit specific needs. WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plug-in API allows such extensions to be incorporated into WasmEdge's building and releasing process. +By developing a plug-in, one can extend the functionality of WasmEdge and customize it to suit specific needs. WasmEdge provides a C based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plug-in API allows such extensions to be incorporated into WasmEdge's building and releasing process. :::note diff --git a/docs/contribute/plugin/develop_plugin_rustsdk.md b/docs/contribute/plugin/develop_plugin_rustsdk.md index c6c4d0eda..c961d2e0c 100644 --- a/docs/contribute/plugin/develop_plugin_rustsdk.md +++ b/docs/contribute/plugin/develop_plugin_rustsdk.md @@ -6,6 +6,14 @@ sidebar_position: 4 By developing a plug-in, one can extend the functionality of WasmEdge and customize it to suit specific needs. WasmEdge provides a Rust-based API for registering extension modules and host functions. +```mermaid +graph TD +A[Build WasmEdge from source] -- witc --> B[Generate Rust Plugin Code] +B -- SDK Crate --> C[Create SDK Crate] +C -- Module File --> D[Create Module File] +D -- Wrapper Functions --> E[Write Wrapper Functions in src/lib.rs] +``` + :::note It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plug-in development because of the support, compatibility, and flexibility the WasmEdge runtime provides. From 816d5581189457f0292d16ea4462ecae79d4cb98 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Tue, 1 Aug 2023 11:38:11 +0600 Subject: [PATCH 16/20] update Signed-off-by: Mahfuza --- docusaurus.config.js | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 10f38eb80..f1b6b19a0 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -214,7 +214,8 @@ const config = { module.exports = { ...config, markdown: { - mermaid: true, - }, - themes: ['@docusaurus/theme-mermaid'], - }; \ No newline at end of file + mermaid: true, + }, + themes: ['@docusaurus/theme-mermaid'], + }; + \ No newline at end of file From 07e5fdc7e56ca7bbdb4f64417480908ab6d21b4c Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Fri, 4 Aug 2023 07:18:16 +0600 Subject: [PATCH 17/20] update as per review Signed-off-by: Mahfuza --- docs/contribute/plugin/develop_plugin_cpp.md | 12 ++++++------ docs/contribute/plugin/intro.md | 4 +--- 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/contribute/plugin/develop_plugin_cpp.md b/docs/contribute/plugin/develop_plugin_cpp.md index 347038bb8..4608f721c 100644 --- a/docs/contribute/plugin/develop_plugin_cpp.md +++ b/docs/contribute/plugin/develop_plugin_cpp.md @@ -226,7 +226,7 @@ To build the plug-in shared library, developers should build in CMake with the W - Copy the `testplugin.h` and `testplugin.cpp` into the `/plugins/test` directory. And then edit the file `/plugins/test/CMakeLists.txt`: ```cmake - wasmedge_add_library(wasmedgePluginWasiLogging + wasmedge_add_library(wasmedgePluginTest SHARED env.cpp func.cpp @@ -234,30 +234,30 @@ To build the plug-in shared library, developers should build in CMake with the W testplugin.cpp ) - target_compile_options(wasmedgePluginWasiLogging + target_compile_options(wasmedgePluginTest PUBLIC -DWASMEDGE_PLUGIN ) - target_include_directories(wasmedgePluginWasiLogging + target_include_directories(wasmedgePluginTest PUBLIC $ ${CMAKE_CURRENT_SOURCE_DIR} ) if(WASMEDGE_LINK_PLUGINS_STATIC) - target_link_libraries(wasmedgePluginWasiLogging + target_link_libraries(wasmedgePluginTest PRIVATE wasmedgeCAPI ) else() - target_link_libraries(wasmedgePluginWasiLogging + target_link_libraries(wasmedgePluginTest PRIVATE wasmedge_shared ) endif() - install(TARGETS wasmedgePluginWasiLogging DESTINATION ${CMAKE_INSTALL_LIBDIR}/wasmedge) + install(TARGETS wasmedgePluginTest DESTINATION ${CMAKE_INSTALL_LIBDIR}/wasmedge) ``` Follow the guide to [build WasmEdge from source](../source/os/linux.md), according to your specific operating system (e.g., Linux), which will include building the plug-in shared library along with WasmEdge. diff --git a/docs/contribute/plugin/intro.md b/docs/contribute/plugin/intro.md index 9d8de20fa..57eb66c06 100644 --- a/docs/contribute/plugin/intro.md +++ b/docs/contribute/plugin/intro.md @@ -14,8 +14,6 @@ graph LR B -- Registers --> C((Wasmedge Runtime)) ``` -In this diagram, the _Host Application_ represents the application or environment where the WasmEdge runtime is embedded or used. The _Plugin Shared Library_ refers to the library that provides portable host modules and host functions for WASM extension. The _WasmEdge Runtime_ represents the runtime environment that executes WebAssembly modules, including the core runtime and any registered plugins. - ## Usages of WasmEdge Plug-in WasmEdge plug-ins can be used in various scenarios, such as high-performance domain-specific languages, cloud-native JavaScript runtime, edge computing, serverless, SaaS, service mesh, and blockchain applications. Moreover, WasmEdge plug-ins can be used in microservices, providing a lightweight, secure, high-performance runtime compatible with frameworks like Dapr and Kubernetes. @@ -51,7 +49,7 @@ To use the loadable plug-ins, developers need to load them from specific paths i - Loadable plug-ins can be loaded from default paths by calling the `WasmEdge_PluginLoadWithDefaultPaths()` API. The default paths include: - The path specified in the environment variable `WASMEDGE_PLUGIN_PATH`. - - The `./plug-in/` directory relative to the WasmEdge installation path. + - The `./plugin/` directory relative to the WasmEdge installation path. - The `./wasmedge/` directory is located under the library path if WasmEdge is installed in a system directory such as `/usr` and `/usr/local`. - If the plug-ins are located in a specific path or directory, developers can use the `WasmEdge_PluginLoadFromPath("PATH_TO_PLUGIN/plug-in.so")` API to load the plug-ins from that particular location. From 5b703db963b39183a2ecb5c7be4d613bd589520b Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Mon, 7 Aug 2023 07:56:09 +0600 Subject: [PATCH 18/20] Update intro.md Signed-off-by: Mahfuza --- docs/contribute/plugin/intro.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/contribute/plugin/intro.md b/docs/contribute/plugin/intro.md index 57eb66c06..06981a1b9 100644 --- a/docs/contribute/plugin/intro.md +++ b/docs/contribute/plugin/intro.md @@ -14,12 +14,6 @@ graph LR B -- Registers --> C((Wasmedge Runtime)) ``` -## Usages of WasmEdge Plug-in - -WasmEdge plug-ins can be used in various scenarios, such as high-performance domain-specific languages, cloud-native JavaScript runtime, edge computing, serverless, SaaS, service mesh, and blockchain applications. Moreover, WasmEdge plug-ins can be used in microservices, providing a lightweight, secure, high-performance runtime compatible with frameworks like Dapr and Kubernetes. - -In addition, WasmEdge plug-ins can support serverless functions for SaaS applications, allowing users to extend and customize their experience without operating their API callback servers. They can also be embedded into innovative device applications as middleware runtime, rendering interactive content on the UI, connecting to native device drivers, and accessing specialized hardware features. WasmEdge plug-ins can manage application state, exchange dynamic data (e.g., strings and arrays) with Wasm programs, and provide native host functions to manipulate data. - ## Benefits of Using WasmEdge Plug-in WasmEdge plug-ins are designed to extend the functionality of the WasmEdge runtime and can be helpful for developers and end-users in several ways: From f3726db7546c85c137f78186e08718930b3caf99 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Wed, 9 Aug 2023 11:13:57 +0600 Subject: [PATCH 19/20] fix typo Signed-off-by: Mahfuza --- docs/contribute/plugin/develop_plugin_c.md | 6 +- docs/contribute/plugin/develop_plugin_cpp.md | 12 +- .../plugin/develop_plugin_rustsdk.md | 4 +- docs/contribute/plugin/intro.md | 10 +- docusaurus.config.js | 15 +- .../current/contribute/plugin/_category_.json | 2 +- .../contribute/plugin/develop_plugin_c.md | 340 +++++++++------- .../contribute/plugin/develop_plugin_cpp.md | 381 ++++++++++-------- .../plugin/develop_plugin_rustsdk.md | 95 +++-- .../current/contribute/plugin/intro.md | 67 ++- 10 files changed, 535 insertions(+), 397 deletions(-) diff --git a/docs/contribute/plugin/develop_plugin_c.md b/docs/contribute/plugin/develop_plugin_c.md index 6e1fbd485..1784380bd 100644 --- a/docs/contribute/plugin/develop_plugin_c.md +++ b/docs/contribute/plugin/develop_plugin_c.md @@ -11,8 +11,8 @@ graph LR; A[Developing WasmEdge Plug-in in C] A --> B(Set up the development environment) A --> C(Create a WasmEdge plug-in project) -A --> D(Write the plugin code) -A --> E(Build the plugin) +A --> D(Write the plug-in code) +A --> E(Build the plug-in) A --> F(Test and debug the plug-in) B --> E C --> D @@ -194,7 +194,7 @@ Remember to implement any additional functions or structures your plug-in requir Following these steps and implementing the necessary functions and descriptors, you can create a plug-in with host functions and modules in WasmEdge C API. You can continue developing your plug-in by adding functionality and implementing the desired behavior. -- **Plugin option** - _WORK IN PROGRESS. This section is reserved for the feature in the future._ +- **Plug-in option** - _WORK IN PROGRESS. This section is reserved for the feature in the future._ ## Build your plug-in diff --git a/docs/contribute/plugin/develop_plugin_cpp.md b/docs/contribute/plugin/develop_plugin_cpp.md index 4608f721c..7a5e6a07d 100644 --- a/docs/contribute/plugin/develop_plugin_cpp.md +++ b/docs/contribute/plugin/develop_plugin_cpp.md @@ -15,18 +15,18 @@ Here is a flowchart showing all the steps needed for developing WasmEdge Plug-in ```mermaid graph TD; -A[Develop WasmEdge Plugin in C++ API] +A[Develop WasmEdge Plug-in in C++ API] A --> B(Set up development environment) B --> C(Create project directory) C --> D(Add configuration files) D --> E(Install necessary tools and dependencies) E --> F(Enable specific backends or components) -F --> G(Write plugin code) -G --> H(Build plugin) -C --> I(Define plugin API) +F --> G(Write plug-in code) +G --> H(Build plug-in) +C --> I(Define plug-in API) H --> I -I --> J(Compile WasmEdge plugin) -J --> K(Test and debug plugin) +I --> J(Compile WasmEdge plug-in) +J --> K(Test and debug plug-in) ``` This flowchart illustrates developing a WasmEdge plug-in, showcasing the steps from choosing a programming language to finalizing and releasing the plug-in. diff --git a/docs/contribute/plugin/develop_plugin_rustsdk.md b/docs/contribute/plugin/develop_plugin_rustsdk.md index c961d2e0c..8176ff89b 100644 --- a/docs/contribute/plugin/develop_plugin_rustsdk.md +++ b/docs/contribute/plugin/develop_plugin_rustsdk.md @@ -8,7 +8,7 @@ By developing a plug-in, one can extend the functionality of WasmEdge and custom ```mermaid graph TD -A[Build WasmEdge from source] -- witc --> B[Generate Rust Plugin Code] +A[Build WasmEdge from source] -- witc --> B[Generate Rust Plug-in Code] B -- SDK Crate --> C[Create SDK Crate] C -- Module File --> D[Create Module File] D -- Wrapper Functions --> E[Write Wrapper Functions in src/lib.rs] @@ -31,7 +31,7 @@ After installing WasmEdge, you need to set up the build environment. If you're u To develop a WasmEdge Plug-in in Rust using the witc tool, you can follow these steps: -- **Generate Rust Plugin Code**: Consider you have a file named `wasmedge_opencvmini.wit` with the following content: +- **Generate Rust Plug-in Code**: Consider you have a file named `wasmedge_opencvmini.wit` with the following content: ```wit imdecode: func(buf: list) -> u32 diff --git a/docs/contribute/plugin/intro.md b/docs/contribute/plugin/intro.md index 06981a1b9..67267473f 100644 --- a/docs/contribute/plugin/intro.md +++ b/docs/contribute/plugin/intro.md @@ -10,7 +10,7 @@ A WasmEdge plug-in is a software component that extends the functionality of the ```mermaid graph LR - A((Host Application)) -- Loads --> B((Plugin Shared Library)) + A((Host Application)) -- Loads --> B((Plug-in Shared Library)) B -- Registers --> C((Wasmedge Runtime)) ``` @@ -54,15 +54,15 @@ The following flowchart shows the process of loading loadable plug-ins into the ```mermaid graph LR - A((Start)) --> B(Loadable Plugins) - B --> C{Load Plugins} + A((Start)) --> B(Loadable Plug-ins) + B --> C{Load Plug-ins} C --> D[Load from Default Paths] C --> E[Load from Specific Path] C --> F[Load from Specific Directory] - D --> G{Is Plugin Found?} + D --> G{Is Plug-in Found?} E --> G F --> G - G -- Yes --> H(Load Plugin) + G -- Yes --> H(Load Plug-in) H --> I(End) G -- No --> I ``` diff --git a/docusaurus.config.js b/docusaurus.config.js index f1b6b19a0..035da1cd8 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -58,6 +58,10 @@ const config = { }), ], ], + + markdown: { + mermaid: true, + }, themes : [ [ @@ -77,11 +81,13 @@ const config = { searchBarPosition: "right", }, ], + ['@docusaurus/theme-mermaid'], ], themeConfig: /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ + metadata: [{ name: 'keywords', content: 'wasmedge, wasm, web assembly, rust, cncf, edge devices, cloud, serverless' }, { name: 'twitter:card', content: 'summary' }], image: "./static/img/wasm_logo.png", announcementBar: { id: "start", @@ -211,11 +217,4 @@ const config = { }), }; -module.exports = { - ...config, - markdown: { - mermaid: true, - }, - themes: ['@docusaurus/theme-mermaid'], - }; - \ No newline at end of file +module.exports = config; diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/_category_.json b/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/_category_.json index fcdcda0bc..d5890d316 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/_category_.json +++ b/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/_category_.json @@ -3,6 +3,6 @@ "position": 3, "link": { "type": "generated-index", - "description": "we will learn how to the WasmEdge Plugin System." + "description": "We will learn how to develop the plug-ins for WasmEdge." } } diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/develop_plugin_c.md b/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/develop_plugin_c.md index 446686fc6..1784380bd 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/develop_plugin_c.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/develop_plugin_c.md @@ -4,27 +4,62 @@ sidebar_position: 2 # Develop WasmEdge Plug-in in C API -WasmEdge provides a C++ based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plugin API allows such extensions to be incorporated into WasmEdge's own building and releasing process. +By developing a plug-in, one can extend the functionality of WasmEdge and customize it to suit specific needs. WasmEdge provides a C based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plug-in API allows such extensions to be incorporated into WasmEdge's building and releasing process. Here is a flowchart showing all the steps needed for developing WasmEdge Plug-in - + +```mermaid +graph LR; +A[Developing WasmEdge Plug-in in C] +A --> B(Set up the development environment) +A --> C(Create a WasmEdge plug-in project) +A --> D(Write the plug-in code) +A --> E(Build the plug-in) +A --> F(Test and debug the plug-in) +B --> E +C --> D +D --> E +``` + +This flowchart illustrates developing a WasmEdge plug-in, showcasing the steps from choosing a programming language to finalizing and releasing the plug-in. + +## Set up the development environment + +To start developing WasmEdge plug-ins, it is essential to correctly set up the development environment. This section provides step-by-step instructions for WasmEdge plug-in development - + +**Install a WasmEdge runtime**: You can download the latest version of WasmEdge from [GitHub repository](https://github.com/wasmEdge/wasmEdge). Follow the instructions in the [installation guide](../../start/install.md) for your specific operating system. -## Prerequisites +After installing WasmEdge, you need to set up the build environment. If you're using Linux or other platforms, you can follow the instructions in the [build environment setup guide](../source/os/linux.md). -For developing the WasmEdge plug-in in C API, please [install WasmEdge](../../start/install.md#install) first. +## Create a WasmEdge plug-in project -## Example +To create a WasmEdge plug-in project, follow these steps: -Assume that the plug-in example is in the file `testplugin.c`. +- **Set up the project directory**: Create a directory structure for your plug-in project. You can use a standard structure for the chosen language or create your structure. To create a project directory structure, use the following commands: -### Host Functions + ```bash + mkdir testplugin + cd testplugin + mkdir src include build + ``` -The goal of the plug-in is to provide the host functions which can be imported when instantiating WASM. +- **Add configuration files**: Add configuration files specifying the plug-in name, version, and dependencies. The specific files and content depend on the chosen programming language and build system. -Therefore, developers can implement their plug-in host functions first, as the same as the [host functions in WasmEdge C API](../../embed/c/reference/latest.md#host-functions). +- **Add any necessary libraries or dependencies**: Include any required libraries or dependencies for your plug-in. Modify the configuration files created in the previous step to include the required dependencies. + +## Write the plug-in code + +To create a plug-in with host functions and modules, follow these steps: + +- **Implement host function definitions**: In this step, you must define the host functions that will be imported when instantiating the WASM module. These functions will perform specific operations and return results. + + Therefore, developers can first implement their plug-in host functions, like the [host functions in WasmEdge C API](/embed/c/reference/latest.md#host-functions). :::note -For the more details about the [external data](../../embed/c/host_function.md#host-data) and [calling frame context](../../embed/c/host_function.md#calling-frame-context), please refer to the host function guide. +For more details about the [external data](/embed/c/host_function.md#host-data) and [calling frame context](/embed/c/host_function.md#calling-frame-context), please refer to the host function guide. ::: +Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers, respectively: + ```c #include @@ -51,152 +86,147 @@ WasmEdge_Result HostFuncSub(void *Data, } ``` -### Host Modules +- **Implement the module creation functions**: In this step, you need to implement the module creation function that creates an instance of the module. This function will be called when the plug-in is loaded. -Then developers should implement the module creation functions. + Here's an example of a module creation function named `CreateTestModule`: -Noticed that there can be several module instances in a plug-in shared library. Here take a module named as `wasmedge_plugintest_c_module` for the example. - -```c -/* The creation function of creating the module instance. */ -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 the description from this descriptor. - */ - - /* Exported module name of this module instance. */ - WasmEdge_String ModuleName = - WasmEdge_StringCreateByCString("wasmedge_plugintest_c_module"); - WasmEdge_ModuleInstanceContext *Mod = - WasmEdge_ModuleInstanceCreate(ModuleName); - WasmEdge_StringDelete(ModuleName); - - 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; - - /* Create and add the host function instances into the module instance. */ - FType = WasmEdge_FunctionTypeCreate(ParamTypes, 2, ReturnTypes, 1); - FuncName = WasmEdge_StringCreateByCString("add"); - FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncAdd, NULL, 0); - WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); - WasmEdge_StringDelete(FuncName); - FuncName = WasmEdge_StringCreateByCString("sub"); - FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncSub, NULL, 0); - WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); - WasmEdge_StringDelete(FuncName); - WasmEdge_FunctionTypeDelete(FType); - - return Mod; -} -``` - -### Plug-in Descriptions - -For constructing the plug-in, developers should supply the descriptions of this plug-in and the modules. - -```c -/* The module descriptor array. There can be multiple modules in a plug-in. */ -static WasmEdge_ModuleDescriptor ModuleDesc[] = {{ + ```c + /* The creation function of creating the module instance. */ + WasmEdge_ModuleInstanceContext * + CreateTestModule(const struct WasmEdge_ModuleDescriptor *Desc) { /* - * 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.", - /* Creation function pointer. */ - .Create = CreateTestModule, -}}; - -/* 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. - */ - .Name = "wasmedge_plugintest_c", - /* Plug-in description. */ - .Description = "", - /* Plug-in API version. */ - .APIVersion = WasmEdge_Plugin_CurrentAPIVersion, - /* Plug-in version. Developers can define the version of this plug-in. */ - .Version = - { - .Major = 0, - .Minor = 1, - .Patch = 0, - .Build = 0, - }, - /* Module count in this plug-in. */ - .ModuleCount = 1, - /* Plug-in option description count in this plug-in (Work in progress). */ - .ProgramOptionCount = 0, - /* Pointer to the module description array. */ - .ModuleDescriptions = ModuleDesc, - /* Pointer to the plug-in option description array (Work in progress). */ - .ProgramOptions = NULL, -}}; -``` - -### Plug-in Options - -WORK IN PROGRESS. This section is reserved for the feature in the future. - -### Implement the Get Descriptor API - -The final step is to implement the `WasmEdge_Plugin_GetDescriptor()` API to return the plug-in descriptor. - -```c -WASMEDGE_CAPI_PLUGIN_EXPORT const WasmEdge_PluginDescriptor * -WasmEdge_Plugin_GetDescriptor(void) { - return &Desc; -} -``` - -## Build - -To build the plug-in shared library, developers can choose to build stand-alone by the compiler or use cmake. - -### Build with Command - -```bash -clang -shared -std=c11 -DWASMEDGE_PLUGIN testplugin.c -lwasmedge -o libwasmedgePluginTest.so -``` - -### Build in CMake - -```cmake -add_library(wasmedgePluginTest - SHARED - testplugin.c -) - -set_target_properties(wasmedgePluginTest PROPERTIES - C_STANDARD 11 -) - -target_compile_options(wasmedgePluginTest - PUBLIC - -DWASMEDGE_PLUGIN -) - -target_link_libraries(wasmedgePluginTest - PRIVATE - wasmedge -) -``` + * 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 = + WasmEdge_StringCreateByCString("wasmedge_plugintest_c_module"); + WasmEdge_ModuleInstanceContext *Mod = + WasmEdge_ModuleInstanceCreate(ModuleName); + WasmEdge_StringDelete(ModuleName); + + 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; + + /* Create and add the host function instances into the module instance. */ + FType = WasmEdge_FunctionTypeCreate(ParamTypes, 2, ReturnTypes, 1); + FuncName = WasmEdge_StringCreateByCString("add"); + FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncAdd, NULL, 0); + WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); + WasmEdge_StringDelete(FuncName); + FuncName = WasmEdge_StringCreateByCString("sub"); + FuncCxt = WasmEdge_FunctionInstanceCreate(FType, HostFuncSub, NULL, 0); + WasmEdge_ModuleInstanceAddFunction(Mod, FuncName, FuncCxt); + WasmEdge_StringDelete(FuncName); + WasmEdge_FunctionTypeDelete(FType); + + return Mod; + } + ``` + + There can be several module instances in a plug-in shared library. Here in the above code snippet, take a module named `wasmedge_plugintest_c_module` for the example. + +- **Supply the plug-in descriptions**- In this step, you need to provide the descriptions of the plug-in and the modules it contains. These descriptions will be used for searching and creating the plug-in and module instances. + + Here's an example of the plug-in and module descriptors: + + ```c + /* 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. + */ + .Name = "wasmedge_plugintest_c_module", + /* Module description. */ + .Description = "This is for the plugin tests in WasmEdge C API.", + /* Creation function pointer. */ + .Create = CreateTestModule, + }}; + + /* 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. + */ + .Name = "wasmedge_plugintest_c", + /* Plug-in description. */ + .Description = "", + /* Plug-in API version. */ + .APIVersion = WasmEdge_Plugin_CurrentAPIVersion, + /* Plug-in version. Developers can define the version of this plug-in. */ + .Version = + { + .Major = 0, + .Minor = 1, + .Patch = 0, + .Build = 0, + }, + /* Module count in this plug-in. */ + .ModuleCount = 1, + /* Plug-in option description count in this plug-in (Work in progress). */ + .ProgramOptionCount = 0, + /* Pointer to the module description array. */ + .ModuleDescriptions = ModuleDesc, + /* Pointer to the plug-in option description array (Work in progress). */ + .ProgramOptions = NULL, + }}; + ``` + + These descriptions define the name, description, version, and creation function of the plug-in and the name and description of the module it contains. + +Remember to implement any additional functions or structures your plug-in requires to fulfill its functionality. + +Following these steps and implementing the necessary functions and descriptors, you can create a plug-in with host functions and modules in WasmEdge C API. You can continue developing your plug-in by adding functionality and implementing the desired behavior. + +- **Plug-in option** - _WORK IN PROGRESS. This section is reserved for the feature in the future._ + +## Build your plug-in + +To build the WasmEdge plug-in shared library, you have two options: build it directly using the compiler or CMake. Here are the instructions for both methods: + +- **Build with Command**: if you choose to build the plug-in using the command line, run the following command in the terminal: + + This command compiles the `testplugin.c` file into a shared library named `libwasmedgePluginTest.so`. The `-std=c11` flag sets the C language standard to C11, and the `-DWASMEDGE_PLUGIN` flag defines the WASMEDGE_PLUGIN macro, which can be used in your code. + +- **Build with CMake**: If you prefer to use CMake to build the plug-in, create a `CMakeLists.txt` file in the root directory of your project and add the following content to the CMakeLists.txt file: + + ```cmake + add_library(wasmedgePluginTest + SHARED + testplugin.c + ) + + set_target_properties(wasmedgePluginTest PROPERTIES + C_STANDARD 11 + ) + + target_compile_options(wasmedgePluginTest + PUBLIC + -DWASMEDGE_PLUGIN + ) + + target_link_libraries(wasmedgePluginTest + PRIVATE + wasmedge + ) + ``` + + This CMake configuration sets up a build target called `wasmedgePluginTest`. It compiles the `testplugin.c` file into a shared library. The `C_STANDARD 11` property sets the C language standard to C11. The `target_compile_options` command defines the `WASMEDGE_PLUGIN` macro using the `-DWASMEDGE_PLUGIN` flag. Finally, the `target_link_libraries` command links the wasmedge library to the plug-in. + +Once you have set up either the command-line build or the CMake build, you can execute the corresponding build command or generate build files using CMake, which will compile your plug-in source code and produce the shared library file `(libwasmedgePluginTest.so)`. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/develop_plugin_cpp.md b/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/develop_plugin_cpp.md index a4a639194..7a5e6a07d 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/develop_plugin_cpp.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/develop_plugin_cpp.md @@ -4,170 +4,200 @@ sidebar_position: 3 # Develop WasmEdge Plug-in in C++ API +By developing a plug-in, one can extend the functionality of WasmEdge and customize it to suit specific needs. WasmEdge provides a C based API for registering extension modules and host functions. While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, the plug-in API allows such extensions to be incorporated into WasmEdge's building and releasing process. + :::note -We recommend developers to [develop plug-ins in WasmEdge C API](develop_plugin_c.md). +It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plug-in development because of the support, compatibility, and flexibility the WasmEdge runtime provides. ::: -## Prerequisites +Here is a flowchart showing all the steps needed for developing WasmEdge Plug-in - + +```mermaid +graph TD; +A[Develop WasmEdge Plug-in in C++ API] +A --> B(Set up development environment) +B --> C(Create project directory) +C --> D(Add configuration files) +D --> E(Install necessary tools and dependencies) +E --> F(Enable specific backends or components) +F --> G(Write plug-in code) +G --> H(Build plug-in) +C --> I(Define plug-in API) +H --> I +I --> J(Compile WasmEdge plug-in) +J --> K(Test and debug plug-in) +``` -For developing the WasmEdge plug-in in internal C++, developers should [build WasmEdge from source](../source/build_from_src.md). +This flowchart illustrates developing a WasmEdge plug-in, showcasing the steps from choosing a programming language to finalizing and releasing the plug-in. -## Example +## Set up a development environment -Assume that the plug-in example is in the file `testplugin.h` and `testplugin.cpp`. +To start developing WasmEdge plug-ins, it is essential to correctly set up the development environment. This section provides step-by-step instructions for WasmEdge plug-in development - -### Host Functions and Modules +**Build WasmEdge from source**: For developing the WasmEdge plug-in in C++, you must build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. -The goal of the plug-in is to provide the host functions which can be imported when instantiating WASM. Therefore, developers should implement their plug-in host functions in WasmEdge internal C++ first. Assume that the host function implementations are in the `testplugin.h`. +After installing WasmEdge, you need to set up the build environment. If you're using Linux or other platforms, you can follow the instructions in the [build environment setup guide](../source/os/linux.md). -```cpp -#pragma once +## Create a WasmEdge plug-in project -#include "plugin/plugin.h" +To create a WasmEdge plug-in project, follow these steps: -#include -#include +- **Set up the project directory**: Create a directory structure for your plug-in project. You can use a standard structure for the chosen language or create your structure. To create a project directory structure, use the following commands: -namespace WasmEdge { -namespace Host { + ```bash + mkdir testplugin + cd testplugin + mkdir src include build + ``` -// The environment class. For the register object. -class WasmEdgePluginTestEnv { -public: - WasmEdgePluginTestEnv() noexcept = default; - - static Plugin::PluginRegister Register; -}; - -// The host function base template class. For inheriting the environment class -// reference. -template -class WasmEdgePluginTestFunc : public Runtime::HostFunction { -public: - WasmEdgePluginTestFunc(WasmEdgePluginTestEnv &HostEnv) - : Runtime::HostFunction(0), Env(HostEnv) {} - -protected: - WasmEdgePluginTestEnv &Env; -}; - -// The host function to add 2 int32_t numbers. -class WasmEdgePluginTestFuncAdd - : public WasmEdgePluginTestFunc { -public: - WasmEdgePluginTestFuncAdd(WasmEdgePluginTestEnv &HostEnv) - : WasmEdgePluginTestFunc(HostEnv) {} - Expect body(const Runtime::CallingFrame &, uint32_t A, uint32_t B) { - return A + B; - } -}; - -// The host function to sub 2 int32_t numbers. -class WasmEdgePluginTestFuncSub - : public WasmEdgePluginTestFunc { -public: - WasmEdgePluginTestFuncSub(WasmEdgePluginTestEnv &HostEnv) - : WasmEdgePluginTestFunc(HostEnv) {} - Expect body(const Runtime::CallingFrame &, uint32_t A, uint32_t B) { - return A - B; - } -}; - -// The host module class. There can be several modules in a plug-in. -class WasmEdgePluginTestModule : public Runtime::Instance::ModuleInstance { -public: - WasmEdgePluginTestModule() - : Runtime::Instance::ModuleInstance("wasmedge_plugintest_cpp_module") { - addHostFunc("add", std::make_unique(Env)); - addHostFunc("sub", std::make_unique(Env)); - } +- **Add necessary libraries or dependencies**: Include any required libraries or dependencies for your plug-in. Modify the configuration files created in the previous step to include the required dependencies. - WasmEdgePluginTestEnv &getEnv() { return Env; } +## Write plug-in code -private: - WasmEdgePluginTestEnv Env; -}; +To create a plug-in with host functions and modules, follow these steps: -} // namespace Host -} // namespace WasmEdge -``` +- **Host Functions and Modules**: The plug-in aims to provide the host functions that can be imported when instantiating WASM. Therefore, developers should first implement their plug-in host functions in WasmEdge internal C++. Assume that the host function implementations are in the `testplugin.h`. -### Creation Functions for Modules + ```cpp + #pragma once -Then developers should implement the module creation functions. Assume that the following implementations are all in the `testplugin.cpp`. + #include "plug-in/plug-in.h" -```cpp -#include "testplugin.h" + #include + #include -namespace WasmEdge { -namespace Host { -namespace { + namespace WasmEdge { + namespace Host { -Runtime::Instance::ModuleInstance * -create(const Plugin::PluginModule::ModuleDescriptor *) noexcept { - // There can be several modules in a plug-in. For that, developers should - // implement several `create` functions for each module. - return new WasmEdgePluginTestModule; -} + // The environment class. For the register object. + class WasmEdgePluginTestEnv { + public: + WasmEdgePluginTestEnv() noexcept = default; -} // namespace -} // namespace Host -} // namespace WasmEdge -``` + static Plugin::PluginRegister Register; + }; -### Plug-in Descriptions + // The host function base template class. For inheriting the environment class + // reference. + template + class WasmEdgePluginTestFunc : public Runtime::HostFunction { + public: + WasmEdgePluginTestFunc(WasmEdgePluginTestEnv &HostEnv) + : Runtime::HostFunction(0), Env(HostEnv) {} -For constructing the plug-in, developers should supply the descriptions of this plug-in and the modules. + protected: + WasmEdgePluginTestEnv &Env; + }; -```cpp -namespace WasmEdge { -namespace Host { -namespace { - -Plugin::Plugin::PluginDescriptor Descriptor{ - // Plug-in name. This is the name for searching the plug-in context by the - // `WasmEdge_PluginFind()` C API. - .Name = "wasmedge_plugintest_cpp", - // Plug-in description. - .Description = "", - // Plug-in API version. - .APIVersion = Plugin::Plugin::CurrentAPIVersion, - // Plug-in version. - .Version = {0, 10, 0, 0}, - // Module count in this plug-in. - .ModuleCount = 1, - // Pointer to module description array. - .ModuleDescriptions = - // The module descriptor array. - (Plugin::PluginModule::ModuleDescriptor[]){ - { - // Module name. This is the name for searching and creating the - // module instance context by the - // `WasmEdge_PluginCreateModule()` C API. - .Name = "wasmedge_plugintest_cpp_module", - // Module description. - .Description = "This is for the plugin tests in WasmEdge.", - // Creation function pointer. - .Create = create, - }, - }, - // Plug-in options (Work in progress). - .AddOptions = nullptr, -}; - -} // namespace -} // namespace Host -} // namespace WasmEdge -``` + // The host function to add 2 int32_t numbers. + class WasmEdgePluginTestFuncAdd + : public WasmEdgePluginTestFunc { + public: + WasmEdgePluginTestFuncAdd(WasmEdgePluginTestEnv &HostEnv) + : WasmEdgePluginTestFunc(HostEnv) {} + Expect body(const Runtime::CallingFrame &, uint32_t A, uint32_t B) { + return A + B; + } + }; + + // The host function to sub 2 int32_t numbers. + class WasmEdgePluginTestFuncSub + : public WasmEdgePluginTestFunc { + public: + WasmEdgePluginTestFuncSub(WasmEdgePluginTestEnv &HostEnv) + : WasmEdgePluginTestFunc(HostEnv) {} + Expect body(const Runtime::CallingFrame &, uint32_t A, uint32_t B) { + return A - B; + } + }; + + // The host module class. There can be several modules in a plug-in. + class WasmEdgePluginTestModule : public Runtime::Instance::ModuleInstance { + public: + WasmEdgePluginTestModule() + : Runtime::Instance::ModuleInstance("wasmedge_plugintest_cpp_module") { + addHostFunc("add", std::make_unique(Env)); + addHostFunc("sub", std::make_unique(Env)); + } + + WasmEdgePluginTestEnv &getEnv() { return Env; } + + private: + WasmEdgePluginTestEnv Env; + }; -### Plug-in Options + } // namespace Host + } // namespace WasmEdge + ``` -WORK IN PROGRESS. This section is reserved for the feature in the future. +- **Creation Functions for Modules**: Then developers should implement the module creation functions. Assume the following implementations are all in the `testplugin.cpp`. -### Implement the Plug-in Descriptor Registration + ```cpp + #include "testplugin.h" -The final step is to implement the `Plugin::PluginRegister` initialization with the plug-in descriptor. + namespace WasmEdge { + namespace Host { + namespace { + + Runtime::Instance::ModuleInstance * + create(const Plugin::PluginModule::ModuleDescriptor *) noexcept { + // There can be several modules in a plug-in. For that, developers should + // implement several `create` functions for each module. + return new WasmEdgePluginTestModule; + } + + } // namespace + } // namespace Host + } // namespace WasmEdge + ``` + +- **Plug-in Descriptions**: For constructing the plug-in, developers should supply the descriptions of this plug-in and the modules. + + ```cpp + namespace WasmEdge { + namespace Host { + namespace { + + Plugin::Plugin::PluginDescriptor Descriptor{ + //Plug-in name - for searching the plug-in context by the + // `WasmEdge_PluginFind()` C API. + .Name = "wasmedge_plugintest_cpp", + //Plug-in description. + .Description = "", + //Plug-in API version. + .APIVersion = Plugin::Plugin::CurrentAPIVersion, + //Plug-in version. + .Version = {0, 10, 0, 0}, + // Module count in this plug-in. + .ModuleCount = 1, + // Pointer to module description array. + .ModuleDescriptions = + // The module descriptor array. + (Plugin::PluginModule::ModuleDescriptor[]){ + { + // Module name. This is the name for searching and creating the + // module instance context by the + // `WasmEdge_PluginCreateModule()` C API. + .Name = "wasmedge_plugintest_cpp_module", + // Module description. + .Description = "This is for the plugin tests in WasmEdge.", + // Creation function pointer. + .Create = create, + }, + }, + //Plug-in options (Work in progress). + .AddOptions = nullptr, + }; + + } // namespace + } // namespace Host + } // namespace WasmEdge + ``` + +- **Plug-in Options**: WORK IN PROGRESS. This section is reserved for the feature in the future. + +- **Implement Plug-in Descriptor Registration**: The final step is to implement the `Plugin::PluginRegister` initialization with the plug-in descriptor. ```cpp namespace WasmEdge { @@ -179,58 +209,55 @@ Plugin::PluginRegister WasmEdgePluginTestEnv::Register(&Descriptor); } // namespace WasmEdge ``` -## Build +Remember to implement any additional functions or structures your plug-in requires to fulfill its functionality. -To build the plug-in shared library, developers should build in cmake with the WasmEdge source. +Following these steps and implementing the necessary functions and descriptors, you can create a plug-in with host functions and modules in WasmEdge C++ API. You can continue developing your plug-in by adding functionality and implementing the desired behavior. -Assume that the folder `test` is created under the `/plugins`. +## Build plug-in -Add this line in the `/plugins/CMakeLists.txt`: +To build the plug-in shared library, developers should build in CMake with the WasmEdge source. -```cmake -add_subdirectory(test) -``` +- Assume that the' test' folder is created under the `/plug-ins`. Add this line in the `/plugins/CMakeLists.txt`: -Copy the `testplugin.h` and `testplugin.cpp` into the `/plugins/test` directory. + ```cmake + add_subdirectory(test) + ``` -And then edit the file `/plugins/test/CMakeLists.txt`: +- Copy the `testplugin.h` and `testplugin.cpp` into the `/plugins/test` directory. And then edit the file `/plugins/test/CMakeLists.txt`: -```cmake -wasmedge_add_library(wasmedgePluginTest - SHARED - testplugin.cpp -) - -target_compile_options(wasmedgePluginTest - PUBLIC - -DWASMEDGE_PLUGIN -) + ```cmake + wasmedge_add_library(wasmedgePluginTest + SHARED + env.cpp + func.cpp + module.cpp + testplugin.cpp + ) -if(CMAKE_SYSTEM_NAME MATCHES "Darwin") - target_link_options(wasmedgePluginTest + target_compile_options(wasmedgePluginTest PUBLIC - -Wl,-U,__ZN8WasmEdge6Plugin14PluginRegisterC1EPKNS0_6Plugin16PluginDescriptorE - -Wl,-U,__ZN8WasmEdge6Plugin14PluginRegisterD1Ev + -DWASMEDGE_PLUGIN ) -endif() - -target_include_directories(wasmedgePluginTest - PUBLIC - $ - ${CMAKE_CURRENT_SOURCE_DIR} -) - -if(WASMEDGE_LINK_PLUGINS_STATIC) - target_link_libraries(wasmedgePluginTest - PRIVATE - wasmedgeCAPI - ) -else() - target_link_libraries(wasmedgePluginTest - PRIVATE - wasmedge_shared + + target_include_directories(wasmedgePluginTest + PUBLIC + $ + ${CMAKE_CURRENT_SOURCE_DIR} ) -endif() -``` -Then you can [follow the guide to build from source](../source/os/linux.md). + if(WASMEDGE_LINK_PLUGINS_STATIC) + target_link_libraries(wasmedgePluginTest + PRIVATE + wasmedgeCAPI + ) + else() + target_link_libraries(wasmedgePluginTest + PRIVATE + wasmedge_shared + ) + endif() + + install(TARGETS wasmedgePluginTest DESTINATION ${CMAKE_INSTALL_LIBDIR}/wasmedge) + ``` + +Follow the guide to [build WasmEdge from source](../source/os/linux.md), according to your specific operating system (e.g., Linux), which will include building the plug-in shared library along with WasmEdge. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/develop_plugin_rustsdk.md b/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/develop_plugin_rustsdk.md index 35f27d070..8176ff89b 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/develop_plugin_rustsdk.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/develop_plugin_rustsdk.md @@ -1,49 +1,78 @@ +--- +sidebar_position: 4 +--- + # Develop WasmEdge Plug-in in Rust SDK with witc -Once you complete C++ plugin code, you can use witc[^1] to generate Rust Plugin SDK +By developing a plug-in, one can extend the functionality of WasmEdge and customize it to suit specific needs. WasmEdge provides a Rust-based API for registering extension modules and host functions. -## Example wasmedge_opencvmini +```mermaid +graph TD +A[Build WasmEdge from source] -- witc --> B[Generate Rust Plug-in Code] +B -- SDK Crate --> C[Create SDK Crate] +C -- Module File --> D[Create Module File] +D -- Wrapper Functions --> E[Write Wrapper Functions in src/lib.rs] +``` -Consider you get a file `wasmedge_opencvmini.wit` with below content + +:::note +It is recommended that developers choose the WasmEdge [C API](develop_plugin_c.md) for plug-in development because of the support, compatibility, and flexibility the WasmEdge runtime provides. +::: -```wit -imdecode: func(buf: list) -> u32 -imshow: func(window-name: string, mat-key: u32) -> unit -waitkey: func(delay: u32) -> unit -``` +## Set up the development environment -Using witc can generate Rust plugin code for it +To start developing WasmEdge plug-ins, it is essential to properly set up the development environment. This section provides step-by-step instructions for WasmEdge plug-in development - -```shell -witc plugin wasmedge_opencvmini.wit -``` +- **Build WasmEdge from source**: For developing the WasmEdge plug-in in C++, you must build WasmEdge from source. Follow the[build WasmEdge from source](../source/build_from_src.md) for instructions. Once you complete the C++ plug-in code, you can use witc[^1] to generate Rust Plug-in SDK. -Now, you will create a SDK crate by +After installing WasmEdge, you need to set up the build environment. If you're using Linux or other platforms, you can follow the instructions in the [build environment setup guide](../source/os/linux.md). -```shell -cargo new --lib opencvmini-sdk && cd opencvmini-sdk -``` +## Write the plug-in code -witc put rust code to stdout, therefore, you might like to create a new module file for generated code +To develop a WasmEdge Plug-in in Rust using the witc tool, you can follow these steps: -```shell -witc plugin wasmedge_opencvmini.wit > src/generated.rs -``` +- **Generate Rust Plug-in Code**: Consider you have a file named `wasmedge_opencvmini.wit` with the following content: -Finally, you write down `mod generated` in `src/lib.rs` to access the code, and write some wrappers + ```wit + imdecode: func(buf: list) -> u32 + imshow: func(window-name: string, mat-key: u32) -> unit + waitkey: func(delay: u32) -> unit + ``` -```rust -mod generated; + You can use the witc tool to generate Rust plug-in code for it by running the following command: -pub fn imdecode(buf: &[u8]) -> u32 { - unsafe { generated::imdecode(buf.as_ptr(), buf.len()) } -} -pub fn imshow(window_name: &str, mat_key: u32) -> () { - unsafe { generated::imshow(window_name.as_ptr(), window_name.len(), mat_key) } -} -pub fn waitkey(delay: u32) -> () { - unsafe { generated::waitkey(delay) } -} -``` + ```shell + witc plugin wasmedge_opencvmini.wit + ``` + +- **Create SDK Crate**: You need to create an SDK crate for your plug-in. Run the following command to create a new crate named `opencvmini-sdk`: + + ```shell + cargo new --lib opencvmini-sdk && cd opencvmini-sdk + ``` + +- **Create Module File**: The witc tool puts the Rust code to stdout. To capture the generated code, create a new module file named `src/generated.rs` and run the following command: + + ```shell + witc plugin wasmedge_opencvmini.wit > src/generated.rs + ``` + +- **Write Wrapper Functions**: In the `src/lib.rs` file of your crate, write the following code of `mod generated` to access the generated code and create wrapper functions: + + ```rust + mod generated; + + pub fn imdecode(buf: &[u8]) -> u32 { + unsafe { generated::imdecode(buf.as_ptr(), buf.len()) } + } + pub fn imshow(window_name: &str, mat_key: u32) -> () { + unsafe { generated::imshow(window_name.as_ptr(), window_name.len(), mat_key) } + } + pub fn waitkey(delay: u32) -> () { + unsafe { generated::waitkey(delay) } + } + ``` + + This code imports the generated module and provides safe wrapper functions for each generated function. [^1]: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/intro.md b/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/intro.md index b735b6d2e..67267473f 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/intro.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/contribute/plugin/intro.md @@ -4,23 +4,76 @@ sidebar_position: 1 # WasmEdge Plug-in System Introduction -While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, developers should implement the host functions before compilation. +While the WasmEdge language SDKs allow registering host functions from a host (wrapping) application, developers should implement the host functions before compilation. However, for a more flexible and dynamic extension of the host functions, WasmEdge provides a plug-in architecture to load the plug-in shared library. -For the other solutions, WasmEdge provides the plug-in architecture to load the plug-in shared library for easier extending of the host functions. +A WasmEdge plug-in is a software component that extends the functionality of the WasmEdge runtime. Currently, developers can follow the guides to implement the plug-ins in [C API](develop_plugin_c.md) (recommended), [C++](develop_plugin_cpp.md) and [Rust](develop_plugin_rustsdk.md). With the help of the WasmEdge SDKs in the supported languages, developers can load and register the host functions from the plug-in shared libraries, allowing them to seamlessly integrate the plug-ins into the WasmEdge runtime as if they were part of the core runtime. -With developing the plug-ins, WasmEdge SDKs in the supported languages can load and register the host functions from the plug-in shared libraries. +```mermaid +graph LR + A((Host Application)) -- Loads --> B((Plug-in Shared Library)) + B -- Registers --> C((Wasmedge Runtime)) +``` -In current, developers can follow the guides to implement the plug-ins in [C API (recommended)](develop_plugin_c.md) or [C++](develop_plugin_cpp.md). +## Benefits of Using WasmEdge Plug-in + +WasmEdge plug-ins are designed to extend the functionality of the WasmEdge runtime and can be helpful for developers and end-users in several ways: + +- **Customization:** WasmEdge plug-ins can be customized to suit the specific needs of a project. Developers can create plug-ins that integrate with other systems or tools or provide unique functionality unavailable in the core WasmEdge runtime. + +- **Performance:** WasmEdge plug-ins are designed to work seamlessly with the core runtime, minimizing overhead and maximizing performance, which means they can provide additional functionality without sacrificing performance. + +- **Ease of use:** WasmEdge plug-ins are easy to use and integrate with the WasmEdge runtime. Developers can load the plug-in into the runtime and use its functions as part of the core runtime. + +- **Scalability:** Developers can compile their compute-intensive functions into host functions and package them into a plug-in to provide the better performance as running in native code. + +WasmEdge plug-ins can provide developers and users with a versatile, customizable, high-performance, and secure way to extend the functionality of the WasmEdge runtime. WasmEdge plug-ins can also improve scalability and ease of use, making it easier to build and deploy complex applications on edge devices. ## Loadable Plug-in -Loadable plugin is a standalone `.so`/`.dylib`/`.dll` file that WasmEdge can load during runtime environment, and provide modules to be imported. +Loadable plug-ins are standalone shared libraries (`.so`/`.dylib`/`.dll` files) that the WasmEdge runtime environment can load at runtime. These plug-ins can provide additional functionality to the WasmEdge runtime environment, such as new modules that can be imported by WebAssembly modules. + +### Creating Loadable Plug-in + +To create a loadable plug-in for WasmEdge, developers can use the WasmEdge Plug-in SDK, which provides a set of Rust, C, and C++ APIs for creating and registering plug-ins. The SDK also includes [example code](https://github.com/WasmEdge/WasmEdge/tree/master/examples/plugin/get-string) that demonstrates creating a simple plug-in that returns a string. By following the provided examples and leveraging the SDK's APIs, developers can quickly build custom plug-ins tailored to their specific needs. + +### Loading plug-in from paths + +To use the loadable plug-ins, developers need to load them from specific paths into the WasmEdge runtime environment. The loading process involves the following steps: + +- Loadable plug-ins can be loaded from default paths by calling the `WasmEdge_PluginLoadWithDefaultPaths()` API. The default paths include: + + - The path specified in the environment variable `WASMEDGE_PLUGIN_PATH`. + - The `./plugin/` directory relative to the WasmEdge installation path. + - The `./wasmedge/` directory is located under the library path if WasmEdge is installed in a system directory such as `/usr` and `/usr/local`. + +- If the plug-ins are located in a specific path or directory, developers can use the `WasmEdge_PluginLoadFromPath("PATH_TO_PLUGIN/plug-in.so")` API to load the plug-ins from that particular location. + +The WasmEdge runtime environment will search for the loadable plug-ins in the specified paths and load them if found. + +The following flowchart shows the process of loading loadable plug-ins into the WasmEdge runtime environment from specific paths: + +```mermaid +graph LR + A((Start)) --> B(Loadable Plug-ins) + B --> C{Load Plug-ins} + C --> D[Load from Default Paths] + C --> E[Load from Specific Path] + C --> F[Load from Specific Directory] + D --> G{Is Plug-in Found?} + E --> G + F --> G + G -- Yes --> H(Load Plug-in) + H --> I(End) + G -- No --> I +``` + +The flowchart shows loading loadable plug-ins into the WasmEdge runtime environment. The process involves searching for plug-ins in default paths, a specific path, or a specific directory. If a plug-in is found in any of these locations, it is loaded into the runtime environment. The flowchart enables developers to quickly load plug-ins and extend the capabilities of the WasmEdge runtime. -Please [refer to the plugin example code](https://github.com/WasmEdge/WasmEdge/tree/master/examples/plugin/get-string). +By following this flowchart, developers can effectively load loadable plug-ins into the WasmEdge runtime environment from specific paths, expanding the runtime's functionality according to their requirements. ## 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 source with the 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 | | --- | --- | --- | --- | From 20d85e4d0c11ef48813aba10e788960aa48fc9de Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Mon, 14 Aug 2023 16:20:15 +0600 Subject: [PATCH 20/20] Update docusaurus.config.js Signed-off-by: Mahfuza --- docusaurus.config.js | 49 ++++++++++++++++++++++++-------------------- 1 file changed, 27 insertions(+), 22 deletions(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 035da1cd8..b68fc2b41 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -59,33 +59,29 @@ const config = { ], ], - markdown: { - mermaid: true, - }, - - themes : [ + themes: [ [ "@easyops-cn/docusaurus-search-local", /** @type {import("@easyops-cn/docusaurus-search-local").PluginOptions} */ // @ts-ignore { - docsRouteBasePath: '/', - hashed: true, - indexBlog: false, - indexPages: true, - language: ["en", "zh"], - highlightSearchTermsOnTargetPage: true, - explicitSearchResultPath: true, - searchBarShortcut: true, - searchBarShortcutHint: true, - searchBarPosition: "right", + docsRouteBasePath: '/', + hashed: true, + indexBlog: false, + indexPages: true, + language: ["en", "zh"], + highlightSearchTermsOnTargetPage: true, + explicitSearchResultPath: true, + searchBarShortcut: true, + searchBarShortcutHint: true, + searchBarPosition: "right", }, - ], - ['@docusaurus/theme-mermaid'], ], + ], + themeConfig: - /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ + /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ metadata: [{ name: 'keywords', content: 'wasmedge, wasm, web assembly, rust, cncf, edge devices, cloud, serverless' }, { name: 'twitter:card', content: 'summary' }], image: "./static/img/wasm_logo.png", @@ -136,15 +132,15 @@ const config = { }, docs: { sidebar: { - hideable: true, + hideable: true, }, - }, + }, footer: { logo: { alt: 'WasmEdge logo', src: '/img/wasmedge_logo.svg', href: 'https://wasmedge.org/', - }, + }, style: 'dark', links: [ { @@ -217,4 +213,13 @@ const config = { }), }; -module.exports = config; +// Extending config to inlcude mermaid also +const extendedConfig = { + ...config, + markdown: { + mermaid: true, + }, + themes: ['@docusaurus/theme-mermaid'], +}; + +module.exports = extendedConfig;