= Compiling on Windows
:hide-uri-scheme:

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

. Get Visual Studio Community 2026,  either the command line tools or the
  complete environment, from https://visualstudio.microsoft.com/vs/community/
. Install the choco package manager, https://chocolatey.org/install
. Clone the sources and move into them: +

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

. 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.
. 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 2026 Community Edition, 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(R).

Quick start:

From the Windows Desktop open _x86 Native Tools Command Prompt for VS_ (VS 2026), _x86 Native Tools Command Prompt for VS 2022_ (or 2019). Then
enter these 4 commands:
[,console]
----
$ 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-core 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.

. Install Visual Studio 2026 Community Edition
  https://visualstudio.microsoft.com/downloads/. Be sure to select components:
+
* [*] ```Desktop development with C++```
* [*] ```C++ CMake tools for windows```
+
. Install git for Windows: https://git-scm.com/download/win
. Open _x86 Native Tools Command Prompt for VS_ (or _x86 Native Tools Command Prompt for Visual Studio 2022_ if you use VS 2022)
. Create folder where you want to work with OpenCPN sources, something
   like this:
+
[,console]
----
$ mkdir \Users\myname\projects
$ cd \Users\myname\projects
----
+
. Clone Opencpn, for example:
+
[,console]
----
$ cd \Users\myname\projects
$ git clone https://github.com/opencpn/opencpn
----
+
. Configure and build OpenCPN then open solution file in Visual Studio:
[,console]
----
$ 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:
[,console]
----
$ .\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:
+
link:https://github.com/OpenCPN/OpenCPN/blob/b9e67db4b31cc1e75f22bc98d25925996974cb3b/model/src/plugin_loader.cpp#L757[`+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:
+
[,console]
----
$ 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:
+
[,console]
----
$ cd OpenCPN
$ .\buildwin\configdev.bat --debug --relwithdebinfo
$ cd .\build\relwithdebinfo
$ .\opencpn -p
----
+

* The full list of command line options are as follows:
+
[,console]
----
 --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
+
[,console]
----
$ cd build
$ msbuild /m -t:Rebuild -p:Configuration=Debug opencpn.sln
----
+
** Build Release version of the installer package
+
[,console]
----
$ 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
+
[,console]
----
$ cd build
$ msbuild /m -t:Rebuild -p:Configuration=RelWithDebInfo All_BUILD.vcxproj
----
+
** Build debug version of OpenCPN core
+
[,console]
----
$ cd build
$ msbuild /m -t:Build -p:Configuration=Debug opencpn.vcxproj
----
+
** Clean opencpn-cmd.exe
+
[,console]
----
$ cd build
$ msbuild /m -t:Clean -p:Configuration=Debug opencpn-cmd.vcxproj
----
+
** Clean and build debug configuration of chart downloader plugin
+
[,console]
----
$ 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.
+
[,console]
----
$ 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.
+
[,console]
----
$ 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.
