0019-Add-a-README.md-with-notes-on-what-is-left-to-do.patch

From 021a9372d791c8620c30ad841ce293ac8d505ac4 Mon Sep 17 00:00:00 2001
From: Jon TURNEY <jon.turney@dronecode.org.uk>
Date: Wed, 5 Feb 2014 13:44:28 +0000
Subject: [PATCH 19/24] Add a README.md with notes on what is left to do

Signed-off-by: Jon TURNEY <jon.turney@dronecode.org.uk>
---
 README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6ce8836
--- /dev/null
+++ b/README.md
@@ -0,0 +1,79 @@
+# Breakpad for Cygwin/MinGW
+
+google-breakpad with support added for PE/COFF executables with DWARF debugging
+information, as used by Cygwin/MinGW
+
+## Compiling
+
+See README
+
+````
+./configure && make
+````
+
+will produce dump\_syms, minidump\_dump, minidump\_stackwalk, libbreakpad.a
+and for MinGW libcrash\_generation_client.a, libcrash\_generation_server.a, crash\_generation_app.exe
+
+Note that since git-svn ignores svn externals, this repository is missing the
+gyp and gtest dependencies.
+
+## Using
+
+See http://code.google.com/p/google-breakpad/wiki/GettingStartedWithBreakpad
+
+### Producing and installing symbols
+
+````
+dump_syms crash_generation_app.exe >crash_generation_app.sym
+FILE=`head -1 crash_generation_app.sym | cut -f5 -d' '`
+BUILDID=`head -1 crash_generation_app.sym | cut -f4 -d' '`
+SYMBOLPATH=/symbols/${FILE}/${BUILDID}/
+mdir -p ${SYMBOLPATH}
+mv crash_generation_app.sym ${SYMBOLPATH}
+````
+
+### Generating a minidump file
+
+A small test application demonstrating out-of-process dumping called
+crash\_generation\_app.exe is built.
+
+- Run it once, selecting "Server->Start" from the menu
+- Run it again, selecting "Client->Deref zero"
+- Client should crash, and a .dmp is written to C:\Dumps\
+
+### Processing the minidump to produce a stack trace
+
+````
+minidump_stackwalk blah.dmp /symbols/
+````
+
+## Issues
+
+### Lack of build-id
+
+Executables produced by Cygwin/MinGW gcc do not currently contain a build-id.
+On Windows, this build-id takes the form of a CodeView record.
+
+This build-id is captured for all modules in the process by MiniDumpWriteDump(),
+and is used by the breakpad minidump processing tools to find the matching
+symbol file.
+
+See http://debuginfo.com/articles/debuginfomatch.html
+
+I have implemented 'ld --build-id' for PE/COFF executables (See
+https://sourceware.org/ml/binutils/2014-01/msg00296.html), but you must use
+sufficently recent binutils and build with '-Wl,--build-id' (or a gcc configured
+'--enable-linker-build-id' which turns that flag on by defualt) to enable that.
+
+A tool could be written to add a build-id to existing PE/COFF executables, but in
+practice this turns out to be quite tricky...
+
+### Symbols from a PDB or the Microsoft Symbol Server
+
+<a href="http://hg.mozilla.org/users/tmielczarek_mozilla.com/fetch-win32-symbols">
+symsrv_convert</a> and dump_syms for PDB cannot be currently built with MinGW,
+because they require the MS DIA (Debug Interface Access) SDK (which is only in
+paid editions of Visual Studio) and the DIA SDK uses ATL.
+
+An alternate PDB parser is available at https://github.com/luser/dump_syms, but
+that also needs some work before it can be built with MinGW.
-- 
2.1.1