DUNE allows users to extend its functionality through the use of plugins. DUNE plugins are simply Python scripts which are fulfilling specific requirements explained below.
- Plugin needs to be placed in the subdirectory of ../src/plugin/.
- In the aforementioned subdirectory you need to create script
main.pyneeds to define 3 functions:
add_parsing(parser)- function that receives instance of argparse.ArgumentParser. It is used to add new DUNE command parsing arguments.
set_dune(dune)- function that receives instance of DUNE so the user could interact with DUNE. It might be stored for later usage if needed.
handle_args(args)- function that receives populated namespace returned by ArgumentParser.parse_args. It is used to handle new DUNE command arguments.
You can find example plugins in plugin_example directory. To test the example plugins, copy or symbolically link the contents of the ../plugin_example/ directory into the ../src/plugin/ directory. This way, DUNE will automatically discover the new plugins.
The simplest plugin, which adds
--hello to DUNE commands. When command
dune --hello is executed then an example output is printed.
Plugin adds command
--bootstrap-account to DUNE commands. When it is executed 3 example accounts are created:
Additionally the contract
eosio.token is deployed to all above accounts.
In this example you can see how
set_dune function is being used to store
dune instance and later use it to create and prepare accounts.
DUNE starts with auto-discovering the plugins in the
src/plugin subdirectories and dynamically loading each
main.py file. The functions from each plugin are then called in the following order:
add_parsing(parser)- this function is called first to add parsing arguments. Users can also initialize their plugin at this stage, however, it should be noted that at this point it is not known if the plugin will be used.
set_dune(dune)- if the user wants to interact with DUNE, they should store the DUNE object in this function.
handle_args(args)- the user should check if their parsing arguments are being used and handle them in this function. This is the main function where the plugin does its job. The DUNE object is usually needed in this function.