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.
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.
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.
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).
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.
28 See below if you want to use mingw or some other compiler instead of
31 ##### Using Visual Studio
32 Assuming that you now have Python installed, then the steps for building under
33 Windows using Visual Studio are:
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:
39 $ git clone git://github.com/ninja-build/ninja.git && cd ninja
40 $ git checkout release
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.
50 The steps for a Visual Studio 2015 64-bit build are outlined here:
53 > "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" x64
54 > python configure.py --bootstrap
57 Copy the ninja executable to another location, if desired, e.g. C:\local\Ninja.
59 Finally add the path where ninja.exe is to the PATH variable.
61 ### Adjusting build flags
63 Build in "debug" mode while developing (disables optimizations and builds
64 way faster on Windows):
66 ./configure.py --debug
68 To use clang, set `CXX`:
70 CXX=clang++ ./configure.py
72 ## How to successfully make changes to Ninja
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.).
78 Good pull requests have all of these attributes:
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
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).
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.
100 ### Test-driven development
102 Set your build command to
104 ./ninja ninja_test && ./ninja_test --gtest_filter=MyTest.Name
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!
110 ## Testing performance impact of changes
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.
116 path/to/misc/measure.py path/to/my/ninja chrome
118 For changing the depfile parser, you can also build `parser_perftest`
119 and run that directly on some representative input files.
123 Generally it's the [Google C++ coding style][], but in brief:
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
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.
136 [Google C++ coding style]: https://google.github.io/styleguide/cppguide.html
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)
148 ### Building the manual
150 sudo apt-get install asciidoc --no-install-recommends
153 ### Building the code documentation
155 sudo apt-get install doxygen
158 ## Building for Windows
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.
164 ### Via Visual Studio
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`
170 [Python for Windows]: http://www.python.org/getit/windows/
172 ### Via mingw on Windows (not well supported)
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
180 ### Via mingw on Linux (not well supported)
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`
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`
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`
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(!))
201 ### Using Microsoft compilers on Linux (extremely flaky)
203 The trick is to install just the compilers, and not all of Visual Studio,
204 by following [these instructions][win7sdk].
206 [win7sdk]: http://www.kegel.com/wine/cl-howto-win7sdk.html
210 Do a clean debug build with the right flags:
212 CFLAGS=-coverage LDFLAGS=-coverage ./configure.py --debug
213 ninja -t clean ninja_test && ninja ninja_test
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
222 Look at the generated `.gcov` files directly, or use your favorite gcov viewer.
226 Build with afl-clang++:
228 CXX=path/to/afl-1.20b/afl-clang++ ./configure.py
231 Then run afl-fuzz like so:
233 afl-fuzz -i misc/afl-fuzz -o /tmp/afl-fuzz-out ./ninja -n -f @@
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.
238 #### Using afl-fuzz with asan
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):
244 CFLAGS="-fsanitize=address -isysroot $(xcrun -show-sdk-path)" \
245 LDFLAGS=-fsanitize=address CXX=path/to/afl-1.20b/afl-clang++ \
247 AFL_CXX=path/to/clang++ ninja
249 Make sure ninja can find the asan runtime:
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 @@