Add best practices for plugin (#191)

* best practice Signed-off-by: Mahfuza Humayra Mohona <[email protected]> * fix headline Signed-off-by: Mahfuza Humayra Mohona <[email protected]> * update testing section Signed-off-by: Mahfuza Humayra Mohona <[email protected]> * update tests Signed-off-by: Mahfuza Humayra Mohona <[email protected]> * add test guide Signed-off-by: Mahfuza Humayra Mohona <[email protected]> * update code Signed-off-by: Mahfuza Humayra Mohona <[email protected]> * security Signed-off-by: Mahfuza Humayra Mohona <[email protected]> * final update Signed-off-by: Mahfuza Humayra Mohona <[email protected]> * updating publish section Signed-off-by: Mahfuza Humayra Mohona <[email protected]> * update format Signed-off-by: Mahfuza Humayra Mohona <[email protected]> * update as per review Signed-off-by: Mahfuza Humayra Mohona <[email protected]> * add hyperlink for image plugin Signed-off-by: Mahfuza Humayra Mohona <[email protected]> * add hyperlink for image plugin Signed-off-by: Mahfuza Humayra Mohona <[email protected]> * change code example langage Signed-off-by: Mahfuza Humayra Mohona <[email protected]> * update code example Signed-off-by: Mahfuza Humayra Mohona <[email protected]> --------- Signed-off-by: Mahfuza Humayra Mohona <[email protected]>
WasmEdge · Mar 4, 2024 · 6499fa3 · 6499fa3
1 parent e42f59d
commit 6499fa3
Show file tree

Hide file tree

Showing 4 changed files with 440 additions and 0 deletions.
diff --git a/docs/contribute/plugin/best_practice.md b/docs/contribute/plugin/best_practice.md
@@ -0,0 +1,155 @@
+---
+sidebar_position: 6
+---
+
+# Best Practice 
+
+When developing a WasmEdge plugin, it's important to follow best practices to ensure the plugin is well purformed, reliable, and efficient. Here are some key best practices to follow:
+
+## Using the Latest Version of WasmEdge
+
+Always use the latest version of WasmEdge to take advantage of the most recent features, improvements, and security updates. 
+
+### Installing the Latest Version
+
+To install the latest version of WasmEdge, follow the installation instructions in the [WasmEdge documentation](https://wasmedge.org/docs/start/install/).
+
+### Updating Existing Plugins
+
+If you have existing plugins that were developed with an older version of WasmEdge, you may need to update them to work with the latest version. This could involve updating the plugin code to use new features or changes in the [WasmEdge API](https://wasmedge.org/docs/category/api-reference/), or updating the build process to use the latest version of WasmEdge.
+
+Remember, using the latest version of WasmEdge not only ensures that you're leveraging the most recent features, but also provides the latest security updates to protect your applications.
+
+
+## Choosing the Appropriate Programming Language
+
+WasmEdge plugins can be developed in several languages including [C](develop_plugin_c.md), [C++](develop_plugin_cpp.md), and [Rust](develop_plugin_rustsdk.md). The choice of language depends on the specific requirements of the plugin and the developer's expertise. The C API is recommended for most use cases due to its simplicity and wide support. However, complex plugins might benefit from the enhanced features of C++ or Rust.
+
+## Writing and Compiling the Plugin
+
+When creating a WasmEdge plugin:
+
+   1. **Code Writing**: While develop your plugin, write clear, maintainable code, and document it well for easy understanding and future maintenance.
+
+   2. **Compiling to Shared Library**: Use a compiler like `gcc` for C or `g++` for C++ to compile your code into a shared library. For example, in a Linux environment, you might use `gcc -shared -fPIC -o my_plugin.so my_plugin.c` for a C plugin.
+
+   3. **Error Handling and Input Validation**: Efficitive error handling to catch and manage potential issues. Validate all inputs thoroughly to ensure the plugin's stability and security.
+
+## Testing the Plugin
+
+Testing is a crucial part of the plugin development process. It ensures that the plugin behaves as expected, meets the requirements, and performs optimally. WasmEdge provides a set of tests for various plugins in its [repository](https://github.com/WasmEdge/WasmEdge/tree/master/test/plugins) that you can use as references for writing your own tests.
+
+To run tests for the WasmEdge plugin, you'll need to follow a few steps. In this case, we'll use the `wasmedge-image` plugin as an example.
+
+   - **Step 1: Build the WasmEdge Runtime and WasmEdge-image Plugin** 
+   First, you need to build both the [build WasmEdge](../source/build_from_src.md) and the [wasmedge-image](../source/plugin/image.md) plugin.
+
+   - **Step 2: Run the Tests**
+   The WasmEdge repository provides a set of tests for various plugins, including `wasmedge-image`. You can find the test cases in the `test/plugins/wasmedge_image` directory of the repository.
+
+      To run these tests, you can use the `ctest` command from the build directory:
+
+      ```bash
+      cd ../../../test/plugins/wasmedge_image
+      mkdir build && cd build
+      cmake ..
+      make
+      ctest
+      ```
+
+   This will run all the unit tests and integration tests for the `wasmedge-image `plugin. These tests ensure that the plugin behaves as expected, meets the requirements, and performs optimally. They also verify that the plugin correctly integrates with the WebAssembly program and that the WebAssembly program can call the plugin's functions correctly.
+
+   - **Step 3: Analyze the Test Results**
+   After running the tests, analyze the results to identify any issues or bugs. If any test fails, you should debug the issue, fix the problem, and then rerun the tests to ensure that the fix works as expected.
+
+By following these steps, you can effectively run tests for the `wasmedge-image` plugin or any other WasmEdge plugin.
+
+<!-- prettier-ignore -->
+:::note
+If you want to develop your own tests follow [Writing Tests for WasmEdge Plugins](test_plugin.md) for details.
+::: 
+
+## Securing the Plugin
+
+Security is a vital part of any software development process. It involves several aspects, including securing the code, verifying inputs, handling errors properly, and using secure coding practices. When developing a WasmEdge plugin, it's essential to follow these best practices:
+
+   - **Validate Inputs:** Always validate the inputs to your functions. This can prevent many types of attacks, including buffer overflow attacks and code injection attacks.
+
+      ```c
+      WasmEdge_Result Add(void *, const WasmEdge_CallingFrameContext *,
+                           const WasmEdge_Value *In, WasmEdge_Value *Out) {
+         if (In[0].Type != WasmEdge_ValType_I32 || In[1].Type != WasmEdge_ValType_I32) {
+         return WasmEdge_Result_Error;
+         }
+         // Rest of the function...
+      }
+      ```
+
+   - **Handle Errors:** Always handle errors properly. Don't ignore return values that indicate an error, and don't continue execution after an error occurs.
+
+      ```c
+      WasmEdge_Result Add(void *, const WasmEdge_CallingFrameContext *,
+                           const WasmEdge_Value *In, WasmEdge_Value *Out) {
+         // Check the input types...
+         int32_t Val1 = WasmEdge_ValueGetI32(In[0]);
+         int32_t Val2 = WasmEdge_ValueGetI32(In[1]);
+         if (Val1 == INT32_MIN || Val2 == INT32_MIN) {
+         return WasmEdge_Result_Error;
+         }
+         // Rest of the function...
+      }
+      ```
+
+   - **Use Secure Coding Practices:** Follow secure coding practices in your chosen language. For example, avoid using unsafe functions, use strong types, and avoid using global variables.
+
+## Publishing the Plugin
+
+Once you have developed, tested, and documented your WasmEdge plugin, it’s time to publish it for others to use. You need to follow following steps for publishing your plugin:
+
+## Exporting the SDKs in Rust
+
+In addition to C and C++ SDKs, you can also create an SDK for Rust developers. This involves creating a Rust library that provides a Rust interface to your plugin's functionality.
+
+### Creating a Rust Library
+
+You can create a Rust library that provides a Rust interface to your plugin's functionality. This involves writing Rust code that calls the functions in your plugin and provides a Rust-friendly API.
+
+In the [wasmedge-image](../source/plugin/image.md) plugin's case, you might have something like this:
+
+```rust 
+// lib.rs
+extern crate wasmedge_image;
+
+use wasmedge_image::Image;
+
+pub fn load_image(path: &str) -> Result<Image, wasmedge_image::Error> {
+    Image::open(path)
+}
+```
+In this Rust library, a single `load_image` function is provided that calls the `open` function from the `wasmedge-image` plugin.
+
+### Building the Rust Library
+
+You can build your Rust library using Cargo, the Rust package manager. This will produce a `.so` file that can be loaded by the WasmEdge runtime.
+
+```bash 
+cargo build --release
+```
+
+### Packaging the Rust SDK
+
+Package the Rust library and the header file into a tarball or a similar package format. This makes it easy for other developers to download and install your SDK.
+
+```bash 
+tar czvf wasmedge_image_rust_sdk.tar.gz libwasmedge_image.so wasmedge_image.h
+```
+
+With this package, other rust developers can easily use your plugin in their applications. They just need to include your header file in their code, and link against your rust library when they compile their application.
+
+Now, when you're ready to publish your plugin and the corresponding SDK, can publish your plugin on the official WasmEdge [plugin repository](https://github.com/WasmEdge/WasmEdge/tree/master/plugins) by creating a pull request into it or any other repository of your choice. Make sure to include the documentation and any other resources (like test files) with your plugin.
+
+## Contributing to the WasmEdge Community
+
+As an open-source contributor, you can share your plugin with the community by submitting it to the official [WasmEdge repository](https://github.com/WasmEdge/WasmEdge). This allows others to benefit from your work.
+
+By following these best practices, you can ensure a successful and efficient plugin development process for WasmEdge.
diff --git a/docs/contribute/plugin/test_plugin.md b/docs/contribute/plugin/test_plugin.md
@@ -0,0 +1,65 @@
+---
+sidebar_position: 5
+---
+
+# Writing Tests for WasmEdge Plugins
+
+This guide aims to help you write tests for your newly developed WasmEdge plugin. We will cover the steps of creating test cases, implementing the test cases in code, and executing them with Google Test, a popular C++ testing framework.
+
+## Understanding Your Plugin
+
+Before you start writing tests, make sure you understand your plugin's functionality and structure. The plugin code for WasmEdge typically consists of the following parts:
+
+- **Plugin and Module Descriptions**: These are structures that provide metadata about the plugin and the modules it includes.
+- **Host Functions and Modules**: These are the functionalities provided by the plugin, implemented as C++ classes and methods.
+- **Module Creation Functions**: These functions create instances of the plugin's modules when the plugin is loaded by the WasmEdge runtime.
+
+## Creating Test Cases
+
+The first step in writing tests is to create test cases. Each test case should focus on a specific functionality of your plugin. For example, if your plugin provides a function to add two numbers, you might have test cases that cover normal inputs, edge cases (like the maximum possible integers), and error handling (like passing non-integer values).
+
+## Implementing Test Cases
+
+Once you have your test cases, you can start implementing them in code. Each test case should be implemented as a C++ function that uses Google Test macros to perform assertions.
+
+Here's an example of how you might implement a test case:
+
+    ```cpp
+    #include "gtest/gtest.h"
+    #include "your_plugin.h"
+
+    TEST(YourPluginTest, ConvertsNormalString) {
+    YourPlugin plugin;
+    std::string input = "123";
+    int expected = 123;
+    EXPECT_EQ(expected, plugin.convert(input));
+    }
+    ```
+
+In this example, `YourPluginTest` is the test suite name, and `ConvertsNormalString` is the test case name. The `EXPECT_EQ` macro is used to verify that the result of `plugin.convert(input)` is the same as `expected`.
+
+## Compiling and Executing Tests
+
+The final step is to compile and execute your tests. WasmEdge uses CMake to manage its build process, so you can add your test file to the `CMakeLists.txt` file in the test directory:
+
+    ```cmake
+    add_executable(your_plugin_test your_plugin_test.cpp)
+    target_link_libraries(your_plugin_test gtest_main your_plugin)
+    add_test(NAME your_plugin_test COMMAND your_plugin_test)
+    ```
+
+Then, you can build and run your tests with the following commands:
+
+    ```bash
+    mkdir build
+    cd buildtest_plugin.md
+    cmake ..
+    make
+    ctest
+    ```
+
+If everything is set up correctly, this will compile your tests, run them, and report the results.
+
+Remember, testing is an iterative process. As you develop new features or fix bugs, you should also update your tests to reflect these changes. This will ensure that your plugin continues to work as expected as it evolves.
+
+We hope this guide helps you get started with writing tests for your WasmEdge plugins!