Crashpad is the crash handler under a huge amount of native software you already use. It's Google's cross-platform crash reporting system, the successor to Breakpad, and it's what catches the crash, writes a minidump, and ships it somewhere useful on Windows, macOS, Linux, Android, and iOS. If you're writing native C++ and you want one crash handler that works everywhere your code runs, Crashpad is the answer, and BugSplat is built to receive what it sends.

This post is about pairing the two: how Crashpad fits with BugSplat, what to expect from the setup, and where to go when you hit the part that's genuinely fiddly.

Why Crashpad, and what BugSplat adds

Crashpad's job ends at "capture the crash and upload a minidump to a URL." That's the hard, low-level part, and Google does it well. But a minidump is a binary blob. On its own it tells you nothing. The value comes from what happens next: symbolicating that minidump into a real call stack with function names and line numbers, grouping it with every other report of the same crash, and putting it somewhere your whole team can read it.

That next part is what BugSplat is. You point Crashpad at your BugSplat database URL, it uploads minidumps there, and we turn them into readable, grouped, prioritized crash reports. Crashpad and Breakpad are wire-compatible, so if you're on a legacy Breakpad setup, those reports process the same way on our end and migrating is low-drama.

The setup, honestly

Integrating with BugSplat is the easy half. You copy two methods from our sample, initializeCrashpad and getExecutableDir, set your database, application, and version, and configure the upload URL:

cpp

std::string url = "https://" + dbName + ".bugsplat.com/post/bp/crash/crashpad.php";

You attach annotations, which BugSplat parses into searchable attributes, build flavor, GPU, level, whatever you want to slice crashes by. You ship crashpad_handler next to your executable and include it in your installer. Our my-cmake-crasher sample has all of this working for Windows, macOS, and Linux, so you're adapting real code, not guessing.

The genuinely hard half is building Crashpad itself. Crashpad uses gn and ninja, its dependencies are managed by gclient rather than git submodules, and you need the Chromium depot_tools on your PATH before any of it works. On Linux you'll need build-essential and libcurl4-openssl-dev. On Windows you'll likely want it as a dynamic library, which means the right extra_cflags. None of this is hard once you've done it once. All of it is annoying the first time.

Read Bobby's guide before you start

Our CTO Bobby wrote the walkthrough we wish existed when we first built Crashpad: How to Build Google Crashpad. It is the single most useful thing you can read before you begin, and it'll save you the afternoon most people lose to the build configuration.

It covers the parts the official docs skim: installing and PATH-ing depot_tools, the fetch and gclient sync checkout flow, generating build configs with gn gen for the target OS and architecture you actually want, and the Windows dynamic-library flags. It also covers symbol generation properly, building dump_syms to turn your binaries into .sym files, and the thing that catches everyone: anything that modifies an executable, code-signing, anti-cheat, must be done before you run dump_syms and symupload. Every time the executable changes, re-run both.

That one rule is responsible for more "why won't my crash symbolicate" support threads than anything else. The module name and ID in the minidump have to match the .sym file exactly. Code-sign after you generate symbols and the IDs no longer match. Bobby's guide spells out the whole symbol pipeline, including building minidump_stackwalk and the module_name/module_id/module_name.sym directory layout symbols need to live in.

If you don't want to build Crashpad at all, we publish pre-built libraries that we update monthly in the bugsplat-crashpad repo, plus the build scripts for Windows, macOS, and Linux. Plenty of teams start there and only build from scratch if they need a custom configuration.

The shortcut worth knowing

Two small things that save real time. Disable Crashpad's rate limiting during development (--no-rate-limit) so every test crash actually produces a dump. And make sure the directory Crashpad writes to is writable, or the handler itself crashes, which is a confusing way to spend twenty minutes.

Get past the build once and Crashpad is the most durable crash reporting decision you can make for native C++: one handler, every major platform, feeding readable reports into one place.

Start here: Bobby's Crashpad build guide and the Crashpad integration docs.

Want to see a minidump turned into a real stack trace? Start a free trial and submit your first crash.