=================================== Nimrod Compiler User Guide =================================== :Author: Andreas Rumpf :Version: |nimrodversion| .. contents:: "Look at you, hacker. A pathetic creature of meat and bone, panting and sweating as you run through my corridors. How can you challenge a perfect, immortal machine?" Introduction ============ This document describes the usage of the *Nimrod compiler* on the different supported platforms. It is not a definition of the Nimrod programming language (therefore is the `manual `_). Nimrod is free software; it is licensed under the `GNU General Public License `_. Compiler Usage ============== Command line switches --------------------- Basis command line switches are: .. include:: ../data/basicopt.txt Advanced command line switches are: .. include:: ../data/advopt.txt Configuration file ------------------ The default configuration file is ``nimrod.cfg``. The ``nimrod`` executable looks for it in the following directories (in this order): 1. ``/home/$user/.config/nimrod.cfg`` (UNIX) or ``%APPDATA%/nimrod.cfg`` (Windows) 2. ``$nimrod/config/nimrod.cfg`` (UNIX), ``%NIMROD%/config/nimrod.cfg`` (Windows) 3. ``/etc/nimrod.cfg`` (UNIX) The search stops as soon as a configuration file has been found. The reading of ``nimrod.cfg`` can be suppressed by the ``--skipCfg`` command line option. **Note:** The *project file name* is the name of the ``.nim`` file that is passed as a command line argument to the compiler. Configuration settings can be overwritten individually in a project specific configuration file that is read automatically. This specific file has to be in the same directory as the project and be of the same name, except that its extension should be ``.cfg``. Command line settings have priority over configuration file settings. Generated C code directory -------------------------- The generated files that Nimrod produces all go into a subdirectory called ``nimcache`` in your project directory. This makes it easy to delete all generated files. However, the generated C code is not platform independent. C code generated for Linux does not compile on Windows, for instance. The comment on top of the C file lists the OS, CPU and CC the file has been compiled for. DLL generation ============== Nimrod supports the generation of DLLs. However, there must be only one instance of the GC per process/address space. This instance is contained in ``nimrtl.dll``. This means that every generated Nimrod DLL depends on ``nimrtl.dll``. To generate the "nimrtl.dll" file, use the command:: nimrod c -d:release lib/nimrtl.nim To link against ``nimrtl.dll`` use the command:: nimrod c -d:useNimRtl myprog.nim Additional Features =================== This section describes Nimrod's additional features that are not listed in the Nimrod manual. Some of the features here only make sense for the C code generator and are subject to change. NoDecl pragma ------------- The `noDecl`:idx: pragma can be applied to almost any symbol (variable, proc, type, etc.) and is sometimes useful for interoperability with C: It tells Nimrod that it should not generate a declaration for the symbol in the C code. For example: .. code-block:: Nimrod var EACCES {.importc, noDecl.}: cint # pretend EACCES was a variable, as # Nimrod does not know its value However, the ``header`` pragma is often the better alternative. **Note**: This will not work for the LLVM backend. Header pragma ------------- The `header`:idx: pragma is very similar to the ``noDecl`` pragma: It can be applied to almost any symbol and specifies that it should not be declared and instead the generated code should contain an ``#include``: .. code-block:: Nimrod type PFile {.importc: "FILE*",