3 `./configure.py` generates the `build.ninja` files used to build
4 ninja. It accepts various flags to adjust build parameters.
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.
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.)
14 ### Adjusting build flags
16 Build in "debug" mode while developing (disables optimizations and builds
17 way faster on Windows):
19 ./configure.py --debug
21 To use clang, set `CXX`:
23 CXX=clang++ ./configure.py
25 ## How to successfully make changes to Ninja
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.).
31 Good pull requests have all of these attributes:
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
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).
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
53 ### Test-driven development
55 Set your build command to
57 ./ninja ninja_test && ./ninja_test --gtest_filter=MyTest.Name
59 now you can repeatedly run that while developing until the tests pass
60 (I frequently set it as my compilation command in Emacs). Remember to
61 build "all" before committing to verify the other source still works!
63 ## Testing performance impact of changes
65 If you have a Chrome build handy, it's a good test case. Otherwise,
66 [the github downoads page](https://github.com/martine/ninja/downloads)
67 has a copy of the Chrome build files (and depfiles). You can untar
70 path/to/my/ninja chrome
72 and compare that against a baseline Ninja.
74 There's a script at `misc/measure.py` that repeatedly runs a command like
75 the above (to address variance) and summarizes its runtime. E.g.
77 path/to/misc/measure.py path/to/my/ninja chrome
79 For changing the depfile parser, you can also build `parser_perftest`
80 and run that directly on some representative input files.
84 Generally it's the [Google C++ coding style][], but in brief:
86 * Function name are camelcase.
87 * Member methods are camelcase, expect for trivial getters which are
89 * Local variables are underscore separated.
90 * Member variables are underscore separated and suffixed by an extra
92 * Two spaces indentation.
93 * Opening braces is at the end of line.
94 * Lines are 80 columns maximum.
95 * All source files should have the Google Inc. license header.
97 [Google C++ coding style]: http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
103 * Use `///` for doxygen.
104 * Use `\a` to refer to arguments.
105 * It's not necessary to document each argument, especially when they're
106 relatively self-evident (e.g. in `CanonicalizePath(string* path, string* err)`,
107 the arguments are hopefully obvious)
109 ### Building the manual
111 sudo apt-get install asciidoc --no-install-recommends
114 ### Building the code documentation
116 sudo apt-get install doxygen
119 ## Building for Windows
121 While developing, it's helpful to copy `ninja.exe` to another name like
122 `n.exe`; otherwise, rebuilds will be unable to write `ninja.exe` because
123 it's locked while in use.
125 ### Via Visual Studio
127 * Install Visual Studio (Express is fine), [Python for Windows][],
128 and (if making changes) googletest (see above instructions)
129 * In a Visual Studio command prompt: `python bootstrap.py`
131 [Python for Windows]: http://www.python.org/getit/windows/
133 ### Via mingw on Windows (not well supported)
135 * Install mingw, msys, and python
136 * In the mingw shell, put Python in your path, and `python bootstrap.py`
137 * To reconfigure, run `python configure.py`
138 * Remember to strip the resulting executable if size matters to you
140 ### Via mingw on Linux (not well supported)
142 Setup on Ubuntu Lucid:
143 * `sudo apt-get install gcc-mingw32 wine`
144 * `export CC=i586-mingw32msvc-cc CXX=i586-mingw32msvc-c++ AR=i586-mingw32msvc-ar`
146 Setup on Ubuntu Precise:
147 * `sudo apt-get install gcc-mingw-w64-i686 g++-mingw-w64-i686 wine`
148 * `export CC=i686-w64-mingw32-gcc CXX=i686-w64-mingw32-g++ AR=i686-w64-mingw32-ar`
151 * Uncomment the `[multilib]` section of `/etc/pacman.conf` and `sudo pacman -Sy`.
152 * `sudo pacman -S mingw-w64-gcc wine`
153 * `export CC=x86_64-w64-mingw32-cc CXX=x86_64-w64-mingw32-c++ AR=x86_64-w64-mingw32-ar`
154 * `export CFLAGS=-I/usr/x86_64-w64-mingw32/include`
157 * `./configure.py --platform=mingw --host=linux`
158 * Build `ninja.exe` using a Linux ninja binary: `/path/to/linux/ninja`
159 * Run: `./ninja.exe` (implicitly runs through wine(!))
161 ### Using Microsoft compilers on Linux (extremely flaky)
163 The trick is to install just the compilers, and not all of Visual Studio,
164 by following [these instructions][win7sdk].
166 [win7sdk]: http://www.kegel.com/wine/cl-howto-win7sdk.html