2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/compile
6 @node Byte Compilation, Debugging, Loading, Top
7 @chapter Byte Compilation
11 GNU Emacs Lisp has a @dfn{compiler} that translates functions written
12 in Lisp into a special representation called @dfn{byte-code} that can be
13 executed more efficiently. The compiler replaces Lisp function
14 definitions with byte-code. When a byte-code function is called, its
15 definition is evaluated by the @dfn{byte-code interpreter}.
17 Because the byte-compiled code is evaluated by the byte-code
18 interpreter, instead of being executed directly by the machine's
19 hardware (as true compiled code is), byte-code is completely
20 transportable from machine to machine without recompilation. It is not,
21 however, as fast as true compiled code.
23 In general, any version of Emacs can run byte-compiled code produced
24 by recent earlier versions of Emacs, but the reverse is not true. In
25 particular, if you compile a program with Emacs 18, you can run the
26 compiled code in Emacs 19, but not vice versa.
28 @xref{Compilation Errors}, for how to investigate errors occurring in
32 * Compilation Functions:: Byte compilation functions.
33 * Eval During Compile:: Code to be evaluated when you compile.
34 * Byte-Code Objects:: The data type used for byte-compiled functions.
35 * Disassembly:: Disassembling byte-code; how to read byte-code.
38 @node Compilation Functions
39 @comment node-name, next, previous, up
40 @section The Compilation Functions
41 @cindex compilation functions
43 You can byte-compile an individual function or macro definition with
44 the @code{byte-compile} function. You can compile a whole file with
45 @code{byte-compile-file}, or several files with
46 @code{byte-recompile-directory} or @code{batch-byte-compile}.
48 When you run the byte compiler, you may get warnings in a buffer called
49 @samp{*Compile-Log*}. These report usage in your program that suggest a
50 problem, but are not necessarily erroneous.
52 @cindex macro compilation
53 Be careful when byte-compiling code that uses macros. Macro calls are
54 expanded when they are compiled, so the macros must already be defined
55 for proper compilation. For more details, see @ref{Compiling Macros}.
57 While byte-compiling a file, any @code{require} calls at top-level are
58 executed. One way to ensure that necessary macro definitions are
59 available during compilation is to require the file that defines them.
62 A byte-compiled function is not as efficient as a primitive function
63 written in C, but runs much faster than the version written in Lisp.
64 For a rough comparison, consider the example below:
69 "Return time before and after N iterations of a loop."
70 (let ((t1 (current-time-string)))
71 (while (> (setq n (1- n))
73 (list t1 (current-time-string))))
79 @result{} ("Thu Jan 12 20:18:38 1989"
80 "Thu Jan 12 20:19:29 1989") ; @r{51 seconds}
84 (byte-compile 'silly-loop)
85 @result{} @r{[Compiled code not shown]}
90 @result{} ("Thu Jan 12 20:21:04 1989"
91 "Thu Jan 12 20:21:17 1989") ; @r{13 seconds}
95 In this example, the interpreted code required 51 seconds to run,
96 whereas the byte-compiled code required 13 seconds. These results are
97 representative, but actual results will vary greatly.
99 @defun byte-compile symbol
100 This function byte-compiles the function definition of @var{symbol},
101 replacing the previous definition with the compiled one. The function
102 definition of @var{symbol} must be the actual code for the function;
103 i.e., the compiler does not follow indirection to another symbol.
104 @code{byte-compile} does not compile macros. @code{byte-compile}
105 returns the new, compiled definition of @var{symbol}.
109 (defun factorial (integer)
110 "Compute factorial of INTEGER."
112 (* integer (factorial (1- integer)))))
117 (byte-compile 'factorial)
120 "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207"
121 [integer 1 * factorial]
122 4 "Compute factorial of INTEGER."]
127 The result is a compiled function object. The string it contains is the
128 actual byte-code; each character in it is an instruction. The vector
129 contains all the constants, variable names and function names used by
130 the function, except for certain primitives that are coded as special
134 @deffn Command compile-defun
135 This command reads the defun containing point, compiles it, and
136 evaluates the result. If you use this on a defun that is actually a
137 function definition, the effect is to install a compiled version of that
141 @deffn Command byte-compile-file filename
142 This function compiles a file of Lisp code named @var{filename} into
143 a file of byte-code. The output file's name is made by appending
144 @samp{c} to the end of @var{filename}.
146 Compilation works by reading the input file one form at a time. If it
147 is a definition of a function or macro, the compiled function or macro
148 definition is written out. Other forms are batched together, then each
149 batch is compiled, and written so that its compiled code will be
150 executed when the file is read. All comments are discarded when the
153 This command returns @code{t}. When called interactively, it prompts
159 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
163 (byte-compile-file "~/emacs/push.el")
169 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
170 -rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc
175 @deffn Command byte-recompile-directory directory flag
176 @cindex library compilation
177 This function recompiles every @samp{.el} file in @var{directory} that
178 needs recompilation. A file needs recompilation if a @samp{.elc} file
179 exists but is older than the @samp{.el} file.
181 If a @samp{.el} file exists, but there is no corresponding @samp{.elc}
182 file, then @var{flag} is examined. If it is @code{nil}, the file is
183 ignored. If it is non-@code{nil}, the user is asked whether the file
186 The returned value of this command is unpredictable.
189 @defun batch-byte-compile
190 This function runs @code{byte-compile-file} on the files remaining on
191 the command line. This function must be used only in a batch execution
192 of Emacs, as it kills Emacs on completion. An error in one file does
193 not prevent processing of subsequent files. (The file which gets the
194 error will not, of course, produce any compiled code.)
197 % emacs -batch -f batch-byte-compile *.el
201 @defun byte-code code-string data-vector max-stack
202 @cindex byte-code interpreter
203 This function actually interprets byte-code. A byte-compiled function
204 is actually defined with a body that calls @code{byte-code}. Don't call
205 this function yourself. Only the byte compiler knows how to generate
206 valid calls to this function.
208 In newer Emacs versions (19 and up), byte-code is usually executed as
209 part of a compiled function object, and only rarely as part of a call to
213 @node Eval During Compile
214 @section Evaluation During Compilation
216 These features permit you to write code to be evaluated during
217 compilation of a program.
219 @defspec eval-and-compile body
220 This form marks @var{body} to be evaluated both when you compile the
221 containing code and when you run it (whether compiled or not).
223 You can get a similar result by putting @var{body} in a separate file
224 and referring to that file with @code{require}. Using @code{require} is
225 preferable if there is a substantial amount of code to be executed in
229 @defspec eval-when-compile body
230 This form marks @var{body} to be evaluated at compile time @emph{only}.
231 The result of evaluation by the compiler becomes a constant which
232 appears in the compiled program. When the program is interpreted, not
233 compiled at all, @var{body} is evaluated normally.
235 At top-level, this is analogous to the Common Lisp idiom
236 @code{(eval-when (compile eval) @dots{})}. Elsewhere, the Common Lisp
237 @samp{#.} reader macro (but not when interpreting) is closer to what
238 @code{eval-when-compile} does.
241 @node Byte-Code Objects
242 @section Byte-Code Objects
243 @cindex compiled function
244 @cindex byte-code function
246 Byte-compiled functions have a special data type: they are
247 @dfn{byte-code function objects}.
249 Internally, a byte-code function object is much like a vector;
250 however, the evaluator handles this data type specially when it appears
251 as a function to be called. The printed representation for a byte-code
252 function object is like that for a vector, with an additional @samp{#}
253 before the opening @samp{[}.
255 In Emacs version 18, there was no byte-code function object data type;
256 compiled functions used the function @code{byte-code} to run the byte
259 A byte-code function object must have at least four elements; there is
260 no maximum number, but only the first six elements are actually used.
265 The list of argument symbols.
268 The string containing the byte-code instructions.
271 The vector of constants referenced by the byte code.
274 The maximum stack size this function needs.
277 The documentation string (if any); otherwise, @code{nil}. For functions
278 preloaded before Emacs is dumped, this is usually an integer which is an
279 index into the @file{DOC} file; use @code{documentation} to convert this
280 into a string (@pxref{Accessing Documentation}).
283 The interactive spec (if any). This can be a string or a Lisp
284 expression. It is @code{nil} for a function that isn't interactive.
287 Here's an example of a byte-code function object, in printed
288 representation. It is the definition of the command
289 @code{backward-sexp}.
293 "^H\204^F^@@\301^P\302^H[!\207"
300 The primitive way to create a byte-code object is with
301 @code{make-byte-code}:
303 @defun make-byte-code &rest elements
304 This function constructs and returns a byte-code function object
305 with @var{elements} as its elements.
308 You should not try to come up with the elements for a byte-code function
309 yourself, because if they are inconsistent, Emacs may crash when you
310 call the function. Always leave it to the byte-compiler to create these
311 objects; it, we hope, always makes the elements consistent.
313 You can access the elements of a byte-code object using @code{aref};
314 you can also use @code{vconcat} to create a vector with the same
318 @section Disassembled Byte-Code
319 @cindex disassembled byte-code
321 People do not write byte-code; that job is left to the byte compiler.
322 But we provide a disassembler to satisfy a cat-like curiosity. The
323 disassembler converts the byte-compiled code into humanly readable
326 The byte-code interpreter is implemented as a simple stack machine.
327 Values get stored by being pushed onto the stack, and are popped off and
328 manipulated, the results being pushed back onto the stack. When a
329 function returns, the top of the stack is popped and returned as the
330 value of the function.
332 In addition to the stack, values used during byte-code execution can
333 be stored in ordinary Lisp variables. Variable values can be pushed
334 onto the stack, and variables can be set by popping the stack.
336 @deffn Command disassemble object &optional stream
337 This function prints the disassembled code for @var{object}. If
338 @var{stream} is supplied, then output goes there. Otherwise, the
339 disassembled code is printed to the stream @code{standard-output}. The
340 argument @var{object} can be a function name or a lambda expression.
342 As a special exception, if this function is used interactively,
343 it outputs to a buffer named @samp{*Disassemble*}.
346 Here are two examples of using the @code{disassemble} function. We
347 have added explanatory comments to help you relate the byte-code to the
348 Lisp source; these do not appear in the output of @code{disassemble}.
349 These examples show unoptimized byte-code. Nowadays byte-code is
350 usually optimized, but we did not want to rewrite these examples, since
351 they still serve their purpose.
355 (defun factorial (integer)
356 "Compute factorial of an integer."
358 (* integer (factorial (1- integer)))))
368 (disassemble 'factorial)
369 @print{} byte-code for factorial:
370 doc: Compute factorial of an integer.
375 0 constant 1 ; @r{Push 1 onto stack.}
377 1 varref integer ; @r{Get value of @code{integer}}
378 ; @r{from the environment}
379 ; @r{and push the value}
380 ; @r{onto the stack.}
384 2 eqlsign ; @r{Pop top two values off stack,}
386 ; @r{and push result onto stack.}
390 3 goto-if-nil 10 ; @r{Pop and test top of stack;}
391 ; @r{if @code{nil}, go to 10,}
396 6 constant 1 ; @r{Push 1 onto top of stack.}
398 7 goto 17 ; @r{Go to 17 (in this case, 1 will be}
399 ; @r{returned by the function).}
403 10 constant * ; @r{Push symbol @code{*} onto stack.}
405 11 varref integer ; @r{Push value of @code{integer} onto stack.}
409 12 constant factorial ; @r{Push @code{factorial} onto stack.}
411 13 varref integer ; @r{Push value of @code{integer} onto stack.}
413 14 sub1 ; @r{Pop @code{integer}, decrement value,}
414 ; @r{push new value onto stack.}
418 ; @r{Stack now contains:}
419 ; @minus{} @r{decremented value of @code{integer}}
420 ; @minus{} @r{@code{factorial}}
421 ; @minus{} @r{value of @code{integer}}
422 ; @minus{} @r{@code{*}}
426 15 call 1 ; @r{Call function @code{factorial} using}
427 ; @r{the first (i.e., the top) element}
428 ; @r{of the stack as the argument;}
429 ; @r{push returned value onto stack.}
433 ; @r{Stack now contains:}
434 ; @minus{} @r{result of result of recursive}
435 ; @r{call to @code{factorial}}
436 ; @minus{} @r{value of @code{integer}}
437 ; @minus{} @r{@code{*}}
441 16 call 2 ; @r{Using the first two}
442 ; @r{(i.e., the top two)}
443 ; @r{elements of the stack}
445 ; @r{call the function @code{*},}
446 ; @r{pushing the result onto the stack.}
450 17 return ; @r{Return the top element}
456 The @code{silly-loop} function is somewhat more complex:
460 (defun silly-loop (n)
461 "Return time before and after N iterations of a loop."
462 (let ((t1 (current-time-string)))
463 (while (> (setq n (1- n))
465 (list t1 (current-time-string))))
470 (disassemble 'silly-loop)
471 @print{} byte-code for silly-loop:
472 doc: Return time before and after N iterations of a loop.
475 0 constant current-time-string ; @r{Push}
476 ; @r{@code{current-time-string}}
477 ; @r{onto top of stack.}
481 1 call 0 ; @r{Call @code{current-time-string}}
482 ; @r{ with no argument,}
483 ; @r{ pushing result onto stack.}
487 2 varbind t1 ; @r{Pop stack and bind @code{t1}}
488 ; @r{to popped value.}
492 3 varref n ; @r{Get value of @code{n} from}
493 ; @r{the environment and push}
494 ; @r{the value onto the stack.}
498 4 sub1 ; @r{Subtract 1 from top of stack.}
502 5 dup ; @r{Duplicate the top of the stack;}
503 ; @r{i.e. copy the top of}
504 ; @r{the stack and push the}
505 ; @r{copy onto the stack.}
509 6 varset n ; @r{Pop the top of the stack,}
510 ; @r{and bind @code{n} to the value.}
512 ; @r{In effect, the sequence @code{dup varset}}
513 ; @r{copies the top of the stack}
514 ; @r{into the value of @code{n}}
515 ; @r{without popping it.}
519 7 constant 0 ; @r{Push 0 onto stack.}
523 8 gtr ; @r{Pop top two values off stack,}
524 ; @r{test if @var{n} is greater than 0}
525 ; @r{and push result onto stack.}
529 9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} > 0}
530 ; @r{else pop top of stack}
532 ; @r{(this exits the while loop).}
536 12 constant nil ; @r{Push @code{nil} onto stack}
537 ; @r{(this is the body of the loop).}
541 13 discard ; @r{Discard result of the body}
542 ; @r{of the loop (a while loop}
543 ; @r{is always evaluated for}
544 ; @r{its side effects).}
548 14 goto 3 ; @r{Jump back to beginning}
553 17 discard ; @r{Discard result of while loop}
554 ; @r{by popping top of stack.}
558 18 varref t1 ; @r{Push value of @code{t1} onto stack.}
562 19 constant current-time-string ; @r{Push}
563 ; @r{@code{current-time-string}}
564 ; @r{onto top of stack.}
568 20 call 0 ; @r{Call @code{current-time-string} again.}
572 21 list2 ; @r{Pop top two elements off stack,}
573 ; @r{create a list of them,}
574 ; @r{and push list onto stack.}
578 22 unbind 1 ; @r{Unbind @code{t1} in local environment.}
580 23 return ; @r{Return value of the top of stack.}