The Android NDK is a set of tools for building native C++ applications for Android. BugSplat recommends using Crashpad to handle native crashes in Android NDK applications. Before getting started with this tutorial, please review the AndroidCrasher application to see an example BugSplat integration.

Building Crashpad

BugSplat leverages Crashpad to provide crash reporting for Android NDK applications. This tutorial provides a quick overview of how to build Crashpad. For an in depth guide that discusses how to build Crashpad, please see this article.

To build crashpad you'll first need to download a copy of the Chromium depot_tools. Once you have downloaded depot_tools, you'll need to add the parent folder to your system's PATH environment variable. After adding depot_tools to your systems PATH, run the following commands to download the Crashpad repository:

Next you'll need to generate Crashpad build configurations for each Android ABI your application supports. You can view the source of gyp_crashpad_android.py to see a list of supported ABIs. Take note of the --api-level value you use here as you'll need this information when configuring your project. The following command will create a Crashpad Android config for the x86 ABI:

Once you've generated a build configuration for all of the Android ABIs you can build the Crashpad libraries. If you build the Debug configurations you will be able to step debug through the Crashpad libraries in the event that you need to troubleshoot your integration. Run the following command to build the Android x86 Debug libraries:

Integrating Crashpad

Once Crashpad has been built you'll need to add the relevant include directories to your project. Copy all of the Crashpad .h files to the directory app/src/main/cpp/crashpad/include. Next, add the include directories your project's CMakeLists.txt file:

After adding the include directories, you'll need to add the Crashpad static libraries to your project. You'll need to add a set of Crashpad libraries for each ABI your application supports. From the /crashpad/out/Debug/{{ABI}} directory you'll want to copy the client, util and third_party/mini_chromium/mini_chromium/base folders to app/src/main/cpp/crashpad/lib/{{ABI}}.

BugSplat crashpad android libs folders

Once all of the Crashpad libraries have been copied to your project directory, add the following to your project's CMakeLists.txt file to link the Crashpad libraries:

Additionally, you'll need ship a copy of the crashpad_handler executable with your application. To do this, you'll need to rename crashpad_handler to libcrashpad_handler.so otherwise it will be ignored by the APK bundler. Copy libcrashpad_handler.so to app/src/main/cpp/crashpad/lib/{{ABI}} for each Crashpad ABI architecture. Add the following snippet to CMakeLists.txt so that libcrashpad_handler.so is copied to your device and made available at runtime:

Configuring Crashpad

To enable Crashpad in your application you'll need to configure the Crashpad handler with your BugSplat database, application name and application version.  The following snippet will configure the Crashpad handler:

Be sure to update the values for database, appName, appVersion and packageNameto values specific to your application. Next add a call to initializeCrashpad at the entry point of your application. The following example defines initializeCrashpad as a native C++ function and calls it using Kotlin from MainActivity:

To test the attachments feature, use Java or Kotlin to write a text file. The following is a Kotlin snippet that creates a file attachment.txt:


To ensure that your crash reports contain function names and line numbers you'll need to add an option to your build configuration that prevents symbolic information from being stripped. To prevent symbols from being stripped, add the following to your build.gradle file:

Next, you will need to generate and upload .sym files to BugSplat. To generate symbols for your Android NDK library you will need to build the Breakpad tool dump_syms on a Linux machine. For more information about building Breakpad tools on Linux please see this document.

Once you've built dump_syms on a Linux system, run dump_syms on a Linux machine passing it the path to your Android library:

You can also run the Linux version of dump_syms using compatible Linux emulator on OS X or Windows. Examples of how to run a Linux build of dump_syms on OS X and Windows can be found in the tools section of the AndroidCrasher repository.

If you're developing on an OS X or Linux system, build the Breakpad tool symupload on your local system. Upload the generated .sym file by running symupload. Be sure to replace the {{database}}, {{application}} and {{version}} with the values you used in the Configuring Crashpad section:

If you're developing on Windows, symupload will not upload your Android .sym files. As an alternative, the AndroidCrasher tools folder provides and example PowerShell script that will upload .sym files to BugSplat.

After each release build you'll need to generate and upload .sym files making sure to increment the version number each time. The version number from the Configuring Crashpad section must match the version number in your upload URL.

Generating a Crash Report

Force a crash in your application after Crashpad has been initialized:

After you've submitted a crash report, navigate to the Crashes page. Click the link in the ID column to see the details of your crash report. The following image is from our sample AndroidCrasher application:

BugSplat android ndk crash