openvpn/README.cmake.md

OpenVPN Builds with CMake
=========================

For Windows builds we do not use the autotools-based buildsystem that we use
for our Unix-like (Linux, BSDs, macOS, etc.) builds. Instead we added a
separate (CMake)[https://cmake.org/]-based buildsystem.

This buildsystem supports building for Windows both with MSVC (i.e. Visual
Studio) and MinGW. MinGW builds are also supported as cross-compile
from Linux.

The official builds, which are also available as CMake presets (see
`cmake --list-presets` and `CMakePresets.json`) all use
(VCPKG)[https://github.com/microsoft/vcpkg/#vcpkg-overview] for dependency
management. This allows us to do proper supply-chain management and
also makes cross-building with MinGW on Linux much simpler. However,
builds are also possible by providing the build dependencies manually,
but that might require specifying more information to CMake.

You need at least CMake version 3.21 or newer for the `CMakePreset.json`
file to be supported. Manual builds might be possible with older CMake
versions, see `cmake_minimum_required` in `CMakeLists.txt`.

If you're looking to build the full Windows installer MSI, take a look
at https://github.com/OpenVPN/openvpn-build.git .

MSVC builds
-----------

The following tools are expected to be present on the system, you
can install them with a package manager of your choice (e.g.
chocolatey, winget) or manually:

* CMake (>= 3.21)
* Git
* Python (3.x), plus the Python module `docutils`
* Visual Studion 17 (2022), C/C++ Enviroment

For example, to prepare the required tools with chocolatey, you
can use the following commands (Powershell):

    # Installing Chocolatey
    Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
    & choco.exe install -y git --params "/GitAndUnixToolsOnPath"
    & choco.exe install -y python
    & python.exe -m ensurepip
    & python.exe -m pip install --upgrade pip
    & python.exe -m pip install docutils
    & choco.exe install -y cmake --installargs 'ADD_CMAKE_TO_PATH=System'
    & choco.exe install -y "visualstudio2022buildtools"
    & choco.exe install -y "visualstudio2022-workload-vctools" --params "--add Microsoft.VisualStudio.Component.UWP.VC.ARM64 --add Microsoft.VisualStudio.Component.VC.Tools.ARM64 --add Microsoft.VisualStudio.Component.VC.ATL.Spectre --add Microsoft.VisualStudio.Component.VC.ATLMFC.Spectre --add Microsoft.VisualStudio.Component.VC.ATL.ARM64.Spectre --add Microsoft.VisualStudio.Component.VC.MFC.ARM64.Spectre --add Microsoft.VisualStudio.Component.VC.Runtimes.ARM64.Spectre --add Microsoft.VisualStudio.Component.VC.Runtimes.x86.x64.Spectre --quiet"
    & choco.exe install -y windows-sdk-10-version-2004-windbg

One or more restarts of Powershell might be required to pick up new additions
to `PATH` between steps. A Windows restart is probably required after
installing Visual Studio before being able to use it.
You can find the exact commands we use to set up the community build machines
at https://github.com/OpenVPN/openvpn-buildbot/blob/master/jenkins/windows-server/msibuild.pkr.hcl

To do a default build, assuming you are in a MSVC 17 2022 environment:

    mkdir C:\OpenVPN
    cd C:\OpenVPN
    git clone https://github.com/microsoft/vcpkg.git
    git clone https://github.com/OpenVPN/openvpn.git
    set VCPKG_ROOT=C:\OpenVPN\vcpkg
    cd openvpn
    cmake --preset win-amd64-release
    cmake --build --preset win-amd64-release
    ctest --preset win-amd64-release

When using the presets, the build directory is
`out/build/<preset-name>/`, you can find the output files there.
No install support is provided directly in OpenVPN build, take a look
at https://github.com/OpenVPN/openvpn-build.git instead.

MinGW builds (cross-compile on Linux)
-------------------------------------

To build the Windows executables on a Linux system:

    # install mingw with the package manager of your choice, e.g.
    sudo apt-get install -y mingw-w64
    # in addition to mingw we also need a toolchain for host builds, e.g.
    sudo apt-get install -y build-essential
    # minimum required tools for vcpkg bootstrap: curl, zip, unzip, tar, e.g.
    sudo apt-get install -y curl zip unzip tar
    # additionally vcpkg requires powershell when building Windows binaries.
    # See https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux
    # e.g.
    sudo apt-get install -y wget apt-transport-https software-properties-common
    wget -q "https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb"
    sudo dpkg -i packages-microsoft-prod.deb
    sudo apt-get update
    sudo apt-get install -y powershell
    # minimum required tools for build: cmake, docutils, git, ninja,
    # pkg-config, python e.g.
    sudo apt-get install -y cmake git ninja-build pkg-config python3 python3-docutils
    # additionally required to build pkcs11-helper: automake, autoconf,
    # man2html, e.g.
    sudo apt-get install -y automake autoconf man2html-base
    mkdir mingw
    cd mingw
    git clone https://github.com/microsoft/vcpkg.git
    git clone https://github.com/OpenVPN/openvpn.git
    export VCPKG_ROOT=$PWD/vcpkg
    cd openvpn
    # requires CMake 3.21 or newer
    cmake --preset mingw-x64
    cmake --build --preset mingw-x64
    # unit tests are built, but no testPreset is provided. You need to copy
    # them to a Windows system manually

The instructions have been verified on a Ubuntu 22.04 LTS system in a
bash shell, and might need adaptions to other Linux distributions/versions.

Note that the MinGW preset builds use the `Ninja multi-config` generator, so
if you want to build the Debug binaries, use

    cmake --build --preset mingw-x64 --config Debug

The default build is equivalent to specifying `--config Release`.

When using the presets, the build directory is
`out/build/mingw/<arch>`, you can find the actual output files in
sub-directories called `<buildtype>`.
No install support is provided directly in OpenVPN build, take a look
at https://github.com/OpenVPN/openvpn-build.git instead.

Unsupported builds
------------------

The CMake buildsystem also supports builds on Unix-like platforms. These builds
are sometimes useful for OpenVPN developers (e.g. when they use IDEs with
integrated CMake support). However, they are not officially supported, do not
include any install support and should not be used to distribute/package
OpenVPN. To emphasize this fact, you need to specify `-DUNSUPPORTED_BUILDS=ON`
to cmake to be able to use these builds.

The `unix-native` CMake preset is available for these builds. This preset does
not require VCPKG and instead assumes all build-dependencies are provided by
the system natively.

Generating compile_commands.json
--------------------------------

To have the CMake buildsystem generate compile_commands.json you can specify
`-DENABLE_COMPILE_COMMANDS=ON` on the command line or enable the CMake option
another way you like. For supported generators the file will then be created.
Additionally, the buildsystem will create a symlink `build/` to the --preset
build directory that contains the generated JSON file. This is done so that
clangd is able to find it.

Enabling this option may cause an error on Windows, since creating a symlink
is a privileged operation there. If you enable Developer Mode for the system,
symlinks can be created by regular users.