.TH oo2c 1
.UC 5
.SH NAME
oo2c \- Oberon-2 compiler
.SH SYNOPSIS
.B oo2c
.RI [ options ]
.IR <module> ...
.br
.B oo2c
.RI ( --make | -M )
.RI [ options ]
.I <module>
.br
.B oo2c
.I --make-lib
.RI [ options ]
.I <module>
.br
.B oo2c
.I --install-lib
.RI [ options ]
.I <module>
.br
.B oo2c
.I --make-file
.RI [ options ]
.I <module>
.SH NOTE
This document is a subset of corresponding chapter of the 
.B OOC Reference 
.BR Manual .
It covers the basic functionality of
.BR oo2c .
For a complete overview of
.BR oo2c 's
features, the reader is referred to the reference manual (see below).
.SH DESCRIPTION
The default mode of
.B 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
.I PATHS
sections of the initialization files (see below).

The option
.I --make 
(or 
.I -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 
.I 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
.I 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 
.I --makefile 
.IR <file-name> ,
a so-called 
.I 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 
.B make
utility to build an executable program for the main module from
existing C code.  

The 
.I --make-lib
function of 
.B oo2c
turns a set of modules into a library.  Just like 
.IR --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 
.IR --install-lib .  
This command takes the same arguments as
.IR --make-lib , 
and invokes 
.B libtool
to install the library in the target directory.
.SH OPTIONS
.TP
.B --optimize, -O
Try harder to optimize the intermediate code.  Also, add the contents
of 
.I coptflags
to invocations of the C compiler.
.TP
.B --no-rtc
Remove all run-time checks from the generated code.
.TP
.B --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 
.IR stdout .
.TP
.B --all, -A
When used with
.IR --make ,
force the compiler to recompile every module, from scratch, that is
part of the program and whose source code is available.
.TP
.B --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 
.IR --opt .)
.TP
.B --options <string>
Add the given string to the initialization file section
.IR OPTIONS .
.TP
.B --pragmas <string>
Add the given string to the initialization file section 
.IR PRAGMAS .
.TP
.B --define <string>
Define a new variable for the initialization file section
.IR PRAGMAS .
.TP
.B --cc <string>
The name of the C compiler.
.TP
.B --cflags <string>
These flags are added to the C compiler's argument list when
translating a C file into an object file.
.TP
.B --coptflags <string>
Like 
.I --cflags
these flags are added to the argument list, but only if the option
.I --optimize
is set.
.TP
.B --ldflags <string>
The value of this string is appended to the link command.
.TP
.B --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.
.TP
.B --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 
.IR --make-lib )
and library installation (with
.IR --install-lib ).
.TP
.B --libtool-cmd <string>
Set the name of the
.B libtool
script, which is used with
.I --make-lib
and
.IR --install-lib .
.TP
.B --install-cmd <string>
Set the command prefix to be used when installing files with
.IR --install-lib .
.TP
.B --libtool-link
When used with
.IR --make ,
invoke
.I libtool
to do final linking.  This option option is provided for linking
against libraries that have not yet been moved to their final
destination.
.TP
.B --no-build
When used with
.IR --make ,
stop make process to after the C code has been written, but before the
C compiler is invoked to create the object files.
.TP
.B --oc-rules
When used with
.IR --make-file ,
write rules that will run 
.B oo2c
from the 
.I Makefile 
and produce, one at a time, the necessary C files from their Oberon-2
code.
.TP
.B --config <file>
Use given file name for the primary initialization file.  An empty
name disables parsing of the default initialization file.
.TP
.B --include-config <file>
Include the given initialization file in addition to the default
initialization file.
.TP
.B --write-config
Write current configuration data to
.I stdout
and exit.
.TP
.B --version
Write compiler version and exit.
.SH INITIALIZATION FILES
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
.IR END .
Only the sections 
.I PATHS
and
.I 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, 
.B oo2c
searches the directories defined in the 
.I PATHS
section of the initialization file.  The
.I 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 
.I 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 
.IR 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 
.IR foo ,
then the files 
.I <dir>/RCS/foo,v
and 
.I <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 
.I .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), 
.B 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 
.IR ~/.oo2crc:

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

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

Additional control over the configuration data is allowed by the
special initialization file section
.IR 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 
.I INCLUDE
section is simply 
.I INCLUDE <file> 
.IR END ,
which causes the entire contents of 
.I <file>
to be processed as if those contents had appeared in place of the
.I INCLUDE
statement.

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

  INCLUDE ~/.oo2crc END

The file 
.I .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 
.I INCLUDE
statement.
.SH ERROR MESSAGES
Any errors encountered while parsing a source file 
.I foo.Mod
are written to
.I 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
.BR ooef .
.SH ENVIRONMENT
.I OOC_HOME
holds the name of the primary initialization file.
.SH FILES
.nf
.ta \w'file.c, file.dXXX'u
~/.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.
.Sp
.fi

In the directory 
.IR <prefix>/lib/oo2c :

.nf
.ta \w'file.c, file.dXXX'u
oo2crc          Primary initialization file.
Errors.short    List of error messages.
lib/__*.[hc]    Auxiliary files of the compiler.
.Sp
.fi
.SH DIAGNOSTICS
The exit status is non zero, if, and only if, an error occurred during
compilation.
.SH SEE ALSO
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://www.uni-kl.de/OOC/.  It is available in info, Postscript, HTML,
and texinfo format.
.SH AUTHOR
Michael van Acken <acken@informatik.uni-kl.de>