diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.md | 11 | ||||
| -rw-r--r-- | doc/dblatex.xsl | 7 | ||||
| -rw-r--r-- | doc/docbook.xsl | 22 | ||||
| -rw-r--r-- | doc/manual.asciidoc | 76 | ||||
| -rw-r--r-- | doc/style.css | 6 |
5 files changed, 93 insertions, 29 deletions
diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..6afe5d4 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,11 @@ +This directory contains the Ninja manual and support files used in +building it. Here's a brief overview of how it works. + +The source text, `manual.asciidoc`, is written in the AsciiDoc format. +AsciiDoc can generate HTML but it doesn't look great; instead, we use +AsciiDoc to generate the Docbook XML format and then provide our own +Docbook XSL tweaks to produce HTML from that. + +In theory using AsciiDoc and DocBook allows us to produce nice PDF +documentation etc. In reality it's not clear anyone wants that, but the +build rules are in place to generate it if you install dblatex. diff --git a/doc/dblatex.xsl b/doc/dblatex.xsl new file mode 100644 index 0000000..c0da212 --- /dev/null +++ b/doc/dblatex.xsl @@ -0,0 +1,7 @@ +<!-- This custom XSL tweaks the dblatex XML settings. --> +<xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'> + <!-- These parameters disable the list of collaborators and revisions. + Together remove a useless page from the front matter. --> + <xsl:param name='doc.collab.show'>0</xsl:param> + <xsl:param name='latex.output.revhistory'>0</xsl:param> +</xsl:stylesheet> diff --git a/doc/docbook.xsl b/doc/docbook.xsl index 8afdc8c..19cc126 100644 --- a/doc/docbook.xsl +++ b/doc/docbook.xsl @@ -1,15 +1,29 @@ -<!-- This soup of XML is the minimum customization necessary to make the - autogenerated manual look ok. --> +<!-- This custom XSL tweaks the DocBook XML -> HTML settings to produce + an OK-looking manual. --> <!DOCTYPE xsl:stylesheet [ <!ENTITY css SYSTEM "style.css"> ]> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'> <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/> + + <!-- Embed our stylesheet as the user-provided <head> content. --> <xsl:template name="user.head.content"><style>&css;</style></xsl:template> + + <!-- Remove the body.attributes block, which specifies a bunch of + useless bgcolor etc. attrs on the <body> tag. --> <xsl:template name="body.attributes"></xsl:template> - <xsl:param name="generate.toc" select="'book toc'"/> - <xsl:param name="chapter.autolabel" select="0" /> + + <!-- Specify that in "book" form (which we're using), we only want a + single table of contents at the beginning of the document. --> + <xsl:param name="generate.toc">book toc</xsl:param> + + <!-- Don't put the "Chapter 1." prefix on the "chapters". --> + <xsl:param name="chapter.autolabel">0</xsl:param> + + <!-- Use <ul> for the table of contents. By default DocBook uses a + <dl>, which makes no semantic sense. I imagine they just did + it because it looks nice? --> <xsl:param name="toc.list.type">ul</xsl:param> <xsl:output method="html" encoding="utf-8" indent="no" diff --git a/doc/manual.asciidoc b/doc/manual.asciidoc index 3c193f1..0d842f9 100644 --- a/doc/manual.asciidoc +++ b/doc/manual.asciidoc @@ -1,5 +1,5 @@ -Ninja -===== +The Ninja build system +====================== Introduction @@ -158,17 +158,13 @@ http://code.google.com/p/gyp/[gyp]:: The meta-build system used to generate build files for Google Chrome and related projects (v8, node.js). gyp can generate Ninja files for all platforms supported by Chrome. See the -http://code.google.com/p/chromium/wiki/NinjaBuild[Chromium Ninja -documentation for more details]. +https://chromium.googlesource.com/chromium/src/+/master/docs/ninja_build.md[Chromium Ninja documentation for more details]. -http://www.cmake.org/[CMake]:: A widely used meta-build system that -can generate Ninja files on Linux as of CMake version 2.8.8. (There -is some Mac and Windows support -- http://www.reactos.org[ReactOS] -uses Ninja on Windows for their buildbots, but those platforms are not -yet officially supported by CMake as the full test suite doesn't -pass.) +https://cmake.org/[CMake]:: A widely used meta-build system that +can generate Ninja files on Linux as of CMake version 2.8.8. Newer versions +of CMake support generating Ninja files on Windows and Mac OS X too. -others:: Ninja ought to fit perfectly into other meta-build software +https://github.com/ninja-build/ninja/wiki/List-of-generators-producing-ninja-build-files[others]:: Ninja ought to fit perfectly into other meta-build software like http://industriousone.com/premake[premake]. If you do this work, please let us know! @@ -689,6 +685,10 @@ A file is a series of declarations. A declaration can be one of: Order-only dependencies may be tacked on the end with +|| _dependency1_ _dependency2_+. (See <<ref_dependencies,the reference on dependency types>>.) ++ +Implicit outputs _(available since Ninja 1.7)_ may be added before +the `:` with +| _output1_ _output2_+ and do not appear in `$out`. +(See <<ref_outputs,the reference on output types>>.) 3. Variable declarations, which look like +_variable_ = _value_+. @@ -717,7 +717,6 @@ spaces within a token must be escaped. There is only one escape character, `$`, and it has the following behaviors: -[horizontal] `$` followed by a newline:: escape the newline (continue the current line across a line break). @@ -782,11 +781,9 @@ A `rule` block contains a list of `key = value` declarations that affect the processing of the rule. Here is a full list of special keys. -`command` (_required_):: the command line to run. This string (after - $variables are expanded) is passed directly to `sh -c` without - interpretation by Ninja. Each `rule` may have only one `command` - declaration. To specify multiple commands use `&&` (or similar) to - concatenate operations. +`command` (_required_):: the command line to run. Each `rule` may + have only one `command` declaration. See <<ref_rule_command,the next + section>> for more details on quoting and executing multiple commands. `depfile`:: path to an optional `Makefile` that contains extra _implicit dependencies_ (see <<ref_dependencies,the reference on @@ -854,6 +851,48 @@ rule link build myapp.exe: link a.obj b.obj [possibly many other .obj files] ---- +[[ref_rule_command]] +Interpretation of the `command` variable +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Fundamentally, command lines behave differently on Unixes and Windows. + +On Unixes, commands are arrays of arguments. The Ninja `command` +variable is passed directly to `sh -c`, which is then responsible for +interpreting that string into an argv array. Therefore the quoting +rules are those of the shell, and you can use all the normal shell +operators, like `&&` to chain multiple commands, or `VAR=value cmd` to +set environment variables. + +On Windows, commands are strings, so Ninja passes the `command` string +directly to `CreateProcess`. (In the common case of simply executing +a compiler this means there is less overhead.) Consequently the +quoting rules are deterimined by the called program, which on Windows +are usually provided by the C library. If you need shell +interpretation of the command (such as the use of `&&` to chain +multiple commands), make the command execute the Windows shell by +prefixing the command with `cmd /c`. + +[[ref_outputs]] +Build outputs +~~~~~~~~~~~~~ + +There are two types of build outputs which are subtly different. + +1. _Explicit outputs_, as listed in a build line. These are + available as the `$out` variable in the rule. ++ +This is the standard form of output to be used for e.g. the +object file of a compile command. + +2. _Implicit outputs_, as listed in a build line with the syntax +| + _out1_ _out2_+ + before the `:` of a build line _(available since + Ninja 1.7)_. The semantics are identical to explicit outputs, + the only difference is that implicit outputs don't show up in the + `$out` variable. ++ +This is for expressing outputs that don't show up on the +command line of the command. + [[ref_dependencies]] Build dependencies ~~~~~~~~~~~~~~~~~~ @@ -865,7 +904,7 @@ There are three types of build dependencies which are subtly different. cause the output to be rebuilt; if these file are missing and Ninja doesn't know how to build them, the build is aborted. + -This is the standard form of dependency to be used for e.g. the +This is the standard form of dependency to be used e.g. for the source file of a compile command. 2. _Implicit dependencies_, either as picked up from @@ -954,4 +993,3 @@ Variable declarations indented in a `build` block are scoped to the 5. Variables from the file that included that file using the `subninja` keyword. - diff --git a/doc/style.css b/doc/style.css index 5d14a1c..9976c03 100644 --- a/doc/style.css +++ b/doc/style.css @@ -24,12 +24,6 @@ div.chapter { margin-top: 4em; border-top: solid 2px black; } -.section .title { - font-size: 1.3em; -} -.section .section .title { - font-size: 1.2em; -} p { margin-top: 0; } |