BlackBox Framework Wiki - User contributions [en]

BlackBox Component Builder

2020-10-07T14:49:47Z

Bernhard: /* External links */ dead link to Stan Warford's book revitalized, dead link to OmiSys redirected to archive.org

'''BlackBox Component Builder''' is an integrated development environment optimized for component-based software development. It consists of development tools, a library of reusable components, a framework that simplifies the development of robust custom components and applications, and a run-time environment for components.

In BlackBox, the development of applications and their components is done in [[Component Pascal]]. This language is a descendant of Pascal, Modula-2, and Oberon. It provides modern features such as objects, full type safety, components (in the form of modules), dynamic linking of components, and garbage collection. The entire BlackBox Component Builder is written in Component Pascal: all library components, all development tools including the Component Pascal compiler, and even the low-level run-time system with its garbage collector.

As its name implies, BlackBox Component Builder supports blackbox abstractions and reuse as opposed to whitebox as defined in <ref>Szyperski, Clemens. ''Component Software''. Addison Wesley, 2002, p. 40f and Chap.7 (p. 109ff)</ref>. It started 1993 as Oberon/F<ref>http://www.edm2.com/0608/oberon.html</ref><ref>D. Pountain, The Oberon/F System, ''BYTE'' 20(1), Jan. 1995.</ref> and was renamed to BlackBox Component Builder with Release 1.3 end of the 1990s. BlackBox Component Builder went open source with Release 1.5 mid-2004.

The design principles of the BlackBox Component Framework are based on Clemens Szyperski's research, published in his PhD thesis <ref>Szyperski, Clemens. ''Insight ETHOS: On Object Orientation in Operating Systems''. PhD thesis: Swiss Federal Institute of Technology (ETH Zurich), Dissertation No 9884. vdf Hochschulverlag AG an der ETH Zürich, Zurich, Switzerland, ISBN 3-7281-1948-2, 1992, [http://e-collection.library.ethz.ch/eserv/eth:38713/eth-38713-02.pdf PDF in ETHZ E-Collection]</ref><ref>Clemens Szyperski's [https://groups.google.com/forum/#!search/Clemens$20Szyperski/comp.lang.oberon/M-y1bJwEYE8/VIiedaFfIfIJ post in c.l.o.]</ref>.

== Downloads ==

BlackBox is available from the BlackBox Framework Center [http://blackboxframework.org/index.php?cID=goto-download-page,en-us Download page].

Also see [[BlackBox_Component_Builder_1.7|Some notes about migration from 1.6 to 1.7]]

== References ==

<references></references>

== External links ==
*[https://web.archive.org/web/20191218082105/http://www.oberon.ch/blackbox.html Official site, last known version from Archive.org]
*[https://www.springer.com/gp/book/9783528058289 An introductory text using BlackBox: Stan Warford - Computing Fundamentals] see also: [https://www.cslab.pepperdine.edu/warford/ComputingFundamentals/ CS-Lab at Pepperdine] and [https://blackboxframework.org/books/warford_2002.pdf a local copy]
*[http://www.zinnamturm.eu/ Tools and Utilities for BlackBox]

H2O

2019-11-05T16:26:37Z

Bernhard: /* Linux */ removed /usr/bin from calling oo2c and added sudo (did not work on a recent Debian 9 otherwise)

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

= Intro and Credits =

H2O (Header to Oberon) is a tool for creating Oberon interface modules from C-Header files for foreign libraries. It has been created by Stewart Greenhill around 2001 for use with the Optimizing Oberon Compiler OOC/oo2c, which in turn has been created by Michael van Acken end of the 1990. Ability to create interface modules for Component Pascal has been implemented by Bernhard Treutwein end of 2006 and fed back into the cvs tree at sourceforge by Stewart Greenhill in March, 2007.

= Installation =

The H2O sources are distributed with [[oo2c]] compiler. The oo2c compiler is/must be used for building H2O.

== Linux ==

1. Download binary distribution and install it: https://sourceforge.net/projects/ooc/files/ooc2/2.1.11/

./configure
sudo make install

2. Download last sources from: https://github.com/Spirit-of-Oberon/oo2c

git clone https://github.com/Spirit-of-Oberon/oo2c

3. Compile last version of '''oo2c''' from repository:

cd oo2c
make cvsclean
./configure
. ENV
make $OOC_DEV_ROOT/oo2crc-install.xml
oo2c -M --config oo2crc-install.xml oo2c
sudo make install BOOTSTRAP_COMPILER=bin/oo2c

4. Compilation of H2O

oo2c -M src/TestH2O.Mod
sudo cp bin/TestH2O /usr/bin/TestH2O

== Windows ==

H2O can be run on windows with [http://www.cygwin.com/ Cygwin].

The example of built distribution you can find [http://forum.oberoncore.ru/viewtopic.php?f=34&t=661&p=86819&hilit=H2O#p68484 here].

[http://forum.oberoncore.ru/download/file.php?id=2847 Download]

= Usage =

There are a couple of modes in which H2O can work.
* With arguments "-cp" it is producing Component Pascal output.
* 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 ==

There are few C files ready for trial usage in the folder with [[oo2c]] sources.

cd tests/h2o
TestH2O misc/test.c

The results will be two files: '''mod.Mod''' and '''test.Mod'''.

{| class="wikitable" style="width: 100%; text-valign: top"
! Name
! C (sources)
! Oberon-2 (output)
|- valign="top"
| width="6%" | mod.h
| width="47%" |
typedef int T;
typedef int * pT;
| width="47%" |
MODULE mod [ INTERFACE "C" ];

IMPORT SYSTEM;
TYPE
T* = LONGINT;
pT* = POINTER TO ARRAY OF LONGINT;
END mod.
|- valign="top"
| test.c
|
#include "mod.h"

typedef T t1;
pT pt1;

int i1;
short int i2;
long int i3;
unsigned int i4;
unsigned short int i5;
unsigned long int i6;

unsigned u;
short s;
long l;
char c;

int * pi;
int ** ppi;

int f1(int x, int y);
int * f2(int x, int y);
int (* f3)(int x, int y);
void f4 (void);
void f5 (int, int, ...);

int ai [];
int * aai1 [3][3];
int (* aai2) [3][3];

struct A {
int a:1;
int b;
} sA1;

struct A sA2;
struct A * psA;

struct A * (* next)(struct A * p);

enum B { a=1, b, c } e1;

typedef unsigned long long I;

I i7;
volatile I i8;
volatile I i9, * const i10;
int a[sizeof(int)];
|
MODULE test [ INTERFACE "C" ];

IMPORT SYSTEM, mod;
CONST
(* Constants occurring in enumeration 'B' *)
a* = 1;
b* = 2;
c* = 3;
TYPE
A_tag* = RECORD
a* : LONGINT;
b* : LONGINT;
END;
B_tag* = LONGINT (* enumerated type *);
AutoPtrA_tag* = POINTER TO A_tag;
t1* = mod.T;
I* = HUGEINT;
VAR
pt1* : mod.pT;
i1* : LONGINT;
i2* : INTEGER;
i3* : LONGINT;
i4* : LONGINT;
i5* : INTEGER;
i6* : LONGINT;
u* : LONGINT;
s* : INTEGER;
l* : LONGINT;
c* : CHAR;
pi* : POINTER TO ARRAY OF LONGINT;
ppi* : POINTER TO ARRAY OF POINTER TO ARRAY OF LONGINT;
f3* : PROCEDURE(x : LONGINT; y : LONGINT) : LONGINT;
ai* : ARRAY OF LONGINT;
aai1* : ARRAY 3 OF ARRAY 3 OF POINTER TO ARRAY OF LONGINT;
aai2* : POINTER TO ARRAY 3 OF ARRAY 3 OF LONGINT;
sA1* : A_tag;
sA2* : A_tag;
psA* : POINTER TO A_tag;
next* : PROCEDURE(p : AutoPtrA_tag) : AutoPtrA_tag;
e1* : B_tag;
i7* : I;
i8* : I;
i9* : I;
i10* : POINTER TO ARRAY OF I;
a* : ARRAY 4 OF LONGINT;
PROCEDURE f1* (x : LONGINT; y : LONGINT) : LONGINT;
PROCEDURE f2* (x : LONGINT; y : LONGINT) : mod.pT;
PROCEDURE f4* ();
PROCEDURE f5* (p0 : LONGINT; p1 : LONGINT);
END test.
|}

== Processing with outer H2O directive ==

Directive file have structure:

H2O {
... translation options here ...
}
#include "topLevelFile"

If we want to translate '''test.c''' from previous example we would make '''test.h2o''' that looks like this:

H2O {
OPTIONS {
MapChar = "SHORTCHAR";
MapShort = "SHORTINT";
MapLong = "INTEGER";
MapLongLong = "LONGINT";
MapFloat = "SHORTREAL";
MapDouble = "REAL";
MapPointer = "ANYPTR";
}

MODULE "test" {
LinkLib = "libtest.so";
}

MODULE "mod" {
LinkLib = "libmod.so";
}
}
#include "test.c"

To initiate the translation you would do:

TestH2O misc/test.h2o

For making of Component Pascal import modules we can use key '''-cp'''.

TestH2O -cp misc/test.h2o

{| class="wikitable" style="width: 100%; text-valign: top"
! Name
! C (sources)
! Component Pascal (output)
|- valign="top"
| width="6%" | mod.h
| width="47%" |
typedef int T;
typedef int * pT;
| width="47%" |
MODULE mod [ "libmod.so" ];

IMPORT SYSTEM;
TYPE
T* = INTEGER;
pT* = POINTER TO ARRAY [untagged] OF INTEGER;
END mod.
|- valign="top"
| test.c
|
#include "mod.h"

typedef T t1;
pT pt1;

int i1;
short int i2;
long int i3;
unsigned int i4;
unsigned short int i5;
unsigned long int i6;

unsigned u;
short s;
long l;
char c;

int * pi;
int ** ppi;

int f1(int x, int y);
int * f2(int x, int y);
int (* f3)(int x, int y);
void f4 (void);
void f5 (int, int, ...);

int ai [];
int * aai1 [3][3];
int (* aai2) [3][3];

struct A {
int a:1;
int b;
} sA1;

struct A sA2;
struct A * psA;

struct A * (* next)(struct A * p);

enum B { a=1, b, c } e1;

typedef unsigned long long I;

I i7;
volatile I i8;
volatile I i9, * const i10;
int a[sizeof(int)];
|
MODULE test [ "libtest.so" ];

IMPORT SYSTEM, mod;
CONST
(* Constants occurring in enumeration 'B' *)
a* = 1;
b* = 2;
c* = 3;
TYPE
A_tag* = RECORD [untagged]
a* : INTEGER;
b* : INTEGER;
END;
B_tag* = INTEGER (* enumerated type *);
AutoPtrA_tag* = POINTER TO A_tag;
t1* = mod.T;
I* = HUGEINT;
VAR
pt1* : mod.pT;
i1* : INTEGER;
i2* : SHORTINT;
i3* : INTEGER;
i4* : INTEGER;
i5* : INTEGER;
i6* : INTEGER;
u* : INTEGER;
s* : SHORTINT;
l* : INTEGER;
c* : SHORTCHAR;
pi* : POINTER TO ARRAY [untagged] OF INTEGER;
ppi* : POINTER TO ARRAY [untagged] OF
POINTER TO ARRAY [untagged] OF INTEGER;
f3* : PROCEDURE(x : INTEGER; y : INTEGER) : INTEGER;
ai* : ARRAY [untagged] OF INTEGER;
aai1* : ARRAY [untagged] 3 OF ARRAY [untagged] 3 OF
POINTER TO ARRAY [untagged] OF INTEGER;
aai2* : POINTER TO ARRAY [untagged] 3 OF
ARRAY [untagged] 3 OF INTEGER;
sA1* : A_tag;
sA2* : A_tag;
psA* : POINTER TO A_tag;
next* : PROCEDURE(p : AutoPtrA_tag) : AutoPtrA_tag;
e1* : B_tag;
i7* : I;
i8* : I;
i9* : I;
i10* : POINTER TO ARRAY [untagged] OF I;
a* : ARRAY [untagged] 4 OF INTEGER;
PROCEDURE f1* (x : INTEGER; y : INTEGER) : INTEGER;
PROCEDURE f2* (x : INTEGER; y : INTEGER) : mod.pT;
PROCEDURE f4* ();
PROCEDURE f5* (p0 : INTEGER; p1 : INTEGER);
END test.
|}

For included modules, the behavior 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.

== Complex examples ==

[[Media:Interfaces.tar.gz]]

H2O

2015-03-31T08:11:45Z

Bernhard: /* Installation */ Intro & Credits added

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

= Intro and Credits =

H2O (Header to Oberon) is a tool fro creating Oberon interface modules from C-Header files for foreign libraries. It has been created by Stewart Greenhill around 2001 for use with the Optiizing Oberon Compiler OOC/oo2c, which in turn has been created by Michael van Acken end of the 1990. Ability to create interface modules for Component Pascal has been implemented by Bernhard Treutwein end of 2006 and fed back into the cvs tree at sourceforge by Stewart Greenhill in March, 2007.

= Installation =

The H2O sources are distributed with [[oo2c]] compiler. The oo2c compiler is/must be used for building H2O.

== 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
sudo cp bin/TestH2O /usr/bin/TestH2O

== Windows ==

H2O can be run on windows with [http://www.cygwin.com/ Cygwin].

The example of built distribution you can find [http://forum.oberoncore.ru/viewtopic.php?f=34&t=661&p=86819&hilit=H2O#p68484 here].

[http://forum.oberoncore.ru/download/file.php?id=2847 Download]

= Usage =

There are a couple of modes in which H2O 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 ==

There are few C files ready for trial usage in the folder with [[oo2c]] sources.

cd tests/h2o
TestH2O misc/test.c

The results will be two files: '''mod.Mod''' and '''test.Mod'''.

{| class="wikitable" style="width: 100%; text-valign: top"
! Name
! C (sources)
! Oberon-2 (output)
|- valign="top"
| width="6%" | mod.h
| width="47%" |
typedef int T;
typedef int * pT;
| width="47%" |
MODULE mod [ INTERFACE "C" ];

IMPORT SYSTEM;
TYPE
T* = LONGINT;
pT* = POINTER TO ARRAY OF LONGINT;
END mod.
|- valign="top"
| test.c
|
#include "mod.h"

typedef T t1;
pT pt1;

int i1;
short int i2;
long int i3;
unsigned int i4;
unsigned short int i5;
unsigned long int i6;

unsigned u;
short s;
long l;
char c;

int * pi;
int ** ppi;

int f1(int x, int y);
int * f2(int x, int y);
int (* f3)(int x, int y);
void f4 (void);
void f5 (int, int, ...);

int ai [];
int * aai1 [3][3];
int (* aai2) [3][3];

struct A {
int a:1;
int b;
} sA1;

struct A sA2;
struct A * psA;

struct A * (* next)(struct A * p);

enum B { a=1, b, c } e1;

typedef unsigned long long I;

I i7;
volatile I i8;
volatile I i9, * const i10;
int a[sizeof(int)];
|
MODULE test [ INTERFACE "C" ];

IMPORT SYSTEM, mod;
CONST
(* Constants occurring in enumeration 'B' *)
a* = 1;
b* = 2;
c* = 3;
TYPE
A_tag* = RECORD
a* : LONGINT;
b* : LONGINT;
END;
B_tag* = LONGINT (* enumerated type *);
AutoPtrA_tag* = POINTER TO A_tag;
t1* = mod.T;
I* = HUGEINT;
VAR
pt1* : mod.pT;
i1* : LONGINT;
i2* : INTEGER;
i3* : LONGINT;
i4* : LONGINT;
i5* : INTEGER;
i6* : LONGINT;
u* : LONGINT;
s* : INTEGER;
l* : LONGINT;
c* : CHAR;
pi* : POINTER TO ARRAY OF LONGINT;
ppi* : POINTER TO ARRAY OF POINTER TO ARRAY OF LONGINT;
f3* : PROCEDURE(x : LONGINT; y : LONGINT) : LONGINT;
ai* : ARRAY OF LONGINT;
aai1* : ARRAY 3 OF ARRAY 3 OF POINTER TO ARRAY OF LONGINT;
aai2* : POINTER TO ARRAY 3 OF ARRAY 3 OF LONGINT;
sA1* : A_tag;
sA2* : A_tag;
psA* : POINTER TO A_tag;
next* : PROCEDURE(p : AutoPtrA_tag) : AutoPtrA_tag;
e1* : B_tag;
i7* : I;
i8* : I;
i9* : I;
i10* : POINTER TO ARRAY OF I;
a* : ARRAY 4 OF LONGINT;
PROCEDURE f1* (x : LONGINT; y : LONGINT) : LONGINT;
PROCEDURE f2* (x : LONGINT; y : LONGINT) : mod.pT;
PROCEDURE f4* ();
PROCEDURE f5* (p0 : LONGINT; p1 : LONGINT);
END test.
|}

== Processing with outer H2O directive ==

Directive file have structure:

H2O {
... translation options here ...
}
#include "topLevelFile"

If we want to translate '''test.c''' from previous example we would make '''test.h2o''' that looks like this:

H2O {
OPTIONS {
MapChar = "SHORTCHAR";
MapShort = "SHORTINT";
MapLong = "INTEGER";
MapLongLong = "LONGINT";
MapFloat = "SHORTREAL";
MapDouble = "REAL";
MapPointer = "ANYPTR";
}

MODULE "test" {
LinkLib = "libtest.so";
}

MODULE "mod" {
LinkLib = "libmod.so";
}
}
#include "test.c"

To initiate the translation you would do:

TestH2O misc/test.h2o

For making of Component Pascal import modules we can use key '''-cp'''.

TestH2O -cp misc/test.h2o

{| class="wikitable" style="width: 100%; text-valign: top"
! Name
! C (sources)
! Component Pascal (output)
|- valign="top"
| width="6%" | mod.h
| width="47%" |
typedef int T;
typedef int * pT;
| width="47%" |
MODULE mod [ "libmod.so" ];

IMPORT SYSTEM;
TYPE
T* = INTEGER;
pT* = POINTER TO ARRAY [untagged] OF INTEGER;
END mod.
|- valign="top"
| test.c
|
#include "mod.h"

typedef T t1;
pT pt1;

int i1;
short int i2;
long int i3;
unsigned int i4;
unsigned short int i5;
unsigned long int i6;

unsigned u;
short s;
long l;
char c;

int * pi;
int ** ppi;

int f1(int x, int y);
int * f2(int x, int y);
int (* f3)(int x, int y);
void f4 (void);
void f5 (int, int, ...);

int ai [];
int * aai1 [3][3];
int (* aai2) [3][3];

struct A {
int a:1;
int b;
} sA1;

struct A sA2;
struct A * psA;

struct A * (* next)(struct A * p);

enum B { a=1, b, c } e1;

typedef unsigned long long I;

I i7;
volatile I i8;
volatile I i9, * const i10;
int a[sizeof(int)];
|
MODULE test [ "libtest.so" ];

IMPORT SYSTEM, mod;
CONST
(* Constants occurring in enumeration 'B' *)
a* = 1;
b* = 2;
c* = 3;
TYPE
A_tag* = RECORD [untagged]
a* : INTEGER;
b* : INTEGER;
END;
B_tag* = INTEGER (* enumerated type *);
AutoPtrA_tag* = POINTER TO A_tag;
t1* = mod.T;
I* = HUGEINT;
VAR
pt1* : mod.pT;
i1* : INTEGER;
i2* : SHORTINT;
i3* : INTEGER;
i4* : INTEGER;
i5* : INTEGER;
i6* : INTEGER;
u* : INTEGER;
s* : SHORTINT;
l* : INTEGER;
c* : SHORTCHAR;
pi* : POINTER TO ARRAY [untagged] OF INTEGER;
ppi* : POINTER TO ARRAY [untagged] OF
POINTER TO ARRAY [untagged] OF INTEGER;
f3* : PROCEDURE(x : INTEGER; y : INTEGER) : INTEGER;
ai* : ARRAY [untagged] OF INTEGER;
aai1* : ARRAY [untagged] 3 OF ARRAY [untagged] 3 OF
POINTER TO ARRAY [untagged] OF INTEGER;
aai2* : POINTER TO ARRAY [untagged] 3 OF
ARRAY [untagged] 3 OF INTEGER;
sA1* : A_tag;
sA2* : A_tag;
psA* : POINTER TO A_tag;
next* : PROCEDURE(p : AutoPtrA_tag) : AutoPtrA_tag;
e1* : B_tag;
i7* : I;
i8* : I;
i9* : I;
i10* : POINTER TO ARRAY [untagged] OF I;
a* : ARRAY [untagged] 4 OF INTEGER;
PROCEDURE f1* (x : INTEGER; y : INTEGER) : INTEGER;
PROCEDURE f2* (x : INTEGER; y : INTEGER) : mod.pT;
PROCEDURE f4* ();
PROCEDURE f5* (p0 : INTEGER; p1 : INTEGER);
END test.
|}

For included modules, the behavior 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.

== Complex examples ==

[[Media:Interfaces.tar.gz]]

BlackBox Component Builder

2014-10-23T16:32:23Z

Bernhard: Link to Insight ETHOS added

'''BlackBox Component Builder''' is an integrated development environment optimized for component-based software development. It consists of development tools, a library of reusable components, a framework that simplifies the development of robust custom components and applications, and a run-time environment for components.

In BlackBox, the development of applications and their components is done in [[Component Pascal]]. This language is a descendant of Pascal, Modula-2, and Oberon. It provides modern features such as objects, full type safety, components (in the form of modules), dynamic linking of components, and garbage collection. The entire BlackBox Component Builder is written in Component Pascal: all library components, all development tools including the Component Pascal compiler, and even the low-level run-time system with its garbage collector.

As its name implies, BlackBox Component Builder supports blackbox abstractions and reuse as opposed to whitebox as defined in.<ref>Szyperski, Clemens. ''Component Software''. Addison Wesley, 2002, p. 40f and Chap.7 (p. 109ff)</ref> It started 1993 as Oberon/F<ref>http://www.edm2.com/0608/oberon.html</ref><ref>D. Pountain, The Oberon/F System, ''BYTE'' 20(1), Jan. 1995.</ref> and was renamed to BlackBox Component Builder with Release 1.3 end of the 1990s. BlackBox Component Builder went open source with Release 1.5 mid-2004.

The design principles of the BlackBox Component Framework are based on Clemens Szyperski's research, published in his PhD thesis.<ref>Szyperski, Clemens. ''Insight ETHOS: On Object Orientation in Operating Systems''. PhD thesis: Swiss Federal Institute of Technology (ETH Zurich), Dissertation No 9884. vdf Hochschulverlag AG an der ETH Zürich, Zurich, Switzerland, ISBN 3-7281-1948-2, 1992, [http://e-collection.library.ethz.ch/eserv/eth:38713/eth-38713-02.pdf PDF in ETHZ E-Collection]</ref><ref>Clemens Szyperski's [https://groups.google.com/forum/#!search/Clemens$20Szyperski/comp.lang.oberon/M-y1bJwEYE8/VIiedaFfIfIJ post in c.l.o.]</ref>

== References ==

<references></references>

== External links ==
*[http://www.oberon.ch/BlackBox.html Official site]
*[http://userserv.reutlingen-university.de/~hug/buch/cf.htm An introductory text using BlackBox: Stan Warford - Computing Fundamentals]
*[http://www.zinnamturm.eu/ Tools and Utilities for BlackBox]

Center

2014-09-15T11:00:34Z

Bernhard: /* Looking beyond our noses */ typo Nicklaus -> Niklaus

The "BlackBox Center" is a non-profit voluntary organization dedicated to maintaining the vision and values of the BlackBox/Component Pascal software developed by Oberon microsystems Inc. (Zurich Switzerland). Today the Center is the ''de facto'' standard for BlackBox developers, users, and project managers. The members spearhead projects that, through a collaborative and meritocratic development process, deliver enterprise-quality software attractive to large user communities. We operate under [http://opensource.org/licenses/BSD-2-Clause BSD 2-clause license] to deploy products for business and individuals.

==Mission==

To provide software for the public good, based on the [[Oberon Spirit]]. We do this by keeping alive, adapting, and developing [[Component Pascal]], [[BlackBox Framework]] and [[BlackBox Component Builder]] starting with the [http://www.oberon.ch/blackbox.html last official release (v 1.6)] provided by [[Oberon microsystems AG]] (the "software") and growing and maintaining an international user community.

''The Blackbox Center provides and ensures guidelines and policies to keep the community centered around the mission described above. We are not the sole developers of the software, nor the only providers of the software, but we provide a clearing house to centralize efforts.''

==Values==
As a community we strive to:
* cooperate for the common good;
* make things as simple as possible but not simpler;
* use the idea of component building and let everybody add what they are good at to form something more than the sum of the parts;
* work democratically and meritocratically;
* be good citizens.

==How is the BlackBox Center and its projects governed?==

Members decide issues by vote, with 80% constituting a quorum. Every vote has the option "none of the above". Such a vote is counted for the quorum, but it does not take a side.

Votes are called by the [[Chair]] only (who is elected by vote on a yearly basis), whose responsibility it is:

* to start a voting thread after sufficient prior discussion;
* to make sure that each member is informed about pending votes (at least about important questions);
* to make sure that each member voted (Robert: "But only 80% need to vote");
* to close the voting thread.

New members can be added by vote.

Members can apply for leaving the Center and stay in touch in the special board group 'exCenter' with posting privileges and without voting rights.

Contributions to the software come from the wider community, and the Center members decide what to add, and when, in compliance with our mission, our vision and our values.

==Visions of development for the software==

The following sections illustrate possible projects and priorities for the future of BlackBox. These visions will mature and evolve in the light of experience and input from the wider user community.

===Keeping alive===

* All parts of the software are documented both in source and in an overview document (no "this module is internal" documentations!)
* All OS function calls are checked regularly and if necessary changed so that the software does not use deprecated functions.
* Known bugs are fixed
* There are regular "working releases" and once a year or so there are "major releases", to make sure that the user can rely on the stability of the software.

=== Adapting===
BlackBox is now 10 years old, and the world has changed. We need to adapt.

* Providing a 64-bit version of the software
* Adapting to the changed native look and feel of the OS
* Internationalization of user documentation and user interface
* Implementation of additional GUI elements provided by the OS as part of the standard distribution

===Developing===
Source-Code compatible versions with local look-and-feel for
* Mac OS
* Linux
* JVM
* Dalvik VM
* .NET
* Raspbian…

==Looking beyond our noses==

* When Niklaus Wirth designed the Oberon System, he discouraged multi-tasking on single processor systems, because it only adds complexity (i.e. it is against the values). Over 20 years later, most of our systems are multi-processor systems. Is the current handling of “Actions” still the best practice, or should be implement – in the spirit of Oberon – multi-threading, and if so, how? For instance, we are faced with the problem that the run time system freezes when you keep a mouse key pressed. Is this really necessary, and how can we solve this in the Oberon Spirit?

* Are there new paradigms of user interaction in software development that we could (and probably should) integrate, such as MS IntelliSense? Is it inherently against the Oberon Spirit, or are there ways to provide similar functionality in keeping the Spirit?

==Center tasks==

* to make first version with all known bug fixes
* to maintain stable versions of [[BlackBox Component Builder]]
* provide it's distribution and promotion.

To maintain means:
* regularly (period?) publish new versions of the BlackBox Component Builder;
* support the international BlackBox open-source community;
* adapt the BlackBox Component Builder to modern challenges.

== Links ==

* [http://blackboxframework.org/ Main website]
* [http://forum.blackboxframework.org Center Forum]
* [http://github.com/BlackBoxCenter Public repository and issues tracker]
* [http://redmine.blackboxframework.org/projects/blackbox-component-builder Center project tracker]