README.md 6.16 KB
Newer Older
Jon Turney's avatar
Jon Turney committed
1 2
# Breakpad for Cygwin/MinGW

3 4
[![Build status](https://ci.appveyor.com/api/projects/status/xp2os1r0m569a470/branch/pecoff-dwarf-on-git-20160304?svg=true)](https://ci.appveyor.com/project/jon-turney/google-breakpad)

Jon Turney's avatar
Jon Turney committed
5 6 7 8 9 10 11 12
google-breakpad with added support for Cygwin/MinGW:
- A `dump_syms` tool which can read DWARF debugging information from PE/COFF executables.
- The breakpad crash-reporting client libraries built using Makefiles rather than MSVC solutions.

## Compiling

### Preparation

13 14 15 16 17 18 19
Run the fetch-externals script to fetch submodules in the DEPS file (e.g the gyp and gtest dependencies).
(The upsteam repository is meant to be checked out using Chromium's `depot_tools`, which does this for you)

```
./fetch-externals
```

Jon Turney's avatar
Jon Turney committed
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
Run autoreconf to generate ./configure

````
autoreconf -fvi
````

### Compiling

See README.orig.md

````
./configure && make
````

will produce `dump_syms.exe`, `minidump_dump.exe`, `minidump_stackwalk.exe`, `libbreakpad.a`,
and for MinGW `libcrash_generation_client.a`, `libcrash_generation_server.a`, `crash_generation_app.exe`

## Using

See [Getting started with breakpad](https://chromium.googlesource.com/breakpad/breakpad/+/master/docs/getting_started_with_breakpad.md)

### 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}/
mkdir -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

On Windows, the 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 a
sufficently recent version of binutils (2.25 or later) and build with
'-Wl,--build-id' (or a gcc configured with '--enable-linker-build-id', which
turns that flag on by default) 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 (i) they require the MS DIA (Debug Interface Access) SDK (only in paid
editions of Visual Studio 2013), and (ii) 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.

97 98 99 100 101
# Breakpad

Breakpad is a set of client and server components which implement a
crash-reporting system.

102 103 104 105 106
* [Homepage](https://chromium.googlesource.com/breakpad/breakpad/)
* [Documentation](https://chromium.googlesource.com/breakpad/breakpad/+/master/docs/)
* [Bugs](https://bugs.chromium.org/p/google-breakpad/)
* Discussion/Questions: [google-breakpad-discuss@googlegroups.com](https://groups.google.com/d/forum/google-breakpad-discuss)
* Developer/Reviews: [google-breakpad-dev@googlegroups.com](https://groups.google.com/d/forum/google-breakpad-dev)
107
* Tests: [![Build Status](https://travis-ci.org/google/breakpad.svg?branch=master)](https://travis-ci.org/google/breakpad) [![Build status](https://ci.appveyor.com/api/projects/status/eguv4emv2rhq68u2?svg=true)](https://ci.appveyor.com/project/vapier/breakpad)
108
* Coverage [![Coverity Status](https://scan.coverity.com/projects/9215/badge.svg)](https://scan.coverity.com/projects/google-breakpad)
109

110
## Getting started (from master)
111

112
1.  First, [download depot_tools](http://dev.chromium.org/developers/how-tos/install-depot-tools)
Mark Mentovai's avatar
Mark Mentovai committed
113
    and ensure that they’re in your `PATH`.
114

115 116
2.  Create a new directory for checking out the source code (it must be named
    breakpad).
117

118
    ```sh
119
    mkdir breakpad && cd breakpad
120
    ```
121 122 123

3.  Run the `fetch` tool from depot_tools to download all the source repos.

124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166
    ```sh
    fetch breakpad
    cd src
    ```

4.  Build the source.

    ```sh
    ./configure && make
    ```

    You can also cd to another directory and run configure from there to build
    outside the source tree.

    This will build the processor tools (`src/processor/minidump_stackwalk`,
    `src/processor/minidump_dump`, etc), and when building on Linux it will
    also build the client libraries and some tools
    (`src/tools/linux/dump_syms/dump_syms`,
    `src/tools/linux/md2core/minidump-2-core`, etc).

5.  Optionally, run tests.

    ```sh
    make check
    ```

6.  Optionally, install the built libraries

    ```sh
    make install
    ```

If you need to reconfigure your build be sure to run `make distclean` first.

To update an existing checkout to a newer revision, you can
`git pull` as usual, but then you should run `gclient sync` to ensure that the
dependent repos are up-to-date.

## To request change review

1.  Follow the steps above to get the source and build it.

2.  Make changes. Build and test your changes.
167 168 169
    For core code like processor use methods above.
    For linux/mac/windows, there are test targets in each project file.

170
3.  Commit your changes to your local repo and upload them to the server.
171 172 173 174
    http://dev.chromium.org/developers/contributing-code
    e.g. `git commit ... && git cl upload ...`
    You will be prompted for credential and a description.

175 176 177 178
4.  At https://chromium-review.googlesource.com/ you'll find your issue listed;
    click on it, then “Add reviewer”, and enter in the code reviewer. Depending
    on your settings, you may not see an email, but the reviewer has been
    notified with google-breakpad-dev@googlegroups.com always CC’d.