Shipdriver template for OpenCPN Plugins
The template at a glance
The shipdriver template is a buildsystem template which can be applied to any OpenCPN plugin. The template provides:
-
Generation of tarballs which can be used by the plugin installer
-
Uploading of tarballs to Cloudsmith
-
Generation of XML metadata with correct download urls and tarball checksum
-
Support for making PRs to the plugins project (i.e., the catalog) by committing metadata automatically into git.
-
Well-defined local builds of tarballs which can be imported
Use of the template with a configured plugin is documented in the usage page. These instructions are shipped with the plugin in the file INSTALL.md.
The following guide illustrates how the template can be applied from scratch to a plugin.
This guide should be read alongside the README files in the ShipDriver repository.
The overall managed plugin flow
A managed plugin becomes available for an OpenCPN user in the Plugins options dialog. Here, a number of plugins are available for users so they can just click on a plugin to install it. The managed plugins workflow is the way a plugin becomes available for users in this UI dialog.
In general, plugin code flows like this:
-
Source code is stored and eventually tagged and released on Github
-
As soon as a change is committed a number of builder services build the code for around 10 platforms.
-
The compiled plugins are stored on cloudsmith. Here, they get a url which can be used to download them.
-
The builds also produce metadata files with plugin data such as name, platform, various info and the download URL.
-
The metadata files are used to create a catalog. This catalog is the underpinning for the list of plugins in the OpenCPN plugin dialog.
Introduction
Alec Leamas is the main architect of the managed plugin system for OpenCPN. His guide is here.
The OpenCPN Developers Manual has extensive general documentation for managed plugins. It also describes the two alternative template systems testplugin and shipdriver. This document provides more info on the shipdriver setup and workflow.
A managed plugin will nearly always start as a `legacy' plugin that installs locally on the developers machine. Alec has provided new scripts to build a managed version of the plugin for OpenCPN. The legacy plugin is the starting point and the purpose of this guide is to describe the steps involved. The aim is to simplify the workflow.
The reference plugin where the development work has been carried out is ShipDriver (Master branch). To show the process from the start TideFinder is used as an illustration.
Mike Rossiter, who developed the ShipDriver and TideFinder plugins, assisted by testing the workflow. He has produced this guide to assist developers in making a managed plugin. Please report any errors or omissions using the issues tab of this GitHub repository.