0

Make some small tweaks to the build instructions.

- Standardize on fenced code blocks, add 'shell' where appropriate.
- Add '$' to shell commands where missing.
- Add `code` marks to more identifiers.
- Minor stylistic/grammatical suggestions.

R=dpranke@chromium.org, teresam@google.com

Review-Url: https://codereview.chromium.org/2536723008
Cr-Commit-Position: refs/heads/master@{#435508}
This commit is contained in:
sdy
2016-11-30 17:03:44 -08:00
committed by Commit bot
parent ceea98f08d
commit 93387fa96a
10 changed files with 482 additions and 344 deletions

@ -14,137 +14,163 @@ Google employee? See [go/building-chrome](https://goto.google.com/building-chrom
* You must have Git and Python installed already.
Most development is done on Ubuntu. Other distros may or may not work;
see the [linux instructions](linux_build_instructions.md) for some suggestions.
see the [Linux instructions](linux_build_instructions.md) for some suggestions.
Building the Android client on Windows or Mac is not supported and doesn't work.
## Install `depot_tools`
Clone the depot_tools repository:
Clone the `depot_tools` repository:
$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
```shell
$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
```
Add depot_tools to the end of your PATH (you will probably want to put this
in your ~/.bashrc or ~/.zshrc). Assuming you cloned depot_tools
to /path/to/depot_tools:
Add `depot_tools` to the end of your PATH (you will probably want to put this
in your `~/.bashrc` or `~/.zshrc`). Assuming you cloned `depot_tools`
to `/path/to/depot_tools`:
$ export PATH=$PATH:/path/to/depot_tools
```shell
$ export PATH="$PATH:/path/to/depot_tools"
```
## Get the code
Create a chromium directory for the checkout and change to it (you can call
Create a `chromium` directory for the checkout and change to it (you can call
this whatever you like and put it wherever you like, as
long as the full path has no spaces):
$ mkdir ~/chromium && cd ~/chromium
$ fetch --nohooks android
```shell
$ mkdir ~/chromium && cd ~/chromium
$ fetch --nohooks android
```
If you don't want the full repo history, you can save a lot of time by
adding the `--no-history` flag to fetch.
adding the `--no-history` flag to `fetch`.
Expect the command to take 30 minutes on even a fast connection, and many
hours on slower ones.
If you've already installed the build dependencies on the machine (from another
checkout, for example), you can omit the `--nohooks` flag and fetch
checkout, for example), you can omit the `--nohooks` flag and `fetch`
will automatically execute `gclient runhooks` at the end.
When fetch completes, it will have created a directory called `src`.
The remaining instructions assume you are now in that directory:
When `fetch` completes, it will have created a hidden `.gclient` file and a
directory called `src` in the working directory. The remaining instructions
assume you have switched to the `src` directory:
$ cd src
```shell
$ cd src
```
### Converting an existing Linux checkout
If you have an existing Linux checkout, you can add Android support by
appending `target_os = ['android']` to your .gclient file (in the
directory above src):
appending `target_os = ['android']` to your `.gclient` file (in the
directory above `src`):
$ echo "target_os = [ 'android' ]" >> ../.gclient
```shell
$ echo "target_os = [ 'android' ]" >> ../.gclient
```
Then run gclient sync to pull the new Android dependencies:
Then run `gclient sync` to pull the new Android dependencies:
gclient sync
```shell
$ gclient sync
```
(This is actually the difference between `fetch android` and `fetch chromium`).
(This is the only difference between `fetch android` and `fetch chromium`.)
### Install additional build dependencies
Once you have checked out the code, run
build/install-build-deps-android.sh
```shell
$ build/install-build-deps-android.sh
```
to get all of the dependencies you need to build on Linux *plus* all of the
to get all of the dependencies you need to build on Linux, *plus* all of the
Android-specific dependencies (you need some of the regular Linux dependencies
because an Android build builds a bunch of the Linux tools and utilities).
because an Android build includes a bunch of the Linux tools and utilities).
### Run the hooks
Once you've run `install-build-deps` at least once, you can now run the
chromium-specific hooks, which will download additional binaries and other
Chromium-specific hooks, which will download additional binaries and other
things you might need:
$ gclient runhooks
```shell
$ gclient runhooks
```
*Optional*: You can also [install API keys](https://www.chromium.org/developers/how-tos/api-keys)
if you want to talk to some of the Google services, but this is not necessary
for most development and testing purposes.
*Optional*: You can also [install API
keys](https://www.chromium.org/developers/how-tos/api-keys) if you want your
build to talk to some Google services, but this is not necessary for most
development and testing purposes.
### Configure the JDK
Make also sure that OpenJDK 1.7 is selected as default:
`sudo update-alternatives --config javac`
`sudo update-alternatives --config java`
`sudo update-alternatives --config javaws`
`sudo update-alternatives --config javap`
`sudo update-alternatives --config jar`
`sudo update-alternatives --config jarsigner`
```shell
$ sudo update-alternatives --config javac
$ sudo update-alternatives --config java
$ sudo update-alternatives --config javaws
$ sudo update-alternatives --config javap
$ sudo update-alternatives --config jar
$ sudo update-alternatives --config jarsigner
```
## Setting up the Build
Chromium uses [Ninja](https://ninja-build.org) as its main build tool, and
a tool called [GN](../tools/gn/docs/quick_start.md) to generate
the .ninja files to do the build. To create a build directory configured
to build Android, run:
Chromium uses [Ninja](https://ninja-build.org) as its main build tool along
with a tool called [GN](../tools/gn/docs/quick_start.md) to generate `.ninja`
files. You can create any number of *build directories* with different
configurations. To create a build directory which builds Chrome for Android,
run:
$ gn gen '--args="target_os="android"' out/Default
```shell
$ gn gen '--args="target_os="android"' out/Default
```
* You only have to do run this command once, it will self-update the build
files as needed after that.
* You can replace `out/Default` with another directory name, but we recommend
it should still be a subdirectory of `out`.
* To specify build parameters for GN builds, including release settings,
see [GN build configuration](https://www.chromium.org/developers/gn-build-configuration).
* You only have to run this once for each new build directory, Ninja will
update the build files as needed.
* You can replace `Default` with another name, but
it should be a subdirectory of `out`.
* For other build arguments, including release settings, see [GN build
configuration](https://www.chromium.org/developers/gn-build-configuration).
The default will be a debug component build matching the current host
operating system and CPU.
* For more info on GN, run `gn help` on the command line or read the
[quick start guide](../tools/gn/docs/quick_start.md).
Also be aware that some scripts (e.g. tombstones.py, adb_gdb.py)
Also be aware that some scripts (e.g. `tombstones.py`, `adb_gdb.py`)
require you to set `CHROMIUM_OUTPUT_DIR=out/Default`.
## Build Chromium
Build Chromium with Ninja using the command:
$ ninja -C out/Default chrome_public_apk
```shell
$ ninja -C out/Default chrome_public_apk
```
You can get a list of all of the other build targets from GN by running `gn ls
out/Default` from the command line. To compile one, pass the GN label to Ninja
with no preceding "//" (so, for `//chrome/test:unit_tests` use `ninja -C
out/Default chrome/test:unit_tests`).
You can get a list of all of the other build targets from GN by running
`gn ls out/Default` from the command line. To compile one, pass to Ninja
the GN label with no preceding "//" (so for `//chrome/test:unit_tests`
use ninja -C out/Default chrome/test:unit_tests`).
## Installing and Running Chromium on a device
If the `adb_install_apk.py` script below fails, make sure aapt is in
your PATH. If not, add aapt's path to your PATH environment variable (it
should be
If the `adb_install_apk.py` script below fails, make sure `aapt` is in your
PATH. If not, add `aapt`'s parent directory to your `PATH` environment variable
(it should be
`/path/to/src/third_party/android_tools/sdk/build-tools/{latest_version}/`).
Prepare the environment:
```shell
. build/android/envsetup.sh
$ . build/android/envsetup.sh
```
### Plug in your Android device

@ -10,77 +10,87 @@ Google employee? See [go/building-chrome](https://goto.google.com/building-chrom
* A 64-bit Mac running 10.11+.
* [Xcode](https://developer.apple.com/xcode) 8.0+.
* The OSX 10.10 SDK. Run
ls `xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs
* The OS X 10.10 SDK. Run
```shell
$ ls `xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs
```
to check whether you have it. Building with the 10.11 SDK works too, but
the releases currently use the 10.10 SDK.
* The current version of the JDK (which is required for the Closure compiler).
* The current version of the JDK (required for the Closure compiler).
## Install `depot_tools`
Clone the depot_tools repository:
Clone the `depot_tools` repository:
$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
```shell
$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
```
Add depot_tools to the end of your PATH (you will probably want to put this
in your ~/.bashrc or ~/.zshrc). Assuming you cloned depot_tools
to /path/to/depot_tools:
Add `depot_tools` to the end of your PATH (you will probably want to put this
in your `~/.bashrc` or `~/.zshrc`). Assuming you cloned `depot_tools` to
`/path/to/depot_tools`:
$ export PATH=$PATH:/path/to/depot_tools
```shell
$ export PATH="$PATH:/path/to/depot_tools"
```
## Get the code
Create a chromium directory for the checkout and change to it (you can call
Create a `chromium` directory for the checkout and change to it (you can call
this whatever you like and put it wherever you like, as
long as the full path has no spaces):
$ mkdir chromium
$ cd chromium
Run the `fetch` tool from depot_tools to check out the code and its
```shell
$ mkdir chromium && cd chromium
```
Run the `fetch` tool from `depot_tools` to check out the code and its
dependencies.
$ fetch ios
(This is identical to `fetch chromium`, except that it sets `target_os=["ios"]`
in your `.gclient` file.
```shell
$ fetch ios
```
If you don't want the full repo history, you can save a lot of time by
adding the `--no-history` flag to fetch. Expect the command to take
30 minutes on even a fast connection, and many hours on slower ones.
adding the `--no-history` flag to `fetch`.
When fetch completes, it will have created a directory called `src`.
The remaining instructions assume you are now in that directory:
Expect the command to take 30 minutes on even a fast connection, and many
hours on slower ones.
$ cd src
When `fetch` completes, it will have created a hidden `.gclient` file and a
directory called `src` in the working directory. The remaining instructions
assume you have switched to the `src` directory:
*Optional*: You can also [install API keys](https://www.chromium.org/developers/how-tos/api-keys)
if you want to talk to some of the Google services, but this is not necessary
for most development and testing purposes.
```shell
$ cd src
```
*Optional*: You can also [install API
keys](https://www.chromium.org/developers/how-tos/api-keys) if you want your
build to talk to some Google services, but this is not necessary for most
development and testing purposes.
## Setting up the build
Since the iOS build is a bit more complicated than a desktop build, we
provide the `ios/build/tools/setup-gn.py`, which will create four
appropriately configured build directories under `out` for Release and
Debug device and simulator builds, and generates an appropriate Xcode
workspace as well.
Since the iOS build is a bit more complicated than a desktop build, we provide
`ios/build/tools/setup-gn.py`, which will create four appropriately configured
build directories under `out` for Release and Debug device and simulator
builds, and generates an appropriate Xcode workspace as well.
This script is run automatically by fetch (as part of `gclient runhooks`).
You can customize the build by editing the file `$HOME/.setup-gn` (create it
if it does not exists). Look at `src/ios/build/tools/setup-gn.config` for
You can customize the build by editing the file `$HOME/.setup-gn` (create it if
it does not exist). Look at `src/ios/build/tools/setup-gn.config` for
available configuration options.
From this point, you can either build from Xcode or from the command-line
using `ninja`. The script `setup-gn.py` creates sub-directories named
`out/${configuration}-${platform}`, so for a `Debug` build for simulator
use:
From this point, you can either build from Xcode or from the command line using
`ninja`. `setup-gn.py` creates sub-directories named
`out/${configuration}-${platform}`, so for a `Debug` build for simulator use:
```shell
ninja -C out/Debug-iphonesimulator gn_all
$ ninja -C out/Debug-iphonesimulator gn_all
```
Note: you need to run `setup-gn.py` script every time one of the `BUILD.gn`
@ -88,42 +98,43 @@ file is updated (either by you or after rebasing). If you forget to run it,
the list of targets and files in the Xcode solution may be stale.
You can also follow the manual instructions on the
[mac page](mac_build_instructions.md), but make sure you set the
[Mac page](mac_build_instructions.md), but make sure you set the
GN arg `target_os="ios"`.
## Running
Any target that is built and runs on the bots (see [below](#Troubleshooting))
should run successfully in a local build. As of the time of writing, this is
only ios_web_shell and unit test targets—see the note at the top of this
page. Check the bots periodically for updates; more targets (new components)
will come on line over time.
only the `ios_web_shell` and `ios_chrome_unittests` targets—see the note at the
top of this page. Check the bots periodically for updates; more targets (new
components) will come on line over time.
To run in the simulator from the command line, you can use `iossim`. For
example, to run a debug build of ios_web_shell:
example, to run a debug build of `ios_web_shell`:
```shell
out/Debug-iphonesimulator/iossim out/Debug-iphonesimulator/ios_web_shell.app
$ out/Debug-iphonesimulator/iossim out/Debug-iphonesimulator/ios_web_shell.app
```
## Update your checkout
To update an existing checkout, you can run
$ git rebase-update
$ gclient sync
```shell
$ git rebase-update
$ gclient sync
```
The first command updates the primary Chromium source repository and rebases
any of your local branches on top of tip-of-tree (aka the Git branch `origin/master`).
If you don't want to use this script, you can also just use `git pull` or
other common Git commands to update the repo.
any of your local branches on top of tip-of-tree (aka the Git branch
`origin/master`). If you don't want to use this script, you can also just use
`git pull` or other common Git commands to update the repo.
The second command syncs the subrepositories to the appropriate versions and
re-runs the hooks as needed.
The second command syncs dependencies to the appropriate versions and re-runs
hooks as needed.
## Tips, tricks, and troubleshooting
If you have problems building, join us in `#chromium` on `irc.freenode.net` and
ask there. As mentioned above, be sure that the
[waterfall](http://build.chromium.org/buildbot/waterfall/) is green and the tree
@ -132,43 +143,54 @@ is open before checking out. This will increase your chances of success.
### Improving performance of `git status`
`git status` is used frequently to determine the status of your checkout. Due
to the number of files in Chromium's checkout, `git status` performance can be
quite variable. Increasing the system's vnode cache appears to help. By
default, this command:
to the large number of files in Chromium's checkout, `git status` performance
can be quite variable. Increasing the system's vnode cache appears to help.
By default, this command:
sysctl -a | egrep kern\..*vnodes
```shell
$ sysctl -a | egrep kern\..*vnodes
```
Outputs `kern.maxvnodes: 263168` (263168 is 257 * 1024). To increase this
setting:
sudo sysctl kern.maxvnodes=$((512*1024))
```shell
$ sudo sysctl kern.maxvnodes=$((512*1024))
```
Higher values may be appropriate if you routinely move between different
Chromium checkouts. This setting will reset on reboot, the startup setting can
be set in `/etc/sysctl.conf`:
echo kern.maxvnodes=$((512*1024)) | sudo tee -a /etc/sysctl.conf
```shell
$ echo kern.maxvnodes=$((512*1024)) | sudo tee -a /etc/sysctl.conf
```
Or edit the file directly.
If your `git --version` reports 2.6 or higher, the following may also improve
If `git --version` reports 2.6 or higher, the following may also improve
performance of `git status`:
git update-index --untracked-cache
```shell
$ git update-index --untracked-cache
```
### Xcode license agreement
If you're getting the error
```
Agreeing to the Xcode/iOS license requires admin privileges, please re-run as root via sudo.
```
> Agreeing to the Xcode/iOS license requires admin privileges, please re-run as
> root via sudo.
the Xcode license hasn't been accepted yet which (contrary to the message) any
user can do by running:
xcodebuild -license
```shell
$ xcodebuild -license
```
Only accepting for all users of the machine requires root:
sudo xcodebuild -license
```shell
$ sudo xcodebuild -license
```

@ -3,18 +3,21 @@
Generally speaking, follow the [Linux Build Instructions](linux_build_instructions.md).
However, do the following instead to install the build dependencies:
## Install the build dependencies:
## Install the build dependencies
Most of these packages are probably already installed since they're often used,
and the parameter --needed ensures that packages up to date are not reinstalled.
and the `--needed` parameter ensures that up-to-date packages are not
reinstalled.
sudo pacman -S --needed python perl gcc gcc-libs bison flex gperf pkgconfig \
nss alsa-lib gconf glib2 gtk2 nspr ttf-ms-fonts freetype2 cairo dbus \
libgnome-keyring
```shell
$ sudo pacman -S --needed python perl gcc gcc-libs bison flex gperf pkgconfig \
nss alsa-lib gconf glib2 gtk2 nspr ttf-ms-fonts freetype2 cairo dbus \
libgnome-keyring
```
For the optional packages on Arch Linux:
* php-cgi is provided with pacman
* wdiff is not in the main repository but dwdiff is. You can get wdiff in
AUR/yaourt
* sun-java6-fonts do not seem to be in main repository or AUR.
* `php-cgi` is provided with `pacman`
* `wdiff` is not in the main repository but `dwdiff` is. You can get `wdiff`
in AUR/`yaourt`
* `sun-java6-fonts` do not seem to be in main repository or AUR.

@ -13,49 +13,59 @@ Google employee? See [go/building-chrome](https://goto.google.com/building-chrom
* At least 100GB of free disk space.
* You must have Git and Python installed already.
Most development is done on Ubuntu (currently 14.04, Trusty Tahr). There are
Most development is done on Ubuntu (currently 14.04, Trusty Tahr). There are
some instructions for other distros below, but they are mostly unsupported.
## Install `depot_tools`
Clone the depot_tools repository:
Clone the `depot_tools` repository:
$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
```shell
$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
```
Add depot_tools to the end of your PATH (you will probably want to put this
in your ~/.bashrc or ~/.zshrc). Assuming you cloned depot_tools
to /path/to/depot_tools:
Add `depot_tools` to the end of your PATH (you will probably want to put this
in your `~/.bashrc` or `~/.zshrc`). Assuming you cloned `depot_tools` to
`/path/to/depot_tools`:
$ export PATH=$PATH:/path/to/depot_tools
```shell
$ export PATH="$PATH:/path/to/depot_tools"
```
## Get the code
Create a chromium directory for the checkout and change to it (you can call
this whatever you like and put it wherever you like, as
long as the full path has no spaces):
$ mkdir chromium
$ cd chromium
Create a `chromium` directory for the checkout and change to it (you can call
this whatever you like and put it wherever you like, as long as the full path
has no spaces):
```shell
$ mkdir ~/chromium && cd ~/chromium
```
Run the `fetch` tool from depot_tools to check out the code and its
dependencies.
$ fetch --nohooks chromium
```shell
$ fetch --nohooks chromium
```
If you don't want the full repo history, you can save a lot of time by
adding the `--no-history` flag to fetch.
adding the `--no-history` flag to `fetch`.
Expect the command to take 30 minutes on even a fast connection, and many
hours on slower ones.
If you've already installed the build dependencies on the machine (from another
checkout, for example), you can omit the `--nohooks` flag and fetch
checkout, for example), you can omit the `--nohooks` flag and `fetch`
will automatically execute `gclient runhooks` at the end.
When fetch completes, it will have created a directory called `src`.
The remaining instructions assume you are now in that directory:
When `fetch` completes, it will have created a hidden `.gclient` file and a
directory called `src` in the working directory. The remaining instructions
assume you have switched to the `src` directory:
$ cd src
```shell
$ cd src
```
### Install additional build dependencies
@ -75,29 +85,35 @@ For Gentoo, you can just run `emerge www-client/chromium`.
### Run the hooks
Once you've run `install-build-deps` at least once, you can now run the
chromium-specific hooks, which will download additional binaries and other
Chromium-specific hooks, which will download additional binaries and other
things you might need:
$ gclient runhooks
```shell
$ gclient runhooks
```
*Optional*: You can also [install API keys](https://www.chromium.org/developers/how-tos/api-keys)
if you want to talk to some of the Google services, but this is not necessary
for most development and testing purposes.
*Optional*: You can also [install API
keys](https://www.chromium.org/developers/how-tos/api-keys) if you want your
build to talk to some Google services, but this is not necessary for most
development and testing purposes.
## Seting up the Build
## Setting up the Build
Chromium uses [Ninja](https://ninja-build.org) as its main build tool, and
a tool called [GN](../tools/gn/docs/quick_start.md) to generate
the .ninja files to do the build. To create a build directory, run:
Chromium uses [Ninja](https://ninja-build.org) as its main build tool along
with a tool called [GN](../tools/gn/docs/quick_start.md) to generate `.ninja`
files. You can create any number of *build directories* with different
configurations. To create a build directory, run:
$ gn gen out/Default
```shell
$ gn gen out/Default
```
* You only have to do run this command once, it will self-update the build
files as needed after that.
* You can replace `out/Default` with another directory name, but we recommend
it should still be a subdirectory of `out`.
* To specify build parameters for GN builds, including release settings,
see [GN build configuration](https://www.chromium.org/developers/gn-build-configuration).
* You only have to run this once for each new build directory, Ninja will
update the build files as needed.
* You can replace `Default` with another name, but
it should be a subdirectory of `out`.
* For other build arguments, including release settings, see [GN build
configuration](https://www.chromium.org/developers/gn-build-configuration).
The default will be a debug component build matching the current host
operating system and CPU.
* For more info on GN, run `gn help` on the command line or read the
@ -112,25 +128,31 @@ settings that may speed up your build.
Build Chromium (the "chrome" target) with Ninja using the command:
$ ninja -C out/Default chrome
```shell
$ ninja -C out/Default chrome
```
You can get a list of all of the other build targets from GN by running
`gn ls out/Default` from the command line. To compile one, pass to Ninja
the GN label with no preceding "//" (so for `//chrome/test:unit_tests`
use ninja -C out/Default chrome/test:unit_tests`).
You can get a list of all of the other build targets from GN by running `gn ls
out/Default` from the command line. To compile one, pass the GN label to Ninja
with no preceding "//" (so, for `//chrome/test:unit_tests` use `ninja -C
out/Default chrome/test:unit_tests`).
## Run Chromium
Once it is built, you can simply run the browser:
$ out/Default/chrome
```shell
$ out/Default/chrome
```
## Running test targets
You can run the tests in the same way. You can also limit which tests are
run using the `--gtest_filter` arg, e.g.:
$ ninja -C out/Default unit_tests --gtest_filter="PushClientTest.*"
```shell
$ ninja -C out/Default unit_tests --gtest_filter="PushClientTest.*"
```
You can find out more about GoogleTest at its
[GitHub page](https://github.com/google/googletest).
@ -139,16 +161,18 @@ You can find out more about GoogleTest at its
To update an existing checkout, you can run
$ git rebase-update
$ gclient sync
```shell
$ git rebase-update
$ gclient sync
```
The first command updates the primary Chromium source repository and rebases
any of your local branches on top of tip-of-tree (aka the Git branch `origin/master`).
If you don't want to use this script, you can also just use `git pull` or
other common Git commands to update the repo.
any of your local branches on top of tip-of-tree (aka the Git branch
`origin/master`). If you don't want to use this script, you can also just use
`git pull` or other common Git commands to update the repo.
The second command syncs the subrepositories to the appropriate versions and
re-runs the hooks as needed.
The second command syncs dependencies to the appropriate versions and re-runs
hooks as needed.
## Tips, tricks, and troubleshooting
@ -156,25 +180,27 @@ re-runs the hooks as needed.
If, during the final link stage:
LINK out/Debug/chrome
```
LINK out/Debug/chrome
```
You get an error like:
collect2: ld terminated with signal 6 Aborted terminate called after throwing an
instance of 'std::bad_alloc'
collect2: ld terminated with signal 11 [Segmentation fault], core dumped
```
collect2: ld terminated with signal 6 Aborted terminate called after throwing an instance of 'std::bad_alloc'
collect2: ld terminated with signal 11 [Segmentation fault], core dumped
```
you are probably running out of memory when linking. You *must* use a 64-bit
system to build. Try the following build settings (see [GN build
configuration](https://www.chromium.org/developers/gn-build-configuration) for
setting):
other settings):
* Build in release mode (debugging symbols require more memory).
* Build in release mode (debugging symbols require more memory):
`is_debug = false`
* Turn off symbols. `symbol_level = 0`
* Build in component mode (this is for developers only, it will be slower and
may have broken functionality). `is_component_build = true`
* Turn off symbols: `symbol_level = 0`
* Build in component mode (this is for development only, it will be slower and
may have broken functionality): `is_component_build = true`
### More links

@ -3,10 +3,10 @@
Generally speaking, follow the [Linux Build Instructions](linux_build_instructions.md).
However, you may need to update the package names in `install-build-deps.sh`:
* libexpat-dev -> libexpat1-dev
* freetype-dev -> libfreetype6-dev
* libbzip2-dev -> libbz2-dev
* libcupsys2-dev -> libcups2-dev
* `libexpat-dev``libexpat1-dev`
* `freetype-dev``libfreetype6-dev`
* `libbzip2-dev``libbz2-dev`
* `libcupsys2-dev``libcups2-dev`
Additionally, if you're building Chromium components for Android, you'll need to
install the package: lib32z1
install the package `lib32z1`.

@ -6,20 +6,22 @@ However, do the following instead to install the build dependenies:
Generally, follow the main [Linux Build instructions], but instead of
running `build/install-build-deps.sh`, run:
su -c 'yum install git python bzip2 tar pkgconfig atk-devel alsa-lib-devel \
bison binutils brlapi-devel bluez-libs-devel bzip2-devel cairo-devel \
cups-devel dbus-devel dbus-glib-devel expat-devel fontconfig-devel \
freetype-devel gcc-c++ GConf2-devel glib2-devel glibc.i686 gperf \
glib2-devel gtk2-devel gtk3-devel java-1.*.0-openjdk-devel libatomic \
libcap-devel libffi-devel libgcc.i686 libgnome-keyring-devel libjpeg-devel \
libstdc++.i686 libX11-devel libXScrnSaver-devel libXtst-devel \
libxkbcommon-x11-devel ncurses-compat-libs nspr-devel nss-devel pam-devel \
pango-devel pciutils-devel pulseaudio-libs-devel zlib.i686 httpd mod_ssl \
php php-cli python-psutil wdiff'
```shell
su -c 'yum install git python bzip2 tar pkgconfig atk-devel alsa-lib-devel \
bison binutils brlapi-devel bluez-libs-devel bzip2-devel cairo-devel \
cups-devel dbus-devel dbus-glib-devel expat-devel fontconfig-devel \
freetype-devel gcc-c++ GConf2-devel glib2-devel glibc.i686 gperf \
glib2-devel gtk2-devel gtk3-devel java-1.*.0-openjdk-devel libatomic \
libcap-devel libffi-devel libgcc.i686 libgnome-keyring-devel libjpeg-devel \
libstdc++.i686 libX11-devel libXScrnSaver-devel libXtst-devel \
libxkbcommon-x11-devel ncurses-compat-libs nspr-devel nss-devel pam-devel \
pango-devel pciutils-devel pulseaudio-libs-devel zlib.i686 httpd mod_ssl \
php php-cli python-psutil wdiff'
```
The msttcorefonts packages can be obtained by following the instructions
present [here](http://www.fedorafaq.org/#installfonts). For the optional
The `msttcorefonts` packages can be obtained by following [these
instructions](http://www.fedorafaq.org/#installfonts). For the optional
packages:
* php-cgi is provided by the php-cli package
* sun-java6-fonts doesn't exist in Fedora repositories, needs investigating
* `php-cgi` is provided by the `php-cli` package.
* `sun-java6-fonts` doesn't exist in Fedora repositories, needs investigating.

@ -5,16 +5,18 @@ However, do the following instead to install the build dependencies:
## Install the build dependencies:
urpmi lib64fontconfig-devel lib64alsa2-devel lib64dbus-1-devel \
lib64GConf2-devel lib64freetype6-devel lib64atk1.0-devel lib64gtk+2.0_0-devel \
lib64pango1.0-devel lib64cairo-devel lib64nss-devel lib64nspr-devel g++ python \
perl bison flex subversion gperf
```shell
urpmi lib64fontconfig-devel lib64alsa2-devel lib64dbus-1-devel \
lib64GConf2-devel lib64freetype6-devel lib64atk1.0-devel lib64gtk+2.0_0-devel \
lib64pango1.0-devel lib64cairo-devel lib64nss-devel lib64nspr-devel g++ python \
perl bison flex subversion gperf
```
* msttcorefonts are not available, you will need to build your own (see
instructions, not hard to do, see
[mandriva_msttcorefonts.md](mandriva_msttcorefonts.md)) or use drakfont to
import the fonts from a windows installation
* These packages are for 64 bit, to download the 32 bit packages,
substitute lib64 with lib
* Some of these packages might not be explicitly necessary as they come as
dependencies, there is no harm in including them however.
* `msttcorefonts` are not available, you will need to build your own (see
instructions, not hard to do, see
[mandriva_msttcorefonts.md](mandriva_msttcorefonts.md)) or use `drakfont` to
import the fonts from a Windows installation.
* These packages are for 64 bit, to download the 32 bit packages, substitute
`lib64` with `lib`.
* Some of these packages might not be explicitly necessary as they come as
dependencies, there is no harm in including them however.

@ -5,15 +5,17 @@ However, do the following instead to install the build dependencies:
## Install the build dependencies:
Use zypper command to install dependencies:
Use `zypper` command to install dependencies:
(openSUSE 11.1 and higher)
sudo zypper in subversion pkg-config python perl \
bison flex gperf mozilla-nss-devel glib2-devel gtk-devel \
wdiff lighttpd gcc gcc-c++ gconf2-devel mozilla-nspr \
mozilla-nspr-devel php5-fastcgi alsa-devel libexpat-devel \
libjpeg-devel libbz2-devel
```shell
sudo zypper in subversion pkg-config python perl \
bison flex gperf mozilla-nss-devel glib2-devel gtk-devel \
wdiff lighttpd gcc gcc-c++ gconf2-devel mozilla-nspr \
mozilla-nspr-devel php5-fastcgi alsa-devel libexpat-devel \
libjpeg-devel libbz2-devel
```
For 11.0, use `libnspr4-0d` and `libnspr4-dev` instead of `mozilla-nspr` and
`mozilla-nspr-devel`, and use `php5-cgi` instead of `php5-fastcgi`. And need
@ -21,20 +23,26 @@ For 11.0, use `libnspr4-0d` and `libnspr4-dev` instead of `mozilla-nspr` and
(openSUSE 11.0)
sudo zypper in subversion pkg-config python perl \
bison flex gperf mozilla-nss-devel glib2-devel gtk-devel \
libnspr4-0d libnspr4-dev wdiff lighttpd gcc gcc-c++ libexpat-devel \
php5-cgi gconf2-devel alsa-devel gtk2-devel jpeg-devel
```shell
sudo zypper in subversion pkg-config python perl \
bison flex gperf mozilla-nss-devel glib2-devel gtk-devel \
libnspr4-0d libnspr4-dev wdiff lighttpd gcc gcc-c++ libexpat-devel \
php5-cgi gconf2-devel alsa-devel gtk2-devel jpeg-devel
```
The Ubuntu package sun-java6-fonts contains a subset of Java of the fonts used.
The Ubuntu package `sun-java6-fonts` contains a subset of Java of the fonts used.
Since this package requires Java as a prerequisite anyway, we can do the same
thing by just installing the equivalent OpenSUSE Sun Java package:
thing by just installing the equivalent openSUSE Sun Java package:
sudo zypper in java-1_6_0-sun
```shell
sudo zypper in java-1_6_0-sun
```
Webkit is currently hard-linked to the Microsoft fonts. To install these using zypper
WebKit is currently hard-linked to the Microsoft fonts. To install these using `zypper`
sudo zypper in fetchmsttfonts pullin-msttf-fonts
```shell
sudo zypper in fetchmsttfonts pullin-msttf-fonts
```
To make the fonts installed above work, as the paths are hardcoded for Ubuntu,
create symlinks to the appropriate locations:

@ -8,68 +8,84 @@ Google employee? See [go/building-chrome](https://goto.google.com/building-chrom
* A 64-bit Mac running 10.9+.
* [Xcode](https://developer.apple.com/xcode) 7.3+.
* The OSX 10.10 SDK. Run
* The OS X 10.10 SDK. Run
```shell
$ ls `xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs
```
ls `xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs
```
to check whether you have it. Building with the 10.11 SDK works too, but
to check whether you have it. Building with a newer SDK works too, but
the releases currently use the 10.10 SDK.
* Git v
* Python 2.7.x.
## Install `depot_tools`
Clone the depot_tools repository:
Clone the `depot_tools` repository:
$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
```shell
$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
```
Add depot_tools to the end of your PATH (you will probably want to put this
in your ~/.bashrc or ~/.zshrc). Assuming you cloned depot_tools
to /path/to/depot_tools:
Add `depot_tools` to the end of your PATH (you will probably want to put this
in your `~/.bashrc` or `~/.zshrc`). Assuming you cloned `depot_tools` to
`/path/to/depot_tools`:
$ export PATH=$PATH:/path/to/depot_tools
```shell
$ export PATH="$PATH:/path/to/depot_tools"
```
## Get the code
Create a chromium directory for the checkout and change to it (you can call
this whatever you like and put it wherever you like, as
long as the full path has no spaces):
$ mkdir chromium
$ cd chromium
Create a `chromium` directory for the checkout and change to it (you can call
this whatever you like and put it wherever you like, as long as the full path
has no spaces):
Run the `fetch` tool from depot_tools to check out the code and its
```shell
$ mkdir chromium && cd chromium
```
Run the `fetch` tool from `depot_tools` to check out the code and its
dependencies.
$ fetch chromium
```shell
$ fetch chromium
```
If you don't want the full repo history, you can save a lot of time by
adding the `--no-history` flag to fetch. Expect the command to take
30 minutes on even a fast connection, and many hours on slower ones.
adding the `--no-history` flag to `fetch`.
When fetch completes, it will have created a directory called `src`.
The remaining instructions assume you are now in that directory:
Expect the command to take 30 minutes on even a fast connection, and many
hours on slower ones.
$ cd src
When `fetch` completes, it will have created a hidden `.gclient` file and a
directory called `src` in the working directory. The remaining instructions
assume you have switched to the `src` directory:
*Optional*: You can also [install API keys](https://www.chromium.org/developers/how-tos/api-keys)
if you want to talk to some of the Google services, but this is not necessary
for most development and testing purposes.
```shell
$ cd src
```
*Optional*: You can also [install API
keys](https://www.chromium.org/developers/how-tos/api-keys) if you want your
build to talk to some Google services, but this is not necessary for most
development and testing purposes.
## Building
Chromium uses [Ninja](https://ninja-build.org) as its main build tool, and
a tool called [GN](../tools/gn/docs/quick_start.md) to generate
the .ninja files to do the build. To create a build directory:
Chromium uses [Ninja](https://ninja-build.org) as its main build tool along
with a tool called [GN](../tools/gn/docs/quick_start.md) to generate `.ninja`
files. You can create any number of *build directories* with different
configurations. To create a build directory:
$ gn gen out/Default
```shell
$ gn gen out/Default
```
* You only have to do run this command once, it will self-update the build
files as needed after that.
* You can replace `out/Default` with another directory name, but we recommend
it should still be a subdirectory of `out`.
* To specify build parameters for GN builds, including release settings,
see [GN build configuration](https://www.chromium.org/developers/gn-build-configuration).
* You only have to run this once for each new build directory, Ninja will
update the build files as needed.
* You can replace `Default` with another name, but
it should be a subdirectory of `out`.
* For other build arguments, including release settings, see [GN build
configuration](https://www.chromium.org/developers/gn-build-configuration).
The default will be a debug component build matching the current host
operating system and CPU.
* For more info on GN, run `gn help` on the command line or read the
@ -83,21 +99,28 @@ lot faster in Release builds.
Put
is_debug = false
```
is_debug = false
```
in your args.gn to do a release build.
in your `args.gn` to do a release build.
Put
is_component_build = true
```
is_component_build = true
```
in your args.gn to build many small dylibs instead of a single large executable.
This makes incremental builds much faster, at the cost of producing a binary
that opens less quickly. Component builds work in both debug and release.
in your `args.gn` to build many small dylibs instead of a single large
executable. This makes incremental builds much faster, at the cost of producing
a binary that opens less quickly. Component builds work in both debug and
release.
Put
symbol_level = 0
```
symbol_level = 0
```
in your args.gn to disable debug symbols altogether. This makes both full
rebuilds and linking faster (at the cost of not getting symbolized backtraces
@ -109,14 +132,18 @@ You might also want to [install ccache](ccache_mac.md) to speed up the build.
Once it is built, you can simply run the browser:
$ out/Default/chrome
```shell
$ out/Default/chrome
```
## Running test targets
You can run the tests in the same way. You can also limit which tests are
run using the `--gtest_filter` arg, e.g.:
$ ninja -C out/Default unit_tests --gtest_filter="PushClientTest.*"
```
$ ninja -C out/Default unit_tests --gtest_filter="PushClientTest.*"
```
You can find out more about GoogleTest at its
[GitHub page](https://github.com/google/googletest).
@ -126,102 +153,114 @@ You can find out more about GoogleTest at its
Good debugging tips can be found
[here](http://dev.chromium.org/developers/how-tos/debugging-on-os-x). If you
would like to debug in a graphical environment, rather than using `lldb` at the
command line, that is possible without building in Xcode. See
[Debugging in Xcode](http://www.chromium.org/developers/how-tos/debugging-on-os-x/building-with-ninja-debugging-with-xcode)
for information on how.
command line, that is possible without building in Xcode (see
[Debugging in Xcode](http://www.chromium.org/developers/how-tos/debugging-on-os-x/building-with-ninja-debugging-with-xcode)).
## Update your checkout
To update an existing checkout, you can run
$ git rebase-update
$ gclient sync
```shell
$ git rebase-update
$ gclient sync
```
The first command updates the primary Chromium source repository and rebases
any of your local branches on top of tip-of-tree (aka the Git branch `origin/master`).
If you don't want to use this script, you can also just use `git pull` or
other common Git commands to update the repo.
any of your local branches on top of tip-of-tree (aka the Git branch
`origin/master`). If you don't want to use this script, you can also just use
`git pull` or other common Git commands to update the repo.
The second command syncs the subrepositories to the appropriate versions and
re-runs the hooks as needed.
The second command syncs dependencies to the appropriate versions and re-runs
hooks as needed.
## Tips, tricks, and troubleshooting
### Using Xcode-Ninja Hybrid
While using Xcode is unsupported, gn supports a hybrid approach of using ninja
While using Xcode is unsupported, GN supports a hybrid approach of using Ninja
for building, but Xcode for editing and driving compilation. Xcode is still
slow, but it runs fairly well even **with indexing enabled**. Most people
build in the Terminal and write code with a text editor though.
build in the Terminal and write code with a text editor, though.
With hybrid builds, compilation is still handled by ninja, and can be run by the
command line (e.g. ninja -C out/gn chrome) or by choosing the chrome target
in the hybrid workspace and choosing build.
With hybrid builds, compilation is still handled by Ninja, and can be run from
the command line (e.g. `ninja -C out/gn chrome`) or by choosing the `chrome`
target in the hybrid workspace and choosing Build.
To use Xcode-Ninja Hybrid pass --ide=xcode to `gn gen`
To use Xcode-Ninja Hybrid pass `--ide=xcode` to `gn gen`:
```shell
gn gen out/gn --ide=xcode
$ gn gen out/gn --ide=xcode
```
Open it:
```shell
open out/gn/ninja/all.xcworkspace
$ open out/gn/ninja/all.xcworkspace
```
You may run into a problem where http://YES is opened as a new tab every time
you launch Chrome. To fix this, open the scheme editor for the Run scheme,
choose the Options tab, and uncheck "Allow debugging when using document
Versions Browser". When this option is checked, Xcode adds
`--NSDocumentRevisionsDebugMode YES` to the launch arguments, and the `YES` gets
interpreted as a URL to open.
`--NSDocumentRevisionsDebugMode YES` to the launch arguments, and the `YES`
gets interpreted as a URL to open.
If you have problems building, join us in `#chromium` on `irc.freenode.net` and
ask there. As mentioned above, be sure that the
[waterfall](http://build.chromium.org/buildbot/waterfall/) is green and the tree
is open before checking out. This will increase your chances of success.
ask there. Be sure that the
[waterfall](http://build.chromium.org/buildbot/waterfall/) is green and the
tree is open before checking out. This will increase your chances of success.
### Improving performance of `git status`
`git status` is used frequently to determine the status of your checkout. Due
to the number of files in Chromium's checkout, `git status` performance can be
quite variable. Increasing the system's vnode cache appears to help. By
to the large number of files in Chromium's checkout, `git status` performance
can be quite variable. Increasing the system's vnode cache appears to help. By
default, this command:
sysctl -a | egrep kern\..*vnodes
```shell
$ sysctl -a | egrep kern\..*vnodes
```
Outputs `kern.maxvnodes: 263168` (263168 is 257 * 1024). To increase this
setting:
sudo sysctl kern.maxvnodes=$((512*1024))
```shell
$ sudo sysctl kern.maxvnodes=$((512*1024))
```
Higher values may be appropriate if you routinely move between different
Chromium checkouts. This setting will reset on reboot, the startup setting can
be set in `/etc/sysctl.conf`:
echo kern.maxvnodes=$((512*1024)) | sudo tee -a /etc/sysctl.conf
```shell
$ echo kern.maxvnodes=$((512*1024)) | sudo tee -a /etc/sysctl.conf
```
Or edit the file directly.
If your `git --version` reports 2.6 or higher, the following may also improve
If `git --version` reports 2.6 or higher, the following may also improve
performance of `git status`:
git update-index --untracked-cache
```shell
$ git update-index --untracked-cache
```
### Xcode license agreement
If you're getting the error
```
Agreeing to the Xcode/iOS license requires admin privileges, please re-run as root via sudo.
```
> Agreeing to the Xcode/iOS license requires admin privileges, please re-run as
> root via sudo.
the Xcode license hasn't been accepted yet which (contrary to the message) any
user can do by running:
xcodebuild -license
```shell
$ xcodebuild -license
```
Only accepting for all users of the machine requires root:
sudo xcodebuild -license
```shell
$ sudo xcodebuild -license
```

@ -88,47 +88,57 @@ using gn - see [crbug.com/611087](https://crbug.com/611087).
## Get the code
Create a chromium directory for the checkout and change to it (you can call
Create a `chromium` directory for the checkout and change to it (you can call
this whatever you like and put it wherever you like, as
long as the full path has no spaces):
$ mkdir chromium
$ cd chromium
Run the `fetch` tool from depot_tools to check out the code and its
```shell
$ mkdir chromium && cd chromium
```
Run the `fetch` tool from `depot_tools` to check out the code and its
dependencies.
$ fetch chromium
```shell
$ fetch ios
```
If you don't want the full repo history, you can save a lot of time by
adding the `--no-history` flag to fetch. Expect the command to take
30 minutes on even a fast connection, and many hours on slower ones.
adding the `--no-history` flag to `fetch`.
When fetch completes, it will have created a directory called `src`.
The remaining instructions assume you are now in that directory:
Expect the command to take 30 minutes on even a fast connection, and many
hours on slower ones.
$ cd src
When `fetch` completes, it will have created a hidden `.gclient` file and a
directory called `src` in the working directory. The remaining instructions
assume you have switched to the `src` directory:
### (optional) Install API keys
```shell
$ cd src
```
You can also [instaldl API keys](https://www.chromium.org/developers/how-tos/api-keys)
if you want to talk to some of the Google services, but this is not necessary
for most development and testing purposes.
*Optional*: You can also [install API
keys](https://www.chromium.org/developers/how-tos/api-keys) if you want your
build to talk to some Google services, but this is not necessary for most
development and testing purposes.
## Seting up the Build
## Building
Chromium uses [Ninja](https://ninja-build.org) as its main build tool, and
a tool called [GN](../tools/gn/docs/quick_start.md) to generate
the .ninja files to do the build. To create a build directory:
Chromium uses [Ninja](https://ninja-build.org) as its main build tool along
with a tool called [GN](../tools/gn/docs/quick_start.md) to generate `.ninja`
files. You can create any number of *build directories* with different
configurations. To create a build directory:
$ gn gen out/Default
```shell
$ gn gen out/Default
```
* You only have to do run this command once, it will self-update the build
files as needed after that.
* You can replace `out/Default` with another directory name, but we recommend
it should still be a subdirectory of `out`.
* To specify build parameters for GN builds, including release settings,
see [GN build configuration](https://www.chromium.org/developers/gn-build-configuration).
* You only have to run this once for each new build directory, Ninja will
update the build files as needed.
* You can replace `Default` with another name, but
it should be a subdirectory of `out`.
* For other build arguments, including release settings, see [GN build
configuration](https://www.chromium.org/developers/gn-build-configuration).
The default will be a debug component build matching the current host
operating system and CPU.
* For more info on GN, run `gn help` on the command line or read the