Crash Reporting for Games Built With CMake

CMake gives you one build description that fans out to Windows, Linux, and macOS, which is a gift for shipping and a headache for crash reporting. A crash that arrives from a player is only useful if you can turn raw addresses back into file and line numbers, and that depends entirely on how each target was configured and which symbols you kept. This post walks through making release builds produce usable stack traces, keeping symbols organized per platform and per build, and capturing enough context that a single report points at the exact commit and toolchain that produced it.

Why build configuration decides everything

A stack trace is just a list of return addresses until something maps those addresses to your source. In a CMake project, the difference between a readable crash and a wall of hex is whether the build that the player ran emitted debug information and whether you kept it. Release builds strip symbols by default on many toolchains, so the crash you most want to diagnose is the one you can least read. The fix starts in your CMakeLists, not in the crash handler.

Set CMAKE_BUILD_TYPE deliberately and treat RelWithDebInfo as your shipping default rather than plain Release. That keeps optimizations on while still producing line tables. On MSVC that means generating PDBs even for optimized builds; on GCC and Clang it means passing the debug flags and then splitting symbols out rather than discarding them. Decide this once, encode it in the build, and every crash report inherits the benefit automatically.

Keeping debug symbols without shipping them

You do not want to hand players a binary fat with debug sections, but you absolutely want those symbols on your own machine. The standard move is to split them: build with full debug info, then use objcopy on Linux to write a separate .debug file and strip the shipped binary, or let MSVC drop the PDB beside the build artifact and archive it. macOS produces a dSYM bundle you collect during the build. Whichever platform, the symbol file gets versioned and stored, never shipped.

Tie each symbol set to a build identifier so you can find it later. A build hash, the Git commit, and the platform triple together name exactly one symbol file. Store them in object storage or a release archive keyed by that identifier. When a crash arrives months later from an old client version, you pull the matching symbols and resolve the trace offline. Without this discipline you will have a thousand reports and no way to read any of them.

Multi-platform reproducibility

The same CMake source builds differently on each platform, so a crash that reproduces on Linux may be invisible on Windows because of allocator behavior, alignment, or undefined behavior that only one compiler exposes. Pin your toolchain versions and record them in the build. Knowing a crash came from Clang 17 on arm64 versus MSVC on x64 narrows the search dramatically, because many crashes are platform-specific by nature, not logic bugs you can reproduce anywhere.

Use CMake toolchain files and presets so that the build is reproducible from a clean checkout. A CMakePresets.json that fixes generator, compiler, and flags means the binary a player ran can be rebuilt bit-for-bit by anyone on the team. That reproducibility is what lets you attach a debugger to the exact code path, set a breakpoint at the offending line, and confirm the fix rather than guessing from the trace alone.

Capturing the crash at runtime

The handler itself is the smallest part. Install a platform signal or exception handler that, on a fatal fault, walks the stack, collects the module base addresses, and records the build identifier you embedded at compile time. Do the minimum work in the handler because the process is already unstable; capture raw frames and module offsets, then serialize them and hand them off. Resolving addresses to symbols is something you do later, on a healthy machine, against the stored symbol file.

Attach context that the trace alone cannot give you: the platform triple, the toolchain version, the build hash, the graphics backend, available memory, and whatever game state matters at the moment of the fault. A crash in a rendering call means something different on a six-year-old integrated GPU than on a current discrete card. The richer the context, the faster you separate a genuine logic bug from an environment that no amount of code review would have caught.

Setting it up with Bugnet

Bugnet gives you crash reporting that captures the stack trace plus the device and platform context in one payload, which fits a CMake project well because your hard problem is correlating a trace with the build that produced it. Send the build hash, commit, and platform triple as custom fields on every report, and the address-to-source mapping becomes a lookup rather than a hunt. The in-game report button captures game state automatically, so a player who hits a soft failure rather than a hard crash still gives you a frame of reference to work from.

Occurrence grouping folds identical crashes into a single issue with a count, so when one bad release spikes across thousands of players you see one entry climbing rather than an unreadable flood. Filter by platform custom field to confirm whether a crash is Windows-only or hits every target, which is exactly the multi-platform question CMake builds raise. One dashboard holds every report from every platform, and you triage by occurrence count instead of by whoever shouted loudest in your Discord.

Make it part of the build, not an afterthought

The teams that diagnose crashes quickly are the ones who treated symbol management as a build step from the first commit. Add a post-build target to your CMake that splits symbols, names them by build identifier, and uploads them to your archive automatically. Now there is no manual step to forget and no release that ships without recoverable symbols. The crash handler and the symbol store were designed together, so every report that arrives is already readable.

Test the pipeline before you need it. Force a crash in a release build, confirm the report arrives with the right build hash, pull the matching symbols, and verify the trace resolves to the line you expect. Do this on every platform you ship. A crash reporting setup you have never exercised end to end is a setup you do not have, and the worst time to discover a broken symbol upload is the night a launch build starts faulting.

Decide your symbol strategy in CMakeLists on day one. A crash report is only as useful as your ability to map its addresses back to source.