comparison lispref/compile.texi @ 90261:7beb78bc1f8e

Revision: [e-mail]--gnu-2005/emacs--unicode--0--patch-97 Merge from emacs--cvs-trunk--0 Patches applied: * emacs--cvs-trunk--0 (patch 616-696) - Add lisp/mh-e/.arch-inventory - Update from CVS - Merge from gnus--rel--5.10 - Update from CVS: lisp/smerge-mode.el: Add 'tools' to file keywords. - lisp/gnus/ChangeLog: Remove duplicate entry * gnus--rel--5.10 (patch 147-181) - Update from CVS - Merge from emacs--cvs-trunk--0 - Update from CVS: lisp/mml.el (mml-preview): Doc fix. - Update from CVS: texi/message.texi: Fix default values. - Update from CVS: texi/gnus.texi (RSS): Addition.

90260:0ca0d9181b5e

This form marks @var{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 @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{}
This form marks @var{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, @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.
@end defspec

90261:7beb78bc1f8e

This form marks @var{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 @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{}
This form marks @var{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, @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.
@end defspec