@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2002, 2003, 2004,
+@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
@xref{Loading Non-ASCII}.
In general, any version of Emacs can run byte-compiled code produced
-by recent earlier versions of Emacs, but the reverse is not true. A
-major incompatible change was introduced in Emacs version 19.29, and
-files compiled with versions since that one will definitely not run
-in earlier versions unless you specify a special option.
-@iftex
-@xref{Docs and Compilation}.
-@end iftex
-In addition, the modifier bits in keyboard characters were renumbered in
-Emacs 19.29; as a result, files compiled in versions before 19.29 will
-not work in subsequent versions if they contain character constants with
-modifier bits.
+by recent earlier versions of Emacs, but the reverse is not true.
@vindex no-byte-compile
If you do not want a Lisp file to be compiled, ever, put a file-local
details, see @ref{Compiling Macros}. If a program does not work the
same way when compiled as it does when interpreted, erroneous macro
definitions are one likely cause (@pxref{Problems with Macros}).
+Inline (@code{defsubst}) functions are less troublesome; if you
+compile a call to such a function before its definition is known, the
+call will still work right, it will just run slower.
Normally, compiling a file does not evaluate the file's contents or
load the file. But it does execute any @code{require} calls at top
occasionally if you edit and recompile Lisp files. When it happens, you
can cure the problem by reloading the file after recompiling it.
- Byte-compiled files made with recent versions of Emacs (since 19.29)
-will not load into older versions because the older versions don't
-support this feature. You can turn off this feature at compile time by
-setting @code{byte-compile-dynamic-docstrings} to @code{nil}; then you
-can compile files that will load into older Emacs versions. You can do
-this globally, or for one source file by specifying a file-local binding
-for the variable. One way to do that is by adding this string to the
-file's first line:
+ You can turn off this feature at compile time by setting
+@code{byte-compile-dynamic-docstrings} to @code{nil}; this is useful
+mainly if you expect to change the file, and you want Emacs processes
+that have already loaded it to keep working when the file changes.
+You can do this globally, or for one source file by specifying a
+file-local binding for the variable. One way to do that is by adding
+this string to the file's first line:
@example
-*-byte-compile-dynamic-docstrings: nil;-*-
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
+recognized 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
+@cindex compile-time constant
+If you have a constant that needs some calculation to produce,
+@code{eval-when-compile} can do that at compile-time. For example,
+
+@lisp
+(defvar my-regexp
+ (eval-when-compile (regexp-opt '("aaa" "aba" "abb"))))
+@end lisp
+
+@cindex macros, at compile time
+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 compatibility 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.
@section Compiler Errors
@cindex compiler errors
- Byte compilation writes errors and warnings into the buffer
+ Byte compilation outputs all errors and warnings into the buffer
@samp{*Compile-Log*}. The messages include file names and line
numbers that identify the location of the problem. The usual Emacs
commands for operating on compiler diagnostics work properly on
@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}.