From 9c8ce45bcaedf24bc718e4c18f1b81ad81e36165 Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Sat, 21 Jun 2014 23:53:01 +0200 Subject: Starts nimrod calling backend section. --- doc/backends.txt | 72 ++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 60 insertions(+), 12 deletions(-) (limited to 'doc') diff --git a/doc/backends.txt b/doc/backends.txt index 2d7075323..9d57450dd 100644 --- a/doc/backends.txt +++ b/doc/backends.txt @@ -18,16 +18,18 @@ Introduction ============ The `Nimrod Compiler User Guide `_ 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. +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 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. +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. On top of generating a library +or executable, Nimrod offers bidirectional interfacing with the backend +targets through generic and specific pragmas. Backends @@ -53,8 +55,10 @@ line invocations:: $ 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 compiler commands select the target backend, but if needed you can +`specify additional switches for cross compilation +`_ to select the target CPU, operative system +or compiler/linker commands. The JavaScript target @@ -93,11 +97,55 @@ platform for easily building fast, scalable network applications Interfacing =========== -intro +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 +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 +component?). + Nimrod code calling the backend -------------------------------- +Nimrod code can interface with the backend through the `Foreign function +interface `_ mainly through the +`importc pragma `_. The ``importc`` pragma is the +*generic* way of making backend code available in Nimrod and is available in +all the target backends (JavaScript too). The C++ or Objective-C backends +have their respective `ImportCpp `_ and +`ImportObjC `_ pragmas to call methods from +classes. + +Whenever you use any of these pragmas you need to integrate native code into +your final binary. In the case of JavaScript this is no problem at all, the +same html file which hosts the generated JavaScript will likely provide other +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 +the need for having the related development libraries installed. This is done +through the `dynlib pragma for import +`_, though more specific control can be +gained using the `dynlib module `_. + +The `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 `_ if there are few sources or providing +them along the Nimrod code is easier than using a system library. Libraries +installed on the host system can be linked in with the `PassL pragma +`_. + +To wrap native code, take a look at the `c2nim tool `_ which helps +with the process of scanning and transforming header files into a Nimrod +interface. + +Example in C. + +Example in JS. + + Backend code calling Nimrod --------------------------- -- cgit 1.4.1-2-gfad0