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're allowed to use `Goma` and have 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#### Disable NaCl 157 158By default, the build includes support for 159[Native Client (NaCl)](https://developer.chrome.com/native-client), but 160most of the time you won't need it. You can set the GN argument 161`enable_nacl=false` and it won't be built. 162 163#### Include fewer debug symbols 164 165By default GN produces a build with all of the debug assertions enabled 166(`is_debug=true`) and including full debug info (`symbol_level=2`). Setting 167`symbol_level=1` will produce enough information for stack traces, but not 168line-by-line debugging. Setting `symbol_level=0` will include no debug 169symbols at all. Either will speed up the build compared to full symbols. 170 171#### Disable debug symbols for Blink 172 173Due to its extensive use of templates, the Blink code produces about half 174of our debug symbols. If you don't ever need to debug Blink, you can set 175the GN arg `blink_symbol_level=0`. 176 177#### Use Icecc 178 179[Icecc](https://github.com/icecc/icecream) is the distributed compiler with a 180central scheduler to share build load. Currently, many external contributors use 181it. e.g. Intel, Opera, Samsung (this is not useful if you're using Goma). 182 183In order to use `icecc`, set the following GN args: 184 185``` 186use_debug_fission=false 187is_clang=false 188``` 189 190See these links for more on the 191[bundled_binutils limitation](https://github.com/icecc/icecream/commit/b2ce5b9cc4bd1900f55c3684214e409fa81e7a92), 192the [debug fission limitation](http://gcc.gnu.org/wiki/DebugFission). 193 194Using the system linker may also be necessary when using glibc 2.21 or newer. 195See [related bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=808181). 196 197#### ccache 198 199You can use [ccache](https://ccache.samba.org) to speed up local builds (again, 200this is not useful if you're using Goma). 201 202Increase your ccache hit rate by setting `CCACHE_BASEDIR` to a parent directory 203that the working directories all have in common (e.g., 204`/home/yourusername/development`). Consider using 205`CCACHE_SLOPPINESS=include_file_mtime` (since if you are using multiple working 206directories, header times in svn sync'ed portions of your trees will be 207different - see 208[the ccache troubleshooting section](http://ccache.samba.org/manual.html#_troubleshooting) 209for additional information). If you use symbolic links from your home directory 210to get to the local physical disk directory where you keep those working 211development directories, consider putting 212 213 alias cd="cd -P" 214 215in your `.bashrc` so that `$PWD` or `cwd` always refers to a physical, not 216logical directory (and make sure `CCACHE_BASEDIR` also refers to a physical 217parent). 218 219If you tune ccache correctly, a second working directory that uses a branch 220tracking trunk and is up to date with trunk and was gclient sync'ed at about the 221same time should build chrome in about 1/3 the time, and the cache misses as 222reported by `ccache -s` should barely increase. 223 224This is especially useful if you use `git-new-workdir` and keep multiple local 225working directories going at once. 226 227#### Using tmpfs 228 229You can use tmpfs for the build output to reduce the amount of disk writes 230required. I.e. mount tmpfs to the output directory where the build output goes: 231 232As root: 233 234 mount -t tmpfs -o size=20G,nr_inodes=40k,mode=1777 tmpfs /path/to/out 235 236*** note 237**Caveat:** You need to have enough RAM + swap to back the tmpfs. For a full 238debug build, you will need about 20 GB. Less for just building the chrome target 239or for a release build. 240*** 241 242Quick and dirty benchmark numbers on a HP Z600 (Intel core i7, 16 cores 243hyperthreaded, 12 GB RAM) 244 245* With tmpfs: 246 * 12m:20s 247* Without tmpfs 248 * 15m:40s 249 250## Build Chromium 251 252Build Chromium (the "chrome" target) with Ninja using the command: 253 254```shell 255$ autoninja -C out/Default chrome 256``` 257 258(`autoninja` is a wrapper that automatically provides optimal values for the 259arguments passed to `ninja`.) 260 261You can get a list of all of the other build targets from GN by running `gn ls 262out/Default` from the command line. To compile one, pass the GN label to Ninja 263with no preceding "//" (so, for `//chrome/test:unit_tests` use `autoninja -C 264out/Default chrome/test:unit_tests`). 265 266## Run Chromium 267 268Once it is built, you can simply run the browser: 269 270```shell 271$ out/Default/chrome 272``` 273 274## Running test targets 275 276You can run the tests in the same way. You can also limit which tests are 277run using the `--gtest_filter` arg, e.g.: 278 279```shell 280$ out/Default/unit_tests --gtest_filter="PushClientTest.*" 281``` 282 283You can find out more about GoogleTest at its 284[GitHub page](https://github.com/google/googletest). 285 286## Update your checkout 287 288To update an existing checkout, you can run 289 290```shell 291$ git rebase-update 292$ gclient sync 293``` 294 295The first command updates the primary Chromium source repository and rebases 296any of your local branches on top of tip-of-tree (aka the Git branch 297`origin/master`). If you don't want to use this script, you can also just use 298`git pull` or other common Git commands to update the repo. 299 300The second command syncs dependencies to the appropriate versions and re-runs 301hooks as needed. 302 303## Tips, tricks, and troubleshooting 304 305### Linker Crashes 306 307If, during the final link stage: 308 309``` 310LINK out/Debug/chrome 311``` 312 313You get an error like: 314 315``` 316collect2: ld terminated with signal 6 Aborted terminate called after throwing an instance of 'std::bad_alloc' 317collect2: ld terminated with signal 11 [Segmentation fault], core dumped 318``` 319 320you are probably running out of memory when linking. You *must* use a 64-bit 321system to build. Try the following build settings (see [GN build 322configuration](https://www.chromium.org/developers/gn-build-configuration) for 323other settings): 324 325* Build in release mode (debugging symbols require more memory): 326 `is_debug = false` 327* Turn off symbols: `symbol_level = 0` 328* Build in component mode (this is for development only, it will be slower and 329 may have broken functionality): `is_component_build = true` 330 331### More links 332 333* Information about [building with Clang](../clang.md). 334* You may want to [use a chroot](using_a_chroot.md) to 335 isolate yourself from versioning or packaging conflicts. 336* Cross-compiling for ARM? See [LinuxChromiumArm](chromium_arm.md). 337* Want to use Eclipse as your IDE? See 338 [LinuxEclipseDev](eclipse_dev.md). 339* Want to use your built version as your default browser? See 340 [LinuxDevBuildAsDefaultBrowser](dev_build_as_default_browser.md). 341 342## Next Steps 343 344If you want to contribute to the effort toward a Chromium-based browser for 345Linux, please check out the [Linux Development page](development.md) for 346more information. 347 348## Notes for other distros <a name="notes"></a> 349 350### Arch Linux 351 352Instead of running `install-build-deps.sh` to install build dependencies, run: 353 354```shell 355$ sudo pacman -S --needed python perl gcc gcc-libs bison flex gperf pkgconfig \ 356nss alsa-lib glib2 gtk3 nspr ttf-ms-fonts freetype2 cairo dbus libgnome-keyring 357``` 358 359For the optional packages on Arch Linux: 360 361* `php-cgi` is provided with `pacman` 362* `wdiff` is not in the main repository but `dwdiff` is. You can get `wdiff` 363 in AUR/`yaourt` 364* `sun-java6-fonts` do not seem to be in main repository or AUR. 365 366### Crostini (Debian based) 367 368First install the `file` and `lsb-release` commands for the script to run properly: 369 370```shell 371$ sudo apt-get install file lsb-release 372``` 373 374Then invoke install-build-deps.sh with the `--no-arm` argument, 375because the ARM toolchain doesn't exist for this configuration: 376 377```shell 378$ sudo install-build-deps.sh --no-arm 379``` 380 381### Fedora 382 383Instead of running `build/install-build-deps.sh`, run: 384 385```shell 386su -c 'yum install git python bzip2 tar pkgconfig atk-devel alsa-lib-devel \ 387bison binutils brlapi-devel bluez-libs-devel bzip2-devel cairo-devel \ 388cups-devel dbus-devel dbus-glib-devel expat-devel fontconfig-devel \ 389freetype-devel gcc-c++ glib2-devel glibc.i686 gperf glib2-devel \ 390gtk3-devel java-1.*.0-openjdk-devel libatomic libcap-devel libffi-devel \ 391libgcc.i686 libgnome-keyring-devel libjpeg-devel libstdc++.i686 libX11-devel \ 392libXScrnSaver-devel libXtst-devel libxkbcommon-x11-devel ncurses-compat-libs \ 393nspr-devel nss-devel pam-devel pango-devel pciutils-devel \ 394pulseaudio-libs-devel zlib.i686 httpd mod_ssl php php-cli python-psutil wdiff \ 395xorg-x11-server-Xvfb' 396``` 397 398The fonts needed by Blink's web tests can be obtained by following [these 399instructions](https://gist.github.com/pwnall/32a3b11c2b10f6ae5c6a6de66c1e12ae). 400For the optional packages: 401 402* `php-cgi` is provided by the `php-cli` package. 403* `sun-java6-fonts` is covered by the instructions linked above. 404 405### Gentoo 406 407You can just run `emerge www-client/chromium`. 408 409### OpenSUSE 410 411Use `zypper` command to install dependencies: 412 413(openSUSE 11.1 and higher) 414 415```shell 416sudo zypper in subversion pkg-config python perl bison flex gperf \ 417 mozilla-nss-devel glib2-devel gtk-devel wdiff lighttpd gcc gcc-c++ \ 418 mozilla-nspr mozilla-nspr-devel php5-fastcgi alsa-devel libexpat-devel \ 419 libjpeg-devel libbz2-devel 420``` 421 422For 11.0, use `libnspr4-0d` and `libnspr4-dev` instead of `mozilla-nspr` and 423`mozilla-nspr-devel`, and use `php5-cgi` instead of `php5-fastcgi`. 424 425(openSUSE 11.0) 426 427```shell 428sudo zypper in subversion pkg-config python perl \ 429 bison flex gperf mozilla-nss-devel glib2-devel gtk-devel \ 430 libnspr4-0d libnspr4-dev wdiff lighttpd gcc gcc-c++ libexpat-devel \ 431 php5-cgi alsa-devel gtk3-devel jpeg-devel 432``` 433 434The Ubuntu package `sun-java6-fonts` contains a subset of Java of the fonts used. 435Since this package requires Java as a prerequisite anyway, we can do the same 436thing by just installing the equivalent openSUSE Sun Java package: 437 438```shell 439sudo zypper in java-1_6_0-sun 440``` 441 442WebKit is currently hard-linked to the Microsoft fonts. To install these using `zypper` 443 444```shell 445sudo zypper in fetchmsttfonts pullin-msttf-fonts 446``` 447 448To make the fonts installed above work, as the paths are hardcoded for Ubuntu, 449create symlinks to the appropriate locations: 450 451```shell 452sudo mkdir -p /usr/share/fonts/truetype/msttcorefonts 453sudo ln -s /usr/share/fonts/truetype/arial.ttf /usr/share/fonts/truetype/msttcorefonts/Arial.ttf 454sudo ln -s /usr/share/fonts/truetype/arialbd.ttf /usr/share/fonts/truetype/msttcorefonts/Arial_Bold.ttf 455sudo ln -s /usr/share/fonts/truetype/arialbi.ttf /usr/share/fonts/truetype/msttcorefonts/Arial_Bold_Italic.ttf 456sudo ln -s /usr/share/fonts/truetype/ariali.ttf /usr/share/fonts/truetype/msttcorefonts/Arial_Italic.ttf 457sudo ln -s /usr/share/fonts/truetype/comic.ttf /usr/share/fonts/truetype/msttcorefonts/Comic_Sans_MS.ttf 458sudo ln -s /usr/share/fonts/truetype/comicbd.ttf /usr/share/fonts/truetype/msttcorefonts/Comic_Sans_MS_Bold.ttf 459sudo ln -s /usr/share/fonts/truetype/cour.ttf /usr/share/fonts/truetype/msttcorefonts/Courier_New.ttf 460sudo ln -s /usr/share/fonts/truetype/courbd.ttf /usr/share/fonts/truetype/msttcorefonts/Courier_New_Bold.ttf 461sudo ln -s /usr/share/fonts/truetype/courbi.ttf /usr/share/fonts/truetype/msttcorefonts/Courier_New_Bold_Italic.ttf 462sudo ln -s /usr/share/fonts/truetype/couri.ttf /usr/share/fonts/truetype/msttcorefonts/Courier_New_Italic.ttf 463sudo ln -s /usr/share/fonts/truetype/impact.ttf /usr/share/fonts/truetype/msttcorefonts/Impact.ttf 464sudo ln -s /usr/share/fonts/truetype/times.ttf /usr/share/fonts/truetype/msttcorefonts/Times_New_Roman.ttf 465sudo ln -s /usr/share/fonts/truetype/timesbd.ttf /usr/share/fonts/truetype/msttcorefonts/Times_New_Roman_Bold.ttf 466sudo ln -s /usr/share/fonts/truetype/timesbi.ttf /usr/share/fonts/truetype/msttcorefonts/Times_New_Roman_Bold_Italic.ttf 467sudo ln -s /usr/share/fonts/truetype/timesi.ttf /usr/share/fonts/truetype/msttcorefonts/Times_New_Roman_Italic.ttf 468sudo ln -s /usr/share/fonts/truetype/verdana.ttf /usr/share/fonts/truetype/msttcorefonts/Verdana.ttf 469sudo ln -s /usr/share/fonts/truetype/verdanab.ttf /usr/share/fonts/truetype/msttcorefonts/Verdana_Bold.ttf 470sudo ln -s /usr/share/fonts/truetype/verdanai.ttf /usr/share/fonts/truetype/msttcorefonts/Verdana_Italic.ttf 471sudo ln -s /usr/share/fonts/truetype/verdanaz.ttf /usr/share/fonts/truetype/msttcorefonts/Verdana_Bold_Italic.ttf 472``` 473 474The Ubuntu package `sun-java6-fonts` contains a subset of Java of the fonts used. 475Since this package requires Java as a prerequisite anyway, we can do the same 476thing by just installing the equivalent openSUSE Sun Java package: 477 478```shell 479sudo zypper in java-1_6_0-sun 480``` 481 482WebKit is currently hard-linked to the Microsoft fonts. To install these using `zypper` 483 484```shell 485sudo zypper in fetchmsttfonts pullin-msttf-fonts 486``` 487 488To make the fonts installed above work, as the paths are hardcoded for Ubuntu, 489create symlinks to the appropriate locations: 490 491```shell 492sudo mkdir -p /usr/share/fonts/truetype/msttcorefonts 493sudo ln -s /usr/share/fonts/truetype/arial.ttf /usr/share/fonts/truetype/msttcorefonts/Arial.ttf 494sudo ln -s /usr/share/fonts/truetype/arialbd.ttf /usr/share/fonts/truetype/msttcorefonts/Arial_Bold.ttf 495sudo ln -s /usr/share/fonts/truetype/arialbi.ttf /usr/share/fonts/truetype/msttcorefonts/Arial_Bold_Italic.ttf 496sudo ln -s /usr/share/fonts/truetype/ariali.ttf /usr/share/fonts/truetype/msttcorefonts/Arial_Italic.ttf 497sudo ln -s /usr/share/fonts/truetype/comic.ttf /usr/share/fonts/truetype/msttcorefonts/Comic_Sans_MS.ttf 498sudo ln -s /usr/share/fonts/truetype/comicbd.ttf /usr/share/fonts/truetype/msttcorefonts/Comic_Sans_MS_Bold.ttf 499sudo ln -s /usr/share/fonts/truetype/cour.ttf /usr/share/fonts/truetype/msttcorefonts/Courier_New.ttf 500sudo ln -s /usr/share/fonts/truetype/courbd.ttf /usr/share/fonts/truetype/msttcorefonts/Courier_New_Bold.ttf 501sudo ln -s /usr/share/fonts/truetype/courbi.ttf /usr/share/fonts/truetype/msttcorefonts/Courier_New_Bold_Italic.ttf 502sudo ln -s /usr/share/fonts/truetype/couri.ttf /usr/share/fonts/truetype/msttcorefonts/Courier_New_Italic.ttf 503sudo ln -s /usr/share/fonts/truetype/impact.ttf /usr/share/fonts/truetype/msttcorefonts/Impact.ttf 504sudo ln -s /usr/share/fonts/truetype/times.ttf /usr/share/fonts/truetype/msttcorefonts/Times_New_Roman.ttf 505sudo ln -s /usr/share/fonts/truetype/timesbd.ttf /usr/share/fonts/truetype/msttcorefonts/Times_New_Roman_Bold.ttf 506sudo ln -s /usr/share/fonts/truetype/timesbi.ttf /usr/share/fonts/truetype/msttcorefonts/Times_New_Roman_Bold_Italic.ttf 507sudo ln -s /usr/share/fonts/truetype/timesi.ttf /usr/share/fonts/truetype/msttcorefonts/Times_New_Roman_Italic.ttf 508sudo ln -s /usr/share/fonts/truetype/verdana.ttf /usr/share/fonts/truetype/msttcorefonts/Verdana.ttf 509sudo ln -s /usr/share/fonts/truetype/verdanab.ttf /usr/share/fonts/truetype/msttcorefonts/Verdana_Bold.ttf 510sudo ln -s /usr/share/fonts/truetype/verdanai.ttf /usr/share/fonts/truetype/msttcorefonts/Verdana_Italic.ttf 511sudo ln -s /usr/share/fonts/truetype/verdanaz.ttf /usr/share/fonts/truetype/msttcorefonts/Verdana_Bold_Italic.ttf 512``` 513 514And then for the Java fonts: 515 516```shell 517sudo mkdir -p /usr/share/fonts/truetype/ttf-lucida 518sudo find /usr/lib*/jvm/java-1.6.*-sun-*/jre/lib -iname '*.ttf' -print \ 519 -exec ln -s {} /usr/share/fonts/truetype/ttf-lucida \; 520``` 521