koch.rst

Nim maintenance script

Version:	|nimversion|

Contents

• Introduction
• Commands
  • boot command
  • clean command
  • csource command
  • inno command
  • install command
  • temp command
  • test command
  • update command
  • web command
  • zip command

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 backend. This option is not supported on Windows.

-d:useGnuReadline

Includes the rdstdin module for 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 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 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 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) 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 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.

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.