docs/ninja_build.md

   1 # Ninja Build
   2
   3 Ninja is a build system written with the specific goal of improving the
   4 edit-compile cycle time. It is used by default everywhere except when building
   5 for iOS.
   6
   7 Ninja behaves very similar to Make -- the major feature is that it starts
   8 building files nearly instantly. (It has a number of minor user interface
   9 improvements to make as well.)
  10
  11 Read more about Ninja at
  12 [the Ninja home page](http://martine.github.com/ninja/).
  13
  14 ## Using it
  15
  16 ### Configure your system to use Ninja
  17
  18 #### Install
  19
  20 Ninja is included in `depot_tools` as well as `gyp`, so there's nothing to
  21 install.
  22
  23 ## Build instructions
  24
  25 To build Chrome:
  26
  27     cd /path/to/chrome/src
  28     ninja -C out/Debug chrome
  29
  30 Specify `out/Release` for a release build. I recommend setting up an alias so
  31 that you don't need to type out that build directory path.
  32
  33 If you want to build all targets, use `ninja -C out/Debug all`. It's faster to
  34 build only the target you're working on, like `chrome` or `unit_tests`.
  35
  36 ## Android
  37
  38 Identical to Linux, just make sure `OS=android` is in your `GYP_DEFINES`. You
  39 want to build one of the apk targets, e.g. `content_shell_apk`.
  40
  41 ## Windows
  42
  43 Similar to Linux. It uses MSVS's `cl.exe`, `link.exe`, etc. so you still need to
  44 have VS installed. To use it, open `cmd.exe`, go to your chrome checkout, and
  45 run:
  46
  47     set GYP_DEFINES=component=shared_library
  48     python build\gyp_chromium
  49     ninja -C out\Debug chrome.exe
  50
  51 `component=shared_library` is optional but recommended for faster links.
  52
  53 You can also set `GYP_GENERATORS=ninja,msvs-ninja` to get both VS projects
  54 generated if you want to use VS just to browse/edit (but then gyp takes twice as
  55 long to run).
  56
  57 If you're using Express or the Windows SDK by itself (rather than using a Visual
  58 Studio install), you'll need to run from a vcvarsall command prompt.
  59
  60 ### Debugging
  61
  62 Miss VS for debugging?
  63
  64 ```
  65 devenv.com /debugexe chrome.exe --my-great-args "go here" --single-process etc
  66 ```
  67
  68 Miss Xcode for debugging? Read
  69 http://dev.chromium.org/developers/debugging-on-os-x/building-with-ninja-debugging-with-xcode
  70
  71 ### Without Visual Studio
  72
  73 That is, building with just the WinDDK. This is documented in the
  74 [regular build instructions](http://dev.chromium.org/developers/how-tos/build-instructions-windows#TOC-Setting-up-the-environment-for-building-with-Visual-C-2010-Express-or-Windows-7.1-SDK).
  75
  76 ## Tweaks
  77
  78 ### Building through errors
  79
  80 Pass a flag like `-k3` to make Ninja build until it hits three errors instead of
  81 stopping at the first.
  82
  83 ### Parallelism
  84
  85 Pass a flag like `-j8` to use 8 parallel processes, or `-j1` to compile just one
  86 at a time (helpful if you're getting weird compiler errors). By default Ninja
  87 tries to use all your processors.
  88
  89 ### More options
  90
  91 There are more options. Run `ninja --help` to see them all.
  92
  93 ### Custom build configs
  94
  95 You can write a specific build config to a specific output directory via the
  96 `-G` flags to gyp. Here's an example from jamesr:
  97 `build/gyp_chromium -Gconfig=Release -Goutput_dir=out_profiling -Dprofiling=1
  98 -Dlinux_fpic=0`
  99
 100 ## Bugs
 101
 102 If you encounter any problems, please file a bug at http://crbug.com/new with
 103 label `ninja` and cc `thakis@` or `scottmg@`.  Assume that it is a bug in Ninja
 104 before you bother anyone about e.g. link problems.