OpenCPN Developer Manual

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

  • Well-defined local builds of tarballs which can be imported

  • 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.

  • Simple, script-based template updates.

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.

Template installation.

The template installation process is described in the Adaptation Overview Page.

Background

Alec Leamas is the main architect of the managed plugin system for OpenCPN. The reference documentation is available 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 often 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.

This workflow is not limited to legacy plugins, it can basically be applied to any plugin.

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.