HACKING.md

   1 ## Basic overview
   2
   3 `./configure.py` generates the `build.ninja` files used to build
   4 ninja.  It accepts various flags to adjust build parameters.
   5
   6 The primary build target of interest is `ninja`, but when hacking on
   7 Ninja your changes should be testable so it's more useful to build
   8 and run `ninja_test` when developing.
   9
  10 (`./bootstrap.py` creates a bootstrap `ninja` and runs the above
  11 process; it's only necessary to run if you don't have a copy of
  12 `ninja` to build with.)
  13
  14 ### Adjusting build flags
  15
  16 Build in "debug" mode while developing (disables optimizations and builds
  17 way faster on Windows):
  18
  19     ./configure.py --debug
  20
  21 To use clang, set `CXX`:
  22
  23     CXX=clang++ ./configure.py
  24
  25 ## How to successfully make changes to Ninja
  26
  27 Github pull requests are convenient for me to merge (I can just click
  28 a button and it's all handled server-side), but I'm also comfortable
  29 accepting pre-github git patches (via `send-email` etc.).
  30
  31 Good pull requests have all of these attributes:
  32
  33 * Are scoped to one specific issue
  34 * Include a test to demonstrate their correctness
  35 * Update the docs where relevant
  36 * Match the Ninja coding style (see below)
  37 * Don't include a mess of "oops, fix typo" commits
  38
  39 These are typically merged without hesitation.  If a change is lacking
  40 any of the above I usually will ask you to fix it, though there are
  41 obvious exceptions (fixing typos in comments don't need tests).
  42
  43 I am very wary of changes that increase the complexity of Ninja (in
  44 particular, new build file syntax or command-line flags) or increase
  45 the maintenance burden of Ninja.  Ninja is already successfully in use
  46 by hundreds of developers for large projects and it already achieves
  47 (most of) the goals I set out for it to do.  It's probably best to
  48 discuss new feature ideas on the mailing list before I shoot down your
  49 patch.
  50
  51 ## Testing
  52
  53 ### Installing gtest
  54
  55 The `ninja_test` binary, containing all the tests, depends on the
  56 googletest (gtest) library.
  57
  58 * On older Ubuntus it'll install as libraries into `/usr/lib`:
  59
  60         apt-get install libgtest
  61
  62 * On newer Ubuntus it's only distributed as source
  63
  64         apt-get install libgtest-dev
  65         ./configure --with-gtest=/usr/src/gtest
  66
  67 * Otherwise you need to download it, unpack it, and pass
  68   `--with-gtest` to `configure.py`.  Get it from [its downloads
  69   page](http://code.google.com/p/googletest/downloads/list); [this
  70   direct download link might work
  71   too](http://googletest.googlecode.com/files/gtest-1.6.0.zip).
  72
  73 ### Test-driven development
  74
  75 Set your build command to
  76
  77     ./ninja ninja_test && ./ninja_test --gtest_filter=MyTest.Name
  78
  79 now you can repeatedly run that while developing until the tests pass
  80 (I frequently set it as my compilation command in Emacs).  Remember to
  81 build "all" before committing to verify the other source still works!
  82
  83 ## Testing performance impact of changes
  84
  85 If you have a Chrome build handy, it's a good test case.  Otherwise,
  86 [the github downoads page](https://github.com/martine/ninja/downloads)
  87 has a copy of the Chrome build files (and depfiles). You can untar
  88 that, then run
  89
  90     path/to/my/ninja chrome
  91
  92 and compare that against a baseline Ninja.
  93
  94 There's a script at `misc/measure.py` that repeatedly runs a command like
  95 the above (to address variance) and summarizes its runtime.  E.g.
  96
  97     path/to/misc/measure.py path/to/my/ninja chrome
  98
  99 For changing the depfile parser, you can also build `parser_perftest`
 100 and run that directly on some representative input files.
 101
 102 ## Coding guidelines
 103
 104 Generally it's the [Google C++ coding style][], but in brief:
 105
 106 * Function name are camelcase.
 107 * Member methods are camelcase, expect for trivial getters which are
 108   underscore separated.
 109 * Local variables are underscore separated.
 110 * Member variables are underscore separated and suffixed by an extra
 111   underscore.
 112 * Two spaces indentation.
 113 * Opening braces is at the end of line.
 114 * Lines are 80 columns maximum.
 115 * All source files should have the Google Inc. license header.
 116
 117 [Google C++ coding style]: http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
 118
 119 ## Documentation
 120
 121 ### Style guidelines
 122
 123 * Use `///` for doxygen.
 124 * Use `\a` to refer to arguments.
 125 * It's not necessary to document each argument, especially when they're
 126   relatively self-evident (e.g. in `CanonicalizePath(string* path, string* err)`,
 127   the arguments are hopefully obvious)
 128
 129 ### Building the manual
 130
 131     sudo apt-get install asciidoc --no-install-recommends
 132     ./ninja manual
 133
 134 ### Building the code documentation
 135
 136     sudo apt-get install doxygen
 137     ./ninja doxygen
 138
 139 ## Building for Windows
 140
 141 While developing, it's helpful to copy `ninja.exe` to another name like
 142 `n.exe`; otherwise, rebuilds will be unable to write `ninja.exe` because
 143 it's locked while in use.
 144
 145 ### Via Visual Studio
 146
 147 * Install Visual Studio (Express is fine), [Python for Windows][],
 148   and (if making changes) googletest (see above instructions)
 149 * In a Visual Studio command prompt: `python bootstrap.py`
 150
 151 [Python for Windows]: http://www.python.org/getit/windows/
 152
 153 ### Via mingw on Windows (not well supported)
 154
 155 * Install mingw, msys, and python
 156 * In the mingw shell, put Python in your path, and `python bootstrap.py`
 157 * To reconfigure, run `python configure.py`
 158 * Remember to strip the resulting executable if size matters to you
 159
 160 ### Via mingw on Linux (not well supported)
 161
 162 Setup on Ubuntu Lucid:
 163 * `sudo apt-get install gcc-mingw32 wine`
 164 * `export CC=i586-mingw32msvc-cc CXX=i586-mingw32msvc-c++ AR=i586-mingw32msvc-ar`
 165
 166 Setup on Ubuntu Precise:
 167 * `sudo apt-get install gcc-mingw-w64-i686 g++-mingw-w64-i686 wine`
 168 * `export CC=i686-w64-mingw32-gcc CXX=i686-w64-mingw32-g++ AR=i686-w64-mingw32-ar`
 169
 170 Then run:
 171 * `./configure.py --platform=mingw --host=linux`
 172 * Build `ninja.exe` using a Linux ninja binary: `/path/to/linux/ninja`
 173 * Run: `./ninja.exe`  (implicitly runs through wine(!))
 174
 175 ### Using Microsoft compilers on Linux (extremely flaky)
 176
 177 The trick is to install just the compilers, and not all of Visual Studio,
 178 by following [these instructions][win7sdk].
 179
 180 [win7sdk]: http://www.kegel.com/wine/cl-howto-win7sdk.html