diff options
Diffstat (limited to 'doc/nimrodc.txt')
| -rwxr-xr-x | doc/nimrodc.txt | 298 |
1 files changed, 0 insertions, 298 deletions
diff --git a/doc/nimrodc.txt b/doc/nimrodc.txt deleted file mode 100755 index 0a0781e36..000000000 --- a/doc/nimrodc.txt +++ /dev/null @@ -1,298 +0,0 @@ -=================================== - 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. - - -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*", 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. |