Provided by:
shapetools_1.4pl6-9_i386 
NAME
shape_RMS — Introduction to the shapeTools Release Management System
SYNOPSIS
shape rms - show synopsis of shapeTools Release Management System Func‐
tions
DESCRIPTION
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 influ‐
ence this model. The release management system as currently imple‐
mented, will in most cases not fit all your needs. Take it as a proto‐
type 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 con‐
figuration and building actions performed automatically, so that he can
concentrate on his development work, rather than code management activ‐
ities.
All functions of the shapeTools RMS are performed by the shape(1) pro‐
gram. 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 set‐
tings. Hence, calls of the shape_RMS have the general form shape tar‐
get [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 hierar‐
chy 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 subsys‐
tems. 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 Shape‐
files 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 cen‐
tral 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 implic‐
itly 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 facili‐
tated 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 direc‐
tory tree (complete in the sense of incorporating each developed system
node) representing the whole project. Private workspaces and corre‐
sponding 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. Develop‐
ment 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 man‐
ually. 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 gener‐
ated. In software development, it typically contains a routine return‐
ing the release identification string mentioned above. This mechanism
automates release identification in software systems.
Beside private workspaces and source repository, a project has a par‐
tial 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 ver‐
sion control). The partial release area holds the most recent
(pre-)release of each system node. Every time, a system node gets pre‐
released 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 reposi‐
tory. 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.
1)
local development and test in private workspaces with local ver‐
sions (save)
2)
individual prepublication of single node system (node prerelease)
3)
global integration and integration testing (top prerelease)
4)
incorporation of change requests from global integration into sin‐
gle node systems and final publication of node systems (node
release)
5)
global release (top release)
6)
local introduction of bug fixes in the released system (node patch
prerelease).
7)
global integration of patches and integration testing (top patch
prerelease).
8)
local releases of patched node system releases (node patch
release).
9)
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 indi‐
vidual 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 individ‐
ual 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 release‐
name, 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 enhance‐
ments 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:
A1)
Create a (UNIX) user to be project owner. This should be a concep‐
tual user, not a natural one. The home directory of this user will
be the project home.
A2)
Define a project group (in /etc/group) and add all project partici‐
pants to this group.
A3)
Set up the central project source repository in project owner’s
home.
· Create development directory
· Create bin, lib and include directory in development direc‐
tory.
· Install system source tree with src directory in the devel‐
opment directory as root.
· Create a directory named AtFS in each directory of the sys‐
tem source tree.
A4)
Set up release and partial release areas by creating the directo‐
ries release and partial.release in project owner’s home.
A5)
Make all previously created directories group-writable.
A6)
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.
A7)
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.
A8)
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 imple‐
mented 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. Espe‐
cially 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 Make‐
files 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.
A9)
define version selection rules
A10)
implement additional actions in stdtargets or stdconf.
A11)
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:
D1)
Make sure to be member of the project group
D2)
Create private development directory/ies
D3)
Connect to the central source repository by establishing a link
named AtFS from your local development directory to the correspond‐
ing 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.
D4)
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.
D5)
Copy Shapefile.tmpl as Shapefile to your development direcory.
Usually, no modifications should be necessary there.
D6)
Copy one of Release.tmpl or release.c.tmpl as Release, resp.
release.c to your local directory.
D7)
Create an empty Dependencies file and run shape depend (1) after‐
wards. Check, if your project setup supports automatic generation
of the Dependencies file. If not, you have to maintain it manually.
D8)
Run shape rms (1) to get a synopsis of the functions provided by
the shapeTools release management system.
ATTRIBUTES
As the shape toolkit has an Attributed Filesystem (AtFS, see afin‐
tro(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
__SymbolicName__
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).
nodename
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.
lastrelease
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.
FILES
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
AUTHOR
Andreas Lampen, Tech. Univ. Berlin (Andreas.Lampen@cs.tu-berlin.de)
Technical University Berlin
Computer Science, Secr. FR 5-6
Franklinstr. 28/29
D-10587 Berlin, Germany