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