Skip to content

Commit 3700055

Browse files
illwieckzillwieckz
committed
readme: update
1 parent fd6cc4c commit 3700055

File tree

1 file changed

+69
-111
lines changed

1 file changed

+69
-111
lines changed

‎README.md‎

Lines changed: 69 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,82 @@
1-
# Breakpad for Cygwin/MinGW
1+
# Breakpad for MinGW and more
22

3-
[![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)
3+
Google Breakpad with added support for MinGW, maintained for the
4+
[Dæmon game engine](https://github.com/DaemonEngine/Daemon) and the
5+
[Unvanquished game](https://unvanquished.net).
6+
7+
- Upstream for the Dæmon branch: https://github.com/DaemonEngine/breakpad
8+
- Bug tracker for the Dæmon branch: https://github.com/DaemonEngine/breakpad/issues
9+
10+
11+
## Dæmon Breakpad
12+
13+
Breakpad is a set of client and server components which implement a crash-reporting system.
14+
15+
The Dæmon Breakpad adds Cygwin/MinGW support to Google Breakpad, based on Jon Turney's patches,
16+
with merged Google upstream adding support for DWARF5 debugging information format.
17+
It retains the support for systems already supported by the Google Breakpad upstream.
18+
19+
It provides:
420

5-
google-breakpad with added support for Cygwin/MinGW:
621
- A `dump_syms` tool which can read DWARF debugging information from PE/COFF executables.
722
- The breakpad crash-reporting client libraries built using Makefiles rather than MSVC solutions.
823

24+
925
## Compiling
1026

1127
### Preparation
1228

13-
Run the fetch-externals script to fetch submodules in the DEPS file (e.g the gyp and gtest dependencies).
14-
(The upsteam repository is meant to be checked out using Chromium's `depot_tools`, which does this for you)
29+
Optional: Run the fetch-externals script to fetch submodules in the DEPS file (e.g the gyp and gtest dependencies).
30+
(The Google upsteam repository is meant to be checked out using Chromium's `depot_tools`, which does this for you).
31+
This is not needed to build Breakpad.
1532

16-
```
33+
```sh
1734
./fetch-externals
1835
```
1936

20-
Run autoreconf to generate ./configure
37+
### Building
38+
39+
💡️ Instead of `-j4` you can use `-jN` where `N` is your number of CPU cores to distribute compilation on them.
40+
Linux systems usually provide a handy `nproc` tool that tells the number of CPU core so you can just do `-j$(nproc)`
41+
to use all available cores.
2142

22-
````
43+
Run `autoreconf` to generate `./configure`:
44+
45+
```sh
2346
autoreconf -fvi
24-
````
47+
```
48+
Run `./configure` to configure the build:
2549

26-
### Compiling
50+
```sh
51+
./configure
52+
```
2753

28-
See README.orig.md
54+
Run `make` to build:
2955

30-
````
31-
./configure && make
32-
````
56+
```sh
57+
make -j4
58+
```
3359

34-
will produce `dump_syms.exe`, `minidump_dump.exe`, `minidump_stackwalk.exe`, `libbreakpad.a`,
60+
This will produce `dump_syms.exe`, `minidump_dump.exe`, `minidump_stackwalk.exe`, `libbreakpad.a`,
3561
and for MinGW `libcrash_generation_client.a`, `libcrash_generation_server.a`, `crash_generation_app.exe`
3662

63+
The `dump_syms` tool to process Linux binaries can be found as `src/tools/linux/dump_syms/dump_syms` and the one to process MinGW binaries can be found as `src/tools/windows/dump_syms_dwarf/dump_syms`.
64+
65+
3766
## Using
3867

39-
See [Getting started with breakpad](https://chromium.googlesource.com/breakpad/breakpad/+/master/docs/getting_started_with_breakpad.md)
68+
See [Getting started with breakpad](https://chromium.googlesource.com/breakpad/breakpad/+/master/docs/getting_started_with_breakpad.md) in Chromium documentation.
4069

4170
### Producing and installing symbols
4271

43-
````
72+
```sh
4473
dump_syms crash_generation_app.exe >crash_generation_app.sym
4574
FILE=`head -1 crash_generation_app.sym | cut -f5 -d' '`
4675
BUILDID=`head -1 crash_generation_app.sym | cut -f4 -d' '`
4776
SYMBOLPATH=/symbols/${FILE}/${BUILDID}/
4877
mkdir -p ${SYMBOLPATH}
4978
mv crash_generation_app.sym ${SYMBOLPATH}
50-
````
79+
```
5180

5281
### Generating a minidump file
5382

@@ -56,123 +85,52 @@ A small test application demonstrating out-of-process dumping called
5685

5786
- Run it once, selecting "Server->Start" from the menu
5887
- Run it again, selecting "Client->Deref zero"
59-
- Client should crash, and a .dmp is written to C:\Dumps\
88+
- Client should crash, and a `.dmp` is written to `C:\Dumps\`
6089

6190
### Processing the minidump to produce a stack trace
6291

63-
````
92+
```sh
6493
minidump_stackwalk blah.dmp /symbols/
65-
````
94+
```
95+
6696

6797
## Issues
6898

6999
### Lack of build-id
70100

71101
On Windows, the build-id takes the form of a CodeView record.
72-
This build-id is captured for all modules in the process by MiniDumpWriteDump(),
102+
This build-id is captured for all modules in the process by `MiniDumpWriteDump()`,
73103
and is used by the breakpad minidump processing tools to find the matching
74104
symbol file.
75105

76-
See http://debuginfo.com/articles/debuginfomatch.html
106+
See <http://debuginfo.com/articles/debuginfomatch.html>.
77107

78-
I have implemented 'ld --build-id' for PE/COFF executables (See
79-
https://sourceware.org/ml/binutils/2014-01/msg00296.html), but you must use a
80-
sufficently recent version of binutils (2.25 or later) and build with
81-
'-Wl,--build-id' (or a gcc configured with '--enable-linker-build-id', which
108+
I (Jon Turney) have implemented `ld --build-id` for PE/COFF executables (See
109+
<https://sourceware.org/ml/binutils/2014-01/msg00296.html>), but you must use a
110+
sufficently recent version of `binutils` (2.25 or later) and build with
111+
`-Wl,--build-id`' (or a GCC configured with `--enable-linker-build-id`, which
82112
turns that flag on by default) to enable that.
83113

84114
A tool could be written to add a build-id to existing PE/COFF executables, but in
85115
practice this turns out to be quite tricky...
86116

87117
### Symbols from a PDB or the Microsoft Symbol Server
88118

89-
<a href="http://hg.mozilla.org/users/tmielczarek_mozilla.com/fetch-win32-symbols">
90-
symsrv_convert</a> and dump_syms for PDB cannot be currently built with MinGW,
91-
because (i) they require the MS DIA (Debug Interface Access) SDK (only in paid
92-
editions of Visual Studio 2013), and (ii) the DIA SDK uses ATL.
119+
[`symsrv_convert`](http://hg.mozilla.org/users/tmielczarek_mozilla.com/fetch-win32-symbols")
120+
and `dump_syms` for PDB cannot be currently built with MinGW,
121+
because
93122

94-
An alternate PDB parser is available at https://github.com/luser/dump_syms, but
95-
that also needs some work before it can be built with MinGW.
123+
1. they require the MS DIA (Debug Interface Access) SDK (only in paid
124+
editions of Visual Studio 2013),
125+
2. the DIA SDK uses ATL.
96126

97-
# Breakpad
127+
An alternate PDB parser is available at <https://github.com/luser/dump_syms>, but
128+
that also needs some work before it can be built with MinGW.
98129

99-
Breakpad is a set of client and server components which implement a
100-
crash-reporting system.
130+
## Upstream Breakpad
101131

102-
* [Homepage](https://chromium.googlesource.com/breakpad/breakpad/)
103-
* [Documentation](https://chromium.googlesource.com/breakpad/breakpad/+/master/docs/)
104-
* [Bugs](https://bugs.chromium.org/p/google-breakpad/)
132+
* Homepage: https://chromium.googlesource.com/breakpad/breakpad/
133+
* Documentation: https://chromium.googlesource.com/breakpad/breakpad/+/master/docs/
134+
* Bugs: https://bugs.chromium.org/p/google-breakpad/
105135
* Discussion/Questions: [google-breakpad-discuss@googlegroups.com](https://groups.google.com/d/forum/google-breakpad-discuss)
106136
* 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)
113-
and ensure that they’re in your `PATH`.
114-
115-
2. Create a new directory for checking out the source code (it must be named
116-
breakpad).
117-
118-
```sh
119-
mkdir breakpad && cd breakpad
120-
```
121-
122-
3. Run the `fetch` tool from depot_tools to download all the source repos.
123-
124-
```sh
125-
fetch breakpad
126-
cd src
127-
```
128-
129-
4. Build the source.
130-
131-
```sh
132-
./configure && make
133-
```
134-
135-
You can also cd to another directory and run configure from there to build
136-
outside the source tree.
137-
138-
This will build the processor tools (`src/processor/minidump_stackwalk`,
139-
`src/processor/minidump_dump`, etc), and when building on Linux it will
140-
also build the client libraries and some tools
141-
(`src/tools/linux/dump_syms/dump_syms`,
142-
`src/tools/linux/md2core/minidump-2-core`, etc).
143-
144-
5. Optionally, run tests.
145-
146-
```sh
147-
make check
148-
```
149-
150-
6. Optionally, install the built libraries
151-
152-
```sh
153-
make install
154-
```
155-
156-
If you need to reconfigure your build be sure to run `make distclean` first.
157-
158-
To update an existing checkout to a newer revision, you can
159-
`git pull` as usual, but then you should run `gclient sync` to ensure that the
160-
dependent repos are up-to-date.
161-
162-
## To request change review
163-
164-
1. Follow the steps above to get the source and build it.
165-
166-
2. Make changes. Build and test your changes.
167-
For core code like processor use methods above.
168-
For linux/mac/windows, there are test targets in each project file.
169-
170-
3. Commit your changes to your local repo and upload them to the server.
171-
http://dev.chromium.org/developers/contributing-code
172-
e.g. `git commit ... && git cl upload ...`
173-
You will be prompted for credential and a description.
174-
175-
4. At https://chromium-review.googlesource.com/ you'll find your issue listed;
176-
click on it, then “Add reviewer”, and enter in the code reviewer. Depending
177-
on your settings, you may not see an email, but the reviewer has been
178-
notified with google-breakpad-dev@googlegroups.com always CC’d.

0 commit comments

Comments
 (0)