You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
7
+
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 -
8
+
9
+
```mermaid
10
+
graph LR;
11
+
A[Developing WasmEdge Plug-in in C]
12
+
A --> B(Set up the development environment)
13
+
A --> C(Create a WasmEdge plug-in project)
14
+
A --> D(Write the plug-in code)
15
+
A --> E(Build the plug-in)
16
+
A --> F(Test and debug the plug-in)
17
+
B --> E
18
+
C --> D
19
+
D --> E
20
+
```
21
+
22
+
This flowchart illustrates developing a WasmEdge plug-in, showcasing the steps from choosing a programming language to finalizing and releasing the plug-in.
23
+
24
+
## Set up the development environment
25
+
26
+
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 -
27
+
28
+
**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.
8
29
9
-
## Prerequisites
30
+
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).
10
31
11
-
For developing the WasmEdge plug-in in C API, please [install WasmEdge](../../start/install.md#install) first.
32
+
## Create a WasmEdge plug-in project
12
33
13
-
## Example
34
+
To create a WasmEdge plug-in project, follow these steps:
14
35
15
-
Assume that the plug-in example is in the file `testplugin.c`.
36
+
-**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:
16
37
17
-
### Host Functions
38
+
```bash
39
+
mkdir testplugin
40
+
cd testplugin
41
+
mkdir src include build
42
+
```
18
43
19
-
The goal of the plug-in is to provide the host functions which can be imported when instantiating WASM.
44
+
-**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.
20
45
21
-
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).
46
+
-**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.
47
+
48
+
## Write the plug-in code
49
+
50
+
To create a plug-in with host functions and modules, follow these steps:
51
+
52
+
-**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.
53
+
54
+
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).
22
55
23
56
<!-- prettier-ignore -->
24
57
:::note
25
-
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.
58
+
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.
26
59
:::
27
60
61
+
Here's an example of two host functions, `HostFuncAdd` and `HostFuncSub`, that add and subtract two `int32_t` numbers, respectively:
- **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.
55
90
56
-
Then developers should implement the module creation functions.
91
+
Here's an example of a module creation function named `CreateTestModule`:
57
92
58
-
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.
59
-
60
-
```c
61
-
/* The creation function of creating the module instance. */
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.
142
+
143
+
-**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.
144
+
145
+
Here's an example of the plug-in and module descriptors:
146
+
147
+
```c
148
+
/* The module descriptor array. There can be multiple modules in a plug-in. */
* Module name. This is the name for searching and creating the module
152
+
* instance context by the `WasmEdge_PluginCreateModule()` API.
153
+
*/
154
+
.Name = "wasmedge_plugintest_c_module",
155
+
/* Module description. */
156
+
.Description = "This is for the plugin tests in WasmEdge C API.",
157
+
/* Creation function pointer. */
158
+
.Create = CreateTestModule,
159
+
}};
160
+
161
+
/* The plug-in descriptor */
162
+
static WasmEdge_PluginDescriptor Desc[] = {{
163
+
/*
164
+
* Plug-in name. This is the name for searching the plug-in context by the
165
+
* `WasmEdge_PluginFind()` API.
166
+
*/
167
+
.Name = "wasmedge_plugintest_c",
168
+
/* Plug-in description. */
169
+
.Description = "",
170
+
/* Plug-in API version. */
171
+
.APIVersion = WasmEdge_Plugin_CurrentAPIVersion,
172
+
/* Plug-in version. Developers can define the version of this plug-in. */
173
+
.Version =
174
+
{
175
+
.Major = 0,
176
+
.Minor = 1,
177
+
.Patch = 0,
178
+
.Build = 0,
179
+
},
180
+
/* Module count in this plug-in. */
181
+
.ModuleCount = 1,
182
+
/* Plug-in option description count in this plug-in (Work in progress). */
183
+
.ProgramOptionCount = 0,
184
+
/* Pointer to the module description array. */
185
+
.ModuleDescriptions = ModuleDesc,
186
+
/* Pointer to the plug-in option description array (Work in progress). */
187
+
.ProgramOptions = NULL,
188
+
}};
189
+
```
190
+
191
+
These descriptions define the name, description, version, and creation function of the plug-in and the name and description of the module it contains.
192
+
193
+
Remember to implement any additional functions or structures your plug-in requires to fulfill its functionality.
194
+
195
+
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.
196
+
197
+
- **Plug-in option** - _WORK IN PROGRESS. This section is reserved for the feature in the future._
198
+
199
+
## Build your plug-in
200
+
201
+
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:
202
+
203
+
- **Build with Command**: if you choose to build the plug-in using the command line, run the following command in the terminal:
204
+
205
+
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.
206
+
207
+
- **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:
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.
231
+
232
+
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)`.
0 commit comments