blob: fdfa120de63762b37d48de9ba2eb527c02bb8bce [file] [log] [blame] [view]
dpranke0ae7cad2016-11-30 07:47:581# Checking out and building Chromium on Linux
andybons3322f762015-08-24 21:37:092
dpranke1a70d0c2016-12-01 02:42:293There are instructions for other platforms linked from the
4[get the code](get_the_code.md) page.
5
dpranke0ae7cad2016-11-30 07:47:586**See also [the old version of this page](old_linux_build_instructions.md).**
andybons3322f762015-08-24 21:37:097
dpranke1a70d0c2016-12-01 02:42:298## Instructions for Google Employees
9
10Are you a Google employee? See
11[go/building-chrome](https://goto.google.com/building-chrome) instead.
andybons8c02a1f2015-09-04 17:02:3212
dpranke0ae7cad2016-11-30 07:47:5813[TOC]
andybonsad92aa32015-08-31 02:27:4414
dpranke0ae7cad2016-11-30 07:47:5815## System requirements
andybonsad92aa32015-08-31 02:27:4416
dpranke0ae7cad2016-11-30 07:47:5817* A 64-bit Intel machine with at least 8GB of RAM. More than 16GB is highly
18 recommended.
19* At least 100GB of free disk space.
20* You must have Git and Python installed already.
andybons3322f762015-08-24 21:37:0921
sdy93387fa2016-12-01 01:03:4422Most development is done on Ubuntu (currently 14.04, Trusty Tahr). There are
dpranke0ae7cad2016-11-30 07:47:5823some instructions for other distros below, but they are mostly unsupported.
andybons3322f762015-08-24 21:37:0924
dpranke0ae7cad2016-11-30 07:47:5825## Install `depot_tools`
andybonsad92aa32015-08-31 02:27:4426
sdy93387fa2016-12-01 01:03:4427Clone the `depot_tools` repository:
andybons3322f762015-08-24 21:37:0928
sdy93387fa2016-12-01 01:03:4429```shell
30$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
31```
andybonsad92aa32015-08-31 02:27:4432
sdy93387fa2016-12-01 01:03:4433Add `depot_tools` to the end of your PATH (you will probably want to put this
34in your `~/.bashrc` or `~/.zshrc`). Assuming you cloned `depot_tools` to
35`/path/to/depot_tools`:
andybonsad92aa32015-08-31 02:27:4436
sdy93387fa2016-12-01 01:03:4437```shell
38$ export PATH="$PATH:/path/to/depot_tools"
39```
andybons3322f762015-08-24 21:37:0940
dpranke0ae7cad2016-11-30 07:47:5841## Get the code
andybonsad92aa32015-08-31 02:27:4442
sdy93387fa2016-12-01 01:03:4443Create a `chromium` directory for the checkout and change to it (you can call
44this whatever you like and put it wherever you like, as long as the full path
45has no spaces):
46
47```shell
48$ mkdir ~/chromium && cd ~/chromium
49```
andybons3322f762015-08-24 21:37:0950
dpranke0ae7cad2016-11-30 07:47:5851Run the `fetch` tool from depot_tools to check out the code and its
52dependencies.
andybonsad92aa32015-08-31 02:27:4453
sdy93387fa2016-12-01 01:03:4454```shell
55$ fetch --nohooks chromium
56```
andybonsad92aa32015-08-31 02:27:4457
dpranke0ae7cad2016-11-30 07:47:5858If you don't want the full repo history, you can save a lot of time by
sdy93387fa2016-12-01 01:03:4459adding the `--no-history` flag to `fetch`.
andybons3322f762015-08-24 21:37:0960
dpranke0ae7cad2016-11-30 07:47:5861Expect the command to take 30 minutes on even a fast connection, and many
62hours on slower ones.
andybonsad92aa32015-08-31 02:27:4463
dpranke0ae7cad2016-11-30 07:47:5864If you've already installed the build dependencies on the machine (from another
sdy93387fa2016-12-01 01:03:4465checkout, for example), you can omit the `--nohooks` flag and `fetch`
dpranke0ae7cad2016-11-30 07:47:5866will automatically execute `gclient runhooks` at the end.
andybons3322f762015-08-24 21:37:0967
sdy93387fa2016-12-01 01:03:4468When `fetch` completes, it will have created a hidden `.gclient` file and a
69directory called `src` in the working directory. The remaining instructions
70assume you have switched to the `src` directory:
andybons3322f762015-08-24 21:37:0971
sdy93387fa2016-12-01 01:03:4472```shell
73$ cd src
74```
andybons3322f762015-08-24 21:37:0975
dpranke0ae7cad2016-11-30 07:47:5876### Install additional build dependencies
andybons3322f762015-08-24 21:37:0977
dpranke0ae7cad2016-11-30 07:47:5878Once you have checked out the code, and assuming you're using Ubuntu, run
79[build/install-build-deps.sh](/build/install-build-deps.sh)
andybons3322f762015-08-24 21:37:0980
dpranke0ae7cad2016-11-30 07:47:5881Here are some instructions for what to do instead for
andybons3322f762015-08-24 21:37:0982
dpranke0ae7cad2016-11-30 07:47:5883* [Debian](linux_debian_build_instructions.md)
84* [Fedora](linux_fedora_build_instructions.md)
85* [Arch Linux](linux_arch_build_instructions.md)
86* [Open SUSE](linux_open_suse_build_instrctions.md)
87* [Mandriva](linux_mandriva_build_instrctions.md)
andybonsad92aa32015-08-31 02:27:4488
dpranke0ae7cad2016-11-30 07:47:5889For Gentoo, you can just run `emerge www-client/chromium`.
andybonsad92aa32015-08-31 02:27:4490
dpranke0ae7cad2016-11-30 07:47:5891### Run the hooks
andybons3322f762015-08-24 21:37:0992
dpranke0ae7cad2016-11-30 07:47:5893Once you've run `install-build-deps` at least once, you can now run the
sdy93387fa2016-12-01 01:03:4494Chromium-specific hooks, which will download additional binaries and other
dpranke0ae7cad2016-11-30 07:47:5895things you might need:
andybonsad92aa32015-08-31 02:27:4496
sdy93387fa2016-12-01 01:03:4497```shell
98$ gclient runhooks
99```
andybonsad92aa32015-08-31 02:27:44100
sdy93387fa2016-12-01 01:03:44101*Optional*: You can also [install API
102keys](https://www.chromium.org/developers/how-tos/api-keys) if you want your
103build to talk to some Google services, but this is not necessary for most
104development and testing purposes.
andybons3322f762015-08-24 21:37:09105
dpranke1a70d0c2016-12-01 02:42:29106## Setting up the build
andybonsad92aa32015-08-31 02:27:44107
sdy93387fa2016-12-01 01:03:44108Chromium uses [Ninja](https://ninja-build.org) as its main build tool along
109with a tool called [GN](../tools/gn/docs/quick_start.md) to generate `.ninja`
110files. You can create any number of *build directories* with different
111configurations. To create a build directory, run:
andybons8c02a1f2015-09-04 17:02:32112
sdy93387fa2016-12-01 01:03:44113```shell
114$ gn gen out/Default
115```
dpranke0ae7cad2016-11-30 07:47:58116
sdy93387fa2016-12-01 01:03:44117* You only have to run this once for each new build directory, Ninja will
118 update the build files as needed.
119* You can replace `Default` with another name, but
120 it should be a subdirectory of `out`.
121* For other build arguments, including release settings, see [GN build
122 configuration](https://www.chromium.org/developers/gn-build-configuration).
dpranke0ae7cad2016-11-30 07:47:58123 The default will be a debug component build matching the current host
124 operating system and CPU.
125* For more info on GN, run `gn help` on the command line or read the
126 [quick start guide](../tools/gn/docs/quick_start.md).
127
128### Faster builds
129
130See [faster builds on Linux](linux_faster_builds.md) for various tips and
131settings that may speed up your build.
132
133## Build Chromium
134
135Build Chromium (the "chrome" target) with Ninja using the command:
136
sdy93387fa2016-12-01 01:03:44137```shell
138$ ninja -C out/Default chrome
139```
dpranke0ae7cad2016-11-30 07:47:58140
sdy93387fa2016-12-01 01:03:44141You can get a list of all of the other build targets from GN by running `gn ls
142out/Default` from the command line. To compile one, pass the GN label to Ninja
143with no preceding "//" (so, for `//chrome/test:unit_tests` use `ninja -C
144out/Default chrome/test:unit_tests`).
dpranke0ae7cad2016-11-30 07:47:58145
146## Run Chromium
147
148Once it is built, you can simply run the browser:
149
sdy93387fa2016-12-01 01:03:44150```shell
151$ out/Default/chrome
152```
dpranke0ae7cad2016-11-30 07:47:58153
154## Running test targets
155
156You can run the tests in the same way. You can also limit which tests are
157run using the `--gtest_filter` arg, e.g.:
158
sdy93387fa2016-12-01 01:03:44159```shell
dpranke1a70d0c2016-12-01 02:42:29160$ out/Default/unit_tests --gtest_filter="PushClientTest.*"
sdy93387fa2016-12-01 01:03:44161```
dpranke0ae7cad2016-11-30 07:47:58162
163You can find out more about GoogleTest at its
164[GitHub page](https://github.com/google/googletest).
165
166## Update your checkout
167
168To update an existing checkout, you can run
169
sdy93387fa2016-12-01 01:03:44170```shell
171$ git rebase-update
172$ gclient sync
173```
dpranke0ae7cad2016-11-30 07:47:58174
175The first command updates the primary Chromium source repository and rebases
sdy93387fa2016-12-01 01:03:44176any of your local branches on top of tip-of-tree (aka the Git branch
177`origin/master`). If you don't want to use this script, you can also just use
178`git pull` or other common Git commands to update the repo.
dpranke0ae7cad2016-11-30 07:47:58179
sdy93387fa2016-12-01 01:03:44180The second command syncs dependencies to the appropriate versions and re-runs
181hooks as needed.
dpranke0ae7cad2016-11-30 07:47:58182
183## Tips, tricks, and troubleshooting
andybons3322f762015-08-24 21:37:09184
185### Linker Crashes
andybonsad92aa32015-08-31 02:27:44186
andybons3322f762015-08-24 21:37:09187If, during the final link stage:
andybonsad92aa32015-08-31 02:27:44188
sdy93387fa2016-12-01 01:03:44189```
190LINK out/Debug/chrome
191```
andybonsad92aa32015-08-31 02:27:44192
andybons3322f762015-08-24 21:37:09193You get an error like:
andybons3322f762015-08-24 21:37:09194
sdy93387fa2016-12-01 01:03:44195```
196collect2: ld terminated with signal 6 Aborted terminate called after throwing an instance of 'std::bad_alloc'
197collect2: ld terminated with signal 11 [Segmentation fault], core dumped
198```
andybonsad92aa32015-08-31 02:27:44199
brettwc25693b32016-05-26 01:11:52200you are probably running out of memory when linking. You *must* use a 64-bit
201system to build. Try the following build settings (see [GN build
202configuration](https://www.chromium.org/developers/gn-build-configuration) for
sdy93387fa2016-12-01 01:03:44203other settings):
andybonsad92aa32015-08-31 02:27:44204
sdy93387fa2016-12-01 01:03:44205* Build in release mode (debugging symbols require more memory):
brettwc25693b32016-05-26 01:11:52206 `is_debug = false`
sdy93387fa2016-12-01 01:03:44207* Turn off symbols: `symbol_level = 0`
208* Build in component mode (this is for development only, it will be slower and
209 may have broken functionality): `is_component_build = true`
andybons3322f762015-08-24 21:37:09210
dpranke0ae7cad2016-11-30 07:47:58211### More links
andybons3322f762015-08-24 21:37:09212
brettwc25693b32016-05-26 01:11:52213* Information about [building with Clang](clang.md).
dpranke0ae7cad2016-11-30 07:47:58214* You may want to [use a chroot](using_a_linux_chroot.md) to
215 isolate yourself from versioning or packaging conflicts.
andybonsad92aa32015-08-31 02:27:44216* Cross-compiling for ARM? See [LinuxChromiumArm](linux_chromium_arm.md).
217* Want to use Eclipse as your IDE? See
218 [LinuxEclipseDev](linux_eclipse_dev.md).
dpranke0ae7cad2016-11-30 07:47:58219* Want to use your built version as your default browser? See
andybonsad92aa32015-08-31 02:27:44220 [LinuxDevBuildAsDefaultBrowser](linux_dev_build_as_default_browser.md).
andybons3322f762015-08-24 21:37:09221
dpranke0ae7cad2016-11-30 07:47:58222### Next Steps
andybonsad92aa32015-08-31 02:27:44223
224If you want to contribute to the effort toward a Chromium-based browser for
225Linux, please check out the [Linux Development page](linux_development.md) for
226more information.