Issue: COMPILER-DIAGNOSTICS (Version 11)

[Kent M Pitman <KMP@STONY-BROOK.SCRC.Symbolics.COM>]

This has the change to make it conform to what we actually voted on:
 - strike sentence 1 of item 3 per X3J13.
Everything else is as before.

-----
Forum:		Compiler
Issue:		COMPILER-DIAGNOSTICS
References:	CLtL p. 438-439, 62, 69, 160, 161
		Condition System, Revision #18
	    	S:>KMP>cl-conditions.text.34
	    	Issue GC-MESSAGES
	    	Issue RETURN-VALUES-UNSPECIFIED
	    	Issue COMPILER-VERBOSITY
		Issue CONDITION-RESTARTS
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, Dan L. Pierson   (new condition types)
	   	V6, 15 Dec 1988, Sandra Loosemore (additions, fix wording)
	    	V7, 16 Dec 1988, Dan L. Pierson   (minor cleanup)
		V8, 07 Jan 1989, Sandra Loosemore (expand discussion)
		V9, 26 Jan 1989, Sandra Loosemore (simplify)
		V10, 22 Mar 1989, Sandra Loosemore (error terminology)
	        V11, 11 Apr 1989, Kent Pitman (changes per X3J13)
Status:		Ready for release
     
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) Introduce a new condition type, STYLE-WARNING, which is a subtype
    of WARNING.

(2) Clarify that 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:
	    file open errors
   	    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 with undefined consequences or that would cause
        an error to be signalled would result at runtime.

        Examples:
	    violation of type declarations
	    SETQ'ing or rebinding a constant defined with DEFCONSTANT
	    calls to built-in Lisp functions with wrong number of arguments
	        or malformed keyword argument lists
	    referencing a variable declared IGNORE
	    unrecognized declaration specifiers

    (c) The compiler is permitted to signal diagnostics about matters of
        programming style as conditions of type STYLE-WARNING.  Although 
        STYLE-WARNINGs -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 STYLE-WARNING and will be signalled by a call to 
        the function WARN.

        Examples:
	    redefinition of function with different argument list
	    calls to function with wrong number of arguments
	    unreferenced local variables not declared IGNORE
	    declaration specifiers described in CLtL but ignored by 
	        the compiler

(3) State that both COMPILE and COMPILE-FILE are allowed to establish 
    a default condition handler.  If such a condition handler is 
    established, however, it must first resignal the condition to give any
    user-established handlers a chance to handle it.  If all user error
    handlers decline, the default handler may handle the condition in an
    implementation-specific way; for example, it might turn errors into
    warnings.

(4) Specify that COMPILE-FILE returns two values.  The first value
    is the truename of the output file, or NIL if the file could not be
    created.  The second value is T if the file was compiled without
    errors, or NIL if errors were signalled during compilation.


Rationale:

Introducing the STYLE-WARNING condition allows handlers to distinguish
between potentially serious problems and mere kibitzing on the part of
the compiler.

Requiring any condition handlers established by the compiler to resignal
the condition before proceeding with any implementation-specific action
gives user error handlers a chance to override the compiler's default
behavior.  For example, the user error handler could invoke a restart
such as ABORT or MUFFLE-WARNING.

Requiring the compiler 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 compilation if it is not feasible to abort a
smaller part.

Requiring a second success-p value to be returned from COMPILE-FILE
gives the user some indication of whether there were serious problems
encountered in compiling the file.


Test Case/Example:

Here is an example of how COMPILE-FILE might set up its condition
handlers.  It establishes an ABORT restart to abort the compilation
and a handler to take implementation-specific action on ERROR
conditions.  Note that INTERNAL-COMPILE-FILE may set up additional
ABORT restarts.

    (defvar *output-file-truename* nil)

    (defun compile-file (input-file &key output-file)
      (let ((*output-file-truename*    nil)
 	    (errors-detected           nil))
	(with-simple-restart (abort "Abort compilation.")
	  (handler-bind ((error  #'(lambda (condition)
				     (setq errors-detected t)
				     (signal condition)
				     ...)))
	    (internal-compile-file input-file output-file)))
	(values *output-file-truename*
		errors-detected)))



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.

IIM Common Lisp's compiler handles errors using a resignalling mechanism
similar to what is described here.


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.

Adding the STYLE-WARNING type may cause conflicts with programs
already using that name.


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 whether the compiler may print normal progress messages
is discussed in detail in a separate issue, COMPILER-VERBOSITY.

Explicit calls to ERROR don't really justify warnings to be signalled
at compile-time, but we assume implementors have some common sense
about when it's appropriate to do so.

Proposal CONDITION-RESTARTS:PERMIT-ASSOCIATION would make it illegal
for conditions to be resignalled.  If that proposal is accepted, the
wording here would have to be changed to indicated that the compiler's
condition handler makes a copy of the condition and signals that.

Moon says:

  I think [requiring the ABORT restart to be handled] is wrong.  The only
  documentation of the ABORT restart that I could find says
  
    The purpose of the ABORT restart is generally to allow return to the
    innermost ``command level.''
  
  I agree with this, and I believe it means that it is wrong for any
  function other than one that establishes a read-eval-print loop or
  a command-level to establish an ABORT restart.  It would be useful
  to have some restart that aborts a portion of the compilation, but
  it should be given some other name.