diff options
Diffstat (limited to 'doc/koch.rst')
| -rw-r--r-- | doc/koch.rst | 151 |
1 files changed, 0 insertions, 151 deletions
diff --git a/doc/koch.rst b/doc/koch.rst deleted file mode 100644 index a58d386ea..000000000 --- a/doc/koch.rst +++ /dev/null @@ -1,151 +0,0 @@ -=============================== - 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. |