OpenCPN Developer Manual

Configure Testplugin Template

Features

  • Fully functional plugin

  • Uses OCPN interfaces and demonstrates how to use the ocpn_draw_pi API, JSON & Binary versions.

  • Continuous Integration and CMake package.

  • Guidance for the automated build process.

  • Cmake, CMakeLists.txt and scripts that are needed to compile the environments.

  • Encapsulates the complexities of multi environment builds and deploys.

  • Makes it easier to build and deliver plugins.

  • Plugin changes are made in CMakeLists.txt.

  • No need to modify the other build files.

  • Delivered to OpenCPN Plugin Management User Interface using metadata files

  • Via OpenCPN Container Project for an Integrated Plugin Management Facility

  • Found at https://github.com/opencpn/plugins

Goal

Assist plugin developers to convert their plugins to the Plugin Manager system which:

  • Uses tarballs and metadata.xml files to store the necessary information.

  • Deploys directly to Cloudsmith repositories (or another location)

  • Online Files are accessed by OpenCPN Plugin Manager using "Library Catalog" (metadata.xml)

  • Plugins are installed from within OpenCPN Options > Plugins

  • User selects a Plugin to download, install or enable from an updated Catalog.

The template configuration is found in https://github.com/jongough/testplugin_pi.

Rename Existing Directories and Files

Create new working Git branch for your Plugin:

  • Keep your currently working "master" branch intact.

  • Create a new git branch.

  • EG: 'git checkout -b <testplugin-template> master'

  • Work in the new branch <testplugin-template>.

    1. Pull new working branch to local.

    2. Pull testplugin to local.

    3. Make sure both local github repositories are current.

Copy original files to a backup:

  • Rename CMakeLists.txt ---→ CMakeLists.txt.bk

  • Rename appveyor.yml ---→ appveyor.save.yml.bk

  • Rename .travis.yml ---→ .travis.save.yml.bk

  • Rename the cmake directory --→ cmake-bk

Keep any other specialized plugin directories or files.

Directories to Remain intact in your Plugin

  • Include

  • Data

  • src

  • po

Any other plugin specific directories.

Directories Not needed from Testplugin

  • data

  • forms

  • include

  • lib

  • src

File Compare Software

  • Use software similar to WinMerge (open source) for File Comparison.

  • Get the two local folders opened and compare each folder.

  • Then follow instructions below.

Copy Files & Folders from Testplugin_pi

Copy full Directories, Sub-dir and Files unless noted replacing any existing folders and files entirely.

  • .circleci

  • ci

  • cmake

  • buildosx

  • buidwin

  • mingw

  • extinclude (Json Validation - only odraw, watchdog, weather_routing)

  • extsrc (Json Validation - only odraw, watchdog, weather_routing) + ocpninclude (only glu directory and TexFont.h

  • ocpnsrc (only GL directory and TexFont.cpp

  • appveyor.yml (file)

  • .travis.yml (file)

Review and Compare.

  • CMakeLists.txt

Edit this file while comparing to old file.
There are inline directions in the file.
Add specific information for your plugin.
Add include files as necesary and headers and libs. See notes below for more detail.

Changes Required

  1. Backup CMakeLists.txt, appveyor.yml, .travis.yml

  2. Modify CMakeLists.txt file, following the in-line notes

    1. Modify Plugin Specifics at the top.

      • Plugin name types,

      • CommonName -search "plugin"_pi.cpp for "GetCommon"

      • Version numbers and date

      • Parent, Package and Git User. Git Repository

      • Cloudsmith User

      • Cloudsmith Base Repository (optional)

      • Plugin XML Info_url, Summary and Description

    2. In the section that also uses your plugins specific code:

      • Modify/configure set(SRCS and HDRS and 'Include' Dir

      • Modify/configure 'Set(SRCS & HDRS' Directories

    3. Modify/configure 'Add Library' listings for the plugin.

      • Make sure all your necessary libraries are found.

  3. API Number must be at least 1.16 for the new Plugin Manager, due to a change in how directories are found and location.

  4. API Names changed from MY_API_VERSION_MAJOR/MINOR to OCPN_API_VERSION_MAJOR/MINOR

    1. OCPN_API_VERSION_MAJOR/MINOR is now used in cmake/in-files/version.h.in

    2. In [pluginname_pi].cpp

      • Several lines must change from MY_API_VERSION_MAJOR/MINOR to

        • EG: "return OCPN_API_VERSION_MAJOR;"

        • EG: "return OCPN_API_VERSION_MINOR;"

      • Find wxString (pluginname_pi)::GetCommonName() and change

        • return _("(pluginname-pi)"); to

        • return _T(PLUGIN_COMMON_NAME);

    3. In the file (plugin_pi).h

      • Several lines must be commented out.

        • // #define MY_API_VERSION_MAJOR 1

        • // #define MY_API_VERSION_MINOR 16

        • or removed.

        • because new values definitions are defined in cmake/in-files/version.h.in

Adapt Plugin

There will be additional changes needed to adapt your plugin to the template. Some of this is related to changes in the API or the ways of handling things. Please see Adapt Plugin for more information that is available about specific changes.

Process

  1. Cmake Files are somewhat generic, but often can be plugin specific, depending on the plugin.

  2. Review the cmake.save files one by one with the new ones and make necessary adjustments.

  3. Configuring this is not simple and requires knowledge about the plugin operation.

Test Build Locally

Note the errors and sequentially fix them one by one until the plugin compiles and builds. The try the plugin in Opencpn and test it. Get everythng working properly.

Get CI Script working

  1. Get the ci/environment scripts working on Circleci, Appveyor

Get Deployment working

  1. Get the uploads to Cloudsmith working.

    1. See Prequisite Services and Clousamirh Setup.

    2. Also join the OpenCPN Organization as a member of the Plugins Team.

EDIT EDIT CHECK THE TEXT BELOW WITH THE ABOVE BELOW IS MORE CURRENT

Posssible Addditions

1. Get setup locally.

  1. From local <plugin> master branch git checkout -b master-cmake

  2. From remote online github Testplugin repository master branch make a PR from jongough master and merge it.

  3. Locally using bash prompt cd documents/github/testplugin_pi then git pull origin master to update

  4. Locally in bash cd watchdog_pi make sure you are in master-cmake branch

  5. Locally using WinMerge open a comparison between testplugin_pi and watchdog_pi

  6. Now you are ready to update frontend2 to be current. copy these folder and files to the plugin from Testplugin_pi

  7. Directories & files to copy from Testplugin--→plugin to be identical.

  8. Folders identical to testplugin - circleci, buildosx, buildwin, ci, cmake, mingw, extinclude, extsrc

  9. Folders for testplugin only (don’t copy) - include, (actually there is one android datectrl.h file)

  10. Folders that are different/not exist in watchdog (Different) build, data, src (Not existing) forms, ocpninclude

  11. ocpninclude - Many ocpn_draw files. I don’t believe we need this folder.

  12. Did the GL folder go to libs/GL?

  13. I see that ocpn_plugin.h, msvc/opencpn.lib and mingw/libopencpn.dll.a landed in libs/ocpn-api so I can delete the api-16 directory.

  14. Texfont.h is in src/ folder.

  15. Don’t see pluginmanager.h anywhere, is it needed?

  16. How to instruct other Plugin Devs about the paths for these changes?

  17. Watchdog_pi uses ocpn_draw for boundaries.

  18. libs (renamed from lib) - copy over all folders leaving existing folders (nmea0183 and bzip2).

  19. mingw identical

  20. modules for watchdog documentation..

  21. ocpninclude -not needed. (Tried copying all files to wd to fix TexFont.cpp issues - it did not fix it)

  22. ocpnsrc - copied over, is it needed? Has glu and Texfont.cpp

  23. po - different

  24. src - different

  25. ui -different

  26. adding buildandroid back in but it is old from bdbcat build and probably not needed.

  27. adding include/android/wx/datectrl.h back in but it is old from bdbcat and probably not needed.

  28. Files travis.yml, appveyor.yml should be copied.

  29. CMakeLists.txt will vary and should be changed appropriately to build.