From 9790e08969922aac26e950c2187334c601f7dfa3 Mon Sep 17 00:00:00 2001
From: Andrew Savage <andrewsavage@google.com>
Date: Wed, 30 Aug 2023 22:16:43 +0000
Subject: [PATCH] Add instructions for symbolizing crashes with container

---
 docker-compose.yml                            |  1 +
 docker/crashpad_symbolize/Dockerfile          |  1 +
 .../doc/evergreen/symbolizing_minidumps.md    | 35 ++++++++++++++++---
 3 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/docker-compose.yml b/docker-compose.yml
index 16927f33d456..3e76c14bc8c7 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -100,6 +100,7 @@ services:
   crashpad-symbolize:
     build:
       args:
+        - MINIDUMP_PATH
         - GITHUB_TAG=${GITHUB_TAG:-23.lts.5}
         - ARCHITECTURE=${ARCHITECTURE:-x64}
         - SB_API_VERSION=${SB_API_VERSION:-14}
diff --git a/docker/crashpad_symbolize/Dockerfile b/docker/crashpad_symbolize/Dockerfile
index 4284a11903df..4205ca52950a 100644
--- a/docker/crashpad_symbolize/Dockerfile
+++ b/docker/crashpad_symbolize/Dockerfile
@@ -51,4 +51,5 @@ RUN libcobalt_path=$(find /tmp/cobalt-evergreen-snapshot/ -name "libcobalt.so")
   && mkdir -p /tmp/symbols/libcobalt.so/$debug_id/ \
   && mv /tmp/libcobalt.so.sym /tmp/symbols/libcobalt.so/$debug_id/
 
+ARG MINIDUMP_PATH
 CMD breakpad/src/src/processor/minidump_stackwalk ${MINIDUMP_PATH} /tmp/symbols
diff --git a/starboard/doc/evergreen/symbolizing_minidumps.md b/starboard/doc/evergreen/symbolizing_minidumps.md
index 4931300378d6..ca887d4a52eb 100644
--- a/starboard/doc/evergreen/symbolizing_minidumps.md
+++ b/starboard/doc/evergreen/symbolizing_minidumps.md
@@ -8,7 +8,33 @@ debugging, as these minidumps have the information for the dynamic
 `libcobalt.so` module correctly mapped, which a out-of-the-box dumper could not
 manage.
 
-## Obtaining the Tools to Symbolize Minidumps
+## Symbolizing with the Provided Docker Container (Recommended)
+
+We provide a docker container at `docker/crashpad_symbolize/Dockerfile` with a
+corresponding docker-compose service, `crashpad-symbolize`, with which you can
+symbolize your minidumps.
+
+Build and run the container with:
+
+```
+MINIDUMP_PATH=/path/to/minidump_file docker-compose up --build crashpad-symbolize
+```
+
+Where `MINIDUMP_PATH` is the path to your minidump file. The service will also
+pick up environment values for `GITHUB_TAG`, `ARCHITECTURE`, `SB_API_VERSION`,
+and `CONFIG`, so ensure these are correct.
+
+* `GITHUB_TAG`: A Cobalt version with an associated release, i.e. 23.lts.5
+* `ARCHITECTURE`: One of `x64`, `x86`, `arm64`, `arm-hardfp`, or `arm-softfp`
+* `SB_API_VERSION`: The Starboard version, i.e. `15`
+* `CONFIG`: One of `release`, `qa`, or `debug`
+
+## Symbolizing Locally
+
+If you wish, you can download all the necessary tools to locally symbolize
+minidumps. This is more work than doing it with the docker container.
+
+### Obtaining the Tools to Symbolize Minidumps
 
 Tools for symbolizing these dumps are available through
 [Breakpad](https://chromium.googlesource.com/breakpad/breakpad/). Breakpad is
@@ -16,8 +42,7 @@ an open source crash reporting library that we use to obtain symbol files
 (`.sym`) from unstripped binaries, and to process the symbol files with the
 minidumps to produce human-readable stacktraces.
 
-
-### Building Breakpad
+#### Building Breakpad
 
 [Breakpad](https://chromium.googlesource.com/breakpad/breakpad/) provides
 instructions for building these tools yourself. The
@@ -51,7 +76,7 @@ building on Linux it will also build the `dump_syms` tool
 depot_tools from your `$PATH` environment variable, as it can conflict with
 Cobalt's depot_tools.
 
-## Symbolizing Minidumps
+### Symbolizing Minidumps
 
 Now that you have all the tools you need, we can symbolize the dumps. To be
 able to symbolize Cobalt using Evergreen, you need to be get the unstripped
@@ -97,7 +122,7 @@ $ /path/to/minidump_stackwalk /path/to/your/minidump.dmp symbols/
 `minidump_stackwalk` produces verbose output on stderr, and the stacktrace on
 stdout, so you may want to redirect stderr.
 
-### Addendum: Adding Other Symbols
+#### Addendum: Adding Other Symbols
 
 We can use the process above to add symbols for any library or executable you
 use, not just `libcobalt.so`. To do this, all you have to do is run the