From c41c200f93815a048dac91207a4970e94a41208b Mon Sep 17 00:00:00 2001
From: Rick Foster <115846221+rick-bt@users.noreply.github.com>
Date: Wed, 31 Jan 2024 10:48:53 -0800
Subject: [PATCH] Rick/update Crashpad Visual Studio doc (#2613)
* Replace Backtrace VS extension guide with VS integration guide
* Structured crashpad docs together, fixed sample code issue
* Improving image resolution
---
.../platform-integrations/crashpad.md | 2 +-
.../platform-integrations/visual-studio.md | 215 ++++++++++++------
sidebars.js | 11 +-
.../vs-extension/5e601bc3cc2b5.png | Bin 64753 -> 0 bytes
.../vs-extension/5e601bc4c83c1.png | Bin 69380 -> 0 bytes
.../vs-extension/5e601bc5af052.png | Bin 132265 -> 0 bytes
.../vs-extension/5e601bc6e64ba.png | Bin 60288 -> 0 bytes
.../vs-extension/5e601bc7c676a.png | Bin 117438 -> 0 bytes
.../vs-extension/5e601bc9156b3.png | Bin 77642 -> 0 bytes
.../vs-extension/5e601bca1b4c4.png | Bin 55943 -> 0 bytes
.../vs-extension/vs-include.png | Bin 0 -> 39799 bytes
.../error-reporting/vs-extension/vs-lang.png | Bin 0 -> 32241 bytes
.../vs-extension/vs-libdir.png | Bin 0 -> 33983 bytes
.../error-reporting/vs-extension/vs-link.png | Bin 0 -> 28188 bytes
14 files changed, 157 insertions(+), 71 deletions(-)
delete mode 100644 static/img/error-reporting/vs-extension/5e601bc3cc2b5.png
delete mode 100644 static/img/error-reporting/vs-extension/5e601bc4c83c1.png
delete mode 100644 static/img/error-reporting/vs-extension/5e601bc5af052.png
delete mode 100644 static/img/error-reporting/vs-extension/5e601bc6e64ba.png
delete mode 100644 static/img/error-reporting/vs-extension/5e601bc7c676a.png
delete mode 100644 static/img/error-reporting/vs-extension/5e601bc9156b3.png
delete mode 100644 static/img/error-reporting/vs-extension/5e601bca1b4c4.png
create mode 100644 static/img/error-reporting/vs-extension/vs-include.png
create mode 100644 static/img/error-reporting/vs-extension/vs-lang.png
create mode 100644 static/img/error-reporting/vs-extension/vs-libdir.png
create mode 100644 static/img/error-reporting/vs-extension/vs-link.png
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.
-})
+## 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.
+})
-**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.
- })
+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.
- })
- })
+- `$(CrashpadRoot)`
+- `$(CrashpadRoot)\third_party\mini_chromium\mini_chromium`
-**Step 3: Automated Symbol Upload**
+})
-- 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."
- })
+### 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:
+})
-
- - Add or replace the appropriate Crashpad libraries for your project.
- - Update the settings for /MD and /MT.
- - Add library paths, include paths, and libraries for the appropriate build configurations (x86_32, x64, debug, release).
-
+### 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.
-})
+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.
-})
+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
+})
-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