# 4.2

Here is my current draft of 4.2. [Moon: I asked you some questions
about compilation environment'' which is unrelated to what is in
this draft, so don't look for it.]

*********************************************************************

\input macros2

\beginChapter 4.{Working Draft American National Standard
for Information Systems---Programming Language Common Lisp}%
{Introduction}{Introduction}

Editors:

Revision: \rev

\endTitlePage

%% Compilation
\beginsubSection{Introduction}

Execution of code can be accomplished by a variety of means ranging
from direct interpretation of the list structure representing a
program through compilation to machine code.  An evaluator
implementation can be based on any of these strategies. The term
{\word implicit compilation\/} refers to compilation performed during
evaluation.  The compiler is a utility that translates code into an
implementation-dependent form that might be represented or executed
efficiently.

Conforming code must be structured so that its results and observable
side effects will be the same whether or not implicit compilation
takes place.

% References:
%    CLtL page 143 (next to last paragraph)
%    CLtL page 321 (second paragraph)
%[rpg: CLtL page 438]

The nature of the processing performed during compilation is discussed
in Compilation Semantics''.  Following Compilation Semantics'' is
a discussion of the behavior of {\function compile-file\/} and the
interface between {\function compile-file\/} and {\function load\/}.
\endsubSection%{Introduction}
\beginsubSection{Terminology}

% Reference:  Issue CONSTANT-COMPILABLE-TYPES

The following terminology is used in this section.

The term {\word constant\/} refers to a quoted or self-evaluating
constant or an {\word object\/} that is a substructure of such a
constant, not a named {\tt (defconstant)\/} constant.  See
Constants''.

The term {\word source code\/} refers to {\word objects\/}
representing programs suitable for evaluation, such as {\word
objects\/} created by {\function read} or by macro expansion.
{\function compile-file} is not required to create such {\word
objects\/} nor to invoke {\function read}.

The term {\word compiled code\/} is used to refer to {\word objects\/}
representing compiled programs, such as {\word objects\/} constructed
by {\function load\/} when applied to a file created by {\function
compile-file\/}.

The term {\word coalesce\/} is defined as follows.  Suppose {\tt A\/}
and {\tt B\/} are two quoted {\word objects\/} defined as quoted
constants in the source code, and that {\tt A'\/} and {\tt B'\/} are
the corresponding {\word objects\/} in the compiled code.  If {\tt
A'\/} and {\tt B'\/} are {\function eql\/} but {\tt A\/} and {\tt B\/}
are not {\function eql\/}, then it is said that {\tt A\/} and {\tt
B\/} have been coalesced by the compiler.

Three different {\word environments\/} relevant to compilation are
distinguished: the {\word compilation environment\/}, the {\word
evaluation environment\/}, and the {\word run time environment\/}. The
{\word compilation environment\/} is maintained by the compiler and is
used to hold definitions to be used by the compiler; the compilation
environment might be separate from the {\word evaluation
environment\/}. The {\word evaluation environment\/} is the run time
{\word environment\/} of the Lisp image from which the compiler was
invoked. The {\word run time environment\/} is the {\word
environment\/} in which the program being compiled will be executed.
It is permitted to implement the compilation environment as the
evaluation environment or as part of it.

The term {\word minimal compilation\/} refers to actions the compiler
must take at compile time. These actions will be specified later.

The term {\word to process\/} refers to determining the time of
evaluation for a {\word form\/}, possibly evaluating that {\word
form\/} (if required), and performing minimal compilation.

The term {\word further compilation\/} refers to compilation beyond
minimal compilation. That is, processing does not imply complete
compilation. Further compilation is permitted to take place at run
time.

The term {\word compile time\/} refers to the duration of time that
the compiler is processing source code. At compile time, only the
compilation and evaluation {\word environments\/} are available.

The term {\word compile time definition\/} refers a definition in the
compilation environment. For example, when compiling a file, the
definition of a function must be retained in the compilation
environment if it is declared or proclaimed {\tt inline}. This
definition might not be available in the evaluation environment.

The term {\word run time\/} refers to the duration of time that the
loader is loading compiled code or compiled code is being executed.
At run time, only the run time {\word environment\/} is available.

The term {\word run time definition\/} refers to a definition in the
run time environment.

The term {\word run-time compiler\/} refers to {\function compile\/}
or implicit compilation, for which the compilation and run time {\word
environments\/} are maintained in the same Lisp (note that in this
case the run time and evaluation {\word environments\/} are the same).
The term {\word compiler\/} refers to both the run-time compiler and
{\function compile-file\/}.

\endsubSection%{Terminology}

\beginsubSection{Compilation Semantics}

% References:
%    Issue COMPILE-ENVIRONMENT-CONSISTENCY [pending]
%    Issue COMPILED-FUNCTION-REQUIREMENTS [pending]
% The material in this section will have to be updated to reflect further
% changes to these issues.

Conceptually, compilation is a process that traverses code, performs
certain kinds of syntactic and semantic analyses using information
(such as proclamations and {\word macro\/} definitions present in the
compile time {\word environment\/}), and produces modified code.

The compiler must perform the following actions, referred to as {\word
minimal compilation\/}:

\beginlist
\itemitem{\bull} All {\word macro\/} calls appearing as code
lexically within the code being compiled must be expanded at compile
time in such a way that they will not be expanded again at run time.
{\function macrolet\/} and {\function symbol-macrolet\/} are replaced
by {\word forms\/} corresponding to their bodies in which calls to
local {\word macros\/} are replaced by their expansions.

\itemitem{\bull}
The compiler must process {\function load-time-value\/} forms that
appear lexically within the program being compiled.  In the case of
{\function compile\/} the {\function load-time-value\/} form will be
evaluated at compile time, and its result will be treated as a
constant at run time.  In the case of {\function compile-file\/}, the
{\function load-time-value\/} form will be evaluated at load time.
\endlist

Additional constraints about the consistency of the compilation and
run time environments imply additional semantic constraints on
conforming programs that are intended to be compiled.  Conforming
programs obeying these constraints will have the same behavior whether
evaluated or compiled, and may be more portable. Some implementations
might impose looser constraints or no such constraints at all.

Except where noted, when a compile time and a run time definition are
different, an error of type {\datatype error\/} might be signalled.
In this case, it is implementation-dependent which definition will
prevail within the compiled code.

The following are the aforementioned semantic constraints:

\beginlist
\itemitem{\bull} Any {\word form\/} that is a {\datatype list\/} beginning
with a {\datatype symbol\/} that does not name a defined {\word
macro\/} or {\word special form\/} is a function call.  (This implies
that {\function setf\/} methods must be available at compile time.)

\itemitem{\bull} The definition of a function that is defined and
declared or proclaimed {\tt inline} in the compilation {\word
environment\/} will be retained at run time.

\itemitem{\bull} Within a named function, a recursive call to a
function of the same name refers to the same function, unless that
function has been declared {\tt notinline}.

\itemitem{\bull} A call to a named function that is defined in the
same file refers to that function, unless that function has been
declared {\tt notinline}.  The consequences are unspecified if
functions are redefined individually at run time or multiply defined
in the same file.

\itemitem{\bull} The argument syntax and number of return values for
all built-in Common Lisp functions will be the same at run time as at
compile time.  All built-in Common Lisp functions are proclaimed {\tt
inline}.

\itemitem{\bull} The argument syntax and number of return values for
all functions whose {\tt ftype\/} was declared at compile time will
remain the same at run time.

% Reference:  CLtL page 69
\itemitem{\bull} Constants defined with {\function defconstant\/} in
the compilation {\word environment\/} will retain the same value at
run time.  A reference to the name of a constant in source code is
equivalent to a reference to an {\word object\/} {\function eql\/} to
the value of the constant.

% The following paragraph from issue COMPILE-ENVIRONMENT-CONSISTENCY
%    seems likely to change:

\itemitem{\bull} Type definitions made with {\function deftype\/} or
{\function defstruct\/} in the compilation {\word environment\/} will
retain the same definition at run time.  Classes defined by {\function
defclass\/} in the compilation {\word environment\/} will be defined
at run time to have the same {\word superclasses\/} and same {\word
metaclass\/}.

This implies that {\word subtype/supertype\/} relationships of type
specifiers will not change between compile time and run time.  (Note
that it is permissible for an unknown {\word type\/} to appear in a
declaration at compile time, though a warning might be emitted in such
a case.)

% Ref:  CLtL page 153
\itemitem{\bull} Type declarations present in the compilation {\word
environment\/} accurately describe the values of the corresponding
variables and functions at run time; otherwise, the run time behavior
of the program is undefined.

\itemitem{\bull} A {\word function\/} defined in the
evaluation {\word environment\/} might have a different definition or
a different {\word signature\/} at run time, except in the situations
explicitly listed above.

\endlist

Conforming programs should not be written using any additional
assumptions about consistency between the compilation and run time
{\word environments\/}.

The presence of a call to a {\word function\/} that is not defined at
compile time will not cause an error to be signalled at compile time.

\endsubSection%
\beginsubSection{File Compilation}

The function {\function compile-file\/} performs compilation of {\word
forms\/} in a file following the rules specified in Compilation
Semantics'', and produces an output file that can be loaded with

Normally, the top-level forms appearing in a file compiled with
{\function compile-file\/} are executed only when the resulting
compiled file is loaded, and not when the file is compiled.  However,
some forms in the file must be evaluated at compile time so the
remainder of the file can be be read and compiled correctly.

The special form {\function eval-when\/} can be used to control
whether a {\word top-level\/} form is evaluated at compile time, load
time, or both.  It is possible to specify any of three situations with
{\function eval-when}, denoted by the symbols {\tt :compile-toplevel},
{\tt :load-toplevel}, and {\tt :execute}.  For toplevel {\function
eval-when\/} forms, {\tt :compile-toplevel} specifies that the
compiler must evaluate the body at compile time in the evaluation
{\word environment\/}, and {\tt :load-toplevel} specifies that the
compiler must arrange to evaluate the body at load time For
non-toplevel {\function eval-when} forms, {\tt :execute} specifies
that the body must be executed in the run time {\word environment\/}.

The behavior of this construct can be more precisely understood in
terms of a model of how {\function compile-file\/} processes forms in
a file to be compiled. There are two processing modes, called
not-compile-time'' and compile-time-too''.

Successive forms are read from the file by the {\function
compile-file} in not-compile-time mode; in this mode, {\function
compile-file\/} arranges for forms to be evaluated only at load time
and not at compile time.  When {\function compile-file} is in
compile-time-too mode, forms are evaluated both at compile time and

Processing of {\word top-level\/} forms in the file compiler is defined
as follows:

\beginlist
\itemitem{1.} If the form is a macro call, it is expanded and the
result is processed as a {\word top-level\/} form in the same
processing mode (compile-time-too or not-compile-time).

\itemitem{2.} If the form is a {\function progn\/} form, each of its
body {\word forms\/} is sequentially processed as a {\word
top-level\/} form in the same processing mode.

\itemitem{3.} If the form is a {\function locally\/}, {\function
macrolet\/}, or {\function symbol-macrolet\/}, {\function
compile-file\/} establishes the appropriate bindings and processes the
body forms as an implicit {\word top-level\/} {\function progn\/} with
those bindings in effect, in the same processing mode.  (Note that
this implies that the lexical {\word environment\/} in which {\word
top-level\/} forms are processed is not necessarily the null lexical
{\word environment\/}.)

\itemitem{4.} If the form is an {\function eval-when\/} form, it is
handled according to Figure {\chapno--\the\capno}.

\boxfig
{\dimen0=.75pc
\tabskip \dimen0 plus .5 fil
\offinterlineskip
\halign to \hsize {\strut#\hfil\tabskip \dimen0 plus 1fil&#\hfil\tabskip
\dimen0 plus .5 fil&#\hfil\tabskip \dimen0 plus 1fil&#\hfil\tabskip \dimen0 plus 1fil
&#\hfil&#\hfil&#\hfil\cr
\noalign{\vskip -11pt}
\hfil{\bf A} & {\bf B} & {\bf C} & {\bf D}& {\bf Action}& {\bf Mode}\cr
\noalign{\hrule}
Yes&Yes&\hfil---&\hfil---&Process&compile-time-too\cr
No&Yes&Yes&Yes&Process&compile-time-too\cr
No&Yes&Yes&No&ProcessÂ¬-compile-time\cr
No&Yes&No&\hfil---&ProcessÂ¬-compile-time\cr
Yes&No&\hfil---&\hfil---&Evaluate&\omit\cr
No&No&Yes&Yes&Evaluate&\omit\cr
\noalign{\vskip -9pt}
}}
\caption{{\function eval-when\/} processing}
\endfig

Column {\bf A} indicates whether {\tt :compile-toplevel} is specified.
Column {\bf B} indicates whether {\tt :load-toplevel} is specified.
Column {\bf C} indicates whether {\tt :execute} is specified.  Column
{\bf D} indicates whether the compiler is in compile-time-too mode.

The {\bf Action} column specifies one of three actions:

\beginlist

\item{}{\bf Process:} process the body as an implicit top-level
{\function progn\/} in the specified mode.

\item{}{\bf Evaluate:} evaluate the body as an implicit {\function
progn\/} in the dynamic execution context of the compiler, using the
evaluation {\word environment\/} as the global environment and the
lexical {\word environment\/} in which the {\function eval-when\/}
appears.

\endlist

\itemitem{5.} Otherwise, the form is a {\word top-level\/} form that
is not one of the special cases.  In compile-time-too mode, the
compiler first evaluates the form and then minimally compiles it.  In
not-compile-time mode, the {\word form\/} is simply minimally
compiled.  All subforms are treated as non-{\word top-level\/} forms.

Note that {\word top-level\/} forms are processed in the order in
which they textually appear in the file, and that each {\word
top-level\/} form read by the compiler is processed before the next is
read.  However, the order of processing (including macro expansion) of
subforms that are not {\word top-level\/} forms and the order of
further compilation is unspecified as long as Common Lisp semantics
are preserved.

\endlist

{\function eval-when\/} forms cause compile time evaluation only at
{\word top-level\/}.  Both {\tt :compile-toplevel\/} and {\tt
:load-toplevel\/} situation specifications are ignored for
non-toplevel forms. For non-toplevel forms, an {\function eval-when}
specifying the {\tt :execute} situation will be treated as if it were
a {\function progn} including the forms in the body of the {\function
eval-when}.

Figure {\chapno--\the\capno} lists macros that make definitions
available both in the compilation and run time {\word environments\/}.
It is not required that definitions made available to the compiler
this way be made available as if evaluated by the compiler in the
evaluation {\word environment\/}, nor is it required that be available
in subsequent compilation units or subsequent invocations of the
compiler.  As with {\function eval-when\/}, these compile time side
effects happen only when the defining macros appear at {\word
top-level\/}.

% The specific details of the compile time side effects should go under
% the description of the macro in chapters 6 & 7.
\boxfig
{\dimen0=.75pc
\tabskip \dimen0 plus .5 fil
\halign to \hsize {#\hfil\tabskip \dimen0 plus 1fil&#\hfil\tabskip \dimen0 plus
1fil&#\hfil\cr
\noalign{\vskip -9pt}
{\function    defconstant}&{\function    define-setf-method}&{\function    defsetf}\cr
{\function    defclass}&{\function    defmacro}&{\function    defstruct}\cr
{\function    defgeneric}&{\function    defmethod}&{\function    deftype}\cr
{\function    define-condition}&{\function    defpackage}&{\function    defvar}\cr
{\function    define-method-combination}&{\function    defparameter}&{\function    in-package}\cr
{\function    define-modify-macro}&{\function    defproclaim}&\cr
\noalign{\vskip -9pt}
}}
\caption{Defining macros}
\endfig
\endsubSection%{File Compilation}

% Reference: Issue QUOTE-SEMANTICS

The functions {\function eval\/} and {\function compile\/} are
required to insure that constants referenced within the resulting
interpreted or compiled code objects are {\function eql\/} to the
corresponding objects in the source code.  {\function compile-file\/},
on the other hand, must produce an output file which, when loaded with
{\function load\/}, constructs the {\word objects\/} defined by the
source code and produces references to them.

In the case of {\function compile-file\/}, {\word objects\/}
constructed by {\function load\/} of the output file cannot be spoken
of as being {\function eql\/} to {\word objects\/} constructed at
compile time, because the compiled file may be loaded into a different
Lisp image than the one in which it was compiled.  This section
defines the concept of {\word similarity as constants\/} which relates
{\word objects\/} in the the compile time {\word environment\/} to the
corresponding {\word objects\/} in the load time {\word
environment\/}.

The constraints on constants described in this subsection apply only
to {\function compile-file\/}; {\function eval\/} and {\function
compile\/} are not permitted to copy or coalesce constants.

\beginsubSection{Constants}

An {\word object\/} can be used as a quoted constant processed by
{\function compile-file\/} if the resulting constant established by
loading the compiled file is {\word similar as a constant\/} to the
original.

The notion of similarity as a constant is not defined on all {\word
types\/}.  Conforming implementations are required to handle such
{\word objects\/} by having the compiler and loader reconstruct an
equivalent copy of the {\word object\/} in some
implementation-specific manner, or by having the compiler signal an
error of type {\datatype error\/}.  A conforming portable program must
not use {\word objects\/} of these {\word types\/} as constants in
code to be processed with {\function compile-file\/}.

The definition of {\word similar\/} is in terms of the relationship
of {\word dissimilarity\/}.

Two {\word objects\/} are dissimilar if and only if they are not
{\function eql} and one of the following holds: they are not of the
same {\word type\/}, they are of the same {\word type\/} but are not
of a {\word type\/} listed below, or they are of the same {\word
type\/} and satisfy the additional requirements listed for that type
as follows:

\beginlist

\item{} {\bf array:} they have different dimensions or they have the
same dimension and satisfy whichever of the following is appropriate:

\beginlist
\item{}{\bf one-dimensional array:} the values of one of the following
attributes are dissimilar: {\function length\/}, {\function
array-element-type\/}, and {\function elt\/} for all valid indices.

\item{}{\bf multi-dimensional array:} the values of one of the
following attributes are dissimilar: {\function array-element-type\/}
and {\function aref\/} for all valid indices.

\endlist

\item{}{\bf character:} they represent different characters

\item{}{\bf cons:} the values of their {\word car\/} components are
dissimilar or the values of their {\word cdr\/} components are
dissimilar

\item{}{\bf hash table:} either they have different tests or for all
one-to-one correspondences between the keys of the two tables, either
the corresponding keys are dissimilar or the corresponding values are
dissimilar.

\item{}{\bf number:} they represent different mathematical values

\item{}{\bf package:} their names are dissimilar as {\datatype
strings\/}

\item{}{\bf pathname:} they have a component whose values are
dissimilar

\item{}{\bf random state:} they produce different sequences of
numbers when {\function random} is repeatedly applied to them

\item{}{\bf string:} they are dissimilar as arrays

\item{}{\bf symbol:} one of them is interned and they are not
{\function eql}, or both are uninterned and their print names are
dissimilar as {\datatype strings\/}

\endlist

Note that two {\word objects\/} are dissimilar if there is a point of
dissimilarity between them.

Two objects are {\word similar\/} is and only if they are not {\word
dissimilar\/}.

If two constants appearing in the source code for a single file
processed with {\function compile-file\/} are {\function eql\/}, the
corresponding constants in the compiled code must also be {\function
eql\/}.
% Reference:  issue CONSTANT-COLLAPSING
However, if two {\word objects\/} are {\function eql\/} in the
compiled code, the corresponding {\word objects\/} in the source code
might not have been {\function eql\/}.  {\function compile-file\/} is
permitted to coalesce constants appearing in the source code if they
are similar as constants, except if the {\word objects\/} involved are
of type {\datatype symbol\/}, {\datatype package\/}, or {\datatype
structure\/}.  {\word Objects\/} of these {\word types\/} are never
coalesced.  In addition, the following are constraints on the handling
of constants during compilation using {\function compile-file}:

\beginlist

\item{}{\bf array:} If an {\datatype array\/} in the source code is a
{\datatype simple-array\/}, then the corresponding {\datatype array\/}
in the compiled code will also be a {\datatype simple-array\/}.  If
the {\datatype array\/} in the source code is displaced, has a {\word
fill pointer\/}, or is adjustable, the corresponding {\datatype
array\/} in the compiled code might lack any or all of these
qualities. If an {\datatype array\/} in the source code has a fill
pointer, then the corresponding {\datatype array\/} in the compiled
code might be only the size implied by the fill pointer.

\item{}{\bf function:} Issue CONSTANT-FUNCTION-COMPILATION specifies
how the compiler and loader handle constant {\datatype functions\/}.

\item{}{\bf hash table:} Two {\datatype hash tables\/} are similar if
there is a one-to-one correspondence between the keys of the two
tables such that the corresponding keys and values are similar.  If
there is more than one such one-to-one correspondence between the
keys of the two tables, the consequences are unspecified if the tables
are coalesced.  Conforming code to be processed with {\function
compile-file\/} must not use a {\datatype hash table\/} as a constant
if it is not possible to construct a similar table with more than one
such one-to-one correspondence with the original.

\item{}{\bf packages:} The loader is required to find the
corresponding {\datatype package\/} object as if by calling {\function
find-package\/} with the package name as an argument.  An error of
type {\datatype package-error\/} is signalled if no {\datatype
package\/} of that name exists at load time.

\item{}{\bf random-state:} A constant {\datatype random-state\/}
object cannot be used as the state argument to the function {\function
random\/} because {\function random\/} modifies this data structure.

\item{}{\bf structure, standard-object:}
% Reference: issue LOAD-OBJECTS
{\word Objects\/} of type {\datatype structure\/} and {\datatype
standard-object\/} may appear in compiled constants if there is an
appropriate {\function make-load-form\/} method defined for that
{\word type\/}.

{\function compile-file\/} calls {\function make-load-form\/} on any
{\word object\/} that is referenced as a constant or as a
self-evaluating form, if the {\word object's metaclass\/} is
{\datatype standard-class\/}, {\datatype structure-class\/}, any
user-defined {\word metaclass\/} that is not a {\word subclass\/} of
{\datatype built-in-class\/}, or any of a possibly empty
implementation-defined list of other {\word metaclasses\/}.
{\function compile-file\/} will call {\function make-load-form\/} once
for any given {\word object\/} within a single file.

\item{}{\bf symbol:} Issue COMPILE-FILE-SYMBOL-HANDLING defines how
{\function compile-file\/} and the loader handle interned {\datatype
symbols\/}.

\endlist

\beginsubSection{Compile Time Error Handling}
% Reference:  Issue COMPILER-DIAGNOSTICS
% The STYLE-WARNING condition needs to be integrated into the section
%     describing the hierarchy of condition types.

{\function compile\/} or {\function compile-file\/} are permitted to
issue errors and warnings, including errors due to compile-time
processing of {\tt (eval-when (:compile-toplevel) ...) \/} forms,
macro expansion, and conditions signalled by the compiler itself.

Conditions of type {\datatype error\/} might be signalled by the
compiler in situations where the compilation cannot proceed without
intervention.

In addition to situations for which the standard specifies that
conditions of type {\datatype warning\/} must or might be signalled,
warnings might be signalled in situations where the compiler can
determine that the results have undefined consequences or that a run
time error will be signalled.  Examples of this situation are as
follows: violating type declarations, altering or assigning the value
of a constant defined with {\function defconstant\/}, calling built-in
Lisp functions with a wrong number of arguments or malformed keyword
argument lists, referencing a variable declared {\tt ignore\/}, and
using unrecognized declaration specifiers.

The compiler is permitted to issue warnings about matters of
programming style as conditions of type {\datatype style-warning\/}.
Examples of this situation are as follows: redefining a function using
a different argument list, calling a function with a wrong number of
arguments, not declaring {\tt ignore\/} of a local variable that is
not referenced, and using declaration specifiers described in the
standard but ignored by the compiler.

Both {\function compile\/} and {\function compile-file\/} are allowed
to establish a default condition handler.  If such a condition handler
is invoked, it must first resignal the {\datatype condition\/} to
allow user-established handlers to handle it.  If all error handlers
decline, the default handler may handle the {\datatype condition\/} in
an implementation-specific way.

% Reference:  issue WITH-COMPILATION-UNIT

Some warnings might be deferred until the end of compilation. See
{\function with-compilation-unit\/}.

\endsubSection%{Introduction}
\endSection
\endChapter

\bye