[ << ] | [ < ] | [ 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-code 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 Emacs 19.29, the compiled code does not run in earlier versions. 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.
@xref{Compilation Errors}, for how to investigate errors occurring in byte compilation.
1.1 Performance of Byte-Compiled Code | An example of speedup from byte compilation. | |
1.2 The Compilation Functions | Byte compilation functions. | |
1.3 Documentation Strings and Compilation | Dynamic loading of documentation strings. | |
1.4 Dynamic Loading of Individual Functions | Dynamic loading of individual functions. | |
1.5 Evaluation During Compilation | Code to be evaluated when you compile. | |
1.6 Byte-Code Function Objects | The data type used for byte-compiled functions. | |
1.7 Disassembled Byte-Code | Disassembling byte-code; how to read byte-code. |
[ << ] | [ < ] | [ 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 100000)
⇒ ("Fri Mar 18 17:25:57 1994"
"Fri Mar 18 17:26:28 1994") ; 31 seconds
(byte-compile 'silly-loop)
⇒ [Compiled code not shown]
(silly-loop 100000)
⇒ ("Fri Mar 18 17:26:52 1994"
"Fri Mar 18 17:26:58 1994") ; 6 seconds
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.
[ << ] | [ < ] | [ 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 @ref{Compiling Macros}.
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 (@pxref{Named 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 byte-code 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) ⇒ #<byte-code (integer) "ÁU«‚Á‡ÂS!_‡" [integer 1 factorial] 3 "Compute factorial of INTEGER.">
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.
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-rw-rw- 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.
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.
The returned 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.)
% emacs -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.
If non-nil
, this specifies that byte-recompile-directory
will continue compiling even when an error occurs in a file. This is
normally nil
, but is bound to t
by
batch-byte-recompile-directory
.
This function actually interprets byte-code. A byte-compiled function
is actually defined with a body that calls 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 byte-code function object, and only rarely due to an explicit
call to byte-code
.
[ << ] | [ < ] | [ 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 this normally is 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.
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 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.
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.
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 byte-code 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 byte-code function objects.
Internally, a byte-code function object is much like a vector; however, the evaluator handles this data type specially when it appears as a function to be called. The printed representation for a byte-code function object begins with ‘#<byte-code’ and ends with ‘>’.
In Emacs version 18, there was no byte-code function object data type;
compiled functions used the function 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. 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 (@pxref{Accessing Documentation}).
The interactive spec (if any). This can be a string or a Lisp
expression. It is nil
for a function that isn’t interactive.
Here’s an example of a byte-code function object, in printed
representation. It is the definition of the command
backward-sexp
.
#[(&optional arg) "^H\204^F^@\301^P\302^H[!\207" [arg 1 forward-sexp] 2 254435 "p"]
The primitive way to create a byte-code object is with
make-byte-code
:
This function constructs and returns a byte-code function object with elements as its elements.
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 aref
;
you can also use vconcat
to create a vector with the same
elements.
[ << ] | [ < ] | [ 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
.
These examples show unoptimized byte-code. Nowadays byte-code is
usually optimized, but we did not want to rewrite these examples, since
they still serve their purpose.
(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 constant 1 ; Push 1 onto stack.
1 varref integer ; Get value of integer
; from the environment
; and push the value
; onto the stack.
2 eqlsign ; Pop top two values off stack, ; compare them, ; and push result onto stack.
3 goto-if-nil 10 ; Pop and test top of stack;
; if nil
, go to 10,
; else continue.
6 constant 1 ; Push 1 onto top of stack. 7 goto 17 ; Go to 17 (in this case, 1 will be ; returned by the function).
10 constant * ; Push symbol*
onto stack. 11 varref integer ; Push value ofinteger
onto stack.
12 constant factorial ; Pushfactorial
onto stack. 13 varref integer ; Push value ofinteger
onto stack. 14 sub1 ; Popinteger
, decrement value, ; push new value onto stack.
; Stack now contains: ; - decremented value ofinteger
; -factorial
; - value ofinteger
; -*
15 call 1 ; Call function factorial
using
; the first (i.e., the top) element
; of the stack as the argument;
; push returned value onto stack.
; Stack now contains: ; - result of recursive ; call tofactorial
; - value ofinteger
; -*
16 call 2 ; Using the first two
; (i.e., the top two)
; elements of the stack
; as arguments,
; call the function *
,
; pushing the result onto the stack.
17 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
; current-time-string
; onto top of stack.
1 call 0 ; Call current-time-string
; with no argument,
; pushing result onto stack.
2 varbind t1 ; Pop stack and bind t1
; to popped value.
3 varref n ; Get value of n
from
; the environment and push
; the value onto the stack.
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 bindn
to the value. ; In effect, the sequencedup varset
; copies the top of the stack ; into the value ofn
; without popping it.
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-nil-else-pop 17 ; Goto 17 if n
<= 0
; (this exits the while loop).
; else pop top of stack
; and continue
12 constant nil ; Push nil
onto stack
; (this is the body of the loop).
13 discard ; Discard result of the body ; of the loop (a while loop ; is always evaluated for ; its side effects).
14 goto 3 ; Jump back to beginning ; of while loop.
17 discard ; Discard result of while loop
; by popping top of stack.
; This result is the value nil
that
; was not popped by the goto at 9.
18 varref t1 ; Push value of t1
onto stack.
19 constant current-time-string ; Push
; current-time-string
; onto top of stack.
20 call 0 ; Call current-time-string
again.
21 list2 ; Pop top two elements off stack, ; create a list of them, ; and push list onto stack.
22 unbind 1 ; Unbind t1
in local environment.
23 return ; Return value of the top of stack.
⇒ nil
[Top] | [Contents] | [Index] | [ ? ] |
This document was generated on December 6, 2024 using texi2html 5.0.
The buttons in the navigation panels have the following meaning:
Button | Name | Go to | From 1.2.3 go to |
---|---|---|---|
[ << ] | FastBack | Beginning of this chapter or previous chapter | 1 |
[ < ] | Back | Previous section in reading order | 1.2.2 |
[ Up ] | Up | Up section | 1.2 |
[ > ] | Forward | Next section in reading order | 1.2.4 |
[ >> ] | FastForward | Next chapter | 2 |
[Top] | Top | Cover (top) of document | |
[Contents] | Contents | Table of contents | |
[Index] | Index | Index | |
[ ? ] | About | About (help) |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
This document was generated on December 6, 2024 using texi2html 5.0.