(Eval During Compile): Explain recommended uses

of eval-when-compile and eval-and-compile.

diff --git a/lispref/compile.texi b/lispref/compile.texi
index f8fd3f72b9a7612c99f469c6750165d83de77f22..46afbad2b0b86f3a91446b259c416166cd2c9830 100644 (file)
--- a/lispref/compile.texi
+++ b/lispref/compile.texi
@@ -407,7 +407,25 @@ 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@dots{}
@@ -417,7 +435,38 @@ 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.