= 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:

. Standard CMake variables, documented in https://cmake.org/documentation/[],
often but not always with a CMAKE_ prefix.
. 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_`.
. 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.
