NAME
shape_RMS - Introduction to the shapeTools Release Management System
SYNOPSIS
shape rms - show synopsis of shapeTools Release Management System
Functions
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
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.
1)
local development and test in private workspaces with local
versions (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
single 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
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:
A1)
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.
A2)
Define a project group (in /etc/group) and add all project
participants 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
directory.
· 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.
A4)
Set up release and partial release areas by creating the
directories 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
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.
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
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.
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)
afterwards. 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
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
__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
SEE ALSO
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