OpenCPN

CMake Usage and Options

General

OpenCPN is configured using cmake. The build is done out-of-tree according to

mkdir build
cd build
cmake [Options] ..
build command

The build command part is platform dependent whereas the rest is identical on all platforms.

The Options part refers to various CMake parameters. They are too many to be documented, this documentation just mentions a few. The best way to get an overview over the available options is to invoke ccmake which displays a comprehensive list of all options, their current values and a short help string.

The goal is that all options should have sane default values, and that a basic build should work without using any of them.

Three kind of options are heavily used by OpenCPN:

  1. Standard CMake variables, documented in https://cmake.org/documentation/, often but not always with a CMAKE_ prefix.

  2. OpenCPN specific variables, often with a OCPN_ prefix. Documented in the code which can be viewed using ccmake or something like cmake -LH | grep -B1 OCPN_.

  3. wxWidgets-specific options with a wxWidgets_ prefix, documented in https://cmake.org/cmake/help/latest/module/FindwxWidgets.html

Build Type — CMAKE_BUILD_TYPE

The default build type is RelWithDebInfo. A common alternative is Debug.

Installation paths

Since 5.0.0 OpenCPN supports the GNU install paths, see https://cmake.org/cmake/help/v3.0/module/GNUInstallDirs.html

CMAKE_INSTALL_PREFIX governs the path where files are installed in thei installation package. Default is platform-dependent. It’s not uncommon to change this to some other location.

Use CMAKE_INSTALL_LIBDIR to change the base directory for plugins; defaults to library location on most platforms, but is 'lib' on Debian.

Include git data in package name — OCPN_CI_BUILD

By default off. If enabled, makes latest git commit part of generated installation files; simplifies when having several test builds.

Explicit target specification — OCPN_TARGET_TUPLE

OpenCPN is built for a combination of operating system and hardware. This is crucial to determine if a plugin is compatible with the main OpenCPN program or not.

On most targets this is computed automatically. In some situations, notably when cross-compiling, this is not possible and must be set in this option. The syntax is target;version;arch like flatpak;20.08;aarch64 or debian:11:x86_64

Use system libraries — OCPN_USE_BUNDLED_LIBS

OpenCPN bundles some libraries which can be found also as system libraries on for example Linux. This option governs whether the bundled libs should be used (OCPN_USE_BUNDLED_LIBS=ON) or the system ones (OCPN_USE_BUNDLED_LIBS=OFF). It can also be set to a comma-separated list of libraries for which the bundled libs should be used. Only code can tell which libraries, though.

Bundled documentation

The package can be built without bundling any documentation using OCPN_BUNDLE_DOCS=OFF. This has the benefit of a considerably smaller package.

Also, unfortunately current documentation is non-free in the open-source sence since the sources are not available for technical reasons. Thus, using OCPN_BUNDLE_DOCS=OFF avoids bundling non-free stuff in generated package

The documentation is available as a separate download from https://www.opencpn.org for installations built without the bundled docs.

Current and Tide Data — TCDATA

Bundling this data is governed by the OCPN_BUNDLE_TCDATA parameter, a boolean. By bundling it the need to install separate tcdata packages can be avoided.

Shoreline World Wide Background Chart — GSHHS

If enabled, the boolean option OCPN_BUNDLE_GSHHS bundles the crude GSHHS data. To use more detailed higher levels the chartdldr plugin is always available for user.

Sound

  • On Android the native AndroidSound backend is always used.

  • On Windows, the MswSound backend is the default. OCPN_ENABLE_SYSTEM_CMD_SOUND can be used to use the SystemCmdSound backend, OCPN_ENABLE_PORTAUDIO to enable possible existing portaudio.

  • On Linux, portaudio is used if found, else SystemCmdSound. OCPN_ENABLE_PORTAUDIO can be used to disable portaudio, and OCPN_ENABLE_SYSTEM_CMD_SOUND to disable SystemCmdSound in which case the wxWidgets wxSound backend is used.

  • MacOS works basically as Linux, but portaudio is normally not available

  • On all platforms OCPN_SOUND_CMD can be used to preset the command used in SystemCmdSound. The default is computed by probing the build host for commands like aplay, afplay or omxplayer.