Issue: COMPILER-DIAGNOSTICS (Version 5)

[Dan L. Pierson <pierson@mist.encore.com>]

Note that I've copied the "Forum" header item from Guy.

Forum:	    	Compiler
Issue:		COMPILER-DIAGNOSTICS
References:	CLtL p. 438-439
		Condition System, Revision #18
		S:>KMP>cl-conditions.text.34
		Issue GC-MESSAGES
		Issue RETURN-VALUES-UNSPECIFIED
		Issue COMPILER-VERBOSITY
Category:	CLARIFICATION, ENHANCEMENT
Edit History:   V1, 15 Oct 1988, Sandra Loosemore
		V2, 19 Oct 1988, Sandra Loosemore (minor fixes)
		V3, 25 Oct 1988, Sandra Loosemore (input from Pitman & Gray)
		V4, 01 Nov 1988, Sandra Loosemore (fix typos)
		V5, 15 Dec 1988, Sandra Loosemore
		                 Dan L. Pierson   (new condition types)


Problem Description:

It is unclear whether various diagnostics issued by the compiler are 
supposed to be true errors and warnings, or merely messages.

In some implementations, COMPILE-FILE handles even serious error
situations (such as syntax errors) by printing a message and then
trying to recover and continue compiling the rest of the file, rather
than by signalling an error.  While this user interface style is just
as acceptable as invoking the debugger, it means that a normal return
 from COMPILE-FILE does not necessarily imply that the file was
successfully compiled.

Many compilers issue warnings about programming style issues (such as
binding a variable that is never used but not declared IGNORE).
Sometimes these messages obscure warnings about more serious problems,
and there should be some way to differentiate between the two.  For
example, it should be possible to suppress the style warnings.

Also, neither CLtL nor issue RETURN-VALUES-UNSPECIFIED states what the 
return value from COMPILE-FILE should be.


Proposal COMPILER-DIAGNOSTICS:USE-HANDLER:

(1) Clarify that COMPILE-FILE is allowed to print messages to
    *STANDARD-OUTPUT* indicating the normal progress of the compilation.
    (See issue COMPILER-VERBOSITY.)

(2) Clarify that both ERROR and WARNING conditions may be signalled within
    COMPILE or COMPILE-FILE, including arbitrary errors which may occur
    due to compile-time processing of (EVAL-WHEN (COMPILE) ...) forms or
    macro expansion.

    Considering only those conditions signalled -by- the compiler (as
    opposed to -within- the compiler),

    (a) Conditions of type ERROR may be signalled by the compiler in
	situations where the compilation cannot proceed without
	intervention.

	Examples:
	    syntax errors

    (b) Conditions of type WARNING may be signalled by the compiler in 
	situations where the standard explicitly states that a warning must,
	should, or may be signalled; and where the compiler can determine 
	that a situation that "is an error" would result at runtime.

	Examples:
	    violation of type declarations
	    SETQ'ing a constant defined with DEFCONSTANT
	    calls to built-in Lisp functions with wrong number of arguments
	    referencing a variable declared IGNORE

    (c) Add a new subtype of CONDITION named MESSAGE, with a subtype NOTICE.
    	Specify that the default handler for conditions of type MESSAGE
	simply prints the message datum and continues.  Add a new standard
	restart function MUFFLE-MESSAGE analogous to MUFFLE-WARNING. 

    (d) All other diagnostics issued by the compiler should be conditions
	of type NOTICE.  In particular, this category includes all
	diagnostics about matters of programming style.  Although
	conditions of type NOTICE -may- be signalled in these situations, 
	no implementation is -required- to do so.  However, if an
	implementation does choose to signal a condition, that condition
	will be of type NOTICE.

	Examples:
	    redefinition of function with different argument list
	    unreferenced local variables not declared IGNORE

(3) Require COMPILE-FILE to establish an error handler.  Add a :HANDLER
    keyword argument to COMPILE-FILE, which is a user condition
    handler function which is to be used during compilation.  If the
    user error handler is not supplied or declines to handle a condition,
    then the compiler's error handler will be invoked.  Require the
    compiler's error handler to handle the ABORT restart by aborting
    the smallest feasible part of the compilation.

(4) Specify that COMPILE-FILE returns three values.  The first value is the
    truename of the output file, or NIL if the file could not be created.
    The second value is non-NIL if errors were signalled during compilation
    (indicating that the output file is almost certainly unusable).  The
    third value is non-NIL if warnings were signalled during compilation
    (indicating that the output file may or may not be usable).

(5) Clarify that COMPILE does not establish a condition handler.  Instead,
    it uses whatever condition handler has been established in the environment
    from which it is called.


Rationale:

Point by point,

(1) This reflects current practice.

(2) Conditions such as syntax errors which are errors in the interpreter
    remain errors in the compiler.  The division of other conditions
    into WARNINGs and NOTICEs allows potentially serious problems to be
    distinguished from mere kibbitzing on the part of the compiler.

(2c) The new condition types MESSAGE and NOTICE are structured to allow
     this part of the condition hierarchy to be further extended.  In
     particular, the issue COMPILER-VERBOSIY proposes an additional
     subtype of MESSAGE named INFO.  Note that an analogue to
     *BREAK-ON-WARNINGS* is not needed because MESSAGE conditions
     "never" cause a break (i.e. not unless a user-defined handler
     causes one).

(3) It is reasonable for the default handling of compiler errors not to
    cause the debugger to be invoked.  However, any error handler 
    established by COMPILE-FILE would override handlers established by the
    user in the surrounding environment.

    Requiring the compiler's error handler to handle the ABORT restart
    reflects what several implementations already do (although probably not
    using this mechanism).  The intent of the wording is to allow an
    implementation to abort the entire file compilation if it is not 
    feasible to abort a smaller part.

(4) This allows users to determine whether or not COMPILE-FILE is able to
    actually compile the file successfully.  Returning several values is
    is more useful than a single success/failure value because there are
    several degrees of failure.

(5) This is to reflect the use of COMPILE-FILE as being more "batch"-oriented
    and COMPILE as being more interactive.  There is less motivation to have
    COMPILE try to recover from errors without user interaction.


Current Practice:

No implementation behaves exactly as specified in this proposal.

In VaxLisp, COMPILE-FILE handles most compile-time errors without
invoking the debugger.  (It gives up on that top-level form and moves on
to the next one.)  Instead of signalling errors or warnings, it simply
prints them out as messages.

In Lucid Common Lisp, COMPILE-FILE invokes the debugger when it encounters
serious problems.  COMPILE-FILE returns the pathname for the output file.

Symbolics Genera usually tries to keep compiling when it encounters errors;
so does Symbolics Cloe.

On the TI Explorer, the compiler tries to catch most errors and turn
them into warnings (except for errors on opening a file), but the user
can change special variable COMPILER:WARN-ON-ERRORS to NIL if he wants
to enter the debugger on an error signalled during reading, macro
expansion, or compile-time evaluation.  The true name of the output
file is returned as the first value.  A second value indicates whether
any errors or warnings were reported.


Cost to implementors:

The cost to implementors is not trivial but not particularly high.  This
proposal tries to allow implementations considerable freedom in what
kinds of conditions the compiler must detect and how they are handled,
while still allowing users some reasonably portable ways to deal with
compile-time errors.


Cost to users:

This is a compatible extension.  This proposal may cause users to see
some small differences in the user interface to the compiler, but
implementations already vary quite widely in their approaches.  Some
users will probably have to make some minor changes to their code.


Benefits:

Users are given a way to detect and handle compilation errors, which
would simplify the implementation of portable code-maintenance
utilities.  The behavior of the compiler in error situations is made
more uniform across implementations.


Discussion:

The issue of normal progress messages from the compiler is discussed
in more detail in a separate issue, COMPILER-VERBOSITY.

Pitman says that he would like to require COMPILE-FILE's error handler
never to invoke the debugger.  I have left that out of this proposal
because it seems like an unnecessary restriction; if users want to ensure
that kind of behavior it is possible to do so by supplying a user error 
handler.  (Of course, the converse is also true.)

Sections 2b and 2d need more work.  In CLtL, everything has been lumped
together as warnings, but there seems to be general agreement that
some things (like complaints about unused variables) should really be
notices instead.  Basically we need to go through and find every place
where CLtL says that the compiler might issue a warning and decide what
category it belongs in, and list it here.

If the condition system is integrated with CLOS or otherwise comes to
support multiple inheritance, we might consider introducing a
COMPILER-CONDITION that can be used in mixins with the other condition
types, so that error handlers can distinguish between errors signalled
by the compiler itself and errors signalled during macroexpansion or
EVAL-WHEN processing.

Gray would like to exclude errors resulting from failure to open the
input and output files from the compiler's error handling.  The
proposal should probably be specific about this, one way or the other.