OpenCPN

Compiling on Windows

5.8.0+ Fast Track

From version 5.8.0 the windows build system has been revised. The fast track described here is simplified and without all the options provided by the procedure described from next section. To set up a complete directly usable local development environment, you should probably prefer the workflow implemented by the winConfig.bat script described in the next chapter.

Steps to to make a build:

  1. Get Visual Studio Community 2022, either the command line tools or the complete environment, from visualstudio.microsoft.com/vs/community/

  2. Install the choco package manager, chocolatey.org/install

  3. Clone the sources and move into them:

    > git clone https://github.com/OpenCPN/OpenCPN.git
> cd OpenCPN

  4. Run the script buildwin\win_deps.bat. First time script installs programs and should be invoked with administrative privileges using the Visual Studio Command Line Interface. Following runs can (i. e., should) be run as a regular user.

  5. Run the script ci\appveyor.bat. This will configure the project using cmake and make an initial build.

After the first build, new builds can be done using in the build directory using:

    > cmake --build . --target opencpn --config Release

Notes:

  • --target opencpn creates the main executable. Other targets which can be built include

    • --target opencpn-cmd — Command line tool

    • --target opencpn-glutil — Command line tool for testing OpenGL capabilities of the system (The opencpn-glutil.exe build product is required in the runtime folder for OpenGL to work)

    • --target tests — Command line unit tests

    • --target package — NSIS installer

  • It is perfectly possible to use --config Debug to create an executable with debugging symbols etc. However, doing so will make the plugins in the catalog incompatible as it is not possible to load optimized libraries into an opencpn debug build. Prefer RelWithDebInfo configuration in most cases.

  • win_deps.bat stores files in the cache directory. This can be removed safely, it is re-created from scratch by win_deps.bat

  • The correct options to invoke cmake manually can be found in ci\appveyor.bat

  • Both win_deps.bat and appveyor.bat are used in the ci builds and should thus be reasonably tested. However, user environment (in particular PATH)) can make them fail.

Complete builds using Visual Studio 2022 Community Edition or Visual Studio 2019 Community Edition

The steps here describe an alternative to the "Fast Track" scenario above. It is much simpler to make a complete build in Visual Studio, including full source debugging with Intellisense®.

Quick start:

From the Windows Desktop open x86 Native Tools Command Prompt for VS 2022 (or 2019). Then enter these 4 commands:

$ git clone https://github.com/opencpn/opencpn
$ cd opencpn
$ .\buildwin\winConfig.bat
$ .\build\opencpn.sln

This one-time procedure takes about 10 minutes on a 12-processor Windows 11 computer. When Visual Studio opens, select the desired build configuration (Debug or RelWithDebInfo) and you are ready to edit and build. Click the "Local Windows Debugger" button in Visual Studio to build and run OpenCPN in the VS debugger.

Here are more details with explanations of each step.

  1. Install Visual Studio 2022 Community Edition visualstudio.microsoft.com/downloads/. Be sure to select components:

    • Desktop development with C++

    • C++ CMake tools for windows

  2. Install git for Windows: git-scm.com/download/win

  3. Open x86 Native Tools Command Prompt for Visual Studio 2022

  4. Create folder where you want to work with OpenCPN sources, something like this:

    $ mkdir \Users\myname\projects
$ cd \Users\myname\projects

  5. Clone Opencpn, for example:

    $ cd \Users\myname\projects
$ git clone https://github.com/opencpn/opencpn

  6. Configure and build OpenCPN then open solution file in Visual Studio:

$ cd opencpn
$ .\buildwin\winConfig.bat --debug --relwithdebinfo
$ .\build\opencpn.sln

Now you can browse the code, run & debug OpenCPN from Visual Studio. Select the desired build configuration (Debug, Release, etc.) and click the "Local Windows Debugger" button.

After you close Visual Studio and the command prompt you can return to Visual Studio using just 2 commands. From an x86 Native Tools Command Prompt run:

$ .\build\opencpn.sln

Notes:

  • Managed plugins are only supplied as Release builds. Thus, if you want to debug OpenCPN when any managed plugins are installed, you must debug OpenCPN in Release or RelWithDebInfo configurations.

  • If you build your own plugin in Debug configuration, then you can debug both OpenCPN and your plugin at the same time using the same Visual Studio Debug session. One possible plugin debug workflow is:

    • Build your plugin in debug configuration and create the tarball. Remember to include the .pdb file for your plugin in the tarball.

    • Open OpenCPN in debug mode using Visual Studio.

    • To step into your plugin set a breakpoint in plugin_loader.cpp at the point where it inits the plugins:

      pic->m_cap_flag = pic->m_pplugin->Init();

    • Import your plugin tarball using the plugin manager. When you step into your plugin you will see the source code and can set other breakpoints anywhere in your plugin.

  • You can use msbuild as the command line builder instead of CMake. The reasons for doing so are:

    • msbuild is faster than CMake or CMake w/Ninja

    • msbuild gives full access to every type of build and project

  • We also recommend installing the latest powershell version. It is more powerful and visually friendly. Install like this:

    $ winget install --id Microsoft.Powershell --source winget

  • It is important to have a 'clean' environment.

    • Make sure there are no permanent environment variables related to wxWidgets (these all begin with WX). If you have any it is safe to delete them.

    • Remove all references to wxWidgets from the permanent PATH environment variables.

    • It is ok to install tools such as NSIS but not required. Any tools required to build or package will be automatically installed by the 'buildwin\winConfig.bat' script.

    • The 'winConfig.bat' script does not install Visual Studio. Neither does it install tools such as git or npm as these are not used by the build system.

  • The 'winConfig.bat' script sets up 4 folders beneath the 'build' folder that house 4 different runtime configurations based on the 4 standard build types. Since each configuration is a standalone local instance of OpenCPN, they have to be run in 'portable' mode. To manually launch a particular configruation (e.g. RelWithDebInfo) set the working folder to OpenCPN\build\RelWithDebInfo then launch OpenCPN in portable mode. For example:

    $ cd OpenCPN
$ .\buildwin\configdev.bat --debug --relwithdebinfo
$ cd .\build\relwithdebinfo
$ .\opencpn -p

  • The full list of command line options are as follows:

     --release          Initialize/build Release configuration
 --relwithdebinfo   Initialize/build RelWithDebInfo configuration
 --minsizerel       Initialize/build MinSizeRel configuration
 --debug            Initialize/build Debug configuration
 --all              Initialize/build all 4 configurations (default)
 --help             Print help text
 --Y                Non-interactive mode (for calling from a script)
 --clean            Delete and reinitialize the build folder
 --rebuild          Rebuild all build types
 --package          Create installer package for each built configuration
 --wxver vn.n[.n]   Build specified version of wxWidgets sources.
                    Note: This is a tag or branch name.

Notes on options:

  • After the first time you initialize a configuration the script remembers which build configurations were selected and only builds those. You can add additional configurations later simply by running the script again with just the desired configuration switch(s).

  • The exception is the --clean option. It purposely does not remember which configurations were previously selected. Therefore, if you do not accompany --clean with selection of configuration options, it will initialize all 4 configurations. This feature allows one to chose a different set of configurations than the first time. So --clean is basically the same as a first time run except it will save the runtime data for all existing configs and restore when a particular configuration (debug, release, etc.) is initialized. The --clean option can be used to up or down size the build tree to just the configurations you are interested in at the moment.

  • Remember, do not try to build a configuration you did not create initially with this script. The results will not run or be useful in any meaningful way. This is why it defaults to all 4 configuration types initially.

  • Use the --package option to build installer packages. The installer will be found in the folder named for each built configuration type (.\build\Release, .\build\Debug, etc.)

Example usage:

  • Useful msbuild command line examples follow. Type these commands after running '.\buildwin\configdev.bat' from the root opencpn git managed folder.

    • Clean and build debug OpenCPN project

      $ cd build
$ msbuild /m -t:Rebuild -p:Configuration=Debug opencpn.sln

    • Build Release version of the installer package

      $ cd build
$ cmake -DCMAKE_INSTALL_PREFIX:STRING="C:/Program Files (x86)/OpenCPN" ..
$ msbuild /v:m /m -p:Configuration=Release PACKAGE.vcxproj
$ cd ..
$ .\buildwin\winconfig

    • Clean and build every project as a Release build with debug info

      $ cd build
$ msbuild /m -t:Rebuild -p:Configuration=RelWithDebInfo All_BUILD.vcxproj

    • Build debug version of OpenCPN core

      $ cd build
$ msbuild /m -t:Build -p:Configuration=Debug opencpn.vcxproj

    • Clean opencpn-cmd.exe

      $ cd build
$ msbuild /m -t:Clean -p:Configuration=Debug opencpn-cmd.vcxproj

    • Clean and build debug configuration of chart downloader plugin

      $ cd build
$ msbuild /m -t:Rebuild -p:Configuration=Debug plugins\chartdldr_pi\chartdldr_pi.vcxproj

  • You can also use CMake if you like.

    • This example will clean and build a Release installer package. When finished, restores the environment back to local building mode.

      $ cd build
$ cmake -DCMAKE_INSTALL_PREFIX:STRING="C:/Program Files (x86)/OpenCPN" ..
$ cmake --build . --config Release --clean-first --target Package
$ cd ..
$ .\buildwin\winconfig

    • This example will build a Windows installer executable with debug configuration. This can be useful to find otherwise hidden debug asserts.

      $ cd build
$ cmake -DCMAKE_INSTALL_PREFIX:STRING="C:/Program Files (x86)/OpenCPN" ..
$ cmake --build . --clean-first --config Debug --target Package
$ cd ..
$ .\buildwin\winconfig

    • Note: Plugins built for a non-debug configuration will not load in a debug build configuration build.

  • It is possible to attach the Visual Studio debugger to a running instance. This is useful if you create an installer, install and run OpenCPN from the start menu. Once OpenCPN is running in its native enviroment the Visual Studio debugger can attach itself to the running instance. Find Attach to process…​ under the Debug menu item.