@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2002, 2003, 2004,
-@c 2005 Free Software Foundation, Inc.
+@c 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/compile
@node Byte Compilation, Advising Functions, Loading, Top
These features permit you to write code to be evaluated during
compilation of a program.
-@defspec eval-and-compile body
+@defspec eval-and-compile body@dots{}
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.
+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
+@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
+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.
@c This is implemented with a defun, but conceptually it is
@c a special form.
-@defspec with-no-warnings body...
+@defspec with-no-warnings body@dots{}
In execution, this is equivalent to @code{(progn @var{body}...)},
but the compiler does not issue warnings for anything that occurs
inside @var{body}.