jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix word wrapping

Browse source
This commit is contained in:
Jjp137 2019-10-17 20:13:04 -07:00
commit 3ad48069d3
18 changed files with 146 additions and 125 deletions
Download patch file Download diff file Expand all files Collapse all files

45
doc/backends.rst
View file

@ -107,12 +107,13 @@ Nim code calling the backend
Nim code can interface with the backend through the `Foreign function
interface <manual.html#foreign-function-interface>`_ mainly through the
`importc pragma <manual.html#foreign-function-interface-importc-pragma>`_. The ``importc`` pragma is the
*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 <manual.html#implementation-specific-pragmas-importcpp-pragma>`_ and
`ImportObjC <manual.html#implementation-specific-pragmas-importobjc-pragma>`_ pragmas to call methods from
classes.
`importc pragma <manual.html#foreign-function-interface-importc-pragma>`_.
The ``importc`` pragma is the *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
<manual.html#implementation-specific-pragmas-importcpp-pragma>`_ and
`ImportObjC <manual.html#implementation-specific-pragmas-importobjc-pragma>`_
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
@ -124,16 +125,16 @@ statically or dynamically. The preferred way of integrating native code is to
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#foreign-function-interface-dynlib-pragma-for-import>`_, though more specific control can be
gained using the `dynlib module <dynlib.html>`_.
<manual.html#foreign-function-interface-dynlib-pragma-for-import>`_, though
more specific control can be gained using the `dynlib module <dynlib.html>`_.
The `dynlibOverride <nimc.html#dynliboverride>`_ command line switch allows
to avoid dynamic linking if you need to statically link something instead.
Nim wrappers designed to statically link source files can use the `compile
pragma <manual.html#implementation-specific-pragmas-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
<manual.html#implementation-specific-pragmas-passl-pragma>`_.
pragma <manual.html#implementation-specific-pragmas-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 <manual.html#implementation-specific-pragmas-passl-pragma>`_.
To wrap native code, take a look at the `c2nim tool <https://nim-lang.org/docs/c2nim.html>`_ which helps
with the process of scanning and transforming header files into a Nim
@ -215,12 +216,12 @@ Backend code calling Nim
------------------------
Backend code can interface with Nim code exposed through the `exportc
pragma <manual.html#foreign-function-interface-exportc-pragma>`_. The ``exportc`` pragma is the *generic*
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.
pragma <manual.html#foreign-function-interface-exportc-pragma>`_. The
``exportc`` pragma is the *generic* 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
@ -329,8 +330,8 @@ 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 depends on the used backend and on your OS but you can
use the ``--nimcache`` `compiler switch <nimc.html#compiler-usage-command-line-switches>`_ to
change it.
use the ``--nimcache`` `compiler switch
<nimc.html#compiler-usage-command-line-switches>`_ to change it.
Memory management
@ -384,8 +385,8 @@ the backend will need careful consideration of who controls who. If you want
to hand a Nim reference to C code, you will need to use `GC_ref
<system.html#GC_ref,ref.T>`_ 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,ref.T>`_ proc to clean up this memory when it is not required
any more.
<system.html#GC_unref,ref.T>`_ 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 Nim so