[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
doc eval-when-compile, eval-and-compile
From: |
Kevin Ryde |
Subject: |
doc eval-when-compile, eval-and-compile |
Date: |
Tue, 25 Oct 2005 08:13:15 +1000 |
User-agent: |
Gnus/5.110004 (No Gnus v0.4) Emacs/21.4 (gnu/linux) |
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.
compile.texi.eval-when.diff
Description: Text document
- doc eval-when-compile, eval-and-compile,
Kevin Ryde <=