mirror of
https://github.com/chromium/crashpad.git
synced 2024-12-27 15:32:10 +08:00
53ccd8fc5e
Having two ~s in one block confused doc generation. R=rsesek@chromium.org Review URL: https://codereview.chromium.org/1413203002 .
216 lines
7.5 KiB
Plaintext
216 lines
7.5 KiB
Plaintext
// Copyright 2015 The Crashpad Authors. All rights reserved.
|
||
//
|
||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||
// you may not use this file except in compliance with the License.
|
||
// You may obtain a copy of the License at
|
||
//
|
||
// http://www.apache.org/licenses/LICENSE-2.0
|
||
//
|
||
// Unless required by applicable law or agreed to in writing, software
|
||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
// See the License for the specific language governing permissions and
|
||
// limitations under the License.
|
||
|
||
:doctype: article
|
||
|
||
= Developing Crashpad
|
||
|
||
== Status
|
||
|
||
link:status.html[Project status] information has moved to its own page.
|
||
|
||
== Introduction
|
||
|
||
Crashpad is a https://dev.chromium.org/Home[Chromium project]. Most of
|
||
its development practices follow Chromium’s. In order to function on its
|
||
own in other projects, Crashpad uses
|
||
https://chromium.googlesource.com/chromium/mini_chromium/[mini_chromium],
|
||
a small, self-contained library that provides many of Chromium’s useful
|
||
low-level base routines.
|
||
https://chromium.googlesource.com/chromium/mini_chromium/+/master/README[mini_chromium’s
|
||
README] provides more detail.
|
||
|
||
== Prerequisites
|
||
|
||
To develop Crashpad, the following tools are necessary, and must be
|
||
present in the `$PATH` environment variable:
|
||
|
||
* Chromium’s
|
||
https://dev.chromium.org/developers/how-tos/depottools[depot_tools].
|
||
* http://git-scm.com/[Git]. This is provided by Xcode on Mac OS X and by
|
||
depot_tools on Windows.
|
||
* https://www.python.org/[Python]. This is provided by the operating system on
|
||
Mac OS X, and by depot_tools on Windows.
|
||
* Appropriate development tools. For Mac OS X, this is
|
||
https://developer.apple.com/xcode/[Xcode], and for Windows, it’s
|
||
https://www.visualstudio.com/[Visual Studio].
|
||
|
||
== Getting the Source Code
|
||
|
||
The main source code repository is a Git repository hosted at
|
||
https://chromium.googlesource.com/crashpad/crashpad. Although it is possible to
|
||
check out this repository directly with `git clone`, Crashpad’s dependencies are
|
||
managed by
|
||
https://dev.chromium.org/developers/how-tos/depottools#TOC-gclient[`gclient`]
|
||
instead of Git submodules, so to work on Crashpad, it is best to use `fetch` to
|
||
get the source code.
|
||
|
||
`fetch` and `gclient` are part of the
|
||
https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. There’s no
|
||
need to install them separately.
|
||
|
||
=== Initial Checkout
|
||
|
||
[subs="verbatim,quotes"]
|
||
----
|
||
$ *mkdir \~/crashpad*
|
||
$ *cd ~/crashpad*
|
||
$ *fetch crashpad*
|
||
----
|
||
|
||
`fetch crashpad` performs the initial `gclient sync`, establishing a
|
||
fully-functional local checkout.
|
||
|
||
=== Subsequent Checkouts
|
||
|
||
[subs="verbatim,quotes"]
|
||
----
|
||
$ *cd ~/crashpad/crashpad*
|
||
$ *git pull -r*
|
||
$ *gclient sync*
|
||
----
|
||
|
||
== Building
|
||
|
||
Crashpad uses https://gyp.googlecode.com/[GYP] to generate
|
||
https://martine.github.io/ninja/[Ninja] build files. The build is described by
|
||
`.gyp` files throughout the Crashpad source code tree. The
|
||
`build/gyp_crashpad.py` script runs GYP properly for Crashpad, and is also
|
||
called when you run `fetch crashpad`, `gclient sync`, or `gclient runhooks`.
|
||
|
||
The Ninja build files and build output are in the `out` directory. Both debug-
|
||
and release-mode configurations are available. The examples below show the debug
|
||
configuration. To build and test the release configuration, substitute `Release`
|
||
for `Debug`.
|
||
|
||
[subs="verbatim,quotes"]
|
||
----
|
||
$ *cd ~/crashpad/crashpad*
|
||
$ *ninja -C out/Debug*
|
||
----
|
||
|
||
Ninja is part of the
|
||
https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. There’s no
|
||
need to install it separately.
|
||
|
||
== Testing
|
||
|
||
Crashpad uses https://googletest.googlecode.com/[Google Test] as its
|
||
unit-testing framework, and some tests use
|
||
https://googlemock.googlecode.com/[Google Mock] as well. Its tests are currently
|
||
split up into several test executables, each dedicated to testing a different
|
||
component. This may change in the future. After a successful build, the test
|
||
executables will be found at `out/Debug/crashpad_*_test`.
|
||
|
||
[subs="verbatim,quotes"]
|
||
----
|
||
$ *cd ~/crashpad/crashpad*
|
||
$ *out/Debug/crashpad_minidump_test*
|
||
$ *out/Debug/crashpad_util_test*
|
||
----
|
||
|
||
A script is provided to run all of Crashpad’s tests. It accepts a single
|
||
argument that tells it which configuration to test.
|
||
|
||
[subs="verbatim,quotes"]
|
||
----
|
||
$ *cd ~/crashpad/crashpad*
|
||
$ *python build/run_tests.py Debug*
|
||
----
|
||
|
||
== Contributing
|
||
|
||
Crashpad’s contribution process is very similar to
|
||
https://dev.chromium.org/developers/contributing-code[Chromium’s contribution
|
||
process].
|
||
|
||
=== Code Review
|
||
|
||
A code review must be conducted for every change to Crashpad’s source code. Code
|
||
review is conducted on https://codereview.chromium.org/[Chromium’s Rietveld]
|
||
system, and all code reviews must be sent to an appropriate reviewer, with a Cc
|
||
sent to
|
||
https://groups.google.com/a/chromium.org/group/crashpad-dev[crashpad-dev]. The
|
||
`codereview.settings` file specifies this environment to `git-cl`.
|
||
|
||
`git-cl` is part of the
|
||
https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. There’s no
|
||
need to install it separately.
|
||
|
||
[subs="verbatim,quotes"]
|
||
----
|
||
$ *cd ~/crashpad/crashpad*
|
||
$ *git checkout -b work_branch origin/master*
|
||
_…do some work…_
|
||
$ *git add …*
|
||
$ *git commit*
|
||
$ *git cl upload*
|
||
----
|
||
|
||
Uploading a patch to Rietveld does not automatically request a review. You must
|
||
select a reviewer and mail your request to them (with a Cc to crashpad-dev) from
|
||
the Rietveld issue page after running `git cl upload`. If you have lost track of
|
||
the issue page, `git cl issue` will remind you of its URL. Alternatively, you
|
||
can request review when uploading to Rietveld by using `git cl upload
|
||
--send-mail`
|
||
|
||
Git branches maintain their association with Rietveld issues, so if you need to
|
||
make changes based on review feedback, you can do so on the correct Git branch,
|
||
committing your changes locally with `git commit`. You can then upload a new
|
||
patch set with `git cl upload` and let your reviewer know you’ve addressed the
|
||
feedback.
|
||
|
||
=== Landing Changes
|
||
|
||
After code review is complete and “LGTM” (“looks good to me”) has been received
|
||
from all reviewers, project members can commit the patch themselves:
|
||
|
||
[subs="verbatim,quotes"]
|
||
----
|
||
$ *cd ~/crashpad/crashpad*
|
||
$ *git checkout work_branch*
|
||
$ *git cl land*
|
||
----
|
||
|
||
Crashpad does not currently have a
|
||
https://dev.chromium.org/developers/testing/commit-queue[commit queue], so
|
||
contributors that are not project members will have to ask a project member to
|
||
commit the patch for them. Project members can commit changes on behalf of
|
||
external contributors by patching the change into a local branch and landing it:
|
||
|
||
[subs="verbatim,quotes"]
|
||
----
|
||
$ *cd ~/crashpad/crashpad*
|
||
$ *git checkout -b for_external_contributor origin/master*
|
||
$ *git cl patch 12345678* _# 12345678 is the Rietveld issue number_
|
||
$ *git cl land -c \'External Contributor <external@contributor.org>'*
|
||
----
|
||
|
||
=== External Contributions
|
||
|
||
Copyright holders must complete the
|
||
https://developers.google.com/open-source/cla/individual[Individual Contributor
|
||
License Agreement] or
|
||
https://developers.google.com/open-source/cla/corporate[Corporate Contributor
|
||
License Agreement] as appropriate before any submission can be accepted, and
|
||
must be listed in the `AUTHORS` file. Contributors may be listed in the
|
||
`CONTRIBUTORS` file.
|
||
|
||
== Buildbot
|
||
|
||
The https://build.chromium.org/p/client.crashpad/[Crashpad Buildbot] performs
|
||
automated builds and tests of Crashpad. Before checking out or updating the
|
||
Crashpad source code, and after checking in a new change, it is prudent to check
|
||
the Buildbot to ensure that “the tree is green.”
|