DHIVA LABS · LEARN

Appearance

Build C and C++ projects ​

WinBridge compiles C and C++ source files into a Windows .exe with Zig or MinGW-w64. When you need Microsoft's own ABI, a second toolchain builds with clang against the Windows SDK.

What WinBridge compiles ​

WinBridge treats a folder as a C/C++ project when it holds a CMakeLists.txt, a Makefile, or files ending in .c, .cpp, .cc or .cxx.

It then compiles the source files it finds in two places: the project folder itself and its src/ subfolder. All of them are compiled and linked into one executable named after the folder.

WARNING

WinBridge does not run CMake or Make. A project that only builds through its CMakeLists.txt or Makefile (several targets, generated files, sources in other subfolders) is not supported in version 0.4.0. The build stops with no direct C/C++ sources found when there is nothing in the project folder or src/ to compile.

Build with the default toolchain ​

The default toolchain has the id c. It prefers Zig and falls back to MinGW-w64.

  1. Get a compiler. Either one works.

    Zig, installed by WinBridge into your home folder (56 MB):

    bash
    winbridge doctor --install zig

    Or MinGW-w64 from your distribution. On Debian and Ubuntu:

    bash
    sudo apt install gcc-mingw-w64-x86-64 g++-mingw-w64-x86-64

  2. Build.

    bash
    winbridge build path/to/project

  3. Find the result in build/winbridge/windows-x64/ inside the project.

With Zig, WinBridge runs zig cc (or zig c++ when any C++ file is present) with -target x86_64-windows-gnu. With MinGW-w64 it runs x86_64-w64-mingw32-gcc or x86_64-w64-mingw32-g++. Release builds add -O2; --debug leaves it out.

Arguments after -- go to the compiler, placed before the source files. For example, to add an include folder and a preprocessor definition:

bash
winbridge build . -- -Iinclude -DNDEBUG

What an ABI is, and when it matters ​

An ABI (application binary interface) is the set of low-level rules compiled code follows: how functions are called, how C++ names are encoded, which runtime library is used. Code built for one ABI cannot always link with code built for another.

Windows has two common ones:

  • MinGW (GNU) ABI: what Zig and MinGW-w64 produce. No licence to accept, small downloads. This is WinBridge's default.
  • MSVC ABI: what Microsoft's Visual C++ compiler produces. You need it when you link a library that a vendor built with Visual C++, or when your code uses MSVC-specific extensions.

If neither of those applies to you, stay with the default.

Build for the MSVC ABI ​

The msvc toolchain compiles with clang in clang-cl mode against Microsoft's C runtime (CRT) and the Windows SDK. WinBridge never selects it on its own; you ask for it with --toolchain msvc.

WARNING

Installing the msvc component downloads 1–2 GB of headers and libraries from Microsoft's servers. They are covered by the Microsoft Software License Terms for Visual Studio. The install command prints a notice and then accepts those terms on your behalf. Read the licence terms first if that matters to you.

  1. Install clang and the LLVM linker from your distribution. WinBridge does not download them. On Debian and Ubuntu:

    bash
    sudo apt install clang lld

    WinBridge looks for the compiler as clang-cl, clang, clang-18 or clang-19, and for the linker as lld-link, lld-link-18, lld-link-19, ld.lld or lld.

  2. Install the Microsoft CRT and Windows SDK.

    bash
    winbridge doctor --install msvc

    This fetches a small tool called xwin (3 MB), then uses it to download the Microsoft files into ~/.cache/winbridge/xwin/.

  3. Build with the toolchain named.

    bash
    winbridge build path/to/project --toolchain msvc

If the SDK is not installed, the build stops with the Microsoft CRT and Windows SDK are not installed and shows the install command. It downloads nothing by itself.

Good to know

The WinBridge project states that the MSVC toolchain has not been verified end to end: its tests check the exact compiler command, but not a real link against the Windows SDK. Test the result on Windows before you rely on it.

See which toolchains can build a project ​

bash
winbridge --verbose detect path/to/project

For a C/C++ project the output names c as the toolchain. With --verbose it adds an also: line for msvc.

Next steps ​