Issue PROCLAIM-ETC-IN-COMPILE-FILE

[David N Gray <Gray@DSG.csc.ti.com>]

Here's a first attempt at resolving another item from the backlog of known
problem areas.

 
Issue:		PROCLAIM-ETC-IN-COMPILE-FILE
References:	CLtL p. 182 [package functions],
		  p. 156 [PROCLAIM], P. 188 [REQUIRE], 
		  p. 439 [COMPILE-FILE];
                Issue COMPILE-FILE-HANDLING-OF-TOP-LEVEL-FORMS
Category:	CLARIFICATION
Edit History:   15 Sept. 88, V1 by David Gray
Status:		For preliminary discussion 
 
Problem Description:

  Page 182 of CLtL says that COMPILE-FILE needs to treat top-level calls
  to the following package functions as though they were wrapped in an
  (EVAL-WHEN (COMPILE LOAD EVAL) ...):

    EXPORT  IMPORT  IN-PACKAGE  MAKE-PACKAGE SHADOW
    SHADOWING-IMPORT  UNEXPORT  UNUSE-PACKAGE  USE-PACKAGE

  There are other things that need special handling by the compiler that
  are not explicitly specified by CLtL.  The proposal
  COMPILE-FILE-HANDLING-OF-TOP-LEVEL-FORMS:CLARIFY addresses the part of
  the problem pertaining to macros that define things.  The following
  proposal adds PROCLAIM and REQUIRE to the list of functions needing
  special handling.
 
Proposal PROCLAIM-ETC-IN-COMPILE-FILE:CLARIFY:
 
  Clarify that when COMPILE-FILE encounters a call to one of the following
  functions at top level in a file, the form will be evaluated at compile
  time as well as at load time:

    EXPORT  IMPORT  IN-PACKAGE  MAKE-PACKAGE  PROCLAIM  REQUIRE  SHADOW
    SHADOWING-IMPORT  UNEXPORT  UNUSE-PACKAGE  USE-PACKAGE

  Note that the compile-time evaluation of these package functions can
  affect the way that the remaining top-level forms in the file are read.

  In the case of PROCLAIM, it is implementation-dependent whether the
  evaluation affects the global environment or is only recorded in data
  structures used by the compiler, and whether the effect of the
  evaluation remains in the global environment after COMPILE-FILE returns.

  (PROCLAIM '(OPTIMIZE ...)) is a special case that is evaluated only at
  compile-time and not at load time, and that affects only the current
  file being compiled.

  Note that the behavior specified here can still be altered by the
  user by wrapping an explicit EVAL-WHEN around the form.

 Rationale:

  Experience seems to have shown that this behavior best matches what
  people expect to have happen.  The examples on pages 189 and 191 of CLtL
  won't work right unless REQUIRE takes effect at compile-time.  Since
  most of the things that PROCLAIM can be used for only affect the
  compiler, it doesn't make much sense for the compiler to not take notice
  during compilation.  Optimization control is something that one usually
  wants to control locally, rather that having a proclamation in one file
  affect other unrelated files compiled later.
 
 Current Practice:

  This proposal follows what the Explorer does, except that (EVAL-WHEN
  (LOAD) (PROCLAIM '(OPTIMIZE ...))) doesn't do anything.  The Symbolics
  compiler has special top-level handling for all of these functions,
  although the details are not clear.  The Lucid documentation indicates
  that certain functions at top-level are treated as though within an
  (EVAL-WHEN (EVAL COMPILE LOAD) ...): REQUIRE, all of the package
  functions listed above, INTERN, and UNINTERN; it is not clear what
  happens with PROCLAIM.

 Cost to implementors:

  Since implementations are already required to have a mechanism for
  compile-time handling of the package functions, it should only require
  minor adjustments to add handling for PROVIDE and REQUIRE if they aren't
  handled already.  The main thing that most implementations would need to
  do is to make OPTIMIZE proclamations local to the file, but that should
  be fairly simple.

 Cost to users:

  If someone has a use of REQUIRE that they want to only be a load-time
  dependency and their implementation did not previously do REQUIRE at
  compile-time, they may want to wrap (EVAL-WHEN (EVAL LOAD) ...) around
  it.

  If someone has a use of (PROCLAIM '(OPTIMIZE ...)) that they really want
  to be global, they would need to wrap (EVAL-WHEN (EVAL COMPILE LOAD)
  ...) around it.
  
 Benefits:

  Users will know what to expect when they use PROCLAIM and REQUIRE.
  
 Costs of Non-Adoption: 

  In order to write programs that would be sure to be portable, the user
  would have to wrap an (EVAL-WHEN (EVAL COMPILE LOAD) ...) around each use
  of PROCLAIM or REQUIRE in order to be sure of what will happen.

 Aesthetics:

  Programs look cleaner if EVAL-WHEN is only needed for unusual cases
  instead of being required for the normal cases.
 
 Discussion:

  Cleanup proposal PROCLAIM-SCOPE:ADD-KEYWORD-PERVASIVE wanted to add an
  option to PROCLAIM to control whether the effect is local to the current
  file.  That may be better handled by an extension to EVAL-WHEN since
  that kind of control might be wanted for definitions as well as
  proclamations.  If the handling of OPTIMIZE specified here is taken as a
  default, that issue can be pursued separately from this one.