version 0.8.10
This commit is contained in:
Araq
parent
53cd61546d
commit
765366c1f3
58 changed files with 768 additions and 30834 deletions
292
doc/c2nim.txt
Executable file
292
doc/c2nim.txt
Executable file
|
|
@ -0,0 +1,292 @@
|
|||
=================================
|
||||
c2nim User's manual
|
||||
=================================
|
||||
|
||||
:Author: Andreas Rumpf
|
||||
:Version: |nimrodversion|
|
||||
|
||||
.. contents::
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
c2nim is a tool to translate Ansi C code to Nimrod. The output is
|
||||
human-readable Nimrod code that is meant to be tweaked by hand after the
|
||||
translation process. c2nim is no real compiler!
|
||||
|
||||
c2nim is preliminary meant to translate C header files. Because of this, the
|
||||
preprocessor is part of the parser. For example:
|
||||
|
||||
.. code-block:: C
|
||||
#define abc 123
|
||||
#define xyz 789
|
||||
|
||||
Is translated into:
|
||||
|
||||
.. code-block:: Nimrod
|
||||
const
|
||||
abc* = 123
|
||||
xyz* = 789
|
||||
|
||||
|
||||
c2nim is meant to translate fragments of C code and thus does not follow
|
||||
include files. c2nim cannot parse all of Ansi C and many constructs cannot
|
||||
be represented in Nimrod: for example `duff's device`:idx: cannot be translated
|
||||
to Nimrod.
|
||||
|
||||
|
||||
Preprocessor support
|
||||
====================
|
||||
|
||||
Even though the translation process is not perfect, it is often the case that
|
||||
the translated Nimrod code does not need any tweaking by hand. In other cases
|
||||
it may be preferable to modify the input file instead of the generated Nimrod
|
||||
code so that c2nim can parse it properly. c2nim's preprocessor defines the
|
||||
symbol ``C2NIM`` that can be used to mark code sections:
|
||||
|
||||
.. code-block:: C
|
||||
#ifndef C2NIM
|
||||
// C2NIM should ignore this prototype:
|
||||
int fprintf(FILE* f, const char* frmt, ...);
|
||||
#endif
|
||||
|
||||
The ``C2NIM`` symbol is only recognized in ``#ifdef`` and ``#ifndef``
|
||||
constructs! ``#if defined(C2NIM)`` does **not** work.
|
||||
|
||||
c2nim *processes* ``#ifdef C2NIM`` and ``#ifndef C2NIM`` directives, but other
|
||||
``#if[def]`` directives are *translated* into Nimrod's ``when`` construct:
|
||||
|
||||
.. code-block:: C
|
||||
#ifdef DEBUG
|
||||
# define OUT(x) printf("%s\n", x)
|
||||
#else
|
||||
# define OUT(x)
|
||||
#endif
|
||||
|
||||
Is translated into:
|
||||
|
||||
.. code-block:: Nimrod
|
||||
when defined(debug):
|
||||
template OUT*(x: expr): expr =
|
||||
printf("%s\x0A", x)
|
||||
else:
|
||||
template OUT*(x: expr): stmt =
|
||||
nil
|
||||
|
||||
As can been seen from the example, C's macros with parameters are mapped
|
||||
to Nimrod's templates. This mapping is the best one can do, but it is of course
|
||||
not accurate: Nimrod's templates operate on syntax trees whereas C's
|
||||
macros work on the token level. c2nim cannot translate any macro that contains
|
||||
the ``##`` token concatenation operator.
|
||||
|
||||
c2nim's preprocessor supports special directives that affect how the output
|
||||
is generated. They should be put into a ``#ifdef C2NIM`` section so that
|
||||
ordinary C compilers ignore them.
|
||||
|
||||
|
||||
``#skipinclude`` directive
|
||||
--------------------------
|
||||
**Note**: There is also a ``--skipinclude`` command line option that can be
|
||||
used for the same purpose.
|
||||
|
||||
By default, c2nim translates an ``#include`` that is not followed by ``<``
|
||||
(like in ``#include <stdlib>``) to a Nimrod ``import`` statement. This
|
||||
directive tells c2nim to just skip any ``#include``.
|
||||
|
||||
|
||||
``#stdcall`` and ``#cdecl`` directives
|
||||
--------------------------------------
|
||||
**Note**: There are also ``--stdcall`` and ``--cdecl`` command line options
|
||||
that can be used for the same purpose.
|
||||
|
||||
These directives tell c2nim that it should annotate every proc (or proc type)
|
||||
with the ``stdcall`` / ``cdecl`` calling convention.
|
||||
|
||||
|
||||
``#dynlib`` directive
|
||||
---------------------
|
||||
**Note**: There is also a ``--dynlib`` command line option that can be used for
|
||||
the same purpose.
|
||||
|
||||
This directive tells c2nim that it should annotate every proc that resulted
|
||||
from a C function prototype with the ``dynlib`` pragma:
|
||||
|
||||
.. code-block:: C
|
||||
|
||||
#ifdef C2NIM
|
||||
# dynlib iupdll
|
||||
# cdecl
|
||||
# if defined(windows)
|
||||
# define iupdll "iup.dll"
|
||||
# elif defined(macosx)
|
||||
# define iupdll "libiup.dynlib"
|
||||
# else
|
||||
# define iupdll "libiup.so"
|
||||
# endif
|
||||
#endif
|
||||
|
||||
int IupConvertXYToPos(PIhandle ih, int x, int y);
|
||||
|
||||
Is translated to:
|
||||
|
||||
.. code-block:: Nimrod
|
||||
when defined(windows):
|
||||
const iupdll* = "iup.dll"
|
||||
elif defined(macosx):
|
||||
const iupdll* = "libiup.dynlib"
|
||||
else:
|
||||
const iupdll* = "libiup.so"
|
||||
|
||||
proc IupConvertXYToPos*(ih: PIhandle, x: cint, y: cint): cint {.
|
||||
importc: "IupConvertXYToPos", cdecl, dynlib: iupdll.}
|
||||
|
||||
Note how the example contains extra C code to declare the ``iupdll`` symbol
|
||||
in the generated Nimrod code.
|
||||
|
||||
|
||||
``#header`` directive
|
||||
---------------------
|
||||
**Note**: There is also a ``--header`` command line option that can be used for
|
||||
the same purpose.
|
||||
|
||||
The ``#header`` directive tells c2nim that it should annotate every proc that
|
||||
resulted from a C function prototype and every exported variable and type with
|
||||
the ``header`` pragma:
|
||||
|
||||
.. code-block:: C
|
||||
|
||||
#ifdef C2NIM
|
||||
# header "iup.h"
|
||||
#endif
|
||||
|
||||
int IupConvertXYToPos(PIhandle ih, int x, int y);
|
||||
|
||||
Is translated to:
|
||||
|
||||
.. code-block:: Nimrod
|
||||
proc IupConvertXYToPos*(ih: PIhandle, x: cint, y: cint): cint {.
|
||||
importc: "IupConvertXYToPos", header: "iup.h".}
|
||||
|
||||
The ``#header`` and the ``#dynlib`` directives are mutually exclusive.
|
||||
A binding that uses ``dynlib`` is much more preferable over one that uses
|
||||
``header``! The Nimrod compiler might drop support for the ``header`` pragma
|
||||
in the future as it cannot work for backends that do not generate C code.
|
||||
|
||||
|
||||
``#prefix`` and ``#suffix`` directives
|
||||
--------------------------------------
|
||||
|
||||
**Note**: There are also ``--prefix`` and ``--suffix`` command line options
|
||||
that can be used for the same purpose.
|
||||
|
||||
c2nim does not do any name mangling by default. However the
|
||||
``#prefix`` and ``#suffix`` directives can be used to strip prefixes and
|
||||
suffixes from the identifiers in the C code:
|
||||
|
||||
.. code-block:: C
|
||||
|
||||
#ifdef C2NIM
|
||||
# prefix Iup
|
||||
# dynlib dllname
|
||||
# cdecl
|
||||
#endif
|
||||
|
||||
int IupConvertXYToPos(PIhandle ih, int x, int y);
|
||||
|
||||
Is translated to:
|
||||
|
||||
.. code-block:: Nimrod
|
||||
|
||||
proc ConvertXYToPos*(ih: PIhandle, x: cint, y: cint): cint {.
|
||||
importc: "IupConvertXYToPos", cdecl, dynlib: dllname.}
|
||||
|
||||
|
||||
``#mangle`` directive
|
||||
---------------------
|
||||
|
||||
Even more sophisticated name mangling can be achieved by the ``#mangle``
|
||||
directive: It takes a PEG pattern and format string that specify how the
|
||||
identifier should be converted:
|
||||
|
||||
.. code-block:: C
|
||||
#mangle "'GTK_'{.*}" "TGtk$1"
|
||||
|
||||
For convenience the PEG pattern and the replacement can be single identifiers
|
||||
too, there is no need to quote them:
|
||||
|
||||
.. code-block:: C
|
||||
#mangle ssize_t int
|
||||
// is short for:
|
||||
#mangle "'ssize_t'" "int"
|
||||
|
||||
|
||||
``#private`` directive
|
||||
----------------------
|
||||
|
||||
By default c2nim marks every top level identifier (proc name, variable, etc.)
|
||||
as exported (the export marker is ``*`` in Nimrod). With the ``#private``
|
||||
directive identifiers can be marked as private so that the resulting Nimrod
|
||||
module does not export them. The ``#private`` directive takes a PEG pattern:
|
||||
|
||||
.. code-block:: C
|
||||
#private "@('_'!.)" // all identifiers ending in '_' are private
|
||||
|
||||
Note: The pattern refers to the original C identifiers, not to the resulting
|
||||
identifiers after mangling!
|
||||
|
||||
|
||||
``#skipcomments`` directive
|
||||
---------------------------
|
||||
**Note**: There is also a ``--skipcomments`` command line option that can be
|
||||
used for the same purpose.
|
||||
|
||||
The ``#skipcomments`` directive can be put into the C code to make c2nim
|
||||
ignore comments and not copy them into the generated Nimrod file.
|
||||
|
||||
|
||||
``#typeprefixes`` directive
|
||||
---------------------------
|
||||
**Note**: There is also a ``--typeprefixes`` command line option that can be
|
||||
used for the same purpose.
|
||||
|
||||
The ``#typeprefixes`` directive can be put into the C code to make c2nim
|
||||
generate the ``T`` or ``P`` prefix for every defined type.
|
||||
|
||||
|
||||
``#def`` directive
|
||||
------------------
|
||||
|
||||
Often C code contains special macros that affect the declaration of a function
|
||||
prototype but confuse c2nim's parser:
|
||||
|
||||
.. code-block:: C
|
||||
// does not parse!
|
||||
EXTERN(int) f(void);
|
||||
EXTERN(int) g(void);
|
||||
|
||||
Instead of removing ``EXTERN()`` from the input source file (which cannot be
|
||||
done reliably even with a regular expression!), one can tell c2nim
|
||||
that ``EXPORT`` is a macro that should be expanded by c2nim too:
|
||||
|
||||
.. code-block:: C
|
||||
#ifdef C2NIM
|
||||
# def EXTERN(x) static x
|
||||
#endif
|
||||
// parses now!
|
||||
EXTERN(int) f(void);
|
||||
EXTERN(int) g(void);
|
||||
|
||||
``#def`` is very similar to C's ``#define``, so in general the macro definition
|
||||
can be copied and pasted into a ``#def`` directive.
|
||||
|
||||
|
||||
Limitations
|
||||
===========
|
||||
|
||||
* C's ``,`` operator (comma operator) is not supported.
|
||||
* C's ``union`` are translated to Nimrod's objects and only the first field
|
||||
is included in the object type. This way there is a high chance that it is
|
||||
binary compatible to the union.
|
||||
* The condition in a ``do while(condition)`` statement must be ``0``.
|
||||
* Lots of other small issues...
|
||||
|
||||
|
|
@ -16,6 +16,9 @@ The documentation consists of several documents:
|
|||
| The user guide lists command line arguments, special features of the
|
||||
compiler, etc.
|
||||
|
||||
- | `Tools documentation <tools.html>`_
|
||||
| Description of some tools that come with the standard distribution.
|
||||
|
||||
- | `Manual <manual.html>`_
|
||||
| The Nimrod manual is a draft that will evolve into a proper specification.
|
||||
|
||||
|
|
|
|||
11
doc/lib.txt
Executable file → Normal file
11
doc/lib.txt
Executable file → Normal file
|
|
@ -256,7 +256,7 @@ Other
|
|||
Wrappers
|
||||
========
|
||||
|
||||
The generated HTML for some of these wrappers is so huge, that it is
|
||||
The generated HTML for some of these wrappers is so huge that it is
|
||||
not contained in the distribution. You can then find them on the website.
|
||||
|
||||
Windows specific
|
||||
|
|
@ -321,6 +321,15 @@ UNIX specific
|
|||
Part of the wrapper for X11.
|
||||
|
||||
|
||||
Regular expressions
|
||||
-------------------
|
||||
|
||||
* `pcre <pcre.html>`_
|
||||
Wrapper for the PCRE library.
|
||||
* `tre <tre.html>`_
|
||||
Wrapper for the TRE library.
|
||||
|
||||
|
||||
Graphics libraries
|
||||
------------------
|
||||
|
||||
|
|
|
|||
191
doc/niminst.txt
Executable file
191
doc/niminst.txt
Executable file
|
|
@ -0,0 +1,191 @@
|
|||
=================================
|
||||
niminst User's manual
|
||||
=================================
|
||||
|
||||
:Author: Andreas Rumpf
|
||||
:Version: |nimrodversion|
|
||||
|
||||
.. contents::
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
niminst is a tool to generate an installer for a Nimrod program. Currently
|
||||
it can create an installer for Windows via `Inno Setup <>`_ as well as
|
||||
installation/deinstallation scripts for UNIX. Later versions will support
|
||||
Linux' package management systems.
|
||||
|
||||
niminst works by reading a configuration file that contains all the
|
||||
information that it needs to generate an installer for the different operating
|
||||
systems.
|
||||
|
||||
|
||||
Configuration file
|
||||
==================
|
||||
|
||||
niminst uses the Nimrod `parsecfg <parsecfg.html>`_ module to parse the
|
||||
configuration file. Here's an example of how the syntax looks like:
|
||||
|
||||
.. include:: doc/mytest.cfg
|
||||
:literal:
|
||||
|
||||
The value of a key-value pair can reference user-defined variables via
|
||||
the ``$variable`` notation: They can be defined in the command line with the
|
||||
``--var:name=value`` switch. This is useful to not hard-coding the
|
||||
program's version number into the configuration file, for instance.
|
||||
|
||||
It follows a description of each possible section and how it affects the
|
||||
generated installers.
|
||||
|
||||
|
||||
Project section
|
||||
---------------
|
||||
The project section gathers general information about your project. It must
|
||||
contain the following key-value pairs:
|
||||
|
||||
==================== =======================================================
|
||||
Key description
|
||||
==================== =======================================================
|
||||
``Name`` the project's name; this needs to be a single word
|
||||
``DisplayName`` the project's long name; this can contain spaces. If
|
||||
not specified, this is the same as ``Name``.
|
||||
``Version`` the project's version
|
||||
``OS`` the OSes to generate C code for; for example:
|
||||
``"windows;linux;macosx"``
|
||||
``CPU`` the CPUs to generate C code for; for example:
|
||||
``"i386;amd64;powerpc"``
|
||||
``Authors`` the project's authors
|
||||
``Description`` the project's description
|
||||
``App`` the application's type: "Console" or "GUI". If
|
||||
"Console", niminst generates a special batch file
|
||||
for Windows to open up the command line shell.
|
||||
``License`` the filename of the application's license
|
||||
==================== =======================================================
|
||||
|
||||
|
||||
``files`` key
|
||||
-------------
|
||||
|
||||
Many sections support the ``files`` key. Listed filenames
|
||||
can be separated by semicolon or the ``files`` key can be repeated. Wildcards
|
||||
in filenames are supported. If it is a directory name, all files in the
|
||||
directory are used::
|
||||
|
||||
[Config]
|
||||
Files: "configDir"
|
||||
Files: "otherconfig/*.conf;otherconfig/*.cfg"
|
||||
|
||||
|
||||
Config section
|
||||
--------------
|
||||
|
||||
The ``config`` section currently only supports the ``files`` key. Listed files
|
||||
will be installed into the OS's configuration directory.
|
||||
|
||||
|
||||
Documentation section
|
||||
---------------------
|
||||
|
||||
The ``documentation`` section currently only supports the ``files`` key.
|
||||
Listed files will be installed into the OS's native documentation directory
|
||||
(which might be ``$appdir/doc``).
|
||||
|
||||
|
||||
Other section
|
||||
-------------
|
||||
|
||||
The ``other`` section currently only supports the ``files`` key.
|
||||
Listed files will be installed into the application installation directory
|
||||
(``$appdir``).
|
||||
|
||||
|
||||
Lib section
|
||||
-----------
|
||||
|
||||
The ``lib`` section currently only supports the ``files`` key.
|
||||
Listed files will be installed into the OS's native library directory
|
||||
(which might be ``$appdir/lib``).
|
||||
|
||||
|
||||
Windows section
|
||||
---------------
|
||||
|
||||
The ``windows`` section supports the ``files`` key for Windows specific files.
|
||||
Listed files will be installed into the application installation directory
|
||||
(``$appdir``).
|
||||
|
||||
Other possible options are:
|
||||
|
||||
==================== =======================================================
|
||||
Key description
|
||||
==================== =======================================================
|
||||
``BinPath`` paths to add to the Windows ``%PATH%`` environment
|
||||
variable. Example: ``BinPath: r"bin;dist\mingw\bin"``
|
||||
``InnoSetup`` boolean flag whether an Inno Setup installer should be
|
||||
generated for Windows. Example: ``InnoSetup: "Yes"``
|
||||
==================== =======================================================
|
||||
|
||||
|
||||
UnixBin section
|
||||
---------------
|
||||
|
||||
The ``UnixBin`` section currently only supports the ``files`` key.
|
||||
Listed files will be installed into the OS's native bin directory
|
||||
(e.g. ``/usr/local/bin``). The exact location depends on the
|
||||
installation path the user specifies when running the ``install.sh`` script.
|
||||
|
||||
|
||||
Unix section
|
||||
------------
|
||||
|
||||
Possible options are:
|
||||
|
||||
==================== =======================================================
|
||||
Key description
|
||||
==================== =======================================================
|
||||
``InstallScript`` boolean flag whether an installation shell script
|
||||
should be generated. Example: ``InstallScript: "Yes"``
|
||||
``UninstallScript`` boolean flag whether a deinstallation shell script
|
||||
should be generated.
|
||||
Example: ``UninstallScript: "Yes"``
|
||||
==================== =======================================================
|
||||
|
||||
|
||||
InnoSetup section
|
||||
-----------------
|
||||
|
||||
Possible options are:
|
||||
|
||||
==================== =======================================================
|
||||
Key description
|
||||
==================== =======================================================
|
||||
``path`` Path to Inno Setup.
|
||||
Example: ``path = r"c:\inno setup 5\iscc.exe"``
|
||||
``flags`` Flags to pass to Inno Setup.
|
||||
Example: ``flags = "/Q"``
|
||||
==================== =======================================================
|
||||
|
||||
|
||||
C_Compiler section
|
||||
------------------
|
||||
|
||||
Possible options are:
|
||||
|
||||
==================== =======================================================
|
||||
Key description
|
||||
==================== =======================================================
|
||||
``path`` Path to the C compiler.
|
||||
``flags`` Flags to pass to the C Compiler.
|
||||
Example: ``flags = "-w"``
|
||||
==================== =======================================================
|
||||
|
||||
|
||||
Real world example
|
||||
==================
|
||||
|
||||
The installers for the Nimrod compiler itself are generated by niminst. Have a
|
||||
look at its configuration file:
|
||||
|
||||
.. include:: rod/nimrod.ini
|
||||
:literal:
|
||||
|
||||
346
doc/theindex.txt
346
doc/theindex.txt
File diff suppressed because it is too large
Load diff
12
doc/tools.txt
Executable file
12
doc/tools.txt
Executable file
|
|
@ -0,0 +1,12 @@
|
|||
=====
|
||||
Tools
|
||||
=====
|
||||
|
||||
The standard distribution ships with the following tools:
|
||||
|
||||
- | `Nimrod Installation Generator <niminst.html>`_
|
||||
| How to generate a nice installer for your Nimrod program.
|
||||
|
||||
- | `C2nim <c2nim.html>`_
|
||||
| C to Nimrod source converter. Translates C header files to Nimrod.
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue