Move dead submodules in-tree

Signed-off-by: swurl <swurl@swurl.xyz>

externals/breakpad/docs/getting_started_with_breakpad.md

@@ -0,0 +1,115 @@
+# Introduction
+
+Breakpad is a library and tool suite that allows you to distribute an
+application to users with compiler-provided debugging information removed,
+record crashes in compact "minidump" files, send them back to your server, and
+produce C and C++ stack traces from these minidumps. Breakpad can also write
+minidumps on request for programs that have not crashed.
+
+Breakpad is currently used by Google Chrome, Firefox, Google Picasa, Camino,
+Google Earth, and other projects.
+
+![Workflow](breakpad.png)
+
+Breakpad has three main components:
+
+*   The **client** is a library that you include in your application. It can
+    write minidump files capturing the current threads' state and the identities
+    of the currently loaded executable and shared libraries. You can configure
+    the client to write a minidump when a crash occurs, or when explicitly
+    requested.
+
+*   The **symbol dumper** is a program that reads the debugging information
+    produced by the compiler and produces a **symbol file**, in [Breakpad's own
+    format](symbol_files.md).
+
+*   The **processor** is a program that reads a minidump file, finds the
+    appropriate symbol files for the versions of the executables and shared
+    libraries the minidump mentions, and produces a human-readable C/C++ stack
+    trace.
+
+# The minidump file format
+
+The minidump file format is similar to core files but was developed by Microsoft
+for its crash-uploading facility. A minidump file contains:
+
+*   A list of the executable and shared libraries that were loaded in the
+    process at the time the dump was created. This list includes both file names
+    and identifiers for the particular versions of those files that were loaded.
+
+*   A list of threads present in the process. For each thread, the minidump
+    includes the state of the processor registers, and the contents of the
+    threads' stack memory. These data are uninterpreted byte streams, as the
+    Breakpad client generally has no debugging information available to produce
+    function names or line numbers, or even identify stack frame boundaries.
+
+*   Other information about the system on which the dump was collected:
+    processor and operating system versions, the reason for the dump, and so on.
+
+Breakpad uses Windows minidump files on all platforms, instead of the
+traditional core files, for several reasons:
+
+*   Core files can be very large, making them impractical to send across a
+    network to the collector for processing. Minidumps are smaller, as they were
+    designed to be used this way.
+
+*   The core file format is poorly documented. For example, the Linux Standards
+    Base does not describe how registers are stored in `PT_NOTE` segments.
+
+*   It is harder to persuade a Windows machine to produce a core dump file than
+    it is to persuade other machines to write a minidump file.
+
+*   It simplifies the Breakpad processor to support only one file format.
+
+# Overview/Life of a minidump
+
+A minidump is generated via calls into the Breakpad library. By default,
+initializing Breakpad installs an exception/signal handler that writes a
+minidump to disk at exception time. On Windows, this is done via
+`SetUnhandledExceptionFilter()`; on OS X, this is done by creating a thread that
+waits on the Mach exception port; and on Linux, this is done by installing a
+signal handler for various exceptions like `SIGILL, SIGSEGV` etc.
+
+Once the minidump is generated, each platform has a slightly different way of
+uploading the crash dump. On Windows & Linux, a separate library of functions is
+provided that can be called into to do the upload. On OS X, a separate process
+is spawned that prompts the user for permission, if configured to do so, and
+sends the file.
+
+# Terminology
+
+**In-process vs. out-of-process exception handling** - it's generally considered
+that writing the minidump from within the crashed process is unsafe - key
+process data structures could be corrupted, or the stack on which the exception
+handler runs could have been overwritten, etc. All 3 platforms support what's
+known as "out-of-process" exception handling.
+
+# Integration overview
+
+## Breakpad Code Overview
+
+All the client-side code is found by visiting the Google Project at
+https://chromium.googlesource.com/breakpad/breakpad. The following directory structure is
+present in the `src` directory:
+
+*   `processor` Contains minidump-processing code that is used on the server
+    side and isn't of use on the client side
+*   `client` Contains client minidump-generation libraries for all platforms
+*   `tools` Contains source code & projects for building various tools on each
+    platform.
+
+(Among other directories)
+
+*   [Windows Integration Guide](windows_client_integration.md)
+*   [Mac Integration Guide](mac_breakpad_starter_guide.md)
+*   [Linux Integration Guide](linux_starter_guide.md)
+
+## Build process specifics(symbol generation)
+
+This applies to all platforms. Inside `src/tools/{platform}/dump_syms` is a tool
+that can read debugging information for each platform (e.g. for OS X/Linux,
+DWARF and STABS, and for Windows, PDB files) and generate a Breakpad symbol
+file. This tool should be run on your binary before it's stripped(in the case of
+OS X/Linux) and the symbol files need to be stored somewhere that the minidump
+processor can find. There is another tool, `symupload`, that can be used to
+upload symbol files if you have written a server that can accept them.