Provided by: shapetools_1.4pl6-14_amd64 bug


       shape_RMS - Introduction to the shapeTools Release Management System


       shape rms - show synopsis of shapeTools Release Management System Functions


       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 activities.

       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 (shape_releas(1)).

           Generation of releases of subsystems or the whole system (shape_releas(1)).

           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.)  (shape_tar(1)).

           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 view.

       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 trivial.

       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 release)

           global release (top release)

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

           global integration of patches and integration testing (top patch prerelease).

           local releases of patched node system releases (node patch release).

           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 home.

             ·    Create development directory

             ·    Create bin, lib and include directory in development directory.

             ·    Install system source tree with src directory in the development  directory  as

             ·    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 stdconf.

       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

           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_tar(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