2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/compile
6 @node Byte Compilation, Advising Functions, Loading, Top
7 @chapter Byte Compilation
11 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 Compiling a Lisp file with the Emacs byte compiler always reads the
24 file as multibyte text, even if Emacs was started with @samp{--unibyte},
25 unless the file specifies otherwise. This is so that compilation gives
26 results compatible with running the same file without compilation.
27 @xref{Loading Non-ASCII}.
29 In general, any version of Emacs can run byte-compiled code produced
30 by recent earlier versions of Emacs, but the reverse is not true. A
31 major incompatible change was introduced in Emacs version 19.29, and
32 files compiled with versions since that one will definitely not run
33 in earlier versions unless you specify a special option.
35 @xref{Docs and Compilation}.
37 In addition, the modifier bits in keyboard characters were renumbered in
38 Emacs 19.29; as a result, files compiled in versions before 19.29 will
39 not work in subsequent versions if they contain character constants with
42 @vindex no-byte-compile
43 If you do not want a Lisp file to be compiled, ever, put a file-local
44 variable binding for @code{no-byte-compile} into it, like this:
47 ;; -*-no-byte-compile: t; -*-
50 @xref{Compilation Errors}, for how to investigate errors occurring in
54 * Speed of Byte-Code:: An example of speedup from byte compilation.
55 * Compilation Functions:: Byte compilation functions.
56 * Docs and Compilation:: Dynamic loading of documentation strings.
57 * Dynamic Loading:: Dynamic loading of individual functions.
58 * Eval During Compile:: Code to be evaluated when you compile.
59 * Compiler Errors:: Handling compiler error messages.
60 * Byte-Code Objects:: The data type used for byte-compiled functions.
61 * Disassembly:: Disassembling byte-code; how to read byte-code.
64 @node Speed of Byte-Code
65 @section Performance of Byte-Compiled Code
67 A byte-compiled function is not as efficient as a primitive function
68 written in C, but runs much faster than the version written in Lisp.
74 "Return time before and after N iterations of a loop."
75 (let ((t1 (current-time-string)))
76 (while (> (setq n (1- n))
78 (list t1 (current-time-string))))
84 @result{} ("Fri Mar 18 17:25:57 1994"
85 "Fri Mar 18 17:26:28 1994") ; @r{31 seconds}
89 (byte-compile 'silly-loop)
90 @result{} @r{[Compiled code not shown]}
95 @result{} ("Fri Mar 18 17:26:52 1994"
96 "Fri Mar 18 17:26:58 1994") ; @r{6 seconds}
100 In this example, the interpreted code required 31 seconds to run,
101 whereas the byte-compiled code required 6 seconds. These results are
102 representative, but actual results will vary greatly.
104 @node Compilation Functions
105 @comment node-name, next, previous, up
106 @section The Compilation Functions
107 @cindex compilation functions
109 You can byte-compile an individual function or macro definition with
110 the @code{byte-compile} function. You can compile a whole file with
111 @code{byte-compile-file}, or several files with
112 @code{byte-recompile-directory} or @code{batch-byte-compile}.
114 The byte compiler produces error messages and warnings about each file
115 in a buffer called @samp{*Compile-Log*}. These report things in your
116 program that suggest a problem but are not necessarily erroneous.
118 @cindex macro compilation
119 Be careful when writing macro calls in files that you may someday
120 byte-compile. Macro calls are expanded when they are compiled, so the
121 macros must already be defined for proper compilation. For more
122 details, see @ref{Compiling Macros}. If a program does not work the
123 same way when compiled as it does when interpreted, erroneous macro
124 definitions are one likely cause (@pxref{Problems with Macros}).
126 Normally, compiling a file does not evaluate the file's contents or
127 load the file. But it does execute any @code{require} calls at top
128 level in the file. One way to ensure that necessary macro definitions
129 are available during compilation is to require the file that defines
130 them (@pxref{Named Features}). To avoid loading the macro definition files
131 when someone @emph{runs} the compiled program, write
132 @code{eval-when-compile} around the @code{require} calls (@pxref{Eval
135 @defun byte-compile symbol
136 This function byte-compiles the function definition of @var{symbol},
137 replacing the previous definition with the compiled one. The function
138 definition of @var{symbol} must be the actual code for the function;
139 i.e., the compiler does not follow indirection to another symbol.
140 @code{byte-compile} returns the new, compiled definition of
143 If @var{symbol}'s definition is a byte-code function object,
144 @code{byte-compile} does nothing and returns @code{nil}. Lisp records
145 only one function definition for any symbol, and if that is already
146 compiled, non-compiled code is not available anywhere. So there is no
147 way to ``compile the same definition again.''
151 (defun factorial (integer)
152 "Compute factorial of INTEGER."
154 (* integer (factorial (1- integer)))))
159 (byte-compile 'factorial)
162 "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207"
163 [integer 1 * factorial]
164 4 "Compute factorial of INTEGER."]
169 The result is a byte-code function object. The string it contains is
170 the actual byte-code; each character in it is an instruction or an
171 operand of an instruction. The vector contains all the constants,
172 variable names and function names used by the function, except for
173 certain primitives that are coded as special instructions.
176 @deffn Command compile-defun &optional arg
177 This command reads the defun containing point, compiles it, and
178 evaluates the result. If you use this on a defun that is actually a
179 function definition, the effect is to install a compiled version of that
182 @code{compile-defun} normally displays the result of evaluation in the
183 echo area, but if @var{arg} is non-@code{nil}, it inserts the result
184 in the current buffer after the form it compiled.
187 @deffn Command byte-compile-file filename &optional load
188 This function compiles a file of Lisp code named @var{filename} into a
189 file of byte-code. The output file's name is made by changing the
190 @samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in
191 @samp{.el}, it adds @samp{.elc} to the end of @var{filename}.
193 Compilation works by reading the input file one form at a time. If it
194 is a definition of a function or macro, the compiled function or macro
195 definition is written out. Other forms are batched together, then each
196 batch is compiled, and written so that its compiled code will be
197 executed when the file is read. All comments are discarded when the
200 This command returns @code{t} if there were no errors and @code{nil}
201 otherwise. When called interactively, it prompts for the file name.
203 If @var{load} is non-@code{nil}, this command loads the compiled file
204 after compiling it. Interactively, @var{load} is the prefix argument.
209 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
213 (byte-compile-file "~/emacs/push.el")
219 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
220 -rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc
225 @deffn Command byte-recompile-directory directory &optional flag force
226 @cindex library compilation
227 This command recompiles every @samp{.el} file in @var{directory} (or
228 its subdirectories) that needs recompilation. A file needs
229 recompilation if a @samp{.elc} file exists but is older than the
232 When a @samp{.el} file has no corresponding @samp{.elc} file,
233 @var{flag} says what to do. If it is @code{nil}, this command ignores
234 these files. If @var{flag} is 0, it compiles them. If it is neither
235 @code{nil} nor 0, it asks the user whether to compile each such file.
237 Interactively, @code{byte-recompile-directory} prompts for
238 @var{directory} and @var{flag} is the prefix argument.
240 If @var{force} is non-@code{nil}, this command recompiles every
241 @samp{.el} file that has a @samp{.elc} file.
243 The returned value is unpredictable.
246 @defun batch-byte-compile &optional noforce
247 This function runs @code{byte-compile-file} on files specified on the
248 command line. This function must be used only in a batch execution of
249 Emacs, as it kills Emacs on completion. An error in one file does not
250 prevent processing of subsequent files, but no output file will be
251 generated for it, and the Emacs process will terminate with a nonzero
254 If @var{noforce} is non-@code{nil}, this function does not recompile
255 files that have an up-to-date @samp{.elc} file.
258 % emacs -batch -f batch-byte-compile *.el
262 @defun byte-code code-string data-vector max-stack
263 @cindex byte-code interpreter
264 This function actually interprets byte-code. A byte-compiled function
265 is actually defined with a body that calls @code{byte-code}. Don't call
266 this function yourself---only the byte compiler knows how to generate
267 valid calls to this function.
269 In Emacs version 18, byte-code was always executed by way of a call to
270 the function @code{byte-code}. Nowadays, byte-code is usually executed
271 as part of a byte-code function object, and only rarely through an
272 explicit call to @code{byte-code}.
275 @node Docs and Compilation
276 @section Documentation Strings and Compilation
277 @cindex dynamic loading of documentation
279 Functions and variables loaded from a byte-compiled file access their
280 documentation strings dynamically from the file whenever needed. This
281 saves space within Emacs, and makes loading faster because the
282 documentation strings themselves need not be processed while loading the
283 file. Actual access to the documentation strings becomes slower as a
284 result, but this normally is not enough to bother users.
286 Dynamic access to documentation strings does have drawbacks:
290 If you delete or move the compiled file after loading it, Emacs can no
291 longer access the documentation strings for the functions and variables
295 If you alter the compiled file (such as by compiling a new version),
296 then further access to documentation strings in this file will give
300 If your site installs Emacs following the usual procedures, these
301 problems will never normally occur. Installing a new version uses a new
302 directory with a different name; as long as the old version remains
303 installed, its files will remain unmodified in the places where they are
306 However, if you have built Emacs yourself and use it from the
307 directory where you built it, you will experience this problem
308 occasionally if you edit and recompile Lisp files. When it happens, you
309 can cure the problem by reloading the file after recompiling it.
311 Byte-compiled files made with recent versions of Emacs (since 19.29)
312 will not load into older versions because the older versions don't
313 support this feature. You can turn off this feature at compile time by
314 setting @code{byte-compile-dynamic-docstrings} to @code{nil}; then you
315 can compile files that will load into older Emacs versions. You can do
316 this globally, or for one source file by specifying a file-local binding
317 for the variable. One way to do that is by adding this string to the
321 -*-byte-compile-dynamic-docstrings: nil;-*-
324 @defvar byte-compile-dynamic-docstrings
325 If this is non-@code{nil}, the byte compiler generates compiled files
326 that are set up for dynamic loading of documentation strings.
329 @cindex @samp{#@@@var{count}}
331 The dynamic documentation string feature writes compiled files that
332 use a special Lisp reader construct, @samp{#@@@var{count}}. This
333 construct skips the next @var{count} characters. It also uses the
334 @samp{#$} construct, which stands for ``the name of this file, as a
335 string.'' It is usually best not to use these constructs in Lisp source
336 files, since they are not designed to be clear to humans reading the
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 user-callable functions, if using one of them does not
355 imply you will probably also use the rest. A specialized mode which
356 provides many keyboard commands often has that usage pattern: a user may
357 invoke 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 yield nonsense
372 These problems will never happen in normal circumstances with
373 installed Emacs files. But they are quite likely to happen with Lisp
374 files that you are changing. The easiest way to prevent these problems
375 is to reload the new compiled file immediately after each recompilation.
377 The byte compiler uses the dynamic function loading feature if the
378 variable @code{byte-compile-dynamic} is non-@code{nil} at compilation
379 time. Do not set this variable globally, since dynamic loading is
380 desirable only for certain files. Instead, enable the feature for
381 specific source files with file-local variable bindings. For example,
382 you could do it by writing this text in the source file's first line:
385 -*-byte-compile-dynamic: t;-*-
388 @defvar byte-compile-dynamic
389 If this is non-@code{nil}, the byte compiler generates compiled files
390 that are set up for dynamic function loading.
393 @defun fetch-bytecode function
394 This immediately finishes loading the definition of @var{function} from
395 its byte-compiled file, if it is not fully loaded already. The argument
396 @var{function} may be a byte-code function object or a function name.
399 @node Eval During Compile
400 @section Evaluation During Compilation
402 These features permit you to write code to be evaluated during
403 compilation of a program.
405 @defspec eval-and-compile body
406 This form marks @var{body} to be evaluated both when you compile the
407 containing code and when you run it (whether compiled or not).
409 You can get a similar result by putting @var{body} in a separate file
410 and referring to that file with @code{require}. That method is
411 preferable when @var{body} is large.
414 @defspec eval-when-compile body
415 This form marks @var{body} to be evaluated at compile time but not when
416 the compiled program is loaded. The result of evaluation by the
417 compiler becomes a constant which appears in the compiled program. If
418 you load the source file, rather than compiling it, @var{body} is
421 @strong{Common Lisp Note:} At top level, this is analogous to the Common
422 Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the
423 Common Lisp @samp{#.} reader macro (but not when interpreting) is closer
424 to what @code{eval-when-compile} does.
427 @node Compiler Errors
428 @section Compiler Errors
429 @cindex compiler errors
431 Byte compilation writes errors and warnings into the buffer
432 @samp{*Compile-Log*}. The messages include file names and line
433 numbers that identify the location of the problem. The usual Emacs
434 commands for operating on compiler diagnostics work properly on
437 However, the warnings about functions that were used but not
438 defined are always ``located'' at the end of the file, so these
439 commands won't find the places they are really used. To do that,
440 you must search for the function names.
442 You can suppress the compiler warning for calling an undefined
443 function @var{func} by conditionalizing the function call on a
444 @code{fboundp} test, like this:
447 (if (fboundp '@var{func}) ...(@var{func} ...)...)
451 The call to @var{func} must be in the @var{then-form} of the @code{if},
452 and @var{func} must appear quoted in the call to @code{fboundp}.
453 Likewise, you can suppress a compiler warning for an unbound variable
454 @var{variable} by conditionalizing its use on a @code{boundp} test,
458 (if (boundp '@var{variable}) ...@var{variable}...)
462 The reference to @var{variable} must be in the @var{then-form} of the
463 @code{if}, and @var{variable} must appear quoted in the call to
466 You can suppress any compiler warnings using the construct
467 @code{with-no-warnings}:
469 @defmac with-no-warnings body...
470 In execution, this is equivalent to @code{(progn @var{body}...)},
471 but the compiler does not issue warnings for anything that occurs
474 We recommend that you use this construct around the smallest
475 possible piece of code.
478 @node Byte-Code Objects
479 @section Byte-Code Function Objects
480 @cindex compiled function
481 @cindex byte-code function
483 Byte-compiled functions have a special data type: they are
484 @dfn{byte-code function objects}.
486 Internally, a byte-code function object is much like a vector;
487 however, the evaluator handles this data type specially when it appears
488 as a function to be called. The printed representation for a byte-code
489 function object is like that for a vector, with an additional @samp{#}
490 before the opening @samp{[}.
492 A byte-code function object must have at least four elements; there is
493 no maximum number, but only the first six elements have any normal use.
498 The list of argument symbols.
501 The string containing the byte-code instructions.
504 The vector of Lisp objects referenced by the byte code. These include
505 symbols used as function names and variable names.
508 The maximum stack size this function needs.
511 The documentation string (if any); otherwise, @code{nil}. The value may
512 be a number or a list, in case the documentation string is stored in a
513 file. Use the function @code{documentation} to get the real
514 documentation string (@pxref{Accessing Documentation}).
517 The interactive spec (if any). This can be a string or a Lisp
518 expression. It is @code{nil} for a function that isn't interactive.
521 Here's an example of a byte-code function object, in printed
522 representation. It is the definition of the command
523 @code{backward-sexp}.
527 "^H\204^F^@@\301^P\302^H[!\207"
534 The primitive way to create a byte-code object is with
535 @code{make-byte-code}:
537 @defun make-byte-code &rest elements
538 This function constructs and returns a byte-code function object
539 with @var{elements} as its elements.
542 You should not try to come up with the elements for a byte-code
543 function yourself, because if they are inconsistent, Emacs may crash
544 when you call the function. Always leave it to the byte compiler to
545 create these objects; it makes the elements consistent (we hope).
547 You can access the elements of a byte-code object using @code{aref};
548 you can also use @code{vconcat} to create a vector with the same
552 @section Disassembled Byte-Code
553 @cindex disassembled byte-code
555 People do not write byte-code; that job is left to the byte compiler.
556 But we provide a disassembler to satisfy a cat-like curiosity. The
557 disassembler converts the byte-compiled code into humanly readable
560 The byte-code interpreter is implemented as a simple stack machine.
561 It pushes values onto a stack of its own, then pops them off to use them
562 in calculations whose results are themselves pushed back on the stack.
563 When a byte-code function returns, it pops a value off the stack and
564 returns it as the value of the function.
566 In addition to the stack, byte-code functions can use, bind, and set
567 ordinary Lisp variables, by transferring values between variables and
570 @deffn Command disassemble object &optional buffer-or-name
571 This command displays the disassembled code for @var{object}. In
572 interactive use, or if @var{buffer-or-name} is @code{nil} or omitted,
573 the output goes in a buffer named @samp{*Disassemble*}. If
574 @var{buffer-or-name} is non-@code{nil}, it must be a buffer or the
575 name of an existing buffer. Then the output goes there, at point, and
576 point is left before the output.
578 The argument @var{object} can be a function name, a lambda expression
579 or a byte-code object.
582 Here are two examples of using the @code{disassemble} function. We
583 have added explanatory comments to help you relate the byte-code to the
584 Lisp source; these do not appear in the output of @code{disassemble}.
585 These examples show unoptimized byte-code. Nowadays byte-code is
586 usually optimized, but we did not want to rewrite these examples, since
587 they still serve their purpose.
591 (defun factorial (integer)
592 "Compute factorial of an integer."
594 (* integer (factorial (1- integer)))))
604 (disassemble 'factorial)
605 @print{} byte-code for factorial:
606 doc: Compute factorial of an integer.
611 0 constant 1 ; @r{Push 1 onto stack.}
613 1 varref integer ; @r{Get value of @code{integer}}
614 ; @r{from the environment}
615 ; @r{and push the value}
616 ; @r{onto the stack.}
620 2 eqlsign ; @r{Pop top two values off stack,}
622 ; @r{and push result onto stack.}
626 3 goto-if-nil 10 ; @r{Pop and test top of stack;}
627 ; @r{if @code{nil}, go to 10,}
632 6 constant 1 ; @r{Push 1 onto top of stack.}
634 7 goto 17 ; @r{Go to 17 (in this case, 1 will be}
635 ; @r{returned by the function).}
639 10 constant * ; @r{Push symbol @code{*} onto stack.}
641 11 varref integer ; @r{Push value of @code{integer} onto stack.}
645 12 constant factorial ; @r{Push @code{factorial} onto stack.}
647 13 varref integer ; @r{Push value of @code{integer} onto stack.}
649 14 sub1 ; @r{Pop @code{integer}, decrement value,}
650 ; @r{push new value onto stack.}
654 ; @r{Stack now contains:}
655 ; @minus{} @r{decremented value of @code{integer}}
656 ; @minus{} @r{@code{factorial}}
657 ; @minus{} @r{value of @code{integer}}
658 ; @minus{} @r{@code{*}}
662 15 call 1 ; @r{Call function @code{factorial} using}
663 ; @r{the first (i.e., the top) element}
664 ; @r{of the stack as the argument;}
665 ; @r{push returned value onto stack.}
669 ; @r{Stack now contains:}
670 ; @minus{} @r{result of recursive}
671 ; @r{call to @code{factorial}}
672 ; @minus{} @r{value of @code{integer}}
673 ; @minus{} @r{@code{*}}
677 16 call 2 ; @r{Using the first two}
678 ; @r{(i.e., the top two)}
679 ; @r{elements of the stack}
681 ; @r{call the function @code{*},}
682 ; @r{pushing the result onto the stack.}
686 17 return ; @r{Return the top element}
692 The @code{silly-loop} function is somewhat more complex:
696 (defun silly-loop (n)
697 "Return time before and after N iterations of a loop."
698 (let ((t1 (current-time-string)))
699 (while (> (setq n (1- n))
701 (list t1 (current-time-string))))
706 (disassemble 'silly-loop)
707 @print{} byte-code for silly-loop:
708 doc: Return time before and after N iterations of a loop.
711 0 constant current-time-string ; @r{Push}
712 ; @r{@code{current-time-string}}
713 ; @r{onto top of stack.}
717 1 call 0 ; @r{Call @code{current-time-string}}
718 ; @r{ with no argument,}
719 ; @r{ pushing result onto stack.}
723 2 varbind t1 ; @r{Pop stack and bind @code{t1}}
724 ; @r{to popped value.}
728 3 varref n ; @r{Get value of @code{n} from}
729 ; @r{the environment and push}
730 ; @r{the value onto the stack.}
734 4 sub1 ; @r{Subtract 1 from top of stack.}
738 5 dup ; @r{Duplicate the top of the stack;}
739 ; @r{i.e., copy the top of}
740 ; @r{the stack and push the}
741 ; @r{copy onto the stack.}
745 6 varset n ; @r{Pop the top of the stack,}
746 ; @r{and bind @code{n} to the value.}
748 ; @r{In effect, the sequence @code{dup varset}}
749 ; @r{copies the top of the stack}
750 ; @r{into the value of @code{n}}
751 ; @r{without popping it.}
755 7 constant 0 ; @r{Push 0 onto stack.}
759 8 gtr ; @r{Pop top two values off stack,}
760 ; @r{test if @var{n} is greater than 0}
761 ; @r{and push result onto stack.}
765 9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0}
766 ; @r{(this exits the while loop).}
767 ; @r{else pop top of stack}
772 12 constant nil ; @r{Push @code{nil} onto stack}
773 ; @r{(this is the body of the loop).}
777 13 discard ; @r{Discard result of the body}
778 ; @r{of the loop (a while loop}
779 ; @r{is always evaluated for}
780 ; @r{its side effects).}
784 14 goto 3 ; @r{Jump back to beginning}
789 17 discard ; @r{Discard result of while loop}
790 ; @r{by popping top of stack.}
791 ; @r{This result is the value @code{nil} that}
792 ; @r{was not popped by the goto at 9.}
796 18 varref t1 ; @r{Push value of @code{t1} onto stack.}
800 19 constant current-time-string ; @r{Push}
801 ; @r{@code{current-time-string}}
802 ; @r{onto top of stack.}
806 20 call 0 ; @r{Call @code{current-time-string} again.}
810 21 list2 ; @r{Pop top two elements off stack,}
811 ; @r{create a list of them,}
812 ; @r{and push list onto stack.}
816 22 unbind 1 ; @r{Unbind @code{t1} in local environment.}
818 23 return ; @r{Return value of the top of stack.}
826 arch-tag: f78e3050-2f0a-4dee-be27-d9979a0a2289