doc eval-when-compile, eval-and-compile

doc eval-when-compile, eval-and-compile

[Kevin Ryde]

[-- Attachment #1: Type: text/plain, Size: 3604 bytes --]

I find I have to think about three times and then think again before
deciding whether eval-when-compile or eval-and-compile or neither are
needed or wanted.

Perhaps it's easy for experts, but it might be nice if the docs had
some examples of typical uses, or typical non-uses.

Below is my go at something like that for the manual.  I think the
eval-when-compile bit is quite nice, but I couldn't think of much good
to say about eval-and-compile.  If eval-when-compile is the more often
used then putting it first in the node might be good.

I see eval-and-compile has been used around autoloads like the
following from gnus, but this is unnecessary now, is it?

	(eval-and-compile
	  (autoload 'password-read "password"))



 -- Special Form: eval-and-compile body...
     This form marks BODY to be evaluated both when you compile the
     containing code and when you run it (whether compiled or not).

     You can get a similar result by putting BODY in a separate file
     and referring to that file with `require'.  That method is
     preferable when BODY is large.  Effectively `require' is
     automatically `eval-and-compile', the package is loaded both when
     compiling and executing.

     `autoload' is also effectively `eval-and-compile' too.  It's
     recognised when compiling, so uses of such a function don't produce
     "not known to be defined" warnings.

     Most uses of `eval-and-compile' are fairly sophisticated.

     If a macro has a helper function to build its result, and that
     macro is used both locally and outside the package, then
     `eval-and-compile' should be used to get the helper both when
     compiling and then later when running.

     If functions are defined programmatically (with `fset' say), then
     `eval-and-compile' can be used to have that done at compile-time
     as well as run-time, so calls to those functions are checked (and
     warnings about "not known to be defined" suppressed).

 -- Special Form: eval-when-compile body...
     This form marks BODY to be evaluated at compile time but not when
     the compiled program is loaded.  The result of evaluation by the
     compiler becomes a constant which appears in the compiled program.
     If you load the source file, rather than compiling it, BODY is
     evaluated normally.

     If you have a constant that needs some calculation to produce,
     `eval-when-compile' can do that done at compile-time.  For example,

          (defvar my-regexp
            (eval-when-compile (regexp-opt '("aaa" "aba" "abb"))))

     If you're using another package, but only need macros from it (the
     byte compiler will expand those), then `eval-when-compile' can be
     used to load it for compiling, but not executing.  For example,

          (eval-when-compile
            (require 'my-macro-package))  ;; only macros needed from this

     The same sort of thing goes for macros or `defalias'es defined
     locally and only for use within the file.  They can be defined
     while compiling, but then not needed when executing.  This is good
     for code that's only a fallback for compability with other
     versions of Emacs.  For example.

          (eval-when-compile
            (unless (fboundp 'some-new-thing)
              (defmacro 'some-new-thing ()
                (compatibility code))))

     *Common Lisp Note:* At top level, `eval-when-compile' is analogous
     to the Common Lisp idiom `(eval-when (compile eval) ...)'.
     Elsewhere, the Common Lisp `#.' reader macro (but not when
     interpreting) is closer to what `eval-when-compile' does.



[-- Attachment #2: compile.texi.eval-when.diff --]
[-- Type: text/plain, Size: 3339 bytes --]

*** compile.texi.~1.24.~	2005-10-20 07:43:07.000000000 +1000
--- compile.texi	2005-10-24 18:43:30.000000000 +1000
***************
*** 407,413 ****
  
  You can get a similar result by putting @var{body} in a separate file
  and referring to that file with @code{require}.  That method is
! preferable when @var{body} is large.
  @end defspec
  
  @defspec eval-when-compile body@dots{}
--- 407,431 ----
  
  You can get a similar result by putting @var{body} in a separate file
  and referring to that file with @code{require}.  That method is
! preferable when @var{body} is large.  Effectively @code{require} is
! automatically @code{eval-and-compile}, the package is loaded both when
! compiling and executing.
! 
! @code{autoload} is also effectively @code{eval-and-compile} too.  It's
! recognised when compiling, so uses of such a function don't produce
! ``not known to be defined'' warnings.
! 
! Most uses of @code{eval-and-compile} are fairly sophisticated.
! 
! If a macro has a helper function to build its result, and that macro
! is used both locally and outside the package, then
! @code{eval-and-compile} should be used to get the helper both when
! compiling and then later when running.
! 
! If functions are defined programmatically (with @code{fset} say), then
! @code{eval-and-compile} can be used to have that done at compile-time
! as well as run-time, so calls to those functions are checked (and
! warnings about ``not known to be defined'' suppressed).
  @end defspec
  
  @defspec eval-when-compile body@dots{}
***************
*** 417,423 ****
  you load the source file, rather than compiling it, @var{body} is
  evaluated normally.
  
! @strong{Common Lisp Note:} At top level, this is analogous to the Common
  Lisp idiom @code{(eval-when (compile eval) @dots{})}.  Elsewhere, the
  Common Lisp @samp{#.} reader macro (but not when interpreting) is closer
  to what @code{eval-when-compile} does.
--- 435,472 ----
  you load the source file, rather than compiling it, @var{body} is
  evaluated normally.
  
! If you have a constant that needs some calculation to produce,
! @code{eval-when-compile} can do that done at compile-time.  For
! example,
! 
! @lisp
! (defvar my-regexp
!   (eval-when-compile (regexp-opt '("aaa" "aba" "abb"))))
! @end lisp
! 
! If you're using another package, but only need macros from it (the
! byte compiler will expand those), then @code{eval-when-compile} can be
! used to load it for compiling, but not executing.  For example,
! 
! @lisp
! (eval-when-compile
!   (require 'my-macro-package))  ;; only macros needed from this
! @end lisp
! 
! The same sort of thing goes for macros or @code{defalias}es defined
! locally and only for use within the file.  They can be defined while
! compiling, but then not needed when executing.  This is good for code
! that's only a fallback for compability with other versions of Emacs.
! For example.
! 
! @lisp
! (eval-when-compile
!   (unless (fboundp 'some-new-thing)
!     (defmacro 'some-new-thing ()
!       (compatibility code))))
! @end lisp
! 
! @strong{Common Lisp Note:} At top level, @code{eval-when-compile} is analogous to the Common
  Lisp idiom @code{(eval-when (compile eval) @dots{})}.  Elsewhere, the
  Common Lisp @samp{#.} reader macro (but not when interpreting) is closer
  to what @code{eval-when-compile} does.

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: doc eval-when-compile, eval-and-compile

[Stefan Monnier]

> Below is my go at something like that for the manual.  I think the
> eval-when-compile bit is quite nice, but I couldn't think of much good
> to say about eval-and-compile.  If eval-when-compile is the more often
> used then putting it first in the node might be good.

I've never used eval-and-compile.

> I see eval-and-compile has been used around autoloads like the
> following from gnus, but this is unnecessary now, is it?

> 	(eval-and-compile
> 	  (autoload 'password-read "password"))

It's probably not unnecessary: the evaluation at compile-time is used
so that the byte-compiler knows the function exists and doesn't put out
warnings about its use.  I.e. it works around the fact that the
byte-compiler does not natively understand that `autoload' "defines"
a function.

More commonly the autoload is in another file which is `require'd, so it's
evaluated both at compile and at run time, with the same end result but
without using eval-and-compile.


        Stefan

Re: doc eval-when-compile, eval-and-compile

[Richard M. Stallman]

    It's probably not unnecessary: the evaluation at compile-time is used
    so that the byte-compiler knows the function exists and doesn't put out
    warnings about its use.  I.e. it works around the fact that the
    byte-compiler does not natively understand that `autoload' "defines"
    a function.

Should we fix that?

Re: doc eval-when-compile, eval-and-compile

[Richard M. Stallman]

It is basically good; I will install it and then make a few changes.

Thanks.

Re: doc eval-when-compile, eval-and-compile

[Kevin Ryde]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
> I.e. it works around the fact that the byte-compiler does not
> natively understand that `autoload' "defines" a function.

I tried byte compiling

	(defun foo ()
	  (bar))

then adding

	(autoload 'bar "barpkg")

and that autoload suppressed the warning about bar, so I thought it
was recognised, without being actually eval'ed.

Re: doc eval-when-compile, eval-and-compile

[Richard M. Stallman]

    then adding

	    (autoload 'bar "barpkg")

    and that autoload suppressed the warning about bar, so I thought it
    was recognised, without being actually eval'ed.

Yes, it does seem to work as is.