ocs(1)

NAME
ocs, ors — command-line oriented driver for the Opal Compilation System

SYNOPSIS
ocs [ -top structure command
| -sub name structure{,structure} ]
{ option }
[ target ]

DESCRIPTION
ocs is a command-line oriented driver for the Opal Compilation 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 arguments 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 structure, 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 properties, implementation and internal properties. Empty property parts are created automatically if needed.

-keep
    keep the analyzed intermediate applicative code generated by the Opal compiler's frontend and the C sources generated by the Opal compiler's backend. Normally, 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 structures 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 providing 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 properties 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 generated description file. In the following, the basic variables of a system description 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 systems, 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 reasonable 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 subsystem.

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 SPECIFYING 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 $(GENSTDSYS) 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 relation of Opal structures changes.

genall   (recursive)
    perform gen in current system as well as on all subnodes.

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 SysDefs 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, implementation, 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 environment 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 recompilation dependencies between structure implementations.

    full
        full optimizations which do introduce recompilation dependencies between structure implementations.

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 functions. 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 outdates intermediate compilation products, this is not recognized 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 recompilation 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 valuable suggestions came from the members of the Opal group, in particular from Andreas Fett, and from the Opal user community. 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