#

## Issue PROCLAIM-ETC-IN-COMPILE-FILE Writeup

    Issue:		PROCLAIM-ETC-IN-COMPILE-FILE
    References:	CLtL p. 182 [package functions],
    		  p. 156 [PROCLAIM], p. 439 [COMPILE-FILE];
                    Issue COMPILE-FILE-HANDLING-OF-TOP-LEVEL-FORMS
    		Issue IN-PACKAGE-FUNCTIONALITY
    		Issue EVAL-WHEN-NON-TOP-LEVEL
    		Issue DEFINING-MACROS-NON-TOP-LEVEL
    Category:	CLARIFICATION, CHANGE, ADDITION
    Edit History:   15 Sep 88, V1 by David Gray
                    23 Sep 88, V2 by Sandra Loosemore (summarize discussion)
    		11 Mar 89, V3 by Sandra Loosemore (rewrite)
    		13 Mar 89, V4 by Sandra Loosemore (discussion)
    Status:		**DRAFT**

    Problem Description:

      Should the compiler treat top-level calls to PROCLAIM specially?

      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

      CLtL is silent on whether top-level calls to PROCLAIM should also be
      evaluated at compile-time, which presumably means they shouldn't be.
      However, some implementations do evaluate PROCLAIM at compile-time.

      In the model of how COMPILE-FILE works that is presented in issues
      EVAL-WHEN-NON-TOP-LEVEL and DEFINING-MACROS-NON-TOP-LEVEL, the special
      form EVAL-WHEN is the only thing that can cause compile-time evaluation
      to occur.  The compile-time side-effects of macros such as DEFMACRO
      and DEFPACKAGE are explained by having them include EVAL-WHEN in their
      expansions.  Any functions that are treated specially, however, must
      be included as special cases in the compiler.

      Proposal IN-PACKAGE-FUNCTIONALITY:NEW-MACRO would remove the
      requirement that the package functions be treated specially.  Do we
      wish to make an exception to the model for PROCLAIM?

    Proposal PROCLAIM-ETC-IN-COMPILE-FILE:YES:

      Require COMPILE-FILE to treat top-level calls to PROCLAIM as if they
      were wrapped in an (EVAL-WHEN (COMPILE LOAD EVAL) ...).

      Rationale:

        Proclamations affect compilation semantics and should be made
        available to the compiler.

    Proposal PROCLAIM-ETC-IN-COMPILE-FILE:NO:

      Clarify that calls to PROCLAIM should be treated the same as any
      other function call.  Users should wrap an explicit EVAL-WHEN around
      top-level calls to PROCLAIM if they want them to affect compilation.

      Rationale:

        This makes the semantics of COMPILE-FILE more uniform and easier
        to understand.  In particular, if we remove the magic compile-time
        behavior of the package functions, it seems silly to add another
        exception for PROCLAIM.

    Proposal PROCLAIM-ETC-IN-COMPILE-FILE:NEW-MACRO:

      Add a new macro:

      DEFPROCLAIM &rest decl-specs					[Macro]

      This macro PROCLAIMs the given <decl-specs>, which are not
      evaluated.  If a call to this macro appears at top-level in a file
      being processed by the file compiler, the proclamations are also
      made at compile-time.  As with other defining macros, it is
      unspecified whether or not the compile-time side-effects of a
      DEFPROCLAIM persist after the file has been compiled.

      Clarify that calls to PROCLAIM should be treated the same as any
      other function call.  Users should wrap an explicit EVAL-WHEN around
      top-level calls to PROCLAIM if they want them to affect compilation,
      or use the macro DEFPROCLAIM.

      Rationale:

        The macro makes the proclamations available to the compiler in such
        a way that does not require any special exceptions to be made in
        the model of how COMPILE-FILE works.

    Current Practice:

      The TI explorer apparently implements proposal YES, except that
      (EVAL-WHEN (LOAD) (PROCLAIM '(OPTIMIZE ...))) doesn't do anything.
      The Symbolics compiler has special top-level handling for PROCLAIM,
      although the details are not clear.

      Lisps developed at Utah (UCL, A-Lisp, PSL/PCLS) do not give PROCLAIM
      any special compile-time handling.

      Lucid does not evaluate calls to PROCLAIM at compile-time.

      The IIM compiler has special top-level handling for PROCLAIM when
      the argument is a constant.  The information is recorded in the remote
      environment.

    Cost to implementors:

      Since implementations are already required to have a mechanism for
      compile-time handling of the package functions, it would probably
      only require minor adjustments to add handling for PROCLAIM.

    Cost to users:

      For proposal YES, users would have no way to suppress compile-time
      evaluation of a top-level call to PROCLAIM.  Wrapping it in an
      (EVAL-WHEN (EVAL LOAD)...) wouldn't work under the model of how
      EVAL-WHEN works in proposal EVAL-WHEN-NON-TOP-LEVEL:GENERALIZE-EVAL.

      Under any of these proposals, some users would probably have to
      make minor changes to their code.

    Benefits:

      Users will know what to expect when they use PROCLAIM.

    Costs of Non-Adoption:

      Users will not know what to expect when they use PROCLAIM.

    Aesthetics:

      At least two people consider requiring magic behavior for certain
      top-level function calls to be "semantically bletcherous".  Removing
      all special cases for functions that are implicitly evaluated at
      compile-time would simplify the model of how COMPILE-FILE works.

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

    Discussion:

      The first version of this writeup also included REQUIRE with PROCLAIM,
      but we have now voted to remove REQUIRE from the language entirely.
      It also specified that OPTIMIZE proclamations should only have a local
      effect within the file being compiled.  This was removed for
      consistency with other compile-time side-effects (such as those from
      DEFMACRO), where their persistence is explicitly left unspecified.

      Loosemore favors proposal NO, but wouldn't oppose proposal NEW-MACRO.

      Kim Barrett says:

        Proposal YES violates the general approach we've been taking of trying
        to limit side-effects on the local environment during compilation.

        Proposal NO makes PROCLAIM virtually worthless.

        Proposal NEW-MACRO -- While this matches up with other stuff we've
        been doing, I'm concerned about two things.  First, I really dislike
        the name DEFPROCLAIM.  This thing isn't defining anything!  It sounds
        like something that modifies the behavior of PROCLAIM, not something
        that actually makes a proclamation.  Second, I'm concerned about the
        cost to users.  I think the statement that

        "Under any of these proposals, some users would probably have to make
        minor changes to their code."

        is rather misleading for this case.  There are a lot of PROCLAIMs out
        there.

    Loosemore replies:

        ....but all of those uses of PROCLAIM are already nonportable.  No
        matter what we do here, somebody is going to get burned.

        Suggestions for better names for the macro are welcome.

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