#

## Issue COMPILER-DIAGNOSTICS Writeup

    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)
                    V12, 21-Jun-89, Moon (changes to point 4 only: return a
                            status value from COMPILE also, make the status
                            value provide more detail)
    		V13, 22-Jun-89, Loosemore (fix one of the fixes)
    		V14, 04-Jul-89, Loosemore (amendments from June meeting)
    Status:         Passed V11 March 89
    		Passed V14 June 89

    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 permitted (but not
        required) to establish a handler for ERROR.  For example, they
        might issue a warning, and restart compilation from some
        implementation-dependent point in order to let the compilation
        proceed without manual intervention.

    (4) Specify that COMPILE and COMPILE-FILE return three values.  The first
        value from COMPILE is not changed by this proposal.  The first value
        from COMPILE-FILE is the truename of the output file, or NIL if the
        file could not be created.

        The second value is NIL if no compiler diagnostics were issued, and
        true otherwise.

        The third value is NIL if no compiler diagnostics other than style
        warnings were issued.  A non-NIL value indicates that there were
        "serious" compiler diagnostics issued, or that other conditions of
        type ERROR or WARNING (but not STYLE-WARNING) 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.

    The second and third return values from COMPILE and COMPILE-FILE give
    some indication of whether there were serious problems encountered in
    compiling the file.

    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.

Copyright 1996-2005, LispWorks Ltd. All rights reserved.