@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, Debugging, Loading, Top
+@node Byte Compilation, Advising Functions, Loading, Top
@chapter Byte Compilation
@cindex byte-code
@cindex compilation
- GNU Emacs Lisp has a @dfn{compiler} that translates functions written
+ Emacs Lisp has a @dfn{compiler} that translates functions written
in Lisp into a special representation called @dfn{byte-code} that can be
executed more efficiently. The compiler replaces Lisp function
definitions with byte-code. When a byte-code function is called, its
transportable from machine to machine without recompilation. It is not,
however, as fast as true compiled code.
+ Compiling a Lisp file with the Emacs byte compiler always reads the
+file as multibyte text, even if Emacs was started with @samp{--unibyte},
+unless the file specifies otherwise. This is so that compilation gives
+results compatible with running the same file without compilation.
+@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. In
-particular, if you compile a program with Emacs 19.29, the compiled
-code does not run in earlier versions.
-@iftex
-@xref{Docs and Compilation}.
-@end iftex
-Files compiled in versions before 19.29 may not work in 19.29 if they
-contain character constants with modifier bits, because the bits were
-renumbered in Emacs 19.29.
+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
+variable binding for @code{no-byte-compile} into it, like this:
+
+@example
+;; -*-no-byte-compile: t; -*-
+@end example
@xref{Compilation Errors}, for how to investigate errors occurring in
byte compilation.
* Docs and Compilation:: Dynamic loading of documentation strings.
* Dynamic Loading:: Dynamic loading of individual functions.
* Eval During Compile:: Code to be evaluated when you compile.
+* Compiler Errors:: Handling compiler error messages.
* Byte-Code Objects:: The data type used for byte-compiled functions.
* Disassembly:: Disassembling byte-code; how to read byte-code.
@end menu
(defun silly-loop (n)
"Return time before and after N iterations of a loop."
(let ((t1 (current-time-string)))
- (while (> (setq n (1- n))
+ (while (> (setq n (1- n))
0))
(list t1 (current-time-string))))
@result{} silly-loop
@code{byte-compile-file}, or several files with
@code{byte-recompile-directory} or @code{batch-byte-compile}.
- When you run the byte compiler, you may get warnings in a buffer
-called @samp{*Compile-Log*}. These report things in your program that
-suggest a problem but are not necessarily erroneous.
+ The byte compiler produces error messages and warnings about each file
+in a buffer called @samp{*Compile-Log*}. These report things in your
+program that suggest a problem but are not necessarily erroneous.
@cindex macro compilation
- Be careful when byte-compiling code that uses macros. Macro calls are
-expanded when they are compiled, so the macros must already be defined
-for proper compilation. For more details, see @ref{Compiling Macros}.
+ Be careful when writing macro calls in files that you may someday
+byte-compile. Macro calls are expanded when they are compiled, so the
+macros must already be defined for proper compilation. For more
+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
operand of an instruction. The vector contains all the constants,
variable names and function names used by the function, except for
certain primitives that are coded as special instructions.
+
+If the argument to @code{byte-compile} is a @code{lambda} expression,
+it returns the corresponding compiled code, but does not store
+it anywhere.
@end defun
-@deffn Command compile-defun
+@deffn Command compile-defun &optional arg
This command reads the defun containing point, compiles it, and
evaluates the result. If you use this on a defun that is actually a
function definition, the effect is to install a compiled version of that
function.
+
+@code{compile-defun} normally displays the result of evaluation in the
+echo area, but if @var{arg} is non-@code{nil}, it inserts the result
+in the current buffer after the form it compiled.
@end deffn
-@deffn Command byte-compile-file filename
-This function compiles a file of Lisp code named @var{filename} into
-a file of byte-code. The output file's name is made by appending
-@samp{c} to the end of @var{filename}.
+@deffn Command byte-compile-file filename &optional load
+This function compiles a file of Lisp code named @var{filename} into a
+file of byte-code. The output file's name is made by changing the
+@samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in
+@samp{.el}, it adds @samp{.elc} to the end of @var{filename}.
Compilation works by reading the input file one form at a time. If it
is a definition of a function or macro, the compiled function or macro
executed when the file is read. All comments are discarded when the
input file is read.
-This command returns @code{t}. When called interactively, it prompts
-for the file name.
+This command returns @code{t} if there were no errors and @code{nil}
+otherwise. When called interactively, it prompts for the file name.
+
+If @var{load} is non-@code{nil}, this command loads the compiled file
+after compiling it. Interactively, @var{load} is the prefix argument.
@example
@group
@end example
@end deffn
-@deffn Command byte-recompile-directory directory flag
+@deffn Command byte-recompile-directory directory &optional flag force
@cindex library compilation
-This function recompiles every @samp{.el} file in @var{directory} that
-needs recompilation. A file needs recompilation if a @samp{.elc} file
-exists but is older than the @samp{.el} file.
+This command recompiles every @samp{.el} file in @var{directory} (or
+its subdirectories) that needs recompilation. A file needs
+recompilation if a @samp{.elc} file exists but is older than the
+@samp{.el} file.
+
+When a @samp{.el} file has no corresponding @samp{.elc} file,
+@var{flag} says what to do. If it is @code{nil}, this command ignores
+these files. If @var{flag} is 0, it compiles them. If it is neither
+@code{nil} nor 0, it asks the user whether to compile each such file,
+and asks about each subdirectory as well.
-When a @samp{.el} file has no corresponding @samp{.elc} file, then
-@var{flag} says what to do. If it is @code{nil}, these files are
-ignored. If it is non-@code{nil}, the user is asked whether to compile
-each such file.
+Interactively, @code{byte-recompile-directory} prompts for
+@var{directory} and @var{flag} is the prefix argument.
-The returned value of this command is unpredictable.
+If @var{force} is non-@code{nil}, this command recompiles every
+@samp{.el} file that has a @samp{.elc} file.
+
+The returned value is unpredictable.
@end deffn
-@defun batch-byte-compile
+@defun batch-byte-compile &optional noforce
This function runs @code{byte-compile-file} on files specified on the
command line. This function must be used only in a batch execution of
Emacs, as it kills Emacs on completion. An error in one file does not
-prevent processing of subsequent files. (The file that gets the error
-will not, of course, produce any compiled code.)
+prevent processing of subsequent files, but no output file will be
+generated for it, and the Emacs process will terminate with a nonzero
+status code.
+
+If @var{noforce} is non-@code{nil}, this function does not recompile
+files that have an up-to-date @samp{.elc} file.
@example
% emacs -batch -f batch-byte-compile *.el
@cindex byte-code interpreter
This function actually interprets byte-code. A byte-compiled function
is actually defined with a body that calls @code{byte-code}. Don't call
-this function yourself. Only the byte compiler knows how to generate
+this function yourself---only the byte compiler knows how to generate
valid calls to this function.
-In newer Emacs versions (19 and up), byte-code is usually executed as
-part of a byte-code function object, and only rarely due to an explicit
-call to @code{byte-code}.
+In Emacs version 18, byte-code was always executed by way of a call to
+the function @code{byte-code}. Nowadays, byte-code is usually executed
+as part of a byte-code function object, and only rarely through an
+explicit call to @code{byte-code}.
@end defun
@node Docs and Compilation
@item
If you alter the compiled file (such as by compiling a new version),
-then further access to documentation strings in this file will give
-nonsense results.
+then further access to documentation strings in this file will
+probably give nonsense results.
@end itemize
If your site installs Emacs following the usual procedures, these
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 Emacs 19.29 will not load into older
-versions because the older versions don't support this feature. You can
-turn off this feature by setting @code{byte-compile-dynamic-docstrings}
-to @code{nil}. Once this is done, 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. Here's one
-way to do that:
+ 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;-*-
use a special Lisp reader construct, @samp{#@@@var{count}}. This
construct skips the next @var{count} characters. It also uses the
@samp{#$} construct, which stands for ``the name of this file, as a
-string.'' It is best not to use these constructs in Lisp source files.
+string.'' It is usually best not to use these constructs in Lisp source
+files, since they are not designed to be clear to humans reading the
+file.
@node Dynamic Loading
@section Dynamic Loading of Individual Functions
The advantage of dynamic function loading is that loading the file
becomes much faster. This is a good thing for a file which contains
-many separate commands, provided that using one of them does not imply
-you will soon (or ever) use the rest. A specialized mode which provides
-many keyboard commands often has that usage pattern: a user may invoke
-the mode, but use only a few of the commands it provides.
+many separate user-callable functions, if using one of them does not
+imply you will probably also use the rest. A specialized mode which
+provides many keyboard commands often has that usage pattern: a user may
+invoke the mode, but use only a few of the commands it provides.
The dynamic loading feature has certain disadvantages:
@item
If you alter the compiled file (such as by compiling a new version),
-then trying to load any function not already loaded will get nonsense
-results.
+then trying to load any function not already loaded will usually yield
+nonsense results.
@end itemize
- If you compile a new version of the file, the best thing to do is
-immediately load the new compiled file. That will prevent any future
-problems.
+ These problems will never happen in normal circumstances with
+installed Emacs files. But they are quite likely to happen with Lisp
+files that you are changing. The easiest way to prevent these problems
+is to reload the new compiled file immediately after each recompilation.
The byte compiler uses the dynamic function loading feature if the
variable @code{byte-compile-dynamic} is non-@code{nil} at compilation
time. Do not set this variable globally, since dynamic loading is
desirable only for certain files. Instead, enable the feature for
-specific source files with file-local variable bindings, like this:
+specific source files with file-local variable bindings. For example,
+you could do it by writing this text in the source file's first line:
@example
-*-byte-compile-dynamic: t;-*-
@end defvar
@defun fetch-bytecode function
-This immediately finishes loading the definition of @var{function} from
-its byte-compiled file, if it is not fully loaded already. The argument
-@var{function} may be a byte-code function object or a function name.
+If @var{function} is a byte-code function object, this immediately
+finishes loading the byte code of @var{function} from its
+byte-compiled file, if it is not fully loaded already. Otherwise,
+it does nothing. It always returns @var{function}.
@end defun
@node Eval During Compile
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}. Using @code{require} is
-preferable if there is a substantial amount of code to be executed in
-this way.
+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
-This form marks @var{body} to be evaluated at compile time and not when
+@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. When
-the program is interpreted, not compiled at all, @var{body} is evaluated
-normally.
-
-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.
+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
+
+@node Compiler Errors
+@section Compiler Errors
+@cindex compiler errors
+
+ 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
+these messages.
+
+ However, the warnings about functions that were used but not
+defined are always ``located'' at the end of the file, so these
+commands won't find the places they are really used. To do that,
+you must search for the function names.
+
+ You can suppress the compiler warning for calling an undefined
+function @var{func} by conditionalizing the function call on an
+@code{fboundp} test, like this:
+
+@example
+(if (fboundp '@var{func}) ...(@var{func} ...)...)
+@end example
+
+@noindent
+The call to @var{func} must be in the @var{then-form} of the
+@code{if}, and @var{func} must appear quoted in the call to
+@code{fboundp}. (This feature operates for @code{cond} as well.)
+
+ Likewise, you can suppress a compiler warning for an unbound variable
+@var{variable} by conditionalizing its use on a @code{boundp} test,
+like this:
+
+@example
+(if (boundp '@var{variable}) ...@var{variable}...)
+@end example
+
+@noindent
+The reference to @var{variable} must be in the @var{then-form} of the
+@code{if}, and @var{variable} must appear quoted in the call to
+@code{boundp}.
+
+ You can suppress any compiler warnings using the construct
+@code{with-no-warnings}:
+
+@c This is implemented with a defun, but conceptually it is
+@c a special form.
+
+@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}.
+
+We recommend that you use this construct around the smallest
+possible piece of code.
@end defspec
@node Byte-Code Objects
function object is like that for a vector, with an additional @samp{#}
before the opening @samp{[}.
- In Emacs version 18, there was no byte-code function object data type;
-compiled functions used the function @code{byte-code} to run the byte
-code.
-
A byte-code function object must have at least four elements; there is
-no maximum number, but only the first six elements are actually used.
+no maximum number, but only the first six elements have any normal use.
They are:
@table @var
ordinary Lisp variables, by transferring values between variables and
the stack.
-@deffn Command disassemble object &optional stream
-This function prints the disassembled code for @var{object}. If
-@var{stream} is supplied, then output goes there. Otherwise, the
-disassembled code is printed to the stream @code{standard-output}. The
-argument @var{object} can be a function name or a lambda expression.
-
-As a special exception, if this function is used interactively,
-it outputs to a buffer named @samp{*Disassemble*}.
+@deffn Command disassemble object &optional buffer-or-name
+This command displays the disassembled code for @var{object}. In
+interactive use, or if @var{buffer-or-name} is @code{nil} or omitted,
+the output goes in a buffer named @samp{*Disassemble*}. If
+@var{buffer-or-name} is non-@code{nil}, it must be a buffer or the
+name of an existing buffer. Then the output goes there, at point, and
+point is left before the output.
+
+The argument @var{object} can be a function name, a lambda expression
+or a byte-code object. If it is a lambda expression, @code{disassemble}
+compiles it and disassembles the resulting compiled code.
@end deffn
Here are two examples of using the @code{disassemble} function. We
@group
0 constant 1 ; @r{Push 1 onto stack.}
-1 varref integer ; @r{Get value of @code{integer}}
+1 varref integer ; @r{Get value of @code{integer}}
; @r{from the environment}
; @r{and push the value}
; @r{onto the stack.}
@group
; @r{Stack now contains:}
; @minus{} @r{decremented value of @code{integer}}
- ; @minus{} @r{@code{factorial}}
+ ; @minus{} @r{@code{factorial}}
; @minus{} @r{value of @code{integer}}
; @minus{} @r{@code{*}}
@end group
(defun silly-loop (n)
"Return time before and after N iterations of a loop."
(let ((t1 (current-time-string)))
- (while (> (setq n (1- n))
+ (while (> (setq n (1- n))
0))
(list t1 (current-time-string))))
@result{} silly-loop
@end group
@group
-19 constant current-time-string ; @r{Push}
+19 constant current-time-string ; @r{Push}
; @r{@code{current-time-string}}
; @r{onto top of stack.}
@end group
@end example
+@ignore
+ arch-tag: f78e3050-2f0a-4dee-be27-d9979a0a2289
+@end ignore