diff options
Diffstat (limited to 'doc/koch.rst')
| -rw-r--r-- | doc/koch.rst | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/doc/koch.rst b/doc/koch.rst new file mode 100644 index 000000000..a58d386ea --- /dev/null +++ b/doc/koch.rst @@ -0,0 +1,151 @@ +=============================== + Nim maintenance script +=============================== + +:Version: |nimversion| + +.. 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 Nim'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 +Nim 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 <nimc.html#nim-interactive-mode>`_ (aka ``nim 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 Nim without compiler as a service (CAAS) support. CAAS + support is required for functionality like Nim's `idetool + <idetools.html>`_ command used to integrate the compiler with + `external IDEs <https://github.com/Araq/Nim/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 Nim 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 + Nim code can use the `foreign function interface (FFI) + <manual.html#foreign-function-interface>`_ at runtime, but macros + are limited to pure Nim code at compilation time. Enabling + this switch will allow macros to execute non-nim code at + compilation time (eg. open a file and write to it). +--gc:refc|v2|markAndSweep|boehm|go|none + Selects which garbage collection strategy to use for the compiler + and generated code. See the `Nim's Garbage Collector <gc.html>`_ + documentation for more information. + +After compilation is finished you will hopefully end up with the nim +compiler in the ``bin`` directory. You can add Nim'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 Nim 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 Nim compiler but with a different final name +(``nim_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 Nim'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 nim 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://nim-lang.org. + +By default the documentation will be built in parallel using the number of +available CPU cores. If any documentation build sub commands fail, they will +be rerun in serial fashion so that meaninful error output can be gathered for +inspection. The ``--parallelBuild:n`` switch or configuration option can be +used to force a specific number of parallel jobs or run everything serially +from the start (``n == 1``). + +zip command +----------- + +The `zip`:idx: command builds the installation ZIP package. |