diff options
| -rw-r--r-- | doc/advopt.txt | 7 | ||||
| -rw-r--r-- | doc/backends.txt | 113 | ||||
| -rw-r--r-- | doc/nimrodc.txt | 46 | ||||
| -rw-r--r-- | web/nimrod.ini | 2 |
4 files changed, 130 insertions, 38 deletions
diff --git a/doc/advopt.txt b/doc/advopt.txt index f5ff90791..e3a62c31b 100644 --- a/doc/advopt.txt +++ b/doc/advopt.txt @@ -1,7 +1,8 @@ Advanced commands: - //compileToC, cc compile project with C code generator - //compileToCpp, cpp compile project to C++ code - //compileToOC, objc compile project to Objective C code + //compileToC, cc compile project with C code generator, see `Backend language options`_ + //compileToCpp, cpp compile project to C++ code, see `Backend language options`_ + //compileToOC, objc compile project to Objective C code, see `Backend language options`_ + //js compile project to Javascript, see `Backend language options`_ //rst2html convert a reStructuredText file to HTML //rst2tex convert a reStructuredText file to TeX //jsondoc extract the documentation to a json file diff --git a/doc/backends.txt b/doc/backends.txt new file mode 100644 index 000000000..2d7075323 --- /dev/null +++ b/doc/backends.txt @@ -0,0 +1,113 @@ +================================ + Nimrod Backend Integration +================================ + +:Author: Puppet Master +:Version: |nimrodversion| + +.. contents:: + + "If we all reacted the same way, we'd be predictable, and there's + always more than one way to view a situation. What's true for the + group is also true for the individual. It's simple: overspecialize, + and you breed in weakness. It's slow death." -- Major Motoko + Kusanagi + + +Introduction +============ + +The `Nimrod Compiler User Guide <nimrodc.html>`_ documents the typical +compiler usage, using the ``compile`` or ``c`` command to transform a ``.nim`` +file into one or more ``.c`` files which are then compiled with the platform's +C compiler into a static binary. However there are other commands to compile +to C++, Objective-C or JavaScript. This document tries to concentrate in a +single place all the backend and interfacing options. + +The Nimrod compiler supports mainly two backends: the C (and derivate) and +the JavaScript targets. The C target creates source files which can be +compiled into a library or a final executable. The JavaScript target generates +a ``.js`` file which you call from an HTML file. + + +Backends +======== + +The C like targets +------------------ + +The commands to compile to either C, C++ or Objective-C are: + + //compileToC, cc compile project with C code generator + //compileToCpp, cpp compile project to C++ code + //compileToOC, objc compile project to Objective C code + +The most significant difference between these commands is that if you look +into the ``nimcache`` directory you will find ``.c``, ``.cpp`` or ``.m`` +files, other than that all of them will produce a native binary for your +project. This allows you to take the generated code and place it directly +into a project using any of these languages. Here are some typical command +line invocations:: + + $ nimrod c hallo.nim + $ nimrod cpp hallo.nim + $ nimrod objc hallo.nim + +The compiler commands select the backend but if you need to specify more +carefully the backend compiler… + + +The JavaScript target +--------------------- + +Nimrod can also generate `JavaScript`:idx: code through the ``js`` command. +However, the JavaScript code generator is experimental! + +Nimrod targets JavaScript 1.5 which is supported by any widely used browser. +Since JavaScript does not have a portable means to include another module, +Nimrod just generates a long ``.js`` file. + +Features or modules that the JavaScript 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 +* unsigned integer arithmetic + +However, the modules `strutils <strutils.html>`_, `math <math.html>`_, and +`times <times.html>`_ are available! To access the DOM, use the `dom +<dom.html>`_ module that is only available for the JavaScript platform. + +To compile a Nimrod module into a ``.js`` file use the ``js`` command; the +default is a ``.js`` file that is supposed to be referenced in an ``.html`` +file. However, you can also run the code with `nodejs`:idx:, a `software +platform for easily building fast, scalable network applications +<http://nodejs.org>`_:: + + nimrod js -d:nodejs -r examples/hallo.nim + + +Interfacing +=========== + +intro + +Nimrod code calling the backend +-------------------------------- + +Backend code calling Nimrod +--------------------------- + +mention NimMain + +Memory management +================= + +Garbage collection, life of objects +----------------------------------- + +Thread coordination +------------------- diff --git a/doc/nimrodc.txt b/doc/nimrodc.txt index 58c234bcb..428c42f39 100644 --- a/doc/nimrodc.txt +++ b/doc/nimrodc.txt @@ -551,8 +551,18 @@ against. For instance, to link statically against Lua this command might work on Linux:: nimrod c --dynlibOverride:lua --passL:liblua.lib program.nim - - + + +Backend language options +======================== + +The typical compiler usage involves using the ``compile`` or ``c`` command to +transform a ``.nim`` file into one or more ``.c`` files which are then +compiled with the platform's C compiler into a static binary. However there +are other commands to compile to C++, Objective-C or Javascript. More details +can be read in the `Nimrod Backend Integration document <backends.html>`_. + + Nimrod documentation tools ========================== @@ -696,35 +706,3 @@ efficient: else: quit(errorStr(p, "expected: console or gui")) of "license": c.license = UnixToNativePath(k.value) else: quit(errorStr(p, "unknown variable: " & k.key)) - - -The JavaScript target -===================== - -Nimrod can also generate `JavaScript`:idx: code. However, the -JavaScript code generator is experimental! - -Nimrod targets JavaScript 1.5 which is supported by any widely used browser. -Since JavaScript does not have a portable means to include another module, -Nimrod just generates a long ``.js`` file. - -Features or modules that the JavaScript 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 -* 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 JavaScript platform. - -To compile a Nimrod module into a ``.js`` file use the ``js`` command; the -default is a ``.js`` file that is supposed to be referenced in an ``.html`` -file. However, you can also run the code with `nodejs`:idx:\: - - nimrod js -d:nodejs -r examples/hallo.nim - diff --git a/web/nimrod.ini b/web/nimrod.ini index ed8236c3e..fc652c158 100644 --- a/web/nimrod.ini +++ b/web/nimrod.ini @@ -37,7 +37,7 @@ UNIX. We don't believe this to be a coincidence. - Jeremy S. Anderson.""" [Documentation] doc: "endb;intern;apis;lib;manual;tut1;tut2;nimrodc;overview;filters;trmacros" -doc: "tools;c2nim;niminst;nimgrep;gc;estp;idetools;docgen;koch" +doc: "tools;c2nim;niminst;nimgrep;gc;estp;idetools;docgen;koch;backends.txt" pdf: "manual;lib;tut1;tut2;nimrodc;c2nim;niminst;gc" srcdoc2: "system.nim;impure/graphics;wrappers/sdl" srcdoc2: "core/macros;pure/marshal;core/typeinfo;core/unsigned" |