Commit 22afb318 authored by andybons's avatar andybons Committed by Commit bot

[Docs]: Updates to match style guide.

TBR=nodir
BUG=524256

Review URL: https://codereview.chromium.org/1314513007

Cr-Commit-Position: refs/heads/master@{#346334}
parent 9c4a5643
......@@ -9,17 +9,18 @@ instructions below for setting up either a physical device or an emulator.
In order to allow the ADB to connect to the device, you must enable USB
debugging:
* Before Android 4.1 (Jelly Bean):
* Go to "System Settings"
* Go to "Developer options"
* Check "USB debugging".
* Un-check "Verify apps over USB".
* On Jelly Bean, developer options are hidden by default. To unhide them:
* Go to "About phone"
* Tap 10 times on "Build number"
* The "Developer options" menu will now be available.
* Check "USB debugging".
* Un-check "Verify apps over USB".
* Before Android 4.1 (Jelly Bean):
* Go to "System Settings"
* Go to "Developer options"
* Check "USB debugging".
* Un-check "Verify apps over USB".
* On Jelly Bean, developer options are hidden by default. To unhide them:
* Go to "About phone"
* Tap 10 times on "Build number"
* The "Developer options" menu will now be available.
* Check "USB debugging".
* Un-check "Verify apps over USB".
### Screen
......@@ -33,7 +34,7 @@ tests will break in exciting ways if stay awake is off).
### Enable Asserts!
`adb shell setprop debug.assert 1`
adb shell setprop debug.assert 1
### Disable Verify Apps
......@@ -94,14 +95,15 @@ It may not be immediately obvious where your test code gets compiled to, so here
are some general rules:
* If your test code lives under /content, it will probably be built as part of
the content\_shell\_test\_apk * If your test code lives under /chrome (or
higher), it will probably be built as part of the chrome\_public\_test\_apk *
(Please fill in more details here if you know them).
NB: We used to call the chrome\_public\_test\_apk the
chromium\_shell\_test\_apk. There may still be references to this kicking
around, but wherever you see chromium\_shell\_test you should replace with
chrome\_public\_test.
the content_shell_test_apk
* If your test code lives under /chrome (or higher), it will probably be built
as part of the chrome_public_test_apk
* (Please fill in more details here if you know them).
NB: We used to call the chrome_public_test_apk the
chromium_shell_test_apk. There may still be references to this kicking
around, but wherever you see chromium_shell_test you should replace with
chrome_public_test.
Once you know what to build, just do it like you normally would build anything
else, e.g.: `ninja -C out/Release chrome_public_test_apk`
......
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
# ERC IRC
It's very simple to get started with ERC; just do the following:
1. Optional: Sign up at freenode.net to claim your nickname.
1. M-x
1. erc (and accept default for the first couple of items)
1. /join #chromium
1. Optional: Sign up at freenode.net to claim your nickname.
1. M-x
1. erc (and accept default for the first couple of items)
1. /join #chromium
You may notice the following problems:
* It's hard to notice when you're mentioned.
* ERC does not have built-in accidental paste prevention, so you might accidentally paste multiple lines of text into the IRC channel.
You can modify the following and add it to your .emacs file to fix both of the above. Note that you'll need to install and configure sendxmpp for the mention hack, which also requires you to create an account for your "robot" on e.g. jabber.org:
* It's hard to notice when you're mentioned.
* ERC does not have built-in accidental paste prevention, so you might
accidentally paste multiple lines of text into the IRC channel.
```
You can modify the following and add it to your .emacs file to fix both of the
above. Note that you'll need to install and configure sendxmpp for the mention
hack, which also requires you to create an account for your "robot" on e.g.
jabber.org:
```el
(require 'erc)
;; Notify me when someone mentions my nick or aliases on IRC.
......@@ -89,4 +97,6 @@ You can modify the following and add it to your .emacs file to fix both of the a
))
```
Note: The paste protection code is modified from a paste by user 'yashh' at http://paste.lisp.org/display/78068 (Google cache [here](http://webcache.googleusercontent.com/search?q=cache:p_S9ZKlWZPoJ:paste.lisp.org/display/78068+paste+78068&cd=1&hl=en&ct=clnk&gl=ca&source=www.google.ca)).
\ No newline at end of file
Note: The paste protection code is modified from a paste by user 'yashh' at
http://paste.lisp.org/display/78068 (Google cache
[here](http://webcache.googleusercontent.com/search?q=cache:p_S9ZKlWZPoJ:paste.lisp.org/display/78068+paste+78068&cd=1&hl=en&ct=clnk&gl=ca&source=www.google.ca)).
This diff is collapsed.
When UsingGit, there are a few tips that are particularly useful when working on the Chromium codebase, especially due to its size.
# Git Tips
See also GitCookbook.
When using Git, there are a few tips that are particularly useful when working
on the Chromium codebase, especially due to its size.
Remember the basic git convention:
> `git` _`COMMAND`_ `[`_`FLAGS`_`]` `[`_`ARGUMENTS`_`]`
Various git commands have underlying executable with a hyphenated name, such as `git-grep`, but these can also be called via the `git` wrapper script as `git grep` (and `man` should work either way too).
[TOC]
## Remember the basic git convention:
git COMMAND [FLAGS] [ARGUMENTS]
Various git commands have underlying executable with a hyphenated name, such as
`git-grep`, but these can also be called via the `git` wrapper script as
`git grep` (and `man` should work either way too).
## Git references
The following resources can provide background on how Git works:
* [Git-SVN Crash Course](http://git-scm.com/course/svn.html) -- this crash course is useful for Subversion users switching to Git.
* [Think Like (a) Git](http://think-like-a-git.net/) -- does a great job of explaining the main purpose of Git's operations.
* [Git User's Manual](http://schacon.github.com/git/user-manual.html) -- a great resource to learn more about how to use Git properly.
* [A Visual Git Reference](http://marklodato.github.com/visual-git-guide/index-en.html) -- a resource that explains various Git operations for visual reasons.
* [Git Cheat Sheet](http://cheat.errtheblog.com/s/git) -- now that you understand Git, here's a cheat sheet to quickly remind you of all the commands you need.
* [Git-SVN Crash Course](http://git-scm.com/course/svn.html) -- this crash
course is useful for Subversion users witching to Git.
* [Think Like (a) Git](http://think-like-a-git.net/) -- does a great job of
explaining the main purpose of Git operations.
* [Git User's Manual](http://schacon.github.com/git/user-manual.html) -- a
great resource to learn more about ho to use Git properly.
* [A Visual Git Reference](http://marklodato.github.com/visual-git-guide/index-en.html)
-- a resource that explains various Git operations for visual reasons.
* [Git Cheat Sheet](http://cheat.errtheblog.com/s/git) -- now that you
understand Git, here's a cheat sheet to quickly remind you of all the
commands you need.
## Committing changes
For a simple workflow (always commit all changed files, don't keep local revisions), the following script handles check; you may wish to call it `gci` (git commit) or similar.
Amending a single revision is generally easier for various reasons, notably for rebasing and for checking that CLs have been committed. However, if you don't use local revisions (a local branch with multiple revisions), you should make sure to upload revisions periodically to code review if you ever need to go to an old version of a CL.
```
For a simple workflow (always commit all changed files, don't keep local
revisions), the following script handles check; you may wish to call it `gci`
(git commit) or similar.
Amending a single revision is generally easier for various reasons, notably for
rebasing and for checking that CLs have been committed. However, if you don't
use local revisions (a local branch with multiple revisions), you should make
sure to upload revisions periodically to code review if you ever need to go to
an old version of a CL.
```bash
#!/bin/bash
# Commit all, amending if not initial commit.
if git status | grep -q "# Your branch is ahead of 'master' by 1 commit."
......@@ -32,24 +53,33 @@ fi
```
## Listing and changing branches
```
```shell
git branch # list branches
git checkout - # change to last branch
```
To quickly list the 5 most recent branches, add the following to `.gitconfig` in the `[alias]` section:
```
last5 = "!git for-each-ref --sort=committerdate refs/heads/ --format='%(committerdate:short) %(refname:short)' | tail -5 | cut -c 12-"
```
A nicely color-coded list, sorted in descending order by date, can be made by the following bash function:
To quickly list the 5 most recent branches, add the following to `.gitconfig`
in the `[alias]` section:
```shell
last5 = "!git for-each-ref --sort=committerdate refs/heads/ \
--format='%(committerdate:short) %(refname:short)' | tail -5 | cut -c 12-"
```
A nicely color-coded list, sorted in descending order by date, can be made by
the following bash function:
```bash
git-list-branches-by-date() {
local current_branch=$(git rev-parse --symbolic-full-name --abbrev-ref HEAD)
local normal_text=$(echo -ne '\E[0m')
local yellow_text=$(echo -ne '\E[0;33m')
local yellow_bg=$(echo -ne '\E[7;33m')
git for-each-ref --sort=-committerdate \
--format=$' %(refname:short) \t%(committerdate:short)\t%(authorname)\t%(objectname:short)' refs/heads \
--format=$' %(refname:short) \
\t%(committerdate:short)\t%(authorname)\t%(objectname:short)' \
refs/heads \
| column -t -s $'\t' -n \
| sed -E "s:^ (${current_branch}) :* ${yellow_bg}\1${normal_text} :" \
| sed -E "s:^ ([^ ]+): ${yellow_text}\1${normal_text}:"
......@@ -57,30 +87,39 @@ git-list-branches-by-date() {
```
## Searching
Use `git-grep` instead of `grep` and `git-ls-files` instead of `find`, as these search only files in the index or _tracked_ files in the work tree, rather than all files in the work tree.
Note that `git-ls-files` is rather simpler than `find`, so you'll often need to use `xargs` instead of `-exec` if you want to process matching files.
Use `git-grep` instead of `grep` and `git-ls-files` instead of `find`, as these
search only files in the index or _tracked_ files in the work tree, rather than
all files in the work tree.
Note that `git-ls-files` is rather simpler than `find`, so you'll often need to
use `xargs` instead of `-exec` if you want to process matching files.
## Global changes
To make global changes across the source tree, it's often easiest to use `sed` with `git-ls-files`, using `-i` for in-place changing (this is generally safe, as we don't use symlinks much, but there are few places that do). Remember that you don't need to use `xargs`, since sed can take multiple input files. E.g., to strip trailing whitespace from C++ and header files:
```
sed -i -E 's/\s+$//' $(git ls-files '*.cpp' '*.h')
```
You may also find `git-grep` useful for limiting the scope of your changes, using `-l` for listing files.
```
sed -i -E '...' $(git grep -lw Foo '*.cpp' '*.h')
```
To make global changes across the source tree, it's often easiest to use `sed`
with `git-ls-files`, using `-i` for in-place changing (this is generally safe,
as we don't use symlinks much, but there are few places that do). Remember that
you don't need to use `xargs`, since sed can take multiple input files. E.g., to
strip trailing whitespace from C++ and header files:
sed -i -E 's/\s+$//' $(git ls-files '*.cpp' '*.h')
You may also find `git-grep` useful for limiting the scope of your changes,
using `-l` for listing files.
sed -i -E '...' $(git grep -lw Foo '*.cpp' '*.h')
Remember that you can restrict sed actions to matching (or non-matching) lines.
For example, to skip lines with a line comment, use the following:
'\,//, ! s/foo/bar/g'
Remember that you can restrict sed actions to matching (or non-matching) lines. For example, to skip lines with a line comment, use the following:
```
'\,//, ! s/foo/bar/g'
```
## Diffs
```
git diff --shortstat
```
git diff --shortstat
Displays summary statistics, such as:
```
2104 files changed, 9309 insertions(+), 9309 deletions(-)
```
\ No newline at end of file
2104 files changed, 9309 insertions(+), 9309 deletions(-)
GN has several different ways to check dependencies. Many of them are checked by the `gn check` command. Running checks involve opening and scanning all source files so this isn't run every time a build is updated. To run check on an existing build:
```
gn check out/mybuild
```
# GN Check
To run the check as part of the "gen" command to update the build (this is what the bots do):
```
gn gen out/mybuild --check
```
GN has several different ways to check dependencies. Many of them are checked by
the `gn check` command. Running checks involve opening and scanning all source
files so this isn't run every time a build is updated. To run check on an
existing build:
gn check out/mybuild
To run the check as part of the "gen" command to update the build (this is what
the bots do):
# Concepts
gn gen out/mybuild --check
## Visibility
[TOC]
Targets can control which other targets may depend on them by specifying `visibility`. Visibility is always checked when running any GN command (not just `gn check`.
## Concepts
By default, targets are "public" meaning any target can depend on them. If you supply a list, visibility will be listed to those targets (possibly including wildcards):
### Visibility
Targets can control which other targets may depend on them by specifying
`visibility`. Visibility is always checked when running any GN command (not just
`gn check`.
By default, targets are "public" meaning any target can depend on them. If you
supply a list, visibility will be listed to those targets (possibly including
wildcards):
```
visibility = [
......@@ -26,11 +36,15 @@ visibility = [
See `gn help visibility` for more details and examples.
## Public header files
### Public header files
Targets can control which headers may be included by dependent targets so as to define a public API. If your target specifies only `sources`, then all headers listed there are public and can be included by all dependents.
Targets can control which headers may be included by dependent targets so as to
define a public API. If your target specifies only `sources`, then all headers
listed there are public and can be included by all dependents.
If your target defines a `public` variable, only the files listed in that list will be public. Files in `sources` but not `public` (they can be in both or only one) may not be included by dependent targets.
If your target defines a `public` variable, only the files listed in that list
will be public. Files in `sources` but not `public` (they can be in both or only
one) may not be included by dependent targets.
```
source_set("foo") {
......@@ -47,11 +61,15 @@ source_set("foo") {
}
```
## Public dependencies
### Public dependencies
In order to include files from your target, that target must be listed in your
target's dependencies. By default, transitively depending on a target doesn't
give your files this privilege.
In order to include files from your target, that target must be listed in your target's dependencies. By default, transitively depending on a target doesn't give your files this privilege.
If a target exposes a dependency as part of its public API, then it can list
that dependency as a `public_deps`:
If a target exposes a dependency as part of its public API, then it can list that dependency as a `public_deps`:
```
source_set("foo") {
sources = [ ... ]
......@@ -63,23 +81,32 @@ source_set("foo") {
]
}
```
Targets that depend on `foo` can include files from `base` but not from `doom_melon`. To include public headers from `doom\_melon, a target would need to depend directly on it.
Public dependencies work transitively, so listing a target as a public dependency also exposes that target's public dependencies. Along with the ability to include headers, public dependencies forward the `public_configs` which allow settings like defines and include directories to apply to dependents.
Targets that depend on `foo` can include files from `base` but not from
`doom_melon`. To include public headers from `doom\_melon, a target would need
to depend directly on it.
# Putting it all together
Public dependencies work transitively, so listing a target as a public
dependency also exposes that target's public dependencies. Along with the
ability to include headers, public dependencies forward the `public_configs`
which allow settings like defines and include directories to apply to
dependents.
## Putting it all together
In order to include a header from target Y in a file that is part of target X:
* X must be in Y's `visibility` list (or B must have no `visibility` defined).
* The header must be in Y's `public` headers (or Y must have no `public` variable defined).
* X must depend directly on Y, or there must be a path from X to Y following only public dependencies.
* X must be in Y's `visibility` list (or B must have no `visibility` defined).
* The header must be in Y's `public` headers (or Y must have no `public`
variable defined).
* X must depend directly on Y, or there must be a path from X to Y following
only public dependencies.
### What gets checked
Chrome currently doesn't come close to passing a `gn check` pass. You can check specific targets or subtrees for issues:
```
gn check out/mybuild //base
Chrome currently doesn't come close to passing a `gn check` pass. You can check
specific targets or subtrees for issues:
gn check out/mybuild //base
gn check out/mybuild "//mojo/*"
```
\ No newline at end of file
gn check out/mybuild "//mojo/*"
# Introduction
# Graphical Debugging Aid for Chromium Views
A simple debugging tool exists to help visualize the views tree during debugging. It consists of 4 components:
## Introduction
1. The function `View::PrintViewGraph()` (already in the file **view.cc** if you've sync'd recently),
1. a gdb script file **viewg.gdb** (see below),
1. the graphViz package (http://www.graphviz.org/ - downloadable for Linux, Windows and Mac), and
1. an SVG viewer (_e.g._ Chrome).
A simple debugging tool exists to help visualize the views tree during
debugging. It consists of 4 components:
# Details
1. The function `View::PrintViewGraph()` (already in the file `view.cc` if
you've sync'd recently),
1. a gdb script file `viewg.gdb` (see below),
1. the graphViz package (http://www.graphviz.org/ - downloadable for Linux,
Windows and Mac), and
1. an SVG viewer (_e.g._ Chrome).
## Details
To use the tool,
1. Make sure you have 'dot' installed (part of graphViz),
1. define `TOUCH_DEBUG` and compile chrome with Views enabled,
1. run gdb on your build and
1. source **viewg.gdb** (this can be done automatically in **.gdbinit**),
1. stop at any breakpoint inside class `View` (or any derived class), and
1. type `viewg` at the gdb prompt.
1. Make sure you have 'dot' installed (part of graphViz),
1. define `TOUCH_DEBUG` and compile chrome with Views enabled,
1. run gdb on your build and
1. `source viewg.gdb` (this can be done automatically in `.gdbinit`),
1. stop at any breakpoint inside class `View` (or any derived class), and
1. type `viewg` at the gdb prompt.
This will cause the current view, and any descendants, to be described in a graph which is stored as **~/state.svg** (Windows users may need to modify the script slightly to run under CygWin). If **state.svg** is kept open in a browser window and refreshed each time `viewg` is run, then it provides a graphical representation of the state of the views hierarchy that is always up to date.
This will cause the current view, and any descendants, to be described in a
graph which is stored as `~/state.svg` (Windows users may need to modify the
script slightly to run under CygWin). If `state.svg` is kept open in a browser
window and refreshed each time `viewg` is run, then it provides a graphical
representation of the state of the views hierarchy that is always up to date.
It is easy to modify the gdb script to generate PDF in case viewing with evince (or other PDF viewer) is preferred.
It is easy to modify the gdb script to generate PDF in case viewing with evince
(or other PDF viewer) is preferred.
If you don't use gdb, you may be able to adapt the script to work with your favorite debugger. The gdb script invokes
```
this->PrintViewGraph(true)
```
on the current object, returning `std::string`, whose contents must then be saved to a file in order to be processed by dot.
If you don't use gdb, you may be able to adapt the script to work with your
favorite debugger. The gdb script invokes
# viewg.gdb
this->PrintViewGraph(true)
on the current object, returning `std::string`, whose contents must then be
saved to a file in order to be processed by dot.
## viewg.gdb
```
define viewg
......@@ -48,4 +60,4 @@ define viewg
set pagination on
end
end
```
\ No newline at end of file
```
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment