Usenet 1994 January/usenetsourcesnewsgroupsinfomagicjanuary1994.iso/sources/unix/volume19/shape/part28

Internet Message Format | 1989-05-31 | 37.0 KB

Subject:  v19i041:  A software configuration management system, Part28/33
Newsgroups: comp.sources.unix
Sender: sources
Approved: [e-mail]

Submitted-by: Axel Mahler <unido!coma!axel>
Posting-number: Volume 19, Issue 41
Archive-name: shape/part28



#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#        "End of archive 28 (of 33)."
# Contents:  man/man1/shape.1
# Wrapped by [e-mail] on Thu Jun  1 19:27:18 1989
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'man/man1/shape.1' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'man/man1/shape.1'\"
else
echo shar: Extracting \"'man/man1/shape.1'\" \(34921 characters\)
sed "s/^X//" >'man/man1/shape.1' <<'END_OF_FILE'
X...
X... Copyright (C) 1989, 1990 W. Koch, A. Lampen, A. Mahler, W. Obst,
X...  and U. Pralle
X...
X... This software is published on an as-is basis. There is ABSOLUTELY NO
X... WARRANTY for any part of this software to work correctly or as described
X... in the manuals. We do not accept any liability for any kind of damage
X... caused by use of this software, such as loss of data, time, money, or
X... effort.
X...
X... Permission is granted to use, copy, modify, or distribute any part of
X... this software as long as this is done without asking for charge, and
X... provided that this copyright notice is retained as part of the source
X... files. You may charge a distribution fee for the physical act of
X... transferring a copy, and you may at your option offer warranty
X... protection in exchange for a fee.
X...
X... Direct questions to: Tech. Univ. Berlin
X...              Wilfried Koch
X...              Sekr. FR 5-6
X...              Franklinstr. 28/29
X...              D-1000 Berlin 10, West Germany
X...
X...              Tel: [phone]
X...              E-mail: [e-mail] or [e-mail]
X...
X.TH SHAPE 1unibase  shape \n(dy.\n(mo.\n(yr
X.SH NAME
X\fRshape \- maintain, update, and regenerate program configurations from versions and variants of components.
X.SH SYNOPSIS
X.IP \fBshape\fR 0.5i
X[\ \fB\-f \fIshapefile\fR\ ] [\ \fB\-R \fIrulename\fR\ ] [\ \fB\-confid \fItarget\fR\ ]
X.br
X[\ \fB\-rebuild \fIconfid\fR\ ] [\ \fB\- deikmnpqrsStb \fR\ ]
X.br
X[\ \fB\-version\fR\ ] [\ \fB\-expandall\fR\ ] [\ \fB\-expandnothing\fR\ ]
X.br
X[ \fItarget ...\fR\ ][\ \fImacro definition ...\fR\ ]
X.SH DESCRIPTION
X\fIShape\fR is an upward compatible extension of \fImake\fR, the standard
Xtool on UNIX for maintaining program groups.
X.PP
XIn contrast to \fImake\fR, \fIshape\fR supports versions and variants
Xof programs. \fIshape\fR supplies an integrated version control system
Xbased on an implementation of an attributed file system.
X.PP
X.I
Xshape
Xexecutes a list of shell commands associated with each target defined
Xin a transformation rule, usually to
Xcreate or update a file of the same name. The
X.I
XShapefile
Xcontains information about how to bring a target `up to date'
Xwith respect to others on which it depends.
X`up to date' has an extended meaning for
X.I
Xshape.
X.I
Xmake
Xproduces a target if, after processing all of its dependencies, a target
Xfile is found either to be missing, or to be older than any of its dependency
Xfiles.
X.I
Xshape
Xbuilds a target if a file is found either to be missing, or not to
Xown the appropriate attributes.
X.SH OPTIONS
X.IP "\fB\-f\fI shapefile"\fR
X\fIshape\fR executes commands in shapefile. If no -f option is present,
X`Shapefile', `shapefile', `Makefile', and `makefile', respectively are
Xtried in order. The contents of
X.I
Xshapefile,
Xwhen present, overide the builtin rules. When more than one \fB-f\fR
X.I
Xshapefile
Xargument pairs appear,
X.I
Xshape
Xevaluates each
X.I
Xshapefile
Xin the order listed (just as if they were run through
X.I
Xcat(1)).
XA `-' as the
X.I
Xshapefile
Xargument forces
X.I
Xshape
Xto read from the standard input.
X.IP "\fB\-R\fI selection rule name"\fR
Xactivates a special selection rule.
X.IP \fB\-d\fR
XRun
X.I
Xshape
Xin debug mode. Print out detailed information about files and attributes.
X.IP \fB\-e\fR
XThis option forces
X.I
Xshape to overide the values of macros defined within the
X.I
XShapefile using the value of environment variables.
XThis option has a different effect than in
X.I
Xmake.
XGenerally not all environment
Xvariables are used as macro definitions within
X.I
Xshapefiles.
XTo use environment variables as macro definitions
X.I
Xshape
Xsupplies a special macro:
X.I
XIMPORT = <environment variable 1> ... <environment variable n>.
XThis special macro forces
X.I
Xshape
Xto use the <environment variables 1> to <environment variable n> for
Xmacro definitions. If the -e option is set
X.I
Xshape
Xwill overide assignments within
X.I
Xshapefiles
Xusing this environment variables.
X.IP \fB\-i\fR
X.I
Xshape
Xignores error codes returned by invoked commands.
X.IP \fB\-k\fR
XWhen a nonzero error status is returned by an invoked command, the work on
Xthe current target is abandoned but
X.I
Xshape
Xcontinues with other branches that do not depend on the target.
X.IP \fB\-n\fR
XNo execution made.
X.I
Xshape
Xprints out commands, but does not execute them. Even lines beginning
Xwith @ are printed. However if a command contains the $(MAKE) macro,
Xthat line is always executed.
X.IP \fB\-p\fR
XPrint out the complete set of macro definitions, target descriptions,
Xrule definitions, and rule section, respectively.
X.IP \fB\-q\fR
XQuestion mode.
X.I
Xshape
Xreturns a zero or nonzero status code depending on whether or not
Xthe target file is up to date.
X.IP \fB\-r\fR
XDo not use the implicit rules
X.I
Xshape
Xsupplies by default. Implicit rules defined in the
X.I
Xshapefile
Xremain in effect.
X.IP \fB\-s\fR
XSilent mode.
X.I
Xshape
Xdoes not print out the command before executing them.
X.IP \fB\-S\fR
XUndo the effect of the -k option.
X.IP \fB\-t\fR
XTouch the targets (bringing them up to date) rather than performing
Xthe commands listed in their rules. Use with care! This option has a
Xdifferent effect than in
X.I
Xmake:
Xtargets are up to date for
X.I
Xshape,
Xif they own the appropriate attributes.
X.IP \fB\-b\fR
XThis option has no effect, but is present for compatibility reasons.
X.IP \fB\-version\fR
X.I
Xshape
Xprints out its current version info and the version info of the AFS used by
X.I
Xshape.
X.IP "\fB\-confid \fItarget\fR"
X.I
X\shape
Xgenerates a configuration identification document for
X.I
Xtarget.
X.IP "\fB\-rebuild \fIcondid\fR"
X.I
Xshape
Xuses the configuration identification document of a target
Xgenerated and stored by
X.I
Xshape
Xto rebuild that target.
X.IP "\fB\-force \fItarget\fR"
Xforces shape \fInot\fR to restore the target \fItarget\fR from the binary
Xpool, even if the target exists with the appropriate attributes.
X.IP "\fB\-expandall\fR"
X.IP "\fB\-expandnothing\fR"
XBefore using an instance of a component for production,
X.I
Xshape
Xexpands macros cited within source files. All attributes, both
Xstandard and user defined attributes,
Xsupplied by the AFS can be cited by \fC$__name$\fR, where \fCname\fR
Xis the name of an attribute. Per default this expansion is done
Xonly for at least saved versions. If you enter the option -expandall
Xvia the command line, expansion is done for busy files too. If you
Xwant to suppress expansion completely, use the option -expandnothing.
XNote that
X.I
Xshape
Xassumes that activation of one of this options produces a different target.
XSo don't be surprised about recompilations.
X.IP "\fItarget ... \fR"
XA list of target names can be passed to
X.I
Xshape
Xvia the command line. If no target is given on the command line and
Xthe special target .DEFAULT is not defined within the
X.I
XShapefile, shape
Xtries to produce the first target defined in the
X.I
XShapefile.
X.IP "\fImacro definition\fR"
XOn the command line you can define or redefine macros. Such a definition
Xoverides a macro defined within the
X.I
XShapefile.
X.RE
X.SH "DESCRIPTION FILES"
XA description file for \fIshape\fR contains:
X.sp
X.IP "\(bu macro definitions"
X.IP "\(bu dependency information"
X.IP "\(bu executable commands"
X.IP "\(bu selection rules"
X.IP "\(bu variant section"
X.RE
X.sp
XComments are started with a '#'. The comment ends at the next newline
Xcharacter. '#'s enclosed in quotes (single or double) are \fInot\fR considered
Xas beginning of a comment.
X.PP
XIf the newline character of a line is escaped by a backslash ('\\')
Xthe next line is considered as a continuation line. The backslash and
Xthe newline character are replaced by a space.
X.SH "TRANSFORMATION RULES"
XA transformation rule gives \fIshape\fR information about the dependency
Xrelationships
Xbetween targets and dependents and commands to build a target. A transformation
Xrule has the following format:
X.sp
X    \fCtarget... [:|::] [rule] [+variant...] [dependent...] [; command]
X.br
X        [command]
X.br
X        [command]
X.br
X        ...\fR
X.sp
XThe first line contains list of target names separated by
Xspaces, terminated
Xby a colon or a double colon. This may be followed by a dependent, or a
Xlist of dependents that
X.I
Xshape
Xchecks in this order. The first dependent may be the name of a selection
Xrule. The following may be a list of variant names defined in the variant
Xsection. To activate a variant, cite the variant names preceded by '+' signs.
XOptionally, after a semicolon, a shell command may appear on the first
Xline of the transformation rule.
XThe following lines in the transformation rule have to begin with a TAB and
Xcontain shell commands. These shell commands may be continued by escaping
Xthe newline character with a backslash ('\\'). Such continuation
Xlines must also start with a TAB.
X.PP
XThe first line that does not start with a TAB or a '#' indicates the
Xend of the transformation rule.
X.PP
XTo build a target
X.I
Xshape
Xexpands the macros, strips off the TABs at the beginning of the command
Xlines and passes each command to a shell for execution.
X.PP
XCommands may be preceeded with one or two special characters:
X.IP \-
X.I
Xshape
Xignores any nonzero error code returned by a command line
Xfor which the first character is a minus sign. The minus sign is
Xnot passed to the shell. When a command returns a nonzero return status
X.I
Xshape
Xnormally terminates, unless the \fB-i\fR or \fB-k\fR options, or
Xthe \fB.IGNORE\fR special target is in effect.
X.IP @
XIf the first character of a command is a '@'
X.I
Xshape
Xdoes not print the command before executing it. The '@' is not passed
Xto the shell.
X.IP "\@\-"
XIf the first two non-TAB characters are `@\-'
X.IP
Xshape
Xboth ignores nonzero return codes and suppresses the printing of the
Xcommand line.
X.RE
X.SH "IMPLICIT RULES"
XWhen a target does not appear in any targetlist of a transformation rule
X.I
Xshape
Xtries to find a so-called
X.I
Ximplicit rule,
Xto build this target. An implicit rule has the following format:
X.sp
X    \fC%[.x] ... : %.y ... [: +(macro-name) ...]
X.br
X        [command]
X.br
X        [command]
X.br
X        ...\fR
X.sp
X.PP
XThe syntax of these rules is an extension of
X.I
Xmake's
Xrules specification formalism. The first line of such a rule contains
Xone ore more abstract targets (a percent sign followed by an optional suffix)
Xfollowed by a double colon, one or more abstract dependencies, and after
Xa second colon an optional list of special macro citations.
X.PP
XThe special macro citation \fC+(macro-name)\fR causes
X.I
Xshape
Xto expand this citation by the complete macro definition
X.I
Xname = value.
XThe targets that are produced with such an implicit rule inherit the
Xmacro definitions cited in this rule. This mechanism can be used
Xto attribute the targets for example with the compilation flags that were
Xin effect or the version of the compiler used to produce the target.
XSo if a user supplies an implicit rule in a
X.I
XShapefile
Xhe should cite at least all macros used in this rule.
X.PP
XNote that implicit
X.I
Xmake
Xrules are still supplied by
X.I
Xshape.
X.SH "PREDEFINED IMPLICIT RULES"
XThe following is a list of predefined implicit rules which are always
Xavailable unless they are not explicitly overwritten or canceled within the
Xdescription file.
X.sp 2
X.KS
X.br
X    Compile C programs and add build archive library
X.br
X        \fC%.a : %.c : +(CC) +(CFLAGS) +(vflags)
X.br
X            $(CC) -c $(CFLAGS) $(vflags) %.c
X.br
X            ar rv %.a %.o
X.br
X            rm -f %.o\fR
X.KE
X.sp 2
X.KS
X.br
X    Generate C programs from Lex grammar
X.br
X        \fC%.c : %.l : +(LEX) +(LFLAGS)
X.br
X            $(LEX) $(LFLAGS) %.l
X.br
X            mv lex.yy.c %.c\fR
X.KE
X.sp 2
X.KS
X.br
X    Generate C programs form Yacc grammar
X.br
X        \fC%.c : %.y : +(YACC) +(YFLAGS)
X.br
X            $(YACC) $(YFLAGS) %.y
X.br
X            mv y.tab.c %.c\fR
X.KE
X.sp 2
X.KS
X.br
X    Generate C program form Lex grammar, the compile with C compiler
X.br
X        \fC%.o : %.l : +(LEX) +(LFLAGS) +(CC) +(CFLAGS) +(vflags)
X.br
X            $(LEX) $(LFLAGS) %.l
X.br
X            $(CC) $(CFLAGS) $(vflags) -c lex.yy.c
X.br
X            rm lex.yy.c
X.br
X            mv lex.yy.o %.o\fR
X.KE
X.sp 2
X.KS
X.br
X    Generate C program form Yacc grammar, the compile with C compiler
X.br
X        \fC%.o : %.y : +(YACC) +(YFLAGS) +(CC) +(CFLAGS) +(vflags)
X.br
X            $(YACC) $(YFLAGS) %.y
X.br
X            $(CC) $(CFLAGS) $(vflags) -c y.tab.c
X.br
X            rm y.tab.c
X.br
X            mv y.tab.o %.o\fR
X.KE
X.sp 2
X.KS
X.br
X    Assembling assembler programs
X.br
X        \fC%.o : %.s : +(AS) +(ASFLAGS)
X.br
X            t$(AS) $(ASFLAGS) -o %.o %.s\fR
X.KE
X.sp 2
X.KS
X.br
X    Compiling Ratfor programs
X.br
X        \fC%.o : %.r +(FC) +(RFLAGS) +(FFLAGS)
X.br
X            $(FC) $(RFLAGS) $(FFLAGS) -c %.r\fR
X.KE
X.sp 2
X.KS
X.br
X    Compiling Fortran programs
X.br
X        \fC%.o : %.F : +(FC) +(FFLAGS)
X.br
X            $(FC) $(FFLAGS) -c %.F\fR
X.KE
X.sp 2
X.KS
X.br
X    Compiling Fortran programs
X.br
X        \fC%.o : %.f : +(FC) +(FFLAGS)
X.br
X            $(FC) $(FFLAGS) -c %.f\fR
X.KE
X.sp 2
X.KS
X.br
X    Compiling a Modula definition module
X.br
X        \fC%.sym : %.def : +(M2C) +(M2FLAGS)
X.br
X            $(M2C) $(M2FLAGS) %.def\fR
X.KE
X.sp 2
X.KS
X.br
X    Compiling Modula programs
X.br
X        \fC%.o : %.mod : +(M2C) +(M2FLAGS)
X.br
X            $(M2C) $(M2FLAGS) %.o\fR
X.KE
X.sp 2
X.KS
X.br
X    Compiling Pascal programs
X.br
X        \fC%.o : %.p : +(PC) +(PFLAGS)
X.br
X            $(PC) $(PFLAGS) -c %.o\fR
X.KE
X.sp 2
X.KS
X.br
X    Compiling C programs
X.br
X        \fC%.o : %.c +(CC) +(CFLAGS) +(vflags)
X.br
X            $(CC) $(CFLAGS) $(vflags) -c %.c\fR
X.KE
X.sp 2
X.KS
X.br
X    Copy a shell script and make it executable
X.br
X        \fC% : %.sh
X.br
X            cat %.sh >%; chmod +x %\fR
X.KE
X.sp 2
X.KS
X.br
X    Compile and link Ratfor programs
X.br
X        \fC% : %.r : +(FC) +(RFLAGS) +(FFLAGS) +(LDFLAGS)
X.br
X            $(FC) $(RFLAGS) $(FFLAGS) $(LDFLAGS) %.r -o %\fR
X.KE
X.sp 2
X.KS
X.br
X    Compile and link Fortran programs
X.br
X        \fC% : %.F : +(FC) +(FFLAGS) +(LDFLAGS)
X.br
X            $(FC) $(FFLAGS) $(LDFLAGS) %.F -o %\fR
X.KE
X.sp 2
X.KS
X.br
X    Compile and link Fortran programs
X.br
X        \fC% : %.f : +(FC) +(FFLAGS) +(LDFLAGS)
X.br
X            $(FC) $(FFLAGS) $(LDFLAGS) %.f -o %\fR
X.KE
X.sp 2
X.KS
X.br
X    Compile and link Pascal programs
X.br
X        \fC% : %.p : +(PC) +(PFLAGS) +(LDFLAGS)
X.br
X            $(PC) $(PFLAGS) $(LDFLAGS) %.p -o %\fR
X.KE
X.sp 2
X.KS
X.br
X    Compile and link Modula programs
X.br
X        \fC% : %.mod : +(M2C) +(M2FLAGS) +(LDFLAGS)
X.br
X            $(M2C) $(M2FLAGS) $(LDFLAGS) %.mod -e % -o %\fR
X.KE
X.sp 2
X.KS
X.br
X    Compile and link C programs
X.br
X        \fC% : %.c : +(CC) +(CFLAGS) +(LDFLAGS) +(vflags)
X.br
X            $(CC) $(CFLAGS) $(vflags) $(LDFLAGS) %.c -o %\fR
X.KE
X.sp 2
X.SH "MACRO DEFINITIONS"
XA macro definition has the form:
X.br
X        \fCname = value\fR
X.PP
XA line in the description file which contains an equal sign is considered
Xas a macro definition. A macro definition must not be proceeded by a
Xcolon or a tab. The name of a macro is a string consisting of
Xletters, digits, underscore or minus sign. The string of characters
Xfollowing the equal sign (leading blanks and tabs are skipped) is assigned
Xto the name. The following are valid macro definitions:
X.sp
X.br
X    \fCINCLFILES = /usr/include/stdio.h:/usr/include/sys/time.h
X.br
X    100X = this is a macro
X.br
X    X = 1
X.br
X    SRC-NAMES = main.c sub1.c sub2.c main.h
X.br
X    COMPILE_FLAGS =\fR
X.sp
XThe last definition assigns the empty string to \fCCOMPILE_FLAGS\fR.
XEvery macro that is never explicitly defined has the empty string as
Xits value.
X.PP
XMacros can also be defined via the command line; for example:
X.br
X    \fCshape blubber "CFLAGS=-pg -DDEBUG"\fR
X.br
XThe macro definition \fCCFLAGS=-pg -DDEBUG\fR assigns the
Xvalue \fC-pg -DDEBUG\fR to the macro \fCCFLAGS\fR.
X.SH "MACRO CITATIONS"
XA macro can be cited within the
X.I
Xshapefile
Xby preceeding the name by a dollar sign. If the macro name is longer than
Xone character it must be enclosed in parentheses, either '(' and ')'
Xor '{' and '}'.
X.PP
XThe following are valid macro citations:
X.br
X    \fC$(CFLAGS)
X.br
X    $7
X.br
X    ${SOURCE-FILES}
X.br
X    $(X)
X.br
X    $X\fR
X.br
XThe last two citations are identical. The citation
X.br
X    \fC$$\fR
X.br
Xwill be replaced by a single dollar sign.
X.SH "PREDEFINED MACROS"
XIn order to have a parametrization of the predefined implicit rules,
X.I
Xshape
Xsupplies a number of macros. So it is possible to redefine for example
Xspecial compilation flags without defining a new rule.
X.PP
XFor example, the command for the compilation of a C source file is
X\fC$(CC) -c $(CFLAGS)\fR. The default values of the macros used are \fCcc\fR
Xand an empty string, resulting in the command \fCcc -c\fR. By redefining
X\fC$(CC)\fR to \fCgcc\fR (by adding a macro definition \fCCC=gcc\fR
Xto the description
Xfile) would cause \fCgcc\fR to be used for all C compilations performed by the
Ximplicit rule. By supplying a macro definition \fCCFLAGS=-DBSD4.3 -pg\fR
Xwithin the \fIshapefile\fR the user can pass the C preprocessor
Xoption \fC-DBSD4.3\fR and the compilation flag \fC-pg\fR to each compilation.
X.PP
XThe following is a list of the predefined macros, the default
Xvalues, and a short description, respectively. If after the `=' sign
Xno value is given, there is no
Xdefault value for that macro.
X.sp
X.br
X    \fCSHAPEFLAGS=\fR        Flags for \fIshape\fR
X.br
X    \fCSHAPE=shape\fR        The program \fIshape\fR itself
X.br
X    \fCASFLAGS=\fR        Flags for the assembler
X.br
X    \fCAS=as\fR            Program for doing assembly
X.br
X    \fCRFLAGS=\fR        Flags for the Fortran compiler for Ratfor programs
X.br
X    \fCFFLAGS=\fR        Flags for the Fortran compiler
X.br
X    \fCFC=f77\fR        Program for compiling Fortran programs
X.br
X    \fCM2FLAGS=\fR        Flags for the Modula2 compiler
X.br
X    \fCM2C=m2c\fR        Program for compiling Modula2 programs
X.br
X    \fCPFLAGS=\fR        Flags for the Pascal compiler
X.br
X    \fCPC=pc\fR            Program for compiling Pascal programs
X.br
X    \fCCFLAGS=\fR        Flags for the C compiler
X.br
X    \fCCC=cc\fR            Program for compiling C programs
X.br
X    \fCLDFLAGS=\fR        Flags for the linker
X.br
X    \fCLD=ld\fR            Program to link programs
X.br
X    \fCLFLAGS=\fR        Flags for the lexical analyzer lex
X.br
X    \fCLEX=lex\fR        Program to turn Lex grammars into C or Ratfor programs
X.br
X    \fCYFLAGS=\fR        Flags for yacc
X.br
X    \fCYACC=yacc\fR        Program to turn Yacc grammars into C programs
X.br
X    \fCMAKE=make\fR        The program \fImake\fR
X.br
X    \fCMAKEFLAGS=b\fR        Flags for \fImake\fR
X.br
X    \fCvflags=\fR        Compilation flags in variant section
X.br
X    \fCvpath=\fR        Extension of search path in variant section
X.PP
XAnother predefined macro is \fCVPATH\fR. The \fCVAPTH\fR macro can be set
Xto a list of directories separated by colons. Usually
X.I
Xshape
Xlooks for a file in the current working directory. If the \fCVPATH\fR
Xmacro is defined the search is extended to the directories of
Xthe \fCVPATH\fR list.
XIn contrast the extension of the search path within the variant section
Xvia the \fCvpath\fR macro forces
X.I
Xshape
Xfirst to look for a file in the directories of \fCvpath\fR list.
X.SH "SPECIAL MACROS"
XBefore shape executes any command, some certain internally maintained
Xmacros are expanded. Any occurence of one of the following four macros in
Xcommand strings is replaced by an appropriate value:
X.br
X    \fIcitation    value\fR
X.sp
X    \fC$@\fR    full name of the current target
X.br
X    \fC$?\fR    list of names of the dependents that were found to be out of date
X.br
X    \fC$<\fR    name of the file, that caused the action
X.br
X    \fC$*\fR    prefix shared by current and the dependent filenames
X.br
XWithin the rule section
X.I
Xshape
Xsupplies a special macro, that is valid for citation within the
X.I
Xmsg
Xpredicate in order to have a trace facility:
X.br
X    citation    value
X.sp
X    \fC$+\fR    name of the file that is currently checked for certain attributes.
X.SH "SPECIAL TARGETS"
XWithin
X.I
XShapefiles
Xthe following special targets have a special meaning:
X.IP .DEFAULT:
XIf a target is to be produced, but there are no explicit commands or a
Xrelevant built-in rules, the commands associated with this target are
Xused. If in this case .DEFAULT is not defined
X.I
Xshape
Xprints an error message and stops.
X.IP .IGNORE:
XCauses
X.I
Xshape
Xto ignore non zero return codes of invoked commands. Equivalent to
Xthe \fB-i\fR option.
X.IP .SILENT:
XSilent command execution. The command lines are not printed before
Xexecution. Equivalent to the \fB-s\fR option.
X.IP .BPOOL:
XIf this target is defined within the \fIShapefile\fR only the dependents
Xassociatet with this target are stored into the binary pool. If no dependents
Xare present no derived object will be stored into the binary pool at all.
X.IP .NOBPOOL:
XDependents associated with this target are \fInot\fR stored into the
Xbinary pool.
X.PP
XIf both .BPOOL and .NOBPOOL are defined only the difference set
Xof both dependency lists will be stored into the binary pool.
X.SH "SELECTION RULES"
XIn order to select a concrete instance of a component to build a target
X.I
Xshape
Xsupplies
X.I
Xselection rules.
X.PP
XSelection rules can be defined within a special section of a
X.I
Xshapefile.
XThis section starts with the special comment line
X.br
X    \fC#% RULE-SECTION\fR
X.br
Xand ends with the comment line
X.br
X    \fC#% END-RULE-SECTION\fR
X.br
XA selection rule is a named sequence of \fIalternatives\fR,
Xseparated by semicolons, constituting a logical OR expression. Each
Xalternative consists of a sequence of \fIpredicates\fR, separated
Xby commas forming a logical AND expression.
X.PP
XThe first predicate in an alternative is a pattern against which the name
Xof the sought component is matched. The other predicates consist of
Xpredefined Boolean functions (with side effects) with one or two parameters.
X.PP
XThe first predicate serves to get a set of instances of components, the other
Xfurther reduce the set to exactly one instance. If the reduction to exactly
Xone instance is not possible the alternative is failed.
XIn detail
X.I
Xshape
Xsupplies the following standard predicates:
X.KS
X.br
X    \fCattr(name,value)\fR
X.br
X    \fCattrnot(name,value)\fR
X.br
X    \fCattrlt(name,value)\fR
X.br
X    \fCattrgt(name,value)\fR
X.br
X    \fCattrle(name,value)\fR
X.br
X    \fCattrge(name,value)\fR
X.br
X    \fCattrmin(name)\fR
X.br
X    \fCattrmax(name)\fR
X.br
X.KE
XThe predicate \fCattr\fR
Xselects all instances of a component whose attribute \fCname\fR
Xhas the value \fCvalue, attrlt\fR
Xall instances whose attribute \fCname\fR
Xhas a value less than \fCvalue.\fR
XThe predicate \fCattrmax\fR
Xselects the instance of a component
Xwith the maximum value of the attribute \fCname,\fR
Xand so on.
X.PP
XA pseudo predicate - in order to have a trace facility - is
X.br
X    \fCmsg(string)\fR.
X.PP
XIf
X.I
Xshape
Xenters an alternative which contains this predicate
X.I
Xshape
Xprints the string \fCstring\fR to stdout.
XThe argument \fCname\fR in a predicate may currently be one
Xof the following standard attributes supplied by the AFS:
X.br
X    \fCgeneration\fR
X.br
X    \fCrevision\fR
X.br
X    \fCstate\fR            where value of \fCstate\fR is \fCbusy, saved, proposed,
X.br
X                published, accessed,\fR or \fCfrozen,\fR resp.
X.br
X    \fCauthor\fR
X.br
X    \fCversion\fR
X.br
X    \fCvariant\fR
X.br
X    \fCsyspath\fR
X.br
X    \fChost\fR
X.PP
XFurthermore it is possible to use any user defined attribute in in the
Xrule section for the selection of a certain instance of a component.
X.SH "VARIANT SECTION"
XThe variant section has to start with the special comment line
X.br
X    \fC#% VARIANT-SECTION\fR
X.br
Xand to end with the line
X.br
X    \fC#% END-VARIANT-SECTION\fR
X.br
XThe variant section consists
X.I
Xvclass
Xand
X.I
Xvariant
Xdefinitions.
XA variant definition consists of a variant name followed by a colon.
XIn the following lines (they have to start with a TAB)
Xarbitrary macro definitions may follow:
X.br
X    \fCname:
X.br
X        name1 = value1
X.br
X        name2 = value2
X.br
X        ...\fR
X.br
XA vclass definition has the form:
X.br
X    \fCvclass name ::= (variant1, variant2, ...),\fR
X.br
Xwhere \fCvariant1, variant2, ...\fR are names of variants which are
X.I
Xnot
Xcompatible. During the selection of instances of components
X.I
Xshape
Xchecks, weather all active variants are not part of the same
Xvclass.
XWhen a variant is activated
X.I
Xmacros defined by the variant in the variant section are used for the
Xproduction of a special target rather than the globally defined macros.
XFurthermore
X.I
Xshape
Xsupplies two special macros:
X.br
X    \fCvflags\fR
X.br
Xand
X.br
X    \fCvpath\fR.
X.br
XWith the macro \fCvpath\fR it is possible
Xto extend the regular VPATH feature
Xof make and temporarily. In this way
X.I
Xshape
Xcan identify variants of components that are located
Xphysically at different places. The \fCvflags\fR macro
Xallows to define additional flags passed to tools, for example to
Xcompile a program conditionally.
XOne or more variants are activated within transformation rules: the
Xsecond, third, forth ....
Xdependent (or the first, second, third ... if no selection rule is present)
Xcan be a plus sign followed by a variant name.
X.SH "CONFIGURATION IDENTIFICATION DOCUMENT"
XInvocation of \fIshape\fR with the command line option \fI-confid
Xtargetname\fR
Xcauses \fIshape\fR to produce a configuration identification
Xdocument (confid) for
Xthis target. The confid is stored in a file \fItargetname.cid\fR and is
Xsimply a shapefile that contains all necessary information to rebuild this
Xtarget. An existing file \fItargetname.cid\fR will be overwritten. So if you
Xwant to keep a confid, you have to save it.
X.PP
XConfids serve to store information about how a target is to be produced
Xrather than the target itself. Note that confids that contain
Xnon-frozen versions of components are \fInot\fR an exact description of a
Xcertain
Xtarget, because these versions still can be changed (not the contents of saved
Xversions,
Xbut you can - for example - change the state or
Xuser-defined attributes). If such versions
Xare part of a confid, \fIshape\fR prints out a warning during generation of
Xthis confid
Xand generates the statement \fImsg("warning confid contains <state> version
Xfor <component>")\fR in the rule section of the confid.
X.SH "INCLUDE MECHANISM"
XIf the string `\fIinclude\fR' appears as the first seven letters of a line
Xfollowed by TABs or BLANKs, the string that follows is taken as a filename.
X.I
Xshape
Xsuspends then reading the current description file and reads another file
Xbefore continuing.
X.PP
XThe
X.I
Xinclude
Xfeature makes it more comfortable to use a common set of macro definitions
Xor implicit rule definitions for several programs handled by individual
Xdescription files in various directories.
X.PP
XSecondly it is possible to define a (pragmatic) project environment.
X.SH "DERIVED OBJECT POOL"
XIn order to avoid unnecessary rebuildings - usually recompilations -
X.I shape
Xuses the binary pool feature supported by the attributed file system.
XAfter having built a target which is actually a file system object and
Xnot a pseudo target
X.I
Xshape
Xsaves this object into the binary pool. A special user defined attribute
Xis added to both the object in the binary pool and the current file system
Xobject. This attribute contains information about the attributes of
Xthe source object(s) which was (were) necessary to build this target.
XNote that the object also inherits the macro definitions which are cited in
Ximplicit rules after the second colon (the +(macros)).
XChanging for example the macro definition for CFLAGS will lead to a
Xcompilation of all C source files, that have not yet been build with
Xthese compile flags. So it is possible for
X.I
Xshape
Xto recognize if a target has already been done and can be restored from the
Xbinary pool.
X.SH EXAMPLE
XThe following is a simple example for a
X.I
XShapefile
Xthat shows basically the features of
X.I
Xshape.
X.PP
XSuppose we have a program
X.I
Xxyz
Xconsisting of six C source files and three header files. The sources are
Xwritten by two developers: \fCa.c, b.c, c.c\fR by myself
Xand \fCxxx.c, yyy.c, zzz.c\fR
Xby someone else. In the
X.I
XShapefile
Xwe have several macro definitions describing which components
Xare necessary for the building of the program \fCxyz: MY-SOURCES,
XMY-OBJECTS, MY-INCL-FILE, MY-SPECIAL-INCL-FILE, OTHER-SOURCES,
XOTHER-OBJECTS, and OTHER-INCL-FILES\fR, respectively.
X.PP
XFor the building of the program an explicit rule is given including
Xthe dependencies of
X.I
Xxyz
Xand the object files and a shell script describing how to link the program.
XFurthermore we have three lines describing the dependencies of the objects
Xand the header files.
X.PP
XDuring development and testing I usually want to use
Xmy current working versions and published versions from the other
Xdeveloper. This is formulated within the
X.I
Xrule section.
XWe have two different rules: the first one - \fCexperimental\fR - will be used
Xfor local testing, the second one - \fCrelease\fR - will cause the
Xconfiguration
Xof the program using only at least published versions.
X.PP
XIn the
X.I
Xvariant section
Xthree different variants are defined: \fCexp, rel, and gnu.\fR
XThe first two variant definitions cause
X.I
Xshape
Xto use special compile flags for the production. The third one (\fCgnu\fR)
Xoverrides the default definition of the macro CC to gcc. If this
Xvariant is activated
X.I
Xshape
Xwill use the GNU C compiler instead of the standard C compiler for
Xcompilation. A certain variant is activated by supplying a macro
Xdefinition via the command line (e.g. \fCVARIANT=gnu\fR), which
Xwill override the default definition \fCVARIANT=exp\fR.
X.sp
X.KS
X    \fC###############################################
X.br
X    #    SHAPEFILE for the program XYZ           #
X.br
X    ###############################################
X.sp 2
X    MY-SOURCES = a.c b.c c.c
X.br
X    MY-OBJECTS = a.o b.o c.o
X.br
X    MY-INCL-FILE = defs.h
X.br
X    MY-SPECIAL-INCL-FILE = c.h
X.br
X    OTHER-SOURCES = xxx.c yyy.c zzz.c
X.br
X    OTHER-OBJECTS = xxx.o yyy.o zzz.o
X.br
X    OTHER-INCL-FILES  = globaldefs.h
X.sp 2
X    #
X.br
X    # Definition of default selection rule and variant
X.br
X    #
X.br
X    RULE = experimental
X.br
X    VARIANT = exp
X.br
X    xyz : $(RULE) +$(VARIANT) $(MY-OBJECTS $(OTHER-OBJECTS)
X.br
X        cc -o xyz $(MY-OBJECTS) $(OTHER-OBJECTS)
X.br
X        @echo done.
X.sp 2
X.br
X    $(MY-OBJECTS) : $(MY-INCL-FILES)
X.br
X    c.o : $(MY-SPECIAL-INCL-FILE)
X.br
X    $(OTHER-OBJECTS) : $(OTHER-INCL-FILES)
X.sp 2
X.br
X    #% RULE-SECTION
X.br
X    experimental:
X.br
X        *.c, attr(author, myself), attr(state, busy);
X.br
X        *.c, attrge(state, published), attrmax(version).
X.br
X    release:
X.br
X        *.c, attrge(state, published), attrmax(version).
X.br
X    #% END-RULE-SECTION
X.sp 2
X.br
X    #% VARIANT-SECTION
X.br
X    exp:
X.br
X        vflags = -DDEBUG -p -pg
X.br
X    rel:
X.br
X        vflags = -O
X.br
X    gnu:
X.br
X        CC = gcc
X.br
X        CFLAGS =  -O -g -finline-functions -fkeep-inline-functions \\
X.br
X        -fcombine-regs
X.br
X    #% END-VARIANT-SECTION\fR
X.br
X.KE
X.PP
X.SH FILES
XShapefile, shapefile, Makefile, makefile, /tmp/shapeXXXXXX, \fIname.\fRcid.
X.SH SEE ALSO
Xmake(1), vadm(1), save(1), retrv(1), vcat(1), af_intro(3)
X.SH DIAGNOSTICS
XThe following is a list of the error messages of \fIshape\fR and their
Xexplanations:
X.br
Xmultiply defined action for: <\fItarget\fR>
X.br
X    several rules with several actions have been found to produce a target
X.br
Xunknown option: <\fIoption\fR>
X.br
X    An unknown option has been passed to \fIshape\fR via command line
X.br
Xdon't know how to shape <\fItarget\fR>
X.br
X    Neither an implicit nor an explicit rule exists to build a target
X.br
Xunknown special macro in cmd <\fIcommand\fR>
X.br
X    An unkown special macro has been cited in a command line
X.br
Xmultiple defined selection rule <\fIrulename\fR>
X.br
X    In the rule section(s) a rulename exists more than once
X.br
Xunknown standard predicate <\fIpredicate\fR>
X.br
X    In the rule section an unkown predicate has been cited
X.br
Xerror in variant section <\fIstring\fR>
X.br
X    Syntax error in the variant section
X.br
Xfile not found <\fIfilename\fR>
X.br
X    The file <\fIfilename\fR> passed to \fIshape\fR via -f or -rebuild does not exist
X.br
Xinvalid gen/rev specification <\fIstring\fR>
X.br
X    An invalid specification of \fIgeneration.revision\fR has been detected in the rule section or on the command line
X.br
Xinternal error in <\fIname\fR>
X.br
X    An internal error has occured. Please contact maintenance.
X.br
Xno description file and no arguments
X.br
X    No description file exists an no arguments have been passed to \fIshape\fR via the command line
X.br
Xcannot open file
X.br
X    Could not open description file
X.br
Xerror during execution; retcode <\fInumber\fR>
X.br
X    An error occured during the execution of a command
X.br
Xsyntax error <\fIline\fR>
X.br
X    A syntax error has been detected in the description file
X.br
Xaborted due to syntactical error(s)
X.br
X    If syntax errors have been detected \fIshape\fR stops with this message
X.br
Xinvalid state <\fIstring\fR>
X.br
X    An invalid state has been cited a selection rule
X.br
Xselection rule for <\fIname\fR> failed
X.br
X    No file with appropriate attributes have been found
X.br
Xvariant name not defined: <\fIname\fR>
X.br
X    Citation of \fIattrvar\fR with unknown variant name has been detected
X.br
Xcan't link ./AFS/<\fIname\fR> to .<\fIname\fR>
X.br
Xcan't unlink <\fIname\fR>
X.br
Xcan't link <\fIname\fR> to tmpfile
X.br
X    Couldn't link or unlink a temporary file (especially while restoring an old version)
X.br
Xinterrupted
X.br
X    An user interrupt occured
X.br
Xcan't open include file <\fIfilename\fR>
X.br
X    Could not open an include file
X.br
Xinfinitely recursive macro caused by line: <\fIstring\fR>?
X.br
X    a recursive macro definition has been detected
X.br
Xinvalid macro citation within heritage field
X.br
X    In an implicit rule an invalid macro citation has been detected
X.br
Xtoo many <\fIstring\fR>
X.br
X    Too many targets, dependents or macros for inheritance have been found
X.br
Xforced stop :-(; couldn't find appropriate version for <\fIname\fR>
X.br
X    Selection of a special version was not successful
X.br
Xattribute too long
X.br
X    The string of attributes for inheritance got too long (hopefully never)
X.br
Xvclass error
X.br
X    Inconsistent variant selection
X.br
Xsyntax error in rule section (delimiter missing)
X.br
X    A syntax error in the rule section has been found
X.br
Xunknown selection rule name
X.br
X    An unkown selection rulename has been passed to \fIshape\fR via the command line
X.br
Xnot yet implemented <\fIfeature\fR>
X.br
X    If a not yet implemented feature is detected \fIshape\fR stops with this message
X.br
Xwarning: derived object not saved into bpool; no AFS subdirectory
X.br
X    Could not save a binary into the binary pool
X.SH BUGS AND CAVEATS
X.PP
XThis version of \fIshape\fR has not been tested comprehensively. So there
Xare possibly a lot of bugs!!!
X.PP
XThe following is a description of the not yet realized features
X.I
Xshape.
X.IP \-q -4
XQuestion mode. Returns a zero or nonzero status code depending on weather
Xor not the target file is up to date.
X.IP \-S
XUndo the effect of the -k option.
X.RE
X.PP
X.sp
X\fBNot yet implemented features of MAKE:\fR
X.PP
X.IP ".PRECIOUS"
XSpecifies a list of files not to delete if an interrupt occurs.
X.IP "Substitutions within macros"
X$(name:str1=str2), where str1 is either a suffix, or a word to be replaced
Xin the macros definition, and str2 is the replacement.
X.IP $%
XThe $% macro is evaluated when the target is an archive member of the
Xform: lib(file.o).
X.IP "$(xD) and $(xF)"
Xgetting filename part and directory part( x stands for @, *, and <,
Xrespectively).
X.IP $(MAKE)/$(SHAPE)
Xrun make recursively, i.e.. recursively in every subdirectory.
X.IP SHELL
XCommands are executed using the Bourne Shell; assigning a different
Xvalue to the SHELL macro has no effect.
X.IP "Dynamic dependency parameters"
X$$@, which refers to the current "thing" to the left of the colon
X(which is $@).
X.IP "FRC"
Xforcing shape/make to completely rebuild a target starting from scratch
X.RE
X.SH AUTHOR
XWolfgang Obst
X.br
XTechnical University Berlin
X.sp
X\fIUUCP:\fR        [e-mail] (unido!coma!wolfgang)
X.br
X\fIBITNET:\fR    wolfgang@db0tui62
END_OF_FILE
if test 34921 -ne `wc -c <'man/man1/shape.1'`; then
    echo shar: \"'man/man1/shape.1'\" unpacked with wrong size!
fi
# end of 'man/man1/shape.1'
fi
echo shar: End of archive 28 \(of 33\).
cp /dev/null ark28isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 33 archives.
    rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0