README.md

ninja-build-gen

Create Ninja build-system manifests from JavaScript. This can be used for build in any kind of project, though (Ruby, Python, or even C++, why not...).

Install

The easiest is to use the mainstream Node.js package manager, npm, to handle the package installation. Most of the time, you'll add it to the devDependencies of your package.json, eg:

$ npm install ninja-build-gen --save-dev

You may typically want to install the ninja-build as well. Indeed, this package does not include the Ninja build system itself.

Generally, you should not need this package for package distribution (instead of being in dependencies), since it's mostly useful to handle the minimal compilation of assets, like CoffeeScript files. Published packages should contain the compiled JS files (or CSS, etc.), not the sources (nor the tests).

Sample Use

This is typically used creating a configure.js script. In this script, let's first create a new build file for Ninja version 1.3, with the build directory build:

ninjaBuildGen = require('ninja-build-gen');
ninja = ninjaBuildGen('1.3', 'build');

Let's add two rules, for example, one to compile CoffeeScript files, the other to compile Stylus files:

ninja.rule('coffee').run('coffee -cs < $in > $out')
     .description("Compile Coffeescript '$in' to '$out'.");
ninja.rule('stylus').run('stylus $in -o $$(dirname $out)')
     .description("Compile Stylus '$in' to '$out'");

Then we can add edges to compile the actual files, for example:

ninja.edge('foo.js').from('foo.coffee').using('coffee');
ninja.edge('bar.js').from('bar.coffee').using('coffee');
ninja.edge('glo.css').from('glo.stylus').using('stylus');
ninja.edge('assets').from(['foo.js', 'bar.js', 'glo.cs']);
ninja.byDefault('assets');

Let's save the file to the standard Ninja filename:

ninja.save('build.ninja');

That's it! Now you can run the configure script, then ninja, to build the project:

$ node configure.js
$ ninja
[1/3] Compile Coffeescript 'foo.coffee' to 'foo.js'.
[2/3] Compile Coffeescript 'bar.coffee' to 'bar.js'.
[3/3] Compile Coffeescript 'glo.styl' to 'glo.css'.
Done.
$ ninja
ninja: nothing to do.

Thanks to Ninja, you get minimal recompilation: only changed file are recompiled upon invocation, as you can see for the second execution above.

Limitations

This package is only here to make easier the creation of Ninja build files, but it does not provide any high-level features, and those are out of scope. That is, no wildcards, no globbing and file lookup; just streamlined Ninja build file generation.

It is recommended to use a globbing library such as glob to create the edges based on existing files. Also, you can generate the output file names by using the globule library. For example:

var files = globule.findMapping('*.coffee', {srcBase: 'src', destBase: 'out',
                                             ext: '.js'});
for (var i = 0; i < files.length; ++i) {
    var match = files[i];
    ninja.edge(match.dest).from(match.src).using('coffee');
}

API

Calls can generally be chained, on <ninja>, <rule> and <edge>. For example: ninja.edge('foo.o').from('foo.c').need('foo.h').using('cc').

ninjaBuildGen([version], [builddir])

Create a <ninja> manifest. version specifies the Ninja version required in the manifest, builddir is the building folder where Ninja will put temporary files. You can refer to it using $builddir in Ninja clauses.

ninjaBuildGen.escape(string)

Escape the string to be suitable in a Ninja file. See the Ninja lexical syntax for more information on escaping. It escapes characters $, :, and spaces. You can use this function to process a list of path when you know you don't need to access variables. Eg:

var paths = ['foo.js', 'bar.js', 'glo.js'];
ninja.edge('concat.js').from(paths.map(ninjaBuildGen.escape)).using('concat');

Otherwise, you need to escape manually. The following statements are equivalent:

ninja.edge('foo$:bar$$glo$ fiz.js');
ninja.edge(ninjaBuildGen.escape('foo:bar$glo fiz.js'));

<ninja>

<ninja>.header(value)

Add an arbitrary header to the file containing value. This is useful to add some comments on top, such as # generated from configure.js. You can't cumulate several headers.

<ninja>.byDefault(name)

Set the default edge to build when Ninja is called without target. There can be only one default edge.

<ninja>.assign(name, value)

Add a global variable assignation in the manifest. The order is important, you shall call this before adding a rule or edge referencing the variable.

<ninja>.rule(name)

Create a <rule>, add it the manifest, and return it. The name of the rule is then used to reference it from the edges.

<ninja>.edge(targets)

Create an <edge>, add it to the manifest, and return it. The targets of the edge is a String or an Array of it specifying the files that will result from the compilation of the edge. Each String is a path, that can be absolute, or relative to the location of the manifest (recommended).

<ninja>.edges

An Array of all the edges added.

<ninja>.rules

An Array of all the rules added.

<ninja>.variables

An Array of all the global variables assigned.

<ninja>.save(path, [callback])

Output the manifest to a file at path. Call callback() once it's done.

<ninja>.saveToStream(stream)

Output the manifest to a Node.js stream.Writable. It does not 'end' it. It can be used, for example, like this:

file = require('fs').createWriteStream('build.ninja');
ninja.saveToStream(file);
file.end();
file.on('finish', function() {console.log('manifest created!')})

<rule>

<rule>.run(command)

Execute the specified command (a String) when the rule is invoked. You can refer to Ninja variables like everywhere else.

<rule>.description(desc)

Provide a description, displayed by Ninja when executing the rule.

<rule>.depfile(file)

Specify a Makefile-compatible dependency file generated by the rule. See the Ninja documentation for more information on those.

<rule>.restat(doRestart)

Enable or not the 'restat' of output files. It's a boolean.

<rule>.generator(isGenerator)

Specifiy if the rule is a 'generator' or not. It's a boolean.

<rule>.write(stream)

Write the rule to a steam. Generally you will want to use <ninja>.save instead.

<edge>

<edge>.using(rule)

Specify the rule (a String) used to build the edge.

<edge>.from(sources)

Specify an Array or a String being the paths of source files for the edge. Those are directly fed to the rule.

<edge>.need(dependencies)

Specify an Array or a String being the paths of dependencies for the edge. Those trigger a recompilation when modified, but are not direct sources for the rule.

<edge>.after(orderDeps)

Specify an Array or a String being the paths of order-only dependencies for the edge.

<edge>.pool(poolName)

Specify a pool for this edges as a String. As you can't creat pools yet this is only really useful for specifying the 'console' pool. See the pool documentation.

<edge>.assign(name, value)

Add a variable assignation local to the edge.

<edge>.write(stream)

Write the rule to a steam. Generally you will want to use <ninja>.save instead.

Contribute

Please, feel free to fork and submit pull requests.