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
|
\---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#
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.
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
-m STRING, --cmake-extra-args=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")