From 7730f0970b801c0c84a6c8a4b005e86e04a5db9d Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Mon, 14 Aug 2023 12:42:40 +0600 Subject: [PATCH 1/4] add plugin user-guide Signed-off-by: Mahfuza --- docs/embed/use-case/plugin/_category_.json | 8 ++ docs/embed/use-case/plugin/c_sdk.md | 147 +++++++++++++++++++++ docs/embed/use-case/plugin/go_sdk.md | 119 +++++++++++++++++ docs/embed/use-case/plugin/rust_sdk.md | 3 + 4 files changed, 277 insertions(+) create mode 100644 docs/embed/use-case/plugin/_category_.json create mode 100644 docs/embed/use-case/plugin/c_sdk.md create mode 100644 docs/embed/use-case/plugin/go_sdk.md create mode 100644 docs/embed/use-case/plugin/rust_sdk.md diff --git a/docs/embed/use-case/plugin/_category_.json b/docs/embed/use-case/plugin/_category_.json new file mode 100644 index 00000000..c7c01dcc --- /dev/null +++ b/docs/embed/use-case/plugin/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Plugin-User Guide", + "position": 7, + "link": { + "type": "generated-index", + "description": "We will learn how to use WasmEdge Plugin System." + } +} diff --git a/docs/embed/use-case/plugin/c_sdk.md b/docs/embed/use-case/plugin/c_sdk.md new file mode 100644 index 00000000..21a34611 --- /dev/null +++ b/docs/embed/use-case/plugin/c_sdk.md @@ -0,0 +1,147 @@ +--- +sidebar_position: 1 +--- + +## Using Plug-ins to Extend the Runtime in C + +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. + +## Loading Plug-ins from Paths + +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: + +```c +WasmEdge_PluginLoadWithDefaultPaths(); +``` + +Once this API is called, plug-ins from the default paths will be loaded. The default paths include: + +- The path specified in the `WASMEDGE_PLUGIN_PATH` environment variable. +- The `../plugin/` directory relative to the WasmEdge installation path. +- The `./wasmedge/` directory under the library path if WasmEdge is installed in a system directory (e.g., `/usr` and `/usr/local`). + +Developers can also load plug-ins from specific paths using this API: + +```c +WasmEdge_PluginLoadFromPath("PATH_TO_PLUGIN/plugin.so"); +``` + +## Listing Loaded Plug-ins + +Once plug-ins are loaded, developers can list the loaded plug-in names using the following approach: + +```c +WasmEdge_PluginLoadWithDefaultPaths(); +printf("Number of loaded plug-ins: %d\n", WasmEdge_PluginListPluginsLength()); + +WasmEdge_String Names[20]; +uint32_t NumPlugins = WasmEdge_PluginListPlugins(Names, 20); +for (int I = 0; I < NumPlugins; I++) { + printf("Plug-in %d name: %s\n", I, Names[I].Buf); +} +``` + +## Retrieving Plug-in Context by Name + +Developers can obtain the plug-in context by its name using the following method: + +```c +/* Assume that wasi_crypto plug-in is installed in the default plug-in path. */ +WasmEdge_PluginLoadWithDefaultPaths(); + +const char PluginName[] = "wasi_crypto"; +WasmEdge_String NameString = + WasmEdge_StringWrap(PluginName, strlen(PluginName)); +const WasmEdge_PluginContext *PluginCxt = WasmEdge_PluginFind(NameString); +``` + +## Creating Module Instances from Plug-ins + +With the plug-in context, developers can create module instances by providing the module name: + +```c +/* Assume that the `PluginCxt` is the context to the wasi_crypto plug-in. */ + +/* List the available host modules in the plug-in. */ +WasmEdge_String Names[20]; +uint32_t ModuleLen = WasmEdge_PluginListModule(PluginCxt, Names, 20); +for (uint32_t I = 0; I < ModuleLen; I++) { + /* Will print the available host module names in the plug-in. */ + printf("%s\n", Names[I].Buf); +} +/* + * Will print here for the WASI-Crypto plug-in here: + * wasi_ephemeral_crypto_asymmetric_common + * wasi_ephemeral_crypto_common + * wasi_ephemeral_crypto_kx + * wasi_ephemeral_crypto_signatures + * wasi_ephemeral_crypto_symmetric + */ + +/* Create a module instance from the plug-in by the module name. */ +const char ModuleName[] = "wasi_ephemeral_crypto_common"; +WasmEdge_String NameString = + WasmEdge_StringWrap(ModuleName, strlen(ModuleName)); +WasmEdge_ModuleInstance *ModCxt = + WasmEdge_PluginCreateModule(PluginCxt, NameString); + +WasmEdge_ModuleInstanceDelete(ModCxt); +``` + +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). + +Before using the plug-ins, developers should [Loading Plug-ins from Paths](#loading-plug-ins-from-paths). + +## Automatic Module Creation and Mocking + +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: + + - `wasi_ephemeral_crypto_asymmetric_common` (for the `WASI-Crypto`) + - `wasi_ephemeral_crypto_common` (for the `WASI-Crypto`) + - `wasi_ephemeral_crypto_kx` (for the `WASI-Crypto`) + - `wasi_ephemeral_crypto_signatures` (for the `WASI-Crypto`) + - `wasi_ephemeral_crypto_symmetric` (for the `WASI-Crypto`) + - `wasi_ephemeral_nn` + - `wasi_snapshot_preview1` + - `wasmedge_httpsreq` + - `wasmedge_process` + +## Handling Missing Plug-ins and Error Messages + +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. + +```c +/* Load the plug-ins in the default paths first. */ +WasmEdge_PluginLoadWithDefaultPaths(); +/* Create the configure context and add the WASI configuration. */ +WasmEdge_ConfigureContext *ConfCxt = WasmEdge_ConfigureCreate(); +WasmEdge_ConfigureAddHostRegistration(ConfCxt, + WasmEdge_HostRegistration_Wasi); +WasmEdge_VMContext *VMCxt = WasmEdge_VMCreate(ConfCxt, NULL); +WasmEdge_ConfigureDelete(ConfCxt); +/* +* The following API can retrieve the registered modules in the VM context, +* includes the built-in WASI and the plug-ins. +*/ +/* +* This API will return `NULL` if the module instance not found. +*/ +WasmEdge_String WasiName = + WasmEdge_StringCreateByCString("wasi_snapshot_preview1"); +/* The `WasiModule` will not be `NULL` because the configuration was set. */ +const WasmEdge_ModuleInstanceContext *WasiModule = + WasmEdge_VMGetRegisteredModule(VMCxt, WasiName); +WasmEdge_StringDelete(WasiName); +WasmEdge_String WasiNNName = + WasmEdge_StringCreateByCString("wasi_ephemeral_nn"); +/* +* The `WasiNNModule` will not be `NULL` even if the wasi_nn plug-in is not +* installed, because the VM context will mock and register the host +* modules. +*/ +const WasmEdge_ModuleInstanceContext *WasiNNModule = + WasmEdge_VMGetRegisteredModule(VMCxt, WasiNNName); +WasmEdge_StringDelete(WasiNNName); + +WasmEdge_VMDelete(VMCxt); +``` diff --git a/docs/embed/use-case/plugin/go_sdk.md b/docs/embed/use-case/plugin/go_sdk.md new file mode 100644 index 00000000..240da42d --- /dev/null +++ b/docs/embed/use-case/plugin/go_sdk.md @@ -0,0 +1,119 @@ +--- +sidebar_position: 3 +--- + + +## Using Plug-ins to Extend the Runtime in C + +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. + +## Loading Plug-ins from Paths + +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: + +```go +wasmedge.LoadPluginDefaultPaths() +``` + +Once this API is called, plug-ins from the default paths will be loaded. The default paths include: + +- The path specified in the `WASMEDGE_PLUGIN_PATH` environment variable. +- The `../plugin/` directory relative to the WasmEdge installation path. +- The `./wasmedge/` directory under the library path if WasmEdge is installed in a system directory (e.g., `/usr` and `/usr/local`). + +Developers can also load plug-ins from specific paths using this API: + +```go +wasmedge.LoadPluginFromPath("PATH_TO_PLUGIN/plugin.so") +``` + +## Listing Loaded Plug-ins + +Once plug-ins are loaded, developers can list the loaded plug-in names using the following approach: + +```go +wasmedge.LoadPluginDefaultPaths() +pluginnames := wasmedge.ListPlugins() +for _, name := range pluginnames { + fmt.Println("Loaded plug-in name: ", name) +} +``` + +## Retrieving Plug-in Context by Name + +Developers can obtain the plug-in context by its name using the following method: + +```go +// Assume that wasi_crypto plug-in is installed in the default plug-in path. +wasmedge.LoadPluginDefaultPaths() +plugincrypto := wasmedge.FindPlugin("wasi_crypto") +``` + +## Creating Module Instances from Plug-ins + +With the plug-in context, developers can create module instances by providing the module name: + +```go +// Assume that the `plugincrypto` is the object to the wasi_crypto plug-in. + +// List the available host modules in the plug-in. +modules := plugincrypto.ListModule() +for _, name := range modules { + fmt.Println("Available module: ", name) +} +// Will print here for the WASI-Crypto plug-in here: +// wasi_ephemeral_crypto_asymmetric_common +// wasi_ephemeral_crypto_common +// wasi_ephemeral_crypto_kx +// wasi_ephemeral_crypto_signatures +// wasi_ephemeral_crypto_symmetric + +// Create a module instance from the plug-in by the module name. +modinst := plugincrypto.CreateModule("wasi_ephemeral_crypto_common") + +modinst.Release() +``` + +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). + +Before using the plug-ins, developers should [Loading Plug-ins from Paths](#loading-plug-ins-from-paths). + +## Automatic Module Creation and Mocking + +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: + + - `wasi_ephemeral_crypto_asymmetric_common` (for the `WASI-Crypto`) + - `wasi_ephemeral_crypto_common` (for the `WASI-Crypto`) + - `wasi_ephemeral_crypto_kx` (for the `WASI-Crypto`) + - `wasi_ephemeral_crypto_signatures` (for the `WASI-Crypto`) + - `wasi_ephemeral_crypto_symmetric` (for the `WASI-Crypto`) + - `wasi_ephemeral_nn` + - `wasi_snapshot_preview1` + - `wasmedge_httpsreq` + - `wasmedge_process` + - `wasi:logging/logging` (for the `WASI-Logging`) + +## Handling Missing Plug-ins and Error Messages + +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. + +```go +// Load the plug-ins in the default paths first. +wasmedge.LoadPluginDefaultPaths() + +// Create the VM object with the WASI configuration. +conf := wasmedge.NewConfigure(wasmedge.WASI) +vm := wasmedge.NewVMWithConfig(conf) +conf.Release() + +// The following API can retrieve the registered modules in the VM objects, includes the built-in WASI and the plug-ins. +// This API will return `NULL` if the module instance not found. + +// The `wasimodule` will not be `nil` because the configuration was set. +wasimodule := vm.GetRegisteredModule("wasi_snapshot_preview1") + +// 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. +wasinnmodule := vm.GetRegisteredModule("wasi_ephemeral_nn") + +vm.Release() +``` diff --git a/docs/embed/use-case/plugin/rust_sdk.md b/docs/embed/use-case/plugin/rust_sdk.md new file mode 100644 index 00000000..718a6037 --- /dev/null +++ b/docs/embed/use-case/plugin/rust_sdk.md @@ -0,0 +1,3 @@ +--- +sidebar_position: 2 +--- From a62557a5496985c078a1752495cdff47fda408c9 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Wed, 16 Aug 2023 16:40:24 +0600 Subject: [PATCH 2/4] added guide for Rust Signed-off-by: Mahfuza --- docs/embed/use-case/plugin/c_sdk.md | 26 ++-- docs/embed/use-case/plugin/go_sdk.md | 27 ++-- docs/embed/use-case/plugin/rust_sdk.md | 75 +++++++++ .../embed/use-case/plugin/_category_.json | 8 + .../current/embed/use-case/plugin/c_sdk.md | 147 ++++++++++++++++++ .../current/embed/use-case/plugin/go_sdk.md | 118 ++++++++++++++ .../current/embed/use-case/plugin/rust_sdk.md | 78 ++++++++++ 7 files changed, 452 insertions(+), 27 deletions(-) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/_category_.json create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/c_sdk.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/go_sdk.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/rust_sdk.md diff --git a/docs/embed/use-case/plugin/c_sdk.md b/docs/embed/use-case/plugin/c_sdk.md index 21a34611..a47fefb9 100644 --- a/docs/embed/use-case/plugin/c_sdk.md +++ b/docs/embed/use-case/plugin/c_sdk.md @@ -19,7 +19,7 @@ Once this API is called, plug-ins from the default paths will be loaded. The def - The path specified in the `WASMEDGE_PLUGIN_PATH` environment variable. - The `../plugin/` directory relative to the WasmEdge installation path. - The `./wasmedge/` directory under the library path if WasmEdge is installed in a system directory (e.g., `/usr` and `/usr/local`). - + Developers can also load plug-ins from specific paths using this API: ```c @@ -41,7 +41,7 @@ for (int I = 0; I < NumPlugins; I++) { } ``` -## Retrieving Plug-in Context by Name +## Getting Plug-in Context by Name Developers can obtain the plug-in context by its name using the following method: @@ -96,19 +96,19 @@ Before using the plug-ins, developers should [Loading Plug-ins from Paths](#load 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: - - `wasi_ephemeral_crypto_asymmetric_common` (for the `WASI-Crypto`) - - `wasi_ephemeral_crypto_common` (for the `WASI-Crypto`) - - `wasi_ephemeral_crypto_kx` (for the `WASI-Crypto`) - - `wasi_ephemeral_crypto_signatures` (for the `WASI-Crypto`) - - `wasi_ephemeral_crypto_symmetric` (for the `WASI-Crypto`) - - `wasi_ephemeral_nn` - - `wasi_snapshot_preview1` - - `wasmedge_httpsreq` - - `wasmedge_process` +- `wasi_ephemeral_crypto_asymmetric_common` (for the `WASI-Crypto`) +- `wasi_ephemeral_crypto_common` (for the `WASI-Crypto`) +- `wasi_ephemeral_crypto_kx` (for the `WASI-Crypto`) +- `wasi_ephemeral_crypto_signatures` (for the `WASI-Crypto`) +- `wasi_ephemeral_crypto_symmetric` (for the `WASI-Crypto`) +- `wasi_ephemeral_nn` +- `wasi_snapshot_preview1` +- `wasmedge_httpsreq` +- `wasmedge_process` ## Handling Missing Plug-ins and Error Messages -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. +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. ```c /* Load the plug-ins in the default paths first. */ @@ -124,7 +124,7 @@ WasmEdge_ConfigureDelete(ConfCxt); * includes the built-in WASI and the plug-ins. */ /* -* This API will return `NULL` if the module instance not found. +* This API will return `NULL` if the module instance is not found. */ WasmEdge_String WasiName = WasmEdge_StringCreateByCString("wasi_snapshot_preview1"); diff --git a/docs/embed/use-case/plugin/go_sdk.md b/docs/embed/use-case/plugin/go_sdk.md index 240da42d..62ce3924 100644 --- a/docs/embed/use-case/plugin/go_sdk.md +++ b/docs/embed/use-case/plugin/go_sdk.md @@ -2,7 +2,6 @@ sidebar_position: 3 --- - ## Using Plug-ins to Extend the Runtime in C 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. @@ -20,7 +19,7 @@ Once this API is called, plug-ins from the default paths will be loaded. The def - The path specified in the `WASMEDGE_PLUGIN_PATH` environment variable. - The `../plugin/` directory relative to the WasmEdge installation path. - The `./wasmedge/` directory under the library path if WasmEdge is installed in a system directory (e.g., `/usr` and `/usr/local`). - + Developers can also load plug-ins from specific paths using this API: ```go @@ -39,7 +38,7 @@ for _, name := range pluginnames { } ``` -## Retrieving Plug-in Context by Name +## Getting Plug-in Context by Name Developers can obtain the plug-in context by its name using the following method: @@ -82,17 +81,17 @@ Before using the plug-ins, developers should [Loading Plug-ins from Paths](#load 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: - - `wasi_ephemeral_crypto_asymmetric_common` (for the `WASI-Crypto`) - - `wasi_ephemeral_crypto_common` (for the `WASI-Crypto`) - - `wasi_ephemeral_crypto_kx` (for the `WASI-Crypto`) - - `wasi_ephemeral_crypto_signatures` (for the `WASI-Crypto`) - - `wasi_ephemeral_crypto_symmetric` (for the `WASI-Crypto`) - - `wasi_ephemeral_nn` - - `wasi_snapshot_preview1` - - `wasmedge_httpsreq` - - `wasmedge_process` - - `wasi:logging/logging` (for the `WASI-Logging`) - +- `wasi_ephemeral_crypto_asymmetric_common` (for the `WASI-Crypto`) +- `wasi_ephemeral_crypto_common` (for the `WASI-Crypto`) +- `wasi_ephemeral_crypto_kx` (for the `WASI-Crypto`) +- `wasi_ephemeral_crypto_signatures` (for the `WASI-Crypto`) +- `wasi_ephemeral_crypto_symmetric` (for the `WASI-Crypto`) +- `wasi_ephemeral_nn` +- `wasi_snapshot_preview1` +- `wasmedge_httpsreq` +- `wasmedge_process` +- `wasi:logging/logging` (for the `WASI-Logging`) + ## Handling Missing Plug-ins and Error Messages 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. diff --git a/docs/embed/use-case/plugin/rust_sdk.md b/docs/embed/use-case/plugin/rust_sdk.md index 718a6037..a74a42d7 100644 --- a/docs/embed/use-case/plugin/rust_sdk.md +++ b/docs/embed/use-case/plugin/rust_sdk.md @@ -1,3 +1,78 @@ --- sidebar_position: 2 --- + +## Using Plug-ins to Extend the Runtime in C + +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. + +## Loading Plug-ins from Paths + +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: + +```toml +impl PluginManager +pub fn load(path: Option<&Path>) -> WasmEdgeResult<()> +``` + +- The default plug-in paths will be used if the path is not given. + + - The path specified in the `WASMEDGE_PLUGIN_PATH` environment variable. + - The `../plugin/` directory relative to the WasmEdge installation path. + - The `./wasmedge/` directory under the library path if WasmEdge is installed in the `/usr` directory. + +- If the path is given, then + + - If the path is pointing at a file, then it indicates that a single plug-in will be loaded from the file. + - If the path is pointing at a directory, then the method will load plug-ins from the files. + +To get the names of all loaded plug-ins as returns - + +```toml +pub fn names() -> Vec +``` + + +:::note +`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. +::: + +## Listing Loaded Plug-ins + +Once plug-ins are loaded, developers can list the loaded plug-in names using the following approach: + +```toml +pub fn names() -> Vec +``` + +## Getting Plug-in Context by Name + +Developers can get the plug-in context by its name using the following method: + +```toml +pub fn find(name: impl AsRef) -> Option +``` + +Here `name` is the name of the target plug-in. + +## Getting Module Instances from Plug-ins + +With the plug-in context, developers can get module instances by providing the module name: + +```toml +pub fn mod_names(&self) -> Vec +``` + +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). + +Before using the plug-ins, developers should [Loading Plug-ins from Paths](#loading-plug-ins-from-paths). + +## Plug-in Module Instance + +To initialize the `wasmedge_process` plug-in module instance with the parameters - + +```toml +pub fn init_wasmedge_process(allowed_cmds: Option>, allowed: bool) +``` + +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. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/_category_.json b/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/_category_.json new file mode 100644 index 00000000..c7c01dcc --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Plugin-User Guide", + "position": 7, + "link": { + "type": "generated-index", + "description": "We will learn how to use WasmEdge Plugin System." + } +} diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/c_sdk.md b/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/c_sdk.md new file mode 100644 index 00000000..a47fefb9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/c_sdk.md @@ -0,0 +1,147 @@ +--- +sidebar_position: 1 +--- + +## Using Plug-ins to Extend the Runtime in C + +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. + +## Loading Plug-ins from Paths + +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: + +```c +WasmEdge_PluginLoadWithDefaultPaths(); +``` + +Once this API is called, plug-ins from the default paths will be loaded. The default paths include: + +- The path specified in the `WASMEDGE_PLUGIN_PATH` environment variable. +- The `../plugin/` directory relative to the WasmEdge installation path. +- The `./wasmedge/` directory under the library path if WasmEdge is installed in a system directory (e.g., `/usr` and `/usr/local`). + +Developers can also load plug-ins from specific paths using this API: + +```c +WasmEdge_PluginLoadFromPath("PATH_TO_PLUGIN/plugin.so"); +``` + +## Listing Loaded Plug-ins + +Once plug-ins are loaded, developers can list the loaded plug-in names using the following approach: + +```c +WasmEdge_PluginLoadWithDefaultPaths(); +printf("Number of loaded plug-ins: %d\n", WasmEdge_PluginListPluginsLength()); + +WasmEdge_String Names[20]; +uint32_t NumPlugins = WasmEdge_PluginListPlugins(Names, 20); +for (int I = 0; I < NumPlugins; I++) { + printf("Plug-in %d name: %s\n", I, Names[I].Buf); +} +``` + +## Getting Plug-in Context by Name + +Developers can obtain the plug-in context by its name using the following method: + +```c +/* Assume that wasi_crypto plug-in is installed in the default plug-in path. */ +WasmEdge_PluginLoadWithDefaultPaths(); + +const char PluginName[] = "wasi_crypto"; +WasmEdge_String NameString = + WasmEdge_StringWrap(PluginName, strlen(PluginName)); +const WasmEdge_PluginContext *PluginCxt = WasmEdge_PluginFind(NameString); +``` + +## Creating Module Instances from Plug-ins + +With the plug-in context, developers can create module instances by providing the module name: + +```c +/* Assume that the `PluginCxt` is the context to the wasi_crypto plug-in. */ + +/* List the available host modules in the plug-in. */ +WasmEdge_String Names[20]; +uint32_t ModuleLen = WasmEdge_PluginListModule(PluginCxt, Names, 20); +for (uint32_t I = 0; I < ModuleLen; I++) { + /* Will print the available host module names in the plug-in. */ + printf("%s\n", Names[I].Buf); +} +/* + * Will print here for the WASI-Crypto plug-in here: + * wasi_ephemeral_crypto_asymmetric_common + * wasi_ephemeral_crypto_common + * wasi_ephemeral_crypto_kx + * wasi_ephemeral_crypto_signatures + * wasi_ephemeral_crypto_symmetric + */ + +/* Create a module instance from the plug-in by the module name. */ +const char ModuleName[] = "wasi_ephemeral_crypto_common"; +WasmEdge_String NameString = + WasmEdge_StringWrap(ModuleName, strlen(ModuleName)); +WasmEdge_ModuleInstance *ModCxt = + WasmEdge_PluginCreateModule(PluginCxt, NameString); + +WasmEdge_ModuleInstanceDelete(ModCxt); +``` + +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). + +Before using the plug-ins, developers should [Loading Plug-ins from Paths](#loading-plug-ins-from-paths). + +## Automatic Module Creation and Mocking + +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: + +- `wasi_ephemeral_crypto_asymmetric_common` (for the `WASI-Crypto`) +- `wasi_ephemeral_crypto_common` (for the `WASI-Crypto`) +- `wasi_ephemeral_crypto_kx` (for the `WASI-Crypto`) +- `wasi_ephemeral_crypto_signatures` (for the `WASI-Crypto`) +- `wasi_ephemeral_crypto_symmetric` (for the `WASI-Crypto`) +- `wasi_ephemeral_nn` +- `wasi_snapshot_preview1` +- `wasmedge_httpsreq` +- `wasmedge_process` + +## Handling Missing Plug-ins and Error Messages + +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. + +```c +/* Load the plug-ins in the default paths first. */ +WasmEdge_PluginLoadWithDefaultPaths(); +/* Create the configure context and add the WASI configuration. */ +WasmEdge_ConfigureContext *ConfCxt = WasmEdge_ConfigureCreate(); +WasmEdge_ConfigureAddHostRegistration(ConfCxt, + WasmEdge_HostRegistration_Wasi); +WasmEdge_VMContext *VMCxt = WasmEdge_VMCreate(ConfCxt, NULL); +WasmEdge_ConfigureDelete(ConfCxt); +/* +* The following API can retrieve the registered modules in the VM context, +* includes the built-in WASI and the plug-ins. +*/ +/* +* This API will return `NULL` if the module instance is not found. +*/ +WasmEdge_String WasiName = + WasmEdge_StringCreateByCString("wasi_snapshot_preview1"); +/* The `WasiModule` will not be `NULL` because the configuration was set. */ +const WasmEdge_ModuleInstanceContext *WasiModule = + WasmEdge_VMGetRegisteredModule(VMCxt, WasiName); +WasmEdge_StringDelete(WasiName); +WasmEdge_String WasiNNName = + WasmEdge_StringCreateByCString("wasi_ephemeral_nn"); +/* +* The `WasiNNModule` will not be `NULL` even if the wasi_nn plug-in is not +* installed, because the VM context will mock and register the host +* modules. +*/ +const WasmEdge_ModuleInstanceContext *WasiNNModule = + WasmEdge_VMGetRegisteredModule(VMCxt, WasiNNName); +WasmEdge_StringDelete(WasiNNName); + +WasmEdge_VMDelete(VMCxt); +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/go_sdk.md b/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/go_sdk.md new file mode 100644 index 00000000..62ce3924 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/go_sdk.md @@ -0,0 +1,118 @@ +--- +sidebar_position: 3 +--- + +## Using Plug-ins to Extend the Runtime in C + +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. + +## Loading Plug-ins from Paths + +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: + +```go +wasmedge.LoadPluginDefaultPaths() +``` + +Once this API is called, plug-ins from the default paths will be loaded. The default paths include: + +- The path specified in the `WASMEDGE_PLUGIN_PATH` environment variable. +- The `../plugin/` directory relative to the WasmEdge installation path. +- The `./wasmedge/` directory under the library path if WasmEdge is installed in a system directory (e.g., `/usr` and `/usr/local`). + +Developers can also load plug-ins from specific paths using this API: + +```go +wasmedge.LoadPluginFromPath("PATH_TO_PLUGIN/plugin.so") +``` + +## Listing Loaded Plug-ins + +Once plug-ins are loaded, developers can list the loaded plug-in names using the following approach: + +```go +wasmedge.LoadPluginDefaultPaths() +pluginnames := wasmedge.ListPlugins() +for _, name := range pluginnames { + fmt.Println("Loaded plug-in name: ", name) +} +``` + +## Getting Plug-in Context by Name + +Developers can obtain the plug-in context by its name using the following method: + +```go +// Assume that wasi_crypto plug-in is installed in the default plug-in path. +wasmedge.LoadPluginDefaultPaths() +plugincrypto := wasmedge.FindPlugin("wasi_crypto") +``` + +## Creating Module Instances from Plug-ins + +With the plug-in context, developers can create module instances by providing the module name: + +```go +// Assume that the `plugincrypto` is the object to the wasi_crypto plug-in. + +// List the available host modules in the plug-in. +modules := plugincrypto.ListModule() +for _, name := range modules { + fmt.Println("Available module: ", name) +} +// Will print here for the WASI-Crypto plug-in here: +// wasi_ephemeral_crypto_asymmetric_common +// wasi_ephemeral_crypto_common +// wasi_ephemeral_crypto_kx +// wasi_ephemeral_crypto_signatures +// wasi_ephemeral_crypto_symmetric + +// Create a module instance from the plug-in by the module name. +modinst := plugincrypto.CreateModule("wasi_ephemeral_crypto_common") + +modinst.Release() +``` + +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). + +Before using the plug-ins, developers should [Loading Plug-ins from Paths](#loading-plug-ins-from-paths). + +## Automatic Module Creation and Mocking + +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: + +- `wasi_ephemeral_crypto_asymmetric_common` (for the `WASI-Crypto`) +- `wasi_ephemeral_crypto_common` (for the `WASI-Crypto`) +- `wasi_ephemeral_crypto_kx` (for the `WASI-Crypto`) +- `wasi_ephemeral_crypto_signatures` (for the `WASI-Crypto`) +- `wasi_ephemeral_crypto_symmetric` (for the `WASI-Crypto`) +- `wasi_ephemeral_nn` +- `wasi_snapshot_preview1` +- `wasmedge_httpsreq` +- `wasmedge_process` +- `wasi:logging/logging` (for the `WASI-Logging`) + +## Handling Missing Plug-ins and Error Messages + +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. + +```go +// Load the plug-ins in the default paths first. +wasmedge.LoadPluginDefaultPaths() + +// Create the VM object with the WASI configuration. +conf := wasmedge.NewConfigure(wasmedge.WASI) +vm := wasmedge.NewVMWithConfig(conf) +conf.Release() + +// The following API can retrieve the registered modules in the VM objects, includes the built-in WASI and the plug-ins. +// This API will return `NULL` if the module instance not found. + +// The `wasimodule` will not be `nil` because the configuration was set. +wasimodule := vm.GetRegisteredModule("wasi_snapshot_preview1") + +// 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. +wasinnmodule := vm.GetRegisteredModule("wasi_ephemeral_nn") + +vm.Release() +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/rust_sdk.md b/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/rust_sdk.md new file mode 100644 index 00000000..a74a42d7 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/rust_sdk.md @@ -0,0 +1,78 @@ +--- +sidebar_position: 2 +--- + +## Using Plug-ins to Extend the Runtime in C + +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. + +## Loading Plug-ins from Paths + +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: + +```toml +impl PluginManager +pub fn load(path: Option<&Path>) -> WasmEdgeResult<()> +``` + +- The default plug-in paths will be used if the path is not given. + + - The path specified in the `WASMEDGE_PLUGIN_PATH` environment variable. + - The `../plugin/` directory relative to the WasmEdge installation path. + - The `./wasmedge/` directory under the library path if WasmEdge is installed in the `/usr` directory. + +- If the path is given, then + + - If the path is pointing at a file, then it indicates that a single plug-in will be loaded from the file. + - If the path is pointing at a directory, then the method will load plug-ins from the files. + +To get the names of all loaded plug-ins as returns - + +```toml +pub fn names() -> Vec +``` + + +:::note +`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. +::: + +## Listing Loaded Plug-ins + +Once plug-ins are loaded, developers can list the loaded plug-in names using the following approach: + +```toml +pub fn names() -> Vec +``` + +## Getting Plug-in Context by Name + +Developers can get the plug-in context by its name using the following method: + +```toml +pub fn find(name: impl AsRef) -> Option +``` + +Here `name` is the name of the target plug-in. + +## Getting Module Instances from Plug-ins + +With the plug-in context, developers can get module instances by providing the module name: + +```toml +pub fn mod_names(&self) -> Vec +``` + +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). + +Before using the plug-ins, developers should [Loading Plug-ins from Paths](#loading-plug-ins-from-paths). + +## Plug-in Module Instance + +To initialize the `wasmedge_process` plug-in module instance with the parameters - + +```toml +pub fn init_wasmedge_process(allowed_cmds: Option>, allowed: bool) +``` + +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. From cee5ffe59e8855d2673d02c17410d300f7ac64d7 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Fri, 1 Sep 2023 11:19:23 +0600 Subject: [PATCH 3/4] small fix Signed-off-by: Mahfuza --- docs/embed/use-case/plugin/go_sdk.md | 2 +- docs/embed/use-case/plugin/rust_sdk.md | 14 +++++++------- .../current/embed/use-case/plugin/go_sdk.md | 2 +- .../current/embed/use-case/plugin/rust_sdk.md | 14 +++++++------- 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/embed/use-case/plugin/go_sdk.md b/docs/embed/use-case/plugin/go_sdk.md index 62ce3924..398631d4 100644 --- a/docs/embed/use-case/plugin/go_sdk.md +++ b/docs/embed/use-case/plugin/go_sdk.md @@ -2,7 +2,7 @@ sidebar_position: 3 --- -## Using Plug-ins to Extend the Runtime in C +## Using Plug-ins to Extend the Runtime in Go 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. diff --git a/docs/embed/use-case/plugin/rust_sdk.md b/docs/embed/use-case/plugin/rust_sdk.md index a74a42d7..bfbc8285 100644 --- a/docs/embed/use-case/plugin/rust_sdk.md +++ b/docs/embed/use-case/plugin/rust_sdk.md @@ -2,7 +2,7 @@ sidebar_position: 2 --- -## Using Plug-ins to Extend the Runtime in C +## Using Plug-ins to Extend the Runtime in Rust 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. @@ -10,7 +10,7 @@ The WasmEdge plug-ins are the shared libraries to provide the WasmEdge runtime t 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: -```toml +```rust impl PluginManager pub fn load(path: Option<&Path>) -> WasmEdgeResult<()> ``` @@ -28,7 +28,7 @@ pub fn load(path: Option<&Path>) -> WasmEdgeResult<()> To get the names of all loaded plug-ins as returns - -```toml +```rust pub fn names() -> Vec ``` @@ -41,7 +41,7 @@ pub fn names() -> Vec Once plug-ins are loaded, developers can list the loaded plug-in names using the following approach: -```toml +```rust pub fn names() -> Vec ``` @@ -49,7 +49,7 @@ pub fn names() -> Vec Developers can get the plug-in context by its name using the following method: -```toml +```rust pub fn find(name: impl AsRef) -> Option ``` @@ -59,7 +59,7 @@ Here `name` is the name of the target plug-in. With the plug-in context, developers can get module instances by providing the module name: -```toml +```rust pub fn mod_names(&self) -> Vec ``` @@ -71,7 +71,7 @@ Before using the plug-ins, developers should [Loading Plug-ins from Paths](#load To initialize the `wasmedge_process` plug-in module instance with the parameters - -```toml +```rust pub fn init_wasmedge_process(allowed_cmds: Option>, allowed: bool) ``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/go_sdk.md b/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/go_sdk.md index 62ce3924..398631d4 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/go_sdk.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/go_sdk.md @@ -2,7 +2,7 @@ sidebar_position: 3 --- -## Using Plug-ins to Extend the Runtime in C +## Using Plug-ins to Extend the Runtime in Go 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. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/rust_sdk.md b/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/rust_sdk.md index a74a42d7..bfbc8285 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/rust_sdk.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/rust_sdk.md @@ -2,7 +2,7 @@ sidebar_position: 2 --- -## Using Plug-ins to Extend the Runtime in C +## Using Plug-ins to Extend the Runtime in Rust 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. @@ -10,7 +10,7 @@ The WasmEdge plug-ins are the shared libraries to provide the WasmEdge runtime t 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: -```toml +```rust impl PluginManager pub fn load(path: Option<&Path>) -> WasmEdgeResult<()> ``` @@ -28,7 +28,7 @@ pub fn load(path: Option<&Path>) -> WasmEdgeResult<()> To get the names of all loaded plug-ins as returns - -```toml +```rust pub fn names() -> Vec ``` @@ -41,7 +41,7 @@ pub fn names() -> Vec Once plug-ins are loaded, developers can list the loaded plug-in names using the following approach: -```toml +```rust pub fn names() -> Vec ``` @@ -49,7 +49,7 @@ pub fn names() -> Vec Developers can get the plug-in context by its name using the following method: -```toml +```rust pub fn find(name: impl AsRef) -> Option ``` @@ -59,7 +59,7 @@ Here `name` is the name of the target plug-in. With the plug-in context, developers can get module instances by providing the module name: -```toml +```rust pub fn mod_names(&self) -> Vec ``` @@ -71,7 +71,7 @@ Before using the plug-ins, developers should [Loading Plug-ins from Paths](#load To initialize the `wasmedge_process` plug-in module instance with the parameters - -```toml +```rust pub fn init_wasmedge_process(allowed_cmds: Option>, allowed: bool) ``` From f84473defb7ffe1bc6211603ebfeff05e88eeaf6 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Tue, 12 Sep 2023 20:55:28 +0600 Subject: [PATCH 4/4] small fix Signed-off-by: Mahfuza --- docs/embed/use-case/plugin/c_sdk.md | 9 +++------ .../current/embed/use-case/plugin/c_sdk.md | 9 +++------ 2 files changed, 6 insertions(+), 12 deletions(-) diff --git a/docs/embed/use-case/plugin/c_sdk.md b/docs/embed/use-case/plugin/c_sdk.md index a47fefb9..a58a1281 100644 --- a/docs/embed/use-case/plugin/c_sdk.md +++ b/docs/embed/use-case/plugin/c_sdk.md @@ -69,8 +69,7 @@ for (uint32_t I = 0; I < ModuleLen; I++) { /* Will print the available host module names in the plug-in. */ printf("%s\n", Names[I].Buf); } -/* - * Will print here for the WASI-Crypto plug-in here: +/* Will print here for the WASI-Crypto plug-in here: * wasi_ephemeral_crypto_asymmetric_common * wasi_ephemeral_crypto_common * wasi_ephemeral_crypto_kx @@ -119,8 +118,7 @@ WasmEdge_ConfigureAddHostRegistration(ConfCxt, WasmEdge_HostRegistration_Wasi); WasmEdge_VMContext *VMCxt = WasmEdge_VMCreate(ConfCxt, NULL); WasmEdge_ConfigureDelete(ConfCxt); -/* -* The following API can retrieve the registered modules in the VM context, +/* The following API can retrieve the registered modules in the VM context, * includes the built-in WASI and the plug-ins. */ /* @@ -134,8 +132,7 @@ const WasmEdge_ModuleInstanceContext *WasiModule = WasmEdge_StringDelete(WasiName); WasmEdge_String WasiNNName = WasmEdge_StringCreateByCString("wasi_ephemeral_nn"); -/* -* The `WasiNNModule` will not be `NULL` even if the wasi_nn plug-in is not +/* The `WasiNNModule` will not be `NULL` even if the wasi_nn plug-in is not * installed, because the VM context will mock and register the host * modules. */ diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/c_sdk.md b/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/c_sdk.md index a47fefb9..a58a1281 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/c_sdk.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/embed/use-case/plugin/c_sdk.md @@ -69,8 +69,7 @@ for (uint32_t I = 0; I < ModuleLen; I++) { /* Will print the available host module names in the plug-in. */ printf("%s\n", Names[I].Buf); } -/* - * Will print here for the WASI-Crypto plug-in here: +/* Will print here for the WASI-Crypto plug-in here: * wasi_ephemeral_crypto_asymmetric_common * wasi_ephemeral_crypto_common * wasi_ephemeral_crypto_kx @@ -119,8 +118,7 @@ WasmEdge_ConfigureAddHostRegistration(ConfCxt, WasmEdge_HostRegistration_Wasi); WasmEdge_VMContext *VMCxt = WasmEdge_VMCreate(ConfCxt, NULL); WasmEdge_ConfigureDelete(ConfCxt); -/* -* The following API can retrieve the registered modules in the VM context, +/* The following API can retrieve the registered modules in the VM context, * includes the built-in WASI and the plug-ins. */ /* @@ -134,8 +132,7 @@ const WasmEdge_ModuleInstanceContext *WasiModule = WasmEdge_StringDelete(WasiName); WasmEdge_String WasiNNName = WasmEdge_StringCreateByCString("wasi_ephemeral_nn"); -/* -* The `WasiNNModule` will not be `NULL` even if the wasi_nn plug-in is not +/* The `WasiNNModule` will not be `NULL` even if the wasi_nn plug-in is not * installed, because the VM context will mock and register the host * modules. */