Provided by: shapetools_1.4pl6-11_i386 bug


       shape_RMS - Introduction to the shapeTools Release Management System


       shape  rms  -  show  synopsis  of  shapeTools Release Management System


       The shapeTools Release Management System (shape_RMS) helps constructing
       and  keeping  track  of  system  releases in complex (multi programmer)
       software development projects. This introductory manual page  gives  an
       overview  of the shape_RMS functionality and helps getting started with
       the release management system.  When  reading  this  introduction,  you
       should  either  be  familiar  with the basics of the shapeTools version
       control system and the shape configuration management program,  or  you
       should  have  the  shapeTools  version  control and the shape(1) manual
       pages at hand.  Complementary to  this  short  reference  manual  page,
       there is a tutorial introduction to the usage of shapeTools, explaining
       how to introduce and use the shape-toolkit's functionality cleverly  in
       a multi programmer project.

       The  cooperation and release management model of a software development
       project is highly dependent on the nature of the project. Factors  like
       the  programming  language  used,  the size of the programmer team, the
       nature  of  the  developed  software,  or  local  preferences  strongly
       influence  this  model.  The  release  management  system  as currently
       implemented, will in most cases not fit all your needs.  Take it  as  a
       prototype  to  begin  with and try to adapt it little by little. In the
       current state, modifying the release management  system  requires  good
       skills  in  Makefile and Shapefile writing and a lot of patience. Think
       twice about every  modification  you  perform  !  Establishing  a  good
       cooperation  and  release model is not as easy as it might look like at
       the first glance.

       The shapeTools RMS imposes a general frame for  the  project  structure
       and the development process within a software development project. This
       frame is necessary for the release management system to determine  it's
       workpieces  and  to be able to systematically document the evolution of
       system configurations. It  helps  the  developer  to  have  all  system
       configuration  and building actions performed automatically, so that he
       can concentrate on his development work, rather  than  code  management

       All  functions  of  the  shapeTools  RMS  are performed by the shape(1)
       program.  This  interprets  a  description  file  (the  Shapefile)  and
       performs  the action associated with a target name given with the shape
       call.  Usually, you may perform a bunch of macro  definitions  together
       with the shape call. These definitions overwrite internal default macro
       settings.  Hence,  calls  of  the  shape_RMS  have  the  general   form
       shape target [MACRONAME=value ...].

       In detail, shape_RMS automatically performs the following actions, each
       of which is described on the referenced manual page.

           System building, installation, and cleaning up (shape_build(1)).

           Generation  of  prereleases  of  subsystems  or  the  whole  system

           Generation   of   releases   of  subsystems  or  the  whole  system

           Constructing patches to existing releases (shape_patch(1)).

           Reinstantiation of old system releases (shape_releas(1))

           Creation  of  shippable  packages  (tar  or   shar   files,   etc.)

           Determination of file dependencies (shape_depend(1)).

       Additionally, it provides

           Standard version selection rules (shape_stdrul(7)).

           A project wide unified variant control raster (shape_stdvar(7)).

           Automatic generation of (pre)release identifications.

           Storing  configuration  management  specific  information with each
           system component.

           Templates for Shapefiles and Makefiles (shape_tmpl(7)).

       The Project Structure

       The general  project  structure  is  hierarchical.  Each  node  in  the
       hierarchy   consists  of  a  number  of  components  and  a  number  of
       subsystems. The top node in the hierarchy represents the whole  system.
       These  three  terms  - node (or system node), component and subsystem -
       will be used throughout all shape_RMS manual pages. A subsystem  and  a
       system  node  are the same thing in principle, consisting of components
       and subsystems. The notions rather distinguish two different points  of

       The  hierarchical  structure is reflected in a UNIX directory tree with
       directories representing nodes and files as system components. Not each
       directory  necessarily  holds  a  whole  system  node. Single nodes may
       spread across multiple directories forming a subtree. The top directory
       of  this  subtree  is  the representant of the node.  Hence, the system
       structure and the directory tree may differ.

       The project structure and it's components is described  by  the  system
       model.  The  system  model  consists  of  a  interwoven  collection  of
       Shapefiles and Makefiles. Each node is equipped with one  Makefile  and
       one  Shapefile  containing  node  specific  system  model  information.
       Additional system model information (such as standard version selection
       rules  or  project wide variant definitions) is maintained in a project
       wide central place and accessed through shape's include facility.

       The functional profile of the system model is reflected  by  predefined
       standard  targets  in  the  system  model files (Shape- and Makefiles).
       These targets are defined either  in  the  individual  (node  specific)
       Shape-  and  Makefiles  or  in  one of the included Shapefile fragments
       maintained project  wide  Shapefile.  A  set  of  standard  macros  and
       implicitly a set of conventions that underlie those macros comprise the
       data interface  between  the  various  modules  of  the  system  model.
       Conformance  with  the necessary underlying conventions and assumptions
       is facilitated by templates for Shape- and Makefiles that are  provided
       to  the  programmers  of  the various system parts (see shape_tmpl(7)).
       Using these templates makes writing  system  model  information  almost

       According  to the templates, the Makefile components contain most macro
       definitions, the usual component dependency definitions and most of the
       explicit  transformation  rules.  The  system of Makefiles is carefully
       designed to be selfcontained enough to be used without  shape(1).  This
       is  necessary to provide a build procedure for compiling and installing
       software system outside the development area (where shape(1) usually is
       not available).

       The  Shapefile  components  contain  information  that  is specifically
       related to shape's special features that are unavailable in make  (e.g.
       version selection, variant handling). The complete system of Shape- and
       Makefiles is free of redundancy, making them easier to  maintain.   The
       Shapefiles,  in  order  to  represent  a complete system model, contain
       include directives to include all significant system model  information
       that  is  stored  in  other  objects,  namely  the centrally maintained
       include files and the Makefiles.

       The  development  work  usually  happens  in  the  developers'  private
       workspaces,  with  the  results  gathered  in  a  central location, the
       projects  source  repository.  The  source  repository  is  a  complete
       directory  tree  (complete in the sense of incorporating each developed
       system node) representing the whole  project.  Private  workspaces  and
       corresponding  subdirectories  in  the  source  repository  are  linked
       together by common AtFS subdirectories  (see  vcintro(1))  holding  all
       saved work results (versions). This mechanis makes files from a private
       workspace get  visible  in  the  source  repository,  as  soon  as  the
       developer  saves  a copy of a file using the shapeTools version control
       system.  Development work may also happen in the source repository.  In
       this  case,  even  the busy version of each workpiece is visible in the
       source repository, which doesn't disturb.

       Each node in the system must contain  a  release  identification  file.
       This  file  is  maintained  automatically  and should never be modified
       manually. It is also to be derived from a given template and contains a
       string  citing  the node name and the actual release number.  With each
       new release, a new  version  of  the  release  identification  file  is
       generated.  In  software  development,  it typically contains a routine
       returning the release  identification  string  mentioned  above.   This
       mechanism automates release identification in software systems.

       Beside  private  workspaces  and  source  repository,  a  project has a
       partial release area and a release area. Both areas are capable to hold
       a  complete  copy  of  the project's source tree as UNIX files (without
       version control).  The partial  release  area  holds  the  most  recent
       (pre-)release  of  each  system  node.  Every  time, a system node gets
       prereleased or released, a copy of  the  involved  source  versions  is
       written   to   the  partial  release  area.   The  release  area  holds
       prereleases and releases of the whole system. It is only filled, when a
       (pre-)release  building procedure is triggered from the top node of the
       source repository.  You find some more details on  this  topic  in  the
       shape_releas(1) manual page.

       The Development Process

       The general development process imposed by the shape release management
       system is described by the following pattern.

           local  development  and  test  in  private  workspaces  with  local
           versions (save)

           individual prepublication of single node system (node prerelease)

           global integration and integration testing (top prerelease)

           incorporation  of  change  requests  from  global  integration into
           single node systems and final publication  of  node  systems  (node

           global release (top release)

           local  introduction of bug fixes in the released system (node patch

           global integration of patches and integration  testing  (top  patch

           local   releases  of  patched  node  system  releases  (node  patch

           generating a global patched release (top patch release).

       Of course, there may be several loops in the  above  list.  First,  the
       construction of node (pre-)releases happens recursively from the leaves
       of the system source tree to the top. Second, several iterations of the
       node/top  prerelease  mechanism will usually be necessary, to come to a
       stable final release.

       Individual development  and  test  happens  in  private  workspaces  of
       individual  developers.  A developer typically uses local busy versions
       and the latest released components of all other system parts  he  needs
       (e.g.  libraries)  in order to test his component. Intermediate results
       of individual development work can be saved into the version base.  The
       corresponding status of emerging versions is saved.

       When the developer thinks that a stable state of development is reached
       or  a  development  transaction  has  been  completed  he  performs  an
       individual  prerelease  of  his  work  results.  Such a release of work
       results consists of saving all  yet  unsaved  busy  versions  into  the
       version base, marking all components of the worked-upon subsystem (i.e.
       all most recent versions) with a common, unique, and well-defined local
       releasename,  and  assigning the status proposed to all these versions.
       These versions, as  residing  in  the  central  source  repository  are
       globally accessible for the system integrator.

       Global  integration  and  integration testing is performed by a special
       user, the integrator. The integrator does typically not do  any  actual
       development  work  himself. In fact the integrator is a conceptual user
       (i.e. a special userId) who acts in the central source  repository  and
       hence has access to all individually released components and subsystems
       of the developed system. Integration testing gathers  all  most  recent
       individual  prereleases  (of  components  and subsystems) and creates a
       prerelease of the developed system. All components that are part  of  a
       prerelease  are  marked  with a common, unique, and well-defined global
       prereleasename, and assigned the version status published.

       The purpose of pre-releasing a system prior to actually  releasing  it,
       is  to  make sure that all components interoperate properly, the system
       installation procedure works properly,  the  new  release  does  build,
       install,  and run correctly on all supported platforms without the risk
       of assigning (and thereby wasting)  the  planned  official  releasename
       prematurely.   During   integration   testing,   no   new  features  or
       enhancements should be allowed to be incorporated into the system.  The
       only  sort  of modification request that shall be processed during this
       phase are bugs in the installation procedure and  portability  problems
       (this includes fixing of bugs that are found during porting).

       Once  the  prerelease  cycle  has produced a stable state of the entire
       system, it can be officially released. The official  release  procedure
       is  similar  to the prerelease procedure, but marks all components with
       the planned official releasename, and assigns the version status frozen
       to them.

       Setting up a Project

       In  the  following you find two checklists. The first one says, what to
       do when initiating a project as project administrator. The  second  one
       helps , connecting to an established project as developer.

       Checklist for initial setup:

           Create  a  (UNIX)  user  to  be  project  owner.  This  should be a
           conceptual user, not a natural one. The home directory of this user
           will be the project home.

           Define  a  project  group  (in  /etc/group)  and  add  all  project
           participants to this group.

           Set up the central project source  repository  in  project  owner's

             ยท    Create development directory

             ยท    Create   bin,  lib  and  include  directory  in  development

             ยท    Install  system  source  tree  with  src  directory  in  the
                  development directory as root.

             ยท    Create  a  directory  named  AtFS  in  each directory of the
                  system source tree.

           Set  up  release  and  partial  release  areas  by   creating   the
           directories release and partial.release in project owner's home.

           Make all previously created directories group-writable.

           Create  a  directory  named  shape  in development/lib and copy the
           shape_RMS templates and include files to that directory.
           These    are    Shapefile.tmpl,    Makefile.tmpl,     Release.tmpl,
           release.c.tmpl, stdconf, stdtargets, stdrules and stdvar.

           Adjust  macro default values in Makefile.tmpl and Shapefile.tmpl in
           development/lib/shape  according   to   local   installation.   The
           shape_tmpl(7) manual page gives you information about the semantics
           of each macro definition. The Makefile template defines

             ยท    base paths for  source  repository,  partial  release  area,
                  release area, and system installation locations.

             ยท    a description of the host system environment.

             ยท    tools and tool options to be used.

             ยท    libraries to be used.

             ยท    default build and installation actions.

           Check  the  stdvar  (project  wide  variant definitions) file.  See
           shape_stdvar(7) for more information about this.

       If  you  stick  strictly  to  the  structuring  and  release  model  as
       implemented  in  the  templates  and  shape  include files given in the
       shapeTools distribution, your job is done now.  Additional  adaptations
       require  changes  to  be  performed manually on the files in shape/lib.
       Before you do this, we recommend reading the shapeTools tutorial first.
       Especially  the Makefile template you should set up very carefully.  As
       most make(1) implementations do not support inclusion of external parts
       into  Makefiles, local Makefiles (derived from the template) hold a lot
       of  information   that   should   better   be   maintained   centrally.
       Modifications  to  the  Makefile  template  made  after  having already
       derived local Makefiles from it, requires  patching  the  changes  into
       each local Makefile. This is a costly and error prone job. We recommend
       to use patch(1) for this, which definitely isn't what you would desire,
       but there is no better solution yet.

           define version selection rules

           implement additional actions in stdtargets or stdconf.

           redefine project wide policies in Makefile.tmpl, Shapefile.tmpl, or

       Don't try to find any additional documentation guiding  through  points
       A9-A11. There is none yet.

       Checklist for developers, when connecting to an existing project:

           Make sure to be member of the project group

           Create private development directory/ies

           Connect  to  the  central  source repository by establishing a link
           named  AtFS  from  your  local   development   directory   to   the
           corresponding  directory  in  the  central  source repository. This
           should either be a symbolic link to the AtFS directory  there,  or,
           on  systems  where  no  symbolic link facility is available, a file
           with the appropriate pathname  as  contents.  The  latter  will  be
           interpreted  by  the shapeTools version control system as surrogate
           for a symbolic link.

           Copy Makefile.tmpl from project_home/lib/shape as Makefile to  your
           development direcory and fill in the necessary macro definitions by
           editing the file. If you already have a Makefile, don't try to  use
           that  further.  You will be much more lucky with a Makefile derived
           from the template.

           Copy Shapefile.tmpl as  Shapefile  to  your  development  direcory.
           Usually, no modifications should be necessary there.

           Copy  one  of  Release.tmpl  or  release.c.tmpl  as  Release, resp.
           release.c to your local directory.

           Create  an  empty  Dependencies  file  and  run  shape  depend  (1)
           afterwards.   Check,  if  your  project  setup  supports  automatic
           generation of the Dependencies file. If not, you have  to  maintain
           it manually.

           Run  shape  rms  (1) to get a synopsis of the functions provided by
           the shapeTools release management system.


       As  the  shape  toolkit  has  an  Attributed  Filesystem   (AtFS,   see
       afintro(3))  as  data  storage  base,  shape_RMS  stores  it's internal
       management information as attributes attached to the system components.
       Attributes  consist  of  name  and  a  list  of  values.  Configuration
       management related attributes are

              Each component version in the system carries a set  of  symbolic
              names  uniquely identifying the (pre-)release(s), it is part of.
              This list may be empty, when a version was never declared to  be
              part  of a (pre-)release.  __SymbolicName__ is an attribute with
              a special meaning throughout all  programs  in  shapeTools.  For
              more information see the -symbolic option of vl(1) and vadm(1).

              Is the name of the node system, the component version belongs to
              as defined in the NODENAME macro in  the  subsystem's  Makefile.
              Only the release number generator file carries this attribute.

              The  unique  name  of  the last generated prerelease or release.
              This attribute gets attached only to  versions  of  the  release
              number  generator file. In fact, it makes sense only at the most
              recent version of the release number generator file.


       Shapefile.tmpl- Template for subsystem specific Shapefiles
       Makefile.tmpl- Template for subsystem specific Makefiles
       stdconf     - standard configuration management tagets
       stdrules    - standard version selection rules
       stdtargets  - common basic targets
       stdvar      - project wide variant raster


       shape_build(1),   shape_depend(1),   shape_patch(1),   shape_releas(1),
       shape_stdrul(7), shape_stdvar(7), shape_tmpl(7)
       Tutorial Introduction to the shape-toolkit


       Andreas Lampen, Tech. Univ. Berlin (

                   Technical University Berlin
                   Computer Science, Secr. FR 5-6
                   Franklinstr. 28/29
                   D-10587 Berlin, Germany