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 ### Adjusting build flags
  11
  12 Build in "debug" mode while developing (disables optimizations and builds
  13 way faster on Windows):
  14
  15     ./configure.py --debug
  16
  17 To use clang, set `CXX`:
  18
  19     CXX=clang++ ./configure.py
  20
  21 ## How to successfully make changes to Ninja
  22
  23 Github pull requests are convenient for me to merge (I can just click
  24 a button and it's all handled server-side), but I'm also comfortable
  25 accepting pre-github git patches (via `send-email` etc.).
  26
  27 Good pull requests have all of these attributes:
  28
  29 * Are scoped to one specific issue
  30 * Include a test to demonstrate their correctness
  31 * Update the docs where relevant
  32 * Match the Ninja coding style (see below)
  33 * Don't include a mess of "oops, fix typo" commits
  34
  35 These are typically merged without hesitation.  If a change is lacking
  36 any of the above I usually will ask you to fix it, though there are
  37 obvious exceptions (fixing typos in comments don't need tests).
  38
  39 I am very wary of changes that increase the complexity of Ninja (in
  40 particular, new build file syntax or command-line flags) or increase
  41 the maintenance burden of Ninja.  Ninja is already successfully in use
  42 by hundreds of developers for large projects and it already achieves
  43 (most of) the goals I set out for it to do.  It's probably best to
  44 discuss new feature ideas on the mailing list before I shoot down your
  45 patch.
  46
  47 ## Testing
  48
  49 ### Test-driven development
  50
  51 Set your build command to
  52
  53     ./ninja ninja_test && ./ninja_test --gtest_filter=MyTest.Name
  54
  55 now you can repeatedly run that while developing until the tests pass
  56 (I frequently set it as my compilation command in Emacs).  Remember to
  57 build "all" before committing to verify the other source still works!
  58
  59 ## Testing performance impact of changes
  60
  61 If you have a Chrome build handy, it's a good test case.  Otherwise,
  62 [the github downoads page](https://github.com/martine/ninja/downloads)
  63 has a copy of the Chrome build files (and depfiles). You can untar
  64 that, then run
  65
  66     path/to/my/ninja chrome
  67
  68 and compare that against a baseline Ninja.
  69
  70 There's a script at `misc/measure.py` that repeatedly runs a command like
  71 the above (to address variance) and summarizes its runtime.  E.g.
  72
  73     path/to/misc/measure.py path/to/my/ninja chrome
  74
  75 For changing the depfile parser, you can also build `parser_perftest`
  76 and run that directly on some representative input files.
  77
  78 ## Coding guidelines
  79
  80 Generally it's the [Google C++ coding style][], but in brief:
  81
  82 * Function name are camelcase.
  83 * Member methods are camelcase, expect for trivial getters which are
  84   underscore separated.
  85 * Local variables are underscore separated.
  86 * Member variables are underscore separated and suffixed by an extra
  87   underscore.
  88 * Two spaces indentation.
  89 * Opening braces is at the end of line.
  90 * Lines are 80 columns maximum.
  91 * All source files should have the Google Inc. license header.
  92
  93 [Google C++ coding style]: http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
  94
  95 ## Documentation
  96
  97 ### Style guidelines
  98
  99 * Use `///` for doxygen.
 100 * Use `\a` to refer to arguments.
 101 * It's not necessary to document each argument, especially when they're
 102   relatively self-evident (e.g. in `CanonicalizePath(string* path, string* err)`,
 103   the arguments are hopefully obvious)
 104
 105 ### Building the manual
 106
 107     sudo apt-get install asciidoc --no-install-recommends
 108     ./ninja manual
 109
 110 ### Building the code documentation
 111
 112     sudo apt-get install doxygen
 113     ./ninja doxygen
 114
 115 ## Building for Windows
 116
 117 While developing, it's helpful to copy `ninja.exe` to another name like
 118 `n.exe`; otherwise, rebuilds will be unable to write `ninja.exe` because
 119 it's locked while in use.
 120
 121 ### Via Visual Studio
 122
 123 * Install Visual Studio (Express is fine), [Python for Windows][],
 124   and (if making changes) googletest (see above instructions)
 125 * In a Visual Studio command prompt: `python configure.py --bootstrap`
 126
 127 [Python for Windows]: http://www.python.org/getit/windows/
 128
 129 ### Via mingw on Windows (not well supported)
 130
 131 * Install mingw, msys, and python
 132 * In the mingw shell, put Python in your path, and
 133   `python configure.py --bootstrap`
 134 * To reconfigure, run `python configure.py`
 135 * Remember to strip the resulting executable if size matters to you
 136
 137 ### Via mingw on Linux (not well supported)
 138
 139 Setup on Ubuntu Lucid:
 140 * `sudo apt-get install gcc-mingw32 wine`
 141 * `export CC=i586-mingw32msvc-cc CXX=i586-mingw32msvc-c++ AR=i586-mingw32msvc-ar`
 142
 143 Setup on Ubuntu Precise:
 144 * `sudo apt-get install gcc-mingw-w64-i686 g++-mingw-w64-i686 wine`
 145 * `export CC=i686-w64-mingw32-gcc CXX=i686-w64-mingw32-g++ AR=i686-w64-mingw32-ar`
 146
 147 Setup on Arch:
 148 * Uncomment the `[multilib]` section of `/etc/pacman.conf` and `sudo pacman -Sy`.
 149 * `sudo pacman -S mingw-w64-gcc wine`
 150 * `export CC=x86_64-w64-mingw32-cc CXX=x86_64-w64-mingw32-c++ AR=x86_64-w64-mingw32-ar`
 151 * `export CFLAGS=-I/usr/x86_64-w64-mingw32/include`
 152
 153 Then run:
 154 * `./configure.py --platform=mingw --host=linux`
 155 * Build `ninja.exe` using a Linux ninja binary: `/path/to/linux/ninja`
 156 * Run: `./ninja.exe`  (implicitly runs through wine(!))
 157
 158 ### Using Microsoft compilers on Linux (extremely flaky)
 159
 160 The trick is to install just the compilers, and not all of Visual Studio,
 161 by following [these instructions][win7sdk].
 162
 163 [win7sdk]: http://www.kegel.com/wine/cl-howto-win7sdk.html
 164
 165 ### Using gcov
 166
 167 Do a clean debug build with the right flags:
 168
 169     CFLAGS=-coverage LDFLAGS=-coverage ./configure.py --debug
 170     ninja -t clean ninja_test && ninja ninja_test
 171
 172 Run the test binary to generate `.gcda` and `.gcno` files in the build
 173 directory, then run gcov on the .o files to generate `.gcov` files in the
 174 root directory:
 175
 176     ./ninja_test
 177     gcov build/*.o
 178
 179 Look at the generated `.gcov` files directly, or use your favorit gcov viewer.
 180
 181 ### Using afl-fuzz
 182
 183 Build with afl-clang++:
 184
 185     CXX=path/to/afl-1.20b/afl-clang++ ./configure.py
 186     ninja
 187
 188 Then run afl-fuzz like so:
 189
 190     afl-fuzz -i misc/afl-fuzz -o /tmp/afl-fuzz-out ./ninja -n -f @@
 191
 192 You can pass `-x misc/afl-fuzz-tokens` to use the token dictionary. In my
 193 testing, that did not seem more effective though.
 194
 195 #### Using afl-fuzz with asan
 196
 197 If you want to use asan (the `isysroot` bit is only needed on OS X; if clang
 198 can't find C++ standard headers make sure your LLVM checkout includes a libc++
 199 checkout and has libc++ installed in the build directory):
 200
 201     CFLAGS="-fsanitize=address -isysroot $(xcrun -show-sdk-path)" \
 202         LDFLAGS=-fsanitize=address CXX=path/to/afl-1.20b/afl-clang++ \
 203         ./configure.py
 204     AFL_CXX=path/to/clang++ ninja
 205
 206 Make sure ninja can find the asan runtime:
 207
 208     DYLD_LIBRARY_PATH=path/to//lib/clang/3.7.0/lib/darwin/ \
 209         afl-fuzz -i misc/afl-fuzz -o /tmp/afl-fuzz-out ./ninja -n -f @@