2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/compile.info
6 @node Byte Compilation, Debugging, Loading, Top
7 @chapter Byte Compilation
11 XEmacs 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-coded 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 XEmacs 20, the compiled code
26 may not run in earlier versions.
28 The first time a compiled-function object is executed, the byte-code
29 instructions are validated and the byte-code is further optimized. An
30 @code{invalid-byte-code} error is signaled if the byte-code is invalid,
31 for example if it contains invalid opcodes. This usually means a bug in
35 @xref{Docs and Compilation}.
38 @xref{Compilation Errors}, for how to investigate errors occurring in
42 * Speed of Byte-Code:: An example of speedup from byte compilation.
43 * Compilation Functions:: Byte compilation functions.
44 * Docs and Compilation:: Dynamic loading of documentation strings.
45 * Dynamic Loading:: Dynamic loading of individual functions.
46 * Eval During Compile:: Code to be evaluated when you compile.
47 * Compiled-Function Objects:: The data type used for byte-compiled functions.
48 * Disassembly:: Disassembling byte-code; how to read byte-code.
51 @node Speed of Byte-Code
52 @section Performance of Byte-Compiled Code
54 A byte-compiled function is not as efficient as a primitive function
55 written in C, but runs much faster than the version written in Lisp.
61 "Return time before and after N iterations of a loop."
62 (let ((t1 (current-time-string)))
63 (while (> (setq n (1- n))
65 (list t1 (current-time-string))))
71 @result{} ("Mon Sep 14 15:51:49 1998"
72 "Mon Sep 14 15:52:07 1998") ; @r{18 seconds}
76 (byte-compile 'silly-loop)
77 @result{} #<compiled-function
80 [current-time-string t1 n 0]
82 "Return time before and after N iterations of a loop.">
87 @result{} ("Mon Sep 14 15:53:43 1998"
88 "Mon Sep 14 15:53:49 1998") ; @r{6 seconds}
92 In this example, the interpreted code required 18 seconds to run,
93 whereas the byte-compiled code required 6 seconds. These results are
94 representative, but actual results will vary greatly.
96 @node Compilation Functions
97 @comment node-name, next, previous, up
98 @section The Compilation Functions
99 @cindex compilation functions
101 You can byte-compile an individual function or macro definition with
102 the @code{byte-compile} function. You can compile a whole file with
103 @code{byte-compile-file}, or several files with
104 @code{byte-recompile-directory} or @code{batch-byte-compile}.
106 When you run the byte compiler, you may get warnings in a buffer
107 called @samp{*Compile-Log*}. These report things in your program that
108 suggest a problem but are not necessarily erroneous.
110 @cindex macro compilation
111 Be careful when byte-compiling code that uses macros. Macro calls are
112 expanded when they are compiled, so the macros must already be defined
113 for proper compilation. For more details, see @ref{Compiling Macros}.
115 Normally, compiling a file does not evaluate the file's contents or
116 load the file. But it does execute any @code{require} calls at top
117 level in the file. One way to ensure that necessary macro definitions
118 are available during compilation is to @code{require} the file that defines
119 them (@pxref{Named Features}). To avoid loading the macro definition files
120 when someone @emph{runs} the compiled program, write
121 @code{eval-when-compile} around the @code{require} calls (@pxref{Eval
124 @defun byte-compile symbol
125 This function byte-compiles the function definition of @var{symbol},
126 replacing the previous definition with the compiled one. The function
127 definition of @var{symbol} must be the actual code for the function;
128 i.e., the compiler does not follow indirection to another symbol.
129 @code{byte-compile} returns the new, compiled definition of
132 If @var{symbol}'s definition is a compiled-function object,
133 @code{byte-compile} does nothing and returns @code{nil}. Lisp records
134 only one function definition for any symbol, and if that is already
135 compiled, non-compiled code is not available anywhere. So there is no
136 way to ``compile the same definition again.''
140 (defun factorial (integer)
141 "Compute factorial of INTEGER."
143 (* integer (factorial (1- integer)))))
148 (byte-compile 'factorial)
149 @result{} #<compiled-function
152 [integer 1 factorial]
154 "Compute factorial of INTEGER.">
159 The result is a compiled-function object. The string it contains is
160 the actual byte-code; each character in it is an instruction or an
161 operand of an instruction. The vector contains all the constants,
162 variable names and function names used by the function, except for
163 certain primitives that are coded as special instructions.
166 @deffn Command compile-defun &optional arg
167 This command reads the defun containing point, compiles it, and
168 evaluates the result. If you use this on a defun that is actually a
169 function definition, the effect is to install a compiled version of that
173 If @var{arg} is non-@code{nil}, the result is inserted in the current
174 buffer after the form; otherwise, it is printed in the minibuffer.
177 @deffn Command byte-compile-file filename &optional load
178 This function compiles a file of Lisp code named @var{filename} into
179 a file of byte-code. The output file's name is made by appending
180 @samp{c} to the end of @var{filename}.
183 If @code{load} is non-@code{nil}, the file is loaded after having been
186 Compilation works by reading the input file one form at a time. If it
187 is a definition of a function or macro, the compiled function or macro
188 definition is written out. Other forms are batched together, then each
189 batch is compiled, and written so that its compiled code will be
190 executed when the file is read. All comments are discarded when the
193 This command returns @code{t}. When called interactively, it prompts
199 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
203 (byte-compile-file "~/emacs/push.el")
209 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
210 -rw-r--r-- 1 lewis 638 Oct 8 20:25 push.elc
215 @c flag is not optional in FSF Emacs
216 @deffn Command byte-recompile-directory directory &optional flag norecursion force
217 @cindex library compilation
218 This function recompiles every @samp{.el} file in @var{directory} that
219 needs recompilation. A file needs recompilation if a @samp{.elc} file
220 exists but is older than the @samp{.el} file.
222 Files in subdirectories of @var{directory} are also processed unless
223 optional argument @var{norecursion} is non-@code{nil}.
225 When a @samp{.el} file has no corresponding @samp{.elc} file, then
226 @var{flag} says what to do. If it is @code{nil}, these files are
227 ignored. If it is non-@code{nil}, the user is asked whether to compile
230 If the fourth optional argument @var{force} is non-@code{nil},
231 recompile every @samp{.el} file that already has a @samp{.elc} file.
233 The return value of this command is unpredictable.
236 @defun batch-byte-compile
237 This function runs @code{byte-compile-file} on files specified on the
238 command line. This function must be used only in a batch execution of
239 Emacs, as it kills Emacs on completion. An error in one file does not
240 prevent processing of subsequent files. (The file that gets the error
241 will not, of course, produce any compiled code.)
244 % xemacs -batch -f batch-byte-compile *.el
249 @defun batch-byte-recompile-directory
250 This function is similar to @code{batch-byte-compile} but runs the
251 command @code{byte-recompile-directory} on the files remaining on the
256 @defvar byte-recompile-directory-ignore-errors-p
257 If non-@code{nil}, this specifies that @code{byte-recompile-directory}
258 will continue compiling even when an error occurs in a file. This is
259 normally @code{nil}, but is bound to @code{t} by
260 @code{batch-byte-recompile-directory}.
263 @defun byte-code instructions constants stack-depth
264 @cindex byte-code interpreter
265 This function actually interprets byte-code.
266 Don't call this function yourself. Only the byte compiler knows how to
267 generate valid calls to this function.
269 In newer Emacs versions (19 and up), byte code is usually executed as
270 part of a compiled-function object, and only rarely due to an explicit
271 call to @code{byte-code}. A byte-compiled function was once actually
272 defined with a body that calls @code{byte-code}, but in recent versions
273 of Emacs @code{byte-code} is only used to run isolated fragments of lisp
274 code without an associated argument list.
277 @node Docs and Compilation
278 @section Documentation Strings and Compilation
279 @cindex dynamic loading of documentation
281 Functions and variables loaded from a byte-compiled file access their
282 documentation strings dynamically from the file whenever needed. This
283 saves space within Emacs, and makes loading faster because the
284 documentation strings themselves need not be processed while loading the
285 file. Actual access to the documentation strings becomes slower as a
286 result, but normally not enough to bother users.
288 Dynamic access to documentation strings does have drawbacks:
292 If you delete or move the compiled file after loading it, Emacs can no
293 longer access the documentation strings for the functions and variables
297 If you alter the compiled file (such as by compiling a new version),
298 then further access to documentation strings in this file will give
302 If your site installs Emacs following the usual procedures, these
303 problems will never normally occur. Installing a new version uses a new
304 directory with a different name; as long as the old version remains
305 installed, its files will remain unmodified in the places where they are
308 However, if you have built Emacs yourself and use it from the
309 directory where you built it, you will experience this problem
310 occasionally if you edit and recompile Lisp files. When it happens, you
311 can cure the problem by reloading the file after recompiling it.
313 Versions of Emacs up to and including XEmacs 19.14 and FSF Emacs 19.28
314 do not support the dynamic docstrings feature, and so will not be able
315 to load bytecode created by more recent Emacs versions. You can turn
316 off the dynamic docstring feature by setting
317 @code{byte-compile-dynamic-docstrings} to @code{nil}. Once this is
318 done, you can compile files that will load into older Emacs versions.
319 You can do this globally, or for one source file by specifying a
320 file-local binding for the variable. Here's one way to do that:
323 -*-byte-compile-dynamic-docstrings: nil;-*-
326 @defvar byte-compile-dynamic-docstrings
327 If this is non-@code{nil}, the byte compiler generates compiled files
328 that are set up for dynamic loading of documentation strings.
331 @cindex @samp{#@@@var{count}}
333 The dynamic documentation string feature writes compiled files that
334 use a special Lisp reader construct, @samp{#@@@var{count}}. This
335 construct skips the next @var{count} characters. It also uses the
336 @samp{#$} construct, which stands for ``the name of this file, as a
337 string.'' It is best not to use these constructs in Lisp source files.
339 @node Dynamic Loading
340 @section Dynamic Loading of Individual Functions
342 @cindex dynamic loading of functions
344 When you compile a file, you can optionally enable the @dfn{dynamic
345 function loading} feature (also known as @dfn{lazy loading}). With
346 dynamic function loading, loading the file doesn't fully read the
347 function definitions in the file. Instead, each function definition
348 contains a place-holder which refers to the file. The first time each
349 function is called, it reads the full definition from the file, to
350 replace the place-holder.
352 The advantage of dynamic function loading is that loading the file
353 becomes much faster. This is a good thing for a file which contains
354 many separate commands, provided that using one of them does not imply
355 you will soon (or ever) use the rest. A specialized mode which provides
356 many keyboard commands often has that usage pattern: a user may invoke
357 the mode, but use only a few of the commands it provides.
359 The dynamic loading feature has certain disadvantages:
363 If you delete or move the compiled file after loading it, Emacs can no
364 longer load the remaining function definitions not already loaded.
367 If you alter the compiled file (such as by compiling a new version),
368 then trying to load any function not already loaded will get nonsense
372 If you compile a new version of the file, the best thing to do is
373 immediately load the new compiled file. That will prevent any future
376 The byte compiler uses the dynamic function loading feature if the
377 variable @code{byte-compile-dynamic} is non-@code{nil} at compilation
378 time. Do not set this variable globally, since dynamic loading is
379 desirable only for certain files. Instead, enable the feature for
380 specific source files with file-local variable bindings, like this:
383 -*-byte-compile-dynamic: t;-*-
386 @defvar byte-compile-dynamic
387 If this is non-@code{nil}, the byte compiler generates compiled files
388 that are set up for dynamic function loading.
391 @defun fetch-bytecode function
392 This immediately finishes loading the definition of @var{function} from
393 its byte-compiled file, if it is not fully loaded already. The argument
394 @var{function} may be a compiled-function object or a function name.
397 @node Eval During Compile
398 @section Evaluation During Compilation
400 These features permit you to write code to be evaluated during
401 compilation of a program.
403 @defspec eval-and-compile body
404 This form marks @var{body} to be evaluated both when you compile the
405 containing code and when you run it (whether compiled or not).
407 You can get a similar result by putting @var{body} in a separate file
408 and referring to that file with @code{require}. Using @code{require} is
409 preferable if there is a substantial amount of code to be executed in
413 @defspec eval-when-compile body
414 This form marks @var{body} to be evaluated at compile time and not when
415 the compiled program is loaded. The result of evaluation by the
416 compiler becomes a constant which appears in the compiled program. When
417 the program is interpreted, not compiled at all, @var{body} is evaluated
420 At top level, this is analogous to the Common Lisp idiom
421 @code{(eval-when (compile eval) @dots{})}. Elsewhere, the Common Lisp
422 @samp{#.} reader macro (but not when interpreting) is closer to what
423 @code{eval-when-compile} does.
426 @node Compiled-Function Objects
427 @section Compiled-Function Objects
428 @cindex compiled function
429 @cindex byte-code function
431 Byte-compiled functions have a special data type: they are
432 @dfn{compiled-function objects}. The evaluator handles this data type
433 specially when it appears as a function to be called.
435 The printed representation for a compiled-function object normally
436 begins with @samp{#<compiled-function} and ends with @samp{>}. However,
437 if the variable @code{print-readably} is non-@code{nil}, the object is
438 printed beginning with @samp{#[} and ending with @samp{]}. This
439 representation can be read directly by the Lisp reader, and is used in
440 byte-compiled files (those ending in @samp{.elc}).
442 In Emacs version 18, there was no compiled-function object data type;
443 compiled functions used the function @code{byte-code} to run the byte
446 A compiled-function object has a number of different attributes.
451 The list of argument symbols.
454 The string containing the byte-code instructions.
457 The vector of Lisp objects referenced by the byte code. These include
458 symbols used as function names and variable names.
461 The maximum stack size this function needs.
464 The documentation string (if any); otherwise, @code{nil}. The value may
465 be a number or a list, in case the documentation string is stored in a
466 file. Use the function @code{documentation} to get the real
467 documentation string (@pxref{Accessing Documentation}).
470 The interactive spec (if any). This can be a string or a Lisp
471 expression. It is @code{nil} for a function that isn't interactive.
474 The domain (if any). This is only meaningful if I18N3 (message-translation)
475 support was compiled into XEmacs. This is a string defining which
476 domain to find the translation for the documentation string and
477 interactive prompt. @xref{Domain Specification}.
480 Here's an example of a compiled-function object, in printed
481 representation. It is the definition of the command
482 @code{backward-sexp}.
485 (symbol-function 'backward-sexp)
486 @result{} #<compiled-function
488 "...(15)" [arg 1 forward-sexp] 2 854740 "_p">
491 The primitive way to create a compiled-function object is with
492 @code{make-byte-code}:
494 @defun make-byte-code arglist instructions constants stack-depth &optional doc-string interactive
495 This function constructs and returns a compiled-function object
496 with the specified attributes.
498 @emph{Please note:} Unlike all other Emacs-lisp functions, calling this with
499 five arguments is @emph{not} the same as calling it with six arguments,
500 the last of which is @code{nil}. If the @var{interactive} arg is
501 specified as @code{nil}, then that means that this function was defined
502 with @code{(interactive)}. If the arg is not specified, then that means
503 the function is not interactive. This is terrible behavior which is
504 retained for compatibility with old @samp{.elc} files which expected
508 You should not try to come up with the elements for a compiled-function
509 object yourself, because if they are inconsistent, XEmacs may crash
510 when you call the function. Always leave it to the byte compiler to
511 create these objects; it makes the elements consistent (we hope).
513 The following primitives are provided for accessing the elements of
514 a compiled-function object.
516 @defun compiled-function-arglist function
517 This function returns the argument list of compiled-function object
521 @defun compiled-function-instructions function
522 This function returns a string describing the byte-code instructions
523 of compiled-function object @var{function}.
526 @defun compiled-function-constants function
527 This function returns the vector of Lisp objects referenced by
528 compiled-function object @var{function}.
531 @defun compiled-function-stack-depth function
532 This function returns the maximum stack size needed by compiled-function
533 object @var{function}.
536 @defun compiled-function-doc-string function
537 This function returns the doc string of compiled-function object
538 @var{function}, if available.
541 @defun compiled-function-interactive function
542 This function returns the interactive spec of compiled-function object
543 @var{function}, if any. The return value is @code{nil} or a two-element
544 list, the first element of which is the symbol @code{interactive} and
545 the second element is the interactive spec (a string or Lisp form).
548 @defun compiled-function-domain function
549 This function returns the domain of compiled-function object
550 @var{function}, if any. The result will be a string or @code{nil}.
551 @xref{Domain Specification}.
555 @section Disassembled Byte-Code
556 @cindex disassembled byte-code
558 People do not write byte-code; that job is left to the byte compiler.
559 But we provide a disassembler to satisfy a cat-like curiosity. The
560 disassembler converts the byte-compiled code into humanly readable
563 The byte-code interpreter is implemented as a simple stack machine.
564 It pushes values onto a stack of its own, then pops them off to use them
565 in calculations whose results are themselves pushed back on the stack.
566 When a byte-code function returns, it pops a value off the stack and
567 returns it as the value of the function.
569 In addition to the stack, byte-code functions can use, bind, and set
570 ordinary Lisp variables, by transferring values between variables and
573 @deffn Command disassemble object &optional stream
574 This function prints the disassembled code for @var{object}. If
575 @var{stream} is supplied, then output goes there. Otherwise, the
576 disassembled code is printed to the stream @code{standard-output}. The
577 argument @var{object} can be a function name or a lambda expression.
579 As a special exception, if this function is used interactively,
580 it outputs to a buffer named @samp{*Disassemble*}.
583 Here are two examples of using the @code{disassemble} function. We
584 have added explanatory comments to help you relate the byte-code to the
585 Lisp source; these do not appear in the output of @code{disassemble}.
589 (defun factorial (integer)
590 "Compute factorial of an integer."
592 (* integer (factorial (1- integer)))))
602 (disassemble 'factorial)
603 @print{} byte-code for factorial:
604 doc: Compute factorial of an integer.
609 0 varref integer ; @r{Get value of @code{integer}}
610 ; @r{from the environment}
611 ; @r{and push the value}
612 ; @r{onto the stack.}
614 1 constant 1 ; @r{Push 1 onto stack.}
618 2 eqlsign ; @r{Pop top two values off stack,}
620 ; @r{and push result onto stack.}
624 3 goto-if-nil 1 ; @r{Pop and test top of stack;}
626 ; @r{go to label 1 (which is also byte 7),}
631 5 constant 1 ; @r{Push 1 onto top of stack.}
633 6 return ; @r{Return the top element}
637 7:1 varref integer ; @r{Push value of @code{integer} onto stack.}
640 8 constant factorial ; @r{Push @code{factorial} onto stack.}
642 9 varref integer ; @r{Push value of @code{integer} onto stack.}
644 10 sub1 ; @r{Pop @code{integer}, decrement value,}
645 ; @r{push new value onto stack.}
649 ; @r{Stack now contains:}
650 ; @minus{} @r{decremented value of @code{integer}}
651 ; @minus{} @r{@code{factorial}}
652 ; @minus{} @r{value of @code{integer}}
656 15 call 1 ; @r{Call function @code{factorial} using}
657 ; @r{the first (i.e., the top) element}
658 ; @r{of the stack as the argument;}
659 ; @r{push returned value onto stack.}
663 ; @r{Stack now contains:}
664 ; @minus{} @r{result of recursive}
665 ; @r{call to @code{factorial}}
666 ; @minus{} @r{value of @code{integer}}
670 12 mult ; @r{Pop top two values off the stack,}
672 ; @r{pushing the result onto the stack.}
676 13 return ; @r{Return the top element}
682 The @code{silly-loop} function is somewhat more complex:
686 (defun silly-loop (n)
687 "Return time before and after N iterations of a loop."
688 (let ((t1 (current-time-string)))
689 (while (> (setq n (1- n))
691 (list t1 (current-time-string))))
696 (disassemble 'silly-loop)
697 @print{} byte-code for silly-loop:
698 doc: Return time before and after N iterations of a loop.
701 0 constant current-time-string ; @r{Push}
702 ; @r{@code{current-time-string}}
703 ; @r{onto top of stack.}
707 1 call 0 ; @r{Call @code{current-time-string}}
708 ; @r{ with no argument,}
709 ; @r{ pushing result onto stack.}
713 2 varbind t1 ; @r{Pop stack and bind @code{t1}}
714 ; @r{to popped value.}
718 3:1 varref n ; @r{Get value of @code{n} from}
719 ; @r{the environment and push}
720 ; @r{the value onto the stack.}
724 4 sub1 ; @r{Subtract 1 from top of stack.}
728 5 dup ; @r{Duplicate the top of the stack;}
729 ; @r{i.e., copy the top of}
730 ; @r{the stack and push the}
731 ; @r{copy onto the stack.}
733 6 varset n ; @r{Pop the top of the stack,}
734 ; @r{and set @code{n} to the value.}
736 ; @r{In effect, the sequence @code{dup varset}}
737 ; @r{copies the top of the stack}
738 ; @r{into the value of @code{n}}
739 ; @r{without popping it.}
743 7 constant 0 ; @r{Push 0 onto stack.}
745 8 gtr ; @r{Pop top two values off stack,}
746 ; @r{test if @var{n} is greater than 0}
747 ; @r{and push result onto stack.}
751 9 goto-if-not-nil 1 ; @r{Goto label 1 (byte 3) if @code{n} <= 0}
752 ; @r{(this exits the while loop).}
753 ; @r{else pop top of stack}
758 11 varref t1 ; @r{Push value of @code{t1} onto stack.}
762 12 constant current-time-string ; @r{Push}
763 ; @r{@code{current-time-string}}
764 ; @r{onto top of stack.}
768 13 call 0 ; @r{Call @code{current-time-string} again.}
770 14 unbind 1 ; @r{Unbind @code{t1} in local environment.}
774 15 list2 ; @r{Pop top two elements off stack,}
775 ; @r{create a list of them,}
776 ; @r{and push list onto stack.}
780 16 return ; @r{Return the top element of the stack.}