diff options
Diffstat (limited to 'doc/backends.txt')
| -rw-r--r-- | doc/backends.txt | 170 |
1 files changed, 85 insertions, 85 deletions
diff --git a/doc/backends.txt b/doc/backends.txt index c2dbb0af6..eb16217cd 100644 --- a/doc/backends.txt +++ b/doc/backends.txt @@ -1,9 +1,9 @@ ================================ - Nimrod Backend Integration + Nim Backend Integration ================================ :Author: Puppet Master -:Version: |nimrodversion| +:Version: |nimversion| .. contents:: "Heresy grows from idleness." -- Unknown. @@ -12,20 +12,20 @@ Introduction ============ -The `Nimrod Compiler User Guide <nimrodc.html>`_ documents the typical +The `Nim Compiler User Guide <nimc.html>`_ documents the typical compiler invocation, 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 backend families: the C, C++ and +The Nim compiler supports mainly two backend families: the C, C++ and Objective-C targets and the JavaScript target. `The C like targets`_ creates source files which can be compiled into a library or a final executable. `The JavaScript target`_ can generate a ``.js`` file which you reference from an HTML file or create a `standalone nodejs program <http://nodejs.org>`_. -On top of generating libraries or standalone applications, Nimrod offers +On top of generating libraries or standalone applications, Nim offers bidirectional interfacing with the backend targets through generic and specific pragmas. @@ -49,25 +49,25 @@ 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 + $ nim c hallo.nim + $ nim cpp hallo.nim + $ nim objc hallo.nim The compiler commands select the target backend, but if needed you can `specify additional switches for cross compilation -<nimrodc.html#cross-compilation>`_ to select the target CPU, operative system +<nimc.html#cross-compilation>`_ to select the target CPU, operative system or compiler/linker commands. The JavaScript target --------------------- -Nimrod can also generate `JavaScript`:idx: code through the ``js`` command. +Nim 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. +Nim 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. +Nim just generates a long ``.js`` file. Features or modules that the JavaScript platform does not support are not available. This includes: @@ -83,35 +83,35 @@ 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 +To compile a Nim 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 + nim js -d:nodejs -r examples/hallo.nim Interfacing =========== -Nimrod offers bidirectional interfacing with the target backend. This means -that you can call backend code from Nimrod and Nimrod code can be called by +Nim offers bidirectional interfacing with the target backend. This means +that you can call backend code from Nim and Nim code can be called by the backend code. Usually the direction of which calls which depends on your -software architecture (is Nimrod your main program or is Nimrod providing a +software architecture (is Nim your main program or is Nim providing a component?). -Nimrod code calling the backend --------------------------------- +Nim code calling the backend +---------------------------- -Nimrod code can interface with the backend through the `Foreign function +Nim code can interface with the backend through the `Foreign function interface <manual.html#foreign-function-interface>`_ mainly through the `importc pragma <manual.html#importc-pragma>`_. The ``importc`` pragma is the -*generic* way of making backend symbols available in Nimrod and is available +*generic* way of making backend symbols available in Nim and is available in all the target backends (JavaScript too). The C++ or Objective-C backends -have their respective `ImportCpp <nimrodc.html#importcpp-pragma>`_ and -`ImportObjC <nimrodc.html#importobjc-pragma>`_ pragmas to call methods from +have their respective `ImportCpp <nimc.html#importcpp-pragma>`_ and +`ImportObjC <nimc.html#importobjc-pragma>`_ pragmas to call methods from classes. Whenever you use any of these pragmas you need to integrate native code into @@ -121,22 +121,22 @@ JavaScript functions which you are importing with ``importc``. However, for the C like targets you need to link external code either statically or dynamically. The preferred way of integrating native code is to -use dynamic linking because it allows you to compile Nimrod programs without +use dynamic linking because it allows you to compile Nim programs without the need for having the related development libraries installed. This is done through the `dynlib pragma for import <manual.html#dynlib-pragma-for-import>`_, though more specific control can be gained using the `dynlib module <dynlib.html>`_. -The `dynlibOverride <nimrodc.html#dynliboverride>`_ command line switch allows +The `dynlibOverride <nimc.html#dynliboverride>`_ command line switch allows to avoid dynamic linking if you need to statically link something instead. -Nimrod wrappers designed to statically link source files can use the `compile -pragma <nimrodc.html#compile-pragma>`_ if there are few sources or providing -them along the Nimrod code is easier than using a system library. Libraries +Nim wrappers designed to statically link source files can use the `compile +pragma <nimc.html#compile-pragma>`_ if there are few sources or providing +them along the Nim code is easier than using a system library. Libraries installed on the host system can be linked in with the `PassL pragma -<nimrodc.html#passl-pragma>`_. +<nimc.html#passl-pragma>`_. To wrap native code, take a look at the `c2nim tool <c2nim.html>`_ which helps -with the process of scanning and transforming header files into a Nimrod +with the process of scanning and transforming header files into a Nim interface. C invocation example @@ -152,7 +152,7 @@ Create a ``logic.c`` file with the following content: Create a ``calculator.nim`` file with the following content: -.. code-block:: nimrod +.. code-block:: nim {.compile: "logic.c".} proc addTwoIntegers(a, b: cint): cint {.importc.} @@ -160,8 +160,8 @@ Create a ``calculator.nim`` file with the following content: when isMainModule: echo addTwoIntegers(3, 7) -With these two files in place, you can run ``nimrod c -r calculator.nim`` and -the Nimrod compiler will compile the ``logic.c`` file in addition to +With these two files in place, you can run ``nim c -r calculator.nim`` and +the Nim compiler will compile the ``logic.c`` file in addition to ``calculator.nim`` and link both into an executable, which outputs ``10`` when run. Another way to link the C file statically and get the same effect would be remove the line with the ``compile`` pragma and run the following typical @@ -169,7 +169,7 @@ Unix commands:: $ gcc -c logic.c $ ar rvs mylib.a logic.o - $ nimrod c --passL:mylib.a -r calculator.nim + $ nim c --passL:mylib.a -r calculator.nim Just like in this example we pass the path to the ``mylib.a`` library (and we could as well pass ``logic.o``) we could be passing switches to link any other @@ -196,50 +196,50 @@ Create a ``host.html`` file with the following content: Create a ``calculator.nim`` file with the following content (or reuse the one from the previous section): -.. code-block:: nimrod +.. code-block:: nim proc addTwoIntegers(a, b: int): int {.importc.} when isMainModule: echo addTwoIntegers(3, 7) -Compile the Nimrod code to JavaScript with ``nimrod js -o:calculator.js +Compile the Nim code to JavaScript with ``nim js -o:calculator.js calculator.nim`` and open ``host.html`` in a browser. If the browser supports javascript, you should see the value ``10``. In JavaScript the `echo proc <system.html#echo>`_ will modify the HTML DOM and append the string. Use the `dom module <dom.html>`_ for specific DOM querying and modification procs. -Backend code calling Nimrod ---------------------------- +Backend code calling Nim +------------------------ -Backend code can interface with Nimrod code exposed through the `exportc +Backend code can interface with Nim code exposed through the `exportc pragma <manual.html#exportc-pragma>`_. The ``exportc`` pragma is the *generic* -way of making Nimrod symbols available to the backends. By default the Nimrod -compiler will mangle all the Nimrod symbols to avoid any name collision, so -the most significant thing the ``exportc`` pragma does is maintain the Nimrod +way of making Nim symbols available to the backends. By default the Nim +compiler will mangle all the Nim symbols to avoid any name collision, so +the most significant thing the ``exportc`` pragma does is maintain the Nim symbol name, or if specified, use an alternative symbol for the backend in case the symbol rules don't match. The JavaScript target doesn't have any further interfacing considerations since it also has garbage collection, but the C targets require you to -initialize Nimrod's internals, which is done calling a ``NimMain`` function. +initialize Nim's internals, which is done calling a ``NimMain`` function. Also, C code requires you to specify a forward declaration for functions or the compiler will asume certain types for the return value and parameters which will likely make your program crash at runtime. -The Nimrod compiler can generate a C interface header through the ``--header`` +The Nim compiler can generate a C interface header through the ``--header`` command line switch. The generated header will contain all the exported symbols and the ``NimMain`` proc which you need to call before any other -Nimrod code. +Nim code. -Nimrod invocation example from C -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Nim invocation example from C +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Create a ``fib.nim`` file with the following content: -.. code-block:: nimrod +.. code-block:: nim proc fib(a: cint): cint {.exportc.} = if a <= 2: @@ -263,35 +263,35 @@ Create a ``maths.c`` file with the following content: } Now you can run the following Unix like commands to first generate C sources -form the Nimrod code, then link them into a static binary along your main C +form the Nim code, then link them into a static binary along your main C program:: - $ nimrod c --noMain --noLinking --header:fib.h fib.nim - $ gcc -o m -Inimcache -Ipath/to/nimrod/lib nimcache/*.c maths.c + $ nim c --noMain --noLinking --header:fib.h fib.nim + $ gcc -o m -Inimcache -Ipath/to/nim/lib nimcache/*.c maths.c -The first command runs the Nimrod compiler with three special options to avoid +The first command runs the Nim compiler with three special options to avoid generating a ``main()`` function in the generated files, avoid linking the object files into a final binary, and explicitly generate a header file for C integration. All the generated files are placed into the ``nimcache`` directory. That's why the next command compiles the ``maths.c`` source plus all the ``.c`` files form ``nimcache``. In addition to this path, you also -have to tell the C compiler where to find Nimrod's ``nimbase.h`` header file. +have to tell the C compiler where to find Nim's ``nimbase.h`` header file. Instead of depending on the generation of the individual ``.c`` files you can -also ask the Nimrod compiler to generate a statically linked library:: +also ask the Nim compiler to generate a statically linked library:: - $ nimrod c --app:staticLib --noMain --header fib.nim - $ gcc -o m -Inimcache -Ipath/to/nimrod/lib libfib.nim.a maths.c + $ nim c --app:staticLib --noMain --header fib.nim + $ gcc -o m -Inimcache -Ipath/to/nim/lib libfib.nim.a maths.c -The Nimrod compiler will handle linking the source files generated in the +The Nim compiler will handle linking the source files generated in the ``nimcache`` directory into the ``libfib.nim.a`` static library, which you can then link into your C program. Note that these commands are generic and will vary for each system. For instance, on Linux systems you will likely need to use ``-ldl`` too to link in required dlopen functionality. -Nimrod invocation example from JavaScript -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Nim invocation example from JavaScript +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Create a ``mhost.html`` file with the following content: @@ -307,7 +307,7 @@ Create a ``mhost.html`` file with the following content: Create a ``fib.nim`` file with the following content (or reuse the one from the previous section): -.. code-block:: nimrod +.. code-block:: nim proc fib(a: cint): cint {.exportc.} = if a <= 2: @@ -315,11 +315,11 @@ from the previous section): else: result = fib(a - 1) + fib(a - 2) -Compile the Nimrod code to JavaScript with ``nimrod js -o:fib.js fib.nim`` and +Compile the Nim code to JavaScript with ``nim js -o:fib.js fib.nim`` and open ``mhost.html`` in a browser. If the browser supports javascript, you should see an alert box displaying the text ``Fib for 9 is 34``. As mentioned earlier, JavaScript doesn't require an initialisation call to ``NimMain`` or -similar function and you can call the exported Nimrod proc directly. +similar function and you can call the exported Nim proc directly. Nimcache naming logic @@ -328,17 +328,17 @@ Nimcache naming logic The `nimcache`:idx: directory is generated during compilation and will hold either temporary or final files depending on your backend target. The default name for the directory is ``nimcache`` but you can use the ``--nimcache`` -`compiler switch <nimrodc.html#command-line-switches>`_ to change it. +`compiler switch <nimc.html#command-line-switches>`_ to change it. Nimcache and C like targets ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The C like backends will place their temporary ``.c``, ``.cpp`` or ``.m`` files in the ``nimcache`` directory. The naming of these files follows the pattern -``babelPackageName_`` + ``nimrodSource``: +``babelPackageName_`` + ``nimSource``: * Filenames for modules imported from `Babel packages - <https://github.com/nimrod-code/babel>`_ will end up with + <https://github.com/nim-code/babel>`_ will end up with ``babelPackageName_module.c``. For example, if you import the ``argument_parser`` module from the same name Babel package you will end up with a ``argument_parser_argument_parser.c`` file @@ -375,7 +375,7 @@ Nimcache and the Javascript target Unless you explicitly use the ``-o:filename.js`` switch as mentioned in the previous examples, the compiler will create a ``filename.js`` file in the -``nimcache`` directory using the name of your input nimrod file. There are no +``nimcache`` directory using the name of your input nim file. There are no other temporary files generated, the output is always a single self contained ``.js`` file. @@ -387,38 +387,38 @@ In the previous sections the ``NimMain()`` function reared its head. Since JavaScript already provides automatic memory management, you can freely pass objects between the two language without problems. In C and derivate languages you need to be careful about what you do and how you share memory. The -previous examples only dealt with simple scalar values, but passing a Nimrod -string to C, or reading back a C string in Nimrod already requires you to be +previous examples only dealt with simple scalar values, but passing a Nim +string to C, or reading back a C string in Nim already requires you to be aware of who controls what to avoid crashing. Strings and C strings --------------------- -The manual mentions that `Nimrod strings are implicitly convertible to +The manual mentions that `Nim strings are implicitly convertible to cstrings <manual.html#cstring-type>`_ which makes interaction usually -painless. Most C functions accepting a Nimrod string converted to a +painless. Most C functions accepting a Nim string converted to a ``cstring`` will likely not need to keep this string around and by the time they return the string won't be needed any more. However, for the rare cases -where a Nimrod string has to be preserved and made available to the C backend +where a Nim string has to be preserved and made available to the C backend as a ``cstring``, you will need to manually prevent the string data from being freed with `GC_ref <system.html#GC_ref>`_ and `GC_unref <system.html#GC_unref>`_. -A similar thing happens with C code invoking Nimrod code which returns a +A similar thing happens with C code invoking Nim code which returns a ``cstring``. Consider the following proc: -.. code-block:: nimrod +.. code-block:: nim proc gimme(): cstring {.exportc.} = result = "Hey there C code! " & $random(100) -Since Nimrod's garbage collector is not aware of the C code, once the +Since Nim's garbage collector is not aware of the C code, once the ``gimme`` proc has finished it can reclaim the memory of the ``cstring``. However, from a practical standpoint, the C code invoking the ``gimme`` -function directly will be able to use it since Nimrod's garbage collector has +function directly will be able to use it since Nim's garbage collector has not had a chance to run *yet*. This gives you enough time to make a copy for -the C side of the program, as calling any further Nimrod procs *might* trigger +the C side of the program, as calling any further Nim procs *might* trigger garbage collection making the previously returned string garbage. Or maybe you are `triggering yourself the collection <gc.html>`_. @@ -426,35 +426,35 @@ are `triggering yourself the collection <gc.html>`_. Custom data types ----------------- -Just like strings, custom data types that are to be shared between Nimrod and +Just like strings, custom data types that are to be shared between Nim and the backend will need careful consideration of who controlls who. If you want -to hand a Nimrod reference to C code, you will need to use `GC_ref +to hand a Nim reference to C code, you will need to use `GC_ref <system.html#GC_ref>`_ to mark the reference as used, so it does not get freed. And for the C backend you will need to expose the `GC_unref <system.html#GC_unref>`_ proc to clean up this memory when it is not required any more. Again, if you are wrapping a library which *mallocs* and *frees* data -structures, you need to expose the appropriate *free* function to Nimrod so +structures, you need to expose the appropriate *free* function to Nim so you can clean it up. And of course, once cleaned you should avoid accessing it -from Nimrod (or C for that matter). Typically C data structures have their own +from Nim (or C for that matter). Typically C data structures have their own ``malloc_structure`` and ``free_structure`` specific functions, so wrapping -these for the Nimrod side should be enough. +these for the Nim side should be enough. Thread coordination ------------------- -When the ``NimMain()`` function is called Nimrod initializes the garbage +When the ``NimMain()`` function is called Nim initializes the garbage collector to the current thread, which is usually the main thread of your -application. If your C code later spawns a different thread and calls Nimrod +application. If your C code later spawns a different thread and calls Nim code, the garbage collector will fail to work properly and you will crash. -As long as you don't use the threadvar emulation Nimrod uses native thread +As long as you don't use the threadvar emulation Nim uses native thread variables, of which you get a fresh version whenever you create a thread. You can then attach a GC to this thread via -.. code-block:: nimrod +.. code-block:: nim setStackBottom(addr(someLocal)) initGC() |