From 332e8219ed9cdcecc587c31241caa94ed9c12c02 Mon Sep 17 00:00:00 2001 From: Mark Mentovai Date: Wed, 1 Apr 2015 12:39:53 -0400 Subject: [PATCH] Migrate content from wiki. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The wiki existed at https://code.google.com/p/crashpad/wiki, but given Google Code Project Hosting’s impending shutdown[1], it’s prudent to move wiki documents into the source code repository. This change moves the existing contents of doc into doc/support, to make way for documentation in doc. The two existing wiki pages, ProjectStatus and DevelopingCrashpad, are converted to AsciiDoc format (a fairly straightforward conversion) and checked in to doc. generate_asciidoc.sh is updated to produce HTML output from these files. The generated HTML will show up at http://docs.crashpad.googlecode.com/git/doc/. Note that generated HTML is still hosted on Google Code Project Hosting, but it’ll be easy to find a new home for them. [1] http://google-opensource.blogspot.com/2015/03/farewell-to-google-code.html R=rsesek@chromium.org Review URL: https://codereview.chromium.org/1055523002 --- crashpad.gyp | 2 +- doc/developing.ad | 213 +++++++++++++++++++++++++ doc/status.ad | 42 +++++ doc/{ => support}/asciidoc.conf | 11 +- doc/{ => support}/asciidoc.css | 0 doc/{ => support}/crashpad.doxy | 0 doc/{ => support}/crashpad.doxy.h | 0 doc/{ => support}/generate_asciidoc.sh | 90 +++++++---- doc/{ => support}/generate_doxygen.sh | 4 +- doc/{ => support}/man_footer.ad | 0 handler/mac/crashpad_handler.ad | 2 +- tools/crashpad_database_util.ad | 2 +- tools/generate_dump.ad | 2 +- tools/mac/catch_exception_tool.ad | 2 +- tools/mac/exception_port_tool.ad | 2 +- tools/mac/on_demand_service_tool.ad | 2 +- tools/mac/run_with_crashpad.ad | 2 +- 17 files changed, 333 insertions(+), 43 deletions(-) create mode 100644 doc/developing.ad create mode 100644 doc/status.ad rename doc/{ => support}/asciidoc.conf (83%) rename doc/{ => support}/asciidoc.css (100%) rename doc/{ => support}/crashpad.doxy (100%) rename doc/{ => support}/crashpad.doxy.h (100%) rename doc/{ => support}/generate_asciidoc.sh (60%) rename doc/{ => support}/generate_doxygen.sh (92%) rename doc/{ => support}/man_footer.ad (100%) diff --git a/crashpad.gyp b/crashpad.gyp index 04b4d778..fd2a2691 100644 --- a/crashpad.gyp +++ b/crashpad.gyp @@ -34,7 +34,7 @@ 'util/util_test.gyp:*', ], 'sources': [ - 'doc/crashpad.doxy.h', + 'doc/support/crashpad.doxy.h', 'package.h', ], }, diff --git a/doc/developing.ad b/doc/developing.ad new file mode 100644 index 00000000..67c3ce4d --- /dev/null +++ b/doc/developing.ad @@ -0,0 +1,213 @@ +// 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 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.” diff --git a/doc/status.ad b/doc/status.ad new file mode 100644 index 00000000..1d5933b5 --- /dev/null +++ b/doc/status.ad @@ -0,0 +1,42 @@ +// 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 + += Project Status + +== Completed + +Crashpad currently consists of a crash-reporting client and some related tools +for Mac OS X. The core client work for Mac OS X is substantially complete. +Crashpad has become the crash reporter client for +https://dev.chromium.org/Home[Chromium] on Mac OS X as of +https://chromium.googlesource.com/chromium/src/+/d413b2dcb54d523811d386f1ff4084f677a6d089[March +2015]. + +== In Progress + +Crashpad is actively being bootstrapped on +https://code.google.com/p/crashpad/issues/detail?id=1[Windows]. With the +exception of the snapshot library, most major components are now working on +Windows, and work is progressing on the Windows snapshot implementation. + +== Future + +There are plans to bring Crashpad clients to other operating systems in the +future, including +https://code.google.com/p/crashpad/issues/detail?id=30[Android] and, more +generically, Linux. There are also plans to implement a +https://code.google.com/p/crashpad/issues/detail?id=29[crash report processor] +as part of Crashpad. No timeline for completing this work has been set yet. diff --git a/doc/asciidoc.conf b/doc/support/asciidoc.conf similarity index 83% rename from doc/asciidoc.conf rename to doc/support/asciidoc.conf index ab330b34..a4ab2c4c 100644 --- a/doc/asciidoc.conf +++ b/doc/support/asciidoc.conf @@ -19,15 +19,20 @@ newline=\n # The default AsciiDoc lang-en.conf uses docdate and doctime for the # last-updated line in footer-text. These attributes are taken from the file’s # mtime and cannot be overridden. For a git-based project, the date of the last -# revision is desirable, so change this to use revdate, an attribute that can be -# computed and passed in by the script that runs AsciiDoc. For man pages, use +# revision is desirable, so change this to use git_date, an attribute that can +# be computed and passed in by the script that runs AsciiDoc. For man pages, use # the mansource and manversion attributes instead of the hard-coded “Version” # string and revnumber attribute, so that the version will appear as “Crashpad # 0.7.0” as it does in “man” output. ifdef::basebackend-html[] [footer-text] +ifdef::doctype-manpage[] {mansource=Version} {manversion={revnumber}}{basebackend-xhtml11?
}{basebackend-xhtml11=
} -Last updated {revdate} +endif::doctype-manpage[] +ifndef::doctype-manpage[] +Version {revnumber}{basebackend-xhtml11?
}{basebackend-xhtml11=
} +endif::doctype-manpage[] +Last updated {git_date} endif::basebackend-html[] # The man_link macro was inspired by git’s linkgit macro. See diff --git a/doc/asciidoc.css b/doc/support/asciidoc.css similarity index 100% rename from doc/asciidoc.css rename to doc/support/asciidoc.css diff --git a/doc/crashpad.doxy b/doc/support/crashpad.doxy similarity index 100% rename from doc/crashpad.doxy rename to doc/support/crashpad.doxy diff --git a/doc/crashpad.doxy.h b/doc/support/crashpad.doxy.h similarity index 100% rename from doc/crashpad.doxy.h rename to doc/support/crashpad.doxy.h diff --git a/doc/generate_asciidoc.sh b/doc/support/generate_asciidoc.sh similarity index 60% rename from doc/generate_asciidoc.sh rename to doc/support/generate_asciidoc.sh index f19bbb47..ea5bd467 100755 --- a/doc/generate_asciidoc.sh +++ b/doc/support/generate_asciidoc.sh @@ -21,14 +21,17 @@ set -e # toolchain including docbook-xml and docbook-xsl is also required. # Run from the Crashpad project root directory. -cd "$(dirname "${0}")/.." +cd "$(dirname "${0}")/../.." -output_dir=out/doc/man +output_dir=out/doc -rm -rf "${output_dir}" -mkdir -p \ - "${output_dir}/html" \ +rm -rf \ + "${output_dir}/doc" \ "${output_dir}/man" +mkdir -p \ + "${output_dir}/doc/html" \ + "${output_dir}/man/html" \ + "${output_dir}/man/man" # Some extensions of command-line tools behave differently on different systems. # $sed_ext should be a sed invocation that enables extended regular expressions. @@ -53,10 +56,23 @@ esac # Get the version from package.h. version=$(${sed_ext} -n -e 's/^#define PACKAGE_VERSION "(.*)"$/\1/p' package.h) -for input in \ - handler/mac/crashpad_handler.ad \ - tools/*.ad \ - tools/mac/*.ad; do +generate() { + input="$1" + type="$2" + + case "${type}" in + doc) + doctype="article" + ;; + man) + doctype="manpage" + ;; + *) + echo "${0}: unknown type ${type}" >& 2 + exit 1 + ;; + esac + echo "${input}" base=$(${sed_ext} -e 's%^.*/([^/]+)\.ad$%\1%' <<< "${input}") @@ -70,30 +86,44 @@ for input in \ --attribute mansource=Crashpad \ --attribute manversion="${version}" \ --attribute manmanual="Crashpad Manual" \ - --attribute revdate="${git_date}" \ - --conf-file doc/asciidoc.conf \ - --doctype manpage \ + --attribute git_date="${git_date}" \ + --conf-file doc/support/asciidoc.conf \ + --doctype "${doctype}" \ --backend html5 \ - --attribute stylesheet="${PWD}/doc/asciidoc.css" \ - --out-file "${output_dir}/html/${base}.html" \ + --attribute stylesheet="${PWD}/doc/support/asciidoc.css" \ + --out-file "${output_dir}/${type}/html/${base}.html" \ "${input}" - # Create “man” output. - # - # AsciiDoc 8.6.9 produces harmless incorrect warnings each time this is run: - # “a2x: WARNING: --destination-dir option is only applicable to HTML based - # outputs”. https://github.com/asciidoc/asciidoc/issues/44 - a2x \ - --attribute mansource=Crashpad \ - --attribute manversion="${version}" \ - --attribute manmanual="Crashpad Manual" \ - --attribute revdate="${git_date}" \ - --asciidoc-opts=--conf-file=doc/asciidoc.conf \ - --doctype manpage \ - --format manpage \ - --destination-dir "${output_dir}/man" \ - "${input}" + if [[ "${type}" = "man" ]]; then + # Create “man” output. + # + # AsciiDoc 8.6.9 produces harmless incorrect warnings each time this is run: + # “a2x: WARNING: --destination-dir option is only applicable to HTML based + # outputs”. https://github.com/asciidoc/asciidoc/issues/44 + a2x \ + --attribute mansource=Crashpad \ + --attribute manversion="${version}" \ + --attribute manmanual="Crashpad Manual" \ + --attribute git_date="${git_date}" \ + --asciidoc-opts=--conf-file=doc/support/asciidoc.conf \ + --doctype "${doctype}" \ + --format manpage \ + --destination-dir "${output_dir}/${type}/man" \ + "${input}" + fi # For PDF output, use an a2x command like the one above, with these options: - # --format pdf --fop --destination-dir "${output_dir}/pdf" + # --format pdf --fop --destination-dir "${output_dir}/${type}/pdf" +} + +for input in \ + doc/*.ad; do + generate "${input}" "doc" +done + +for input in \ + handler/mac/crashpad_handler.ad \ + tools/*.ad \ + tools/mac/*.ad; do + generate "${input}" "man" done diff --git a/doc/generate_doxygen.sh b/doc/support/generate_doxygen.sh similarity index 92% rename from doc/generate_doxygen.sh rename to doc/support/generate_doxygen.sh index 5da9cd31..ba565e7b 100755 --- a/doc/generate_doxygen.sh +++ b/doc/support/generate_doxygen.sh @@ -19,11 +19,11 @@ set -e # Generating Doxygen documentation requires Doxygen, http://www.doxygen.org/. # Run from the Crashpad project root directory. -cd "$(dirname "${0}")/.." +cd "$(dirname "${0}")/../.." output_dir=out/doc/doxygen rm -rf "${output_dir}" mkdir -p "${output_dir}" -doxygen doc/crashpad.doxy +doxygen doc/support/crashpad.doxy diff --git a/doc/man_footer.ad b/doc/support/man_footer.ad similarity index 100% rename from doc/man_footer.ad rename to doc/support/man_footer.ad diff --git a/handler/mac/crashpad_handler.ad b/handler/mac/crashpad_handler.ad index 85780b89..b53d0977 100644 --- a/handler/mac/crashpad_handler.ad +++ b/handler/mac/crashpad_handler.ad @@ -105,4 +105,4 @@ man_link:crashpad_database_util[1], man_link:generate_dump[1], man_link:run_with_crashpad[1] -include::../../doc/man_footer.ad[] +include::../../doc/support/man_footer.ad[] diff --git a/tools/crashpad_database_util.ad b/tools/crashpad_database_util.ad index 36b7447d..76f93e12 100644 --- a/tools/crashpad_database_util.ad +++ b/tools/crashpad_database_util.ad @@ -148,4 +148,4 @@ Failure, with a message printed to the standard error stream. man_link:crashpad_handler[8] -include::../../doc/man_footer.ad[] +include::../doc/support/man_footer.ad[] diff --git a/tools/generate_dump.ad b/tools/generate_dump.ad index 342c72d0..d8a53c8d 100644 --- a/tools/generate_dump.ad +++ b/tools/generate_dump.ad @@ -93,4 +93,4 @@ Failure, with a message printed to the standard error stream. man_link:catch_exception_tool[1] -include::../doc/man_footer.ad[] +include::../doc/support/man_footer.ad[] diff --git a/tools/mac/catch_exception_tool.ad b/tools/mac/catch_exception_tool.ad index 2d559029..a639de4c 100644 --- a/tools/mac/catch_exception_tool.ad +++ b/tools/mac/catch_exception_tool.ad @@ -114,4 +114,4 @@ Failure, with a message printed to the standard error stream. man_link:exception_port_tool[1], man_link:on_demand_service_tool[1] -include::../../doc/man_footer.ad[] +include::../../doc/support/man_footer.ad[] diff --git a/tools/mac/exception_port_tool.ad b/tools/mac/exception_port_tool.ad index e32d7197..3ef36f12 100644 --- a/tools/mac/exception_port_tool.ad +++ b/tools/mac/exception_port_tool.ad @@ -185,4 +185,4 @@ The program specified by 'COMMAND' could not be found. man_link:catch_exception_tool[1], man_link:on_demand_service_tool[1] -include::../../doc/man_footer.ad[] +include::../../doc/support/man_footer.ad[] diff --git a/tools/mac/on_demand_service_tool.ad b/tools/mac/on_demand_service_tool.ad index 5a04482a..5db4713f 100644 --- a/tools/mac/on_demand_service_tool.ad +++ b/tools/mac/on_demand_service_tool.ad @@ -99,4 +99,4 @@ man_link:catch_exception_tool[1], man_link:exception_port_tool[1], launchctl(1) -include::../../doc/man_footer.ad[] +include::../../doc/support/man_footer.ad[] diff --git a/tools/mac/run_with_crashpad.ad b/tools/mac/run_with_crashpad.ad index 7d395455..129488a3 100644 --- a/tools/mac/run_with_crashpad.ad +++ b/tools/mac/run_with_crashpad.ad @@ -109,4 +109,4 @@ The program specified by 'COMMAND' could not be found. man_link:crashpad_handler[8], man_link:exception_port_tool[1] -include::../../doc/man_footer.ad[] +include::../../doc/support/man_footer.ad[]