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 @xref{Docs and Compilation}.
31 @xref{Compilation Errors}, for how to investigate errors occurring in
35 * Speed of Byte-Code:: An example of speedup from byte compilation.
36 * Compilation Functions:: Byte compilation functions.
37 * Docs and Compilation:: Dynamic loading of documentation strings.
38 * Dynamic Loading:: Dynamic loading of individual functions.
39 * Eval During Compile:: Code to be evaluated when you compile.
40 * Compiled-Function Objects:: The data type used for byte-compiled functions.
41 * Disassembly:: Disassembling byte-code; how to read byte-code.
44 @node Speed of Byte-Code
45 @section Performance of Byte-Compiled Code
47 A byte-compiled function is not as efficient as a primitive function
48 written in C, but runs much faster than the version written in Lisp.
54 "Return time before and after N iterations of a loop."
55 (let ((t1 (current-time-string)))
56 (while (> (setq n (1- n))
58 (list t1 (current-time-string))))
64 @result{} ("Fri Nov 28 20:56:16 1997"
65 "Fri Nov 28 20:56:39 1997") ; @r{23 seconds}
69 (byte-compile 'silly-loop)
70 @result{} #<compiled-function
74 [current-time-string t1 n 0]
76 "Return time before and after N iterations of a loop.">
81 @result{} ("Fri Nov 28 20:57:49 1997"
82 "Fri Nov 28 20:57:55 1997") ; @r{6 seconds}
86 In this example, the interpreted code required 23 seconds to run,
87 whereas the byte-compiled code required 6 seconds. These results are
88 representative, but actual results will vary greatly.
90 @node Compilation Functions
91 @comment node-name, next, previous, up
92 @section The Compilation Functions
93 @cindex compilation functions
95 You can byte-compile an individual function or macro definition with
96 the @code{byte-compile} function. You can compile a whole file with
97 @code{byte-compile-file}, or several files with
98 @code{byte-recompile-directory} or @code{batch-byte-compile}.
100 When you run the byte compiler, you may get warnings in a buffer
101 called @samp{*Compile-Log*}. These report things in your program that
102 suggest a problem but are not necessarily erroneous.
104 @cindex macro compilation
105 Be careful when byte-compiling code that uses macros. Macro calls are
106 expanded when they are compiled, so the macros must already be defined
107 for proper compilation. For more details, see @ref{Compiling Macros}.
109 Normally, compiling a file does not evaluate the file's contents or
110 load the file. But it does execute any @code{require} calls at top
111 level in the file. One way to ensure that necessary macro definitions
112 are available during compilation is to require the file that defines
113 them (@pxref{Named Features}). To avoid loading the macro definition files
114 when someone @emph{runs} the compiled program, write
115 @code{eval-when-compile} around the @code{require} calls (@pxref{Eval
118 @defun byte-compile symbol
119 This function byte-compiles the function definition of @var{symbol},
120 replacing the previous definition with the compiled one. The function
121 definition of @var{symbol} must be the actual code for the function;
122 i.e., the compiler does not follow indirection to another symbol.
123 @code{byte-compile} returns the new, compiled definition of
126 If @var{symbol}'s definition is a compiled-function object,
127 @code{byte-compile} does nothing and returns @code{nil}. Lisp records
128 only one function definition for any symbol, and if that is already
129 compiled, non-compiled code is not available anywhere. So there is no
130 way to ``compile the same definition again.''
134 (defun factorial (integer)
135 "Compute factorial of INTEGER."
137 (* integer (factorial (1- integer)))))
142 (byte-compile 'factorial)
143 @result{} #<compiled-function
147 [integer 1 factorial]
149 "Compute factorial of INTEGER.">
154 The result is a compiled-function object. The string it contains is
155 the actual byte-code; each character in it is an instruction or an
156 operand of an instruction. The vector contains all the constants,
157 variable names and function names used by the function, except for
158 certain primitives that are coded as special instructions.
161 @deffn Command compile-defun &optional arg
162 This command reads the defun containing point, compiles it, and
163 evaluates the result. If you use this on a defun that is actually a
164 function definition, the effect is to install a compiled version of that
168 If @var{arg} is non-@code{nil}, the result is inserted in the current
169 buffer after the form; otherwise, it is printed in the minibuffer.
172 @deffn Command byte-compile-file filename &optional load
173 This function compiles a file of Lisp code named @var{filename} into
174 a file of byte-code. The output file's name is made by appending
175 @samp{c} to the end of @var{filename}.
178 If @code{load} is non-@code{nil}, the file is loaded after having been
181 Compilation works by reading the input file one form at a time. If it
182 is a definition of a function or macro, the compiled function or macro
183 definition is written out. Other forms are batched together, then each
184 batch is compiled, and written so that its compiled code will be
185 executed when the file is read. All comments are discarded when the
188 This command returns @code{t}. When called interactively, it prompts
194 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
198 (byte-compile-file "~/emacs/push.el")
204 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
205 -rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc
210 @c flag is not optional in FSF Emacs
211 @deffn Command byte-recompile-directory directory &optional flag
212 @cindex library compilation
213 This function recompiles every @samp{.el} file in @var{directory} that
214 needs recompilation. A file needs recompilation if a @samp{.elc} file
215 exists but is older than the @samp{.el} file.
217 When a @samp{.el} file has no corresponding @samp{.elc} file, then
218 @var{flag} says what to do. If it is @code{nil}, these files are
219 ignored. If it is non-@code{nil}, the user is asked whether to compile
222 The returned value of this command is unpredictable.
225 @defun batch-byte-compile
226 This function runs @code{byte-compile-file} on files specified on the
227 command line. This function must be used only in a batch execution of
228 Emacs, as it kills Emacs on completion. An error in one file does not
229 prevent processing of subsequent files. (The file that gets the error
230 will not, of course, produce any compiled code.)
233 % emacs -batch -f batch-byte-compile *.el
238 @defun batch-byte-recompile-directory
239 This function is similar to @code{batch-byte-compile} but runs the
240 command @code{byte-recompile-directory} on the files remaining on the
245 @defvar byte-recompile-directory-ignore-errors-p
246 If non-@code{nil}, this specifies that @code{byte-recompile-directory}
247 will continue compiling even when an error occurs in a file. This is
248 normally @code{nil}, but is bound to @code{t} by
249 @code{batch-byte-recompile-directory}.
252 @defun byte-code code-string data-vector max-stack
253 @cindex byte-code interpreter
254 This function actually interprets byte-code. A byte-compiled function
255 is actually defined with a body that calls @code{byte-code}. Don't call
256 this function yourself. Only the byte compiler knows how to generate
257 valid calls to this function.
259 In newer Emacs versions (19 and up), byte-code is usually executed as
260 part of a compiled-function object, and only rarely due to an explicit
261 call to @code{byte-code}.
264 @node Docs and Compilation
265 @section Documentation Strings and Compilation
266 @cindex dynamic loading of documentation
268 Functions and variables loaded from a byte-compiled file access their
269 documentation strings dynamically from the file whenever needed. This
270 saves space within Emacs, and makes loading faster because the
271 documentation strings themselves need not be processed while loading the
272 file. Actual access to the documentation strings becomes slower as a
273 result, but normally not enough to bother users.
275 Dynamic access to documentation strings does have drawbacks:
279 If you delete or move the compiled file after loading it, Emacs can no
280 longer access the documentation strings for the functions and variables
284 If you alter the compiled file (such as by compiling a new version),
285 then further access to documentation strings in this file will give
289 If your site installs Emacs following the usual procedures, these
290 problems will never normally occur. Installing a new version uses a new
291 directory with a different name; as long as the old version remains
292 installed, its files will remain unmodified in the places where they are
295 However, if you have built Emacs yourself and use it from the
296 directory where you built it, you will experience this problem
297 occasionally if you edit and recompile Lisp files. When it happens, you
298 can cure the problem by reloading the file after recompiling it.
300 Byte-compiled files made with Emacs 19.29 will not load into older
301 versions because the older versions don't support this feature. You can
302 turn off this feature by setting @code{byte-compile-dynamic-docstrings}
303 to @code{nil}. Once this is done, you can compile files that will load
304 into older Emacs versions. You can do this globally, or for one source
305 file by specifying a file-local binding for the variable. Here's one
309 -*-byte-compile-dynamic-docstrings: nil;-*-
312 @defvar byte-compile-dynamic-docstrings
313 If this is non-@code{nil}, the byte compiler generates compiled files
314 that are set up for dynamic loading of documentation strings.
317 @cindex @samp{#@@@var{count}}
319 The dynamic documentation string feature writes compiled files that
320 use a special Lisp reader construct, @samp{#@@@var{count}}. This
321 construct skips the next @var{count} characters. It also uses the
322 @samp{#$} construct, which stands for ``the name of this file, as a
323 string.'' It is best not to use these constructs in Lisp source files.
325 @node Dynamic Loading
326 @section Dynamic Loading of Individual Functions
328 @cindex dynamic loading of functions
330 When you compile a file, you can optionally enable the @dfn{dynamic
331 function loading} feature (also known as @dfn{lazy loading}). With
332 dynamic function loading, loading the file doesn't fully read the
333 function definitions in the file. Instead, each function definition
334 contains a place-holder which refers to the file. The first time each
335 function is called, it reads the full definition from the file, to
336 replace the place-holder.
338 The advantage of dynamic function loading is that loading the file
339 becomes much faster. This is a good thing for a file which contains
340 many separate commands, provided that using one of them does not imply
341 you will soon (or ever) use the rest. A specialized mode which provides
342 many keyboard commands often has that usage pattern: a user may invoke
343 the mode, but use only a few of the commands it provides.
345 The dynamic loading feature has certain disadvantages:
349 If you delete or move the compiled file after loading it, Emacs can no
350 longer load the remaining function definitions not already loaded.
353 If you alter the compiled file (such as by compiling a new version),
354 then trying to load any function not already loaded will get nonsense
358 If you compile a new version of the file, the best thing to do is
359 immediately load the new compiled file. That will prevent any future
362 The byte compiler uses the dynamic function loading feature if the
363 variable @code{byte-compile-dynamic} is non-@code{nil} at compilation
364 time. Do not set this variable globally, since dynamic loading is
365 desirable only for certain files. Instead, enable the feature for
366 specific source files with file-local variable bindings, like this:
369 -*-byte-compile-dynamic: t;-*-
372 @defvar byte-compile-dynamic
373 If this is non-@code{nil}, the byte compiler generates compiled files
374 that are set up for dynamic function loading.
377 @defun fetch-bytecode function
378 This immediately finishes loading the definition of @var{function} from
379 its byte-compiled file, if it is not fully loaded already. The argument
380 @var{function} may be a compiled-function object or a function name.
383 @node Eval During Compile
384 @section Evaluation During Compilation
386 These features permit you to write code to be evaluated during
387 compilation of a program.
389 @defspec eval-and-compile body
390 This form marks @var{body} to be evaluated both when you compile the
391 containing code and when you run it (whether compiled or not).
393 You can get a similar result by putting @var{body} in a separate file
394 and referring to that file with @code{require}. Using @code{require} is
395 preferable if there is a substantial amount of code to be executed in
399 @defspec eval-when-compile body
400 This form marks @var{body} to be evaluated at compile time and not when
401 the compiled program is loaded. The result of evaluation by the
402 compiler becomes a constant which appears in the compiled program. When
403 the program is interpreted, not compiled at all, @var{body} is evaluated
406 At top level, this is analogous to the Common Lisp idiom
407 @code{(eval-when (compile eval) @dots{})}. Elsewhere, the Common Lisp
408 @samp{#.} reader macro (but not when interpreting) is closer to what
409 @code{eval-when-compile} does.
412 @node Compiled-Function Objects
413 @section Compiled-Function Objects
414 @cindex compiled function
415 @cindex byte-code function
417 Byte-compiled functions have a special data type: they are
418 @dfn{compiled-function objects}.
420 A compiled-function object is a bit like a vector; however, the
421 evaluator handles this data type specially when it appears as a function
422 to be called. The printed representation for a compiled-function
423 object normally begins with @samp{#<compiled-function} and ends with
424 @samp{>}. However, if the variable @code{print-readably} is
425 non-@code{nil}, the object is printed beginning with @samp{#[} and
426 ending with @samp{]}. This representation can be read directly
427 by the Lisp reader, and is used in byte-compiled files (those ending
430 In Emacs version 18, there was no compiled-function object data type;
431 compiled functions used the function @code{byte-code} to run the byte
434 A compiled-function object has a number of different elements.
439 The list of argument symbols.
442 The string containing the byte-code instructions.
445 The vector of Lisp objects referenced by the byte code. These include
446 symbols used as function names and variable names.
449 The maximum stack size this function needs.
452 The documentation string (if any); otherwise, @code{nil}. The value may
453 be a number or a list, in case the documentation string is stored in a
454 file. Use the function @code{documentation} to get the real
455 documentation string (@pxref{Accessing Documentation}).
458 The interactive spec (if any). This can be a string or a Lisp
459 expression. It is @code{nil} for a function that isn't interactive.
462 The domain (if any). This is only meaningful if I18N3 (message-translation)
463 support was compiled into XEmacs. This is a string defining which
464 domain to find the translation for the documentation string and
465 interactive prompt. @xref{Domain Specification}.
468 Here's an example of a compiled-function object, in printed
469 representation. It is the definition of the command
470 @code{backward-sexp}.
476 "...(15)" [arg 1 forward-sexp] 2 854740 "_p">
479 The primitive way to create a compiled-function object is with
480 @code{make-byte-code}:
482 @defun make-byte-code &rest elements
483 This function constructs and returns a compiled-function object
484 with @var{elements} as its elements.
486 @emph{Please note:} Unlike all other Emacs-lisp functions, calling this with
487 five arguments is @emph{not} the same as calling it with six arguments,
488 the last of which is @code{nil}. If the @var{interactive} arg is
489 specified as @code{nil}, then that means that this function was defined
490 with @code{(interactive)}. If the arg is not specified, then that means
491 the function is not interactive. This is terrible behavior which is
492 retained for compatibility with old @samp{.elc} files which expected
496 You should not try to come up with the elements for a compiled-function
497 object yourself, because if they are inconsistent, XEmacs may crash
498 when you call the function. Always leave it to the byte compiler to
499 create these objects; it makes the elements consistent (we hope).
501 The following primitives are provided for accessing the elements of
502 a compiled-function object.
504 @defun compiled-function-arglist function
505 This function returns the argument list of compiled-function object
509 @defun compiled-function-instructions function
510 This function returns a string describing the byte-code instructions
511 of compiled-function object @var{function}.
514 @defun compiled-function-constants function
515 This function returns the vector of Lisp objects referenced by
516 compiled-function object @var{function}.
519 @defun compiled-function-stack-size function
520 This function returns the maximum stack size needed by compiled-function
521 object @var{function}.
524 @defun compiled-function-doc-string function
525 This function returns the doc string of compiled-function object
526 @var{function}, if available.
529 @defun compiled-function-interactive function
530 This function returns the interactive spec of compiled-function object
531 @var{function}, if any. The return value is @code{nil} or a two-element
532 list, the first element of which is the symbol @code{interactive} and
533 the second element is the interactive spec (a string or Lisp form).
536 @defun compiled-function-domain function
537 This function returns the domain of compiled-function object
538 @var{function}, if any. The result will be a string or @code{nil}.
539 @xref{Domain Specification}.
543 @section Disassembled Byte-Code
544 @cindex disassembled byte-code
546 People do not write byte-code; that job is left to the byte compiler.
547 But we provide a disassembler to satisfy a cat-like curiosity. The
548 disassembler converts the byte-compiled code into humanly readable
551 The byte-code interpreter is implemented as a simple stack machine.
552 It pushes values onto a stack of its own, then pops them off to use them
553 in calculations whose results are themselves pushed back on the stack.
554 When a byte-code function returns, it pops a value off the stack and
555 returns it as the value of the function.
557 In addition to the stack, byte-code functions can use, bind, and set
558 ordinary Lisp variables, by transferring values between variables and
561 @deffn Command disassemble object &optional stream
562 This function prints the disassembled code for @var{object}. If
563 @var{stream} is supplied, then output goes there. Otherwise, the
564 disassembled code is printed to the stream @code{standard-output}. The
565 argument @var{object} can be a function name or a lambda expression.
567 As a special exception, if this function is used interactively,
568 it outputs to a buffer named @samp{*Disassemble*}.
571 Here are two examples of using the @code{disassemble} function. We
572 have added explanatory comments to help you relate the byte-code to the
573 Lisp source; these do not appear in the output of @code{disassemble}.
574 These examples show unoptimized byte-code. Nowadays byte-code is
575 usually optimized, but we did not want to rewrite these examples, since
576 they still serve their purpose.
580 (defun factorial (integer)
581 "Compute factorial of an integer."
583 (* integer (factorial (1- integer)))))
593 (disassemble 'factorial)
594 @print{} byte-code for factorial:
595 doc: Compute factorial of an integer.
600 0 constant 1 ; @r{Push 1 onto stack.}
602 1 varref integer ; @r{Get value of @code{integer}}
603 ; @r{from the environment}
604 ; @r{and push the value}
605 ; @r{onto the stack.}
609 2 eqlsign ; @r{Pop top two values off stack,}
611 ; @r{and push result onto stack.}
615 3 goto-if-nil 10 ; @r{Pop and test top of stack;}
616 ; @r{if @code{nil}, go to 10,}
621 6 constant 1 ; @r{Push 1 onto top of stack.}
623 7 goto 17 ; @r{Go to 17 (in this case, 1 will be}
624 ; @r{returned by the function).}
628 10 constant * ; @r{Push symbol @code{*} onto stack.}
630 11 varref integer ; @r{Push value of @code{integer} onto stack.}
634 12 constant factorial ; @r{Push @code{factorial} onto stack.}
636 13 varref integer ; @r{Push value of @code{integer} onto stack.}
638 14 sub1 ; @r{Pop @code{integer}, decrement value,}
639 ; @r{push new value onto stack.}
643 ; @r{Stack now contains:}
644 ; @minus{} @r{decremented value of @code{integer}}
645 ; @minus{} @r{@code{factorial}}
646 ; @minus{} @r{value of @code{integer}}
647 ; @minus{} @r{@code{*}}
651 15 call 1 ; @r{Call function @code{factorial} using}
652 ; @r{the first (i.e., the top) element}
653 ; @r{of the stack as the argument;}
654 ; @r{push returned value onto stack.}
658 ; @r{Stack now contains:}
659 ; @minus{} @r{result of recursive}
660 ; @r{call to @code{factorial}}
661 ; @minus{} @r{value of @code{integer}}
662 ; @minus{} @r{@code{*}}
666 16 call 2 ; @r{Using the first two}
667 ; @r{(i.e., the top two)}
668 ; @r{elements of the stack}
670 ; @r{call the function @code{*},}
671 ; @r{pushing the result onto the stack.}
675 17 return ; @r{Return the top element}
681 The @code{silly-loop} function is somewhat more complex:
685 (defun silly-loop (n)
686 "Return time before and after N iterations of a loop."
687 (let ((t1 (current-time-string)))
688 (while (> (setq n (1- n))
690 (list t1 (current-time-string))))
695 (disassemble 'silly-loop)
696 @print{} byte-code for silly-loop:
697 doc: Return time before and after N iterations of a loop.
700 0 constant current-time-string ; @r{Push}
701 ; @r{@code{current-time-string}}
702 ; @r{onto top of stack.}
706 1 call 0 ; @r{Call @code{current-time-string}}
707 ; @r{ with no argument,}
708 ; @r{ pushing result onto stack.}
712 2 varbind t1 ; @r{Pop stack and bind @code{t1}}
713 ; @r{to popped value.}
717 3 varref n ; @r{Get value of @code{n} from}
718 ; @r{the environment and push}
719 ; @r{the value onto the stack.}
723 4 sub1 ; @r{Subtract 1 from top of stack.}
727 5 dup ; @r{Duplicate the top of the stack;}
728 ; @r{i.e., copy the top of}
729 ; @r{the stack and push the}
730 ; @r{copy onto the stack.}
734 6 varset n ; @r{Pop the top of the stack,}
735 ; @r{and bind @code{n} to the value.}
737 ; @r{In effect, the sequence @code{dup varset}}
738 ; @r{copies the top of the stack}
739 ; @r{into the value of @code{n}}
740 ; @r{without popping it.}
744 7 constant 0 ; @r{Push 0 onto stack.}
748 8 gtr ; @r{Pop top two values off stack,}
749 ; @r{test if @var{n} is greater than 0}
750 ; @r{and push result onto stack.}
754 9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0}
755 ; @r{(this exits the while loop).}
756 ; @r{else pop top of stack}
761 12 constant nil ; @r{Push @code{nil} onto stack}
762 ; @r{(this is the body of the loop).}
766 13 discard ; @r{Discard result of the body}
767 ; @r{of the loop (a while loop}
768 ; @r{is always evaluated for}
769 ; @r{its side effects).}
773 14 goto 3 ; @r{Jump back to beginning}
778 17 discard ; @r{Discard result of while loop}
779 ; @r{by popping top of stack.}
780 ; @r{This result is the value @code{nil} that}
781 ; @r{was not popped by the goto at 9.}
785 18 varref t1 ; @r{Push value of @code{t1} onto stack.}
789 19 constant current-time-string ; @r{Push}
790 ; @r{@code{current-time-string}}
791 ; @r{onto top of stack.}
795 20 call 0 ; @r{Call @code{current-time-string} again.}
799 21 list2 ; @r{Pop top two elements off stack,}
800 ; @r{create a list of them,}
801 ; @r{and push list onto stack.}
805 22 unbind 1 ; @r{Unbind @code{t1} in local environment.}
807 23 return ; @r{Return value of the top of stack.}