oo2c - Oberon-2 compiler

oo2c [options] <module>...

oo2c (--make|-M) [options] <module>

oo2c --make-lib [options] <module>

oo2c --install-lib [options] <module>

oo2c --make-file [options] <module>

This document is a subset of corresponding chapter of the OOC Reference Manual. It covers the basic functionality of oo2c. For a complete overview of oo2c's features, the reader is referred to the reference manual (see below).

The default mode of oo2c assumes that all arguments are names of source files and tries to compile them to ANSI-C code. Compiling a single module in this way can be used to do a check syntax on a module, or selectively force recompilation of modules. If a file name argument has no directory part, the compiler searches in the directories listed in the PATHS sections of the initialization files (see below).

The option --make (or -M for short) turns a set of Oberon-2 modules into an executable program. The single argument can be either the name of a module or a module's file name. Again, the compiler searches the directories in PATHS if the file name has no directory part. The compiler inspects all modules imported directly or indirectly by the given main module, and generates new C code for any modules that have not been compiled yet, or whose C code is not up to date anymore. Then, all necessary object files are generated by invoking the C compiler. The final step links object files and libraries into an executable program with the same name as the main module. Note that, unlike the Oberon System, there is no notion of commands (i.e., parameterless exported procedures, which can be activated directly by the user). Instead, the module body of the main module specifies the program's execution sequence.

With --makefile <file-name>, a so-called Makefile is written to the specified file. This option takes a single argument: the name of a module or a file name. The generated file contains the rules necessary to use the make utility to build an executable program for the main module from existing C code.

The --make-lib function of oo2c turns a set of modules into a library. Just like --make, it takes a single argument: the name of a module or a file name. The main module must look like this:

MODULE FooLib [LIBRARY "foo" "1:2:3"; INTERFACE "C"]; IMPORT ...; END FooLib.

To install a newly created library use --install-lib. This command takes the same arguments as --make-lib, and invokes libtool to install the library in the target directory.

--optimize, -O

Try harder to optimize the intermediate code. Also, add the contents of coptflags to invocations of the C compiler.

--no-rtc

Remove all run-time checks from the generated code.

--verbose, -v

Be more verbose during compilation. In particular, the name of the file currently compiled, changes in symbol files, and all external program invocations are written to stdout.

--warnings, -w

Include warnings in error listings.

--all, -A

When used with --make, force the compiler to recompile every module, from scratch, that is part of the program and whose source code is available.

--opt <string>

Set the sequence of code transformations. Every character in the given string represents a transformation. (To get the entire list of available choices use some illegal selection, like --opt.)

--options <string>

Add the given string to the initialization file section OPTIONS.

--pragmas <string>

Add the given string to the initialization file section PRAGMAS.

--define <string>

Define a new variable for the initialization file section PRAGMAS.

--cc <string>

The name of the C compiler.

--cflags <string>

These flags are added to the C compiler's argument list when translating a C file into an object file.

--coptflags <string>

Like --cflags these flags are added to the argument list, but only if the option --optimize is set.

--ldflags <string>

The value of this string is appended to the link command.

--gcflags <string>

This specifies the linker command that adds the garbage collector code to the executable program. Garbage collection is disabled by setting the variable to the empty string. All modules of a program must be compiled with the same setting.

--lib-path <string>

Specify the directory where the libraries should be installed. Note that the same destination directory has to be used for both library creation (with --make-lib) and library installation (with --install-lib).

--libtool-cmd <string>

Set the name of the libtool script, which is used with --make-lib and --install-lib.

--install-cmd <string>

Set the command prefix to be used when installing files with --install-lib.

--libtool-link

When used with --make, invoke libtool to do final linking. This option option is provided for linking against libraries that have not yet been moved to their final destination.

--no-build

When used with --make, stop make process to after the C code has been written, but before the C compiler is invoked to create the object files.

--oc-rules

When used with --make-file, write rules that will run oo2c from the Makefile and produce, one at a time, the necessary C files from their Oberon-2 code.

--config <file>

Use given file name for the primary initialization file. An empty name disables parsing of the default initialization file.

--include-config <file>

Include the given initialization file in addition to the default initialization file.

--write-config

Write current configuration data to stdout and exit.

--version

Write compiler version and exit.

An initialization file is composed of sections; each section is introduced by its keyword, followed by data in a section-dependent formant, and terminated by the keyword END. Only the sections PATHS and INCLUDE are explained in this man page. For information about the other sections refer to the OOC Reference Manual.

When looking for a particular file, oo2c searches the directories defined in the PATHS section of the initialization file. The PATHS section lists a number of wildcard strings, which are used to determine which directories should be scanned for matching file names.

The syntax of the PATHS section is defined like this:

paths_section = "PATHS" {source_pattern} "END". source_pattern = "GET" wildcard_list "FROM" path {path}. wildcard_list = wildcard {[","] wildcard}. wildcard = name | string. path = ( name | string ) [";"].

A wildcard may contain the special characters `*' and `?'. A `*' matches an arbitrary number of characters (including none at all), whereas `?' matches exactly one character. Writing `[RCS]' after a wildcard signals that a file matching the pattern might be under control of the Revision Control System (RCS), and should be checked out if no working file exists.

Any non-absolute path (i.e., all path strings not starting with a `/' or a `~') is interpreted relative to the directory the compiler, or tool, was started from. Whenever a program is invoked from a different directory, these relative path names will then resolve differently. If the intention is to always use the exact same directories for all invocations, all paths in the initialization file must be absolute.

When looking for a particular file, say foo, the list of patterns is scanned from top to bottom. For every match, the list of directories is tested from left to right. The first directory that contains a file with the requested name is used. If the file cannot be found in any of these directories, the simple file name is used. If RCS support is enabled for foo, then the files <dir>/RCS/foo,v and <dir>/foo,v are also searched for in these directories.

Note that, if a module name is passed as argument from the command line, the standard suffix .Mod is appended, and the resulting file name is searched for using the above mechanism. Also, if a file name that contains a directory part is used, no searching is done at all; the file name is used exactly as specified.

When trying to decide where to place a generated file (e.g., one of the numerous intermediate files with C code), oo2c uses a simplified version of the mechanism described above. It looks for the first matching wildcard, and uses the first directory in that list; the newly created file is written to this directory. It does not matter if the file exists beforehand or not, or if a file of the same name exists in any of the other listed directories.

The default setting is to have the compiler place generated files in the current directory. To have these files put away in other directories the user should put something like the following lines into his personal initialization file ~/.oo2crc:

PATHS GET *.Sym, *.Lib FROM sym GET *.c, *.d, *.h, *.o FROM obj END

This places all symbol files in directory sym, all generated C code in directory obj, and executables in the current directory. The subdirectories sym and obj have to exist in the current directory, otherwise the compiler will abort with an error message. Note that with the default setup ~/.oo2crc merely extends the system wide path configuration, it does not replace it.

Additional control over the configuration data is allowed by the special initialization file section INCLUDE. It is a simple, but efficient, way to add personalized or project specific configuration details to the global default settings. The format of an INCLUDE section is simply INCLUDE <file> END, which causes the entire contents of <file> to be processed as if those contents had appeared in place of the INCLUDE statement.

For example, the default initialization file contains the following statement to include a user's personalized settings:

INCLUDE ~/.oo2crc END

The file .oo2crc from the user's home directory is then parsed just as though it were part of the initialization file at the place of the INCLUDE statement.

Any errors encountered while parsing a source file foo.Mod are written to stdout like this:

In file foo.Mod: <pos>: <num> <error message>

The integer <pos> refers to the position of the error in the file (the first character has position 0). The integer <num> is the error number. The rest of the line is a plain text error message. The message format can be changed with the filter program ooef.

OOC_HOME holds the name of the primary initialization file.

~/.oo2crc       Personal initialization file.
file.Mod        Source code of Oberon-2 Module.
file.Sym        Symbol file with public interface of module.
file.Lib        Library description.
file.h          Header file with C level interface of module.
file.c, file.d  Generated ANSI-C code for module.
file.o          Object file derived from file.d and file.c.

In the directory <prefix>/lib/oo2c:

oo2crc          Primary initialization file.
Errors.short    List of error messages.
lib/__*.[hc]    Auxiliary files of the compiler.

The exit status is non zero, if, and only if, an error occurred during compilation.

oob(1), ooef(1), oowhereis(1)

Additional topics covered by the OOC Reference Manual: installing oo2c, use of initialization files, interfacing to C code, creating static and shared libraries from Oberon-2 modules, and using the Oberon-2 mode for Emacs.

The OOC Reference Manual can be obtained from the OOC Home Page at http://ooc.sourceforge.net/. It is available in info, Postscript, HTML, and texinfo format.

Michael van Acken <acken@informatik.uni-kl.de>