H2O

H2O — is the tool for making Oberon and Component Pascal import modules from C header files.

Installation

H2O sources distributed with oo2c compiler.

Linux

1. Download sources from: http://github.com/AlexIljin/oo2c

git clone http://github.com/AlexIljin/oo2c.git

2. Compilation of oo2c:

cd oo2c
export LDFLAGS="-lm"
chmod +x configure
./configure --prefix /usr
make
sudo make install

3. Compilation of H2O

oo2c -M src/TestH2O.Mod

Windows

H2O can be run on windows with Cygwin. The example you can download here.

Usage

There are a couple of modes in which it can work.

• With arguments "--preprocess" it just preprocesses source, outputting tokenised symbols (not very useful).
• With arguments "--preprocess --text" it preprocesses source, outputting text.
• Without arguments, it translates "C" definitions, producing Oberon-2 output.

Processing C source code

TestH2O misc/test.c

Processing with outer H2O directive

You have to tell H2O the name of the top level file. Normally, this file will include a H2O section with options and module definitions and finish with a #include directive that includes the actual source files that you want to translate.

So if you want to translate test.c, you would make test.h2o that looks like this:

H2O {
  ... translation options here ...
}
#include "test.c"

To initiate the translation you would do:

TestH2O test.h2o

For included modules, the behaviour depends on the type of include. If you do:

 #include <mod.h>

it looks in the search path specified by the Include option. If you do:

 #include "mod.h"

it looks in the same directory as the file that does the #include.

The "OPTIONS" directive is global to the translation, and includes things like:

• OutputDirectory — where to put the generated module files
• Include — list of paths to get include files
• Exclude — list of files to not include (#include ignored)
• AutoPrefix — prefix for auto-generated type names (default "Auto")
• TagSuffix — suffix to be added to structure tags (default "_tag")
• RenameProcedures — when set to "1" (the default) renames procedures using module "StripPrefix" specification.
• RenameVariables — when set to "1" (default is "0", since this is unsupported in OOC V2) renames variables using module "StripPrefix" specification.
• ModuleSuffix — suffix for module file names (default "Mod").

In this section, you can also specify the type mappings for scalar types:

  OPTION symbol          C type                Default output type
  ----------------------------------------------------------------
  MapChar                "char"                "CHAR"
  MapUnsignedChar        "unsigned char"       "CHAR"
  MapShort               "short"               "INTEGER"
  MapUnsignedShort       "unsigned short"      "INTEGER"
  MapLong                "long"                "LONGINT"
  MapUnsignedLong        "unsigned long"       "LONGINT"
  MapLongLong            "long long"           "HUGEINT"
  MapUnsignedLongLong    "unsigned long long"  "HUGEINT"
  MapFloat               "float"               "REAL"
  MapDouble              "double"              "LONGREAL"
  MapLongDouble          "long double"         "LONGDOUBLE"
  MapPointer             "void *"              "SYSTEM.PTR"
  MapEnum                "enum ..."            "LONGINT"
  MapVoid                "void"                "C_VOID"

Each "MODULE" directive controls how to treat the named module. The base module name comes from the name of the corresponding ".h" file. Options per module include:

• OutputName — Output name for this module (defaults to header name)
• StripPrefix — list of prefixes to be removed from symbol names
• LinkLib, LinkFile, LinkFramework — specifies libraries, files and frameworks to link to this module (OOC-specific directive)
• Prolog — "C" definitions to be processed at the start of this module
• Epilog — "C" definitions to be processed at the end of this module
• Merge — when set to "1", causes all files included by this module to be declared within this module, rather than in separate modules.

Each "VARIANT" directive specifies how to translate particular symbols. As you would know, there are many ways of interpreting C declarations, and the default rules don't always work. For example:

  f(char * arg);

could be:

  PROCEDURE f (arg : POINTER TO ARRAY OF CHAR);
  PROCEDURE f (arg : ARRAY OF CHAR);
  PROCEDURE f (VAR arg : ARRAY OF CHAR);
  PROCEDURE f (VAR arg : CHAR);

So VARIANT directives allow you to place particular interpretations on the "C" declarations. Normally, you can see some specific patterns, but it varies from API to API.

The format of variants is a form of designator. The designators are composed of:

• strings — which match the names of globally declared objects
• [n] — which matches item <n> in a compound type or parameter list
• ^ — which matches the item referenced by a pointer type
• .symbol — which matches a named item in a type or paramter list

Strings or symbols use OOC's regexp string format. Basically, ".*" matches an string of characters, "$" matches the end of a string, and "[]" matches one of a set of characters.

Examples:

  "gl.*v$".params : ARRAY;

This means any symbol (here, procedure) starting with "gl" and ending with "v" has its "params" parameter interpreted as an array.

  "gl.*Matrix[fd]$"[0] : ARRAY;

This means any symbol starting with "gl" and ending with "Matrixf" or "Matrixd" has its first parameter interpreted as an array.

  "String$" : CSTRING POINTER;

This means that the type "String" is to be interpreted as a POINTER to a C string (in OOC, it assigns the "CSTRING" attribute to the pointer, which means that you can use a string literal or CHAR array for this type).

  "glutInit$".argcp : VAR;

This means that the "argcp" parameter of function "glutInit" is to be treated as a VAR parameter.

  "cvRelease[^D].*$"[0] : VAR;

This means that symbols starting "cvRelease" followed by any character EXCEPT "D" has its first parameter interpreted as a VAR parameter.