DHIVA LABS · LEARN

Appearance

Beginner guide ​

In about ten minutes you write a five-line C program on Linux, build it into a Windows .exe with WinBridge, and run that .exe without touching a Windows machine.

What cross-compiling is ​

A compiler turns source code into a program for one kind of system. Normally it builds for the system it runs on: compile on Linux, get a Linux program.

Cross-compiling means building on one system for a different one. Here the compiler runs on Linux but writes a Windows program: a file in the PE format that Windows uses, usually ending in .exe. Linux cannot start that file directly, and Windows cannot start a Linux program.

Each language has its own way to cross-compile, with its own flags and extra tools. WinBridge hides those differences: it detects the project type, calls the right compiler with the right settings, and checks that the output really is a Windows executable.

What you need ​

  • WinBridge installed. See Install.
  • An internet connection for two downloads: the Zig compiler (56 MB) and, in the last part, the Wine runtime (about 94 MB).

You do not need a C compiler installed. WinBridge fetches one into your home folder.

Build your first Windows program ​

  1. See what WinBridge can use on your machine.

    bash
    winbridge doctor

    Look at the Installable components section. It lists what WinBridge can download for you and how large each download is. Under Toolchains, a line starting with MISSING names a tool that a toolchain needs and that is not installed.

  2. Install the Zig compiler.

    bash
    winbridge doctor --install zig

    WinBridge uses Zig as its C and C++ cross-compiler. It is downloaded, checked against a checksum, and unpacked into ~/.cache/winbridge/toolchains/. No sudo is involved.

  3. Create a project folder with one source file.

    bash
    mkdir hello
cd hello

    Save this as main.c in the hello folder:

    c
    #include <stdio.h>

int main(void) {
    printf("hello from winbridge\n");
    return 0;
}

  4. Ask WinBridge what it sees.

    bash
    winbridge detect

    The answer names the project (hello, after the folder), its type (C/C++), the file that decided it (main.c) and the toolchain that would build it (c). Nothing is built yet.

  5. Build it.

    bash
    winbridge build

    WinBridge prints Building hello (C/C++) for windows-x64 with c, runs the compiler, checks the result, and ends with a line like Built hello for windows-x64 followed by the path and size of the file it made.

  6. Look at the result.

    bash
    ls build/winbridge/windows-x64/

    You see hello.exe. This is a 64-bit Windows program. You can copy it to a Windows PC and run it there.

Good to know

Build output always goes to build/winbridge/windows-x64/ inside the project folder, unless you pass --output. Compiler caches stay out of your project, under ~/.cache/winbridge/build/.

Run it on Linux ​

  1. Start the program with winbridge run.

    bash
    winbridge run build/winbridge/windows-x64/hello.exe

  2. Wait for the first-run setup.

    The first time, WinBridge downloads its Wine runtime into ~/.cache/winbridge/runtimes/ and prints Creating a new prefix for hello (first run takes a moment). Wine is a compatibility layer that lets Linux run Windows programs. A prefix is a private Windows environment for one app, with its own C: drive and registry.

  3. Read the output.

    The program prints:

    text
    hello from winbridge

    Run the same command again. This time it starts straight away, because the runtime and the prefix already exist.

Clean up ​

The prefix that winbridge run created is named after the executable. List what exists, then delete the one from this guide:

bash
winbridge prefix list
winbridge prefix delete hello

Deleting a prefix removes everything in that app's Windows environment. For this test program that is nothing you need.

What you learned ​

  • winbridge doctor shows which toolchains are ready, and winbridge doctor --install fetches a compiler without sudo.
  • winbridge detect reports the project type without building.
  • winbridge build produces a verified Windows .exe in build/winbridge/windows-x64/.
  • winbridge run starts a Windows program on Linux in its own prefix.

Next steps ​