Merge pull request #1237 from Varriount/gradha-pr_documents_koch

Gradha pr documents koch

7 files changed, 166 insertions, 7 deletions

diff --git a/doc/intern.txt b/doc/intern.txt
index ec6db8709..1dcf27774 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..032151808
--- /dev/null
+++ b/doc/koch.txt
@@ -0,0 +1,144 @@
+===============================
+   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 \{\} \;
+-d:useFFI
+  Nimrod code can use the `foreign function interface (FFI)
+  <manual.html#foreign-function-interface>`_ at runtime, but macros
+  are limited to pure Nimrod code at compilation time.  Enabling
+  this switch will allow macros to execute non-nimrod code at
+  compilation time (eg. open a file and write to it).
+--gc:refc|v2|markAndSweep|boehm|none
+  Selects which garbage collection strategy to use for the compiler
+  and generated code. See the `Nimrod's Garbage Collector <gc.html>`_
+  documentation for more information.
+
+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.
diff --git a/koch.nim b/koch.nim
index 4d0ac0254..15ee3732d 100644
--- a/koch.nim
+++ b/koch.nim
@@ -6,6 +6,8 @@
 #    See the file "copying.txt", included in this
 #    distribution, for details about the copyright.
 #
+#    See doc/koch.txt for documentation.
+#
 
 when defined(gcc) and defined(windows):
   when defined(x86):
diff --git a/lib/wrappers/readline/readline.nim b/lib/wrappers/readline/readline.nim
index 1f0dd564f..bbe416534 100644
--- a/lib/wrappers/readline/readline.nim
+++ b/lib/wrappers/readline/readline.nim
@@ -29,8 +29,8 @@ elif defined(macosx):
 else: 
   const 
     readlineDll* = "libreadline.so.6(|.0)"
-##  mangle "'TCommandFunc'" TCommandFunc
-##  mangle TvcpFunc TvcpFunc
+#  mangle "'TCommandFunc'" TCommandFunc
+#  mangle TvcpFunc TvcpFunc
 
 import rltypedefs
 
diff --git a/readme.md b/readme.md
index 38e04233f..e8c081d4e 100644
--- a/readme.md
+++ b/readme.md
@@ -39,8 +39,9 @@ $ bin/nimrod c koch
 $ ./koch boot -d:release
 ```
 
-``koch install [dir]`` may then be used to install Nimrod, or you
-can simply add it to your PATH.
+``koch install [dir]`` may then be used to install Nimrod, or you can simply
+add it to your PATH. More ``koch`` related options are documented in
+[doc/koch.txt](doc/koch.txt).
 
 The above steps can be performed on Windows in a similar fashion, the
 ``build.bat`` and ``build64.bat`` (for x86_64 systems) are provided to be used
diff --git a/readme.txt b/readme.txt
index 3eaef0b35..3f6aef05c 100644
--- a/readme.txt
+++ b/readme.txt
@@ -39,8 +39,9 @@ $ bin/nimrod c koch
 $ ./koch boot -d:release
 ```
 
-``koch install [dir]`` may then be used to install Nimrod, or you
-can simply add it to your PATH.
+``koch install [dir]`` may then be used to install Nimrod, or you can simply
+add it to your PATH. More ``koch`` related options are documented in
+[doc/koch.txt](doc/koch.txt).
 
 The above steps can be performed on Windows in a similar fashion, the
 ``build.bat`` and ``build64.bat`` (for x86_64 systems) are provided to be used
diff --git a/web/nimrod.ini b/web/nimrod.ini
index 14701ecea..ed8236c3e 100644
--- a/web/nimrod.ini
+++ b/web/nimrod.ini
@@ -37,7 +37,7 @@ UNIX. We don't believe this to be a coincidence. - Jeremy S. Anderson."""
 
 [Documentation]
 doc: "endb;intern;apis;lib;manual;tut1;tut2;nimrodc;overview;filters;trmacros"
-doc: "tools;c2nim;niminst;nimgrep;gc;estp;idetools;docgen"
+doc: "tools;c2nim;niminst;nimgrep;gc;estp;idetools;docgen;koch"
 pdf: "manual;lib;tut1;tut2;nimrodc;c2nim;niminst;gc"
 srcdoc2: "system.nim;impure/graphics;wrappers/sdl"
 srcdoc2: "core/macros;pure/marshal;core/typeinfo;core/unsigned"
@@ -64,6 +64,15 @@ srcdoc2: "pure/nimprof;pure/unittest;packages/docutils/highlite"
 srcdoc2: "packages/docutils/rst;packages/docutils/rstast"
 srcdoc2: "packages/docutils/rstgen;pure/logging;pure/asyncdispatch;pure/asyncnet"
 srcdoc2: "pure/rawsockets;pure/asynchttpserver;pure/net;pure/selectors;pure/future"
+srcdoc2: "wrappers/expat;wrappers/readline/history"
+srcdoc2: "wrappers/libsvm.nim;wrappers/libuv"
+srcdoc2: "wrappers/zip/zlib;wrappers/zip/libzip"
+srcdoc2: "wrappers/libcurl;pure/md5;wrappers/mysql;wrappers/iup"
+srcdoc2: "posix/posix;wrappers/odbcsql"
+srcdoc2: "wrappers/tre;wrappers/openssl;wrappers/pcre"
+srcdoc2: "wrappers/sqlite3;wrappers/postgres;wrappers/tinyc"
+srcdoc2: "wrappers/readline/readline;wrappers/readline/rltypedefs"
+srcdoc2: "wrappers/joyent_http_parser"
 
 webdoc: "wrappers/libcurl;pure/md5;wrappers/mysql;wrappers/iup"
 webdoc: "wrappers/sqlite3;wrappers/postgres;wrappers/tinyc"