@c Copyright (C) 1990, 1991, 1992, 1993, 1994 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 18, you can run the
-compiled code in Emacs 19, but not vice versa.
+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.
@xref{Compilation Errors}, for how to investigate errors occurring in
byte compilation.
@menu
* Speed of Byte-Code:: An example of speedup from byte compilation.
* Compilation Functions:: Byte compilation functions.
+* 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.
* Byte-Code Objects:: The data type used for byte-compiled functions.
* Disassembly:: Disassembling byte-code; how to read byte-code.
@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 usage 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}.
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-level in the file. One way to ensure that necessary macro
-definitions are available during compilation is to require the file that
-defines them. @xref{Features}.
+load the file. But it does execute any @code{require} calls at top
+level in the file. One way to ensure that necessary macro definitions
+are available during compilation is to require the file that defines
+them (@pxref{Named Features}). To avoid loading the macro definition files
+when someone @emph{runs} the compiled program, write
+@code{eval-when-compile} around the @code{require} calls (@pxref{Eval
+During Compile}).
@defun byte-compile symbol
This function byte-compiles the function definition of @var{symbol},
@code{byte-compile} returns the new, compiled definition of
@var{symbol}.
-If @var{symbol}'s definition is a byte-code function object,
+ If @var{symbol}'s definition is a byte-code function object,
@code{byte-compile} does nothing and returns @code{nil}. Lisp records
only one function definition for any symbol, and if that is already
compiled, non-compiled code is not available anywhere. So there is no
@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}.
+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
needs recompilation. A file needs recompilation if a @samp{.elc} file
exists but is older than the @samp{.el} file.
-If a @samp{.el} file exists, but there is no corresponding @samp{.elc}
-file, then @var{flag} says what to do. If it is @code{nil}, the file is
-ignored. If it is non-@code{nil}, the user is asked whether to compile
-the file.
+When a @samp{.el} file has no corresponding @samp{.elc} file, @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.
The returned value of this command is unpredictable.
@end deffn
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 which 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.
@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
+@section Documentation Strings and Compilation
+@cindex dynamic loading of documentation
+
+ Functions and variables loaded from a byte-compiled file access their
+documentation strings dynamically from the file whenever needed. This
+saves space within Emacs, and makes loading faster because the
+documentation strings themselves need not be processed while loading the
+file. Actual access to the documentation strings becomes slower as a
+result, but this normally is not enough to bother users.
+
+ Dynamic access to documentation strings does have drawbacks:
+
+@itemize @bullet
+@item
+If you delete or move the compiled file after loading it, Emacs can no
+longer access the documentation strings for the functions and variables
+in the file.
+
+@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.
+@end itemize
+
+ If your site installs Emacs following the usual procedures, these
+problems will never normally occur. Installing a new version uses a new
+directory with a different name; as long as the old version remains
+installed, its files will remain unmodified in the places where they are
+expected to be.
+
+ However, if you have built Emacs yourself and use it from the
+directory where you built it, you will experience this problem
+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:
+
+@example
+-*-byte-compile-dynamic-docstrings: nil;-*-
+@end example
+
+@defvar byte-compile-dynamic-docstrings
+If this is non-@code{nil}, the byte compiler generates compiled files
+that are set up for dynamic loading of documentation strings.
+@end defvar
+
+@cindex @samp{#@@@var{count}}
+@cindex @samp{#$}
+ The dynamic documentation string feature writes compiled files that
+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 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
+
+@cindex dynamic loading of functions
+@cindex lazy loading
+ When you compile a file, you can optionally enable the @dfn{dynamic
+function loading} feature (also known as @dfn{lazy loading}). With
+dynamic function loading, loading the file doesn't fully read the
+function definitions in the file. Instead, each function definition
+contains a place-holder which refers to the file. The first time each
+function is called, it reads the full definition from the file, to
+replace the place-holder.
+
+ 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 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:
+
+@itemize @bullet
+@item
+If you delete or move the compiled file after loading it, Emacs can no
+longer load the remaining function definitions not already loaded.
+
+@item
+If you alter the compiled file (such as by compiling a new version),
+then trying to load any function not already loaded will yield nonsense
+results.
+@end itemize
+
+ 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. For example,
+you could do it by writing this text in the source file's first line:
+
+@example
+-*-byte-compile-dynamic: t;-*-
+@end example
+
+@defvar byte-compile-dynamic
+If this is non-@code{nil}, the byte compiler generates compiled files
+that are set up for dynamic function loading.
+@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.
@end defun
@node Eval During Compile
@section Evaluation During Compilation
-These features permit you to write code to be evaluated during
+ These features permit you to write code to be evaluated during
compilation of a program.
@defspec eval-and-compile body
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.
@end defspec
@defspec eval-when-compile body
-This form marks @var{body} to be evaluated at compile time @emph{only}.
-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.
+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
@node Byte-Code Objects
-@section Byte-Code Objects
+@section Byte-Code Function Objects
@cindex compiled function
@cindex byte-code function
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
The string containing the byte-code instructions.
@item constants
-The vector of constants referenced by the byte code.
+The vector of Lisp objects referenced by the byte code. These include
+symbols used as function names and variable names.
@item stacksize
The maximum stack size this function needs.
@item docstring
-The documentation string (if any); otherwise, @code{nil}. For functions
-preloaded before Emacs is dumped, this is usually an integer which is an
-index into the @file{DOC} file; use @code{documentation} to convert this
-into a string (@pxref{Accessing Documentation}).
+The documentation string (if any); otherwise, @code{nil}. The value may
+be a number or a list, in case the documentation string is stored in a
+file. Use the function @code{documentation} to get the real
+documentation string (@pxref{Accessing Documentation}).
@item interactive
The interactive spec (if any). This can be a string or a Lisp
You should not try to come up with the elements for a byte-code
function yourself, because if they are inconsistent, Emacs may crash
-when you call the function. Always leave it to the byte-compiler to
+when you call the function. Always leave it to the byte compiler to
create these objects; it makes the elements consistent (we hope).
You can access the elements of a byte-code object using @code{aref};
The byte-code interpreter is implemented as a simple stack machine.
It pushes values onto a stack of its own, then pops them off to use them
-in calculations and push the result back on the stack. When a byte-code
-function returns, it pops a value off the stack and returns it as the
-value of the function.
+in calculations whose results are themselves pushed back on the stack.
+When a byte-code function returns, it pops a value off the stack and
+returns it as the value of the function.
- In addition to the stack, byte-code functions can use, bind and set
+ In addition to the stack, byte-code functions can use, bind, and set
ordinary Lisp variables, by transferring values between variables and
the stack.
@group
; @r{Stack now contains:}
- ; @minus{} @r{result of result of recursive}
+ ; @minus{} @r{result of recursive}
; @r{call to @code{factorial}}
; @minus{} @r{value of @code{integer}}
; @minus{} @r{@code{*}}
@end group
@group
-9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} > 0}
+9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0}
+ ; @r{(this exits the while loop).}
; @r{else pop top of stack}
; @r{and continue}
- ; @r{(this exits the while loop).}
@end group
@group
@group
17 discard ; @r{Discard result of while loop}
; @r{by popping top of stack.}
+ ; @r{This result is the value @code{nil} that}
+ ; @r{was not popped by the goto at 9.}
@end group
@group
HCoop / bpt / emacs.git / blobdiff