Adds documentation about koch.

2 files changed, 136 insertions, 0 deletions

diff --git a/doc/intern.txt b/doc/intern.txt
index c602e4933..a8466160c 100644
--- a/doc/intern.txt
+++ b/doc/intern.txt
@@ -59,6 +59,8 @@ And for a debug version compatible with GDB::
 
 The ``koch`` program is Nimrod's maintenance script. It is a replacement for
 make and shell scripting with the advantage that it is much more portable.
+More information about its options can be found in the `koch <koch.html>`_
+documentation.
 
 
 Coding Guidelines
diff --git a/doc/koch.txt b/doc/koch.txt
new file mode 100644
index 000000000..11d0fa33f
--- /dev/null
+++ b/doc/koch.txt
@@ -0,0 +1,134 @@
+===============================
+   Nimrod maintenance script
+===============================
+
+:Version: |nimrodversion|
+
+.. contents::
+
+.. raw:: html
+  <blockquote><p>
+  "A great chef is an artist that I truly respect" -- Robert Stack.
+  </p></blockquote>
+
+
+Introduction
+============
+
+The `koch`:idx: program is Nimrod's maintenance script. It is a replacement
+for make and shell scripting with the advantage that it is much more portable.
+The word *koch* means *cook* in German. ``koch`` is used mainly to build the
+Nimrod compiler, but it can also be used for other tasks. This document
+describes the supported commands and their options.
+
+
+Commands
+========
+
+boot command
+------------
+
+The `boot`:idx: command bootstraps the compiler, and it accepts different
+options:
+
+-d:release
+  By default a debug version is created, passing this option will
+  force a release build, which is much faster and should be preferred
+  unless you are debugging the compiler.
+-d:tinyc
+  Include the `Tiny C <http://bellard.org/tcc/>`_ backend. This
+  option is not supported on Windows.
+-d:useGnuReadline
+  Includes the `rdstdin module <rdstdin.html>`_ for `interactive
+  mode <nimrodc.html#nimrod-interactive-mode>`_ (aka ``nimrod i``).
+  This is not needed on Windows. On other platforms this may
+  incorporate the GNU readline library.
+-d:nativeStacktrace
+  Use native stack traces (only for Mac OS X or Linux).
+-d:noCaas
+  Builds Nimrod without compiler as a service (CAAS) support. CAAS
+  support is required for functionality like Nimrod's `idetool
+  <idetools.html>`_ command used to integrate the compiler with
+  `external IDEs <https://github.com/Araq/Nimrod/wiki/Editor-Support>`_.
+-d:avoidTimeMachine
+  Only for Mac OS X, activating this switch will force excluding
+  the generated ``nimcache`` directories from Time Machine backups.
+  By default ``nimcache`` directories will be included in backups,
+  and just for the Nimrod compiler itself it means backing up 20MB
+  of generated files each time you update the compiler. Using this
+  option will make the compiler invoke the `tmutil
+  <https://developer.apple.com/library/mac/documentation/Darwin/Reference/Manpages/man8/tmutil.8.html>`_
+  command on all ``nimcache`` directories, setting their backup
+  exclusion bit.
+
+  You can use the following command to locate all ``nimcache``
+  directories and check their backup exclusion bit::
+
+    $ find . -type d -name nimcache -exec tmutil isexcluded \{\} \;
+
+After compilation is finished you will hopefully end up with the nimrod
+compiler in the ``bin`` directory. You can add Nimrod's ``bin`` directory to
+your ``$PATH`` or use the `install command`_ to place it where it will be
+found.
+
+clean command
+-------------
+
+The `clean`:idx: command removes all generated files.
+
+csource command
+---------------
+
+The `csource`:idx: command builds the C sources for installation. It accepts
+the same options as you would pass to the `boot command`_.
+
+inno command
+------------
+
+The `inno`:idx: command builds the `Inno Setup installer for Windows
+<http://www.jrsoftware.org/isinfo.php>`_.
+
+install command
+---------------
+
+The `install`:idx: command installs Nimrod to the specified directory, which
+is required as a parameter. For example, on Unix platforms you could run::
+
+  $ ./koch install /usr/local/bin
+
+temp command
+------------
+
+The temp command builds the Nimrod compiler but with a different final name
+(``nimrod_temp``), so it doesn't overwrite your normal compiler. You can use
+this command to test different options, the same you would issue for the `boot
+command`_.
+
+test command
+------------
+
+The `test`:idx: command can also be invoked with the alias ``tests``. This
+command will compile and run ``tests/testament/tester.nim``, which is the main
+driver of Nimrod's test suite. You can pass options to the ``test`` command,
+they will be forwarded to the tester. See its source code for available
+options.
+
+update command
+--------------
+
+The `update`:idx: command updates nimrod to the latest version from github.
+For this command to work you need to have compiled ``koch`` itself with the
+``-d:withUpdate`` switch.
+
+web command
+-----------
+
+The `web`:idx: command converts the documentation in the ``doc`` directory
+from rst to HTML. It also repeats the same operation but places the result in
+the ``web/upload`` which can be used to update the website at
+http://nimrod-lang.org.
+
+zip command
+-----------
+
+The `zip`:idx: command builds the installation ZIP package.