Manual page for OC(1)

oc - an Orca compiler

SYNOPSIS

oc [option] sources
oc_check [option] sources

INTRODUCTION

This document provides an introduction to the use of the oc driver for the Orca compiler. Its task is to call the Orca compiler, which translates Orca modules/objects into ANSI C modules, then call an ANSI C compiler to process the Orca compiler output, and then call a link editor to combine the object files and the Orca runtime system into a binary.

USAGE

Users are expected to use the oc command through one of the shell scripts oc_bcast-rpc(1), oc_panda(1), oc_unixproc(1), or oc_sinproc(1). These shell scripts set the various variables and options right for the runtime system chosen.

FILENAMES

Usually, an Orca program consists of several specification and implementation modules. Specification modules must reside in files with names having a ".spf" extension. Implementation modules must reside in files having a ".imp" extension. The name of the file in which a specification module is stored must be the same as the module-name, apart from the extension.

DESCRIPTION

There are two commands: oc, which tries to run the full compilation pipeline including linking, and oc_check, which only runs the Orca compiler, producing a C module. The usual mode of working is that the user writes an Orca program, consisting of a number of specification and implementation modules/objects. The user may then run oc_check on each implementation module/object, and then run oc on the implementation module containing the Orca main process (called OrcaMain), or he may just do the latter. Oc will find the modules/objects used if they reside in the current directory or any of the other source directories given with the -S option, and recompile them if necessary.

The input is taken from sources. In addition, oc also examines import lists in an attempt to collect the complete sources of the Orca program. However, it only looks for source files in the current directory. Source files from other directories must be specified explicitly.

Option is a, possibly empty, sequence of the following combinations:

-Sdirname: append dirname to the list of directories where sources are looked for. By default, this is only the current directory.
-Idirname: append dirname to the list of directories where specifications are looked for. When the compiler needs a specification, it is first searched for in the current directory, and then in the directories given to it by the -I flag in the order given, and then in the directory containing the specifications for the standard Orca library, currently $OC_HOME/$OC_LIBNAM/std.
-LIN: don't generate code for file name and line number administration.
-L: generate line directives in the C code.
-CHK: don't generate runtime checks (for instance for array references, graph references).
-v: verbose flag. Print commands before they are executed.
-w: suppress warning messages from the Orca compiler.
-values: Only print the values of the variables described below.
-p, -pg: profiling. This flag is passed on to the C compiler, and a profiling version of the runtime system is selected.
-trc: tracing. Use a tracing version of the runtime system. This feature is only available for the Panda runtime system. See "Panda trace package".
-c: compile, but do not link.
-u: do not complain about functions mentioned in the specification but not present in the implementation. This may be useful for functions that are written in another language.
--flag: pass the debug flag --flag on to the Orca compiler.
-o filename: produce the resulting binary in filename, instead of a.out.

name=value: Oc and oc_check have a number of variables with default values which can be changed through the environment or on the command line. See the "environment" paragraph for the names and default values of these variables.

Unrecognized options (starting with a '-') are passed to the C compiler.

Each Orca module compiles into a separate C module (usually a .c and a .h file, but for generic modules a .gc and a .gh file). It is also possible to just compile an Orca specification, but this is only needed when the implementation is written in another language. In this case, the relocatable object file (or the C file) of this implementation must be passed on to oc explicitly.

ENVIRONMENT

There are several variables in the driver which can be changed by the user. Values in the environment override default values, and values given on the command line override both default values and environment values. The variables are:

OC_HOME: This variable indicates the path to the root of the Orca tree.
OC_LIBNAM: This variable indicates the path from $OC_HOME to the libraries. Its value usually is "lib".
OC_SPECIAL: This variable indicates a special version of the libraries, for instance "optimized" or "profiling".
OC_MACH: This variable contains a <machine>_<operating system> combination, for instance "sparc_sunos4", and indicates what kind of system the compilation is for.
OC_RTSNAM: This variable indicates the name of the Orca runtime system, for instance "panda" or "unixproc".
OC_COMP: This variable indicates the path to the Orca compiler.
OC_FLAGS: This variable indicates the flags passed to the Orca compiler.
OC_INCLUDES: This variable indicates a list of -I options for the include directories for Orca.
OC_RTSINCLUDES: This variable indicates a list of -I options for the include directories of the Orca runtime system. These are required for the C compilation of the resulting C programs.
OC_CCOMP: This variable indicates the C compiler used. This must be an ANSI C compiler.
OC_CFLAGS: This variable indicated the flags passed to the C compiler.
OC_LD: This variable indicate the linker used.
OC_LDFLAGS: This variable indicates the flags passed to the linker.
OC_STARTOFF: This variable indicated the runtime start-off used.
OC_LIBS: This variable indicates a list of runtime libraries.

The default values for these environment variables are suitable for running the Orca program with the unixproc RTS.

STANDARD MODULES

The specifications for the standard modules can be found in the directory $OC_HOME/$OC_LIBNAM/std.

DIAGNOSTICS

All warning and error messages are written on standard error output.

REMARKS

To avoid cluttering up the working directory, oc uses its own working directory, .oc_driver, and other file names starting with a '.'.

This is a product under development. Please send comments and bug-reports to ceriel@cs.vu.nl.

Markup created by unroff 1.0, November 05, 1998.