Plugins Structure

As mentioned in Quick Start, the ALFAsim-SDK package has some utilities to help in the process of creating a plugin file.

First, to create the plugin use new:

>>> alfasim-sdk new --help

alfasim-sdk new

Generate a new plugin directory structure and files.

The template folder will be placed on the dst option, that by default is the current directory from where the command was invoked.

A tasks.py will be generated containing default tasks, and which can be further customized if needed. Run invoke --list to get a list of the available tasks.

The files generated and their contents are ready to be used and have the following structure:

<dest>
\---<plugin_id>
    |   CMakeLists.txt
    |   tasks.py
    |
    +---assets
    |       plugin.yaml
    |       README.md
    |       CHANGELOG.rst
    |
    \---src
        |   CMakeLists.txt
        |   hook_specs.h
        |   <plugin_id>.cpp
        |
        \---python
            |   <plugin_id>.py
            |
            \---alfasim_sdk_plugins
                \---<plugin_id>
                        __init__.py

Any python code placed in alfasim_sdk_plugins/<plugin_id> is importable by using import alfasim_sdk_plugins.<plugin_id>.<my_extra_module>.

Usage

alfasim-sdk new [OPTIONS]

Options

--dst <dst>

A path to where the plugin project should be created. Default: Current directory

--caption <caption>

Caption to be used across the application to identify the plugin

--plugin-id <plugin_id>

The name of the plugin

--author-name <author_name>

Name of the plugin author, this value is stored in plugin metadata and not displayed on the application explicitly

--author-email <author_email>

Email of the plugin author, this value is stored in plugin metadata and not displayed on the application explicitly

Pyinvoke tasks

Once the plugin structure is created, you can perform all necessary activities using pyinvoke tasks, with compile, package and update beeing the most commonly used during plugin development. Below you can find a list of all available along with their descriptions.

Task	Description
compile	Compile the plugin and generate the shared library. Accepts --debug, --clean, and --cmake-extra-args options.
package	Compile and package the plugin into a .hmplugin file. Combines compile and package-only in one step.
package-only	Generate a .hmplugin file from the already-compiled artifacts without recompiling. Accepts --package-name and --dst options.
update	Update plugin files automatically generated by ALFAsim-SDK (e.g. hook_specs.h). Run this after upgrading the SDK.
install-plugin	Install the packaged plugin into the ALFAsim plugins directory (defaults to ~/.alfasim_plugins).
uninstall-plugin	Remove the plugin from the ALFAsim plugins directory.
reinstall-plugin	Uninstall, recompile, repackage and reinstall the plugin in one step.
clean	Remove all build folders and .hmplugin files from the plugin root.
msvc	Generate a Visual Studio (MSVC) solution file for the plugin (Windows only).

You can check their implementations here and you can also overwrite them by just defining a function with the same name of the default task with the @sdk_task decorator.

For instance, if you want to overwrite the clean task, define the following inside your tasks.py in the root of your plugin.

from invoke import task

@sdk_task
def clean():
    print("Overwriting the clean task")