| blob | 38f2b8196f309c3d95537826b936ee5cdb3252c0 |
1 @c -*-texinfo-*-
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, Debugging, Loading, Top
7 @chapter Byte Compilation
8 @cindex byte-code
9 @cindex 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
29 byte compilation.
31 @menu
32 * Speed of Byte-Code:: An example of speedup from byte compilation.
33 * Compilation Functions:: Byte compilation functions.
34 * Eval During Compile:: Code to be evaluated when you compile.
35 * Byte-Code Objects:: The data type used for byte-compiled functions.
36 * Disassembly:: Disassembling byte-code; how to read byte-code.
37 @end menu
39 @node Speed of Byte-Code
40 @section Performance of Byte-Compiled Code
42 A byte-compiled function is not as efficient as a primitive function
43 written in C, but runs much faster than the version written in Lisp.
44 Here is an example:
46 @example
47 @group
48 (defun silly-loop (n)
49 "Return time before and after N iterations of a loop."
50 (let ((t1 (current-time-string)))
51 (while (> (setq n (1- n))
52 0))
53 (list t1 (current-time-string))))
54 @result{} silly-loop
55 @end group
57 @group
58 (silly-loop 100000)
59 @result{} ("Fri Mar 18 17:25:57 1994"
60 "Fri Mar 18 17:26:28 1994") ; @r{31 seconds}
61 @end group
63 @group
64 (byte-compile 'silly-loop)
65 @result{} @r{[Compiled code not shown]}
66 @end group
68 @group
69 (silly-loop 100000)
70 @result{} ("Fri Mar 18 17:26:52 1994"
71 "Fri Mar 18 17:26:58 1994") ; @r{6 seconds}
72 @end group
73 @end example
75 In this example, the interpreted code required 31 seconds to run,
76 whereas the byte-compiled code required 6 seconds. These results are
77 representative, but actual results will vary greatly.
79 @node Compilation Functions
80 @comment node-name, next, previous, up
81 @section The Compilation Functions
82 @cindex compilation functions
84 You can byte-compile an individual function or macro definition with
85 the @code{byte-compile} function. You can compile a whole file with
86 @code{byte-compile-file}, or several files with
87 @code{byte-recompile-directory} or @code{batch-byte-compile}.
89 When you run the byte compiler, you may get warnings in a buffer called
90 @samp{*Compile-Log*}. These report usage in your program that suggest a
91 problem, but are not necessarily erroneous.
93 @cindex macro compilation
94 Be careful when byte-compiling code that uses macros. Macro calls are
95 expanded when they are compiled, so the macros must already be defined
96 for proper compilation. For more details, see @ref{Compiling Macros}.
98 Normally, compiling a file does not evaluate the file's contents or
99 load the file. But it does execute any @code{require} calls at
100 top-level in the file. One way to ensure that necessary macro
101 definitions are available during compilation is to require the file that
102 defines them. @xref{Features}.
104 @defun byte-compile symbol
105 This function byte-compiles the function definition of @var{symbol},
106 replacing the previous definition with the compiled one. The function
107 definition of @var{symbol} must be the actual code for the function;
108 i.e., the compiler does not follow indirection to another symbol.
109 @code{byte-compile} returns the new, compiled definition of
110 @var{symbol}.
112 If @var{symbol}'s definition is a byte-code function object,
113 @code{byte-compile} does nothing and returns @code{nil}. Lisp records
114 only one function definition for any symbol, and if that is already
115 compiled, non-compiled code is not available anywhere. So there is no
116 way to ``compile the same definition again.''
118 @example
119 @group
120 (defun factorial (integer)
121 "Compute factorial of INTEGER."
122 (if (= 1 integer) 1
123 (* integer (factorial (1- integer)))))
124 @result{} factorial
125 @end group
127 @group
128 (byte-compile 'factorial)
129 @result{}
130 #[(integer)
131 "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207"
132 [integer 1 * factorial]
133 4 "Compute factorial of INTEGER."]
134 @end group
135 @end example
137 @noindent
138 The result is a byte-code function object. The string it contains is
139 the actual byte-code; each character in it is an instruction or an
140 operand of an instruction. The vector contains all the constants,
141 variable names and function names used by the function, except for
142 certain primitives that are coded as special instructions.
143 @end defun
145 @deffn Command compile-defun
146 This command reads the defun containing point, compiles it, and
147 evaluates the result. If you use this on a defun that is actually a
148 function definition, the effect is to install a compiled version of that
149 function.
150 @end deffn
152 @deffn Command byte-compile-file filename
153 This function compiles a file of Lisp code named @var{filename} into
154 a file of byte-code. The output file's name is made by appending
155 @samp{c} to the end of @var{filename}.
157 Compilation works by reading the input file one form at a time. If it
158 is a definition of a function or macro, the compiled function or macro
159 definition is written out. Other forms are batched together, then each
160 batch is compiled, and written so that its compiled code will be
161 executed when the file is read. All comments are discarded when the
162 input file is read.
164 This command returns @code{t}. When called interactively, it prompts
165 for the file name.
167 @example
168 @group
169 % ls -l push*
170 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
171 @end group
173 @group
174 (byte-compile-file "~/emacs/push.el")
175 @result{} t
176 @end group
178 @group
179 % ls -l push*
180 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
181 -rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc
182 @end group
183 @end example
184 @end deffn
186 @deffn Command byte-recompile-directory directory flag
187 @cindex library compilation
188 This function recompiles every @samp{.el} file in @var{directory} that
189 needs recompilation. A file needs recompilation if a @samp{.elc} file
190 exists but is older than the @samp{.el} file.
192 If a @samp{.el} file exists, but there is no corresponding @samp{.elc}
193 file, then @var{flag} says what to do. If it is @code{nil}, the file is
194 ignored. If it is non-@code{nil}, the user is asked whether to compile
195 the file.
197 The returned value of this command is unpredictable.
198 @end deffn
200 @defun batch-byte-compile
201 This function runs @code{byte-compile-file} on files specified on the
202 command line. This function must be used only in a batch execution of
203 Emacs, as it kills Emacs on completion. An error in one file does not
204 prevent processing of subsequent files. (The file which gets the error
205 will not, of course, produce any compiled code.)
207 @example
208 % emacs -batch -f batch-byte-compile *.el
209 @end example
210 @end defun
212 @defun byte-code code-string data-vector max-stack
213 @cindex byte-code interpreter
214 This function actually interprets byte-code. A byte-compiled function
215 is actually defined with a body that calls @code{byte-code}. Don't call
216 this function yourself. Only the byte compiler knows how to generate
217 valid calls to this function.
219 In newer Emacs versions (19 and up), byte-code is usually executed as
220 part of a byte-code function object, and only rarely due to an explicit
221 call to @code{byte-code}.
222 @end defun
224 @node Eval During Compile
225 @section Evaluation During Compilation
227 These features permit you to write code to be evaluated during
228 compilation of a program.
230 @defspec eval-and-compile body
231 This form marks @var{body} to be evaluated both when you compile the
232 containing code and when you run it (whether compiled or not).
234 You can get a similar result by putting @var{body} in a separate file
235 and referring to that file with @code{require}. Using @code{require} is
236 preferable if there is a substantial amount of code to be executed in
237 this way.
238 @end defspec
240 @defspec eval-when-compile body
241 This form marks @var{body} to be evaluated at compile time @emph{only}.
242 The result of evaluation by the compiler becomes a constant which
243 appears in the compiled program. When the program is interpreted, not
244 compiled at all, @var{body} is evaluated normally.
246 At top-level, this is analogous to the Common Lisp idiom
247 @code{(eval-when (compile eval) @dots{})}. Elsewhere, the Common Lisp
248 @samp{#.} reader macro (but not when interpreting) is closer to what
249 @code{eval-when-compile} does.
250 @end defspec
252 @node Byte-Code Objects
253 @section Byte-Code Objects
254 @cindex compiled function
255 @cindex byte-code function
257 Byte-compiled functions have a special data type: they are
258 @dfn{byte-code function objects}.
260 Internally, a byte-code function object is much like a vector;
261 however, the evaluator handles this data type specially when it appears
262 as a function to be called. The printed representation for a byte-code
263 function object is like that for a vector, with an additional @samp{#}
264 before the opening @samp{[}.
266 In Emacs version 18, there was no byte-code function object data type;
267 compiled functions used the function @code{byte-code} to run the byte
268 code.
270 A byte-code function object must have at least four elements; there is
271 no maximum number, but only the first six elements are actually used.
272 They are:
274 @table @var
275 @item arglist
276 The list of argument symbols.
278 @item byte-code
279 The string containing the byte-code instructions.
281 @item constants
282 The vector of constants referenced by the byte code.
284 @item stacksize
285 The maximum stack size this function needs.
287 @item docstring
288 The documentation string (if any); otherwise, @code{nil}. For functions
289 preloaded before Emacs is dumped, this is usually an integer which is an
290 index into the @file{DOC} file; use @code{documentation} to convert this
291 into a string (@pxref{Accessing Documentation}).
293 @item interactive
294 The interactive spec (if any). This can be a string or a Lisp
295 expression. It is @code{nil} for a function that isn't interactive.
296 @end table
298 Here's an example of a byte-code function object, in printed
299 representation. It is the definition of the command
300 @code{backward-sexp}.
302 @example
303 #[(&optional arg)
304 "^H\204^F^@@\301^P\302^H[!\207"
305 [arg 1 forward-sexp]
306 2
307 254435
308 "p"]
309 @end example
311 The primitive way to create a byte-code object is with
312 @code{make-byte-code}:
314 @defun make-byte-code &rest elements
315 This function constructs and returns a byte-code function object
316 with @var{elements} as its elements.
317 @end defun
319 You should not try to come up with the elements for a byte-code
320 function yourself, because if they are inconsistent, Emacs may crash
321 when you call the function. Always leave it to the byte-compiler to
322 create these objects; it makes the elements consistent (we hope).
324 You can access the elements of a byte-code object using @code{aref};
325 you can also use @code{vconcat} to create a vector with the same
326 elements.
328 @node Disassembly
329 @section Disassembled Byte-Code
330 @cindex disassembled byte-code
332 People do not write byte-code; that job is left to the byte compiler.
333 But we provide a disassembler to satisfy a cat-like curiosity. The
334 disassembler converts the byte-compiled code into humanly readable
335 form.
337 The byte-code interpreter is implemented as a simple stack machine.
338 It pushes values onto a stack of its own, then pops them off to use them
339 in calculations and push the result back on the stack. When a byte-code
340 function returns, it pops a value off the stack and returns it as the
341 value of the function.
343 In addition to the stack, byte-code functions can use, bind and set
344 ordinary Lisp variables, by transferring values between variables and
345 the stack.
347 @deffn Command disassemble object &optional stream
348 This function prints the disassembled code for @var{object}. If
349 @var{stream} is supplied, then output goes there. Otherwise, the
350 disassembled code is printed to the stream @code{standard-output}. The
351 argument @var{object} can be a function name or a lambda expression.
353 As a special exception, if this function is used interactively,
354 it outputs to a buffer named @samp{*Disassemble*}.
355 @end deffn
357 Here are two examples of using the @code{disassemble} function. We
358 have added explanatory comments to help you relate the byte-code to the
359 Lisp source; these do not appear in the output of @code{disassemble}.
360 These examples show unoptimized byte-code. Nowadays byte-code is
361 usually optimized, but we did not want to rewrite these examples, since
362 they still serve their purpose.
364 @example
365 @group
366 (defun factorial (integer)
367 "Compute factorial of an integer."
368 (if (= 1 integer) 1
369 (* integer (factorial (1- integer)))))
370 @result{} factorial
371 @end group
373 @group
374 (factorial 4)
375 @result{} 24
376 @end group
378 @group
379 (disassemble 'factorial)
380 @print{} byte-code for factorial:
381 doc: Compute factorial of an integer.
382 args: (integer)
383 @end group
385 @group
386 0 constant 1 ; @r{Push 1 onto stack.}
388 1 varref integer ; @r{Get value of @code{integer}}
389 ; @r{from the environment}
390 ; @r{and push the value}
391 ; @r{onto the stack.}
392 @end group
394 @group
395 2 eqlsign ; @r{Pop top two values off stack,}
396 ; @r{compare them,}
397 ; @r{and push result onto stack.}
398 @end group
400 @group
401 3 goto-if-nil 10 ; @r{Pop and test top of stack;}
402 ; @r{if @code{nil}, go to 10,}
403 ; @r{else continue.}
404 @end group
406 @group
407 6 constant 1 ; @r{Push 1 onto top of stack.}
409 7 goto 17 ; @r{Go to 17 (in this case, 1 will be}
410 ; @r{returned by the function).}
411 @end group
413 @group
414 10 constant * ; @r{Push symbol @code{*} onto stack.}
416 11 varref integer ; @r{Push value of @code{integer} onto stack.}
417 @end group
419 @group
420 12 constant factorial ; @r{Push @code{factorial} onto stack.}
422 13 varref integer ; @r{Push value of @code{integer} onto stack.}
424 14 sub1 ; @r{Pop @code{integer}, decrement value,}
425 ; @r{push new value onto stack.}
426 @end group
428 @group
429 ; @r{Stack now contains:}
430 ; @minus{} @r{decremented value of @code{integer}}
431 ; @minus{} @r{@code{factorial}}
432 ; @minus{} @r{value of @code{integer}}
433 ; @minus{} @r{@code{*}}
434 @end group
436 @group
437 15 call 1 ; @r{Call function @code{factorial} using}
438 ; @r{the first (i.e., the top) element}
439 ; @r{of the stack as the argument;}
440 ; @r{push returned value onto stack.}
441 @end group
443 @group
444 ; @r{Stack now contains:}
445 ; @minus{} @r{result of result of recursive}
446 ; @r{call to @code{factorial}}
447 ; @minus{} @r{value of @code{integer}}
448 ; @minus{} @r{@code{*}}
449 @end group
451 @group
452 16 call 2 ; @r{Using the first two}
453 ; @r{(i.e., the top two)}
454 ; @r{elements of the stack}
455 ; @r{as arguments,}
456 ; @r{call the function @code{*},}
457 ; @r{pushing the result onto the stack.}
458 @end group
460 @group
461 17 return ; @r{Return the top element}
462 ; @r{of the stack.}
463 @result{} nil
464 @end group
465 @end example
467 The @code{silly-loop} function is somewhat more complex:
469 @example
470 @group
471 (defun silly-loop (n)
472 "Return time before and after N iterations of a loop."
473 (let ((t1 (current-time-string)))
474 (while (> (setq n (1- n))
475 0))
476 (list t1 (current-time-string))))
477 @result{} silly-loop
478 @end group
480 @group
481 (disassemble 'silly-loop)
482 @print{} byte-code for silly-loop:
483 doc: Return time before and after N iterations of a loop.
484 args: (n)
486 0 constant current-time-string ; @r{Push}
487 ; @r{@code{current-time-string}}
488 ; @r{onto top of stack.}
489 @end group
491 @group
492 1 call 0 ; @r{Call @code{current-time-string}}
493 ; @r{ with no argument,}
494 ; @r{ pushing result onto stack.}
495 @end group
497 @group
498 2 varbind t1 ; @r{Pop stack and bind @code{t1}}
499 ; @r{to popped value.}
500 @end group
502 @group
503 3 varref n ; @r{Get value of @code{n} from}
504 ; @r{the environment and push}
505 ; @r{the value onto the stack.}
506 @end group
508 @group
509 4 sub1 ; @r{Subtract 1 from top of stack.}
510 @end group
512 @group
513 5 dup ; @r{Duplicate the top of the stack;}
514 ; @r{i.e., copy the top of}
515 ; @r{the stack and push the}
516 ; @r{copy onto the stack.}
517 @end group
519 @group
520 6 varset n ; @r{Pop the top of the stack,}
521 ; @r{and bind @code{n} to the value.}
523 ; @r{In effect, the sequence @code{dup varset}}
524 ; @r{copies the top of the stack}
525 ; @r{into the value of @code{n}}
526 ; @r{without popping it.}
527 @end group
529 @group
530 7 constant 0 ; @r{Push 0 onto stack.}
531 @end group
533 @group
534 8 gtr ; @r{Pop top two values off stack,}
535 ; @r{test if @var{n} is greater than 0}
536 ; @r{and push result onto stack.}
537 @end group
539 @group
540 9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} > 0}
541 ; @r{else pop top of stack}
542 ; @r{and continue}
543 ; @r{(this exits the while loop).}
544 @end group
546 @group
547 12 constant nil ; @r{Push @code{nil} onto stack}
548 ; @r{(this is the body of the loop).}
549 @end group
551 @group
552 13 discard ; @r{Discard result of the body}
553 ; @r{of the loop (a while loop}
554 ; @r{is always evaluated for}
555 ; @r{its side effects).}
556 @end group
558 @group
559 14 goto 3 ; @r{Jump back to beginning}
560 ; @r{of while loop.}
561 @end group
563 @group
564 17 discard ; @r{Discard result of while loop}
565 ; @r{by popping top of stack.}
566 @end group
568 @group
569 18 varref t1 ; @r{Push value of @code{t1} onto stack.}
570 @end group
572 @group
573 19 constant current-time-string ; @r{Push}
574 ; @r{@code{current-time-string}}
575 ; @r{onto top of stack.}
576 @end group
578 @group
579 20 call 0 ; @r{Call @code{current-time-string} again.}
580 @end group
582 @group
583 21 list2 ; @r{Pop top two elements off stack,}
584 ; @r{create a list of them,}
585 ; @r{and push list onto stack.}
586 @end group
588 @group
589 22 unbind 1 ; @r{Unbind @code{t1} in local environment.}
591 23 return ; @r{Return value of the top of stack.}
593 @result{} nil
594 @end group
595 @end example