oo2c(1)

NAME
oo2c - Oberon-2 compiler

SYNOPSIS
oo2c [options] <module>...
oo2c (--make|-M) [options] <module>
oo2c --uses <ext-ident> [options] <module>...
oo2c --build-package [options] <package>
oo2c --install-package [options] <package>
oo2c --uninstall-package [options] <package>
oo2c --build-pkg-doc [options] <package>
oo2c --package-installed [options] <package>
oo2c --list-packages [options]
oo2c --update-repository [options]

NOTE
This document is a subset of corresponding chapter of the OOC2 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).

DESCRIPTION
The default mode of oo2c assumes that all arguments are names of modules or source files and tries to compile them to C code. Compiling a single module in this way can be used to do a syntax check on a module. Module names are resolved by searching in the repositories listed in the corresponding section of the compiler configuration. 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. The compiler searches the configured repositories to resolve module names. It 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 (that is, 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. The command --uses lists using occurences of the given declaration in the source code. The modules given on the command line and all their imported modules are searched. The declaration is identified by a module name followed by an arbitrary long sequence of names, separated by dots, like module.procedure.var. With --build-package, --install-package, and --uninstall-package packages are compiled, installed, and uninstalled. A package is a set of libraries, executables, resource files, option definitions, and pragma definitions. Its content is described by the file pkginfo.xml in the package's top-level directory. The option --build-pkg-doc creates HTML documentation for all modules used by the libraries and executables of the given package. After successful completion, the files can be found under <repository>/oocdoc/html. --package-installed tests if a given package is installed. If the package name appears in the repository's manifest file <oocdir>/pkginfo.xml, then the exit code is 0. Otherwise, the program exits with a non-zero code. --list-packages writes a list of all packages to stdout, one package per line. The first word in the line is the package name. The command --update-repository updates the file <oocdir>/pkginfo.xml from on the meta information of all packages that have been installed into the repository <oocdir>. This is also done automatically after every --install-package and --uninstall-package.

OPTIONS

--repository <directory>, -r <directory>
    Add a directory to the list of repositories used by the compiler. A repository has a fixed directory structure, with subdirectory src/ holding source files, sym/, obj/, and bin/ storing symbol files, C header and code files, object files and binaries produced by the compiler, and so on. Repositories are searched from right to left, with command line arguments taking precedence of entries in the compiler's configuration file. By default, the current working directory is part of the list of repositories.

--no-rtc
    Remove all run-time checks and ASSERT statements from the generated code. Typically, this produces a significant speedup.

--all, -A
    Force compilation of all modules whose source code is available. By default, only modules with missing or inconsistent derived files are compiled.

--verbose, -v
    If set, then the compiler logs the names of read and written files to stdout, as well as any shell commands run by it.

--warnings, -w
    Currently no effect.

--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.

--cppflags <string>
    Flags targeted at the C compiler's preprocessor.

--ldflags <string>
    The value of this string is appended to the link command.

--libs <string>
    The value of this string is added to the very end of the link command.

--libtool <string>
    The name of the libtool binary. If the value is no, the the compiler does not produce static or shared libraries at all.

--libdir <string>
    Specify the directory where libraries should be installed. Note that the same destination directory has to be used for both library creation (with --build-package) and library installation (with --install-package).

--bindir <string>
    Binaries are installed into this directory by --install-package.

--oocdir <string>
    All module data produced by the compiler, like symbol files, header files, or package meta data, are copied by --install-package into this directory. By default, this is the directory used when installing the compiler, typically <prefix>/lib/oo2c.

--install <string>

--install-program <string>

--install-data <string>

--uninstall <string>
    Commands to install directories, binaries, and data files, and the command used to remove them with --uninstall-package.

--xsltproc <string>
    Name of the XSLT processor. It produces the HTML version of the documentation of library modules. The value no disables HTML documentation.

--config <file>
    Use given file name for the configuration file.

--error-style <string>
    Selects the format of emitted error messages. The default setting is file:line:column, which generates messages like "src/Foo.Mod:2:15: Some horrible error". The setting char-pos selects the error format of oo2c v1, "4212: 123 Some horrible error", where the first number is the character position in the file. The file name itself is given in a separate line.

CONFIGURATION FILES
The compilers configuration is determined by the file <prefix>/lib/oo2c/oo2crc.xml and by the pkginfo.xml files of any repositories listed there. oo2crc.xml provides default value for options and pragma variables, and also defines a default list of repositories: the compiler's installation directory and the current working directory. The name of the configuration file can be overridden by setting the environment variable OO2CRC. Within a pkginfo.xml file, the root element package and its child elements describe the meta data of a package. Among other things, the provide a package name, a version, and optional lists of executables, libraries, and resource files. The compiler uses this information to take appropriate action when executing a --build-package or --install-package command. The file may also include package specific definitions of options and pragma variables. This information is incorporated automatically by the compiler and extends the settings from oo2crc.xml. For examples of pkginfo.xml, please refer to ./pkginfo.xml and ./lib/pkginfo.xml.in in oo2c's distribution tar ball.

ERROR MESSAGES
Any errors encountered while parsing a source file foo.Mod are written to stdout like this:
  src/foo.Mod:<line>:<column>: <error message> The integer <line> refers to a line in the file (the first line is 1), and <column> to a column within that line (the first column being 1). The rest of the line is a plain text error message. The message format can be changed with the option --error-style, and in connection with --error-style char-pos, the filter program ooef can also be used.

ENVIRONMENT
OO2CRC overrides the name of the configuration file. OOC_REPS is a list of repository paths, separated by colons (:). Empty paths are ignored.

FILES
file.Mod        Source code of an Oberon-2 module.
file.Sym        Symbol file with public interface of the module.
file.Doc        Documentation strings from the public interface.
file.oh         Header file with C level interface.
file.c, file.d  Generated ANSI-C code.
file.o          Object file derived from file.d and file.c.

In the directory <prefix>/lib/oo2c:
oo2crc.xml      Configuration file with defaults for options, pragmas,
                and repositories.
src/__*.h       Auxiliary files of the compiler.

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

SEE ALSO
ooef(1), oowhereis(1) Additional topics covered by the OOC2 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. Please note: At the time of writing, only the OOC Reference Manual for version 1 is available.

AUTHOR
Michael van Acken <mva@users.sf.net>