diff --git a/docs/error-reporting/platform-integrations/crashpad.md b/docs/error-reporting/platform-integrations/crashpad.md index be9c29de2e..05ecee249e 100644 --- a/docs/error-reporting/platform-integrations/crashpad.md +++ b/docs/error-reporting/platform-integrations/crashpad.md @@ -1,7 +1,7 @@ --- id: crashpad title: Integrating Crashpad -sidebar_label: Crashpad +sidebar_label: Integration Guide description: Integrate Crashpad in your Backtrace project. --- diff --git a/docs/error-reporting/platform-integrations/visual-studio.md b/docs/error-reporting/platform-integrations/visual-studio.md index 5e91198691..8d1e74e0e2 100644 --- a/docs/error-reporting/platform-integrations/visual-studio.md +++ b/docs/error-reporting/platform-integrations/visual-studio.md @@ -1,106 +1,185 @@ --- id: visual-studio -title: Visual Studio Extension Guide (C++ and Crashpad) -sidebar_label: Visual Studio Extension Guide -description: The Backtrace Extension for Visual Studio . +title: Crashpad Integration Guide for Visual Studio 2022 +sidebar_label: Visual Studio +description: Crashpad Integration Guide for Visual Studio 2022 --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import useBaseUrl from '@docusaurus/useBaseUrl'; -The Backtrace extension for Visual Studio simplifies the integration and configuration of Crashpad in your C++ based application, allowing you to capture and submit crashes to your Backtrace instance. +## (C++ and Crashpad) -The extension installs a new item in the Project Menu (right-click on your project in the **Solution Explorer** to see **Add Crashpad support**). Selecting the menu item launches a wizard that allows the developer to download, configure, and integrate a supported Crashpad library into your application. +Follow these steps to add Crashpad to a C++ project. -Add crashpad support +## Build Crashpad binaries -## What You'll Need +In a x64 Native Tools Command Prompt for VS 2022 run the following commands to build Crashpad binaries for both the Debug and Release configurations. -- A Backtrace account ([log in](https://backtrace.io/login) or sign up for a [free trial license](https://backtrace.io/sign-up)). -- Your subdomain name (used to connect to your Backtrace instance). For example, `https://example-subdomain.sp.backtrace.io`. -- A Backtrace project and a [submission token](/error-reporting/project-setup/submission-url). -- Visual Studio 2017 or 2019 (Preview) with the Visual Studio Extensions plugin and WPF. -- Windows (Win32 or x86_64) as the target build platform. - -## Setup and Installation +```powershell +git clone https://github.com/backtrace-labs/crashpad.git +cd crashpad +cmake -B cbuild +cmake --build cbuild --config Debug +cmake --build cbuild --config Release +``` -1. Download the Backtrace Visual Studio Extension from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=Backtrace.VSPlugin2019-01-19). -2. Open the .vsix file either using Windows Explorer or the "Developer Command Prompt" along with the VSIXInstaller.exe file to install the extension. -3. Open a C++ project in Visual Studio. -4. Right-click on the project in the Solution Explorer to open the project menu. You see the new **Add Crashpad support** menu item. -5. Select the **Add Crashpad support** menu item to launch the wizard, which installs and configures the Crashpad library in the project. +## Set up a Visual Studio project -## Wizard Overview +### Set Language Standard -The wizard consists of three main steps: +Crashpad requires C++17. In project properties, select `All Configurations` and change the C++ Language Standard in the General tab from the default `C++14` to `C++17 (/std:c++17)`, if necessary. +listeners -**Step 1: Backtrace Server Information** +### Set Additional Include Directories -- Enter the URL of your Backtrace server and the submission token. -- The submission URL field provides an autocomplete feature based on the instance name you enter. -- The submission token field to allow crashes to be submitted to the Backtrace instance. This field requires that the provided string has exactly 64 characters. If you don't have a Backtrace instance, you can create one by following the provided link. -- Don't have an account?: This link will take the user to a web page where they can create a new Backtrace instance. Use this link if you don't already have a Backtrace instance provisioned for your project. -- Click **Next** to proceed to the next page. - step 1: backtrace server information +To simplify the paths, the following instructions assume that `$(CrashpadRoot)` is defined in a property sheet and points to the root directory of the cloned Backtrace Crashpad source code from the previous step. -**Step 2: Download or Use Existing Crashpad Library** +Add the following include directories in your Visual Studio project for all configurations in C/C++, Additional Include Directories: -- This step allows you to choose the versions of Crashpad you want to download (from the get.backtrace.io/crashpad/builds page) or specify the directory of an already downloaded library. -- Select the desired configuration and platform versions from the dropdown lists. Backtrace provides both Release and Debug configurations of Crashpad, and x64 & Win32 platforms. -- Use the **Download Crashpad** to connect to the `get.backtrace.io` servers and download the specified versions. Select the destination directory, and the wizard downloads the latest Crashpad binaries. If you specify multiple Configurations or Platforms to download, the wizard will download each. -- The **Backtrace Crashpad package directory** field is automatically filled if you use the **Download Crashpad**, but you can also provide a custom path by using the textbox or you can choose existing path by using **Browse**. -- Proceed to the next step after making the appropriate selections. - step 2: setup the configuration and platform versions - downloading the library +- `$(CrashpadRoot)` +- `$(CrashpadRoot)\third_party\mini_chromium\mini_chromium` -**Step 3: Automated Symbol Upload** +listeners -- In this final step, you can enable debug symbols upload after debug or release builds types. -- **Would you like to enable automated symbol upload for your project?** Tick this checkbox if you want the Wizard to configure post build steps to upload symbols to Backtrace after building your application. -- Check the "Enable automated symbol upload" field to configure post-build steps for uploading symbols to Backtrace. -- Select **Debug** and **Release** to configure Visual Studio to upload debug symbols as needed for different build types. -- If you are uploading symbols, you will need a **Symbol Upload Token**. This allows you to upload Symbols to Backtrace. This is a different token from your Submission token. -- Complete the wizard by clicking "Finish." - automated symbol upload +### Set Additional Library Directory -## Wizard Completion Tasks +Add a library directory pointing to the build output directory from the previous step in the project's Linker, General, Additional Library Directories. This would be `$(CrashpadRoot)\cbuild`, for instance. -After finishing the wizard, the extension performs background tasks to configure your project properly. These tasks include creating and modifying files in your project: +listeners - +### Add Additional Library Dependencies -You may see dialogs notifying you that files are being modified outside the Visual Studio environment. Choose **Reload All** as necessary. -Reload all button +Add the following libraries in the project's Linker, Input, Additional Dependencies. -A dialog about inconsistent line endings may appear. It's recommended to normalize the line endings according to your environment. -inconsistent line endings dialog +For debug configuration(s):
+`client\Debug\client.lib` -The Visual Studio Extension modifies the vcxproj file (project definition file) to add Crashpad to your project. You can further customize each option in **Project Properties**. +For release configuration(s):
+`client\Release\client.lib` -If you enable symbol upload, a post-build task is created. After each successful build, the extension sends the necessary files (.PDBs, .DLLs, .EXEs) as a zip archive to the Backtrace instance. You can disable this option in **Project Properties** under **Post-build** actions. +Or, if the configurations are named `Debug` and `Release` then this can be simplified to the following for all configurations:
+`client\$(Configuration)\client.lib` -## Post Install Steps +listeners -After completing the wizard, make sure to open the CrashpadSetup.cpp file and specify the following values: -- **db_path**: Set the directory where crash reports should be locally stored before submitting to Backtrace. -- **handler_path**: Configure the launch mechanism for Crashpad (for example., out-of-process). +## Code Samples -Additionally, initialize Crashpad and check the result with a function call like the following in your main function: +The following code can be added to your project and can be used to initialize Crashpad in your application. +Header, `bt_crashpad.h` ```cpp -bool result = backtrace::initializeCrashpad(); +#pragma once + +namespace backtrace { + bool startCrashHandler(); +} ``` -## FAQ +Source file, `bt_crashpad.cpp` +```cpp +#include "bt_crashpad.h" + +#include +#include +#include +#include +#include + + +#define NOMINMAX // prevent Windows headers from defining min/max +#include +#include +#include +#include + + +/* + * ENSURE THIS VALUE IS CORRECT. + * + * This is the directory used to store and queue crash data for the application. + */ +static const wchar_t CRASHPAD_DATABASE_PATH[] = L"."; + + +/* + * ENSURE THIS VALUE IS CORRECT. + * + * Crashpad has the ability to support crashes both in-process and out-of-process. + * The out-of-process handler is significantly more robust than traditional in-process + * crash handlers. This path may be relative. Point to the installed Crashpad handler + * built from the Backtrace Crashpad source. + */ +static const wchar_t CRASHPAD_HANDLER_PATH[] = L".\\handler.exe"; + + +/* + * YOU MUST CHANGE THIS VALUE. + * + * Replace "youruniverse" with the Backtrace universe name and replace the submission token. + */ +static const char BACKTRACE_SUBMIT_URL[] = "https://submit.backtrace.io/youruniverse/000000000000000000000000000000000000000000000000000000000000000/minidump"; + + +namespace backtrace { + + +static std::unique_ptr database; + -Q1: What happens if the user doesn't specify a `db_path` variable in the `CrashpadSetup.cpp`?
-A1: The Crashpad initialization code returns `-1` (error), so Crashpad won't initialize. +bool startCrashHandler() +{ + using namespace crashpad; -Q2: What is `_rxid` in the build window?
-A2: That is the result from a server when we upload archive with symbols. + + std::map annotations; + std::vector arguments = { "--no-rate-limit" }; + + + /* + * THE FOLLOWING ANNOTATIONS MUST BE SET. + * + * Backtrace supports many file formats. Set format to minidump + * so it knows how to process the incoming dump. + */ + annotations["format"] = "minidump"; + + + base::FilePath db(CRASHPAD_DATABASE_PATH); + base::FilePath handler(CRASHPAD_HANDLER_PATH); + + + database = crashpad::CrashReportDatabase::Initialize(db); + + + if (database == nullptr || database->GetSettings() == NULL) + return false; + + + /* Enable automated uploads. */ + database->GetSettings()->SetUploadsEnabled(true); + + + return CrashpadClient{}.StartHandler( + handler, db, db, BACKTRACE_SUBMIT_URL, annotations, arguments, false, false, {} + ); +} + +} +``` + +In your initialization code, +```cpp +#include “bt_crashpad.h” + +{ + … + if (backtrace::startCrashHandler() == false) + { + // crashpad failed to start + } + … +} +``` \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 09477a3f81..98542bdf99 100644 --- a/sidebars.js +++ b/sidebars.js @@ -465,8 +465,15 @@ module.exports = { 'error-reporting/platform-integrations/coresnap/setup', ], }, - 'error-reporting/platform-integrations/visual-studio', - 'error-reporting/platform-integrations/crashpad', + { + type: 'category', + label: 'Crashpad', + collapsed: true, + items: [ + 'error-reporting/platform-integrations/crashpad', + 'error-reporting/platform-integrations/visual-studio', + ], + }, 'error-reporting/platform-integrations/breakpad', 'error-reporting/platform-integrations/http-submission', ], diff --git a/static/img/error-reporting/vs-extension/5e601bc3cc2b5.png b/static/img/error-reporting/vs-extension/5e601bc3cc2b5.png deleted file mode 100644 index 88f65a5234..0000000000 Binary files a/static/img/error-reporting/vs-extension/5e601bc3cc2b5.png and /dev/null differ diff --git a/static/img/error-reporting/vs-extension/5e601bc4c83c1.png b/static/img/error-reporting/vs-extension/5e601bc4c83c1.png deleted file mode 100644 index 6c4f70ddff..0000000000 Binary files a/static/img/error-reporting/vs-extension/5e601bc4c83c1.png and /dev/null differ diff --git a/static/img/error-reporting/vs-extension/5e601bc5af052.png b/static/img/error-reporting/vs-extension/5e601bc5af052.png deleted file mode 100644 index f77f981d03..0000000000 Binary files a/static/img/error-reporting/vs-extension/5e601bc5af052.png and /dev/null differ diff --git a/static/img/error-reporting/vs-extension/5e601bc6e64ba.png b/static/img/error-reporting/vs-extension/5e601bc6e64ba.png deleted file mode 100644 index 0ea7438b34..0000000000 Binary files a/static/img/error-reporting/vs-extension/5e601bc6e64ba.png and /dev/null differ diff --git a/static/img/error-reporting/vs-extension/5e601bc7c676a.png b/static/img/error-reporting/vs-extension/5e601bc7c676a.png deleted file mode 100644 index 4f8991f69d..0000000000 Binary files a/static/img/error-reporting/vs-extension/5e601bc7c676a.png and /dev/null differ diff --git a/static/img/error-reporting/vs-extension/5e601bc9156b3.png b/static/img/error-reporting/vs-extension/5e601bc9156b3.png deleted file mode 100644 index 950561dfe6..0000000000 Binary files a/static/img/error-reporting/vs-extension/5e601bc9156b3.png and /dev/null differ diff --git a/static/img/error-reporting/vs-extension/5e601bca1b4c4.png b/static/img/error-reporting/vs-extension/5e601bca1b4c4.png deleted file mode 100644 index 7c29698fbd..0000000000 Binary files a/static/img/error-reporting/vs-extension/5e601bca1b4c4.png and /dev/null differ diff --git a/static/img/error-reporting/vs-extension/vs-include.png b/static/img/error-reporting/vs-extension/vs-include.png new file mode 100644 index 0000000000..389fbc1d82 Binary files /dev/null and b/static/img/error-reporting/vs-extension/vs-include.png differ diff --git a/static/img/error-reporting/vs-extension/vs-lang.png b/static/img/error-reporting/vs-extension/vs-lang.png new file mode 100644 index 0000000000..6a564c3f56 Binary files /dev/null and b/static/img/error-reporting/vs-extension/vs-lang.png differ diff --git a/static/img/error-reporting/vs-extension/vs-libdir.png b/static/img/error-reporting/vs-extension/vs-libdir.png new file mode 100644 index 0000000000..d8b0c1db28 Binary files /dev/null and b/static/img/error-reporting/vs-extension/vs-libdir.png differ diff --git a/static/img/error-reporting/vs-extension/vs-link.png b/static/img/error-reporting/vs-extension/vs-link.png new file mode 100644 index 0000000000..cb642c2c35 Binary files /dev/null and b/static/img/error-reporting/vs-extension/vs-link.png differ