Create a plugin

This section provides a step by step guide on how to get Chipmunk and the Quickstart repository as well as how to build them. The repository Quickstart provides a variety of plugins which can be copied and modifed to create new plugins.

Installation of plugins and Chipmunk

First off clone the create a folder for Chipmunk and Quickstart by typing the following commands:

mkdir chipmunk-developing
cd chipmunk-developing

After creating the folder, clone both the Chipmunk and the Quickstart repository into the folder and navigate into it.

git clone https://github.com/esrlabs/chipmunk.git
git clone https://github.com/esrlabs/chipmunk-quickstart.git
cd chipmunk-quickstart

The Quickstart repository has a few examples of plugins which are located in the folder plugin:

└── plugins
    ├── plugin.helloworld
    ├── plugin.row.columns
    ├── plugin.row.parser
    ├── plugin.selection.parser
    └── plugin.sh

To build the plugin, type the following command with the path to the target plugin:

rake build[./plugins/plugin.helloworld]

Optionally you can define a version of your plugin:

rake build[./plugins/plugin.helloworld, 1.0.1]

WINDOWS Note: To call a rake task with multiple arguments, it could be command should be wrapped as string rake 'build[./plugins/plugin.helloworld, 1.0.1]'

Note: The very first build always takes some noticeable time because of build script downloads and compiles necessary infrastructure.

As a result the folder releases will be created with the compiled plugin:

├── plugins
│    ├── plugin.helloworld
│    ├── plugin.row.columns
│    ├── plugin.row.parser
│    ├── plugin.selection.parser
│    └── plugin.sh
└── releases
     └── plugin.helloworld

To build Chipmunk run the following commands to navigate into the folder where the repository was copied:

rake full_pipeline

The building of Chipmunk will take some time but only needs to be built once. After the build is finished Chipmunk can be executed from the releases folder.

Before starting Chipmunk some environment variables need to be passed in as a preparation.

First off define a full path to the folder that will hold the release of your plugin.

export CHIPMUNK_PLUGINS_SANDBOX=../chipmunk-quickstart/releases

By default Chipmunk stores plugins the home folder in .chipmunk/plugins but by running the command above it can be modified.

To prevent the installation of default plugins, run the following command

export CHIPMUNK_PLUGINS_NO_DEFAULTS=true

If your has plugin already been published in the Chipmunk Store these commands would prevent it from updating:

export CHIPMUNK_PLUGINS_NO_UPGRADE=true
export CHIPMUNK_PLUGINS_NO_UPDATES=true

To enable logs in the Console making it easier to debug:

export CHIPMUNK_DEV_LOGLEVEL=ENV

Now Chipmunk is ready to be executed.

Rake commands

The following Rake commands are vital for the compilation of Chipmunk, which is why in this section the most important rake commands are going to be mentioned and described.

rake start                                          # Start Chipmunk
rake full_pipeline                                  # Build Chipmunk (whole application)
rake build[./plugins/plugin.helloworld]             # Build plugin
rake build[./plugins/plugin.helloworld, 1.0.1]      # Build plugin with version
rake 'build[./plugins/plugin.helloworld, 1.0.1]'    # Build plugin with version (Windows)

If a new update of Chipmunk is available, first run rake clobber (to remove all compiled files) and then rake full_pipeline to update and re-build Chipmunk.

The next section gives a thorough explanation of the default plugins provided by Quickstart

documentation

Create a plugin

Installation of plugins and Chipmunk

Rake commands