crashpad/doc/developing.ad

// 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 `gclient`
to get the source code.

`gclient` is part of the
https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. There’s no
need to install it separately.

=== Initial Checkout

[subs="verbatim,quotes"]
----
$ *mkdir \~/crashpad*
$ *cd ~/crashpad*
$ *gclient config --unmanaged https://chromium.googlesource.com/crashpad/crashpad*
$ *gclient sync*
----

=== 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 `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.”