diff --git a/doc/intern.txt b/doc/intern.txt index c602e49337..a8466160c5 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 `_ +documentation. Coding Guidelines diff --git a/doc/koch.txt b/doc/koch.txt new file mode 100644 index 0000000000..11d0fa33fb --- /dev/null +++ b/doc/koch.txt @@ -0,0 +1,134 @@ +=============================== + Nimrod maintenance script +=============================== + +:Version: |nimrodversion| + +.. contents:: + +.. raw:: html +

+ "A great chef is an artist that I truly respect" -- Robert Stack. +

+ + +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 `_ backend. This + option is not supported on Windows. +-d:useGnuReadline + Includes the `rdstdin module `_ for `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 + `_ command used to integrate the compiler with + `external IDEs `_. +-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 + `_ + 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 +`_. + +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 9d59344f2b..054db4f8f6 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/readme.md b/readme.md index 38e04233fc..e8c081d4ed 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 3eaef0b355..3f6aef05cd 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 b29bcff309..3a05bad3d5 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"