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