Using Kanzi Engine Rust plugins¶

Kanzi Rust API allows you to follow the same workflows for Kanzi Engine Rust plugins as for plugins written in C++.

Create a Kanzi Engine Rust plugin using a template¶

You can create a Kanzi Engine plugin in Rust using the template provided by the Kanzi Rust API package.

To create a Kanzi Engine Rust plugin:

In the Kanzi Studio New Project window choose the Application with Rust plugin template.
Click Create.

Kanzi creates both Kanzi Studio and Kanzi application projects, placing the Rust plugin in the Application/src/plugin directory. The application includes a ready-made CMake utility that allows you to build the Rust module as part of the application build step.

Build a Kanzi Engine Rust plugin¶

Before building your Kanzi application with the Rust module, make sure that the KANZI_HOME environment variable is set to the <KanziWorkspace> directory.

If you use a custom installation directory for the Kanzi Rust API package, set its location in the KANZI_RUST_HOME environment variable.

To build a Kanzi Engine Rust plugin, you can either:

Use the Visual Studio Code build task provided by the template:
1. Open the <MyProject>/Application directory in Visual Studio Code.
2. Press Ctrl+Shift+B to run the build task. This way you build the application and the plugin, and install the plugin to the <MyProject>/Application/lib/<Platform>/<ConfigurationName> directory.
Build the plugin from the command line with these steps:
1. Navigate to the <MyProject>/Application directory.
2. Configure the project and generate build files:
```
cmake -B build_vs2019 -G "Visual Studio 16 2019" -A "x64"
```
3. Build the Kanzi Engine Rust plugin DLL:
```
cmake --build build_vs2019 --config "Release" --verbose --target "<MyProject>_build"
```
  This CMake command invokes the cargo command with the required settings to build the Rust module as a shared library.
4. Install the DLL to the <MyProject>/Application/lib/<Platform>/<ConfigurationName> directory:
```
cmake --build build_vs2019 --config "Release" --verbose --target "<MyProject>_plugin_studio_install"
```
  This CMake command copies the built DLL to the location where Kanzi Studio loads the native plugins.

To update the Kanzi Engine Rust plugin in the Kanzi Studio project, in the Library > Kanzi Engine Plugins right-click the plugin and select Update Kanzi Engine Plugin. This way you update the plugin and take into use the changes that you made to your plugin.

Register a Kanzi Engine Rust plugin in your Kanzi application¶

For dynamically linked plugins, Kanzi Engine loads and registers the plugin automatically when it is a dependency of the kzb file.

For statically linked plugins, register the plugin in your application code by calling the registration function provided by the plugin, for example:

// The generated header file with the plugin registration function.
#include <myrustplugin_plugin.hpp>

class MyRustPluginApplication : public ExampleApplication
{
public:
    void registerMetadataOverride(ObjectFactory& factory) override
    {
        // Register MyRustPlugin
        Domain* domain = getDomain();
        // Call the registration function of MyRustPlugin plugin.
        rust::registerMyRustPluginPlugin(domain);
    }
};

Debug a Kanzi Engine Rust plugin¶

The recommended way to debug Kanzi Rust modules is to use Visual Studio Code. The project created from the template has launch tasks allowing you to debug both Rust and C++ code. To enable full debugging support, make sure you have installed the Rust and C++ extensions in Visual Studio Code.

To start debugging, open the project in Visual Studio Code and press F5.