Building for Windows

This document describes the process to build Ocean for Windows. It covers:

1. General requirements
2. Building required third-party libraries
3. Building Ocean

1 Prerequisites

• General prerequisites listed on the main page
• Python 3.10 or higher, plus the build scripts' dependencies: pip install -r build/python/requirements.txt
• Visual Studio 2019 or later is required (2022 recommended). The build system will auto-detect the newest installed version.

Enabling Long Path Support (Highly Recommended)

Windows traditionally has a 260-character path limit (MAX_PATH). Ocean's build process can generate deeply nested paths that may exceed this limit. It is highly recommended to enable Long Path support before building.

To enable Long Path support, run this command in an elevated (Administrator) PowerShell:

Set-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1

Alternatively, use the Group Policy Editor: 1. Open gpedit.msc 2. Navigate to: Computer Configuration > Administrative Templates > System > Filesystem 3. Enable: "Enable Win32 long paths"

A system restart may be required after enabling this setting.

Note: The build system will automatically check for Long Path support and display a warning if it is not enabled.

2 Building the third-party libraries

The third-party libraries are built using the Python-based build system. The same script works from PowerShell, Command Prompt, or Git Bash.

cd \path\to\ocean

# Build for every target this host supports (debug + release, static + shared)
python build/python/build_ocean_3rdparty.py

# Build for every Windows architecture the selected Visual Studio supports
python build/python/build_ocean_3rdparty.py --target win

# Build for one specific architecture
python build/python/build_ocean_3rdparty.py --target win_x86_64

# Build release only, static only
python build/python/build_ocean_3rdparty.py --config release --link static

# Use a specific Visual Studio version
python build/python/build_ocean_3rdparty.py --vs-version 2022

# Include optional libraries (e.g., OpenCV)
python build/python/build_ocean_3rdparty.py --with opencv

# Show build plan without building
python build/python/build_ocean_3rdparty.py --dry-run

It is advisable to place build and install directories as close to the root of a filesystem as possible, due to Windows limitations on path lengths:

python build/python/build_ocean_3rdparty.py --output-dir C:\ocean_3rdparty

Once the build is complete, the installed libraries can be found in ocean_3rdparty/install/ (or the custom output directory). Each library is a complete, relocatable CMake install prefix at <target>/<library>/, for example win_x64_vc143_static/zlib/include/zlib.h and win_x64_vc143_static/zlib/lib/zlib.lib. The target name carries the MSVC toolset (vc143 for Visual Studio 2022, vc145 for 2026); release targets have no suffix and debug targets add _debug.

Passing --for-external-integration produces a different, flattened layout intended for non-CMake build systems, with headers shared across architectures: <library>/h/win/ and <library>/lib/<target>/.

On Windows, the default is to build both static and shared libraries. ARM64 targets use arm64 in place of x64.

Run python build/python/build_ocean_3rdparty.py --help to see all available options.

Note: The build system displays a real-time TUI with progress for all parallel build jobs. Use --log-level verbose to see detailed build output instead.

3 Building Ocean

Ocean is built using a Python build script that invokes CMake with the correct configuration.

Using the Build Script (Recommended)

cd \path\to\ocean

# Build Ocean using the Python 3P layout
python build/python/build_ocean.py
# Build for a specific configuration
python build/python/build_ocean.py --config release

# Use a specific Visual Studio version
python build/python/build_ocean.py --vs-version 2022

# Specify custom directories
python build/python/build_ocean.py `
    --build-dir C:\build_ocean `
    --install-dir C:\install_ocean `
    --third-party-dir C:\ocean_3rdparty\install

# Show build plan without building
python build/python/build_ocean.py --dry-run

Once the build is complete, the compiled binaries can be found in ocean_install/win_x64_vc143_static (release) and .../win_x64_vc143_static_debug (or win_arm64_vc143_static* for ARM64 targets; the vcNNN component follows the Visual Studio version in use).

Run python build/python/build_ocean.py --help to see all available options.

Using CMake Directly

Alternatively, you can invoke CMake directly:

cd \path\to\ocean

# Configure
cmake -S . -B build_win -G "Visual Studio 17 2022" -A x64 `
    -DCMAKE_BUILD_TYPE=Release `
    -DBUILD_SHARED_LIBS=OFF `
    -DOCEAN_THIRD_PARTY_ROOT=.\ocean_3rdparty\install `
    -DCMAKE_INSTALL_PREFIX=.\ocean_install\win_x64_vc143_static

# Build and install. Visual Studio is a multi-config generator, so --config must
# repeat the configuration; without it MSBuild builds Debug against the release
# libraries, which links and then fails at startup on a runtime mismatch.
cmake --build build_win --config Release --target install

-A selects the target architecture (x64, ARM64 or Win32) and must match the third-party libraries you built. Change -G to target another Visual Studio version, for example "Visual Studio 18 2026"; the toolset it implies (vc143, vc145) is part of the third-party directory name.

Building with Visual Studio

To open the project in Visual Studio after configuration:

# Configure the project
python build/python/build_ocean.py --configure-only

# Open in Visual Studio
start ocean_build\win_x64_vc143_static\ocean.sln

Then build and run the desired targets from within Visual Studio.