Skip to content

Commit a34fc38

Browse files
mhmohonamhmohona
authored
Update plugin section - user guide (#146)
* add plugin user-guide Signed-off-by: Mahfuza <[email protected]> * added guide for Rust Signed-off-by: Mahfuza <[email protected]> * small fix Signed-off-by: Mahfuza <[email protected]> * small fix Signed-off-by: Mahfuza <[email protected]> --------- Signed-off-by: Mahfuza <[email protected]>
1 parent 80f56b8 commit a34fc38

File tree

8 files changed

+696
-0
lines changed

8 files changed

+696
-0
lines changed

‎docs/embed/use-case/plugin/_category_.json

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Plugin-User Guide",
3+
"position": 7,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "We will learn how to use WasmEdge Plugin System."
7+
}
8+
}

‎docs/embed/use-case/plugin/c_sdk.md

+144
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
## Using Plug-ins to Extend the Runtime in C
6+
7+
The WasmEdge plug-ins are the shared libraries to provide the WasmEdge runtime to load and create host module instances. With the plug-ins, the WasmEdge runtime can be extended more easily.
8+
9+
## Loading Plug-ins from Paths
10+
11+
Developers can start using WasmEdge plug-ins by loading them from specific paths. To load plug-ins from the default paths, the following API can be used:
12+
13+
```c
14+
WasmEdge_PluginLoadWithDefaultPaths();
15+
```
16+
17+
Once this API is called, plug-ins from the default paths will be loaded. The default paths include:
18+
19+
- The path specified in the `WASMEDGE_PLUGIN_PATH` environment variable.
20+
- The `../plugin/` directory relative to the WasmEdge installation path.
21+
- The `./wasmedge/` directory under the library path if WasmEdge is installed in a system directory (e.g., `/usr` and `/usr/local`).
22+
23+
Developers can also load plug-ins from specific paths using this API:
24+
25+
```c
26+
WasmEdge_PluginLoadFromPath("PATH_TO_PLUGIN/plugin.so");
27+
```
28+
29+
## Listing Loaded Plug-ins
30+
31+
Once plug-ins are loaded, developers can list the loaded plug-in names using the following approach:
32+
33+
```c
34+
WasmEdge_PluginLoadWithDefaultPaths();
35+
printf("Number of loaded plug-ins: %d\n", WasmEdge_PluginListPluginsLength());
36+
37+
WasmEdge_String Names[20];
38+
uint32_t NumPlugins = WasmEdge_PluginListPlugins(Names, 20);
39+
for (int I = 0; I < NumPlugins; I++) {
40+
printf("Plug-in %d name: %s\n", I, Names[I].Buf);
41+
}
42+
```
43+
44+
## Getting Plug-in Context by Name
45+
46+
Developers can obtain the plug-in context by its name using the following method:
47+
48+
```c
49+
/* Assume that wasi_crypto plug-in is installed in the default plug-in path. */
50+
WasmEdge_PluginLoadWithDefaultPaths();
51+
52+
const char PluginName[] = "wasi_crypto";
53+
WasmEdge_String NameString =
54+
WasmEdge_StringWrap(PluginName, strlen(PluginName));
55+
const WasmEdge_PluginContext *PluginCxt = WasmEdge_PluginFind(NameString);
56+
```
57+
58+
## Creating Module Instances from Plug-ins
59+
60+
With the plug-in context, developers can create module instances by providing the module name:
61+
62+
```c
63+
/* Assume that the `PluginCxt` is the context to the wasi_crypto plug-in. */
64+
65+
/* List the available host modules in the plug-in. */
66+
WasmEdge_String Names[20];
67+
uint32_t ModuleLen = WasmEdge_PluginListModule(PluginCxt, Names, 20);
68+
for (uint32_t I = 0; I < ModuleLen; I++) {
69+
/* Will print the available host module names in the plug-in. */
70+
printf("%s\n", Names[I].Buf);
71+
}
72+
/* Will print here for the WASI-Crypto plug-in here:
73+
* wasi_ephemeral_crypto_asymmetric_common
74+
* wasi_ephemeral_crypto_common
75+
* wasi_ephemeral_crypto_kx
76+
* wasi_ephemeral_crypto_signatures
77+
* wasi_ephemeral_crypto_symmetric
78+
*/
79+
80+
/* Create a module instance from the plug-in by the module name. */
81+
const char ModuleName[] = "wasi_ephemeral_crypto_common";
82+
WasmEdge_String NameString =
83+
WasmEdge_StringWrap(ModuleName, strlen(ModuleName));
84+
WasmEdge_ModuleInstance *ModCxt =
85+
WasmEdge_PluginCreateModule(PluginCxt, NameString);
86+
87+
WasmEdge_ModuleInstanceDelete(ModCxt);
88+
```
89+
90+
There may be several plug-ins in the default plug-in paths if users [installed WasmEdge plug-ins by the installer](/contribute/installer.md#plugins).
91+
92+
Before using the plug-ins, developers should [Loading Plug-ins from Paths](#loading-plug-ins-from-paths).
93+
94+
## Automatic Module Creation and Mocking
95+
96+
Upon creating a `VM` context, the WasmEdge runtime will automatically create and register the modules of loaded plug-ins. In cases where specific plug-ins are not loaded, WasmEdge will provide mock implementations for certain host modules. These mocked modules include:
97+
98+
- `wasi_ephemeral_crypto_asymmetric_common` (for the `WASI-Crypto`)
99+
- `wasi_ephemeral_crypto_common` (for the `WASI-Crypto`)
100+
- `wasi_ephemeral_crypto_kx` (for the `WASI-Crypto`)
101+
- `wasi_ephemeral_crypto_signatures` (for the `WASI-Crypto`)
102+
- `wasi_ephemeral_crypto_symmetric` (for the `WASI-Crypto`)
103+
- `wasi_ephemeral_nn`
104+
- `wasi_snapshot_preview1`
105+
- `wasmedge_httpsreq`
106+
- `wasmedge_process`
107+
108+
## Handling Missing Plug-ins and Error Messages
109+
110+
When the WASM want to invoke these host functions but the corresponding plug-in is not installed, WasmEdge will print the error message and return an error.
111+
112+
```c
113+
/* Load the plug-ins in the default paths first. */
114+
WasmEdge_PluginLoadWithDefaultPaths();
115+
/* Create the configure context and add the WASI configuration. */
116+
WasmEdge_ConfigureContext *ConfCxt = WasmEdge_ConfigureCreate();
117+
WasmEdge_ConfigureAddHostRegistration(ConfCxt,
118+
WasmEdge_HostRegistration_Wasi);
119+
WasmEdge_VMContext *VMCxt = WasmEdge_VMCreate(ConfCxt, NULL);
120+
WasmEdge_ConfigureDelete(ConfCxt);
121+
/* The following API can retrieve the registered modules in the VM context,
122+
* includes the built-in WASI and the plug-ins.
123+
*/
124+
/*
125+
* This API will return `NULL` if the module instance is not found.
126+
*/
127+
WasmEdge_String WasiName =
128+
WasmEdge_StringCreateByCString("wasi_snapshot_preview1");
129+
/* The `WasiModule` will not be `NULL` because the configuration was set. */
130+
const WasmEdge_ModuleInstanceContext *WasiModule =
131+
WasmEdge_VMGetRegisteredModule(VMCxt, WasiName);
132+
WasmEdge_StringDelete(WasiName);
133+
WasmEdge_String WasiNNName =
134+
WasmEdge_StringCreateByCString("wasi_ephemeral_nn");
135+
/* The `WasiNNModule` will not be `NULL` even if the wasi_nn plug-in is not
136+
* installed, because the VM context will mock and register the host
137+
* modules.
138+
*/
139+
const WasmEdge_ModuleInstanceContext *WasiNNModule =
140+
WasmEdge_VMGetRegisteredModule(VMCxt, WasiNNName);
141+
WasmEdge_StringDelete(WasiNNName);
142+
143+
WasmEdge_VMDelete(VMCxt);
144+
```

‎docs/embed/use-case/plugin/go_sdk.md

+118
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
## Using Plug-ins to Extend the Runtime in Go
6+
7+
The WasmEdge plug-ins are the shared libraries to provide the WasmEdge runtime to load and create host module instances. With the plug-ins, the WasmEdge runtime can be extended more easily.
8+
9+
## Loading Plug-ins from Paths
10+
11+
Developers can start using WasmEdge plug-ins by loading them from specific paths. To load plug-ins from the default paths, the following API can be used:
12+
13+
```go
14+
wasmedge.LoadPluginDefaultPaths()
15+
```
16+
17+
Once this API is called, plug-ins from the default paths will be loaded. The default paths include:
18+
19+
- The path specified in the `WASMEDGE_PLUGIN_PATH` environment variable.
20+
- The `../plugin/` directory relative to the WasmEdge installation path.
21+
- The `./wasmedge/` directory under the library path if WasmEdge is installed in a system directory (e.g., `/usr` and `/usr/local`).
22+
23+
Developers can also load plug-ins from specific paths using this API:
24+
25+
```go
26+
wasmedge.LoadPluginFromPath("PATH_TO_PLUGIN/plugin.so")
27+
```
28+
29+
## Listing Loaded Plug-ins
30+
31+
Once plug-ins are loaded, developers can list the loaded plug-in names using the following approach:
32+
33+
```go
34+
wasmedge.LoadPluginDefaultPaths()
35+
pluginnames := wasmedge.ListPlugins()
36+
for _, name := range pluginnames {
37+
fmt.Println("Loaded plug-in name: ", name)
38+
}
39+
```
40+
41+
## Getting Plug-in Context by Name
42+
43+
Developers can obtain the plug-in context by its name using the following method:
44+
45+
```go
46+
// Assume that wasi_crypto plug-in is installed in the default plug-in path.
47+
wasmedge.LoadPluginDefaultPaths()
48+
plugincrypto := wasmedge.FindPlugin("wasi_crypto")
49+
```
50+
51+
## Creating Module Instances from Plug-ins
52+
53+
With the plug-in context, developers can create module instances by providing the module name:
54+
55+
```go
56+
// Assume that the `plugincrypto` is the object to the wasi_crypto plug-in.
57+
58+
// List the available host modules in the plug-in.
59+
modules := plugincrypto.ListModule()
60+
for _, name := range modules {
61+
fmt.Println("Available module: ", name)
62+
}
63+
// Will print here for the WASI-Crypto plug-in here:
64+
// wasi_ephemeral_crypto_asymmetric_common
65+
// wasi_ephemeral_crypto_common
66+
// wasi_ephemeral_crypto_kx
67+
// wasi_ephemeral_crypto_signatures
68+
// wasi_ephemeral_crypto_symmetric
69+
70+
// Create a module instance from the plug-in by the module name.
71+
modinst := plugincrypto.CreateModule("wasi_ephemeral_crypto_common")
72+
73+
modinst.Release()
74+
```
75+
76+
There may be several plug-ins in the default plug-in paths if users [installed WasmEdge plug-ins by the installer](/contribute/installer.md#plugins).
77+
78+
Before using the plug-ins, developers should [Loading Plug-ins from Paths](#loading-plug-ins-from-paths).
79+
80+
## Automatic Module Creation and Mocking
81+
82+
Upon creating a `VM` context, the WasmEdge runtime will automatically create and register the modules of loaded plug-ins. In cases where specific plug-ins are not loaded, WasmEdge will provide mock implementations for certain host modules. These mocked modules include:
83+
84+
- `wasi_ephemeral_crypto_asymmetric_common` (for the `WASI-Crypto`)
85+
- `wasi_ephemeral_crypto_common` (for the `WASI-Crypto`)
86+
- `wasi_ephemeral_crypto_kx` (for the `WASI-Crypto`)
87+
- `wasi_ephemeral_crypto_signatures` (for the `WASI-Crypto`)
88+
- `wasi_ephemeral_crypto_symmetric` (for the `WASI-Crypto`)
89+
- `wasi_ephemeral_nn`
90+
- `wasi_snapshot_preview1`
91+
- `wasmedge_httpsreq`
92+
- `wasmedge_process`
93+
- `wasi:logging/logging` (for the `WASI-Logging`)
94+
95+
## Handling Missing Plug-ins and Error Messages
96+
97+
When the WASM want to invoke these host functions but the corresponding plug-in not installed, WasmEdge will print the error message and return an error.
98+
99+
```go
100+
// Load the plug-ins in the default paths first.
101+
wasmedge.LoadPluginDefaultPaths()
102+
103+
// Create the VM object with the WASI configuration.
104+
conf := wasmedge.NewConfigure(wasmedge.WASI)
105+
vm := wasmedge.NewVMWithConfig(conf)
106+
conf.Release()
107+
108+
// The following API can retrieve the registered modules in the VM objects, includes the built-in WASI and the plug-ins.
109+
// This API will return `NULL` if the module instance not found.
110+
111+
// The `wasimodule` will not be `nil` because the configuration was set.
112+
wasimodule := vm.GetRegisteredModule("wasi_snapshot_preview1")
113+
114+
// The `wasinnmodule` will not be `nil` even if the wasi_nn plug-in is not installed, because the VM context will mock and register the host modules.
115+
wasinnmodule := vm.GetRegisteredModule("wasi_ephemeral_nn")
116+
117+
vm.Release()
118+
```

‎docs/embed/use-case/plugin/rust_sdk.md

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
## Using Plug-ins to Extend the Runtime in Rust
6+
7+
The WasmEdge plug-ins are the shared libraries to provide the WasmEdge runtime to load and create host module instances. With the plug-ins, the WasmEdge runtime can be extended more easily.
8+
9+
## Loading Plug-ins from Paths
10+
11+
Developers can start using WasmEdge plug-ins by loading them from specific paths. To load plug-ins from the default paths, the following API can be used:
12+
13+
```rust
14+
impl PluginManager
15+
pub fn load(path: Option<&Path>) -> WasmEdgeResult<()>
16+
```
17+
18+
- The default plug-in paths will be used if the path is not given.
19+
20+
- The path specified in the `WASMEDGE_PLUGIN_PATH` environment variable.
21+
- The `../plugin/` directory relative to the WasmEdge installation path.
22+
- The `./wasmedge/` directory under the library path if WasmEdge is installed in the `/usr` directory.
23+
24+
- If the path is given, then
25+
26+
- If the path is pointing at a file, then it indicates that a single plug-in will be loaded from the file.
27+
- If the path is pointing at a directory, then the method will load plug-ins from the files.
28+
29+
To get the names of all loaded plug-ins as returns -
30+
31+
```rust
32+
pub fn names() -> Vec<String>
33+
```
34+
35+
<!-- prettier-ignore -->
36+
:::note
37+
`path` - A path to a plug-in file or a directory holding plug-in files. If `None`, then the default plug-in path will be used.
38+
:::
39+
40+
## Listing Loaded Plug-ins
41+
42+
Once plug-ins are loaded, developers can list the loaded plug-in names using the following approach:
43+
44+
```rust
45+
pub fn names() -> Vec<String>
46+
```
47+
48+
## Getting Plug-in Context by Name
49+
50+
Developers can get the plug-in context by its name using the following method:
51+
52+
```rust
53+
pub fn find(name: impl AsRef<str>) -> Option<Plugin>
54+
```
55+
56+
Here `name` is the name of the target plug-in.
57+
58+
## Getting Module Instances from Plug-ins
59+
60+
With the plug-in context, developers can get module instances by providing the module name:
61+
62+
```rust
63+
pub fn mod_names(&self) -> Vec<String>
64+
```
65+
66+
There may be several plug-ins in the default plug-in paths if users [installed WasmEdge plug-ins by the installer](/contribute/installer.md#plugins).
67+
68+
Before using the plug-ins, developers should [Loading Plug-ins from Paths](#loading-plug-ins-from-paths).
69+
70+
## Plug-in Module Instance
71+
72+
To initialize the `wasmedge_process` plug-in module instance with the parameters -
73+
74+
```rust
75+
pub fn init_wasmedge_process(allowed_cmds: Option<Vec<&str>>, allowed: bool)
76+
```
77+
78+
Here, `allowed_cmds` is A white list of commands and `allowed` determines if wasmedge_process is allowed to execute all commands on the white list.

‎i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/_category_.json

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Plugin-User Guide",
3+
"position": 7,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "We will learn how to use WasmEdge Plugin System."
7+
}
8+
}

0 commit comments

Comments
 (0)