acd.1

minix操作系统最新版本（3.1.1）的源代码

.TH ACD 1
.SH NAME
acd \- a compiler driver
.SH SYNOPSIS
.B acd
\fB\-v\fR[\fIn\fR]
\fB\-vn\fR[\fIn\fR]
.BI \-name " name"
.BI \-descr " descr"
.BI \-T " dir"
.RI [ arg " ...]"
.SH DESCRIPTION
.de SP
.if t .sp 0.4
.if n .sp
..
.B Acd
is a compiler driver, a program that calls the several passes that are needed
to compile a source file.  It keeps track of all the temporary files used
between the passes.  It also defines the interface of the compiler, the
options the user gets to see.
.PP
This text only describes
.B acd
itself, it says nothing about the different options the C-compiler accepts.
(It has nothing to do with any language, other than being a tool to give
a compiler a user interface.)
.SH OPTIONS
.B Acd
itself takes five options:
.TP
\fB\-v\fR[\fIn\fR]
Sets the diagnostic level to
.I n
(by default
.BR 2 ).
The higher
.I n
is, the more output
.B acd
generates:
.B \-v0
does not produce any output.
.B \-v1
prints the basenames of the programs called.
.B \-v2
prints names and arguments of the programs called.
.B \-v3
shows the commands executed from the description file too.
.B \-v4
shows the program read from the description file too.  Levels 3 and 4 use
backspace overstrikes that look good when viewing the output with a smart
pager.
.TP
\fB\-vn\fR[\fIn\fR]
Like
.B \-v
except that no command is executed.  The driver is just play-acting.
.TP
.BI \-name " name"
.B Acd
is normally linked to the name the compiler is to be called with by the
user.  The basename of this, say
.BR cc ,
is the call name of the driver.  It plays a role in selecting the proper
description file.  With the
.B \-name
option one can change this.
.B Acd \-name cc
has the same effect as calling the program as
.BR cc .
.TP
.BI \-descr " descr"
Allows one to choose the pass description file of the driver.  By default
.I descr
is the same as
.IR name ,
the call name of the program.  If
.I descr
doesn't start with
.BR / ,
.BR ./ ,
or
.BR ../
then the file
.BI /usr/lib/ descr /descr
will be used for the description, otherwise
.I descr
itself.  Thus
.B cc \-descr newcc
calls the C-compiler with a different description file without changing the
call name.  Finally, if
.I descr
is \fB"\-"\fP, standard input is read.  (The default lib directory
.BR /usr/lib ,
may be changed to
.I dir
at compile time by \fB\-DLIB=\e"\fP\fIdir\fP\fB\e"\fP.  The default
.I descr
may be set with \fB\-DDESCR=\e"\fP\fIdescr\fP\fB\e"\fP for simple
installations on a system without symlinks.)
.TP
.BI \-T " dir"
Temporary files are made in
.B /tmp
by default, which may be overridden by the environment variable
.BR TMPDIR ,
which may be overridden by the
.B \-T
option.
.SH "THE DESCRIPTION FILE"
The description file is a program interpreted by the driver.  It has variables,
lists of files, argument parsing commands, and rules for transforming input
files.
.SS Syntax
There are four simple objects:
.PP
.RS
Words, Substitutions, Letters, and Operators.
.RE
.PP
And there are two ways to group objects:
.PP
.RS
Lists, forming sequences of anything but letters,
.SP
Strings, forming sequences of anything but Words and Operators.
.RE
.PP
Each object has the following syntax:
.IP Words
They are sequences of characters, like
.BR cc ,
.BR \-I/usr/include ,
.BR /lib/cpp .
No whitespace and no special characters.  The backslash character
.RB ( \e )
may be used to make special characters common, except whitespace.  A backslash
followed by whitespace is completely removed from the input.  The sequence
.B \en
is changed to a newline.
.IP Substitutions
A substitution (henceforth called 'subst') is formed with a
.BR $ ,
e.g.
.BR $opt ,
.BR $PATH ,
.BR ${lib} ,
.BR $\(** .
The variable name after the
.B $
is made of letters, digits and underscores, or any sequence of characters
between parentheses or braces, or a single other character.  A subst indicates
that the value of the named variable must be substituted in the list or string
when fully evaluated.
.IP Letters
Letters are the single characters that would make up a word.
.IP Operators
The characters
.BR = ,
.BR + ,
.BR \- ,
.BR \(** ,
.BR < ,
and
.B >
are the operators.  The first four must be surrounded by whitespace if they
are to be seen as special (they are often used in arguments).  The last two
are always special.
.IP Lists
One line of objects in the description file forms a list.  Put parentheses
around it and you have a sublist.  The values of variables are lists.
.IP Strings
Anything that is not yet a word is a string.  All it needs is that the substs
in it are evaluated, e.g.
.BR $LIBPATH/lib$key.a .
A single subst doesn't make a string, it expands to a list.  You need at
least one letter or other subst next to it.  Strings (and words) may also
be formed by enclosing them in double quotes.  Only
.B \e
and
.B $
keep their special meaning within quotes.
.SS Evaluation
One thing has to be carefully understood: Substitutions are delayed until
the last possible moment, and description files make heavy use of this.
Only if a subst is tainted, either because its variable is declared local, or
because a subst in its variable's value is tainted, is it immediately
substituted.  So if a list is assigned to a variable then this list is only
checked for tainted substs.  Those substs are replaced by the value
of their variable.  This is called partial evaluation.
.PP
Full evaluation expands all substs, the list is flattened, i.e. all
parentheses are removed from sublists.
.PP
Implosive evaluation is the last that has to be done to a list before it
can be used as a command to execute.  The substs within a string have been
evaluated to lists after full expansion, but a string must be turned into
a single word, not a list.  To make this happen, a string is first exploded
to all possible combinations of words choosing one member of the lists within
the string.  These words are tried one by one to see if they exist as a
file.  The first one that exists is taken, if none exists than the first
choice is used.  As an example, assume
.B LIBPATH
equals
.BR "(/lib /usr/lib)" ,
.B key
is
.B (c)
and
.B key
happens to be local.  Then we have:
.PP
.RS
\fB"$LIBPATH/lib$key.a"\fP
.RE
.PP
before evaluation,
.PP
.RS
\fB"$LIBPATH/lib(c).a"\fP
.RE
.PP
after partial evaluation,
.PP
.RS
\fB"(/lib/libc.a /usr/lib/libc.a)"\fP
.RE
.PP
after full evaluation, and finally
.PP
.RS
.B /usr/lib/libc.a
.RE
.PP
after implosion, if the file exists.
.SS Operators
The operators modify the way evaluation is done and perform a special
function on a list:
.TP
.B \(**
Forces full evaluation on all the list elements following it.  Use it to
force substitution of the current value of a variable.  This is the only
operator that forces immediate evaluation.
.TP
.B +
When a
.B +
exists in a list that is fully evaluated, then all the elements before the
.B +
are imploded and all elements after the
.B +
are imploded and added to the list if they are not already in the list.  So
this operator can be used either for set addition, or to force implosive
expansion within a sublist.
.TP
.B \-
Like
.BR + ,
except that elements after the
.B \-
are removed from the list.
.PP
The set operators can be used to gather options that exclude each other
or for their side effect of implosive expansion.  You may want to write:
.PP
.RS
\fBcpp \-I$LIBPATH/include\fP
.RE
.PP
to call cpp with an extra include directory, but
.B $LIBPATH
is expanded using a filename starting with
.B \-I
so this won't work.  Given that any problem in Computer Science can be solved
with an extra level of indirection, use this instead:
.PP
.RS
.ft B
cpp \-I$INCLUDE
.br
INCLUDE = $LIBPATH/include +
.ft P
.RE
.SS "Special Variables"
There are three special variables used in a description file:
.BR $\(** ,
.BR $< ,
and
.BR $> .
These variables are always local and mostly read-only.  They will be
explained later.
.SS "A Program"
The lists in a description file form a program that is executed from the
first to the last list.  The first word in a list may be recognized as a
builtin command (only if the first list element is indeed simply a word.)
If it is not a builtin command then the list is imploded and used as a
\s-2UNIX\s+2 command with arguments.
.PP
Indentation (by tabs or spaces) is not just makeup for a program, but are
used to group lines together.  Some builtin commands need a body.  These
bodies are simply lines at a deeper indentation.
.PP
Empty lines are not ignored either, they have the same indentation level as
the line before it.  Comments (starting with a
.B #
and ending at end of line) have an indentation of their own and can be used
as null commands.
.PP
.B Acd
will complain about unexpected indentation shifts and empty bodies.  Commands
can share the same body by placing them at the same indentation level before
the indented body.  They are then "guards" to the same body, and are tried
one by one until one succeeds, after which the body is executed.
.PP
Semicolons may be used to separate commands instead of newlines.  The commands
are then all at the indentation level of the first.
.SS "Execution phases"
The driver runs in three phases: Initialization, Argument scanning, and
Compilation.  Not all commands work in all phases.  This is further explained
below.
.SS "The Commands"
The commands accept arguments that are usually generic expressions that
implode to a word or a list of words.  When
.I var
is specified, then a single word or subst needs to be given, so
an assignment can be either
.I name
.B =
.IR value ,
or
.BI $ name
.B =
.IR value .
.TP
.IB "var " = " expr ..."
The partially evaluated list of expressions is assigned to
.IR var .
During the evaluation is
.I var
marked as local, and after the assignment set from undefined to defined.
.TP
.BI unset " var"
.I Var
is set to null and is marked as undefined.
.TP
.BI import " var"
If
.I var
is defined in the environment of
.B acd
then it is assigned to
.IR var .
The environment variable is split into words at whitespace and colons.  Empty
space between two colons
.RB ( :: )
is changed to a dot.
.TP
.BI mktemp " var " [ suffix ]
Assigns to
.I var
the name of a new temporary file, usually something like /tmp/acd12345x.  If
.I suffix
is present then it will be added to the temporary file's name.  (Use it
because some programs require it, or just because it looks good.)
.B Acd
remembers this file, and will delete it as soon as you stop referencing it.
.TP
.BI temporary " word"
Mark the file named by
.I word
as a temporary file.  You have to make sure that the name is stored in some
list in imploded form, and not just temporarily created when
.I word
is evaluated, because then it will be immediately removed and forgotten.
.TP
.BI stop " suffix"
Sets the target suffix for the compilation phase.  Something like
.B stop .o
means that the source files must be compiled to object files.  At least one
.B stop
command must be executed before the compilation phase begins.  It may not be
changed during the compilation phase.  (Note: There is no restriction on
.IR suffix ,
it need not start with a dot.)
.TP
.BI treat " file suffix"
Marks the file as having the given suffix for the compile phase.  Useful
for sending a
.B \-l
option directly to the loader by treating it as having the
.B .a
suffix.
.TP
.BI numeric " arg"
Checks if
.I arg
is a number.  If not then
.B acd
will exit with a nice error message.
.TP
.BI error " expr ..."
Makes the driver print the error message
.I "expr ..."
and exit.
.TP
.BI if " expr " = " expr"
.B If
tests if the two expressions are equal using set comparison, i.e. each
expression should contain all the words in the other expression.  If the
test succeeds then the if-body is executed.
.TP
.BI ifdef " var"
Executes the ifdef-body if
.I var
is defined.
.TP
.BI ifndef " var"
Executes the ifndef-body if
.I var
is undefined.
.TP
.BI iftemp " arg"
Executes the iftemp-body if
.I arg
is a temporary file.  Use it when a command has the same file as input and
output and you don't want to clobber the source file:
.SP
.RS
.nf
.ft B