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:
\---myplugin
| CMakeLists.txt
| tasks.py
|
+---assets
| plugin.yaml
| README.md
|
\---src
| CMakeLists.txt
| hook_specs.h
| myplugin.cpp
|
\---python
myplugin.py
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.
By default, the `package` command will assume that the plugin project is the current directory and the generated file
will be placed also in the current directory.
In order to change that, it's possible to use the options `plugin-dir` and `dst`
Options:
-c STRING, --ctx=STRING
-d STRING, --dst=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 @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
@task
def clean():
print("Overwriting the clean task")