| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
XEmacs Lisp has a compiler that translates functions written in Lisp into a special representation called byte-code that can be executed more efficiently. The compiler replaces Lisp function definitions with byte-code. When a byte-coded function is called, its definition is evaluated by the byte-code interpreter.
Because the byte-compiled code is evaluated by the byte-code interpreter, instead of being executed directly by the machine’s hardware (as true compiled code is), byte-code is completely transportable from machine to machine without recompilation. It is not, however, as fast as true compiled code.
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 XEmacs 20, the compiled code may not run in earlier versions.
The first time a compiled-function object is executed, the byte-code
instructions are validated and the byte-code is further optimized. An
invalid-byte-code error is signaled if the byte-code is invalid,
for example if it contains invalid opcodes. This usually means a bug in
the byte compiler.
See section Debugging Problems in Compilation, for how to investigate errors occurring in byte compilation.
| 21.1 Performance of Byte-Compiled Code | An example of speedup from byte compilation. | |
| 21.2 The Compilation Functions | Byte compilation functions. | |
| 21.3 Options for the Byte Compiler | Controlling the byte compiler’s behavior. | |
| 21.4 Documentation Strings and Compilation | Dynamic loading of documentation strings. | |
| 21.5 Dynamic Loading of Individual Functions | Dynamic loading of individual functions. | |
| 21.6 Evaluation During Compilation | Code to be evaluated when you compile. | |
| 21.7 Compiled-Function Objects | The data type used for byte-compiled functions. | |
| 21.8 Disassembled Byte-Code | Disassembling byte-code; how to read byte-code. | |
| 21.9 Different Behavior | When compiled code gives different results. |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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. Here is an example:
(defun silly-loop (n)
"Return time before and after N iterations of a loop."
(let ((t1 (current-time-string)))
(while (> (setq n (1- n))
0))
(list t1 (current-time-string))))
⇒ silly-loop
(silly-loop 5000000)
⇒ ("Mon Sep 14 15:51:49 1998"
"Mon Sep 14 15:52:07 1998") ; 18 seconds
(byte-compile 'silly-loop) ⇒ #<compiled-function (n) "...(23)" [current-time-string t1 n 0] 2 "Return time before and after N iterations of a loop."> (silly-loop 5000000)
⇒ ("Mon Sep 14 15:53:43 1998"
"Mon Sep 14 15:53:49 1998") ; 6 seconds
|
In this example, the interpreted code required 18 seconds to run, whereas the byte-compiled code required 6 seconds. These results are representative, but actual results will vary greatly.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can byte-compile an individual function or macro definition with
the byte-compile function. You can compile a whole file with
byte-compile-file, or several files with
byte-recompile-directory or batch-byte-compile.
When you run the byte compiler, you may get warnings in a buffer called ‘*Compile-Log*’. These report things in your program that suggest a problem but are not necessarily erroneous.
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 Macros and Byte Compilation.
Normally, compiling a file does not evaluate the file’s contents or
load the file. But it does execute any 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 (see section Features). To avoid loading the macro definition files
when someone runs the compiled program, write
eval-when-compile around the require calls (see section Evaluation During Compilation).
This function byte-compiles the function definition of symbol,
replacing the previous definition with the compiled one. The function
definition of symbol must be the actual code for the function;
i.e., the compiler does not follow indirection to another symbol.
byte-compile returns the new, compiled definition of
symbol.
If symbol’s definition is a compiled-function object,
byte-compile does nothing and returns 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.”
(defun factorial (integer)
"Compute factorial of INTEGER."
(if (= 1 integer) 1
(* integer (factorial (1- integer)))))
⇒ factorial
(byte-compile 'factorial) ⇒ #<compiled-function (integer) "...(21)" [integer 1 factorial] 3 "Compute factorial of INTEGER."> |
The result is a compiled-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.
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.
If arg is non-nil, the result is inserted in the current
buffer after the form; otherwise, it is printed in the minibuffer.
This function compiles a file of Lisp code named filename into a file of byte-code. The output file’s name is made by appending ‘c’ to the end of filename.
If load is non-nil, the file is loaded after having been
compiled.
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 t. When called interactively, it prompts
for the file name.
% ls -l push* -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el (byte-compile-file "~/emacs/push.el")
⇒ t
% ls -l push* -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el -rw-r--r-- 1 lewis 638 Oct 8 20:25 push.elc |
This function recompiles every ‘.el’ file in directory that needs recompilation. A file needs recompilation if a ‘.elc’ file exists but is older than the ‘.el’ file.
Files in subdirectories of directory are also processed unless
optional argument norecursion is non-nil.
When a ‘.el’ file has no corresponding ‘.elc’ file, then
flag says what to do. If it is nil, these files are
ignored. If it is non-nil, the user is asked whether to compile
each such file.
If the fourth optional argument force is non-nil,
recompile every ‘.el’ file that already has a ‘.elc’ file.
The return value of this command is unpredictable.
This function runs 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.)
% xemacs -batch -f batch-byte-compile *.el |
This function is similar to batch-byte-compile but runs the
command byte-recompile-directory on the files remaining on the
command line.
When non-nil, byte-recompile-directory will continue
compiling even when an error occurs in a file. Default: nil, but
bound to t by batch-byte-recompile-directory.
When non-nil, byte-recompile-directory will recurse on
subdirectories. Default: t.
This function actually interprets byte-code. Don’t call 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 due to an explicit
call to byte-code. A byte-compiled function was once actually
defined with a body that calls byte-code, but in recent versions
of Emacs byte-code is only used to run isolated fragments of lisp
code without an associated argument list.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Warning: this node is a quick draft based on docstrings. There may be inaccuracies, as the docstrings occasionally disagree with each other. This has not been checked yet.
The byte compiler and optimizer are controlled by the following
variables. The byte-compiler-options macro described below
provides a convenient way to set most of them on a file-by-file basis.
Regexp which matches Emacs Lisp source files.
You may want to redefine byte-compile-dest-file if you change
this. Default: "\\.el$".
Convert an Emacs Lisp source file name to a compiled file name. This
function may be redefined by the user, if necessary, for compatibility
with emacs-lisp-file-regexp.
When non-nil, print messages describing progress of
byte-compiler. Default: t if interactive on a not-too-slow
terminal (see search-slow-speed), otherwise nil.
Level of optimization in the byte compiler.
nilDo no optimization.
tDo all optimizations.
sourceDo optimizations manipulating the source code only.
byteDo optimizations manipulating the byte code (actually, LAP code) only.
Default: t.
When non-nil, the optimizer may delete forms that may signal an
error if that is the only change in the function’s behavior.
This includes variable references and calls to functions such as
car.
Default: t.
When non-nil, the byte-compiler logs optimizations into
‘*Compile-Log*’.
nilLog no optimization.
tLog all optimizations.
sourceLog optimizations manipulating the source code only.
byteLog optimizations manipulating the byte code (actually, LAP code) only.
Default: nil.
When non-nil, the byte-compiler reports warnings with error.
Default: nil.
The warnings used when byte-compile-warnings is t. Called
byte-compile-warning-types in GNU Emacs.
Default: (redefine callargs subr-callargs free-vars unresolved
unused-vars obsolete).
List of warnings that the compiler should issue (t for the
default set). Elements of the list may be:
free-varsReferences to variables not in the current lexical scope.
unused-varsReferences to non-global variables bound but not referenced.
unresolvedCalls to unknown functions.
callargsLambda calls with args that don’t match the definition.
subr-callargsCalls to subrs with args that don’t match the definition.
redefineFunction cell redefined from a macro to a lambda or vice versa, or redefined to take a different number of arguments.
obsoleteUse of an obsolete function or variable.
pedanticWarn of use of compatible symbols.
The default set is specified by byte-compile-default-warnings and
normally encompasses all possible warnings.
See also the macro byte-compiler-options. Default: t.
The compiler can generate a call graph, which gives information about which functions call which functions.
When non-nil, the compiler generates a call graph. This records
functions that were called and from where. If the value is t,
compilation displays the call graph when it finishes. If the value is
neither t nor nil, compilation asks you whether to display
the graph.
The call tree only lists functions called, not macros used. Those
functions which the byte-code interpreter knows about directly
(eq, cons, etc.) are not reported.
The call tree also lists those functions which are not known to be called
(that is, to which no calls have been compiled). Functions which can be
invoked interactively are excluded from this list. Default: nil.
Alist of functions and their call tree, used internally. Each element takes the form
(function callers calls)
where callers is a list of functions that call function, and calls is a list of functions for which calls were generated while compiling function.
When non-nil, sort the call tree. The values name,
callers, calls, and calls+callers specify different
fields to sort on.") Default: name.
byte-compile-overwrite-file controls treatment of existing
compiled files.
When non-nil, do not preserve backups of ‘.elc’s.
Precisely, if nil, old ‘.elc’ files are deleted before the
new one is saved, and ‘.elc’ files will have the same modes as the
corresponding ‘.el’ file. Otherwise, existing ‘.elc’ files
will simply be overwritten, and the existing modes will not be changed.
If this variable is nil, then an ‘.elc’ file which is a
symbolic link will be turned into a normal file, instead of the file
which the link points to being overwritten. Default: t.
Variables controlling recompiling directories are described elsewhere
See section The Compilation Functions. They are
byte-recompile-directory-ignore-errors-p and
byte-recompile-directory-recursively.
The dynamic loading features are described elsewhere. These are
controlled by the variables byte-compile-dynamic (see section Dynamic Loading of Individual Functions) and byte-compile-dynamic-docstrings (see section Documentation Strings and Compilation).
The byte compiler is a relatively recent development, and has evolved significantly over the period covering Emacs versions 19 and 20. The following variables control use of newer functionality by the byte compiler. These are rarely needed since the release of XEmacs 21.
Another set of compatibility issues arises between Mule and non-Mule XEmacsen; there are no known compatibility issues specific to the byte compiler. There are also compatibility issues between XEmacs and GNU Emacs’s versions of the byte compiler. While almost all of the byte codes are the same, and code compiled by one version often runs perfectly well on the other, this is very dangerous, and can result in crashes or data loss. Always recompile your Lisp when moving between XEmacs and GNU Emacs.
When non-nil, the choice of emacs version (v19 or v20) byte-codes
will be hard-coded into bytecomp when it compiles itself. If the
compiler itself is compiled with optimization, this causes a speedup.
Default: nil.
When non-nil generate output that can run in Emacs 19.
Default: nil when Emacs version is 20 or above, otherwise
t.
When non-nil, the compiler may generate code that creates unique
symbols at run-time. This is achieved by printing uninterned symbols
using the #:symbol notation, so that they will be read
uninterned when run.
With this feature, code that uses uninterned symbols in macros will not be runnable under pre-21.0 XEmacsen.
Default: When byte-compile-emacs19-compatibility is non-nil, this
variable is ignored and considered to be nil. Otherwise
t.
This is completely ignored. For backwards compatibility.
Set some compilation-parameters for this file. This will affect only the file in which it appears; this does nothing when evaluated, or when loaded from a ‘.el’ file.
Each argument to this macro must be a list of a key and a value. (#### Need to check whether the newer variables are settable here.)
Keys: Values: Corresponding variable: verbose t, nil byte-compile-verbose optimize t, nil, source, byte byte-optimize warnings list of warnings byte-compile-warnings file-format emacs19, emacs20 byte-compile-emacs19-compatibility |
The value specified with the warningsoption must be a list,
containing some subset of the following flags:
free-vars references to variables not in the current lexical scope. unused-vars references to non-global variables bound but not referenced. unresolved calls to unknown functions. callargs lambda calls with args that don't match the definition. redefine function cell redefined from a macro to a lambda or vice versa, or redefined to take a different number of arguments. |
If the first element if the list is + or ‘ then the
specified elements are added to or removed from the current set of
warnings, instead of the entire set of warnings being overwritten.
(#### Need to check whether the newer warnings are settable here.)
For example, something like this might appear at the top of a source file:
(byte-compiler-options
(optimize t)
(warnings (- callargs)) ; Don't warn about arglist mismatch
(warnings (+ unused-vars)) ; Do warn about unused bindings
(file-format emacs19))
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 normally not enough to bother users.
Dynamic access to documentation strings does have drawbacks:
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.
Versions of Emacs up to and including XEmacs 19.14 and FSF Emacs 19.28
do not support the dynamic docstrings feature, and so will not be able
to load bytecode created by more recent Emacs versions. You can turn
off the dynamic docstring feature by setting
byte-compile-dynamic-docstrings to 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:
-*-byte-compile-dynamic-docstrings: nil;-*- |
If this is non-nil, the byte compiler generates compiled files
that are set up for dynamic loading of documentation strings.
Default: t.
The dynamic documentation string feature writes compiled files that use a special Lisp reader construct, ‘#@count’. This construct skips the next count characters. It also uses the ‘#$’ construct, which stands for “the name of this file, as a string.” It is best not to use these constructs in Lisp source files.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When you compile a file, you can optionally enable the dynamic function loading feature (also known as 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 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.
The dynamic loading feature has certain disadvantages:
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.
The byte compiler uses the dynamic function loading feature if the
variable byte-compile-dynamic is non-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:
-*-byte-compile-dynamic: t;-*- |
If this is non-nil, the byte compiler generates compiled files
that are set up for dynamic function loading.
Default: nil.
This immediately finishes loading the definition of function from its byte-compiled file, if it is not fully loaded already. The argument function may be a compiled-function object or a function name.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These features permit you to write code to be evaluated during compilation of a program.
This form marks 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 body in a separate file
and referring to that file with require. Using require is
preferable if there is a substantial amount of code to be executed in
this way.
This form marks body to be evaluated at compile time and 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, body is evaluated normally.
At top level, this is analogous to the Common Lisp idiom
(eval-when (compile eval) …). Elsewhere, the Common Lisp
‘#.’ reader macro (but not when interpreting) is closer to what
eval-when-compile does.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Byte-compiled functions have a special data type: they are compiled-function objects. The evaluator handles this data type specially when it appears as a function to be called.
The printed representation for a compiled-function object normally
begins with ‘#<compiled-function’ and ends with ‘>’. However,
if the variable print-readably is non-nil, the object is
printed beginning with ‘#[’ and ending with ‘]’. This
representation can be read directly by the Lisp reader, and is used in
byte-compiled files (those ending in ‘.elc’).
In Emacs version 18, there was no compiled-function object data type;
compiled functions used the function byte-code to run the byte
code.
A compiled-function object has a number of different attributes. They are:
The list of argument symbols.
The string containing the byte-code instructions.
The vector of Lisp objects referenced by the byte code. These include symbols used as function names and variable names.
The maximum stack size this function needs.
The documentation string (if any); otherwise, nil. The value may
be a number or a list, in case the documentation string is stored in a
file. Use the function documentation to get the real
documentation string (see section Access to Documentation Strings).
The interactive spec (if any). This can be a string or a Lisp
expression. It is nil for a function that isn’t interactive.
The domain (if any). This is only meaningful if I18N3 (message-translation) support was compiled into XEmacs. This is a string defining which domain to find the translation for the documentation string and interactive prompt. See section Domain Specification.
Here’s an example of a compiled-function object, in printed
representation. It is the definition of the command
backward-sexp.
(symbol-function 'backward-sexp) ⇒ #<compiled-function (&optional arg) "...(15)" [arg 1 forward-sexp] 2 854740 "_p"> |
The primitive way to create a compiled-function object is with
make-byte-code:
This function constructs and returns a compiled-function object with the specified attributes.
Please note: Unlike all other Emacs-lisp functions, calling this with
five arguments is not the same as calling it with six arguments,
the last of which is nil. If the interactive arg is
specified as nil, then that means that this function was defined
with (interactive). If the arg is not specified, then that means
the function is not interactive. This is terrible behavior which is
retained for compatibility with old ‘.elc’ files which expected
these semantics.
You should not try to come up with the elements for a compiled-function object yourself, because if they are inconsistent, XEmacs 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).
The following primitives are provided for accessing the elements of a compiled-function object.
This function returns the argument list of compiled-function object function.
This function returns a string describing the byte-code instructions of compiled-function object function.
This function returns the vector of Lisp objects referenced by compiled-function object function.
This function returns the maximum stack size needed by compiled-function object function.
This function returns the doc string of compiled-function object function, if available.
This function returns the interactive spec of compiled-function object
function, if any. The return value is nil or a two-element
list, the first element of which is the symbol interactive and
the second element is the interactive spec (a string or Lisp form).
This function returns the domain of compiled-function object
function, if any. The result will be a string or nil.
See section Domain Specification.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
People do not write byte-code; that job is left to the byte compiler. But we provide a disassembler to satisfy a cat-like curiosity. The disassembler converts the byte-compiled code into humanly readable form.
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 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 ordinary Lisp variables, by transferring values between variables and the stack.
This function prints the disassembled code for object. If
stream is supplied, then output goes there. Otherwise, the
disassembled code is printed to the stream standard-output. The
argument 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 ‘*Disassemble*’.
Here are two examples of using the disassemble function. We
have added explanatory comments to help you relate the byte-code to the
Lisp source; these do not appear in the output of disassemble.
(defun factorial (integer)
"Compute factorial of an integer."
(if (= 1 integer) 1
(* integer (factorial (1- integer)))))
⇒ factorial
(factorial 4)
⇒ 24
(disassemble 'factorial)
-| byte-code for factorial:
doc: Compute factorial of an integer.
args: (integer)
0 varref integer ; Get value of 2 eqlsign ; Pop top two values off stack, ; compare them, ; and push result onto stack. 3 goto-if-nil 1 ; Pop and test top of stack;
; if 5 constant 1 ; Push 1 onto top of stack. 6 return ; Return the top element ; of the stack.
7:1 varref integer ; Push value of 8 constant factorial ; Push ; Stack now contains: ; - decremented value of 15 call 1 ; Call function ; Stack now contains: ; - result of recursive ; call to 12 mult ; Pop top two values off the stack, ; multiply them, ; pushing the result onto the stack. 13 return ; Return the top element ; of the stack. ⇒ nil |
The silly-loop function is somewhat more complex:
(defun silly-loop (n)
"Return time before and after N iterations of a loop."
(let ((t1 (current-time-string)))
(while (> (setq n (1- n))
0))
(list t1 (current-time-string))))
⇒ silly-loop
(disassemble 'silly-loop)
-| byte-code for silly-loop:
doc: Return time before and after N iterations of a loop.
args: (n)
0 constant current-time-string ; Push
; 1 call 0 ; Call 2 varbind t1 ; Pop stack and bind 3:1 varref n ; Get value of 4 sub1 ; Subtract 1 from top of stack.
5 dup ; Duplicate the top of the stack; ; i.e., copy the top of ; the stack and push the ; copy onto the stack. 6 varset n ; Pop the top of the stack, ; and set 7 constant 0 ; Push 0 onto stack. 8 gtr ; Pop top two values off stack, ; test if n is greater than 0 ; and push result onto stack. 9 goto-if-not-nil 1 ; Goto label 1 (byte 3) if 11 varref t1 ; Push value of 12 constant current-time-string ; Push
; 13 call 0 ; Call 15 list2 ; Pop top two elements off stack, ; create a list of them, ; and push list onto stack. 16 return ; Return the top element of the stack.
⇒ nil
|
For maximal equivalence between interpreted and compiled code, the
variables byte-compile-delete-errors and
byte-compile-optimize can be set to nil, but this is not
recommended.
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.