
This is README for release 1.3 of shapeTools.

It contains general information on the shape toolkit and an overview
of its parts. At the end of this file you find a section with special
information for using shapeTools on a System V machine. The file
"INSTALL" helps you installing the toolkit on your machine. The file
"PORTING" gives hints for solving portability problems and describes
the procedure for porting the toolkit to new operating system
platforms. Please read the file "LICENSE" before installing and using
the shape toolkit on your computer.

If you have any questions, hints or bug reports, you may contact us
via:
	Tech. Univ. Berlin		Tel: +49-30-314-73230
	"shape"				Fax: +49-30-314-73488
 	Secr. FR 5-6 			E-mail: shape@cs.tu-berlin.de
 	Franklinstr. 28/29
 	D-1000 Berlin 10, Germany

We set up a mailing list for announcing new releases and patches and
for discussion of shape specific topics. If you want to be kept
informed about the evolution of the toolkit, you should subscribe to
the mailing list. The list is managed automatically. You can subscribe
by sending a mail to 
	"listserv@tubvm.cs.tu-berlin.de"
with the contents
	"sub shape-l <your full name>".

Submissions to the mailing list are to be sent to
	"shape-l@tubvm.cs.tu-berlin.de".


General information:
====================

The shape toolkit (we also refer to it as "shapeTools") is a
collection of programs to support software configuration management in
an UNIX environment. It consists of a set of version and attribute
control commands, and a configuration interpreter and build tool
("shape"). The toolkit is integrated on top of AtFS (Attributed File
System), a storage system supporting multiple versions of files and
associating an arbitrary number of application defined attributes of
the form "name=value" with each version. AtFS comes as a function
library that is meant as an extension to the UNIX file system. It does
this without the need for kernel modifications and without imposing
any restrictions to existing file system applications. ShapeTools is
designed to live meaningfully together with any other UNIX tool
operating on regular files. This distribution also contains a
prototype for a comprehensive change control and release management
system designed to manage the evolution of system releases in multi
programmer software development efforts.

The shape version and attribute control system ("shape_VC")
-----------------------------------------------------------

The shapeTools version and attribute control control system is a set
of UNIX(1) commands. Shape_VC offers version control functionality
and direct access to user definable attributes associated with each
version. In detail, shape_VC comprises
 - storage and retrieval of multiple revisions of files.
 - a built in status model for revisions.
   (States: busy, saved, proposed, published, accessed, frozen)
 - documentation of change histories.
 - synchronization of concurrent updates to a history.
 - symbolic names as version number aliases.
 - a basic network user concept.
 - full (read and write) access to user definable attributes.

The last point in the list, the attribute control, deserves some more
attention. As the underlying storage system (AtFS) supports
associating any number of attributes with each version, shape_VC uses 
this mechanism to allow the user to attach his/her own management
information in form of attributes to stored revisions. The attribute
mechanism supports
 - genuine attributes		(<name> = <static_value>)
     where the attribute value is given statically.
 - execution attributes		(<name> = !<executable_program>)
     where the attribute value is built dynamically by executing a given
     program or shell script and catching it's output.
 - reference attributes		(<name> = @<filename>)
     where the contents of a file is taken as attribute value.

The toolkit character of the system allows to use it directly by
calling the commands from the shell, or to build a customized
environment on top of it. As an example, we built an alternate user
interface to the system using GNU-Emacs. This lead to a much more
comprehensive, integrated user interface. The corresponding emacs lisp
code is contained in the distribution.

The Attributed File System (AtFS)
---------------------------------
	[ Formerly, we used the acronym AFS which often lead to
	  confusion with CMU's Andrew File System. ]

AtFS is the base abstraction of the whole toolkit. It provides uniform
access to immutable revisions of files stored in special archive files
(in a directory named "AtFS"), and mutable regular UNIX files.
Consequently, the AtFS based toolkit lives peacefully (and
meaningfully!) together with standard file system applications
(editors, compilers, formatters etc.). Cooperative work within
projects is supported by a build-in status model, controlling
visibility of version objects, and locking, a primitive form of "long
transactions" for synchronizing concurrent updates. The general
concept of application defined attributes provides a basis for storing
management information with versions and passing this information
between individual tools. This mechanism is useful for building
integrated environments from a set of unrelated tools. AtFS also
supports derived object management, i.e. it maintains a cache of
multiple versions of compiled object-files (e.g. compiled c-files with
different compile switches).

People with sophisticated requirements may also add their own
applications on basis of AtFS to the toolkit. There is a fully
documented C-language interface to AtFS, on top of which all the
toolkit programs are built.

The configuration management and build program ("shape_CM")
-----------------------------------------------------------

The shape_CM component consists of the program "shape", performing
 - identification of system components,
 - component version selection,
 - variant control,
 - driving transformations (eg. compilations) and
 - recording configurations (for later rebuild) 
for the software system to be built.

Shape_CM uses, similar to make, a description file named "Shapefile".
In fact shape_CM is upward compatible to Make in that it can properly
handle conventional Makefiles. The Shapefile however, uses 
Makefile-style dependencies as (versionless) abstract system model and
employs version selection rules to dynamically bind particular versions
to the names listed in the system model. The version selection
mechanism exploits AtFS' ability to maintain any number of arbitrary
attributes for objects in the object base. On special request, shape
records an identified configuration in a configuration identification
document (CID) which has the form of a completely bound Shapefile (all
object-instances are explicit).

One of the most useful features of shape is its support of various
variant administration techniques. Shape makes no assumptions about
the semantics of the variant notion other than having alternative
(conceptually equivalent) instances of the same concept ("module").
Despite the particular semantics of a certain variant-concept, there
is a small number of techniques to physically handle variants. These
techniques are what shape supports. Most commonly used techniques are:
 - equally named files in different directories
 - one source file representing multiple variants that are
   extracted by a preprocessor using different preprocessor switches 
   (e.g. conditional compilation)
 - one source file processed by different tools or different
   tool versions/variants (e.g. cross compilation, different coders)
 - combinations of the above.
Shape includes a variant definition facility that allows very flexible
and convenient handling of all of the above variant administration
techniques.

The shape release management system (shape_RMS)
-----------------------------------------------

Enclosed in the distribution is a prototype for a configuration
management environment to be used for constructing system releases in
complex (multi programmer) software development projects. Using this
environment does not require any experience in writing Shapefiles
(resp. Makefiles). The environment consists of templates for a
Shapefile and a Makefiles and of a library of Shapefile fragments for
project wide use.

The shape_RMS supports:
 - a fully automatic global release building mechanism with automatic
   release number generation.
 - automatic generation of prereleases as systematic preparation of
   releases.
 - construction of subsystem releases and prereleases
 - system building and installation by shape *and* make
 - standard version selection rules
 - a project wide unified variant raster
 - built in standard functions for cleaning up, generating tar or shar
   files, determine file dependencies etc.

Each directory where a part of the managed system is developed, has to
be equipped with a Shapefile and a Makefile derived from the given
templates. In the normal case, the derivation just requires setting a
few macros. Shape- and Makefile are kept redundancy free, the Makefile 
is inserted in the Shapefile via an "include" mechanism. The
management of a Shapefile *and* a Makefile (although the Shapefile
alone should be enough) implies, that certain system building
functions can also be performed by "make". This is especially
important for producing self contained releases (buildable and
installable on shape-less computer systems by use of make) from the
projects development area (managed by shape).

Further reading
---------------

You can find additional information on the shape toolkit in the manual
pages and the tutorial enclosed in the distribution. The tutorial
shall help you to learn to use the toolkit in your development work.
If you want to read more about the concepts of shape and its object
base, we refer to:

    Axel Mahler, Andreas Lampen
    "An Integrated Toolset for Engineering Software Configurations"
    Proceedings of the ACM SOFSOFT/SIGPLAN Software Engineering
    Symposium on Practical Software Engineering Environments
    Boston MA, 28-30 November 1988
    pp. 191-200 SIGSOFT SE Notes V13-No5, SIGPLAN NOTICES V24-No2,
    
    Andreas Lampen, Axel Mahler
    "An Object Base for Attributed Software Objects"
    Proceedings of the EUUG Autumn '88 Conference
    Cascais (Portugal) 3-7 October 1988
    pp. 95-105, European UNIX User Group, London 1988

    Ulrich Pralle
    "Driving the Software Release Process with Shape"
    Proceedings of the EUUG Autumn '90 Conference
    Nice (France) October 1990
    pp. 27-38, European UNIX User Group, London 1988


This distribution contains the following parts:
===============================================
	+Patchlevel  -- The current Patchlevel
	INSTALL	     -- Information how to build and install the
			toolkit on your machine.
	LICENSE      -- Important information about copying
			permissions and warranty issues.
			This file should *not* be deleted
	README	     -- The file you are currently reading
	Dependencies -- A file containing module dependencies.
			This file is empty at the top level.
	Makefile     -- The top level Makefile for the toolkit
	Release      -- The current Release Id
	ShapeTools.log -- The log file, automatically issued by the
			  shape CM environment when releasing Version
			  1.3 of the toolkit.
	Shapefile    -- The top level Shapefile
	bin/
	include/     -- Two local installation directories.
			These are initially empty.
	lib/	     -- The lib directory for local installation of
			internal libraries during system build.
			Initially only contains subdir "shape".
	    shape/   -- The common Shapefile parts of the toolkit
			and local installation directory for the
			templates for Makefile and Shapefile
	man/         -- The online manuals for
	    man1/    	-- version and attribute control commands
			   and the "shape" command
	    man3/    	-- the AtFS interface
	    man5/	-- file formats of AtFS archive files
	    man8/	-- "atfsrepair", an AtFS archive repair tool
	src/	     -- The sources
	    atfs/	-- the attributed file system (AtFS)
	        conf/	   -- operating system specific code.
	    atfstk/	-- the AtFS toolkit library containing several
			   useful things for AtFS applications.
	    interface/- the shapeTools mode (GNU-Emacs lisp code)
	    rms/     -- the release management system
	    shape/	-- the shape program
	    vc/		-- the version control system
	tutorial/    -- A tutorial on how to work with the shape toolkit
	utils/	     -- A bunch of utilities

Specialties of the System V version
===================================

One problem when using shape's version control system on a System V
machine is the 14 characters limit for filenames. Hence, the names for
archive files where saved versions are stored can not simply be built
by adding some magic characters to the original filename. Archive
names on machines with a 14 character limit for filenames are built by
taking a 11 character fragment of the name and adding the usual
leading and trailing magic characters. This avoids an additional
limit for the length of filenames to 11 or 12 characters (like in
RCS).  Only if the chosen name fragment is equal for two different
files in one directory (which is quite unusual) shape's version
control system fails to construct a proper archive file name and
complains about the clash.

For sake of a proper release management with shape, it is extremely
useful to be able to share AtFS subdirectories (where the archive files
are stored) between different directories. On BSD systems, this can be
organized by using symbolic links.  System V does not support symbolic
links, so we introduced a mechanism allowing the "AtFS" entry in a
directory to be either a subdirectory (the normal case) or a regular
file containing a directory name. The latter case is handled like a
BSD symbolic link and archive files are searched in the directory
named in the "AtFS" entry.


Acknowledgement
===============

Version 1.0 of the shape toolkit was a result of the UniBase project,
a joint research and development project funded by the
"Bundesministerium fuer Forschung und Technologie" (BMFT, Federal
Ministry for Research and Technology of West Germany) under grant
number ITS-8308. The project aimed at the development of a large
scale industrial software production environment.

The current work on the toolkit (version 1.1 and newer) is mostly part
of the STONE project (A STructured and OpeN Environment). STONE is a
scientific project aiming at the construction of a generic software
development environment kernel. The STONE consortium consists of
nine German universities and research institutes, three of them from
former East Germany. STONE is also funded by the BMFT under grant
ITS-8902E8.

Further contributions come from members of the REX project
(Reconfigurable and Extensible Parallel and Distributed Systems)
funded by the EC as ESPRIT Project 2080, and from faculty members of
the TU Berlin.

Thanks to the various people who sent bug reports, hints and
recommendations. Thank you also to the moderator and reviewers of
comp.sources.reviewed, who made very valuable comments on
shapeTools-1.2. They definitely had no easy job reviewing shapeTools
in it's whole complexity.

Special thanks to Steve Emerson (steve@unidata.ucar.edu) who rewrote
parts of the shape program. Juergen Nickelsen (nickel@cs.tu-berlin.de)
wrote the emacs shapeTools mode and the rcs2atfs utility.

The shapeTools people,

	Andy Lampen and Axel Mahler