Adapting the legacy plugin

In order to enable both local builds and Continous Integration (CI) a number of template files and directories needs to be installed in the plugin sources. This page describes this process.

The reference plugin where the development work has been carried out is ShipDriver (Master branch). To show the process from start TideFinder is used as an illustration.

Before using the shipdriver templates a plugin must as a first step be adapted to the Plugin Installer as described in the Developer Manual Page.

1. Install template files

1.1. update-templates

The script update-templates script has been written to simplify the process of adding the directories/files needed for the workflow. You will need git bash for running the script. A guide is included in UPDATE_TEMPLATES.md.

The script will install all files required in TideFinder except as noted below. Note that script is normally used to update to from a tag like sd3.0.0

1.2. README.md and COPYING

All plugins should have README.md which gives a short summary of the plugin, links to documentation and, important, an overall copyright and license statement. This is a legal requirement to be able to distribute the plugin

Files in the templates have different licenses, all compatible with GPL version 3 or later (GPLv3+). If you choose to use this license, there should also be a file COPYING containing the license. This could be retrieved using git checkout shipdriver/master COPYING

1.3. CMakeLists.txt

The templates have divided the usual, single CMakeLists.txt into two files Plugin.cmake and CMakeLists.txt. Plugin.cmake contains everything which is specific for the plugin. CMakeLists.txt is part of the templates and the same in all plugins.

After running the script, Plugin.cmake is still missing. It can be added using git checkout sd3.0.0 Plugin.cmake, assuming update-templates was updating to sd3.0.0

This file needs to be modified, most of the required items will be available in CMakeLists.txt. After having modified Plugin.cmake to match TideFinder checkout the generic, template CMakeLists.txt using git checkout sd3.0.0 CMakeLists.txt, assuming update-templates used the sd3.0.0 tag.

This will overwrite the existing CMakeLists.txt, but after all it is in the git history. Commit the two files.

1.4. The flatpak directory

Start by checking out the shipdriver flatpak directory using: git checkout shipdriver/master flatpak

The directory will contain a file named org.opencpn.OpenCPN.Plugin.shipdriver.yaml. This should be renamed to match the TideFinder plugin i. e., org.opencpn.OpenCPN.Plugin.TideFinder.yaml.

After renaming it, edit file and replace ShipDriver with TideFinder in all places. This is enough for simple plugins.

If org.opencpn.OpenCPN.Plugin.TideFinder.yaml already exists and flatpak builds fail compare the file with org.opencpn.OpenCPN.Plugin.shipdriver.yaml in the ShipDriver repo. A small edit for the flatpak SDK version may be needed.

1.5. Remove obsolete files

Remove src/ocpn_plugin.h from the source files listed in Plugin.cmake. This is now found in the libs/api-16 directory. The file should also be removed from the src directory.

2. Testing

When completed, it should be possible to run local builds as described in INSTALL.md or the Usage page and build dependencies page.

3. Appendix: Affected Files

3.1. Directories replaced by template files:

.circleci

ci

buildwin

libs

cmake

cmake

scripts

3.2. Files added/replaced:

.clang-format

.cmake-format.yaml

.drone.yml

.gitattributes

.gitignore

.travis.yml

appveyor.yml

CMakeLists

INSTALL.md

plugin.xml.in

UPDATE_TEMPLATES.md

update-templates