README.cmake.md

   1 OpenVPN Builds with CMake
   2 =========================
   3
   4 For Windows builds we do not use the autotools-based buildsystem that we use
   5 for our Unix-like (Linux, BSDs, macOS, etc.) builds. Instead we added a
   6 separate (CMake)[https://cmake.org/]-based buildsystem.
   7
   8 This buildsystem supports building for Windows both with MSVC (i.e. Visual
   9 Studio) and MinGW. MinGW builds are also supported as cross-compile
  10 from Linux.
  11
  12 The official builds, which are also available as CMake presets (see
  13 `cmake --list-presets` and `CMakePresets.json`) all use
  14 (VCPKG)[https://github.com/microsoft/vcpkg/#vcpkg-overview] for dependency
  15 management. This allows us to do proper supply-chain management and
  16 also makes cross-building with MinGW on Linux much simpler. However,
  17 builds are also possible by providing the build dependencies manually,
  18 but that might require specifying more information to CMake.
  19
  20 If you're looking to build the full Windows installer MSI, take a look
  21 at https://github.com/OpenVPN/openvpn-build.git .
  22
  23 MSVC builds
  24 -----------
  25
  26 The following tools are expected to be present on the system, you
  27 can install them with a package manager of your choice (e.g.
  28 chocolatey, winget) or manually:
  29
  30 * CMake
  31 * Git
  32 * Python (3.x), plus the Python module `docutils`
  33 * Visual Studion 17 (2022), C/C++ Enviroment
  34
  35 For example, to prepare the required tools with chocolatey, you
  36 can use the following commands (Powershell):
  37
  38     # Installing Chocolatey
  39     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'))
  40     & choco.exe install -y git --params "/GitAndUnixToolsOnPath"
  41     & choco.exe install -y python
  42     & python.exe -m ensurepip
  43     & python.exe -m pip install --upgrade pip
  44     & python.exe -m pip install docutils
  45     & choco.exe install -y cmake --installargs 'ADD_CMAKE_TO_PATH=System'
  46     & choco.exe install -y "visualstudio2022buildtools"
  47     & 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"
  48     & choco.exe install -y windows-sdk-10-version-2004-windbg
  49
  50 One or more restarts of Powershell might be required to pick up new additions
  51 to `PATH` between steps. A Windows restart is probably required after
  52 installing Visual Studio before being able to use it.
  53 You can find the exact commands we use to set up the community build machines
  54 at https://github.com/OpenVPN/openvpn-buildbot/blob/master/jenkins/windows-server/msibuild.pkr.hcl
  55
  56 To do a default build, assuming you are in a MSVC 17 2022 environment:
  57
  58     mkdir C:\OpenVPN
  59     cd C:\OpenVPN
  60     git clone https://github.com/microsoft/vcpkg.git
  61     git clone https://github.com/OpenVPN/openvpn.git
  62     set VCPKG_ROOT=C:\OpenVPN\vcpkg
  63     cd openvpn
  64     cmake --preset win-amd64-release
  65     cmake --build --preset win-amd64-release
  66     ctest --preset win-amd64-release
  67
  68 When using the presets, the build directory is
  69 `out/build/<preset-name>/`, you can find the output files there.
  70 No install support is provided directly in OpenVPN build, take a look
  71 at https://github.com/OpenVPN/openvpn-build.git instead.
  72
  73 MinGW builds (cross-compile on Linux)
  74 -------------------------------------
  75
  76 To build the Windows executables on a Linux system:
  77
  78     # install mingw with the package manager of your choice, e.g.
  79     sudo apt-get install -y mingw-w64
  80     # in addition to mingw we also need a toolchain for host builds, e.g.
  81     sudo apt-get install -y build-essential
  82     # minimum required tools for vcpkg bootstrap: curl, zip, unzip, tar, e.g.
  83     sudo apt-get install -y curl zip unzip tar
  84     # additionally vcpkg requires powershell when building Windows binaries.
  85     # See https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux
  86     # e.g.
  87     sudo apt-get install -y wget apt-transport-https software-properties-common
  88     wget -q "https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb"
  89     sudo dpkg -i packages-microsoft-prod.deb
  90     sudo apt-get update
  91     sudo apt-get install -y powershell
  92     # minimum required tools for build: cmake, docutils, git, ninja,
  93     # pkg-config, python e.g.
  94     sudo apt-get install -y cmake git ninja-build pkg-config python3 python3-docutils
  95     # additionally required to build pkcs11-helper: automake, autoconf,
  96     # man2html, e.g.
  97     sudo apt-get install -y automake autoconf man2html-base
  98     mkdir mingw
  99     cd mingw
 100     git clone https://github.com/microsoft/vcpkg.git
 101     git clone https://github.com/OpenVPN/openvpn.git
 102     export VCPKG_ROOT=$PWD/vcpkg
 103     cd openvpn
 104     cmake --preset mingw-x64
 105     cmake --build --preset mingw-x64
 106     # unit tests are built, but no testPreset is provided. You need to copy
 107     # them to a Windows system manually
 108
 109 The instructions have been verified on a Ubuntu 22.04 LTS system in a
 110 bash shell, and might need adaptions to other Linux distributions/versions.
 111
 112 Note that the MinGW preset builds use the `Ninja multi-config` generator, so
 113 if you want to build the Debug binaries, use
 114
 115     cmake --build --preset mingw-x64 --config Debug
 116
 117 The default build is equivalent to specifying `--config Release`.
 118
 119 When using the presets, the build directory is
 120 `out/build/mingw/<arch>`, you can find the actual output files in
 121 sub-directories called `<buildtype>`.
 122 No install support is provided directly in OpenVPN build, take a look
 123 at https://github.com/OpenVPN/openvpn-build.git instead.
 124
 125 Unsupported builds
 126 ------------------
 127
 128 The CMake buildsystem also supports builds on Unix-like platforms. These builds
 129 are sometimes useful for OpenVPN developers (e.g. when they use IDEs with
 130 integrated CMake support). However, they are not officially supported, do not
 131 include any install support and should not be used to distribute/package
 132 OpenVPN. To emphasize this fact, you need to specify `-DUNSUPPORTED_BUILDS=ON`
 133 to cmake to be able to use these builds.
 134
 135 The `unix-native` CMake preset is available for these builds. This preset does
 136 not require VCPKG and instead assumes all build-dependencies are provided by
 137 the system natively.