Qt
Sample
BugSplat has developed a sample application that demonstrates a cross-platform Qt crash reporting solution with Crashpad. The MyQtCrasher sample application provides a good starting point for developers wishing to capture crashes on Windows, macOS, and Linux. Additionally, the sample provides symbol upload scripts that you can incorporate into your build tools in order to generate crash reports with fully symbolicated call stacks
The MyQtCrasher sample application is available on GitHub.
Building Crashpad
BugSplat leverages Crashpad to provide crash reporting for macOS, Windows, and Linux Qt applications. For an in-depth guide that discusses how to build Crashpad, please see this article.
For Windows, you'll need to build shared libraries for both Release (/MD
) and Debug (/MDd
) configurations. You'll also want to consider building with Whole Program Optimization turned off (/GL-
). To build shared libraries generate your Crashpad build using the following terminal command:
The snippet above works with Windows CMD and depending on the terminal you're using you might get various errors related to escape characters. If you choose to omit the /GL-
flag you must ensure that you build Crashpad with the same version of MSVC you use for building your Qt application otherwise your project will not build. Setting the version of MSVC that builds Crashpad can be done by instead generating your configuration using the command gn gen out/Default --winsdk="10.0.19041.0" --ide="vs2017"
.
For more info on how to build Crashpad shared libraries on Windows, see this post.
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 $$PWD/Crashpad/Include/crashpad
where $$PWD
is your project's working directory. Add the include directories to your project by pasting the following snippet at the top of your project file:
Next, link your app with the Crashpad libraries. Linking with the Crashpad libraries is platform-dependent.
macOS
Copy libcommon.a
, libbase.a
, libutil.a
, libclient.a
, and libmig_output.a
into $$PWD/Crashpad/Libraries/MacOS
. You'll need to link to versions of these libraries that were built to target either arm64
or x86_64
depending which architecture your build targets. You'll also need to link with the system libraries libbsm
, AppKit.Framework
, and Security.Framework
. Add the following snippet to your project file to link with the aforementioned libraries:
You'll need to ship a copy of the crashpad_handler
executable with your application. Again, be sure to copy the version of crashpad_handler
that targets either arm64
or x86_64
depending on what architecture you're targeting.
Copy crashpad_handler
to the $$PWD/Crashpad/Bin/MacOS
directory. Add the following snippet to the macx
section of your project file that copies the macOS crashpad_handler
to your project's build directory.
Windows
Copy base.lib
, common.lib
, client.lib
and util.lib
into $$PWD/Crashpad/Libraries/Windows
. You'll need to link with the system library Advapi32
. Add the following snippet to your project file to link with the aforementioned libraries:
Additionally, you'll need to ship a copy of the crashpad_handler.exe
executable with your application.
Copy crashpad_handler.exe
to the $$PWD/Crashpad/Bin/Windows
directory. Add the following snippet to the win32
section of your project file that copies the Windows crashpad_handler.exe
to your project's build directory.
Linux
Copy libbase.a
, libutil.a
, libcommon.a
and libclient.a
into $$PWD/Crashpad/Libraries/Linux
. The order in which you specify the Crashpad libraries to link is important! libcommon.a
, and libclient.a
must be specified first, then libutil.a
and finally libbase.a
. Add the following snippet to your project file to link with the aforementioned libraries:
Additionally, you'll need to ship a copy of the crashpad_handler
executable with your application. Copy crashpad_handler
to the $$PWD/Crashpad/Bin/Linux
directory. Add the following snippet to the linux
section of your project file that copies the Linux crashpad_handler
to your project's build directory.
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 is a macOS, Windows, and Linux compatible snippet that will configure the Crashpad handler:
Be sure to update the values for dbName
, appName
and appVersion
to values specific to your application. The Paths
class allows you to get platform-specific paths for Crashpad and its source can be found here. To configure the paths to crashpad_handler
, metricsDir
, reportsDir
and attachment
you'll first want to find the location of your executable using the sample code below:
Add a call to initializeCrashpad
at your application's entry point.
Symbols
In order to get function names and line numbers in your crash reports, you will need to generate and upload .sym
files to BugSplat. Crashpad .sym
files can be generated from a macOS .dSYM
file, a Windows .pdb
file or a Linux .debug
file.
To generate .dSYM
, .pdb
and .debug
files add the following to the project file:
macOS
To generate .sym
files you will need to build or locate a copy of dump_syms
. Additionally, to upload symbol files to BugSplat you will need to build or locate a copy of symupload
. Prebuilt copies of dump_syms
and symupload
can be found here.
Build your project and run dump_syms
to generate .sym
files:
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:
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. An example of how to run dump_syms
and symupload
as a build step can be found here.
Windows
The functionality of dump_syms.exe
is built into symupload.exe
on Windows. In order to generate .sym
files, you will need to build or locate a copy of symupload.exe
. A prebuilt copy of symupload.exe
can be found here. Additionally, in order to run symupload.exe
a copy of msdia140.dll
must be present in the same directory as symupload.exe
.
Run symupload.exe
to upload .sym
files to BugSplat. Be sure to replace the {{database}}
, {{application}}
and {{version}}
with the values you used in the Configuring Crashpad section:
You'll need to generate and upload .sym
files making sure to increment the version number for each release build. The version number from the Configuring Crashpad section must match the version number in your upload URL. An example of how to run dump_syms
and symupload
as a build step can be found here.
Linux
To generate .sym
files you will need to build or locate a copy of dump_syms
. Additionally, to upload symbol files to BugSplat you will need to build or locate a copy of symupload
. Prebuilt copies of dump_syms
and symupload
can be found here. Build your project and run dump_syms
to generate .sym
files:
When symbols are dumped from a debug file Crashpad creates an incorrect module name. To correct this issue, use sed
to correct the module name in the .sym
file.
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:
You'll need to generate and upload .sym
files making sure to increment the version number for each release build. The version number from the Configuring Crashpad section must match the version number in your upload URL. An example of how to run dump_syms
and symupload
as a build step can be found here.
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 Dashboard page. Click the link in the ID
column to see the details of your crash report. The following image is from our sample myQtCrasher
application:
Last updated