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