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