NAME
ocs, ors - command-line oriented driver for the Opal Compi-
lation System
SYNOPSIS
ocs [ -top structure command
| -sub name structure{,structure} ]
{ option }
[ target ]
DESCRIPTION
ocs is a command-line oriented driver for the Opal Compila-
tion System. It is used to compile and maintain Opal
software systems. ors is similar in it's functionality, but
also offers version and configuration management. In the
following, when we talk about ocs we are simultaneously
describing the common functionality of both ocs and ors.
target instructs ocs as to what shall be done; it can be
augmented by options specifying how it shall be done. If
target is omitted, the default action is to build the system
in the current directory. If the system is not specified by
the -top or -sub option on the command line, the system
description is retrieved from a file named SysDefs in the
current directory.
ocs always tries to build its target using the minimum
number of steps. Thus, if ocs is called with the same argu-
ments again, nothing will be executed. Only if options
change, or if sources constituting a system are modified,
will subsequent calls to ocs rebuild (parts of) a system.
ocs and ors can actually be used to manage software projects
consisting of arbitrary documents and sources. ocs is based
on GNU make, while ors is based on the shape(1) toolkit.
PROJECT TREES AND SYSTEMS
A project tree under ocs is a directory tree of the file
system. Each node in this tree describes a system. There
are currently 4 kinds of systems:
Opal top-level systems
consist of at least one top-level structure which
exports a top-level command. All structures located in
the system's node which are in the import relation of
the top-level structure are also incorporated.
Opal subsystems
consist of a possibly unrelated collection of Opal
structures which constitutes a software library. This
collection is enriched by all imported structures
located in the subsystem's node.
Opal subsystems with handcoding
This is a specialization of the above, and additionally
supports hand-coded structures, i.e. Opal structures
partially or totally implemented in C.
miscellaneous systems
In the simplest case, a miscellaneous system is just
used for bracketing other nodes in the project tree.
However, it can actually be an arbitrary collection of
documents, in which case you might want to define your
own basic GNU-make or shape maintenance rules. See
DEFINING YOUR OWN KIND OF SYSTEM.
SPECIFYING SYSTEMS FROM THE COMMAND LINE
The straightforward use of ocs is to specify an Opal top-
level or subsystem from the command line:
-top structure command
specifies an Opal top-level system in the current
directory, where structure gives the top-level struc-
ture, and command the top-level command.
-sub system structure{,structure}
specifies an Opal subsystem in the current directory,
where system must be the basename of the directory
node, and structures are incorporated (at least) into
the subsystem.
The following options control how a system specified on the
command-line shall be compiled:
-v[level]
verbose level, see oc(1).
-w[level]
warning level, see oc(1).
-o[kind]
optimization option, see oc(1). We recommend the use of
the switch opt=config instead of this option (see
below).
-d[kind]
debugging option, see oc(1). We recommend the use of
the switch debug=config instead of this option (see
below).
-prop
activate the property language. Each structure is then
constituted by the four parts: signature, external pro-
perties, implementation and internal properties. Empty
property parts are created automatically if needed.
-keep
keep the analyzed intermediate applicative code gen-
erated by the Opal compiler's frontend and the C
sources generated by the Opal compiler's backend. Nor-
mally, compilation from implementation to object files
is performed in one step, and these intermediate files
are deleted.
-s[mode] nodepath
base the specified system on the subsystem located at
nodepath. This option can be repeated. Imported struc-
tures in the import relation of the system are first
looked up in the current node, then in the systems
specified by -s options in the order they appear on the
command line, and finally in the Opal standard library.
Note that for top-level systems even subsystems provid-
ing invisibly imported structures must be specified
with a -s option so the linker can find them. -s
without mode is equivalent to -sdh. mode controls the
type of subsystem and is a combination of:
f The subsystem is frozen. Structures belonging to
it are not considered in recompilation checks. It
is assumed that a structure is provided by a
frozen subsystem if its derived signature export
file is present.
d The subsystem is in development. Structures
belonging to it are considered in recompilation
checks. It is assumed that a structure is provided
by a subsystem in development if its signature
file is present.
p The subsystem contains property parts which shall
be considered in recompilation checks of proper-
ties in the current system. This option only makes
sense if the subsystem under nodepath is compiled
with the -prop option.
h The derived objects of the subsystem are hidden in
a subdirectory nodepath/OCS.
Note that these options, when specified from the command
line, only take effect together with a -top or -sub switch.
However, the same options can be assigned to the variables
GENOPTIONS and GENSUBSYS in a system description file (see
below).
SPECIFYING SYSTEMS WITH A DESCRIPTION FILE
The options -top and -sub trigger nothing more then the
automatic generation of a trivial system description file
named SysDefs.structure-command or SysDefs.system. You can
rename this file SysDefs and edit it by hand. You can also
create a symbolic link SysDefs -> SysDefs.structure-command,
in which case the call ocs -top structure command ...
updates the system description and repeated calls without a
system specification on the command line use the latest
updates.
There is a template file for each of the four system kinds,
found under /usr/ocs/lib/om/tmpls and named SysDefs.{top,
sub, subhc, misc}.tmpl. For larger software projects, in
particular if they are based on ors, we recommend the use if
these templates instead of editing an automatically gen-
erated description file.
In the following, the basic variables of a system descrip-
tion file are given, where each variable is marked with the
system kind it is used for and as required or optional.
SYSKIND (all) (optional)
specifies the system kind (one of top, sub, subhc or
misc). Defaults to top.
NODENAME (all) (optional)
defines the name of the system. For Opal top-level sys-
tems, this can be the name of the top-level command.
For Opal subsystems, this must be the basename of the
nodepath. For miscellaneous systems, it can be any rea-
sonable name. If not given, this variable defaults to
opalnode.
SUBNODES (all) (optional)
defines the direct subdnodes of this node. If you
create a bracketing node from the SysDefs.misc.tmpl
template, you usually have to define only this variable
and the variable NODENAME.
TOPSTRUCT (top) (required)
defines the name of the top-level structure.
TOPCOM (top) (required)
defines the name of the top-level command.
STRUCTS (sub) (required)
defines the structures incorporated in an Opal subsys-
tem.
NORMSTRUCTS (subhc) (required)
defines the structures in a subsystem with hand-coding
which are completely implemented in Opal.
FOREIGNSTRUCTS (subhc) (required)
defines the structures in a subsystem with hand-coding
which are partially implemented in Opal.
OPAL_LIBS (all) (optional)
defines the standard Opal libraries to be referenced by
this system. The value of this variable is usually set
up by referencing predefined variables which denote
standard library packages of the installation. For
example, setting OPAL_LIBS = ${OPAL_WIN} ${OPAL_BASE}
specifies the inclusion of the window as well as the
Opal basic library. The set of packages available
depends on the installation (normally OPAL_WIN
OPAL_READLINE OPAL_TCL OPAL_TK OPAL_BASE).
GENOPTIONS (top/sub/subhc) (optional)
defines the options used for generating the building
rules for this system. All options described in SPECI-
FYING SYSTEMS FROM THE COMMAND LINE can be assigned to
this variable, except the -s option.
GENSUBSYS (top/sub/subhc) (optional)
defines the subsystems this system is based on by a
sequence of -s options. The variable application $(GEN-
STDSYS) should be put at the end of this sequence; it
refers to the Opal standard libraries as given by
OPAL_LIBS.
TARGETS AND FURTHER OPTIONS
Many of the targets of ocs recur over the nodes of a project
tree: the action specified by the target is applied either
depth-first or top-down to each node in the tree, choosing
the directory where ocs is invoked as a root.
all (recursive)
build systems in subnodes and then the current system.
This is the default target.
check (recursive)
check property parts of structures. Property parts are
not considered by the all target. This option only
makes sense if the property language is activated (see
-prop).
clean
remove all intermediate compilation products.
cleanall (recursive)
perform clean in current system as well as on all
subnodes.
gen force generating rules for building the current system.
Rules are automatically (re-)generated if the system
specification has been changed or if the import rela-
tion of Opal structures changes.
genall (recursive)
perform gen in current system as well as on all sub-
nodes.
help short description of options and targets.
info give information about the Opal Compilation System
used.
install
install system at places defined by variables from Sys-
Defs file.
pack (recursive)
pack systems components in a compressed tar(1) file.
sendbug
start interactive procedure to send a bug-report.
xhelp
extended description of options and targets.
-force structure.{sign,impl,c}
forces the recompilation of the signature, implementa-
tion, or C code of the structure.
SWITCHES AND PROJECT DEFINITIONS
Switches are used to choose between predefined optimization,
debugging and other configurations. The default setting of
switches and to some extent also the meaning of the switches
is defined by a so-called project definition file. The name
of a project definition file is retrieved from the environ-
ment variable OCSPROJECT; if this variable is not set,
default project definitions are assumed. A template to
create your own project definitions can be found in
/usr/ocs/lib/om/tmpls/ProjectDefs.tmpl.
debug=config
choose debugging configuration, where config is one of:
no no debugging
opal generate code for debugging Opal sources with the
GNU debugger gdb(1). This is a prerequisite for
use of the debug(1) or btrace(1) utilities bundled
with OCS.
c generate code for debugging on the level of the
generated C sources with gdb.
opt=config
choose optimization configuration, where config is one
of:
no no optimization
modest
some rather modest optimizations
medium
medium optimizations which do not introduce recom-
pilation dependencies between structure implemen-
tations.
full full optimizations which do introduce recompila-
tion dependencies between structure implementa-
tions.
profile=config
choose profiling configuration, where config is one of:
no no profiling
gprof
profiling on C code level, using the -gp option.
This feature is, however, rather cumbersome to
use. In the files generated by gprof(1), you will
find numbered symbols of C functions. In order to
relate them with the original Opal symbols, use
the option -keep to save the C sources and search
them for the declarations of the numbered func-
tions. There you will find a comment which denotes
the original symbol.
ocs=config
choose Opal compiler configuration. config is one of:
stdocs
use the standard configuration
expocs
use an experimental configuration with other
libraries, binaries, etc. The definition of this
configuration is usually given in the project
definition file.
var=value
overwrite any make variable. You should know what you
are doing before you use this switch.
SUBSYSTEMS WITH HAND-CODING
See the manual "Handcoder's Guide to the Opal Compilation
System Version 2", written by Wolfgang Grieskamp.
DEFINING YOUR OWN KIND OF SYSTEM
[more to come]
VERSION AND CONFIGURATION MANAGEMENT
[more to come]
TIPS
Another way to remove your intermediate compilation products
is, instead of calling ocs with the clean target, to delete
your OCS subdirectory.
Deleting your OCS/OCSDefs-SysDefs file is also quicker than
calling ocs with the gen target for generating the rules for
building the current system anew. Then you can call ocs to
compile your system.
FILES
./SysDefs
system definition file
./OCS/OcsDefs-SysDefs.{structure-command,system}
generated building rules of ocs
./OCS/OrsDefs-SysDefs.{structure-command,system}
generated building rules of ors
./OCS/structure.{sign,impl,extp,intp}.deps
import dependency files
./OCS/structure.o
object files generated by the C Compiler
./OCS/libsystem.*
library of subsystem
DIAGNOSTICS
The diagnostics come from GNU make(1) or shape(1).
BUGS
Although the change of debugging or optimization levels out-
dates intermediate compilation products, this is not recog-
nized by ocs.
This is particularly evident when you change from a lower
optimization level to a higher one using the switch
opt=full, since this optimization level introduces recompi-
lation dependencies which are not yet reflected in the
building rules. In such cases, the target gen should be used
to enforce the new generation of building rules.
In any case, one should not trust ocs to strictly guarantee
the consistency of the compilation products. One of oc's
known bugs is that it does not detect inconsistency in
intermediate files, so there is no support from this end. If
in doubt, one should use the target clean or cleanall and
then rebuild the project from the beginning; this always
eliminates consistency problems.
AUTHORS
The ocs and ors drivers and the make and shape files were
designed and implemented by Wolfgang Grieskamp. Many valu-
able suggestions came from the members of the Opal group, in
particular from Andreas Fett, and from the Opal user commun-
ity. Several concepts and technical tricks were borrowed
from the shape release management system RMS, bundled with
the shape toolkit.
The Opal Group may be contacted at: Technische Universitaet
Berlin, Institut fuer Kommunikations- und Softwaretechnik,
Sekretariat FR 5-13, Franklinstr. 28/29, 10587 Berlin,
email: opal@cs.tu-berlin.de