docs/linux_build_instructions.md

   1 # Linux-specific build instructions
   2
   3 [TOC]
   4
   5 ## Get the code
   6
   7 [Get the Code](http://dev.chromium.org/developers/how-tos/get-the-code). The
   8 general instructions on the "Get the code" page cover basic Linux build setup
   9 and configuration.
  10
  11 This page documents some additional Linux-specific build issues.
  12
  13 ## Overview
  14
  15 Due its complexity, Chromium uses a set of custom tools to check out and build.
  16 Here's an overview of the steps you'll run:
  17
  18 1.  **gclient**. A checkout involves pulling nearly 100 different SVN
  19     repositories of code. This process is managed with a tool called `gclient`.
  20 1.  **GN** / **gyp**. Cross-platform build configuration systems (GYP is the
  21     older one, GN is the one being transitioned to). It generates ninja build
  22     files. Running `gn`/`gyp` is analogous to the `./configure` step seen in
  23     most other software.
  24 1.  **ninja**. The actual build itself uses `ninja`. A prebuilt binary is in
  25     `depot_tools` and should already be in your path if you followed the steps
  26     to check out Chromium.
  27 1.  We don't provide any sort of "install" step.
  28 1.  You may want to
  29     [use a chroot](http://code.google.com/p/chromium/wiki/UsingALinuxChroot) to
  30     isolate yourself from versioning or packaging conflicts (or to run the
  31     layout tests).
  32
  33 ## Getting a checkout
  34
  35 [Prerequisites](linux_build_instructions_prerequisites.md): what you need before
  36 you build.
  37
  38 **Note**. If you are working on Chromium OS and already have sources in
  39 `chromiumos/chromium`, you **must** run `chrome_set_ver --runhooks` to set the
  40 correct dependencies. This step is otherwise performed by `gclient` as part of
  41 your checkout.
  42
  43 ## Compilation
  44
  45 The weird "`src/`" directory is an artifact of `gclient`. Start with:
  46
  47     $ cd src
  48
  49 ### Faster builds
  50
  51 See [Linux Faster Builds](linux_faster_builds.md)
  52
  53 ### Build every test
  54
  55     $ ninja -C out/Debug
  56
  57 The above builds all libraries and tests in all components. **It will take
  58 hours.**
  59
  60 Specifying other target names to restrict the build to just what you're
  61 interested in. To build just the simplest unit test:
  62
  63     $ ninja -C out/Debug base_unittests
  64
  65 ### Clang builds
  66
  67 Information about building with Clang can be found [here](clang.md).
  68
  69 ### Output
  70
  71 Executables are written in `src/out/Debug/` for Debug builds, and
  72 `src/out/Release/` for Release builds.
  73
  74 ### Release mode
  75
  76 Pass `-C out/Release` to the ninja invocation:
  77
  78     $ ninja -C out/Release chrome
  79
  80 ### Seeing the commands
  81
  82 If you want to see the actual commands that ninja is invoking, add `-v` to the
  83 ninja invocation.
  84
  85     $ ninja -v -C out/Debug chrome
  86
  87 This is useful if, for example, you are debugging gyp changes, or otherwise need
  88 to see what ninja is actually doing.
  89
  90 ### Clean builds
  91
  92 If you're using GN, you can clean the build directory (`out/Default` in this
  93 example):
  94
  95     gn clean out/Default
  96
  97 This will delete all files except a bootstrap ninja file necessary for
  98 recreating the build.
  99
 100 If you're using GYP, do:
 101
 102     rm -rf out
 103     gclient runhooks
 104
 105 Ninja can also be used to clean a build with `ninja -C out/Debug -t clean` but
 106 this will not be as complete as the above methods.
 107
 108 ### Linker Crashes
 109
 110 If, during the final link stage:
 111
 112     LINK(target) out/Debug/chrome
 113
 114 You get an error like:
 115
 116 ```
 117 collect2: ld terminated with signal 6 Aborted terminate called after throwing an
 118 instance of 'std::bad_alloc'
 119
 120 collect2: ld terminated with signal 11 [Segmentation fault], core dumped
 121 ```
 122 you are probably running out of memory when linking.  Try one of:
 123
 124 1.  Use the `gold` linker
 125 1.  Build on a 64-bit computer
 126 1.  Build in Release mode (debugging symbols require a lot of memory)
 127 1.  Build as shared libraries (note: this build is for developers only, and may
 128     have broken functionality)
 129
 130 Most of these are described on the [Linux Faster Builds](linux_faster_builds.md)
 131 page.
 132
 133 ## Advanced Features
 134
 135 *   Building frequently? See [LinuxFasterBuilds](linux_faster_builds.md).
 136 *   Cross-compiling for ARM? See [LinuxChromiumArm](linux_chromium_arm.md).
 137 *   Want to use Eclipse as your IDE? See
 138     [LinuxEclipseDev](linux_eclipse_dev.md).
 139 *   Built version as Default Browser? See
 140     [LinuxDevBuildAsDefaultBrowser](linux_dev_build_as_default_browser.md).
 141
 142 ## Next Steps
 143
 144 If you want to contribute to the effort toward a Chromium-based browser for
 145 Linux, please check out the [Linux Development page](linux_development.md) for
 146 more information.