Skip to content

Build Labrador

This page, Run the minimal sample and Start your own project are the route for people who use Git. If you have the starter project, you already have everything they make and can go straight to Make a first change.

On this route you build Labrador on its own first. That proves the tools work before your own project adds anything, and it builds the samples you will look at next. It needs Git, from step 2 of Install the tools.

Every command on this page runs in the x64 Native Tools Command Prompt from Install the tools, one box at a time, in order.

  1. Clone the repository into your projects folder. This downloads Labrador into a new folder, C:\dev\Labrador, and moves the prompt into it:

    Terminal window
    cd /d C:\dev
    git clone https://github.com/matt439/Labrador.git
    cd Labrador

    Git prints a few lines counting objects and ends with Resolving deltas: 100% and done.; the prompt then ends C:\dev\Labrador>. If Git says destination path 'Labrador' already exists and is not an empty directory, you have cloned it before: run only the last line, cd Labrador, and carry on.

    The clone is on master, which can be ahead of v0.4.0, the release these pages describe. This puts it on that release, so that what you build is what they say:

    Terminal window
    git checkout v0.4.0

    It prints a note that begins Note: switching to 'v0.4.0'. and ends HEAD is now at followed by a commit. That is expected.

  2. Configure the build:

    Terminal window
    cmake --preset x64-debug

    A preset is a named configuration in the repository’s CMakePresets.json. x64-debug is a 64-bit debug build using the Direct3D 11 renderer, with its output in out\build\x64-debug.

    The first time you run this, vcpkg downloads and builds Labrador’s dependencies: DirectX Tool Kit and the DirectXMath library it uses, the XAudio2 redistributable, the doctest test framework and the lodepng image library. With nothing cached, the first configure downloads about 330 MB in all. On a fast desktop with an empty cache that configure took 2 minutes 17 seconds, 1.2 minutes of it vcpkg building seven packages, and vcpkg keeps the results, so later configures are quick. A slower machine can take much longer; leave the window alone until the prompt comes back. The whole build folder, out, comes to about 1.3 GB once the next two steps have run.

    Before building those libraries, vcpkg checks the tools it uses. It may download its own CMake and PowerShell 7 even though cmake --version worked: its package cache depends on specific tool versions, and Visual Studio does not install PowerShell 7. Lines like these announce normal tool downloads, rather than a failure to configure the build:

    Example output, 13 November 2026
    A suitable version of cmake was not found (required v4.3.2).
    A suitable version of powershell-core was not found (required v7.5.4).

    Those examples came from Visual Studio 2026's bundled vcpkg on 13 November 2026. That run downloaded about 53 MB of CMake and 117 MB of PowerShell. Other Visual Studio or vcpkg versions can select different tools and print different versions or an order unlike this example. A clean Windows Sandbox run that day fetched CMake 4.4.3, PowerShell 7.6.6 and 7-Zip 26.03; a tool's downloaded version can exceed the minimum the message names.

    Keep vcpkg's default tool selection. You do not need to install PowerShell 7 separately or change a setting to force system tools. Let the downloads finish and check for the finalConfiguring done and Generating done lines below. Later configures reuse the downloaded tools and built libraries while their caches remain available.

    It has worked when the last lines are these, with your own folder in the last one:

    Output
    -- Configuring done
    -- Generating done
    -- Build files have been written to: C:/dev/Labrador/out/build/x64-debug

    CMake also prints a time in brackets after each done. If it ends with Configuring incomplete, errors occurred! instead, find the first line that says Error and look it up under If something fails below.

  3. Build it:

    Terminal window
    cmake --build --preset x64-debug

    This builds the engine, all six samples, the tests and the benchmarks, which took 21 seconds on the same desktop. Ninja numbers each step as it goes, such as [57/326], and a build that worked stops at the last number with no line saying FAILED; your total may differ. Warnings are errors in every Labrador build, so a successful build has none.

  4. Run the tests:

    Terminal window
    ctest --preset x64-debug

    Eighteen test programs, the minimal and collision samples’ start-up checks and the benchmarks run, and ctest should report 100% tests passed, 0 tests failed out of 21. One of them, RenderPixelTests, draws real frames through Direct3D and compares them with reference images, so a pass also tells you the renderer works on your machine.

A new command prompt starts in its own folder, not in Labrador. Each time you open the x64 Native Tools Command Prompt to carry on, go back to the folder first:

Terminal window
cd /d C:\dev\Labrador

Then run the step you want. The build only recompiles what changed, so running the build and test lines again is always safe.

The build folder remembers how it was configured. After a configure failed, or after you change something it depends on, such as VCPKG_ROOT, the folder the project is in, or which prompt you use, delete the build folder and configure again. From the Labrador folder:

Terminal window
rmdir /s /q out\build\x64-debug
cmake --preset x64-debug
cmake --build --preset x64-debug

rmdir /s /q deletes the folder and everything in it without asking, so check that the prompt ends Labrador> before you run it. It deletes only what the build made; vcpkg keeps what it downloaded elsewhere, so the configure after it is quicker than the first one was. For another preset, put its name in place of x64-debug in all three lines.

The x64-* presets are available only when CMake runs on Windows. The wasm-* presets have no host restriction. On Linux they have been built once, on WSL 2 Ubuntu, where vcpkg also needed zip, unzip and pkg-config and the tests that need no browser passed; no CI job builds there, and building them on macOS is unverified. They still require the browser toolchain. There is no native Linux or macOS window implementation; Platform support states the supported targets and the port plans.

The repository has a debug and a release preset for each renderer. Swap the preset name in all three commands to use one:

Preset Renderer
x64-debug, x64-release Direct3D 11
x64-debug-d3d12, x64-release-d3d12 Direct3D 12
x64-debug-gl, x64-release-gl OpenGL 3.3
x64-debug-vulkan, x64-release-vulkan Vulkan, which needs the Vulkan SDK
x64-debug-null, x64-release-null None: records what it was asked to draw, for testing on machines without a graphics card

The renderer is chosen when you configure rather than when the game starts. Asking for one that was not built is a link error, not a crash on the first frame. A game you ship is built with one renderer too: Which renderer to ship recommends Direct3D 11 and says what a machine that refuses it shows.

Troubleshooting has more messages, each with what it means and how to get past it.

Documentation for Labrador v0.4.0. Built from Labrador f525bc6 of 2026-11-17.

All documentation versions