1# Checking out and building Chromium on Linux 2 3There are instructions for other platforms linked from the 4[get the code](../get_the_code.md) page. 5 6## Instructions for Google Employees 7 8Are you a Google employee? See 9[go/building-chrome](https://goto.google.com/building-chrome) instead. 10 11[TOC] 12 13## System requirements 14 15* A 64-bit Intel machine with at least 8GB of RAM. More than 16GB is highly 16 recommended. 17* At least 100GB of free disk space. 18* You must have Git and Python v2 installed already. 19 20Most development is done on Ubuntu (currently 16.04, Xenial Xerus). There are 21some instructions for other distros below, but they are mostly unsupported. 22 23## Install `depot_tools` 24 25Clone the `depot_tools` repository: 26 27```shell 28$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git 29``` 30 31Add `depot_tools` to the end of your PATH (you will probably want to put this 32in your `~/.bashrc` or `~/.zshrc`). Assuming you cloned `depot_tools` to 33`/path/to/depot_tools`: 34 35```shell 36$ export PATH="$PATH:/path/to/depot_tools" 37``` 38 39When cloning `depot_tools` to your home directory **do not** use `~` on PATH, 40otherwise `gclient runhooks` will fail to run. Rather, you should use either 41`$HOME` or the absolute path: 42 43```shell 44$ export PATH="$PATH:${HOME}/depot_tools" 45``` 46 47## Get the code 48 49Create a `chromium` directory for the checkout and change to it (you can call 50this whatever you like and put it wherever you like, as long as the full path 51has no spaces): 52 53```shell 54$ mkdir ~/chromium && cd ~/chromium 55``` 56 57Run the `fetch` tool from depot_tools to check out the code and its 58dependencies. 59 60```shell 61$ fetch --nohooks chromium 62``` 63 64If you don't want the full repo history, you can save a lot of time by 65adding the `--no-history` flag to `fetch`. 66 67Expect the command to take 30 minutes on even a fast connection, and many 68hours on slower ones. 69 70If you've already installed the build dependencies on the machine (from another 71checkout, for example), you can omit the `--nohooks` flag and `fetch` 72will automatically execute `gclient runhooks` at the end. 73 74When `fetch` completes, it will have created a hidden `.gclient` file and a 75directory called `src` in the working directory. The remaining instructions 76assume you have switched to the `src` directory: 77 78```shell 79$ cd src 80``` 81 82### Install additional build dependencies 83 84Once you have checked out the code, and assuming you're using Ubuntu, run 85[build/install-build-deps.sh](/build/install-build-deps.sh) 86 87```shell 88$ ./build/install-build-deps.sh 89``` 90 91You may need to adjust the build dependencies for other distros. There are 92some [notes](#notes) at the end of this document, but we make no guarantees 93for their accuracy. 94 95### Run the hooks 96 97Once you've run `install-build-deps` at least once, you can now run the 98Chromium-specific hooks, which will download additional binaries and other 99things you might need: 100 101```shell 102$ gclient runhooks 103``` 104 105*Optional*: You can also [install API 106keys](https://www.chromium.org/developers/how-tos/api-keys) if you want your 107build to talk to some Google services, but this is not necessary for most 108development and testing purposes. 109 110## Setting up the build 111 112Chromium uses [Ninja](https://ninja-build.org) as its main build tool along with 113a tool called [GN](https://gn.googlesource.com/gn/+/master/docs/quick_start.md) 114to generate `.ninja` files. You can create any number of *build directories* 115with different configurations. To create a build directory, run: 116 117```shell 118$ gn gen out/Default 119``` 120 121* You only have to run this once for each new build directory, Ninja will 122 update the build files as needed. 123* You can replace `Default` with another name, but 124 it should be a subdirectory of `out`. 125* For other build arguments, including release settings, see [GN build 126 configuration](https://www.chromium.org/developers/gn-build-configuration). 127 The default will be a debug component build matching the current host 128 operating system and CPU. 129* For more info on GN, run `gn help` on the command line or read the 130 [quick start guide](https://gn.googlesource.com/gn/+/master/docs/quick_start.md). 131 132### <a name="faster-builds"></a>Faster builds 133 134This section contains some things you can change to speed up your builds, 135sorted so that the things that make the biggest difference are first. 136 137#### Use Goma 138 139Google developed the distributed compiler called 140[Goma](https://chromium.googlesource.com/infra/goma/client). 141Googlers and contributors who have 142[tryjob access](https://www.chromium.org/getting-involved/become-a-committer#TOC-Try-job-access) 143could use `Goma`. 144 145If you are not a Googler and would like to use `Goma` 146[sign up](https://docs.google.com/forms/d/1NKHcyqYqw3c4jftrLPwvyiPlolRm4Hf6ObrB83wHXy8/viewform). 147 148Once you've allowed to use `Goma` service and installed the client, 149[set the following GN args](https://www.chromium.org/developers/gn-build-configuration#TOC-Goma): 150 151``` 152use_goma=true 153goma_dir="/path/to/goma-client" 154``` 155 156#### Jumbo/Unity builds 157 158Jumbo builds merge many translation units ("source files") and compile them 159together. Since a large portion of Chromium's code is in shared header files, 160this dramatically reduces the total amount of work needed. Check out the 161[Jumbo / Unity builds](jumbo.md) for more information. 162 163Enable jumbo builds by setting the GN arg `use_jumbo_build=true`. 164 165#### Disable NaCl 166 167By default, the build includes support for 168[Native Client (NaCl)](https://developer.chrome.com/native-client), but 169most of the time you won't need it. You can set the GN argument 170`enable_nacl=false` and it won't be built. 171 172#### Include fewer debug symbols 173 174By default GN produces a build with all of the debug assertions enabled 175(`is_debug=true`) and including full debug info (`symbol_level=2`). Setting 176`symbol_level=1` will produce enough information for stack traces, but not 177line-by-line debugging. Setting `symbol_level=0` will include no debug 178symbols at all. Either will speed up the build compared to full symbols. 179 180#### Disable debug symbols for Blink 181 182Due to its extensive use of templates, the Blink code produces about half 183of our debug symbols. If you don't ever need to debug Blink, you can set 184the GN arg `blink_symbol_level=0`. 185 186#### Use Icecc 187 188[Icecc](https://github.com/icecc/icecream) is the distributed compiler with a 189central scheduler to share build load. Currently, many external contributors use 190it. e.g. Intel, Opera, Samsung (this is not useful if you're using Goma). 191 192In order to use `icecc`, set the following GN args: 193 194``` 195linux_use_bundled_binutils=false 196use_debug_fission=false 197is_clang=false 198``` 199 200See these links for more on the 201[bundled_binutils limitation](https://github.com/icecc/icecream/commit/b2ce5b9cc4bd1900f55c3684214e409fa81e7a92), 202the [debug fission limitation](http://gcc.gnu.org/wiki/DebugFission). 203 204Using the system linker may also be necessary when using glibc 2.21 or newer. 205See [related bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=808181). 206 207#### ccache 208 209You can use [ccache](https://ccache.samba.org) to speed up local builds (again, 210this is not useful if you're using Goma). 211 212Increase your ccache hit rate by setting `CCACHE_BASEDIR` to a parent directory 213that the working directories all have in common (e.g., 214`/home/yourusername/development`). Consider using 215`CCACHE_SLOPPINESS=include_file_mtime` (since if you are using multiple working 216directories, header times in svn sync'ed portions of your trees will be 217different - see 218[the ccache troubleshooting section](http://ccache.samba.org/manual.html#_troubleshooting) 219for additional information). If you use symbolic links from your home directory 220to get to the local physical disk directory where you keep those working 221development directories, consider putting 222 223 alias cd="cd -P" 224 225in your `.bashrc` so that `$PWD` or `cwd` always refers to a physical, not 226logical directory (and make sure `CCACHE_BASEDIR` also refers to a physical 227parent). 228 229If you tune ccache correctly, a second working directory that uses a branch 230tracking trunk and is up to date with trunk and was gclient sync'ed at about the 231same time should build chrome in about 1/3 the time, and the cache misses as 232reported by `ccache -s` should barely increase. 233 234This is especially useful if you use `git-new-workdir` and keep multiple local 235working directories going at once. 236 237#### Using tmpfs 238 239You can use tmpfs for the build output to reduce the amount of disk writes 240required. I.e. mount tmpfs to the output directory where the build output goes: 241 242As root: 243 244 mount -t tmpfs -o size=20G,nr_inodes=40k,mode=1777 tmpfs /path/to/out 245 246*** note 247**Caveat:** You need to have enough RAM + swap to back the tmpfs. For a full 248debug build, you will need about 20 GB. Less for just building the chrome target 249or for a release build. 250*** 251 252Quick and dirty benchmark numbers on a HP Z600 (Intel core i7, 16 cores 253hyperthreaded, 12 GB RAM) 254 255* With tmpfs: 256 * 12m:20s 257* Without tmpfs 258 * 15m:40s 259 260## Build Chromium 261 262Build Chromium (the "chrome" target) with Ninja using the command: 263 264```shell 265$ autoninja -C out/Default chrome 266``` 267 268(`autoninja` is a wrapper that automatically provides optimal values for the 269arguments passed to `ninja`.) 270 271You can get a list of all of the other build targets from GN by running `gn ls 272out/Default` from the command line. To compile one, pass the GN label to Ninja 273with no preceding "//" (so, for `//chrome/test:unit_tests` use `autoninja -C 274out/Default chrome/test:unit_tests`). 275 276## Run Chromium 277 278Once it is built, you can simply run the browser: 279 280```shell 281$ out/Default/chrome 282``` 283 284## Running test targets 285 286You can run the tests in the same way. You can also limit which tests are 287run using the `--gtest_filter` arg, e.g.: 288 289```shell 290$ out/Default/unit_tests --gtest_filter="PushClientTest.*" 291``` 292 293You can find out more about GoogleTest at its 294[GitHub page](https://github.com/google/googletest). 295 296## Update your checkout 297 298To update an existing checkout, you can run 299 300```shell 301$ git rebase-update 302$ gclient sync 303``` 304 305The first command updates the primary Chromium source repository and rebases 306any of your local branches on top of tip-of-tree (aka the Git branch 307`origin/master`). If you don't want to use this script, you can also just use 308`git pull` or other common Git commands to update the repo. 309 310The second command syncs dependencies to the appropriate versions and re-runs 311hooks as needed. 312 313## Tips, tricks, and troubleshooting 314 315### Linker Crashes 316 317If, during the final link stage: 318 319``` 320LINK out/Debug/chrome 321``` 322 323You get an error like: 324 325``` 326collect2: ld terminated with signal 6 Aborted terminate called after throwing an instance of 'std::bad_alloc' 327collect2: ld terminated with signal 11 [Segmentation fault], core dumped 328``` 329 330you are probably running out of memory when linking. You *must* use a 64-bit 331system to build. Try the following build settings (see [GN build 332configuration](https://www.chromium.org/developers/gn-build-configuration) for 333other settings): 334 335* Build in release mode (debugging symbols require more memory): 336 `is_debug = false` 337* Turn off symbols: `symbol_level = 0` 338* Build in component mode (this is for development only, it will be slower and 339 may have broken functionality): `is_component_build = true` 340 341### More links 342 343* Information about [building with Clang](../clang.md). 344* You may want to [use a chroot](using_a_chroot.md) to 345 isolate yourself from versioning or packaging conflicts. 346* Cross-compiling for ARM? See [LinuxChromiumArm](chromium_arm.md). 347* Want to use Eclipse as your IDE? See 348 [LinuxEclipseDev](eclipse_dev.md). 349* Want to use your built version as your default browser? See 350 [LinuxDevBuildAsDefaultBrowser](dev_build_as_default_browser.md). 351 352## Next Steps 353 354If you want to contribute to the effort toward a Chromium-based browser for 355Linux, please check out the [Linux Development page](development.md) for 356more information. 357 358## Notes for other distros <a name="notes"></a> 359 360### Arch Linux 361 362Instead of running `install-build-deps.sh` to install build dependencies, run: 363 364```shell 365$ sudo pacman -S --needed python perl gcc gcc-libs bison flex gperf pkgconfig \ 366nss alsa-lib glib2 gtk3 nspr ttf-ms-fonts freetype2 cairo dbus libgnome-keyring 367``` 368 369For the optional packages on Arch Linux: 370 371* `php-cgi` is provided with `pacman` 372* `wdiff` is not in the main repository but `dwdiff` is. You can get `wdiff` 373 in AUR/`yaourt` 374* `sun-java6-fonts` do not seem to be in main repository or AUR. 375 376### Crostini (Debian based) 377 378First install the `file` and `lsb-release` commands for the script to run properly: 379 380```shell 381$ sudo apt-get install file lsb-release 382``` 383 384Then invoke install-build-deps.sh with the `--no-arm` argument, 385because the ARM toolchain doesn't exist for this configuration: 386 387```shell 388$ sudo install-build-deps.sh --no-arm 389``` 390 391### Fedora 392 393Instead of running `build/install-build-deps.sh`, run: 394 395```shell 396su -c 'yum install git python bzip2 tar pkgconfig atk-devel alsa-lib-devel \ 397bison binutils brlapi-devel bluez-libs-devel bzip2-devel cairo-devel \ 398cups-devel dbus-devel dbus-glib-devel expat-devel fontconfig-devel \ 399freetype-devel gcc-c++ glib2-devel glibc.i686 gperf glib2-devel \ 400gtk3-devel java-1.*.0-openjdk-devel libatomic libcap-devel libffi-devel \ 401libgcc.i686 libgnome-keyring-devel libjpeg-devel libstdc++.i686 libX11-devel \ 402libXScrnSaver-devel libXtst-devel libxkbcommon-x11-devel ncurses-compat-libs \ 403nspr-devel nss-devel pam-devel pango-devel pciutils-devel \ 404pulseaudio-libs-devel zlib.i686 httpd mod_ssl php php-cli python-psutil wdiff \ 405xorg-x11-server-Xvfb' 406``` 407 408The fonts needed by Blink's web tests can be obtained by following [these 409instructions](https://gist.github.com/pwnall/32a3b11c2b10f6ae5c6a6de66c1e12ae). 410For the optional packages: 411 412* `php-cgi` is provided by the `php-cli` package. 413* `sun-java6-fonts` is covered by the instructions linked above. 414 415### Gentoo 416 417You can just run `emerge www-client/chromium`. 418 419### OpenSUSE 420 421Use `zypper` command to install dependencies: 422 423(openSUSE 11.1 and higher) 424 425```shell 426sudo zypper in subversion pkg-config python perl bison flex gperf \ 427 mozilla-nss-devel glib2-devel gtk-devel wdiff lighttpd gcc gcc-c++ \ 428 mozilla-nspr mozilla-nspr-devel php5-fastcgi alsa-devel libexpat-devel \ 429 libjpeg-devel libbz2-devel 430``` 431 432For 11.0, use `libnspr4-0d` and `libnspr4-dev` instead of `mozilla-nspr` and 433`mozilla-nspr-devel`, and use `php5-cgi` instead of `php5-fastcgi`. 434 435(openSUSE 11.0) 436 437```shell 438sudo zypper in subversion pkg-config python perl \ 439 bison flex gperf mozilla-nss-devel glib2-devel gtk-devel \ 440 libnspr4-0d libnspr4-dev wdiff lighttpd gcc gcc-c++ libexpat-devel \ 441 php5-cgi alsa-devel gtk3-devel jpeg-devel 442``` 443 444The Ubuntu package `sun-java6-fonts` contains a subset of Java of the fonts used. 445Since this package requires Java as a prerequisite anyway, we can do the same 446thing by just installing the equivalent openSUSE Sun Java package: 447 448```shell 449sudo zypper in java-1_6_0-sun 450``` 451 452WebKit is currently hard-linked to the Microsoft fonts. To install these using `zypper` 453 454```shell 455sudo zypper in fetchmsttfonts pullin-msttf-fonts 456``` 457 458To make the fonts installed above work, as the paths are hardcoded for Ubuntu, 459create symlinks to the appropriate locations: 460 461```shell 462sudo mkdir -p /usr/share/fonts/truetype/msttcorefonts 463sudo ln -s /usr/share/fonts/truetype/arial.ttf /usr/share/fonts/truetype/msttcorefonts/Arial.ttf 464sudo ln -s /usr/share/fonts/truetype/arialbd.ttf /usr/share/fonts/truetype/msttcorefonts/Arial_Bold.ttf 465sudo ln -s /usr/share/fonts/truetype/arialbi.ttf /usr/share/fonts/truetype/msttcorefonts/Arial_Bold_Italic.ttf 466sudo ln -s /usr/share/fonts/truetype/ariali.ttf /usr/share/fonts/truetype/msttcorefonts/Arial_Italic.ttf 467sudo ln -s /usr/share/fonts/truetype/comic.ttf /usr/share/fonts/truetype/msttcorefonts/Comic_Sans_MS.ttf 468sudo ln -s /usr/share/fonts/truetype/comicbd.ttf /usr/share/fonts/truetype/msttcorefonts/Comic_Sans_MS_Bold.ttf 469sudo ln -s /usr/share/fonts/truetype/cour.ttf /usr/share/fonts/truetype/msttcorefonts/Courier_New.ttf 470sudo ln -s /usr/share/fonts/truetype/courbd.ttf /usr/share/fonts/truetype/msttcorefonts/Courier_New_Bold.ttf 471sudo ln -s /usr/share/fonts/truetype/courbi.ttf /usr/share/fonts/truetype/msttcorefonts/Courier_New_Bold_Italic.ttf 472sudo ln -s /usr/share/fonts/truetype/couri.ttf /usr/share/fonts/truetype/msttcorefonts/Courier_New_Italic.ttf 473sudo ln -s /usr/share/fonts/truetype/impact.ttf /usr/share/fonts/truetype/msttcorefonts/Impact.ttf 474sudo ln -s /usr/share/fonts/truetype/times.ttf /usr/share/fonts/truetype/msttcorefonts/Times_New_Roman.ttf 475sudo ln -s /usr/share/fonts/truetype/timesbd.ttf /usr/share/fonts/truetype/msttcorefonts/Times_New_Roman_Bold.ttf 476sudo ln -s /usr/share/fonts/truetype/timesbi.ttf /usr/share/fonts/truetype/msttcorefonts/Times_New_Roman_Bold_Italic.ttf 477sudo ln -s /usr/share/fonts/truetype/timesi.ttf /usr/share/fonts/truetype/msttcorefonts/Times_New_Roman_Italic.ttf 478sudo ln -s /usr/share/fonts/truetype/verdana.ttf /usr/share/fonts/truetype/msttcorefonts/Verdana.ttf 479sudo ln -s /usr/share/fonts/truetype/verdanab.ttf /usr/share/fonts/truetype/msttcorefonts/Verdana_Bold.ttf 480sudo ln -s /usr/share/fonts/truetype/verdanai.ttf /usr/share/fonts/truetype/msttcorefonts/Verdana_Italic.ttf 481sudo ln -s /usr/share/fonts/truetype/verdanaz.ttf /usr/share/fonts/truetype/msttcorefonts/Verdana_Bold_Italic.ttf 482``` 483 484The Ubuntu package `sun-java6-fonts` contains a subset of Java of the fonts used. 485Since this package requires Java as a prerequisite anyway, we can do the same 486thing by just installing the equivalent openSUSE Sun Java package: 487 488```shell 489sudo zypper in java-1_6_0-sun 490``` 491 492WebKit is currently hard-linked to the Microsoft fonts. To install these using `zypper` 493 494```shell 495sudo zypper in fetchmsttfonts pullin-msttf-fonts 496``` 497 498To make the fonts installed above work, as the paths are hardcoded for Ubuntu, 499create symlinks to the appropriate locations: 500 501```shell 502sudo mkdir -p /usr/share/fonts/truetype/msttcorefonts 503sudo ln -s /usr/share/fonts/truetype/arial.ttf /usr/share/fonts/truetype/msttcorefonts/Arial.ttf 504sudo ln -s /usr/share/fonts/truetype/arialbd.ttf /usr/share/fonts/truetype/msttcorefonts/Arial_Bold.ttf 505sudo ln -s /usr/share/fonts/truetype/arialbi.ttf /usr/share/fonts/truetype/msttcorefonts/Arial_Bold_Italic.ttf 506sudo ln -s /usr/share/fonts/truetype/ariali.ttf /usr/share/fonts/truetype/msttcorefonts/Arial_Italic.ttf 507sudo ln -s /usr/share/fonts/truetype/comic.ttf /usr/share/fonts/truetype/msttcorefonts/Comic_Sans_MS.ttf 508sudo ln -s /usr/share/fonts/truetype/comicbd.ttf /usr/share/fonts/truetype/msttcorefonts/Comic_Sans_MS_Bold.ttf 509sudo ln -s /usr/share/fonts/truetype/cour.ttf /usr/share/fonts/truetype/msttcorefonts/Courier_New.ttf 510sudo ln -s /usr/share/fonts/truetype/courbd.ttf /usr/share/fonts/truetype/msttcorefonts/Courier_New_Bold.ttf 511sudo ln -s /usr/share/fonts/truetype/courbi.ttf /usr/share/fonts/truetype/msttcorefonts/Courier_New_Bold_Italic.ttf 512sudo ln -s /usr/share/fonts/truetype/couri.ttf /usr/share/fonts/truetype/msttcorefonts/Courier_New_Italic.ttf 513sudo ln -s /usr/share/fonts/truetype/impact.ttf /usr/share/fonts/truetype/msttcorefonts/Impact.ttf 514sudo ln -s /usr/share/fonts/truetype/times.ttf /usr/share/fonts/truetype/msttcorefonts/Times_New_Roman.ttf 515sudo ln -s /usr/share/fonts/truetype/timesbd.ttf /usr/share/fonts/truetype/msttcorefonts/Times_New_Roman_Bold.ttf 516sudo ln -s /usr/share/fonts/truetype/timesbi.ttf /usr/share/fonts/truetype/msttcorefonts/Times_New_Roman_Bold_Italic.ttf 517sudo ln -s /usr/share/fonts/truetype/timesi.ttf /usr/share/fonts/truetype/msttcorefonts/Times_New_Roman_Italic.ttf 518sudo ln -s /usr/share/fonts/truetype/verdana.ttf /usr/share/fonts/truetype/msttcorefonts/Verdana.ttf 519sudo ln -s /usr/share/fonts/truetype/verdanab.ttf /usr/share/fonts/truetype/msttcorefonts/Verdana_Bold.ttf 520sudo ln -s /usr/share/fonts/truetype/verdanai.ttf /usr/share/fonts/truetype/msttcorefonts/Verdana_Italic.ttf 521sudo ln -s /usr/share/fonts/truetype/verdanaz.ttf /usr/share/fonts/truetype/msttcorefonts/Verdana_Bold_Italic.ttf 522``` 523 524And then for the Java fonts: 525 526```shell 527sudo mkdir -p /usr/share/fonts/truetype/ttf-lucida 528sudo find /usr/lib*/jvm/java-1.6.*-sun-*/jre/lib -iname '*.ttf' -print \ 529 -exec ln -s {} /usr/share/fonts/truetype/ttf-lucida \; 530``` 531