Getting started and setup

Getting started and setup

This page will go through all the steps to get started and set up using the Godot Backtrace module. The Crashpad module supports Windows, MacOS, and Linux desktop operating systems. As new platforms are added, this page will change accordingly.

Getting started

The module has a few dependencies that need to be set up before it can be used. First, you will need to download and compile the 3.x branch of the Godot Github repository. The Godot documentation has a guide for compiling for all desktop operating systems on its documentation that covers all the steps needed. Windows, MacOS, and Linux all have their own pages on the Godot documentation that explain the steps that need to be taken to compile Godot on each platform. You will need to install all of the dependencies and libraries needed to compile Godot, including scons. If you wish to make modifications to the module, you may also want to look at the engine development page on the documentation.

Next, you will need to download and compile Google Crashpad. This module currently uses Google Crashpad for generating crash reports that can be parsed by services like Backtrace. The Developing Crashpad page on the Crashpad repository covers how to download and compile Crashpad on your machine. Note that to compile Crashpad, you will need to download Google's depot_tools, in addition to Crashpad itself.

Note: You will need to compile Crashpad to use it successfully with this module. Crashpad can be a little tricky to setup and compile. Some notes:

• Crashpad uses gn to create the project settings, and gn requires Python 2 to run correctly! However, scons requires Python 3, and both expect python to refer to their version. I found that, on Windows, I had to install Python 2, compile Crashpad, and then uninstall Python 2 to use scons.
• IMPORTANT: For Windows, you need to generate dynamic libraries in order to link them to Godot for use in this module. This requires calling gn gen out\Default --args="extra_cflags=\"/MD\"" on Windows. Credit to IceFire on Stackoverflow for the solution.

After you have Crashpad compiled, you will need to copy a few things in order for it to work with the module.

The Crashpad module requires the compiled library files from Crashpad to be in the modules/crashpad/lib/ folder so it can be linked. The following compiled libraries are needed:

• base
  • On Windows, this file is called base.lib and can be found at crashpad/out/Default/obj/third_party/mini_chromium/mini_chromium/base
  • On Linux, this file is called libbase.a and can be found at crashpad/out/Default/obj/third_party/mini_chromium/mini_chromium/base
  • MacOS has not yet been tested, but the file should be called libbase.a and can be found at crashpad/out/Default/obj/third_party/mini_chromium/mini_chromium/base
• client
  • On Windows, this file is called client.lib and can be found at crashpad/out/Default/obj/client
  • On Linux, this file is called libclient.a and can be found at crashpad/out/Default/obj/client
  • MacOS has not yet been tested, but the file should be called libclient.a and can be found at crashpad/out/Default/obj/client
• common
  • On Windows, this file is called common.lib and can be found at crashpad/out/Default/obj/handler
  • On Linux, this file is called libcommon.a and can be found at crashpad/out/Default/obj/handler
  • MacOS has not yet been tested, but the file should be called libhandler.a and can be found at crashpad/out/Default/obj/handler
• util
  • On Windows, this file is called util.lib and can be found at crashpad/out/Default/obj/util
  • On Linux, this file is called libutil.a and can be found at crashpad/out/Default/obj/util
  • MacOS has not yet been tested, but the file should be called libutil.a and can be found at crashpad/out/Default/obj/util

You will need to take these libraries and copy-paste them into modules/crashpad/lib so they can be linked when compiling Godot.

Next, you will also need to make a copy of the Crashpad source code and copy it to the thirdparty folder. Copy the crashpad folder and paste it into the thirdparty/crashpad folder of this module. This is required for Godot to compile the headers correctly.

Note: You need to copy the crashpad that has a child folder of build, client, etc and not the crashpad/crashpad folder into thirdparty/crashpad. You can make sure you have copied it correctly by checking if thirdparty/crashpad/crashpad/build is a valid filepath.

For Linux there is an additional dependency. Crashpad on Linux does not provide a database manager and so the module handles uploading the crash files manually. To do this, it requires curl to be installed on your system. To know whether you have curl installed, open a terminal and type curl and then press enter. If you get output like curl: try 'curl --help' or 'curl --manual' for more information then curl is successfully installed and usable. If curl is not installed, you will need to install it so crash reports can be sent to the online server. To install curl, search "OS-HERE install curl", where "OS-HERE" is the name of the Linux OS you are using. For most Linux operating systems, curl is installed automatically.

Once you have all those steps finished, you are ready to start using the module! The last steps are to copy the modules and thirdparty folders from the Godot Backtrace Module and paste them into the folder where you downloaded the Godot source code. This should add a crashpad folder to the modules folder, as well as adding a crashpad folder to the thirdparty folder in the Godot source code.

Now you can compile Godot normally using scons. The code should build like normal and you will receive an executable you can run.

Setting up

Once you have successfully compiled the module, there are just a few more steps you need to complete. First, open the Godot project that you want to add automatic error generation to with the newly compiled Godot executable. Next, create a new node and make sure Crashpad is an option from the drop down list. If it is there, then that means the module has successfully compiled and is ready to be used. If it is not present, please check the "Getting Started" section to see if you missed any steps.

Setting up Godot

There are a few different ways you can setup the Crashpad node, depending on your use case. The generally recommend way is to make a new scene and use an autoload singleton to automatically load and create the scene. This way, there is just a single instance of the node and it is accessible in all scenes.

First, make a new scene by clicking the "+" icon in the Godot editor and set the root node to a Crashpad node. Save this scene as something like automatic_crash_report.tscn. Click the Crashpad node and expand the Crashpad Settings group. Here is all the properties you can use to configure Crashpad, like where it uploads the crash report, what attributes are assigned, and where to store the database.

For now, use the following properties:

• Api Url = yoursubdomainhere.sp.backtrace.io
• Crashpad Api Token = todo
• Application Path = res://crashpad_handler
  • NOTE: You do not need to add anything to your project! res:// will be converted to the folder of the executable by the module.
  • NOTE: Do not add any extensions, even if on Windows! The module will, by default, handle the extension
• Database Path = res://Crashpad/db/

The rest of the properties you can leave blank. When finished, it should look like this:

Next, add a script to the Crashpad node, name it automatic_crash_report.gd, and paste the following:

extends Crashpad

func _ready():
	start_crashpad()

That is all the scripting that is needed! As you can see it is really easy and fast to get automatic crash reporting ready and set up for your Godot project. Save the scene and script.

We need to make the automatic_crash_report.tscn scene run as an autoload singleton in Godot. First, open the project settings by clicking project in the top right corner of the Godot editor and then select project settings. From the window that pops up, select the AutoLoad tab and then in the Path: field, set the path to the automatic_crash_report.tscn file, optionally change the node name, and then select Add. This will make the scene run automatically as an autoload singleton.

If you want to learn more about autoload singletons in Godot, refer to the Godot documentation on autoload singleton.

Before we can run this code, we need to figure out what values we'll need for api_URL and api_token, so the system knows where to send the crash report once it occurs.

Setting up Backtrace

Because this module is designed to work with Backtrace, we will be following the steps to set up the module so Crashpad sends it's data to a Backtrace instance.

First, go to the Backtrace website at https://backtrace.io/ and make a free account by pressing "GET STARTED" if you do not already have an account. Backtrace is free for single developers with a limit of 25K monthly errors, which is more than enough for small projects.

If you are making a new account, be sure to remember to note what you put in as your subdomain, as this will be important! If you already have an account, you will need to get your subdomain so you can correctly point the module to the right place.

Once you have made your account, go to your subdomain, which should be something like https://SUBDOMAIN_HERE.sp.backtrace.io/, where SUBDOMAIN_HERE is, instead, the subdomain you have chosen for your account. Once logged in, make a new project and name it the same as your Godot project. Then go to the project settings, which you can access by clicking your profile on the top right corner, and select "project settings" from the drop down. On the left side, go to "Integration guides" and select "Minidump".

This will bring you to the Minidump integration guide. What we are looking for is the automatically formatted URL for CURL, which should be right below the text "If you are using curl, the following command submits a file.dmp into your Backtrace instance". It should look something like the following:

curl -v --data-binary @file.dmp 'https://submit.backtrace.io/SUBDOMAIN_HERE/1234567890123456789012345678901234567890123456789012345678901234/minidump'

On your page, instead of SUBDOMAIN_HERE it will, instead, have the name of your subdomain in all lowercase, and instead of a long string of 1234567890, there will be a token that is unique to your project. This is the data we need to set in the autoload singleton we made in Godot.

First, copy https://submit.backtrace.io/SUBDOMAIN_HERE/ (where SUBDOMAIN_HERE is your subdomain) and paste it as the value of Api Url in the Crashpad node inspector in the automatic_crash_report.tscn scene we made earlier. It's important that there be a / at the end of the URL, as otherwise it will not work correctly, so make sure to include it at the end.

Next, copy the long string after the URL that should look something like 1234567890123456789012345678901234567890123456789012345678901234 and paste that as the Crashpad Api Token in the autoload singleton scene file we made in Godot earlier. Make sure to use the full token from the Minidump integration guide without any / characters.

Once done, the Crashpad node in your inspector should look something like this:

If it does, then we're almost ready to send our first test crash report to make sure everything is working!

Next, we need to copy the crashpad_handler executable from Crashpad and make sure it is in the same folder as our compiled Godot executable. This executable is required by Crashpad and it cannot generate and upload the crashes without it!.

• For Windows, you can find the executable in crashpad/out/Default/ and it's called crashpad_handler.exe
• For Linux, you can find the executable in crashpad/out/Default and it's called crashpad_handler
• For MacOS, you can find the executable in crashpad/out/Default and it's called crashpad_handler

Just copy the executable and paste it right beside your compiled Godot executable. When finished, it should look something like this:

NOTE: When shipping any Godot applications that use this module, you will need to make sure to include crashpad_handler beside the executable! Without this file, the exported Godot application will be unable to send crash reports.

The last step we need to do is generate and submit the symbol files, so when a crash occurs Backtrace knows how to link the stacktrace to code in Godot.

To do this, we first need to generate a .sym file that we can upload to Backtrace. Go to where you compiled Godot and open the folder with the executable you compiled. Then open a terminal at that location and type the following command:

// For Linux, it should look something like this:
dump_syms godot.x11.tools.64 > godot.x11.tools.64.sym

What this will do is call the dump_syms command from Google Crashpad and will generate a symbols file that we can then use to map stacktrace data from Crashpad to lines of code.

Note: You may need to change godot.x11.tools.64 in the command based on how you compiled Godot. For example, if you compiled Godot with 32 bits instead of 64, then you will need to change it to godot.x11.tools.32 instead. If you are compiling on Windows, you will need to change it to godot.windows.tools.64.exe

Once finished, go back to the Backtrace website and on the right side, select "Symbols", and from the drop down, select "Upload an archive". Then drag and drop the .sym file you just generated with dump_syms and hit "next". You can optionally add a tag (I suggest 0.0.1) and then hit next. Backtrace will then upload it to their servers and you are ready to go!

Please note that you will need to repeat this process of generating the .sym files and uploading it to Backtrace each time you compile Godot from source with the Crashpad module. This is required because anytime the Godot source code changes the stacktrace data changes as well.

Testing

To test to see if the automatic error reporting code works correctly, change the code in automatic_crash_report.gd to the following:

extends Breakpad

func _ready():
	start_crashpad()
	# Wait a couple seconds - let everything initialize
	yield (get_tree().create_timer(2.0), "timeout")
	# Force a crash
	force_crash()

What this code does is wait a few seconds, just to make sure everything is fully initialized, and then forces a crash using the force_crash function, which is designed specifically to cause a simple crash by trying to divide an integer by zero. Run this code and you should find that Godot will launch, stay for a few moments, and then automatically close. If so, then that means everything worked correctly!

Go ahead and check your project on Backtrace. From the project settings, click the "Back" button with an arrow on the top left of the screen. This will bring you to the triage screen and you should see a single open error with a description of "Crashpad::crash". You can click the fingerprint on this error to see more details. If you look at the call stack, it will show the C++ code that was executed leading up to the crash. This means the module is working and set up successfully!

Now enjoy the benefits of having automatic crash detection in your Godot games! Remember to remove force_crash() in your singleton, so your project only will upload a crash when Godot actually crashes.