docs/linux_build_instructions.md

   1 # Build instructions for Linux
   2
   3 [TOC]
   4
   5 ## Overview
   6
   7 Due its complexity, Chromium uses a set of custom tools to check out and build.
   8 Here's an overview of the steps you'll run:
   9
  10 1.  **gclient**. A checkout involves pulling nearly 100 different SVN
  11     repositories of code.  This process is managed with a tool called `gclient`.
  12 1.  **gyp**. The cross-platform build configuration system is called `gyp`, and
  13     on Linux it generates ninja build files.  Running `gyp` is analogous to the
  14     `./configure` step seen in most other software.
  15 1.  **ninja**. The actual build itself uses `ninja`. A prebuilt binary is in
  16     `depot_tools` and should already be in your path if you followed the steps
  17     to check out Chromium.
  18 1.  We don't provide any sort of "install" step.
  19 1.  You may want to [use a chroot](using_a_linux_chroot.md) to isolate yourself
  20     from versioning or packaging conflicts (or to run the layout tests).
  21
  22 ## Getting a checkout
  23
  24 *   [Prerequisites](linux_build_instructions_prerequisites.md): what you need
  25     before you build.
  26 *   [Get the Code](http://dev.chromium.org/developers/how-tos/get-the-code):
  27     check out the source code.
  28
  29 *** note
  30 Note: if you are working on Chromium OS and already have sources in
  31 `chromiumos/chromium`, you **must** run `chrome_set_ver --runhooks` to set the
  32 correct dependencies. This step is otherwise performed by `gclient` as part of
  33 your checkout.
  34 ***
  35
  36 ## First Time Build Bootstrap
  37
  38 *   Make sure your dependencies are up to date by running the
  39     `install-build-deps.sh` script:
  40
  41     .../chromium/src$ build/install-build-deps.sh
  42
  43 *   Before you build, you should also
  44     [install API keys](https://sites.google.com/a/chromium.org/dev/developers/how-tos/api-keys).
  45
  46 ## `gyp` (configuring)
  47
  48 After `gclient sync` finishes, it will run `gyp` automatically to generate the
  49 ninja build files. For standard chromium builds, this automatic step is
  50 sufficient and you can start [compiling](linux_build_instructions.md).
  51
  52 To manually configure `gyp`, run `gclient runhooks` or run `gyp` directly via
  53 `build/gyp_chromium`. See [Configuring the Build](https://code.google.com/p/chromium/wiki/CommonBuildTasks#Configuring_the_Build) for detailed `gyp` options.
  54
  55 [GypUserDocumentation](https://code.google.com/p/gyp/wiki/GypUserDocumentation) gives background on `gyp`, but is not necessary if you are just building Chromium.
  56
  57 ### Configuring `gyp`
  58
  59 See [Configuring the Build](common_build_tasks.md) for details; most often
  60 you'll be changing the `GYP_DEFINES` options, which is discussed here.
  61
  62 `gyp` supports a minimal amount of build configuration via the `-D` flag.
  63
  64     build/gyp_chromium -Dflag1=value1 -Dflag2=value2
  65
  66 You can store these in the `GYP_DEFINES` environment variable, separating flags
  67 with spaces, as in:
  68
  69     export GYP_DEFINES="flag1=value1 flag2=value2"
  70
  71 After changing your `GYP_DEFINES` you need to rerun `gyp`, either implicitly via
  72 `gclient sync` (which also syncs) or `gclient runhooks` or explicitly via
  73 `build/gyp_chromium`.
  74
  75 Note that quotes are not necessary for a single flag, but are useful for
  76 clarity; `GYP_DEFINES=flag1=value1` is syntactically valid but can be confusing
  77 compared to `GYP_DEFINES="flag1=value1"`.
  78
  79 If you have various flags for various purposes, you may find it more legible to
  80 break them up across several lines, taking care to include spaces, such as like
  81 this:
  82
  83     export GYP_DEFINES="flag1=value1 flag2=value2"
  84
  85 or like this (allowing comments):
  86
  87     export GYP_DEFINES="flag1=value1" # comment
  88     GYP_DEFINES+=" flag2=value2" # another comment
  89
  90
  91 ### Sample configurations
  92
  93 *   **gcc warnings**. By default we fail to build if there are any compiler
  94     warnings. If you're getting warnings, can't build because of that, but just
  95     want to get things done, you can specify `-Dwerror=` to turn that off:
  96
  97 ```script
  98 # one-off
  99 build/gyp_chromium -Dwerror=
 100 # via variable
 101 export GYP_DEFINES="werror="
 102 build/gyp_chromium
 103 ```
 104
 105 *   **ChromeOS**. `-Dchromeos=1` builds the ChromeOS version of Chrome. This is
 106     **not** all of ChromeOS (see
 107     [the ChromiumOS](http://www.chromium.org/chromium-os) page for full build
 108     instructions), this is just the slightly tweaked version of the browser that
 109     runs on that system. Its not designed to be run outside of ChromeOS and some
 110     features won't work, but compiling on your Linux desktop can be useful for
 111     certain types of development and testing.
 112
 113 ```shell
 114 # one-off
 115 build/gyp_chromium -Dchromeos=1
 116 # via variable
 117 export GYP_DEFINES="chromeos=1"
 118 build/gyp_chromium
 119 ```
 120
 121 ## Compilation
 122
 123 The weird "`src/`" directory is an artifact of `gclient`. Start with:
 124
 125     $ cd src
 126
 127 ### Build just chrome
 128
 129     $ ninja -C out/Debug chrome
 130
 131
 132 ### Faster builds
 133
 134 See [Linux Faster Builds](linux_faster_builds.md)
 135
 136 ### Build every test
 137
 138     $ ninja -C out/Debug
 139
 140 The above builds all libraries and tests in all components. **It will take
 141 hours.**
 142
 143 Specifying other target names to restrict the build to just what you're
 144 interested in. To build just the simplest unit test:
 145
 146     $ ninja -C out/Debug base_unittests
 147
 148 ### Clang builds
 149
 150 Information about building with Clang can be found [here](clang.md).
 151
 152 ### Output
 153
 154 Executables are written in `src/out/Debug/` for Debug builds, and
 155 `src/out/Release/` for Release builds.
 156
 157 ### Release mode
 158
 159 Pass `-C out/Release` to the ninja invocation:
 160
 161     $ ninja -C out/Release chrome
 162
 163
 164 ### Seeing the commands
 165
 166 If you want to see the actual commands that ninja is invoking, add `-v` to the
 167 ninja invocation.
 168
 169     $ ninja -v -C out/Debug chrome
 170
 171 This is useful if, for example, you are debugging gyp changes, or otherwise need
 172 to see what ninja is actually doing.
 173
 174 ### Clean builds
 175
 176 All built files are put into the `out/` directory, so to start over with a clean
 177 build, just
 178
 179     rm -rf out
 180
 181 and run `gclient runhooks` or `build\gyp_chromium` again to recreate the ninja
 182 build files (which are also stored in `out/`). Or you can run `ninja -C
 183 out/Debug -t clean`.
 184
 185 ### Linker Crashes
 186
 187 If, during the final link stage:
 188
 189     LINK(target) out/Debug/chrome
 190
 191
 192 You get an error like:
 193
 194 ```
 195 collect2: ld terminated with signal 6 Aborted terminate called after throwing an
 196 instance of 'std::bad_alloc'
 197
 198 collect2: ld terminated with signal 11 [Segmentation fault], core dumped
 199 ```
 200
 201 you are probably running out of memory when linking. Try one of:
 202
 203 1.  Use the `gold` linker
 204 1.  Build on a 64-bit computer
 205 1.  Build in Release mode (debugging symbols require a lot of memory)
 206 1.  Build as shared libraries (note: this build is for developers only, and may
 207     have broken functionality)
 208
 209 Most of these are described on the [LinuxFasterBuilds](linux_faster_builds.md)
 210 page.
 211
 212 ## Advanced Features
 213
 214 *   Building frequently? See [LinuxFasterBuilds](linux_faster_builds.md).
 215 *   Cross-compiling for ARM? See [LinuxChromiumArm](linux_chromium_arm.md).
 216 *   Want to use Eclipse as your IDE? See
 217     [LinuxEclipseDev](linux_eclipse_dev.md).
 218 *   Built version as Default Browser? See
 219     [LinuxDevBuildAsDefaultBrowser](linux_dev_build_as_default_browser.md).
 220
 221 ## Next Steps
 222
 223 If you want to contribute to the effort toward a Chromium-based browser for
 224 Linux, please check out the [Linux Development page](linux_development.md) for
 225 more information.