C++ libraries linking

When we introduced static linking of C libraries, the promise was simple: name a .lib or .a archive in your #import, compile with -s, and ship one self-contained executable, no DLLs riding along, nothing to install on the target machine.

There was one big frontier left, and everyone saw it coming: the libraries people want most (vision, GUI, audio, machine learning) are written in C++. A C++ library is a very different animal to link: it brings global constructors, exceptions, RTTI, templates, thread-local storage, and an entire language runtime that expects to be wired up just so. Until now, that was the line where you switched back to DLLs.

That line is gone. The Red toolchain now statically links C++ libraries too (their runtime included) on every platform Red targets: Windows, Linux (x86 and ARM), and macOS.

The best part: nothing changes. It is the same import system and same compilation switch:

    red -r -s myapp.red

Libraries built with MSVC, GCC or clang are all accepted, in their native object formats.

What you need preinstalled

➤ Windows: for C++ libraries (or C code built against Microsoft's static runtime), install the free Visual Studio Build Tools with the "Desktop development with C++" workload. Just one installer, and Red locates everything by itself: no vcvarsall, no PATH, no environment variables. Plain C libraries still need nothing at all and that now extends to C libraries touching COM, DirectX or MediaFoundation: the GUID constants such code references ship inside the toolchain, so a fresh Windows 11 with only red-toolchain executable on it links them!

➤ Linux: the GNU runtime archives from your distribution's gcc packages (libstdc++.a, libgcc.a and friends) placed next to your library. If one is missing, the linker names exactly what it needs.

➤ macOS: nothing beyond the toolchain; the system C++ runtime binds automatically.

Some constraints

32-bit libraries for now, until the 64-bit toolchain is ready.

The imported surface must be C (extern "C", cdecl or stdcall), the same contract as any FFI, dynamic linking included. C++ classes and templates do their work inside the library; a thin C shim is required to exposes them to Red (most C++ libraries provide the shim). Keep exceptions inside too: a catch-all guard in each exported function is the pattern. See this wiki page on how to write shims.

No link-time-optimized objects, build libraries without /GL or -flto. Default Release settings are fine.

On Windows, build against the static runtime (/MT).

For comfort, bundle a library and its dependencies into one archive (lib.exe /OUT:foo-red.lib ... on Windows, an ar MRI script elsewhere), so your Red side stays a single #import line.

Examples

We have tested the Red toolchain new linking abilities with some of the most demanding C++ codebases around, built once and run on every platform:

➤ OpenCV5: a complete vision pipeline (filters, features, video decoding) in a single binary, with pixel-identical results on Windows, Linux and a Raspberry Pi.

You can download the C shim code from this direct link. The compiled opencv5c.lib file weights ~270MB. Here is the compilation log for Windows platform:

-=== Red Compiler 0.6.6 ===-

Compiling D:\Dev\opencv5-red\demo.red ...
...GUI backend      : native
...Modules          : View
...compilation time : 1258 ms

Target: Windows

Compiling to native code...
Static linking...
...linking          : opencv5c.lib
...linking (dep)    : libcpmt.lib
...linking (dep)    : libcmt.lib
...MSVC static CRT  : entry -> mainCRTStartup, Red start -> _main
...linking (dep)    : oldnames.lib
...linking (dep)    : uuid.lib
...linking (dep)    : libconcrt.lib
...linking (dep)    : mfuuid.lib
...linking (dep)    : strmiids.lib
...linking (dep)    : comsuppw.lib
...linking (dep)    : libvcruntime.lib
...linking (dep)    : libucrt.lib
...static-link time : 41582 ms
...compilation time : 40670 ms
...global words     : 25805 (78.44%)
...linking time     : 55281 ms
...output file size : 18767872 bytes
...output file      : D:\Dev\opencv5-red\demo.exe 

➤ llama.cpp: building a local LLM chat program in Red gives a ~5 MB standalone executable linking the llama.cpp library: around 40 tokens/s on a desktop, about 2 tokens/s on a RPI4. The C shim is available here (in this case,  just for convenience, it does a bit more than just wrapping the C++ API). The llm-demo code itself is available here.

> llm-demo Qwen3-1.7B-Q4_K_M.gguf "Give me one surprising fact about the color red."

model : models\Qwen3-1.7B-Q4_K_M.gguf
ctx   : 4096
prompt: Give me one surprising fact about the color red. /no_think

One surprising fact about the color red is that it is the **only color** that is
**not** associated with the word "red" in the English language. While red is
commonly associated with emotions like love, anger, and danger, it is not the word
"red" itself. Instead, the word "red" is derived from the Latin word *rubidus*,
which means "red" or "burning."
--- 90 tokens - 40.2 tok/s ---

➤ Dear ImGui: a Dear ImGUI wrapper in Red/System and a full widgets demo running at 60 fps, all linked into a single executable.

You can download the prebuilt signed Windows exe for this demo from this direct link.

Final thoughts

You can use coding agents to generate C shims for any C++ library you need. 

Please report libraries that fail to link in a red/red repo ticket, so we can see if the linker can be improved.

Have fun!