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