rsalz@uunet.uu.net (Rich Salz) (06/07/89)
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 rsalz@papaya.bbn.com 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: +49-30-314-22972 X... E-mail: shape@coma.uucp or shape@db0tui62.bitnet 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 wolfgang@coma.uucp (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 -- Please send comp.sources.unix-related mail to rsalz@uunet.uu.net.