Nim/doc/nimrodc.txt

===================================
   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 <manual.html>`_).

Nimrod is free software; it is licensed under the
`GNU General Public License <gpl.html>`_.


Compiler Usage
==============

Command line switches
---------------------
Basis command line switches are:

.. include:: basicopt.txt

Advanced command line switches are:

.. include:: 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.


Cross compilation
=================

To `cross compile`:idx:, use for example::

  nimrod c --cpu:i386 --os:linux --compile_only --gen_script myproject.nim

Then move the C code and the compile script ``compile_myproject.sh`` to your 
Linux i386 machine and run the script.


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`:idx: 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*", header: "<stdio.h>".} = distinct pointer
      # import C's FILE* type; Nimrod will treat it as a new pointer type

The ``header`` pragma always expects a string constant. The string contant
contains the header file: As usual for C, a system header file is enclosed
in angle brackets: ``<>``. If no angle brackets are given, Nimrod
encloses the header file in ``""`` in the generated C code.

**Note**: This will not work for the LLVM backend.


Compile pragma
--------------
The `compile`:idx: pragma can be used to compile and link a C/C++ source file 
with the project: 

.. code-block:: Nimrod
  {.compile: "myfile.cpp".}

**Note**: Nimrod computes a CRC checksum and only recompiles the file if it 
has changed. You can use the ``-f`` command line option to force recompilation
of the file.


Link pragma
-----------
The `link`:idx: pragma can be used to link an additional file with the project: 

.. code-block:: Nimrod
  {.link: "myfile.o".}


Emit pragma
-----------
The `emit`:idx: pragma can be used to directly affect the output of the 
compiler's code generator. So it makes your code unportable to other code
generators/backends. Its usage is highly discouraged! However, it can be
extremely useful for interfacing with C++ or Objective C code.

Example:

.. code-block:: Nimrod
  {.emit: """
  static int cvariable = 420;
  """.}

  proc embedsC() {.pure.} = 
    var nimrodVar = 89
    # use backticks to access Nimrod symbols within an emit section:
    {.emit: """fprintf(stdout, "%d\n", cvariable + (int)`nimrodVar`);""".}

  embedsC()


LineDir option
--------------
The `lineDir`:idx: option can be turned on or off. If turned on the
generated C code contains ``#line`` directives. This may be helpful for
debugging with GDB.


StackTrace option
-----------------
If the `stackTrace`:idx: option is turned on, the generated C contains code to
ensure that proper stack traces are given if the program crashes or an
uncaught exception is raised.


LineTrace option
----------------
The `lineTrace`:idx: option implies the ``stackTrace`` option. If turned on,
the generated C contains code to ensure that proper stack traces with line
number information are given if the program crashes or an uncaught exception
is raised.

Debugger option
---------------
The `debugger`:idx: option enables or disables the *Embedded Nimrod Debugger*.
See the documentation of endb_ for further information.


Breakpoint pragma
-----------------
The *breakpoint* pragma was specially added for the sake of debugging with
ENDB. See the documentation of `endb <endb.html>`_ for further information.


Volatile pragma
---------------
The `volatile`:idx: pragma is for variables only. It declares the variable as
``volatile``, whatever that means in C/C++.

**Note**: This pragma will not exist for the LLVM backend.


Debugging with Nimrod
=====================

Nimrod comes with its own *Embedded Nimrod Debugger*. See
the documentation of endb_ for further information.


Optimizing for Nimrod
=====================

Nimrod has no separate optimizer, but the C code that is produced is very
efficient. Most C compilers have excellent optimizers, so usually it is
not needed to optimize one's code. Nimrod has been designed to encourage
efficient code: The most readable code in Nimrod is often the most efficient
too.

However, sometimes one has to optimize. Do it in the following order:

1. switch off the embedded debugger (it is **slow**!)
2. turn on the optimizer and turn off runtime checks
3. profile your code to find where the bottlenecks are
4. try to find a better algorithm
5. do low-level optimizations

This section can only help you with the last item.


Optimizing string handling
--------------------------

String assignments are sometimes expensive in Nimrod: They are required to
copy the whole string. However, the compiler is often smart enough to not copy
strings. Due to the argument passing semantics, strings are never copied when
passed to subroutines. The compiler does not copy strings that are a result from
a procedure call, because the callee returns a new string anyway.
Thus it is efficient to do:

.. code-block:: Nimrod
  var s = procA() # assignment will not copy the string; procA allocates a new
                  # string already

However it is not efficient to do:

.. code-block:: Nimrod
  var s = varA    # assignment has to copy the whole string into a new buffer!

..
  String case statements are optimized too. A hashing scheme is used for them
  if several different string constants are used. This is likely to be more
  efficient than any hand-coded scheme.


..
  The ECMAScript code generator
  =============================

  Note: As of version 0.7.0 the ECMAScript code generator is not maintained any
  longer. Help if you are interested.

  Note: I use the term `ECMAScript`:idx: here instead of `JavaScript`:idx:,
  since it is the proper term.

  The ECMAScript code generator is experimental!

  Nimrod targets ECMAScript 1.5 which is supported by any widely used browser.
  Since ECMAScript does not have a portable means to include another module,
  Nimrod just generates a long ``.js`` file.

  Features or modules that the ECMAScript platform does not support are not
  available. This includes:

  * manual memory management (``alloc``, etc.)
  * casting and other unsafe operations (``cast`` operator, ``zeroMem``, etc.)
  * file management
  * most modules of the Standard library
  * proper 64 bit integer arithmetic
  * proper unsigned integer arithmetic

  However, the modules `strutils`:idx:, `math`:idx:, and `times`:idx: are
  available! To access the DOM, use the `dom`:idx: module that is only
  available for the ECMAScript platform.