diff options
Diffstat (limited to 'README.markdown')
| -rw-r--r-- | README.markdown | 80 |
1 files changed, 46 insertions, 34 deletions
diff --git a/README.markdown b/README.markdown index c7ef8dd..abe0ceb 100644 --- a/README.markdown +++ b/README.markdown @@ -12,25 +12,31 @@ seconds to rebuild after changing one file, even on a fast computer. Here are some of the design goals of Ninja: -* incredibly fast (i.e., instant) builds, even for very large projects -* very little implicit policy; "explicit is better than implicit" -* get dependencies correct, including situations that are difficult +* incredibly fast (i.e., instant) builds, even for very large projects. +* very little implicit policy; "explicit is better than implicit". +* get dependencies correct, in particular situations that are difficult to get right with Makefiles (e.g. outputs have an implicit dependency on - the command line used to generate them; supporting gcc's `-M` flags - for header dependencies) -* when convenience and speed are in conflict, prefer speed -* provide good tools for getting insight into your build speed + the command line used to generate them; using gcc's `-M` flags + for header dependencies). +* when convenience and speed are in conflict, prefer speed. +* provide tools for getting insight into your build speed. -Some explicit non-goals: +Some explicit *non-goals*: * being convenient to write build files by hand. *You should generate your ninja files via some other mechanism*. +* providing much policy about how builds work. * being competitive in terms of user-friendliness with any of the many - fine build systems that exist -* forcing your project into any particular directory layout -* providing a lot of build-time customization of the build; instead, - you should provide customization in the system that generates your - `.ninja` files, like how autoconf provides `./configure`. + fine build systems that exist. +* forcing your project into any particular directory layout. +* providing a lot of build-time customization of the build. + +Ninja has no built-in behavior describing how to build C source, or +build libraries, or install binaries. You decide this policy when you +create your `.ninja` files. Customization and configuration are out +of scope, instead you should provide customization in the system that +generates your `.ninja` files, like how autoconf provides +`./configure`. ## Getting Started The included `bootstrap.sh` should hopefully produce a working `ninja` @@ -44,42 +50,40 @@ where `target` is a known output described by `build.ninja` in the current directory. ## Creating .ninja files - A build file (default name: `build.ninja`) provides a list of *rules* along with a list of *build* statements saying how to build files -using the rules. +using the rules. The only other syntax is a way of declaring +(immutable) variables. Conceptually, `build` statements describe the dependency graph of your project, while `rule` statements describe how to generate the files -within a given edge of the graph. - -### Rules +along a given edge of the graph. -Rules begin with the `rule` keyword and a name for the rule, followed -by an indented set of `key = val` lines. Here's an example of a -simple rule for compiling C code. +Here's a basic `.ninja` file that demonstrates most of the syntax. rule cc command = gcc -c $in -o $out + build foo.o: cc foo.c + +### Rules +Rules begin with the `rule` keyword and a name for the rule, followed +by an indented set of `key = val` lines. The `command` key is special, +as it defines the command to run. (A full list of special keys is +provided in the reference.) This declares a new rule named `cc`, along with the command to run. -`Variables` begin with a `$` and are described more fully later, but +Variables begin with a `$` and are described more fully later, but here `$in` expands to the list of input files and `$out` to the output file for this command. ### Build statements -Continuing the example, here's how we might declare a particular -file is built with the `cc` rule. - - build foo.o: cc foo.c - -This declares that `foo.o` should be rebuilt when `foo.c` changes, and -that the `cc` rule should be used to do it. A `build` statement -supports multiple outputs (before the colon) and multiple inputs -(after the rule name). +Build statements begin with the `build` keyword, followed by a list of +output files, followed by a colon, followed by a rule name, followed +by a list of input files. Such a declaration says that all of the +output files should be generated from the input files when the inputs +change. ### Variables - Despite the non-goal of being convenient to write by hand, to keep build files readable (debuggable), Ninja supports declaring bindings (variables). A declaration like the following @@ -103,10 +107,18 @@ A file is a series of declarations. A declaration can be one of: 2. A build edge, which looks like `build output: rule input`. 3. Variable declarations, which look like `variable = value`. +Newlines are significant, but they can be escaped by putting a `\\` +before them. + +Whitespace is only significant if it's at the beginning of a line. If +a line is intended more than the previous one, it's considered part of +its parent's scope; if it is indented less than the previous one, it +closes the previous scope. + ### Rule Declarations +XXX List special keys here. ### Special variables - `builddir` is a directory for intermediate build output. (The name comes from autoconf.) It is special in that it gets a shorter alias: `@`. You must still be explicit in your rules. In the following @@ -118,4 +130,4 @@ subdirectory. ### Evaluation and scoping -talk about where variables live, nested scopes etc +XXX talk about where variables live, nested scopes etc |