Refactoring Crashpad + uploading debug symbols

BUILD.md

@@ -13,6 +13,8 @@
     - Android Studio. Make sure to install an SDK and accept the licenses.
     - On Linux, set up environment variables for building GFXReconstruct as explained [here](https://github.com/LunarG/gfxreconstruct/blob/dev/BUILD.md#additional-linux-command-linux-prerequisites)
         - Note: Use Java 17, because this uses an older version of Gradle.
+- dump_syms, which generates debug symbols for release builds, can be installed via the [Rust installer](https://rustup.rs/). Alternatively, on Linux, you can use `sudo apt install cargo`. Also on macOS, you can use `brew install rust`. Once Cargo is set up, run the command `cargo install dump_syms`.
+- On Linux, the curl library is required to upload debug symbols to a Crashpad server. You can install it using `sudo apt install libcurl4-openssl-dev`.
 
 For MacOS, they can be installed via the brew command
 
@@ -39,6 +41,9 @@ export QTDIR=~/Qt/5.11.2/gcc_64
 export CMAKE_PREFIX_PATH=$QTDIR
 export PATH=$QTDIR:$PATH
 
+# Crashpad Symbol Upload (Required for Official Releases)
+export CRASHPAD_API_KEY=<your_api_key>
+
 # Recommended but not necessary
 export DIVE_ROOT_PATH=/path/to/dive
 ```
@@ -58,6 +63,9 @@ set QTDIR=C:\Users\name\...\Qt\5.11.2\msvc2017_64
 set CMAKE_PREFIX_PATH=%QTDIR%
 set PATH=%QTDIR%\bin;%PATH%
 
+REM Crashpad Symbol Upload (Required for Official Releases)
+set CRASHPAD_API_KEY=<your_api_key>
+
 REM Recommended but not necessary
 set DIVE_ROOT_PATH=C:\path\to\dive
 ```
@@ -83,6 +91,10 @@ export DIVE_ROOT_PATH=~/src/dive
 
 # Building Dive
 
+## Crashpad
+
+To build with Crashpad, ensure the CMake flag "DIVE_BUILD_WITH_CRASHPAD=ON" and the build type is "RelWithDebInfo".
+
 ## Dive Host Tools
 
 ### Linux and MacOS

CMakeLists.txt

@@ -38,10 +38,22 @@ if(MSVC)
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /MP")
 endif()
 set(THIRDPARTY_DIRECTORY "${CMAKE_SOURCE_DIR}/third_party")
-option(DIVE_BUILD_WITH_CRASHPAD "Build Dive with CrashPad" OFF)
 
 option(DIVE_BUILD_WITH_SANITIZER "Build Dive with sanitizers" OFF)
 
+option(DIVE_BUILD_WITH_CRASHPAD "Build Dive with Crashpad" ON)
+
+option(UPLOAD_DEBUG_SYMBOLS "Enable uploading debug symbols to Crashpad" OFF)
+if(UPLOAD_DEBUG_SYMBOLS)
+    if(NOT DIVE_BUILD_WITH_CRASHPAD)
+        message(
+            FATAL_ERROR
+            "UPLOAD_DEBUG_SYMBOLS requires DIVE_BUILD_WITH_CRASHPAD to be ON"
+        )
+    endif()
+    include(cmake/breakpad_tools.cmake)
+endif()
+
 # Placeholder value for DESTINATION to override cmake default.
 # These are all relative to the install destination prefix which is recommended as "pkg/"
 # e.g. install(TARGETS target_name DESTINATION "${DIVE_INSTALL_DEST_*}")
@@ -78,7 +90,7 @@ endif()
 set(DIVE_RELEASE_TYPE
     "dev"
     CACHE STRING
-    "Release type can be set with cmake flag -DDIVE_RELEASE_TYPE=<dev|canary|release|internal>"
+    "Release type name string (used in the Dive version string)"
 )
 string(STRIP "${DIVE_RELEASE_TYPE}" DIVE_RELEASE_TYPE)
 

cmake/breakpad_tools.cmake

@@ -0,0 +1,102 @@
+#
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+if(ANDROID)
+    message(
+        CHECK_FAIL
+        "breakpad tools including dump_syms and sym_upload are not targeted for Android."
+    )
+    return()
+endif()
+
+find_package(Python3 REQUIRED COMPONENTS Interpreter)
+
+# Locate dump_syms (External Dependency)
+# We expect the developer to have installed this via Rust (cargo install dump_syms)
+# or another method, and it must be available in the system PATH.
+
+find_program(
+    DUMP_SYMS
+    NAMES dump_syms dump_syms.exe
+    DOC "Path to the dump_syms executable"
+)
+
+if(DUMP_SYMS)
+    message(STATUS "Found dump_syms: ${DUMP_SYMS}")
+    add_executable(dump_syms IMPORTED GLOBAL)
+    set_property(TARGET dump_syms PROPERTY IMPORTED_LOCATION "${DUMP_SYMS}")
+else()
+    message(
+        FATAL_ERROR
+        "Could not find 'dump_syms' in your PATH.\n"
+        "Please install it before proceeding. The recommended way is via Rust:\n"
+        "  cargo install dump_syms\n"
+    )
+endif()
+
+# Upload debug symbols to the Crashpad server
+
+function(upload_debug_symbols TARGET_NAME)
+    set(CRASHPAD_UPLOAD_URL
+        "https://prod-crashsymbolcollector-pa.googleapis.com"
+    )
+
+    get_target_property(REAL_OUTPUT_NAME ${TARGET_NAME} OUTPUT_NAME)
+    if(NOT REAL_OUTPUT_NAME)
+        set(REAL_OUTPUT_NAME ${TARGET_NAME})
+    endif()
+
+    if(WIN32)
+        set(DEBUG_FILE "$<TARGET_PDB_FILE:${TARGET_NAME}>")
+    elseif(APPLE)
+        set(DEBUG_FILE "$<TARGET_FILE:${TARGET_NAME}>.dSYM")
+        add_custom_command(
+            TARGET ${TARGET_NAME}
+            POST_BUILD
+            COMMAND dsymutil $<TARGET_FILE:${TARGET_NAME}>
+            WORKING_DIRECTORY "${BINARY_OUTPUT_DIR}"
+            COMMENT "Generating debug symbols bundle (dSYM)"
+            VERBATIM
+        )
+    elseif(UNIX)
+        set(DEBUG_FILE "$<TARGET_FILE:${TARGET_NAME}>")
+    endif()
+
+    set(BINARY_OUTPUT_DIR "$<TARGET_FILE_DIR:${TARGET_NAME}>")
+    set(SYM_FILENAME "${REAL_OUTPUT_NAME}.sym")
+
+    add_custom_command(
+        TARGET ${TARGET_NAME}
+        POST_BUILD
+        COMMAND $<TARGET_FILE:dump_syms> ${DEBUG_FILE} > "${SYM_FILENAME}"
+        WORKING_DIRECTORY "${BINARY_OUTPUT_DIR}"
+        COMMENT "Generating debug symbols: ${BINARY_OUTPUT_DIR}/${SYM_FILENAME}"
+        VERBATIM
+    )
+
+    add_custom_command(
+        TARGET ${TARGET_NAME}
+        POST_BUILD
+        COMMAND
+            "${Python3_EXECUTABLE}"
+            "${CMAKE_SOURCE_DIR}/scripts/upload_debug_symbols_to_crashpad.py"
+            "${SYM_FILENAME}" "${CRASHPAD_UPLOAD_URL}"
+        WORKING_DIRECTORY "${BINARY_OUTPUT_DIR}"
+        COMMENT
+            "Uploading debug symbols using upload_debug_symbols_to_crashpad.py..."
+        VERBATIM
+    )
+endfunction()

scripts/upload_debug_symbols_to_crashpad.py

@@ -0,0 +1,116 @@
+#
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import argparse
+import os
+import sys
+import json
+import urllib.request
+import urllib.error
+
+def write_step(message):
+    print(f"\n[Upload debug symbols]: {message}")
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Upload Crashpad .sym files to Google Symbol Collector."
+    )
+    parser.add_argument("sym_file_path", help="Path to the .sym file")
+    parser.add_argument("upload_url", help="Base URL for the symbol collector")
+
+    args = parser.parse_args()
+
+    api_key = os.environ.get("CRASHPAD_API_KEY")
+    if not api_key:
+        raise RuntimeError("CRASHPAD_API_KEY environment variable is not set. Symbol upload will fail.")
+
+    if not os.path.exists(args.sym_file_path):
+        raise FileNotFoundError(f"Symbol file not found at {args.sym_file_path}")
+
+    with open(args.sym_file_path, 'r', encoding='utf-8', errors='ignore') as f:
+        first_line = f.readline().strip()
+
+    parts = first_line.split()
+    if len(parts) < 5:
+        raise ValueError("Invalid .sym file format. Header missing required parts.")
+
+    # Standard sym format: MODULE OS CPU ID FILENAME
+    debug_id = parts[3]
+    debug_file = parts[4]
+
+    base_url = args.upload_url.rstrip('/')
+    write_step(f"Preparing upload for {debug_file} ({debug_id})")
+
+    try:
+        create_url = f"{base_url}/v1/uploads:create?key={api_key}"
+        write_step("Requesting upload credentials...")
+
+        req = urllib.request.Request(create_url, method='POST')
+        req.add_header('Content-Length', '0')
+
+        with urllib.request.urlopen(req) as response:
+            if response.status != 200:
+                raise RuntimeError(f"Create request failed with status {response.status}")
+
+            data = json.load(response)
+            upload_url_signed = data.get('uploadUrl')
+            upload_key = data.get('uploadKey')
+
+        if not upload_url_signed or not upload_key:
+            raise ValueError(f"Server response missing credentials. Raw response: {data}")
+
+        write_step("Sending file to storage...")
+
+        with open(args.sym_file_path, 'rb') as f:
+            file_data = f.read()
+
+        req = urllib.request.Request(upload_url_signed, data=file_data, method='PUT')
+        # The server expects NO Content-Type header (or empty).
+        req.add_header('Content-Type', '') 
+
+        with urllib.request.urlopen(req) as response:
+            if response.status not in (200, 201):
+                raise RuntimeError(f"File transfer failed with status {response.status}")
+
+        write_step("Notifying collector of completion...")
+
+        complete_url = f"{base_url}/v1/uploads/{upload_key}:complete?key={api_key}"
+
+        payload = {
+            "symbol_id": {
+                "debug_file": debug_file,
+                "debug_id": debug_id
+            }
+        }
+        json_payload = json.dumps(payload).encode('utf-8')
+
+        req = urllib.request.Request(complete_url, data=json_payload, method='POST')
+        req.add_header('Content-Type', 'application/json')
+
+        with urllib.request.urlopen(req) as response:
+            if response.status != 200:
+                raise RuntimeError(f"Finalization failed with status {response.status}")
+
+        print("\n[SUCCESS] Symbol uploaded and finalized.\n")
+
+    except urllib.error.HTTPError as e:
+        try:
+            print(f"Response context: {e.read().decode('utf-8')}")
+        except Exception:
+            pass
+        raise
+
+if __name__ == "__main__":
+    main()

src/dive/CMakeLists.txt

@@ -22,4 +22,5 @@ add_subdirectory(common)
 
 if(NOT ANDROID)
     add_subdirectory(ui)
+    add_subdirectory(crash_report)
 endif()

src/dive/crash_report/CMakeLists.txt

@@ -0,0 +1,41 @@
+#
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+set(USE_CRASHPAD_CONDITION
+    $<AND:$<CONFIG:RelWithDebInfo>,$<BOOL:${DIVE_BUILD_WITH_CRASHPAD}>>
+)
+
+add_library(crash_report STATIC)
+
+target_sources(
+    crash_report
+    PRIVATE
+        absl_utils.h
+        crash_report.h
+        $<$<BOOL:${USE_CRASHPAD_CONDITION}>:crash_report_crashpad.cpp>
+        $<$<NOT:${USE_CRASHPAD_CONDITION}>:crash_report_absl.cpp>
+)
+
+target_link_libraries(
+    crash_report
+    PUBLIC absl::status
+    PRIVATE
+        absl::debugging
+        absl::symbolize
+        absl::failure_signal_handler
+        absl::strings
+        $<$<BOOL:${USE_CRASHPAD_CONDITION}>:dive_crashpad>
+)