issue COMPILER-VERBOSITY, version 4

[sandra%defun@cs.utah.edu (Sandra J Loosemore)]

Forum:	    	Compiler
Issue:		COMPILER-VERBOSITY
References:	CLtL p. 438-329; 426
		issue COMPILER-DIAGNOSTICS
Category:	CHANGE/CLARIFICATION/ENHANCEMENT
Edit History:   V1, 25 Oct 1988, Sandra Loosemore
    	    	V2, 12 Dec 1988, Dan L. Pierson (add USE-CONDITIONS)
    	    	V3, 15 Dec 1988, Dan L. Pierson (expand on conditions)
    	    	V4, 21 Dec 1988, Dan L. Pierson (reword and clarify)


Problem Description:

Implementations vary widely in the amount of information that is printed
out by COMPILE-FILE.  In some situations, it would be useful to control
how much information is printed.


Proposal COMPILER-VERBOSITY:LIKE-LOAD:

Introduce a special variable, *COMPILE-VERBOSE*, with an implementation-
dependent initial value.

Add :VERBOSE and :PRINT keyword arguments to the function COMPILE-FILE,
analogous to those for the function LOAD.

The :VERBOSE argument (which defaults to the value of *COMPILE-VERBOSE*),
if true, permits COMPILE-FILE to print a message in the form of a comment
to *STANDARD-OUTPUT* indicating what file is being compiled and other
useful information.

The :PRINT argument (which defaults to NIL), if true, causes
information about top-level forms in the file being compiled to be
printed to *STANDARD-OUTPUT*.  Exactly what is printed will vary from
implementation to implementation, but nevertheless some information
will be printed.


Rationale:

This proposal makes COMPILE-FILE behave like LOAD.  There is already
some precedent for doing this (for example, issue COMPILE-FILE-PACKAGE,
which makes COMPILE-FILE as well as LOAD rebind *PACKAGE*).


Current Practice:

Lucid provides a :MESSAGES keyword argument to COMPILE-FILE, which can
either be a stream to send progress messages to, or NIL to suppress messages.
The default value is T, which sends messages to "the standard terminal
device".

On the TI Explorer, COMPILE-FILE displays the name of the function being
compiled when the option :VERBOSE T is given or special variable
COMPILER:COMPILER-VERBOSE is true.  (In other words, they use :VERBOSE
to mean what this proposal says to use :PRINT for.)


Cost to implementors:

This is an incompatible change for some implementations.  While the
changes required should be conceptually simple, their implementation
may involve a significant amount of grunt work.  At least two
implementations already provide some similar mechanism for suppressing
messages.


Cost to users:

Some (non-portable) user code may break in implementations where this is
an incompatible change.

Specifying that the :PRINT argument defaults to NIL is consistent with
LOAD, but in most implementations the default now is to print out a
lot of information about each function or top-level form.  Some users
may find it irritating to have to type in :print t to get the same
amount of information they're used to seeing.


Benefits:

Users are given a portable way to control how much information is printed
by COMPILE-FILE.




Proposal COMPILER-VERBOSITY:USE-CONDITIONS:

Add the new subtype of CONDITION, NOTICE, defined in
COMPILER-DIAGNOSTICS (V5).  Add a new subtype of NOTICE, INFO.
Require compilers to "print" all messages covered by this proposal by
using the function NOTICE to signal a condition of type INFO instead
of directly writing the message.  For the purposes of this proposal
"compilers" refers to both COMPILE and COMPILE-FILE.

Note that, since a compiler is never required to print any messages
covered by this proposal, no portable program may assume that any
conditions of type INFO will actually be signalled.

Rationale:

This allows informational compiler messages and compiler diagnostics
to be handled in a uniform manner with a simple, well defined way for
the user to gain any desired degree of control over these messages.

Current Practice:

No one currently controls compiler messages via the condition system.

Cost to implementors:

This is an incompatible change for all implementations.  It should be
a conceptually simple change to make once an implementation supports
the condition system, however the actual implementation of the change
may involve a significant amount of grunt work.

All existing implementations can continue support their current
message control interfaces as long as the implementation of their
current interface is changed to comply with this proposal.  This could
be done by:

    1. Causing the old interface to either establish a condition
       handler that accepts messages that shouldn't be printed and
       does nothing with them.  Note that it would not be legal to
       make the handler print the messages that should be printed,
       because a user handler must still be given a chance to look at
       them. 

    2. Changing the old interface to conditionally write the message
       as it used to, except that NOTICE is used to actually write the
       message. 

Cost to users:

Some user code may break in implementations which remove any
(non-portable) existing mechanisms to control compiler output.

Benefits:

Users are given a portable way to control how much information is printed
by COMPILE-FILE.

Aesthetics:

Using a well defined, already existing, general mechanism is more
aesthetically pleasing than adding another ad-hoc flag or special
variable. 



Discussion:

Rather than just treating :PRINT and :VERBOSE as boolean values, it
might be useful to have them convey more information.  For example,
Pitman has suggested using keyword values like :BRIEF or :DETAILED to
allow varying amounts of information of each type to be printed.
Alternatively, it might be reasonable to follow Lucid's precedent to
allow the values of :PRINT and :VERBOSE to be streams to allow
messages to be directed somewhere other than *STANDARD-OUTPUT*.
Either of these suggestions could reasonably be made to apply to LOAD
as well, but the intent of LIKE-LOAD is to make COMPILE-FILE
behave like LOAD, not to change the specification of LOAD.

Loosemore believes that using conditions for this purpose is not
appropriate, because this issue deals with messages indicating the
normal progress of the compiler and conditions are supposed to be used
to signal exceptional (non-ordinary) situations.

Pierson believes that conditions provide a well defined, portable,
non-intrusive interface for user control of infrequent events.  While
the use of conditions is not notably efficient, compiler informational
messages are sufficiently infrequent that this should not impose a
noticeable performance penalty.

Pierson would like to see LOAD, etc. changed to also use this
interface. 

The two proposals are not mutually incompatible in that the LIKE-LOAD
keywords can be added to an implementation whether or not it is based
on USE-CONDITIONS.

-------