.ig Copyright (C) 1993,1994 by the author(s). This software is published in the hope that it will be useful, but WITHOUT ANY WARRANTY for any part of this software to work correctly or as described in the manuals. See the ShapeTools Public License for details. Permission is granted to use, copy, modify, or distribute any part of this software but only under the conditions described in the ShapeTools Public License. A copy of this license is supposed to have been given to you along with ShapeTools in a file named LICENSE. Among other things, this copyright notice and the Public License must be preserved on all copies. Author: Axel Mahler (Axel.Mahler@cs.tu-berlin.de) $Header: shape.1[7.0] Thu Jul 8 01:21:54 1993 axel@cs.tu-berlin.de frozen $ .. .TH shape 1 "Thu Jul 8 01:21:47 1993" "shape_CM-4.9" "ShapeTools" .SH NAME \fRshape \- identify and build program configurations from versions of source objects .SH SYNOPSIS .IP \fBshape\fR 0.5i [\ \fB\-f \fI\fR\ ] .br [\ \fB\-R \fI\fR\ ] [\ \fB\-V\ \fI\fR\ ] .br [\ \fB\-echo\ \fI\fR\ ] [\ \fB\-force\ \fI\fR\ ] [\ \fB\-rebuild \fI\fR\ ] .br [\ \fB\- dDehiknprs\fR\ ] .br [\ \fB\-bct\fR\ ] [\ \fB\-help\fR\ ] [\ \fB\-nomsg\fR\ ] [\ \fB\-novclass\fR\ ] [\ \fB\-version\fR\ ] [\ \fB\-xpoff\fR\ ] [\ \fB\-xpon\fR\ ] .br [\ \fItarget1\ target2 ...\fR\ ] [\ \fImacro=value ...\fR\ ] [\ \fImacro+=value ...\fR\ ] .SH DESCRIPTION Shape allows to transparently compile source objects that are either regular files, or source object \fIversions\fP in the ShapeTools version object base. More generally, shape produces a set of \fIderived objects\fP (``targets'') from appropriately selected versions of corresponding source objects according to a description of the dependencies between the objects. Shape keeps track of the relevant parameters for compilations (source versions, compiler versions, compiler switches etc.) and thus provides a safe and efficient build machinery. .PP When shape compiles source objects, it stores the resulting derived objects together with the effective compile parameters in its \fIderived object cache\fP. Before the derivation process for a requested object is actually started, shape attempts to find an existing derived object that matches the requirements for the target, in the derived object cache. Caching and restoring of objects that are derived from immutable versions allows developers to profit from previous builds by other team members. Overall compile costs in projects are substantially reduced. .PP When serving a build request, shape considers a possibly large number of versions that are stored for an object. Which particular version is \fIbound\fP to an object's name in the description file, is determined by \fIversion selection rules\fP. .PP Shape can manage builds of different variants of a system in parallel. Shape uses the combined potential of dynamic version selection, dynamic macro redefinition, and derived object management to handle variant builds. As most \- if not all \- of the objects and parameters involved in a build are defined as \fImacros\fP, shape provides a great deal of flexibility by allowing to alter some or all of the macros dynamically, depending on which variant shall be built. The concept of \fIvariant definition\fP in shape's description file offers a clear focal point for all definitions that are relevant for a certain variant. .SH OPTIONS .IP "\fB\-f\ \fI\fR" \fIshape\fR uses the supplied argument as name of the description file to be used for the build. If no \fB\-f\fP option is specified, shape tries to find a description file under one of the names ``Shapefile'', ``shapefile'', ``Makefile'', and ``makefile'' (from left to right). If no regular file with one of these names can be found, but versions of respective files are available in the version object base, shape will use the most recent version. When more than one \fB\-f\fR \fI\fR argument pair appears, shape reads each description file in turn. If the name of the description file is specified as ``\-'', shape will read the system description from standard input. It is possible to specify the description file in bound version notation, e.g. \fIShapefile[2.8]\fP or \fIShapefile[Release4]\fP (see \fBvbind(1)\fP for details about bound version notation). .IP "\fB\-R\fI \fR" activates the specified selection rule as initial version binding for source objects. If the \fB\-R\fR option is present, and a selection rule is defined as the first dependency of the first target, shape will use the selection rule passed via the command line, and ignore the first (and only the first) selection rule activation within the description file. The option is useful to override initial default selection rules, specified within the description file, from the command line. .IP "\fB\-V\fI \fR" activates the variant specified by \fI\fP. Several variants can be activated simultaneously from the command line by specifying the \fB\-V\fP option multiple times. All variant specific definitions will be in effect as soon as shape reads the corresponding variant definition in the description file. .IP "\fB\-force \fI\fR" forces shape to build the specified target unconditionally, i.e. even if a suitable, previously build object exists. .IP "\fB\-echo \fI\fR" the value of the macro \fI\fR is written to standard output. This option is useful to extract information from the system description file (e.g. \fCshape \-echo SOURCES\fP, or \fCshape \-echo SUBSYSTEMS\fP), or to control the effect of variant activations. .IP "\fB\-rebuild \fI\fR" attempt a precise rebuild of \fItarget\fP according to a \fIbound configuration thread\fP, supplied in a file named \fI.\fCbct\fR (see description of \fB\-bct\fP switch). .IP \fB\-d\fR run shape in debug mode. Print out detailed information about object dependencies and attributes. .IP \fB\-D\fR print detailed information about the version binding process, and shape's reasoning regarding (re)builds of targets, or retrievals from the derived object cache. This switch is useful to find out about the exact reasons, why shape rederives a target (or not). .IP \fB\-e\fR macro definitions that are imported from the environment (see description of special macro \fIIMPORT\fP, below) override macro definitions in the description file (by default, macro definitions in the description file have precedence over imports from the environment). .IP \fB\-h\fP print usage information on standard output (this is an abbreviation for the \fB\-help\fP switch, see below). .IP \fB\-i\fR ignore error codes returned by commands. .IP \fB\-k\fR when a nonzero error status is returned by an invoked command, the work on the current target is abandoned but shape continues with other branches that do not depend on the failed target. .IP \fB\-n\fR no execution mode. Shape prints out commands, but does not execute them. Even command lines beginning with @ are printed. If a command contains the $(MAKE) macro reference, however, that line is always executed in order to allow tracing of recursive build processes. .IP \fB\-p\fR print out the complete set of macro definitions, target descriptions, and rule definitions, respectively. .IP \fB\-r\fR do not use shape's built-in implicit rules. Implicit rules defined in the description file remain in effect. .IP \fB\-s\fR run in silent mode. Shape does not print out the commands before executing them. .IP \fB\-bct\fP record the build in a \fIbound configuration thread\fP file. A shape configuration thread contains precise definitions of all source versions, their dependencies, the involved tools, and related options that were in effect for a build. The configuration thread for a produced toplevel target (the first target in the description file, or a target requested from the command line) is stored in a file named \fI.\fCbct\fR. Bound configuration threads can be used as input for rebuilds (see option \fB\-rebuild\fP, above). If the source version context of a bct-build is unsafe, shape will record that fact in the bct, and issue a warning message. .IP \fB\-help\fP print usage information on standard output. .IP \fB\-nomsg\fP turn off the trace facility \fImsg\fP in version selection rules. .IP \fB\-novclass\fP disable checking for incompatibility of activated variants. .IP \fB\-version\fP print the version identification of the shape program. .IP \fB\-xpoff\fP turn off attribute expansion in source versions retrieved from the object base. By default, attribute expansion is turned on for all source objects that are directly retrieved from the object base, and turned off for source objects that are regular files (see \fBretrv(1)\fP for details about attribute expansion). .IP \fB\-xpon\fP turn on attribute expansion for all source objects, even in regular files. By default, attribute expansion is turned off for source objects that are regular files, and turned on for all source objects that are directly retrieved from the object base. .IP \fItarget\ ...\fP A list of target names can be passed to shape via the command line. If no target is given on the command line, and the special target .DEFAULT is not defined within the description file, shape tries to produce the first target defined in the description file. .IP "\fI\fR" It is possible to define or modify macros in the description file from the command line. Macros that are defined this way take precedence over all other definitions. Command line macro definitions have either of two forms: .PP .ta 2.0c .nf \fINAME=VALUE\fP and \fINAME+=VALUE\fP .fi .PP with \fINAME\fP being a word and \fIVALUE\fP an arbitrary string. If \fIVALUE\fP contains white space, make sure to quote it. The first form of command line macro definitions sets \fINAME\fP to the substitution \fIVALUE\fP. If \fIVALUE\fP is empty, the macro is reset. The second form appends \fIVALUE\fP with a leading space character to the \fIcurrent substitution\fP of \fINAME\fP. The current substitution may be defined in the description file, or by a previous setting on the command line. For details about the semantics of macro definitions and substitutions, see the respective sections below. .SH "DESCRIPTION FILES" The operation of shape is controlled by a system description file (usually a \fIMakefile\fP) that provides structural information about the system to be managed. Other than \fBmake(1)\fP, shape works on top of \fIAtFS\fP (\fIAt\fPtributed \fPF\fPile \fPS\fPystem), a repository of versioned objects, rather than plain files. Thus, genuine shape description files (usually called \fIShapefile\fP) feature version selection rules, and variant definitions in addition to standard Makefile dependency rules. Shape's description file is an upward compatible extension of make(1)'s description file, the Makefile. A useful structuring convention for shape description files is to maintain a Makefile, and a Shapefile in parallel. Only genuine shape constructs (such as version selection rules, or variant definitions) are kept in \fIShapefile\fP, while the bulk of target rule- and macro definitions is kept in \fIMakefile\fP. The Makefile shall be \fIincluded\fP in \fIShapefile\fP (see description of \fIinclude\fP directive, below). This structuring convention has the advantage that programs that were developed with the support of the ShapeTools system can be shipped as source distribution to sites that don't use ShapeTools. .PP Although shape is largely downward compatible with the original make program, it should be noted that several popular extensions of the original make program, such as GNU Make or Sun Make, provide features \fInot\fP present in shape. See the section on known incompatibilities below. .PP The description file provides an ideal central information base for all sorts of product related definitions. Shape encourages the development of a set of (project\- or organization-specific) conventions for system description, and provides a simple way to extract this information for use by other tools (see \fB\-echo\fP option, above). The description file syntax not only serves to specify component dependencies that are relevant for build processes, but allows a general, hierarchical definition of product oriented tasks. The concept of recursive dependencies maps directly to a stepwise refinement of task definitions. Such tasks can be fully, partly, or not at all automated as appropriate. Thus, certain activities may be automated and standardized, while other activities are just informally described in order to document them or to reason about them (see \fBshape_rms(1)\fP for examples). .PP .SH "\fBSyntactical Structure\fP" The basic syntactical structure of shape's description file is made up of: .IP \fIComments\fP Comments begin with a ``\fC#\fP'' character and extend to the end of the line. In Shapefiles, the end of a line is defined as an unescaped newline (``\e\fI\fP''), or the end of the file. The comment character can't be escaped, but can be quoted in single\- or double quotes. Comment characters in command lines of target rules are ignored by shape. .IP \fIDirectives\fP Directives are special keywords, known to shape. Directives begin at column 0 of a line and extend to the line end. Currently, the only directive recognized by shape is .PP .nf \fCinclude\fI \fP .fi .IP "\fIMacro Definitions\fP" Macro definitions have the general form: .PP .nf \fINAME VALUE\fP .fi .PP \fINAME\fP must be a single word consisting of a sequence of name characters. Name characters are all printable characters except the following: .PP .ce \fC$ # : = ; \fI\fP \et \en\fR .PP The macro definition symbol is either of ``\fC=\fP'', ``\fC+=\fP'', or ``\fC:=\fP''. \fIVALUE\fP is an arbitrary string terminated by the end of the line, or a comment. Macro definitions usually begin in the first column of a line, but may be preceded by leading \fI\fP characters. Macro definitions must not contain leading \fI\fP characters (see section on \fIMacro Definitions\fP, below, for more details). .IP "\fIMacro References\fP" Macro references have one of the following forms: .PP .nf \fC$(\fI\fP) ${\fP\fP} $\fP\fR .fi .PP The macro substitution operator (``\fC$\fP'') can't be escaped, but can be represented by the substitution ``\fC$$\fP''. Macro substitution occurs anywhere in the description file, except in comments, macro names, left hand sides of version selection rule\- and variant definition headers (see next section), and variant class definitions (see section on \fIMacro Substitutions\fP, below, for more details). .IP \fIRules\fP Rules are made up from a \fIrule header\fP, and an optional \fIrule body\fP. The rule header consists of a \fIleft hand side\fP, a \fIrule definition symbol\fP, and an optional \fIright hand side\fP. The left hand side usually begins in column 0 of a line, and may be preceded by leading \fI\fP characters. Left hand sides of rule headers must not contain leading \fI\fP characters. The optional right hand side of a rule header extends to the end of the line, or the beginning of the rule body. A rule body consists of consecutive lines beginning with a \fI\fP character. The body of a rule is terminated by the next line not beginning with a \fI\fP character, or the end of the file. .RS .PP Shape recognizes three different kinds of rules, distinguished by their respective rule definition symbols: .IP \(bu 0.5c \fBtarget rules\fP. Target rules have a single colon character (``\fC:\fP'') as rule definition symbol. The left hand side of target rule headers is a space-separated list of names. The optional right hand side consists of a space-separated list of names, followed by an optional list of production ingredients (see section on \fITarget Rules\fP, below). .IP \(bu \fBversion selection rules\fP. Version selection rules have the rule definition symbol ``\fC:-\fP''. The rule header of version selection rules has a single word on its left hand side, and no right hand side (see section on \fIVersion Selection Rules\fP, below). .IP \(bu \fBvariant definitions\fP. Although variant definitions are \- as the name suggests \- \fIdefinitions\fP, not rules (from a semantical view point), their syntactical representation is that of a rule. Variant definitions have the rule definition symbol ``\fC:+\fP''. The rule header of a variant definition has a single word on its left hand side, and no right hand side (see section on \fIVariant Definitions\fP, below). .RE .IP "\fIVariant Class Definitions\fP" Variant class definitions have the form .PP .ce \fCvclass \fI\fP ::= (\fIvariant1, variant2, ...\fP)\fR .PP (see section on \fIVariants\fP, below). .IP "\fILine Continuations\fP If the end of an input line is escaped by a backslash (``\e'') the next line is considered as a continuation line. The backslash newline character sequence is replaced by a space. .SH \fBMacro Definitions\fP Macro definitions associate names with strings that will be substituted wherever the name of the macro is referenced (see next section). Macros are useful for writing maintainable, and somewhat generic description files. Even moderately large projects will find it extremely rewarding to define conventions for naming and usage of certain macros throughout the product description file. .PP There are three different kinds of macro definitions: .PP \fISimple Macro Definitions\fP .PP A simple macro definition looks like .PP .nf \fINAME \fC=\fP \fR .fi .PP The string that is associated with the macro name can contain macro references. If a macro is defined multiple times within a description file, the last definition will be effective. Macros defined on the command line take precedence over definitions of the same macro in the description file. .PP \fIAdditive Macro Definitions\fP .PP This type of macro definition looks like .PP .nf \fINAME \fC+=\fP \fR .fi .PP The string on the right hand side of the definition is appended to any existing value associated with \fINAME\fP, separated by a space character. Multiple additive macro definitions are concatenated in the order in which they appear in the description file. If an additive macro definition occurs on the command line, the last string value defined in the description file is prepended to the string value defined on the command line. Additive macro definitions in the description file are appended to string values defined on the command line. .PP \fIEvaluative Macro Definitions\fP .PP Evaluative macros are defined in the following way: .PP .nf \fINAME \fC:=\fP \fR .fi .PP First, the string value is associated to \fINAME\fP in the same way as for simple macro definitions. When \fINAME\fP is substituted for the first time, the right hand side of the definition is evaluated, and the result of this evaluation replaces the original string value associated with \fINAME\fP. Thus, evaluation of the right hand side occurs exactly once. This is particularly useful if the defining string is a command substitution (see next section). .SH \fBMacro Substitutions\fP Macro substitution is the process of substituting a \fImacro reference\fP by the string value associated with a macro name. References to undefined macros are substituted by an empty string. Macro references have either of the forms: .PP .nf \fC$(\fINAME\fP) ${\fINAME\fP} $\fI\fR .fi .PP The following are valid macro references: .PP .nf \fC$(CFLAGS) $7 ${SOURCE-FILES} $(X) $X\fR .fi .PP The last two references have identical substitutions. The macro reference .PP .nf \fC$$\fR .fi .PP will substitute a single dollar sign. .PP Before a macro reference is substituted, the associated string will be evaluated. Evaluation of a string value includes .IP \- 0.5c substitution of all macro references in the string value .IP \- command substitution. Any substring of the string value enclosed in backquotes (``\fC`\fP'') will be passed as command to the shell, and be replaced by the command's standard output. .IP \- string substitution. If a macro reference has the form .PP .nf \fC$(\fINAME\fP:\fP\fP=\fP\fP)\fR .fi .PP the reference will be substituted by the evaluated value of \fINAME\fP, with all occurrences of the string \fI\fP replaced by the string \fI\fP. This is particularly useful to maintain related lists, such as \fICSOURCES\fP and \fIOBJECTS\fP for example, automatically: .PP .nf \fCCSOURCES := `echo *.c` OBJECTS := $(CSOURCES:.c=.o) .fi .PP Shape substitutes macro references as late as possible. Macro references occurring in a macro definition are only substituted when the defined macro itself is substituted. Macro references on the dependencies side of target rules are substituted when the rule is evaluated. Macro references on the target side of target rules are substituted immediately after shape has read the description file, i.e. before any production is started. Macro references in include directives are substituted when the directive is executed while shape reads the description file. .SH \fBBuilt-in and Special Purpose Macros\fP In order to provide parametrization of shape's built-in implicit rules, a number of predefined macros is supplied by convention. These macros have meaningful initial values that can be altered by the user. There are also several macros that have special meaning for shape. .PP .nf .ta 3.0c 8.0c 12c \fBMacro Purpose Initial value Remark\fP .sp \fC@\fR full name of the current \fI\fP special target \fC?\fR list of target dependencies \fI\fP special \fC<\fR name of the first target \fI\fP special dependency \fC*\fR prefix shared by target \fI\fP special and the dependent filenames \fC#\fR bound version id of the current \fI\fP special dependency \fC$\fR the character ``\fC$\fP'' $ \fI\fP \fC+\fR name of object to be bound \fI\fP special to a version (selection rules only!) AS Program for doing assembly as conventional ASFLAGS Flags for the assembler \fI\fP conventional CC Program for compiling C cc conventional programs CFLAGS Flags for the C compiler \fI\fP conventional FC Program for compiling Fortran f77 conventional programs FFLAGS Flags for the Fortran compiler \fI\fP conventional HOSTTYPE Host architecture of the \fI\fP special computer that runs shape. The value of this macro is used by shape to construct the derivation key attribute for derived objects IMPORT List of environment variables \fI\fP special that shall be imported as macro definitions LD Program to link programs ld conventional LDFLAGS Flags for the linker \fI\fP conventional LEX Program to turn Lex grammars lex conventional into C or Ratfor programs LFLAGS Flags for the lexical analyzer \fI\fP conventional lex LOGNAME The name or network-id under \fI\fP special which the user who owns the shape process is logged on M2C Program for compiling Modula2 m2c conventional programs M2FLAGS Flags for the Modula2 compiler \fI\fP conventional MAKE The command line with which shape $(MAKEFLAGS) special shape has been invoked. This macro is used for recursive calls to shape MAKEFLAGS Command line flags relevant \fI\fP PC Program for compiling Pascal pc conventional programs PFLAGS Flags for the Pascal compiler \fI\fP conventional RFLAGS Flags for the Fortran compiler \fI\fP conventional for Ratfor programs SHAPEPID The process id of the \fI\fP special running shape program SHAPEVERSION The version id of the shape_CM-4.4 special shape program (or above) SHELL The command processor for /bin/sh special the target rule command lines. The referenced command processor must be able to take its commands from standard input (see section on \fICommand execution\fP, below) VPATH Search path extension for \fI\fP special localizing source components YACC Program to turn Yacc grammars yacc conventional into C programs YFLAGS Flags for yacc \fI\fP conventional vpath Dynamic search path extension \fI\fP special for variants of source components .fi .PP The function of the special purpose macros \fIHOSTTYPE\fP, \fIIMPORT\fP, \fPMAKE\fP, \fIVPATH\fP, and \fIvpath\fP are described in the sections on OPERATION, and Variants below. .SH \fBTarget Rules\fP A target rule defines how, and under what conditions a target is derived from a set of source objects and/or other targets. A target is a name that can refer to a file but need not to do so. Target rules have the following format: .ta 2.0c 4.0c .nf \fI... \fC:\fP [] [\fC+\fI...] [...] \e [\fC:\fI ...] [\fC;\fI ] \fC\et\fI[] ...\fR .fi .PP The header of a target rule (see \fISyntactical Structure\fP, above) consists of a list of \fBtargets\fP, terminated by a colon, followed by an optional list of \fBdependencies\fP, and an optional list of \fBproduction ingredients\fP, beginning after a second colon character. The rule header is terminated by a newline or a semicolon, and followed by the optional rule body. The rule body consists of \fBcommand lines\fP that are executed when a target needs to be rederived. The first command line may immediately follow the semicolon that terminates the rule header. Subsequent command lines must begin with a \fI\fP character. The target rule body is terminated by the first line that doesn't begin with a \fI\fP, or by the end of the file. .PP \fITargets\fP .PP When multiple targets appear on the left hand side of a rule header, and the derivation process needs to be started, shape will derive all of the targets in a single run. .PP \fIDependencies\fP .PP Shape checks a target's dependencies from left to right. The first dependency is examined whether it is the name of a version selection rule. If it is, shape sets the selection rule active (eclipsing all previous selection rule activations), and proceeds to the next dependency. Next, shape checks whether the dependency is a variant activation. If the dependency starts with a ``+'' character followed by the name of a variant, the variant is activated (see the section on \fIVariants\fP, below). Shape proceeds to check for variant activations until the first dependency that isn't a variant activation is found. Next, shape proceeds through the list of remaining dependencies, and \fIbinds\fP (or \fIderives\fP) each of them as necessary, performing a depth first traversal of the dependency graph (see the section on \fIOPERATION\fP, below). .PP \fIProduction Ingredients\fP .PP After all dependencies have been bound, shape constructs the \fIderivation key\fP for the target. The derivation key is an attribute that defines the complete set of parameters that determine whether a target needs to be rebuild. Besides all bound dependencies, the derivation key contains the \fIproduction ingredients\fP that were specified in the target rule header. Production ingredients are typically complete definitions of the macros that are referenced in the command lines of the rule's body. Thus, tool versions and switches affecting the operation of a tool can be made part of the derivation parameters of a target. In order to include macro definitions into the derivation key of a target, the special reference .PP .nf \fI+(NAME1) +(NAME2) ...\fP .fi .PP must occur in place of the production ingredients. .PP \fICommand Lines\fP .PP When shape concludes that a target needs to be (re-)derived, the commands in the target rule body are executed. The rule body consists of consecutive lines that are treated as separate commands. Each command line is evaluated as described in the section on \fIMacro Substitution\fP, above, and passed to the command interpreter defined by the macro \fISHELL\fP. Each command line is executed as a separate process. If complex commands are needed that don't fit on a single line, or if the overhead of repeated process invocations shall be avoided, a logical command line can be extended by escaping the newline with a backslash character (\e\fI\fP), and continuing it on the next physical line. .PP Command lines may be preceded by one or two special characters: .IP \fC\-\fP shape ignores any nonzero error code returned by a command line for which the first character is a minus sign. The minus sign is not passed to the shell. When a command returns a nonzero return status, shape usually considers the derivation process for the target as failure and terminates, unless the \fB\-i\fR or \fB\-k\fR switches, or the \fB.IGNORE\fR special target is in effect. .IP \fC@\fP If the first character of a command is a ``\fC@\fP'', shape does not print the command before executing it. The ``\fC@\fP'' is not passed to the shell. .IP \fC\@\-\fP If the first two non-\fI\fP characters are ``\fC@\-\fP'', shape ignores nonzero return codes, and suppresses the printing of the command line. .PP If shape is invoked in \fIno execution mode\fP (\fB\-n\fP), the evaluated command lines are printed on standard output, showing what shape \fIwould\fP do if invoked without \fB\-n\fP. Command lines that contain the macro reference \fI$(MAKE)\fP are always executed, even if \fB\-n\fP is set. This is done to allow simulation of recursive builds that may span over subdirectories. The reference \fI$(MAKE)\fP is substituted by a shape command invocation with all relevant command line switches set. .PP Within command lines of the rule body, some parts of the target rule header can be dynamically referenced. When a command line is evaluated, the following substitutions are possible .PP .ta 3.0c 4.0c .nf \fBReference Substitution\fR \fC$@\fR full name of the current target \fC$?\fR list of dependencies \fC$<\fR name of the first dependency \fC$*\fR prefix shared by current and the dependent filenames \fC$#\fR bound version id of the current dependency (implicit rules only) .fi .SH \fBImplicit Rules\fP Shape's target rules come in two different flavors: explicit, and implicit. Implicit rules can be seen as templates that define dependency patterns which apply to most targets of a given kind. For this reason, implicit rules are sometimes called \fIpattern rules\fP. Shape converts make's old-style implicit rules (e.g. \fC.c.o:\fP) to pattern rules while it reads the description file. A typical dependency pattern is, for example, the dependency of files containing linkable object code, e.g. \fImodule.o\fP to corresponding files containing source code, e.g. \fImodule.c\fP. The derivation process for most of these source/derived pairs is identical. Rather than writing separate rules for all source/derived dependencies of a system, it is possible to write a single, generic rule, called implicit rule. An implicit rule has the following format: .PP .ta 2.0c 3.0c 3.5c .nf \fC%\fI[\fC.\fI] \fC%\fI[\fC.\fI] ... \fC: %\fI[\fC.\fI] \fC%\fI[\fC.\fI]...\fC \e\fP [\fC:\fP ...] [\fC;\fI ] \fC\et\fP[] \fC\et\fP[] ...\fR .fi .PP While the structure of implicit rules is the same as described above, the names of targets and dependencies are replaced by target patterns, and dependency templates respectively. The percent character in a target pattern acts as wildcard that is matched against all of a target's name up to the optional trailing suffix. For shape, an object name \fIsuffix\fP is the sequence of characters enclosed by the last period character (``.'') within the name, and the \fI\fP character terminating the name. The following example illustrates shape's concept of suffixes: .PP .nf .ta 1.0c 4.0c \fBName Suffix\fC sample.cde cde sample.x.y.c c sample_c .sample.c c\fR .fi .PP The following is an example for an implicit rule that derives linkable object code from corresponding C source files: .ta 1.0c 2.0c 2.5c .PP .nf \fC%.o : %.c : +(CC) +(CFLAGS) \et@echo shape - executing: $(CC) -c $(CFLAGS) $#; \et@$(CC) $(CFLAGS) -E %.c | sed 's;^\e(# [0-9][0-9]* \e"\e)%.c\e(\e".*\e)$$;e\1$#\e2;' > %.i; \et@$(CC) -c $(CFLAGS) %.i; \et@rm %.i;\fR .fi .PP NOTE: This rule is shape's built-in implicit rule to compile C source files. The cryptic command sequence has the purpose to encode the complete file version id into the object code (e.g. \fCsample.c[3.4]\fP rather than \fCsample.c\fP). This is extremely useful in conjunction with with the \fB\-g\fP switch of most C compilers, and version sensitive debuggers, such as \fBvgdb\fP. .PP If a target is derived using implicit rules, the name of the target is matched against the target patterns of the implicit rules. If a rule matches, the matching portion of the target name (the \fIstem\fP, referred to by the ``\fC%\fP'') is consistently substituted for all other occurrences of the wildcard character throughout the rule. Once this is done, the implicit rule is treated like an explicit target rule. .SH \fBExplicit Rules\fP Explicit rules associate explicit target names with explicit dependencies. Explicit rules are most typically used to specify dependencies that cannot be covered by implicit rules, such as deriving an executable program by linking many object code modules. In many cases, explicit rules are used to specify only those target dependencies that are not implied by an implicit rule (such as include dependencies for object files), while the ``natural'' dependencies are assumed as being present. If a description file contains only this sort of explicit dependencies, the omitted implicit dependencies (and an applicable rule body) are automatically added by shape to the total list of target dependencies. .SH \fBBuilt-in Implicit Rules\fP Shape provides a number of predefined implicit target rules that cover many common source/target derivations. The following table lists target patterns, and dependency templates for shape's built-in implicit rules. .PP .nf .ta 3.0c 6.0c \fBTarget Dependency Derivation\fP \fC%.a %.c\fP Compile archive library from C source \fC%.c %.l\fP Generate C programs from Lex grammar \fC%.c %.y\fP Generate C programs from Yacc grammar \fC%.o %.l\fP Compile object code from Lex grammar \fC%.o %.y\fP Compile object code from Yacc grammar \fC%.o %.s\fP Translate assembler program to object code \fC%.o %.r\fP Compile Ratfor source \fC%.o %.F\fP Compile Fortran source \fC%.o %.f\fP Compile Fortran source \fC%.sym %.def\fP Compile Modula definition modules \fC%.o %.mod\fP Compile Modula implementation modules \fC%.o %.p\fP Compile Pascal source \fC%.o %.c\fP Compile C source \fC% %.sh\fP Make executable program from shell-script \fC% %.r\fP Build executable program from Ratfor source \fC% %.F\fP Build executable program from Fortran source \fC% %.f\fP Build executable program from Fortran source \fC% %.p\fP Build executable program from Pascal source \fC% %.mod\fP Build executable program from Modula source \fC% %.c\fP Build executable program from C source .fi .PP .ta 2.0c For a complete definition of shape's built-in implicit rules, run \fCshape -p\fP. .SH \fBSpecial Purpose Targets\fP Several aspects of shape's operation are controlled by special purpose targets that can be put into the description file. Special purpose targets by convention begin with a period character, and have no associated commands. .PP .nf .ta 3.0c \fBTarget Purpose\fP .fi .IP ".DEFAULT:" 3.0c commands in the rule body of the \fI.DEFAULT\fP target rule are executed for all targets that cannot be derived by explicit or implicit target rules. If no commands at all shall be executed for a rule but \fI.DEFAULT\fP is needed for other targets, that rule can be given an empty command (either a ``\fC;\fP'' at the end of the rule header, or an empty line beginning with \fI\fP). If \fI.DEFAULT\fP has dependencies, and no targets are requested from the command line, these dependencies are treated as if they were targets requested from the command line. .IP ".IGNORE:" causes shape to ignore non zero return codes of invoked commands. Equivalent to the \fB\-i\fR switch .IP ".SILENT:" silent command execution. The command lines are not printed before execution. Equivalent to the \fB\-s\fR switch .IP ".BPOOL:" only the dependencies associated with this target are stored in the derived object cache .IP ".NOBPOOL:" dependencies associated with this target are \fInot\fR stored in the derived object cache. .PP If both, \fI.BPOOL\fP, and \fI.NOBPOOL\fP are defined, only the difference set of both dependency lists will be stored in the derived object cache. .SH \fBVersion Selection Rules\fP When shape builds a target, it uses \fIversion selection rules\fP to bind a unique version to each name of the prerequisite source objects. Version selection rules consist of a name, and an associated set of \fIpredicate lists\fP in the rule body. The format of version selection rules is: .ta 2.0c 3.0c .nf \fI [\fC( \fI\fC, \fI\fC,\fI...\fC)\fI]\fC :- \et\fI[\fC,\fP] \fC(...), \fI \fC(...); \et\fI[\fC,\fP] \fC(...), \fI \fC(...); ... \et.\fR .fi The body of a version selection rule consists of a sequence of \fIalternatives\fP, separated by semicolons. Each of the alternatives is an optional pattern, followed by a comma-separated list of \fIpredicates\fP. The selection rule is terminated by a period character. The semicolon-separated sequence of alternatives in a version selection rule constitutes a logical \fIOR\fP expression. The comma-separated list of predicates in an alternative constitutes a logical \fIAND\fP expression. .PP \fIVersion Binding\fP .PP Version binding is the process of determining exactly one version of a given source object from the set of all available versions. Version binding is said to \fIsucceed\fP if one of the rule alternatives succeeds. An alternative succeeds, if it leads to the identification of exactly one version. It is said to \fIfail\fP otherwise. When shape binds a version to the name of a source object, it tries each alternative with a matching pattern, until the name is unambiguously bound to a version. If the pattern is omitted, the alternative will be tried unconditionally. .PP The functioning of version selection rules is one of shape's most important, yet most subtile aspects. In order to provide a basis for an intuitive understanding of the selection rule mechanism, an example is described. The rule \fImost_recent\fP, below, binds: .br \-\ files that were checked out for modification by the shape-invoking user .br \- versions of files that were recently modified (\(-> status \fIsaved\fP) by the same user .br \- the most recently proposed version (\(-> status \fIproposed\fP) of files modified by other users, .br \- or the file version from the last release. .PP .ta 1.0c 2.0c 2.5c 7.5c .nf \fCLASTRELEASE := `lastrelease` # "lastrelease" returns the name # of the last release most_recent :- eq (status, busy), exists ($+[locked_by($(LOGNAME)):]); ge (status, saved), max (mtime), max (version), eq (author, $(LOGNAME)); ge (status, proposed), max (mtime), max (version); eq (__SymbolicName__, $(LASTRELEASE)); cut ($_rule$: couldn't bind $+ as requested!). locked_by (user_id) :- max (version), eq (locker, $_user_id$). .fi .PP For a more detailed description of version selection rule syntax, semantics, and the list of built-in predicates, see \fBBindRules(7)\fP. .PP \fIActivation of Version Selection Rules\fP .PP A version selection for a certain target is invoked by specifying the name of the selection rule as first dependency of a target, or by supplying a selection rule name as argument to the \fB\-R\fP option. If no selection rule is specified explicitly, shape uses its built-in version selection rule that tries to bind a regular file, or the most recent version to the name of an object. .SH \fBVariants\fP The term \fIvariant\fP refers to the intention to manage a product that must comply with different sets of varying external constraints as a unit. Independently from particular semantics that might be associated with the variant notion, there exists a small number of techniques to implement software variation on a technical level. These techniques are: .PP \fIphysical separation\fP of variant components. This is achieved by maintaining separate copies of components in different directories, or by maintaining variant specific branches in version control systems; .PP \fIsource preprocessing\fP of variant components. With this technique, multiple logical variants of a source component are maintained in a single file that contains preprocessor instructions. Before a particular variant can be accessed, a preprocessor must extract it from the common source. A popular example of this technique is \fIconditional compilation\fP, controlled by the \fC#if\fP, and \fC#ifdef\fP instructions within the domain of C/C++ programming; .PP \fIcomposition variation\fP of complex product variants. This technique addresses the case when different variants of a complex product (such as a program) are composed from different sets of components; .PP \fIderivation variation\fP (or variation of the process) that produces different variants of derived objects from the same set of sources by modifying parameters of the derivation process. A typical example for this case is cross compilation of the same sources for different target platforms, or code instrumentation for various purposes, such as debugging, testing, profiling, or optimization. .PP Depending on the particular needs of a project, all of these techniques may be in simultaneous use, and can occur intermixed as appropriate. Shape allows to associate logical variant names with a set of definitions that control all of the above mentioned techniques, making it possible to request builds of particular system variants (and combinations of compatible variants) without the need to worry about how these variants are realized technically. .SH \fBVariant Definitions\fP Shape derives its flexibility from using \fImacro substitution\fP in the description file wherever possible. Shape variant definitions are basically groups of macro definitions that take effect when the variant is activated for a build. A variant definition has the following format: .PP .ta 2.0c 3.0c .nf \fI\fC :+ \et\fI\fC=\fI ...\fR .fi .PP When a variant is activated, the macro definitions associated with the variant become effective. Any previous definition of a macro made in the description file, or on the command line is replaced by the variant macro substitution. If a macro is defined in several variants that are activated together, the respective values are concatenated. .PP \fILocating physically separate Variant Source Objects\fP .PP Shape provides a special macro, \fIvpath\fP, that is intended to be used in variant definitions. The \fIvpath\fP macro defines shape's search precedence when source version archives are located. If \fIvpath\fP is non-empty, shape tries to find any referenced source object in the vpath directories first. If several activated variants define vpath, the variant search path is concatenated and searched from right to left, i.e. the last variant that has been activated has precedence. Only if a referenced source component cannot be found in any of the vpath directories, the current directory is searched. If a source object has been found, it will be bound by the current version selection rule, and be temporarily installed in the build directory. This means that components which are maintained in a vpath subdirectory are temporarily moved up to the main directory. Thus, it is not necessary to make any reference to a vpath subdirectory path in the target rules. .PP \fIVariant Activation\fP .PP When a product is configured and built, variants are typically activated by supplying a variant name as argument to the \fB\-V\fP options. .PP Variants can also be activated for a given target by specifying respective, ``\fC+\fP''-prefixed variant names as dependencies (see section on Target Rules, above). Variant activations for a target must occur before any real object dependency on the dependency line, and after the optional version selection rule activation. .SH \fBVariant Class Definitions\fP With \fIVariant class definitions\fP, shape offers a construct that allows to define \fIincompatible variants\fP, i.e. variants that cannot be activated simultaneously. Shape variant class definitions have the following format: .PP .nf \fCvclass\fI \fP ::= ( \fI\fP, \fP ...\fC)\fR .fi .PP The same variant name can occur in multiple variant class definitions. If a combination of variants is requested with any two variant names that are member of the same variant class, shape will issue an error message, and terminate. Checking of variant classes can be disabled by specifying the \fB\-novclass\fP switch on the command line. .PP NOTE: variant class definitions must occur in the description file \fIbefore\fP any variant definition referenced in a variant class. Variant classes that are defined after referenced variants cannot enforce mutual exclusion of incompatible variants. .PP \fIAn Example\fP .PP The following example shall illustrate the use of variant definitions, and variant classes: .PP .ta 1.0c 2.0c .nf \fCvclass compiler ::= (gnu, prop) gnu:+ CC = gcc -Wall OPTIMIZE = -O2 -inline-functions DEBUG = -g -g3 PROFILE = -pg -a STDC = -ansi prop:+ CC = cc OPTIMIZE = +O3 DEBUG = -g -z +Y PROFILE = -G STDC = -Aa vclass quality ::= (debug, profile, optimize) debug:+ VARCFLAGS = $(DEBUG) profile:+ VARCFLAGS = $(PROFILE) optimize:+ VARCFLAGS = $(OPTIMIZE) CFLAGS += $(VARCFLAGS)\fR .PP .fi If a variant requires the modification of macros with predefined meaning, it is sometimes a good idea \fInot\fP to redefine the macro itself in the variant section. In such a case it is possible to augment an existing macro value by using shape's additive macro definition facility, and a macro from the variant definition defined for this purpose (e.g. \fIVARCFLAGS\fP in the example above). .SH OPERATION When invoked, shape first parses the command line. Shape records the names of the variants to be activated from the command line via the \fB\-V\fP option. Next, shape initializes the built-in, and special macros. Also, shape's built-in derivation rules are initialized. .PP \fIReading the Description File\fP .PP After that, all macro definitions made on the command line are made effective. Shape then locates and opens its description file. If no description file is specified as argument to the \fB\-f\fP option, shape tries to find one of the files \fIShapefile\fP, \fIshapefile\fP, \fIMakefile\fP, or \fImakefile\fP. For each of these names, shape tries to find a regular file first, and, if no such file exists, to find the most recent version of that file in a version control archive. If no such version can be found, shape tries the next name. .PP When shape reads the description file, it collects all macro definitions, and makes them immediately effective, unless a macro of the same name has been defined on the command line. If the special macro \fIIMPORT\fP is encountered, the listed environment variables are defined as macros. If macros with the same name as an imported environment variable occurs in the description file, it has precedence over the definition from the environment, unless the \fB\-e\fP switch is in effect. .PP When shape reads an \fIinclude\fP directive, it evaluates the rest of the line (i.e. the characters that immediately follow the directive), and interprets each word as the name of a file to be read. Each of the file names is bound to either a regular file, or the most recent version of the file. Shape opens each of the included files, suspends reading the current description file, and continues to read the contents of the included file(s), before it resumes reading of the original control file. If multiple file names are specified in an include directive, shape reads each of the files in turn, starting with the leftmost, and ending with the rightmost file name. If an included file could not be opened, shape issues a warning. .PP While shape reads its description files, version selection rules, and target rules are \fIcollected\fP. They are \fIdefined\fP only after shape has finished reading the description file. Macro\-, variant\-, and variant class definitions are made effective as soon as they have been recognized. .PP \fIThe Build Process\fP .PP After the description file has been read, shape determines which targets have been requested. If targets have been requested from the command line, shape will attempt to build each of them, starting with the leftmost target and proceeding towards the rightmost. If no target has been requested from the command line, shape searches the description file for a target named \fI.DEFAULT\fP. If such a target exists, and there are any dependencies associated with it, shape will attempt to build each of these dependencies, from left to right. If no \fI.DEFAULT\fP target rule has been defined in the description file, shape will attempt to build the \fIfirst target defined in the description file\fP. .PP When shape builds a target, it proceeds as follows: .IP 1) 0.7c determine the names of the source objects for a given target by traversing the dependency graph, using built-in and user supplied target rules. The dependency graph is traversed depth first. The ids of all applied rules are recorded. .IP 2) for each required source object, locate the source version archive in the repository. Locating of source version archives takes the current \fIvpath\fP into account. .IP 3) bind each of the source object's names to an appropriate version as implied by the currently active version selection rule. Record the id of each bound dependency. If a dependency is itself a derived object, use its \fIcache key\fP as id. .IP 4) construct the \fIderivation key\fP for the current target from the target name and the records resulting from steps 1) and 3). .IP 5) search the derived object cache for an object that has a derivation key identical to the key constructed in step 4). .IP 6a) if an appropriate derived object was found, a copy of it is installed in the build directory, rather than deriving it from its sources. .IP 6b) if no appropriate derived object was found, it is created by deriving it from its parts. The resulting derived object is put into the derived object cache, and associated with the derivation key resulting from step 4). .PP Targets with an empty list of dependencies \- and thus an empty derivation key \- are always (re-) derived. .PP When shape determines the dependencies of a requested target, it does so by evaluating either explicit target rules, or by applying \- possibly built-in \- implicit rules. If explicit target rules specify object dependencies but no derivation script in the rule body, shape will attempt to supply an appropriate default derivation script. When searching for such a default derivation script, shape tries to find an applicable implicit rule for the current target. An implicit rule is considered applicable, if it has the current target in its list of targets (after pattern substitution), and all \- explicit, and implied \- dependencies exist. If no implicit rule is found to be applicable, shape looks for the \fI.DEFAULT\fP target rule. If such a rule exists, and if it has an associated derivation script in its rule body, this script will be supplied as default derivation script. If neither of the two possibilities leads to a default derivation script, shape gives up. .PP \fIDerived Object Caching\fP .PP Before the derivation process for a requested target is started, it is attempted to find a suitable derived object in the derived object cache that matches the required properties. Shape is based on the \fIderivation key\fP concept for target objects. The derivation key is constructed according to the algorithm described above. Relevant parameters that go into the derivation key are the \fIlist of dependency ids\fP, the \fItarget rule id\fP, the \fIlist of production ingredients\fP, the \fIbuild platform\fP (usually defined by the macro \fIHOSTTYPE\fP; if this macro is not defined, shape takes the host id as build platform), and the \fIattribute expansion status\fP of each source object. When an object has been derived, shape stores it in the derived object cache, and marks it with the derivation key attribute. For a detailed trace of shape's derived object cache handling, and the use of derivation keys, run shape with the \fB\-D\fP switch. .PP \fICommand Execution\fP .PP When a target needs to be (re-) derived, shape executes the commands associated with the target. Before the commands are executed, shape sets up the command execution context. The version objects of the target's dependencies are installed as regular files in the file system. If necessary, shape retrieves source objects from the version control archive. If a file with the object's name already exists in the place where a version is to be installed, shape will temporarily move it to the \fIAtFS\fP subdirectory. After the command script has completed, shape will restore the original state of all affected directories. .PP Shape executes a command line by starting the program referenced in the \fI$(SHELL)\fP macro, and opening a pipe to the resulting process. The command line is written to the pipe, and thus sent to the \fI$(SHELL)\fP process' standard input. .PP Each of the command lines in a rule body are executed by a separate process. Thus, the execution status of separate commands is not preserved. If multiple commands are needed that rely on the execution status of previous commands, all these commands must occur in a single command line. This is possible with \fIline continuations\fP (see section on \fISyntactical Structure\fP, above). .br NOTE: many command interpreters use the ``\fC$\fP'' character as special symbol (typically as variable reference). Make sure to pass ``\fC$\fP'' characters in commands to the \fI$(SHELL)\fP process by using the ``\fC$$\fP'' special macro (see section on \fIMacro References\fP, above). .SH INCOMPATIBILITIES In order to facilitate migration from \fBmake(1)\fP, shape was designed to be upward compatible with Makefiles. Although most of make's description file features are present in shape, there is a number of incompatibilities that may need to be taken care of. There exists also a number of popular extensions of the original make program (e.g. Sun's Make, HP's Make, GNU Make, nmake etc.) that offer various special features that aren't supported by other make extensions, or by shape. When a migration from make to shape is planned, it should be checked whether special extensions or incompatible features are used. .PP \fIFeatures not supported by shape\fP .IP "\fBDouble colon rules\fP" Double colon rules associate the same target with different derivation scripts. This type of rule is useful to support different derivations for a target depending on which dependencies are out of date. Because shape bases its decision whether to derive on the \fIderivation key\fP, rather than mere modification time stamps of files, this sort of rule makes no sense in shape. .IP "\fBArchive member targets\fP" Archive member targets are objects that live in an archive file (see \fBar(1)\fP) rather than the file system. Within these archives, make bases its decisions on the modification time stamps of source files, and archive entry dates. There is no way for shape to simulate the concept of derivation keys for archive members. Maintenance of archives, however, is easy with shape, because all data for compiled object files is maintained in the derived object cache. If the source for an object that is stored in an archive is modified, shape can rederive this object, and selectively replace the entry in the archive. .IP "\fBSCCS stuff\fP" In order to provide basic support for team oriented development processes, make allows to retrieve the most recent version of source files from SCCS archives. Because of the awkward naming convention for SCCS version archive files, special support for dealing with these archives had to be built into make. Because shape is tightly integrated with the \fIAtFS\fP version object repository, there is no need for any special SCCS support. .IP "\fBSpecial targets\fP" Shape does not recognize the special targets \fI.PRECIOUS:\fP, and \fI.SUFFIXES:\fP. The .PRECIOUS target in Makefiles has the purpose to prevent deletion of expensively derived intermediate targets (by default, make deletes intermediate targets). Because shape stores intermediate targets in the derived object cache, there is no need for the .PRECIOUS feature. To prevent caching of possibly large, useless intermediate targets, use the \fI.NOBPOOL:\fP special target (see section on \fISpecial Targets\fP, above). The .SUFFIXES target in Makefiles has the purpose to introduce new suffix types into make's derivation engine, and to determine the order in which implicit rules (\fIsuffix rules\fP in make terminology) are applied. In shape, new suffix types can be added dynamically, simply by introducing new implicit rules. Moreover, shape has an intelligent algorithm the determines the applicable implicit rule. .PP \fIFeatures with different semantics\fP .PP .IP "\fBEnvironment Variables\fP" Many make programs import the entire set of environment variables as macro definitions into the build process. This can sometimes produce surprising results. In shape, environment variables are explicitly imported with the \fIIMPORT\fP special macro. .IP "\fB? Macro\fP" In make's target rules, the special macro reference \fC$?\fP is substituted by the names of those dependency file names that have been updated since the current target has been derived. Because shape bases its decision whether to derive on the concept of \fIderivation key\fP, rather than mere file modification time stamps, the \fI?\fP macro cannot be correctly defined. Instead, shape substitutes the entire list of dependency names \- updated or not. .SH FILES Shapefile, shapefile, Makefile, makefile, /tmp/shapeXXXXXX, \fI\fP.bct .SH "SEE ALSO" \fBmake(1)\fP, \fPsave(1)\fP, \fPretrv(1)\fP, \fPvadm(1)\fP, \fPvl(1)\fP, \fPvgdb(1)\fP, \fPvbind(1)\fP, \fPafintro(3)\fP, \fPatfstkintro(3)\fP, \fPsttkintro(3)\fP, \fPbindrules(7)\fP .SH "CAVEATS AND BUGS" Macro references containing string substitutions cause a syntax error if used in place of target dependencies. Workaround: use indirect macro substitution. .PP There are probably more bugs in shape. Please report any bug findings to \fIshape-cr@cs.tu-berlin.de\fP. .SH "FURTHER READING" .IP "\fIAxel Mahler:\fP" 2.5c ``Using the Shape Toolkit for Cooperative Software Development \- A Tutorial'', in the toolkit distribution. .IP "\fIAxel Mahler \fPand\fP Andreas Lampen\fP:" ``An Integrated Toolset for Engineering Software Configurations'', Sigplan Notices, Vol. 24, No. 2, or Software Engineering Notes, Vol. 13, No. 5, November 1988. .IP "\fIAndreas Lampen\fP and \fPAxel Mahler\fP:" ``An Object Base for Attributed Software Objects'', Proceedings of the Fall 1988 EUUG Conference. .PP These and other papers are available via anonymous ftp from \fIcoma.cs.tu-berlin.de\fP (pub/shapeTools/papers). .SH AUTHOR \fIShape\fP was designed by the shape project team at Technical University Berlin. The program was originally implemented by Wolfgang Obst (1988). Extensive fixes and modifications were introduced by Axel Mahler (1992). Valuable contributions came from Steve Emmerson. In 1993 most parts of shape were re-implemented by Axel Mahler. The version binding was re-implemented by Andreas Lampen. A complete re-implementation of the Shapefile parser was done by Juergen Nickelsen. .sp Contact: .nf SHAPE Technical University Berlin Sekr. FR 5-6 Franklinstr. 28/29 10587 Berlin .sp General correspondence: shape@cs.tu-berlin.de Bug reports and modification requests: shape-cr@cs.tu-berlin.de