Emacs 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.
If you do not want a Lisp file to be compiled, ever, put a file-local
variable binding for no-byte-compile into it, like this:
;; -*-no-byte-compile: t; -*-
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 the time, in seconds, to run N iterations of a loop."
(let ((t1 (float-time)))
(while (> (setq n (1- n)) 0))
(- (float-time) t1)))
⇒ silly-loop
(silly-loop 50000000) ⇒ 5.200886011123657
(byte-compile 'silly-loop)
⇒ [Compiled code not shown]
(silly-loop 50000000) ⇒ 0.6239290237426758
In this example, the interpreted code required more than 5 seconds to run, whereas the byte-compiled code required less than 1 second. These results are representative, but actual results may vary.
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.
Sometimes, the byte compiler produces warning and/or error messages
(see Compiler Errors, for details). These messages are normally
recorded in a buffer called *Compile-Log*, which uses
Compilation mode. See Compilation Mode in The GNU Emacs
Manual. However, if the variable byte-compile-debug is
non-nil, error messages will be signaled as Lisp errors instead
(see Errors).
Be careful when writing macro calls in files that you intend to
byte-compile. Since macro calls are expanded when they are compiled,
the macros need to be loaded into Emacs or the byte compiler will not
do the right thing. The usual way to handle this is with
require forms which specify the files containing the needed
macro definitions (see Features). Normally, the
byte compiler does not evaluate the code that it is compiling, but it
handles require forms specially, by loading the specified
libraries. To avoid loading the macro definition files when someone
runs the compiled program, write eval-when-compile
around the require calls (see Evaluation During Compilation). For
more details, See Macros and Byte Compilation.
Inline (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.
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;
byte-compile does not handle function indirection. The return
value is the byte-code function object which is the compiled
definition of symbol (see Closure Function Objects).
(defun factorial (integer)
"Compute factorial of INTEGER."
(if (= 1 integer) 1
(* integer (factorial (1- integer)))))
⇒ factorial
(byte-compile 'factorial) ⇒ #[257 "\211\300U\203^H^@\300\207\211\301^BS!_\207" [1 factorial] 4 "Compute factorial of INTEGER.\n\n(fn INTEGER)"]
If symbol’s definition is a byte-code function object,
byte-compile does nothing and returns nil. It does not
compile the symbol’s definition again, since the original
(non-compiled) code has already been replaced in the symbol’s function
cell by the byte-compiled code.
The argument to byte-compile can also be a lambda
expression. In that case, the function returns the corresponding
compiled code but does not store it anywhere.
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.
compile-defun normally displays the result of evaluation in the
echo area, but if arg is non-nil, it inserts the result
in the current buffer after the form it has compiled.
This function compiles a file of Lisp code named filename into a file of byte-code. The output file’s name is made by changing the ‘.el’ suffix into ‘.elc’; if filename does not end in ‘.el’, it adds ‘.elc’ to the end of 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 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 if there were no errors and nil
otherwise. When called interactively, it prompts for the file name.
$ ls -l push* -rw-r--r-- 1 lewis lewis 791 Oct 5 20:31 push.el
(byte-compile-file "~/emacs/push.el")
⇒ t
$ ls -l push* -rw-r--r-- 1 lewis lewis 791 Oct 5 20:31 push.el -rw-rw-rw- 1 lewis lewis 638 Oct 8 20:25 push.elc
This command recompiles every ‘.el’ file in directory (or its subdirectories) 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,
flag says what to do. If it is nil, this command ignores
these files. If flag is 0, it compiles them. If it is neither
nil nor 0, it asks the user whether to compile each such file,
and asks about each subdirectory as well.
Interactively, byte-recompile-directory prompts for
directory and flag is the prefix argument.
If force is non-nil, this command recompiles every
‘.el’ file that has a ‘.elc’ file.
This command will normally not compile ‘.el’ files that are
symlinked. If the optional follow-symlink parameter is
non-nil, symlinked ‘.el’ will also be compiled.
The returned value 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, but no output file will be
generated for it, and the Emacs process will terminate with a nonzero
status code.
If noforce is non-nil, this function does not recompile
files that have an up-to-date ‘.elc’ file.
$ emacs -batch -f batch-byte-compile *.el
When Emacs loads functions and variables from a byte-compiled file, it normally does not load their documentation strings into memory. Each documentation string is dynamically loaded from the byte-compiled file only when needed. This saves memory, and speeds up loading by skipping the processing of the documentation strings.
This feature has a drawback: if you delete, move, or alter the compiled file (such as by compiling a new version), Emacs may no longer be able to access the documentation string of previously-loaded functions or variables. Such a problem normally only occurs if you build Emacs yourself, and happen to edit and/or recompile the Lisp source files. To solve it, just reload each file after recompilation.
Dynamic loading of documentation strings from byte-compiled files is
determined, at compile time, for each byte-compiled file. It can be
disabled via the option byte-compile-dynamic-docstrings.
If this is non-nil, the byte compiler generates compiled files
that are set up for dynamic loading of documentation strings.
To disable the dynamic loading feature for a specific file, set this
option to nil in its header line (see Local Variables in Files in The GNU Emacs Manual), like this:
-*-byte-compile-dynamic-docstrings: nil;-*-
This is useful mainly if you expect to change the file, and you want Emacs sessions that have already loaded it to keep working when the file changes.
Internally, the dynamic loading of documentation strings is accomplished by writing compiled files with 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. Do not use these constructs in Lisp source files; they are not designed to be clear to humans reading the file.
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. That method is
preferable when body is large. Effectively require is
automatically eval-and-compile, the package is loaded both when
compiling and executing.
autoload is also effectively eval-and-compile too. It’s
recognized when compiling, so uses of such a function don’t produce
“not known to be defined” warnings.
Most uses of 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
eval-and-compile should be used to get the helper both when
compiling and then later when running.
If functions are defined programmatically (with fset say), then
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).
This form marks 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, body is evaluated normally.
If you have a constant that needs some calculation to produce,
eval-when-compile can do that at compile-time. For example,
(defvar gauss-schoolboy-problem (eval-when-compile (apply #'+ (number-sequence 1 100))))
If you’re using another package, but only need macros from it (the
byte compiler will expand those), then eval-when-compile can be
used to load it for compiling, but not executing. For example,
(eval-when-compile (require 'my-macro-package))
The same sort of thing goes for macros and defsubst functions
defined locally and only for use within the file. They are needed for
compiling the file, but in most cases they are not needed for
execution of the compiled file. For example,
(eval-when-compile
(unless (fboundp 'some-new-thing)
(defmacro some-new-thing ()
(compatibility code))))
This is often good for code that’s only a fallback for compatibility with other versions of Emacs.
Common Lisp Note: At top level, eval-when-compile 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.
Error and warning messages from byte compilation are printed in a buffer named *Compile-Log*. These messages include file names and line numbers identifying the location of the problem. The usual Emacs commands for operating on compiler output can be used on these messages.
When an error is due to invalid syntax in the program, the byte compiler might get confused about the error’s exact location. One way to investigate is to switch to the buffer *Compiler Input*. (This buffer name starts with a space, so it does not show up in the Buffer Menu.) This buffer contains the program being compiled, and point shows how far the byte compiler was able to read; the cause of the error might be nearby. See Debugging Invalid Lisp Syntax, for some tips for locating syntax errors.
A common type of warning issued by the byte compiler is for functions and variables that were used but not defined. Such warnings report the line number for the end of the file, not the locations where the missing functions or variables were used; to find these, you must search the file manually.
If you are sure that a warning message about a missing function or variable is unjustified, there are several ways to suppress it:
fboundp test, like
this:
(if (fboundp 'func) ...(func ...)...)
The call to func must be in the then-form of the
if, and func must appear quoted in the call to
fboundp. (This feature operates for cond as well.)
boundp
test:
(if (boundp 'variable) ...variable...)
The reference to variable must be in the then-form of the
if, and variable must appear quoted in the call to
boundp.
declare-function. See Telling the Compiler that a Function is Defined.
defvar with no initial value. (Note that this marks the
variable as special, i.e. dynamically bound, but only within the
current lexical scope, or file if at top-level.) See Defining Global Variables.
You can also suppress compiler warnings within a certain expression
using the with-suppressed-warnings macro:
In execution, this is equivalent to (progn body...), but
the compiler does not issue warnings for the specified conditions in
body. warnings is an association list of warning symbols
and function/variable symbols they apply to. For instance, if you
wish to call an obsolete function called foo, but want to
suppress the compilation warning, say:
(with-suppressed-warnings ((obsolete foo)) (foo ...))
For more coarse-grained suppression of compiler warnings, you can use
the with-no-warnings construct:
In execution, this is equivalent to (progn body...),
but the compiler does not issue warnings for anything that occurs
inside body.
We recommend that you use with-suppressed-warnings instead, but
if you do use this construct, that you use it around the smallest
possible piece of code to avoid missing possible warnings other than
one you intend to suppress.
Byte compiler warnings can be controlled more precisely by setting
the variable byte-compile-warnings. See its documentation
string for details.
Sometimes you may wish the byte-compiler warnings to be reported
using error. If so, set byte-compile-error-on-warn to a
non-nil value.
Byte-compiled functions use a special data type: they are closures. Closures are used both for byte-compiled Lisp functions as well as for interpreted Lisp functions. Whenever such an object appears as a function to be called, Emacs uses the appropriate interpreter to execute either the byte-code or the non-compiled Lisp code.
Internally, a closure is much like a vector; its
elements can be accessed using aref. Its printed
representation is like that for a vector, with an additional ‘#’
before the opening ‘[’. It must have at least three elements;
there is no maximum number, but only the first six elements have any
normal use. They are:
The descriptor of the arguments. This can either be a list of
arguments, as described in Features of Argument Lists, or an integer encoding
the required number of arguments. In the latter case, the value of
the descriptor specifies the minimum number of arguments in the bits
zero to 6, and the maximum number of arguments in bits 8 to 14. If
the argument list uses &rest, then bit 7 is set; otherwise it’s
cleared.
When the closure is a byte-code function, if argdesc is a list, the arguments will be dynamically bound before executing the byte code. If argdesc is an integer, the arguments will be instead pushed onto the stack of the byte-code interpreter, before executing the code.
For interpreted functions, this element is the (non-empty) list of Lisp forms that make up the function’s body. For byte-compiled functions, it is the string containing the byte-code instructions.
For byte-compiled functions, this holds the vector of Lisp objects
referenced by the byte code. These include symbols used as function
names and variable names.
For interpreted functions, this is nil if the function is using the old
dynamically scoped dialect of Emacs Lisp, and otherwise it holds the
function’s lexical environment.
The maximum stack size this function needs. This element is left unused for interpreted functions.
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 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.
Here’s an example of a byte-code function object, in printed
representation. It is the definition of the command
backward-sexp.
#[256 "\211\204^G^@\300\262^A\301^A[!\207" [1 forward-sexp] 3 1793299 "^p"]
The primitive way to create a byte-code object is with
make-byte-code:
This function constructs and returns a closure which represents the 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).
The primitive way to create an interpreted function is with
make-interpreted-closure:
This function constructs and returns a closure representing the
interpreted function with arguments args and whose body is made of
body which must be a non-nil list of Lisp forms. env is the
lexical environment in the same form as used with eval
(see Eval). The documentation docstring if non-nil should be
a string, and the interactive form iform if non-nil should be of
the form (interactive arg-descriptor) (see Using interactive).
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 human-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 command displays the disassembled code for object. In
interactive use, or if buffer-or-name is nil or omitted,
the output goes in a buffer named *Disassemble*. If
buffer-or-name is non-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 object can be a function name, a lambda expression
(see Lambda Expressions), or a byte-code object (see Closure Function Objects). If it is a lambda expression, disassemble compiles
it and disassembles the resulting compiled code.
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: (arg1)
0 dup ; Get the value of integer and
; push it onto the stack.
1 constant 1 ; Push 1 onto stack.
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 nil, go to 1, else continue.
6 constant 1 ; Push 1 onto top of stack.
7 return ; Return the top element of the stack.
8:1 dup ; Push value ofintegeronto stack. 9 constant factorial ; Pushfactorialonto stack. 10 stack-ref 2 ; Push value ofintegeronto stack. 11 sub1 ; Popinteger, decrement value, ; push new value onto stack. 12 call 1 ; Call functionfactorialusing first ; (i.e., top) stack element as argument; ; push returned value onto stack.
13 mult ; Pop top two values off stack, multiply ; them, and push result onto stack. 14 return ; Return the top element of the stack.
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: (arg1)
0 constant current-time-string ; Push current-time-string
; onto top of stack.
1 call 0 ; Callcurrent-time-stringwith no ; argument, push result onto stack ast1.
2:1 stack-ref 1 ; Get value of the argument n
; and push the value on the stack.
3 sub1 ; Subtract 1 from top of stack.
4 dup ; Duplicate top of stack; i.e., copy the top ; of the stack and push copy onto stack. 5 stack-set 3 ; Pop the top of the stack, ; and setnto the value. ;; (In effect, the sequencedup stack-setcopies the top of ;; the stack into the value ofnwithout 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-not-nil 1 ; Goto 1 if n > 0
; (this continues the while loop)
; else continue.
12 dup ; Push value oft1onto stack. 13 constant current-time-string ; Pushcurrent-time-string; onto the top of the stack. 14 call 0 ; Callcurrent-time-stringagain.
15 list2 ; Pop top two elements off stack, create a ; list of them, and push it onto stack. 16 return ; Return value of the top of stack.