docs/linux_build_instructions.md

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