ack/doc/ack.doc

.\" $Id$
.nr PD 1v
.tr ~
.TL
Ack Description File
.br
Reference Manual
.AU
Ed Keizer
.AI
Vakgroep Informatica
Vrije Universiteit
Amsterdam
.NH
Introduction
.PP
The program \fIack\fP(I) internally maintains a table of
possible transformations and a table of string variables.
The transformation table contains one entry for each possible
transformation of a file.
Which transformations are used depends on the suffix of the
source file.
Each transformation table entry tells which input suffixes are
allowed and what suffix/name the output file has.
When the output file does not already satisfy the request of the
user (indicated with the flag \fB\-c.suffix\fP), the table is scanned
starting with the next transformation in the table for another
transformation that has as input suffix the output suffix of
the previous transformation.
A few special transformations are recognized, among them is the
combiner, which is
a program combining several files into one.
When no stop suffix was specified (flag \fB\-c.suffix\fP) \fIack\fP
stops after executing the combiner with as arguments the \-
possibly transformed \- input files and libraries.
\fIAck\fP will only perform the transformations in the order in
which they are presented in the table.
.LP
The string variables are used while creating the argument list
and program call name for
a particular transformation.
.NH
Which descriptions are used
.PP
\fIAck\fP always uses two description files: one to define the
front-end transformations and one for the machine dependent
back-end transformations.
Each description has a name.
First the way of determining
the name of the descriptions needed is described.
.PP
When the shell environment variable ACKFE is set \fIack\fP uses
that to determine the front-end table name, otherwise it uses
\fBfe\fP.
.PP
The way the backend table name is determined is more
convoluted.
.br
First, when the last filename in the program call name is not
one of \fIack\fP or the front-end call-names,
this filename is used as the backend description name.
Second, when the \fB\-m\fP is present the \fB\-m\fP is chopped of this
flag and the rest is used as the backend description name.
Third, when both failed the shell environment variable ACKM is
used.
Last, when also ACKM was not present the default backend is
used, determined by the definition of ACKM in h/local.h.
The presence and value of the definition of ACKM is
determined at compile time of \fIack\fP.
.PP
Now, we have the names, but that is only the first step.
\fIAck\fP stores a few descriptions at compile time.
This descriptions are simply files read in at compile time.
At the moment of writing this document, the descriptions
included are: pdp, fe, i86, m68k2, vax2 and int.
The name of a description is first searched for internally,
then in lib/descr/\fIname\fP, then in
lib/\fIname\fP/descr, and finally in the current
directory of the user.
.NH
Using the description file
.PP
Before starting on a narrative of the description file,
the introduction of a few terms is necessary.
All these terms are used to describe the scanning of zero
terminated strings, thereby producing another string or
sequence of strings.
.IP Backslashing 5
.br
All characters preceded by \e are modified to prevent
recognition at further scanning.
This modification is undone before a string is passed to the
outside world as argument or message.
When reading the description files the
sequences \e\e, \e# and \e<newline> have a special meaning.
\e\e translates to a single \e, \e# translates to a single #
that is not
recognized as the start of comment, but can be used in
recognition and finally, \e<newline> translates to nothing at
all, thereby allowing continuation lines.
.nr PD 0
.IP "Variable replacement"
.br
The scan recognizes the sequences {{, {NAME} and {NAME?text}
Where NAME can be any combination if characters excluding ? and
} and text may be anything excluding }.
(~\e} is allowed of course~)
The first sequence produces an unescaped single {.
The second produces the contents of the NAME, definitions are
done by \fIack\fP and in description files.
When the NAME is not defined an error message is produced on
the diagnostic output.
The last sequence produces the contents of NAME if it is
defined and text otherwise.
.PP
.IP "Expression replacement"
.br
Syntax:  (\fIsuffix sequence\fP:\fIsuffix sequence\fP=\fItext\fP)
.br
Example: (.c.p.e:.e=tail_em)
.br
If the two suffix sequences have a common member \-~\&.e in this
case~\- the text is produced.
When no common member is present the empty string is produced.
Thus the example given is a constant expression.
Normally, one of the suffix sequences is produced by variable
replacement.
\fIAck\fP sets three variables while performing the diverse
transformations: HEAD, TAIL and RTS.
All three variables depend on the properties \fIrts\fP and
\fIneed\fP from the transformations used.
Whenever a transformation is used for the first time,
the text following the \fIneed\fP is appended to both the HEAD and
TAIL variable.
The value of the variable RTS is determined by the first
transformation used with a \fIrts\fP property.
.IP
Two runtime flags have effect on the value of one or more of
these variables.
The flag \fB\-.suffix\fP has the same effect on these three variables
as if a file with that \fBsuffix\fP was included in the argument list
and had to be translated.
The flag \fB\-r.suffix\fP only has that effect on the TAIL
variable.
The program call names \fIacc\fP and \fIcc\fP have the effect
of an automatic \fB\-.c\fP flag.
\fIApc\fP and \fIpc\fP have the effect of an automatic \fB\-.p\fP flag.
.IP "Line splitting"
.br
The string is transformed into a sequence of strings by replacing
the blank space by string separators (nulls).
.IP "IO replacement"
.br
The > in the string is replaced by the output file name.
The < in the string is replaced by the input file name.
When multiple input files are present the string is duplicated
for each input file name.
.nr PD 1v
.LP
Each description is a sequence of variable definitions followed
by a sequence of transformation definitions.
Variable definitions use a line each, transformations
definitions consist of a sequence of lines.
Empty lines are discarded, as are lines with nothing but
comment.
Comment is started by a # character, and continues to the end
of the line.
Three special two-characters sequences exist: \e#, \e\e and
\e<newline>.
Their effect is described under 'backslashing' above.
Each \- nonempty \- line starts with a keyword, possibly
preceded by blank space.
The keyword can be followed by a further specification.
The two are separated by blank space.
.PP
Variable definitions use the keyword \fIvar\fP and look like this:
.DS X
   var NAME=text
.DE
The name can be any identifier, the text may contain any
character.
Blank space before the equal sign is not part of the NAME.
Blank space after the equal is considered as part of the text.
The text is scanned for variable replacement before it is
associated with the variable name.
.br
.sp 2
The start of a transformation definition is indicated by the
keyword \fIname\fP.
The last line of such a definition contains the keyword
\fIend\fP.
The lines in between associate properties to a transformation
and may be presented in any order.
The identifier after the \fIname\fP keyword determines the name
of the transformation.
This name is used for debugging and by the \fB\-R\fP flag.
The keywords are used to specify which input suffices are
recognized by that transformation,
the program to run, the arguments to be handed to that program
and the name or suffix of the resulting output file.
Two keywords are used to indicate which run-time startoffs and
libraries are needed.
The possible keywords are:
.IP \fIfrom\fP
.br
followed by a sequence of suffices.
Each file with one of these suffices is allowed as input file.
Preprocessor transformations do not need the \fIfrom\fP
keyword. All other transformations do.
.nr PD 0
.IP \fIto\fP
.br
followed by the suffix of the output file name or in the case of a
linker
the output file name.
.IP \fIprogram\fP
.br
followed by name of the load file of the program, a pathname most likely
starts with either a / or {EM}.
This keyword must be
present, the remainder of the line
is subject to backslashing and variable replacement.
.IP \fImapflag\fP
.br
The mapflags are used to grab flags given to \fIack\fP and
pass them on to a specific transformation.
This feature uses a few simple pattern matching and replacement
facilities.
Multiple occurrences of this keyword are allowed.
This text following the keyword is
subjected to backslashing.
The keyword is followed by a match expression and a variable
assignment separated by blank space.
As soon as both description files are read, \fIack\fP looks
at all transformations in these files to find a match for the
flags given to \fIack\fP.
The flags \fB\-m\fP, \fB\-o\fP,
\fB\-O\fP, \fB\-r\fP, \fB\-v\fP, \fB\-g\fP, \-\fB\-c\fP, \fB\-t\fP,
\fB\-k\fP, \fB\-R\fP and \-\fB\-.\fP are specific to \fIack\fP and
not handed down to any transformation.
The matching is performed in the order in which the entries
appear in the definition.
The scanning stops after first match is found.
When a match is found, the variable assignment is executed.
A * in the match expression matches any sequence of characters,
a * in the right hand part of the assignment is
replaced by the characters matched by
the * in the expression.
The right hand part is also subject to variable replacement.
The variable will probably be used in the program arguments.
The \fB\-l\fP flags are special,
the order in which they are presented to \fIack\fP must be
preserved.
The identifier LNAME is used in conjunction with the scanning of
\fB\-l\fP flags.
The value assigned to LNAME is used to replace the flag.
The example further on shows the use of all this.
.IP \fIargs\fP
.br
The keyword is followed by the program call arguments.
It is subject to backslashing, variable replacement, expression
replacement, line splitting and IO replacement.
The variables assigned to by \fImapflags\fP will probably be
used here.
The flags not recognized by \fIack\fP or any of the transformations
are passed to the linker and inserted before all other arguments.
.IP \fIstdin\fP
.br
This keyword indicates that the transformation reads from standard input.
.IP \fIstdout\fP
.br
This keyword indicates that the transformation writes on standard output.
.IP \fIoptimizer\fP
.br
The presence of this keyword indicates that this transformation is an optimizer.
It can be followed by a number, indicating the "level" of the
optimizer (see description of the -O option in the ack(1ACK) manual page).
.IP \fIpriority\fP
.br
This \-~optional~\- keyword is followed by a number. Positive priority means
that the transformation is likely to be used, negative priority means that
the transformation is unlikely to be used.
Priorities can also be set with a ack(1ACK) command line option.
Priorities come in handy when there are several implementations of a
certain transformation. They can then be used to select a default one.
.IP \fIlinker\fP
.br
This keyword indicates that this transformation is the linker.
.IP \fIcombiner\fP
.br
This keyword indicates that this transformation is a combiner. A combiner
is a program combining several files into one, but is not a linker.
An example of a combiner is the global optimizer.
.IP \fIprep\fP
.br
This \-~optional~\- keyword is followed an option indicating its relation
to the preprocessor.
The possible options are:
.DS X
  always	the input files must be preprocessed
  cond	the input files must be preprocessed when starting with #
  is	this transformation is the preprocessor
.DE
.IP \fIrts\fP
.br
This \-~optional~\- keyword indicates that the rest of the line must be
used to set the variable RTS, if it was not already set.
Thus the variable RTS is set by the first transformation
executed which such a property or as a result from \fIack\fP's program
call name (acc, cc, apc or pc) or by the \fB\-.suffix\fP flag.
.IP \fIneed\fP
.br
This \-~optional~\- keyword indicates that the rest of the line must be
concatenated to the HEAD and TAIL variables.
This is done once for every transformation used or indicated
by one of the program call names mentioned above or indicated
by the \fB\-.suffix\fP flag.
.br
.nr PD 1v
.NH
Conventions used in description files
.PP
\fIAck\fP reads two description files.
A few of the variables defined in the machine specific file
are used by the descriptions of the front-ends.
Other variables, set by \fIack\fP, are of use to all
transformations.
.PP
\fIAck\fP sets the variable EM to the home directory of the
Amsterdam Compiler Kit.
The variable SOURCE is set to the name of the argument that is currently
being massaged, this is useful for debugging.
The variable SUFFIX is set to the suffix of the argument that is
currently being massaged.
.br
The variable M indicates the
directory in lib/{M}/tail_..... and NAME is the string to
be defined by the preprocessor with \-D{NAME}.
The definitions of {w}, {s}, {l}, {d}, {f} and {p} indicate
EM_WSIZE, EM_SSIZE, EM_LSIZE, EM_DSIZE, EM_FSIZE and EM_PSIZE
respectively.
.br
The variable INCLUDES is used as the last argument to \fIcpp\fP.
It is used to add directories to
the list of directories containing #include files.
.PP
The variables HEAD, TAIL and RTS are set by \fIack\fP and used
to compose the arguments for the linker.
.NH
Example
.PP
Description for front-end
.DS X
.ta 4n 40n
name cpp	# the C-preprocessor
		# no from, it's governed by the P property
	to .i	# result files have suffix i
	program {EM}/lib/cpp	# pathname of loadfile
	mapflag \-I* CPP_F={CPP_F?} \-I*	# grab \-I.. \-U.. and
	mapflag \-U* CPP_F={CPP_F?} \-U*	# \-D.. to use as arguments
	mapflag \-D* CPP_F={CPP_F?} \-D*	# in the variable CPP_F
	args {CPP_F?} {INCLUDES?} \-D{NAME} \-DEM_WSIZE={w} \-DEM_PSIZE={p} \e
	    \-DEM_SSIZE={s} \-DEM_LSIZE={l} \-DEM_FSIZE={f} \-DEM_DSIZE={d} <
		# The arguments are: first the \-[IUD]...
		#  then the include dir's for this machine
		#  then the NAME and size values finally
		#  followed by the input file name
	stdout	# Output on stdout
	prep is	# Is preprocessor
end
name cem	# the C-compiler proper
	from .c	# used for files with suffix .c
	to .k	# produces compact code files
	program {EM}/lib/em_cem	# pathname of loadfile
	mapflag \-p CEM_F={CEM_F?} \-Xp	# pass \-p as \-Xp to cem
	mapflag \-L CEM_F={CEM_F?} \-l	# pass \-L as \-l to cem
	args \-Vw{w}i{w}p{p}f{f}s{s}l{l}d{d} {CEM_F?}
		# the arguments are the object sizes in
		# the \-V... flag and possibly \-l and \-Xp
	stdin	# input from stdin
	stdout	# output on stdout
	prep always	# use cpp
	rts .c	# use the C run-time system
	need .c	# use the C libraries
end
name decode	# make human readable files from compact code
	from .k.m	# accept files with suffix .k or .m
	to .e	# produce .e files
	program {EM}/lib/em_decode	# pathname of loadfile
	args <	# the input file name is the only argument
	stdout	# the output comes on stdout
end
.DE

.DS X
.ta 4n 40n
Example of a backend, in this case the EM assembler/loader.

var w=2	# wordsize 2
var p=2	# pointersize 2
var s=2	# short size 2
var l=4	# long size 4
var f=4	# float size 4
var d=8	# double size 8
var M=em22
var NAME=em22	# for cpp (NAME=em22 results in #define em22 1)
var LIB=lib/{M}/tail_	# part of file name for libraries
var RT=lib/{M}/head_	# part of file name for run-time startoff
var SIZE_FLAG=\-sm	# default internal table size flag
var INCLUDES=\-I{EM}/include	# use {EM}/include for #include files
name asld	# Assembler/loader
	from .k.m.a	# accepts compact code and archives
	to e.out	# output file name
	program {EM}/lib/em_ass	# load file pathname
	mapflag \-l* LNAME={EM}/{LIB}*	# e.g. \-ly becomes
		#	{EM}/mach/int/lib/tail_y
	mapflag \-+* ASS_F={ASS_F?} \-+*  # recognize \-+ and \-\-
	mapflag \-\-* ASS_F={ASS_F?} \-\-*
	mapflag \-s* SIZE_FLAG=\-s*	# overwrite old value of SIZE_FLAG
	args {SIZE_FLAG} \e
	    ({RTS}:.c={EM}/{RT}cc) ({RTS}:.p={EM}/{RT}pc) \-o > < \e
	    (.p:{TAIL}={EM}/{LIB}pc) \e
	    (.c:{TAIL}={EM}/{LIB}cc.1s {EM}/{LIB}cc.2g) \e
	    (.c.p:{TAIL}={EM}/{LIB}mon)
		# \-s[sml] must be first argument
		# the next line contains the choice for head_cc or head_pc
		# and the specification of in- and output.
		# the last three args lines choose libraries
	linker
end
.DE

The command \fIack \-mem22 \-v \-v \-I../h \-L \-ly prog.c\fP
would result in the following
calls (with exec(II)):
.DS X
.ta 4n
1)	/lib/cpp \-I../h \-I/usr/em/include \-Dem22 \-DEM_WSIZE=2 \-DEM_PSIZE=2 \e
	    \-DEM_SSIZE=2 \-DEM_LSIZE=4 \-DEM_FSIZE=4 \-DEM_DSIZE=8 prog.c
2)	/usr/em/lib/em_cem \-Vw2i2p2f4s2l4d8 \-l
3)	/usr/em/lib/em_ass \-sm /usr/em/lib/em22/head_cc \-o e.out prog.k
	/usr/em/lib/em22/tail_y /usr/em/lib/em22/tail_cc.1s
	/usr/em/lib/em22/tail_cc.2g /usr/em/lib/em22/tail_mon
.DE