Plugins Structure

As mentioned in Quick Start, the ALFAsim-SDK package has some utilities to help in the process to create 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
    |
    \---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>.

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

Except for creating the plugin structure, all other activities that you might want to perform, you will use pyinvoke tasks.

Below there is detailed list on what they are meant to do. However, in general, the tasks that you will use the most are compile, package and update.

clean

Usage: invoke clean [--options] [other tasks here ...]

Docstring:
  Remove all build folders and .hmplugin files from plugin root and children folders

Options:
  -c STRING, --ctx=STRING

compile

Usage: invoke compile [--options] [other tasks here ...]

Docstring:
  Compile the plugin and generate shared lib.

  The option ``cmake_extra_args`` gives you the ability to pass a
  list of parameters to the cmake command. The list must be a space
  separeted list, for example, "-DARIABLE1=TEST -DVARIABLE2=TEST2"
  Remember to use quotes to wrap the content being passed to this option.

  If the ``--debug`` flag is present, the build configuration will be
  changed from ``Release`` to ``Debug``. Also, if this flag is active,
  more information about the compilation process will be printed to
  the console

  If the ``--clean`` flag is present, the previous generated ``build`` folder
  is removed. This is useful because in the absence of the task, the compilation
  will use cmake's cache to speed up the compilation time.

Options:
  -c STRING, --ctx=STRING
  -d, --debug
  -l, --clean
  -m STRING, --cmake-extra-args=STRING

install_plugin

Usage: invoke install_plugin [--options] [other tasks here ...]

Docstring:
  Install a plugin to ``install_dir`` folder.

  If absent, the ``install_dir`` will be assumed to be ``$HOME/.alfasim_plugins`` on linux
  or ``USERPROFILE\.alfasim_plugins`` on windows.

  Note: remember to always set ``ALFASIM_PLUGINS_DIR` to ``install_dir`` if you are using
  a different path than the default.

Options:
  -c STRING, --ctx=STRING
  -i STRING, --install-dir=STRING

msvc

Usage: invoke msvc [--options] [other tasks here ...]

Docstring:
  Create a MSVC solution file for the plugin.

Options:
  -c STRING, --ctx=STRING

package

Usage: invoke package [--options] [other tasks here ...]

Docstring:
  Create a new `<package-name>.hmplugin` file containing all the necessary files.

  This command will first call `invoke compile` command to generate the shared library, and after that, the plugin
  package will be generated with all the content available from the directory assets and artifacts.

  The `package` command will assume that the plugin project is the directory that
  contains the ``tasks.py`` file and the generated file will be placed also in the current directory.

Options:
  -c STRING, --ctx=STRING
  -d STRING, --dst=STRING
  -e, --debug
  -l, --clean
  -m STRING, --cmake-extra-args=STRING
  -p STRING, --package-name=STRING

package_only

Usage: invoke package_only [--options] [other tasks here ...]

Docstring:
  Generate a `<package_name>.hmplugin` file with all the content from the directory
  assets and artifacts.

  By default, the package will be created inside the folder plugin_dir, however, it's possible
  to give another path filling the --dst argument.

Options:
  -c STRING, --ctx=STRING
  -d STRING, --dst=STRING
  -p STRING, --package-name=STRING

reinstall_plugin

Usage: invoke reinstall_plugin [--options] [other tasks here ...]

Docstring:
  Remove, package and install an specified plugin to install_dir

  If absent, the ``install_dir`` will be assumed to be ``$HOME/.alfasim_plugins`` on linux
  or ``USERPROFILE\.alfasim_plugins`` on windows.

  It does the following steps:
      1) Remove the specified plugin from $HOME/.alfasim_plugins
      2) Compile the specified plugin and generate package
      3) Install the specified plugin to $HOME/.alfasim_plugins

Options:
  -c STRING, --ctx=STRING
  -i STRING, --install-dir=STRING
  -p STRING, --package-name=STRING

uninstall_plugin

Usage: invoke uninstall_plugin [--options] [other tasks here ...]

Docstring:
  Remove plugin from install folder.

  If absent, the ``install_dir`` will be assumed to be ``$HOME/.alfasim_plugins`` on linux
  or ``USERPROFILE\.alfasim_plugins`` on windows.

Options:
  -c STRING, --ctx=STRING
  -i STRING, --install-dir=STRING

update

Usage: invoke update [--options] [other tasks here ...]

Docstring:
  Update plugin files automatically generated by ALFAsim-SDK.

  It is important to update the automatically generated files from each plugin when
  a new version of ALFAsim-SDK is released. Otherwise compilation problems can occur.

  The files updated are: |br|
  - ´<plugin_folder>/src/hook_specs.h´ |br|

Options:
  -c STRING, --ctx=STRING

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")