{"id":28857,"date":"2026-03-01T20:53:54","date_gmt":"2026-03-01T19:53:54","guid":{"rendered":"https:\/\/blog.mi.hdm-stuttgart.de\/?p=28857"},"modified":"2026-03-01T21:22:05","modified_gmt":"2026-03-01T20:22:05","slug":"building-a-modern-c-project-zig-webassembly-and-visual-ci-cd","status":"publish","type":"post","link":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/2026\/03\/01\/building-a-modern-c-project-zig-webassembly-and-visual-ci-cd\/","title":{"rendered":"Building a Modern C Project: Zig, WebAssembly, and Visual CI\/CD"},"content":{"rendered":"

How we used Zig as a build system, Emscripten for the web, and Python for automated visual regression testing on a C-based path tracer.<\/em><\/p>\n

1. Introduction<\/h3>\n

Writing a path tracer from scratch in C is a fantastic way to learn the physics of light simulation. But maintaining that project, ensuring it builds across platforms, catching memory leaks, deploying it to the web, and proving the math remains correct<\/strong> after every commit, is where the real engineering challenges begin.<\/p>\n

We built Tracy<\/strong><\/a>, a cross-platform, multi-threaded C11 path tracer<\/strong>. While constructing the path tracer itself caused its own challenges, this post isn\u2019t about the math of rendering but about the infrastructure surrounding it. Here is how we used reliable tools like Python to build a visual CI\/CD pipeline<\/strong>, while using the project as a sandbox to experiment with bleeding-edge, not quite production-ready tech: using Zig to replace CMake<\/strong>, and Emscripten to bring heavy, multi-threaded<\/strong> native code to the browser<\/strong>, along with the hard truths we learned along the way.<\/p>\n

2. Ditching CMake: Zig as a C Build System<\/h3>\n

If you have ever built a C project of reasonable size, you know the traditional drill. You start with a simple, elegant Makefile. It works beautifully until you need cross-platform support, dependency management, or WebAssembly<\/strong> compilation. At that point, developers usually surrender and migrate to CMake, bracing themselves for a clunky scripting language that often feels like it\u2019s fighting against you.<\/p>\n

Since we wanted to compile our path tracer, Tracy, for Linux, Windows, and the web, we needed a modern alternative. For that purpose we chose Zig<\/strong>.<\/p>\n

Even though Tracy is written almost entirely in C11, Zig acts as a drop-in C\/C++ compiler (zig cc<\/code>). More importantly, it features a build system where configuration files (build.zig<\/code>) are written in a proper, strongly typed programming language. There are no weird macros or string-matching hacks; just standard, imperative code.<\/p>\n

The Performance Hunt<\/strong><\/em><\/p>\n

However, it wasn\u2019t all sunshine and rainbows from day one. When we first migrated from our quick-and-dirty Unix Makefile to Zig, we noticed something alarming: Zig\u2019s ReleaseFast<\/code> mode (the build profile for maximum execution speed) was actually running slower than our previous clang -O3 -march=native -flto<\/code> Makefile setup. In a path tracer, where millions of ray-scene intersections occur every second, this was a major issue.<\/p>\n

We dug into the build graph and realized the problem lay in our linking strategy, specifically regarding our random number generator (RNG). Monte Carlo path tracing requires millions of random numbers per pixel. Initially, we were building our RNG dependency (the PCG library<\/a>) separately and linking it to our library afterwards. This isolated the optimization steps, creating a boundary that prevented the compiler from applying a crucial optimization (inlining the frequent RNG calls).<\/p>\n

Typically, the modern solution for crossing this compilation boundary is Link Time Optimization (LTO), but enabling it in Zig wasn\u2019t enough to fully catch up to the performance of the raw clang<\/code> command. Instead, we bypassed the linking step entirely by forcing a \u201cUnity build\u201d. We compiled the PCG source files directly alongside tracy.c<\/code>, which guarantees the compiler can apply the previously mentioned optimizations.<\/p>\n

With these optimizations we not only matched our old Makefile performance, but the Zig build actually ran faster<\/em>.<\/p>\n

Ultimately, we created a single build.zig<\/code> file that generates our native C binaries and orchestrates our entire Zig-based test suite.<\/p>\n

However, we do have to admit one engineering reality check: our build.zig<\/code> does not currently handle our WebAssembly target. While Zig has impressive cross-compilation capabilities, we hit a roadblock trying to get it to compile our OpenMP multi-threading directives for the web. Rather than fighting the toolchain, we made the pragmatic choice to rely on Emscripten (emcc<\/code>) for the web build, orchestrated with Vite using standard Node.js scripts.<\/p>\n

3. White-Box Testing C Code with Zig<\/h3>\n

Testing C code is a well-solved problem, but it usually involves reaching for third-party frameworks like Check<\/a>, CMocka<\/a>, or Unity<\/a>. While these tools are robust, they often require wiring up separate build targets and writing a fair amount of macro-heavy boilerplate just to assert simple math operations.<\/p>\n

Since we were already using Zig to orchestrate our build, we decided to use its built-in test runner to test our C codebase. The integration promises to be seamless thanks to Zig\u2019s @cImport<\/code> function, which can parse C code directly.<\/p>\n

Instead of just importing our public tracy.h<\/code> header, our Zig test files import the actual tracy.c<\/code> source file. This allowed us to perform true white-box testing<\/strong>. We could instantiate internal C structs and write tests for private geometry intersection functions without exposing them in our public API or restructuring our codebase.<\/p>\n

The Free Sanitizer Catch<\/strong><\/em><\/p>\n

Initially, this setup felt great thanks to Zig\u2019s compiler automatically instrumenting the code with safety checks similar to C\u2019s Undefined Behavior Sanitizer (UBSan).<\/p>\n

This saved us from a notoriously difficult-to-debug graphical glitch early on. During our global HDR to LDR tonemapping phase, a calculated pixel luminance value was slightly exceeding its bounds before being assigned to an 8-bit unsigned integer. In our previous standard C compilation, this value silently overflowed, resulting in yellow speckles in the brightest parts of the generated images. Because of Zig\u2019s automatic runtime safety checks, it caught the overflow instantly and pointed us to the exact line of C code that caused the issue.<\/p>\n

While enabling tools like UBSan in a traditional C setup is as simple as adding a compiler flag, having these checks baked into the default zig build test<\/code> command ensures that safety isn\u2019t an opt-in configuration you have to remember to enable.<\/p>\n

The Reality Check: Zig\u2019s Rough Edges<\/strong><\/em><\/p>\n

However, our enthusiasm was eventually tempered by reality. While @cImport<\/code> sounds like magic, relying on a pre-1.0 language for complex C interop comes with severe limitations that made us question its production readiness.<\/p>\n

The first major issue was with Zig\u2019s translate-c<\/code> engine. In our C code, we define our scenes using C99 designated initializers combined with unions (e.g., {.shape.type=TRIANGLE, .shape.data.triangle={...}}<\/code>). The Zig translation engine completely choked on this syntax. Instead of failing gracefully, it fell back to declaring our scene definitions as extern<\/code> variables, causing \u201cundefined symbol\u201d errors from the linker. To fix it, we had to introduce a terrible hack: exporting dummy, zero-length arrays from Zig just to satisfy the linker so our unit tests would compile.<\/p>\n

While this is problematic and should be fixed on Zig\u2019s end, the most dangerous issue was the caching system. The absolute worst thing a test suite can do is give you a false positive. At one point, we modified the implementation in tracy.c<\/code> and ran zig build test<\/code>. The tests should have failed here, but everything passed. We later realized that Zig\u2019s build cache had failed to detect the change in the underlying C file and simply re-ran a cached test executable. We had to nuke the .zig-cache<\/code> to get our tests to fail properly, and we eventually disabled caching for the unit tests in our CI pipeline to avoid being lied to.<\/p>\n

Ultimately, using Zig to test C code is a fascinating concept that yields DX wins. But until the translation engine and the build cache mature, it remains a tool that you have to handle with care.<\/p>\n

4. Visual CI\/CD: The Quest for Physical Correctness<\/h3>\n

While unit testing individual C functions with Zig is fantastic for ensuring our vector math or ray-sphere intersections are mathematically sound, it falls short of validating the renderer as a whole. A microscopic bias in a material calculation or a missing cosine term in the integration loop might easily slip past isolated unit tests, yet completely break the physical accuracy of the final image.<\/p>\n

To guarantee the entire system works from end to end, we rely on image-to-image comparison<\/strong>. To test if a rendered image is \u201cphysically correct\u201d we compare it to a ground truth. For this, we use Mitsuba 3<\/a>, an industry-standard, heavily validated research path tracer. By recreating our test scenes (geometry, materials, and lighting) exactly in Mitsuba\u2019s XML format, we generate \u201cgolden\u201d reference images. Crucially, we output these as EXR files to preserve the raw, floating-point High Dynamic Range (HDR) light data. Comparing Tracy\u2019s output directly against these references allows us to test the entire rendering pipeline in one go.<\/p>\n

Choosing the Right Metric<\/strong><\/em><\/p>\n

While relying on human visual inspection alone is possible if you know exactly what to look for, it\u2019s highly subjective and error-prone. This manual approach is better suited for optimizing the look and feel (e.g., for a video game) rather than mathematical correctness.<\/p>\n

Humans are surprisingly bad at spotting math errors in rendered images, especially in high-contrast areas. This is mostly due to the brain\u2019s filtering of visual information; we are hypersensitive to contrast and edges but relatively blind to subtle shifts in uniformly colored surfaces or specific color channels where the eye has lower sensitivity. In cases where human-perceived quality is the main goal, perceptual metrics for image-to-image comparison such as SSIM<\/strong> or the more modern FLIP<\/strong> developed by NVIDIA can be used. These try to mimic the human \u201cfilter\u201d to automate the evaluation process.<\/p>\n

For Tracy, we need to know that our math is actually correct<\/strong>, not just that it looks pleasing to the eye. Human perception was no longer a sufficient benchmark, so we shifted our focus from perceptual metrics to physical ones.<\/p>\n

We initially looked at Mean Squared Error (MSE)<\/strong>, but standard MSE is notoriously biased toward bright pixels in HDR rendering. A tiny error in a bright area would spike the score, while a massive error in a dark shadow might go unnoticed. To fix this, we implemented Relative Mean Squared Error (RelMSE),<\/strong> which normalizes the error across extreme HDR brightness levels. This serves as an objective measure of physical accuracy against our Mitsuba-generated ground truth.<\/p>\n

Ultimately, we landed on a comparison to a ground-truth image using relMSE, which distills the quality of the entire render into a single, objective score.<\/p>\n

Difference Maps<\/strong><\/em><\/p>\n

A single error score does tell you that something is wrong with the rendered image, but for pinpointing the error you need a visual representation. For this purpose, we generate difference maps<\/strong>. By comparing our render against the Mitsuba reference pixel-by-pixel, we produce an image where bright areas represent high error and dark areas represent high accuracy. This allows a developer to instantly see if a bug is localized to, for example, refractive surfaces or certain light sources.<\/p>\n

This comparison image below perfectly illustrates why relying on the naked eye is a trap. Looking at our render in the middle panel, the scene appears completely fine. The lighting, shadows, and glass all look subjectively \u201ccorrect.\u201d<\/p>\n

However, the difference map on the right reveals the mathematical reality. It highlights two distinct types of errors: the faint, grainy texture across the walls is simply expected variance (standard Monte Carlo noise). However, the glaringly bright ring around the edge of the glass sphere is a systematic failure. It instantly exposed a subtle bug in our Fresnel reflection logic at grazing angles. Without image diffing, a physical inaccuracy like that could have easily gone unnoticed.<\/p>\n

For even more precision, we could instead generate error heatmaps<\/strong>, applying a configurable color gradient that makes subtle flaws more obvious, but currently we are still using simple difference maps.<\/p>\n

\"\"<\/a>
Mitsuba Reference (left), Tracy Render (middle), Difference Map (right)<\/figcaption><\/figure>\n

While RelMSE gave us a performance score, running metrics manually across every commit was not scalable. To make certain our math stayed correct and performant as the codebase grew, we integrated benchmarking, unit tests and logging directly into a GitHub Actions CI\/CD pipeline<\/strong>. By archiving these metrics on every push, we laid the groundwork to automatically generate trendline graphs that visualize our renderer\u2019s improvements over time and catch regressions at a glance.<\/p>\n

Continuous Integration<\/strong><\/em><\/p>\n

We build our binaries inside a dedicated Docker container. This ensures that library versions, system configurations, and compiler toolchains remain identical for every run, preventing the \u201cit works on my machine\u201d issue. The pipeline executes benchmarks based on a YAML configuration file that defines target scenes, and path tracing settings.<\/p>\n

\n
\"\"<\/a><\/pre>\n<\/div>\n
This example shows a simplified configuration of a scene named \u201cCaustics\u201d as well as two rendering jobs, each with a different configuration (std – Standard, rr – Russian roulette ray elimination).<\/p>\n
At the end of the CI step all of the important files get exported as run artifacts. This includes raw benchmark logs (error scores and timings) alongside PNG versions of the rendered images, reference images, and difference maps.<\/p>\n
However, path tracing is a computationally expensive task, so to keep the pipeline from feeling sluggish we included two main optimizations:<\/p>\n