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