docs/common_build_tasks.md

   1 # Common Build Tasks
   2
   3 The Chromium build system is a complicated beast of a system, and it is not very
   4 well documented beyond the basics of getting the source and building the
   5 Chromium product. This page has more advanced information about the build
   6 system.
   7
   8 If you're new to Chromium development, read the
   9 [getting started guides](http://dev.chromium.org/developers/how-tos/get-the-code).
  10
  11 There is some additional documentation on
  12 [setting GYP build parameters](http://dev.chromium.org/developers/gyp-environment-variables).
  13
  14 [TOC]
  15
  16 ## Faster Builds
  17
  18 ### Components Build
  19
  20 A non-standard build configuration is to use dynamic linking instead of static
  21 linking for the various modules in the Chromium codebase. This results in
  22 significantly faster link times, but is a divergence from what is shipped and
  23 primarily tested. To enable the
  24 [component build](http://www.chromium.org/developers/how-tos/component-build):
  25
  26     $ GYP_DEFINES="component=shared_library" gclient runhooks
  27
  28 or
  29
  30 ```
  31 C:\...\src>set GYP_DEFINES=component=shared_library
  32 C:\...\src>gclient runhooks
  33 ```
  34
  35 ### Windows: Debug Builds Link Faster
  36
  37 On Windows if using the components build, building in debug mode will generally
  38 link faster. This is because in debug mode, the linker works incrementally. In
  39 release mode, a full link is performed each time.
  40
  41 ### Mac: Disable Release Mode Stripping
  42
  43 On Mac, if building in release mode, one of the final build steps will be to
  44 strip the build products and create dSYM files. This process can slow down your
  45 incremental builds, but it can be disabled with the following define:
  46
  47     $ GYP_DEFINES="mac_strip_release=0" gclient runhooks
  48
  49 ### Mac: DCHECKs in Release Mode
  50
  51 DCHECKs are only designed to be run in debug builds. But building in release
  52 mode on Mac is significantly faster. You can have your cake and eat it too by
  53 building release mode with DCHECKs enabled using the following define:
  54
  55     $ GYP_DEFINES="dcheck_always_on=1" gclient runhooks
  56
  57 ### Linux
  58
  59 Linux has its own page on [making the build faster](linux_faster_builds.md).
  60
  61 ## Configuring the Build
  62
  63 ### Environment Variables
  64
  65 There are various environment variables that can be passed to the metabuild
  66 system GYP when generating project files. This is a summary of them:
  67
  68 TODO(andybons): Convert to list.
  69
  70 | GYP\_DEFINES | A set of key=value pairs separated by space that will set default values of variables used in .gyp and .gypi files |
  71 |:-------------|:-------------------------------------------------------------------------------------------------------------------|
  72 | GYP\_GENERATORS | The specific generator that creates build-system specific files                                                    |
  73 | GYP\_GENERATOR\_FLAGS | Flags that are passed down to the tool that generates the build-system specific files                              |
  74 | GYP\_GENERATOR\_OUTPUT | The directory that the top-level build output directory is relative to                                             |
  75
  76 Note also that GYP uses CPPFLAGS, CFLAGS, and CXXFLAGS when generating ninja
  77 files (the values at build time = ninja run time are _not_ used); see
  78 [gyp/generator/ninja.py](https://code.google.com/p/chromium/codesearch#chromium/src/tools/gyp/pylib/gyp/generator/ninja.py&q=cxxflags).
  79
  80 ### Variable Files
  81
  82 If you want to keep a set of variables established, there are a couple of magic
  83 files that GYP reads:
  84
  85 #### chromium.gyp\_env
  86
  87 Next to your top-level `/src/` directory, create a file called
  88 `chromium.gyp_env`. This holds a JSON dictionary, with the keys being any of the
  89 above environment variables. For the full list of supported keys, see
  90 [/src/build/gyp_helper.py](/build/gyp_helper.py).
  91
  92 ``` {
  93   'variables': {
  94     'mac_strip_release': 0,
  95   }, 'GYP_DEFINES':
  96     'clang=1 ' 'component=shared_library ' 'dcheck_always_on=1 '
  97 } ```
  98
  99 #### include.gyp
 100
 101 Or globally in your home directory, create a file `~/.gyp/include.gypi`.
 102
 103 #### supplement.gypi
 104
 105 The build system will also include any files named `/src/*/supplement.gypi`,
 106 which should be in the same format as include.gyp above.
 107
 108 ### Change the Build System
 109
 110 Most platforms support multiple build systems (Windows: different Visual Studios
 111 versions and ninja, Mac: Xcode and ninja, etc.). A sensible default is selected,
 112 but it can be overridden:
 113
 114     $ GYP_GENERATORS=ninja gclient runhooks
 115
 116 [Ninja](ninja_build.md) is generally the fastest way to build anything on any
 117 platform.
 118
 119 ### Change Build Output Directory
 120
 121 If you need to change a compile-time flag and do not want to touch your current
 122 build output, you can re-run GYP and place output into a new directory, like so,
 123 assuming you are using ninja:
 124
 125 ```shell
 126 $ GYP_GENERATOR_FLAGS="output_dir=out_other_ninja" gclient runhooks
 127 $ ninja -C out_other_ninja/Release chrome
 128 ```
 129
 130 Alternatively, you can do the following, which should work with all GYP
 131 generators, but the out directory is nested as `out_other/out/`.
 132
 133 ```shell
 134 $ GYP_GENERATOR_OUTPUT="out_other" gclient runhooks
 135 $ ninja -C out_other/out/Release chrome
 136 ```
 137
 138 **Note:** If you wish to run the WebKit layout tests, make sure you specify the
 139 new directory using `--build-directory=out_other_ninja` (don't include the
 140 `Release` part).
 141
 142 ### Building Google Chrome
 143
 144 To build Chrome, you need to be a Google employee and have access to the
 145 [src-internal](https://goto.google.com/src-internal) repository. Once your
 146 checkout is set up, you can run gclient like so:
 147
 148     $ GYP_DEFINES="branding=Chrome buildtype=Official" gclient runhooks
 149
 150 Then building the `chrome` target will produce the official build. This tip can
 151 be used in conjunction with changing the output directory, since changing these
 152 defines will rebuild the world.
 153
 154 Also note that some GYP\_DEFINES flags are incompatible with the official build.
 155 If you get an error when you try to build, try removing all your flags and start
 156 with just the above ones.