Ninja

Based on original version from http://martine.github.com/ninja/

Ninja is a small build system with a focus on speed. It differs from other build systems in two major respects:


Contents

Note

I have forked the orignal version to support MINGW [13], MSYS [14], and CYGWIN [9] builds too.

Ninja should be usable on most platforms as cmake do!

Claus Klein

See the manual -- http://ClausKlein.github.com/ninja/doc/manual.html or doc/manual.asciidoc included in the distribution -- for background and more details.

Download the current Ninja source code as zip file from https://github.com/ClausKlein/ninja/zipball/develop

Getting a source code version of Ninja with git [3] to work with:

git clone git://github.com/ClausKlein/ninja.git
cd ninja
make ninja

Building

To bootstrap Ninja and you have python [5] istalled, run python ./bootstrap.py. It first blindly compiles all non-test source files together, then re-builds Ninja using itself and ./build.ninja. You should end up with a Ninja binary in the source root. Run ./ninja -h for help.

If you like to use cmake [1] and make [4] to bootstrap Ninja create a build dir and generate your build project:

mkdir -p build && cd build cmake .. && make # or you have already ninja installed cmake -G Ninja .. && ninja

You may also create a Mac OSX Package Maker installer with cpack:

cpack -C CPackConfig.cmake -G PackageMaker

On Windows you may want to create "Null Soft Installer":

cpack -C CPackConfig.cmake -G NSIS

The only file of interest to a user is the resulting Ninja binary.

You may install it yourself with:

sudo install ninja /usr/local/bin
# or
sudo make install

Contributing

If you want to work with code, you should use git-flow [2] . Fork the my git repository. Then, run:

git clone --recursive git@github.com:<username>/ninja.git
git branch develop origin/develop
git flow init -d
git flow feature start <your feature>

Then, do work and commit your changes:

git flow feature publish <your feature>

When done, open a pull request to your feature branch.

HACKING :)

Build Dependencies:

Requiered packages:

Recomended packages to use:

Requiered packages for development are:

Adjusting build flags and use ccache [7] at build.ninja:

CFLAGS=-O3 CXX='/opt/local/bin/ccache g++' ./configure.py \
  --with-gtest=./gtest-1.6.0

and rebuild.

Attention!

ninja -t clean removes generated source files!

You need re2c [15] to build it again with your installed ninja.

To bootstap it again you have to restore this generated sources:

git checkout src/depfile_parser.cc src/lexer.cc

The build times for ninja on a macbok pro with 2 CPU cores are:

1.) build without ccache rebuild with ccache build "no work to do"
real 0m9.444s real 0m0.849s real 0m0.005s
user 0m14.492s user 0m0.202s user 0m0.002s
sys 0m1.838s sys 0m0.248s sys 0m0.003s
Building tests requires gtest, to get it:
  • On older Ubuntus you can apt-get install libgtest.
  • On newer Ubuntus it's only distributed as source; 1) apt-get install libgtest-dev 2) ./configure --with-gtest=/usr/src/gtest
  • Otherwise you need to download it, unpack it, and pass --with-gtest as appropriate.

Test-driven development:

Depends on gtest [12] source pack - Google's framework for writing C++ tests

Set your build command to:

sudo apt-get install libgtest-dev
./ninja ninja_test && ./ninja_test --gtest_filter=MyTest.Name

now you can repeatedly run that while developing until the tests pass. Remember to build "all" before committing to verify the other source still works!

Testing performance impact of changes:

If you have a Chrome build handy, it's a good test case. Otherwise, https://github.com/martine/ninja/downloads has a copy of the Chrome build files (and depfiles). You can untar that, then run:

path/to/my/ninja chrome

and compare that against a baseline Ninja.

There's a script at misc/measure.py that repeatedly runs a command like the above (to address variance) and summarizes its runtime. E.g.:

path/to/misc/measure.py path/to/my/ninja chrome

For changing the depfile parser, you can also build 'parser_perftest' and run that directly on some representative input files.

Coding guidelines:

  • Function name are camelcase.
  • Member methods are camelcase, expect for trivial getters which are underscore separated.
  • Local variables are underscore separated.
  • Member variables are underscore separated and suffixed by an extra underscore.
  • Two spaces indentation.
  • Opening braces is at the end of line.
  • Lines are 80 columns maximum.
  • All source files should have the Google Inc. license header.
  • Also follow this style: http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml

Documentation guidelines:

  • Use /// for doxygen [11].
  • Use a to refer to arguments.
  • It's not necessary to document each argument, especially when they're relatively self-evident (e.g. in CanonicalizePath(string* path, string* err), the arguments are hopefully obvious)

Build docu:

sudo apt-get install doxygen
./ninja doxygen

Generating the manual:

You need asciidoc [6] to do it:

sudo apt-get install asciidoc --no-install-recommends
./ninja manual

Windows development on Linux (this is kind of hacky right now):

  • Get the gtest [12] source, unpack it into your source dir:

    sudo apt-get install gcc-mingw32 wine
    #or export CC=i586-mingw32msvc-cc CXX=i586-mingw32msvc-c++ AR=i586-mingw32msvc-ar
    
    CC=i386-mingw32-cc CXX=i386-mingw32-c++ AR=i386-mingw32-ar \
      ./configure.py --platform=mysys --with-gtest=./gtest-1.6.0
    
  • Build ninja:

    /path/to/linux/ninja
    
  • Run: ./ninja.exe (implicitly runs through wine [16] (!) )

Windows development on Windows:

  • install mingw [13], msys [14], and python [5]
  • in the mingw shell, put Python in your path, and: python bootstrap.py
  • to reconfigure, run python configure.py
  • remember to strip the resulting executable if size matters to you
  • you'll need to rename ninja.exe into my-ninja.exe during development, otherwise ninja won't be able to overwrite itself when building

Using clang [8]:

  • Enable colors manually:

    CXX='/path/to/llvm/Release+Asserts/bin/clang++ -fcolor-diagnostics' ./configure.py
    

Using Ninja with an IDE:

You can configure the make [4] program as <path/to>/ninja within a custom project in Eclipse, NetBeans, or Visual Studio 2005.

Hint

cmake [1] starting with version 2.8.9 supports on all platforms ninja as buildsytem. You may generate projects for:

  • 'Eclipse CDT4 - Ninja'
  • 'KDevelop3 - Ninja'
  • 'CodeBlocks - Ninja'

Or you may always use a Makefile "stub" and import your project as a Makefile based project. Use a Makefile like this:

MAKEFLAGS+= --no-builtin-rules
export MAKE:=${MAKE} -${MAKEFLAGS}
.SILENT:

.DEFAULT: all
all::

.PHONY: help
help:
        ninja -t targets

# NoOp rules for this Makefile
Makefile: ;

# Anything we don't know how to build will use this rule.
#
% :: ;
        ninja $@


[1](1, 2) http://cmake.org/
[2](1, 2) http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/
[3](1, 2) http://git-scm.com/documentation/
[4](1, 2) http://www.gnu.org/software/make/make.html
[5](1, 2, 3) http://python.org/
[6](1, 2) http://www.methods.co.nz/asciidoc/
[7](1, 2) http://ccache.samba.org/
[8]http://clang.llvm.org/
[9]http://www.cygwin.com/
[10]http://docutils.sourceforge.net/
[11](1, 2) http://www.doxygen.org/
[12](1, 2, 3) http://code.google.com/p/googletest/
[13](1, 2) http://mingw.org/
[14](1, 2) http://mingw.org/wiki/MSYS/
[15](1, 2) http://re2c.sf.net/
[16]http://winehq.org/

License

Copyright 2012 Google Inc. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.