@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
+@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.
@end menu
-@node Compilation Functions
-@comment node-name, next, previous, up
-@section The Compilation Functions
-@cindex compilation functions
-
- You can byte-compile an individual function or macro definition with
-the @code{byte-compile} function. You can compile a whole file with
-@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.
-
-@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}.
-
- While byte-compiling a file, any @code{require} calls at top-level are
-executed. One way to ensure that necessary macro definitions are
-available during compilation is to require the file that defines them.
-@xref{Features}.
+@node Speed of Byte-Code
+@section Performance of Byte-Compiled Code
A byte-compiled function is not as efficient as a primitive function
written in C, but runs much faster than the version written in Lisp.
-For a rough comparison, consider the example below:
+Here is an example:
@example
@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
@group
(silly-loop 100000)
-@result{} ("Thu Jan 12 20:18:38 1989"
- "Thu Jan 12 20:19:29 1989") ; @r{51 seconds}
+@result{} ("Fri Mar 18 17:25:57 1994"
+ "Fri Mar 18 17:26:28 1994") ; @r{31 seconds}
@end group
@group
@group
(silly-loop 100000)
-@result{} ("Thu Jan 12 20:21:04 1989"
- "Thu Jan 12 20:21:17 1989") ; @r{13 seconds}
+@result{} ("Fri Mar 18 17:26:52 1994"
+ "Fri Mar 18 17:26:58 1994") ; @r{6 seconds}
@end group
@end example
- In this example, the interpreted code required 51 seconds to run,
-whereas the byte-compiled code required 13 seconds. These results are
+ In this example, the interpreted code required 31 seconds to run,
+whereas the byte-compiled code required 6 seconds. These results are
representative, but actual results will vary greatly.
+@node Compilation Functions
+@comment node-name, next, previous, up
+@section The Compilation Functions
+@cindex compilation functions
+
+ You can byte-compile an individual function or macro definition with
+the @code{byte-compile} function. You can compile a whole file with
+@code{byte-compile-file}, or several files with
+@code{byte-recompile-directory} or @code{batch-byte-compile}.
+
+ 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 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}).
+
+ 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 (@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},
+This function byte-compiles the function definition of @var{symbol},
replacing the previous definition with the compiled one. The function
definition of @var{symbol} must be the actual code for the function;
i.e., the compiler does not follow indirection to another symbol.
-@code{byte-compile} does not compile macros. @code{byte-compile}
-returns the new, compiled 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,
+@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
+way to ``compile the same definition again.''
@example
@group
"Compute factorial of INTEGER."
(if (= 1 integer) 1
(* integer (factorial (1- integer)))))
- @result{} factorial
+@result{} factorial
@end group
@group
(byte-compile 'factorial)
- @result{}
+@result{}
#[(integer)
"^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207"
[integer 1 * factorial]
@end example
@noindent
-The result is a compiled function object. The string it contains is the
-actual byte-code; each character in it is 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.
+The result is a byte-code function object. The string it contains is
+the actual byte-code; each character in it is an instruction or an
+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.
@end defun
@deffn Command compile-defun
@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
+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
definition is written out. Other forms are batched together, then each
batch is compiled, and written so that its compiled code will be
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
+This command returns @code{t}. When called interactively, it prompts
for the file name.
@example
@deffn Command byte-recompile-directory directory flag
@cindex library compilation
- This function recompiles every @samp{.el} file in @var{directory} that
+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.
- If a @samp{.el} file exists, but there is no corresponding @samp{.elc}
-file, then @var{flag} is examined. If it is @code{nil}, the file is
-ignored. If it is non-@code{nil}, the user is asked whether the file
-should be compiled.
+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.
+The returned value of this command is unpredictable.
@end deffn
@defun batch-byte-compile
- This function runs @code{byte-compile-file} on the files remaining 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.)
+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, 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
@defun byte-code code-string data-vector max-stack
@cindex byte-code interpreter
- This function actually interprets byte-code. A byte-compiled function
+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 compiled function object, and only rarely as part of a 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
with @var{elements} as its elements.
@end defun
- 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 create these
-objects; it, we hope, always makes the elements consistent.
+ 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
+create these objects; it makes the elements consistent (we hope).
You can access the elements of a byte-code object using @code{aref};
you can also use @code{vconcat} to create a vector with the same
form.
The byte-code interpreter is implemented as a simple stack machine.
-Values get stored by being pushed onto the stack, and are popped off and
-manipulated, the results being pushed back onto the stack. When a
-function returns, the top of the stack is popped and returned as the
-value of the function.
+It pushes values onto a stack of its own, then pops them off to use them
+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, values used during byte-code execution can
-be stored in ordinary Lisp variables. Variable values can be pushed
-onto the stack, and variables can be set by popping the stack.
+ In addition to the stack, byte-code functions can use, bind, and set
+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
@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
@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{*}}
(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
@group
5 dup ; @r{Duplicate the top of the stack;}
- ; @r{i.e. copy the top of}
+ ; @r{i.e., copy the top of}
; @r{the stack and push the}
; @r{copy onto the stack.}
@end group
@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
@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
HCoop / bpt / emacs.git / blobdiff