Commit | Line | Data |
---|---|---|
b8d4c8d0 GM |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
ba318903 | 3 | @c Copyright (C) 1990-1994, 2001-2014 Free Software Foundation, Inc. |
b8d4c8d0 | 4 | @c See the file elisp.texi for copying conditions. |
ecc6530d | 5 | @node Byte Compilation |
b8d4c8d0 GM |
6 | @chapter Byte Compilation |
7 | @cindex byte compilation | |
8 | @cindex byte-code | |
9 | @cindex compilation (Emacs Lisp) | |
10 | ||
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}. | |
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 | ||
b8d4c8d0 GM |
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. | |
25 | ||
26 | @vindex no-byte-compile | |
27 | If you do not want a Lisp file to be compiled, ever, put a file-local | |
28 | variable binding for @code{no-byte-compile} into it, like this: | |
29 | ||
30 | @example | |
31 | ;; -*-no-byte-compile: t; -*- | |
32 | @end example | |
33 | ||
b8d4c8d0 GM |
34 | @menu |
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. | |
d24880de | 39 | * Eval During Compile:: Code to be evaluated when you compile. |
b8d4c8d0 | 40 | * Compiler Errors:: Handling compiler error messages. |
d24880de | 41 | * Byte-Code Objects:: The data type used for byte-compiled functions. |
b8d4c8d0 GM |
42 | * Disassembly:: Disassembling byte-code; how to read byte-code. |
43 | @end menu | |
44 | ||
45 | @node Speed of Byte-Code | |
46 | @section Performance of Byte-Compiled Code | |
47 | ||
48 | A byte-compiled function is not as efficient as a primitive function | |
49 | written in C, but runs much faster than the version written in Lisp. | |
50 | Here is an example: | |
51 | ||
52 | @example | |
53 | @group | |
54 | (defun silly-loop (n) | |
25dec365 CY |
55 | "Return the time, in seconds, to run N iterations of a loop." |
56 | (let ((t1 (float-time))) | |
57 | (while (> (setq n (1- n)) 0)) | |
58 | (- (float-time) t1))) | |
b8d4c8d0 GM |
59 | @result{} silly-loop |
60 | @end group | |
61 | ||
62 | @group | |
c36745c6 | 63 | (silly-loop 50000000) |
25dec365 | 64 | @result{} 10.235304117202759 |
b8d4c8d0 GM |
65 | @end group |
66 | ||
67 | @group | |
68 | (byte-compile 'silly-loop) | |
69 | @result{} @r{[Compiled code not shown]} | |
70 | @end group | |
71 | ||
72 | @group | |
c36745c6 | 73 | (silly-loop 50000000) |
25dec365 | 74 | @result{} 3.705854892730713 |
b8d4c8d0 GM |
75 | @end group |
76 | @end example | |
77 | ||
25dec365 CY |
78 | In this example, the interpreted code required 10 seconds to run, |
79 | whereas the byte-compiled code required less than 4 seconds. These | |
80 | results are representative, but actual results may vary. | |
b8d4c8d0 GM |
81 | |
82 | @node Compilation Functions | |
25dec365 | 83 | @section Byte-Compilation Functions |
b8d4c8d0 GM |
84 | @cindex compilation functions |
85 | ||
86 | You can byte-compile an individual function or macro definition with | |
87 | the @code{byte-compile} function. You can compile a whole file with | |
88 | @code{byte-compile-file}, or several files with | |
89 | @code{byte-recompile-directory} or @code{batch-byte-compile}. | |
90 | ||
25dec365 CY |
91 | Sometimes, the byte compiler produces warning and/or error messages |
92 | (@pxref{Compiler Errors}, for details). These messages are recorded | |
2bb0eca1 | 93 | in a buffer called @file{*Compile-Log*}, which uses Compilation mode. |
25dec365 | 94 | @xref{Compilation Mode,,,emacs, The GNU Emacs Manual}. |
b8d4c8d0 GM |
95 | |
96 | @cindex macro compilation | |
25dec365 CY |
97 | Be careful when writing macro calls in files that you intend to |
98 | byte-compile. Since macro calls are expanded when they are compiled, | |
99 | the macros need to be loaded into Emacs or the byte compiler will not | |
100 | do the right thing. The usual way to handle this is with | |
101 | @code{require} forms which specify the files containing the needed | |
102 | macro definitions (@pxref{Named Features}). Normally, the | |
103 | byte compiler does not evaluate the code that it is compiling, but it | |
104 | handles @code{require} forms specially, by loading the specified | |
105 | libraries. To avoid loading the macro definition files when someone | |
106 | @emph{runs} the compiled program, write @code{eval-when-compile} | |
107 | around the @code{require} calls (@pxref{Eval During Compile}). For | |
108 | more details, @xref{Compiling Macros}. | |
109 | ||
110 | Inline (@code{defsubst}) functions are less troublesome; if you | |
b8d4c8d0 GM |
111 | compile a call to such a function before its definition is known, the |
112 | call will still work right, it will just run slower. | |
113 | ||
b8d4c8d0 GM |
114 | @defun byte-compile symbol |
115 | This function byte-compiles the function definition of @var{symbol}, | |
116 | replacing the previous definition with the compiled one. The function | |
117 | definition of @var{symbol} must be the actual code for the function; | |
25dec365 CY |
118 | @code{byte-compile} does not handle function indirection. The return |
119 | value is the byte-code function object which is the compiled | |
120 | definition of @var{symbol} (@pxref{Byte-Code Objects}). | |
b8d4c8d0 GM |
121 | |
122 | @example | |
123 | @group | |
124 | (defun factorial (integer) | |
125 | "Compute factorial of INTEGER." | |
126 | (if (= 1 integer) 1 | |
127 | (* integer (factorial (1- integer))))) | |
128 | @result{} factorial | |
129 | @end group | |
130 | ||
131 | @group | |
132 | (byte-compile 'factorial) | |
133 | @result{} | |
134 | #[(integer) | |
135 | "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207" | |
136 | [integer 1 * factorial] | |
137 | 4 "Compute factorial of INTEGER."] | |
138 | @end group | |
139 | @end example | |
140 | ||
25dec365 CY |
141 | If @var{symbol}'s definition is a byte-code function object, |
142 | @code{byte-compile} does nothing and returns @code{nil}. It does not | |
143 | ``compile the symbol's definition again'', since the original | |
144 | (non-compiled) code has already been replaced in the symbol's function | |
145 | cell by the byte-compiled code. | |
146 | ||
147 | The argument to @code{byte-compile} can also be a @code{lambda} | |
148 | expression. In that case, the function returns the corresponding | |
149 | compiled code but does not store it anywhere. | |
b8d4c8d0 GM |
150 | @end defun |
151 | ||
152 | @deffn Command compile-defun &optional arg | |
153 | This command reads the defun containing point, compiles it, and | |
154 | evaluates the result. If you use this on a defun that is actually a | |
155 | function definition, the effect is to install a compiled version of that | |
156 | function. | |
157 | ||
158 | @code{compile-defun} normally displays the result of evaluation in the | |
159 | echo area, but if @var{arg} is non-@code{nil}, it inserts the result | |
160 | in the current buffer after the form it compiled. | |
161 | @end deffn | |
162 | ||
163 | @deffn Command byte-compile-file filename &optional load | |
164 | This function compiles a file of Lisp code named @var{filename} into a | |
165 | file of byte-code. The output file's name is made by changing the | |
166 | @samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in | |
167 | @samp{.el}, it adds @samp{.elc} to the end of @var{filename}. | |
168 | ||
169 | Compilation works by reading the input file one form at a time. If it | |
170 | is a definition of a function or macro, the compiled function or macro | |
171 | definition is written out. Other forms are batched together, then each | |
172 | batch is compiled, and written so that its compiled code will be | |
173 | executed when the file is read. All comments are discarded when the | |
174 | input file is read. | |
175 | ||
176 | This command returns @code{t} if there were no errors and @code{nil} | |
177 | otherwise. When called interactively, it prompts for the file name. | |
178 | ||
179 | If @var{load} is non-@code{nil}, this command loads the compiled file | |
180 | after compiling it. Interactively, @var{load} is the prefix argument. | |
181 | ||
182 | @example | |
183 | @group | |
08c0a604 PE |
184 | $ ls -l push* |
185 | -rw-r--r-- 1 lewis lewis 791 Oct 5 20:31 push.el | |
b8d4c8d0 GM |
186 | @end group |
187 | ||
188 | @group | |
189 | (byte-compile-file "~/emacs/push.el") | |
190 | @result{} t | |
191 | @end group | |
192 | ||
193 | @group | |
08c0a604 PE |
194 | $ ls -l push* |
195 | -rw-r--r-- 1 lewis lewis 791 Oct 5 20:31 push.el | |
196 | -rw-rw-rw- 1 lewis lewis 638 Oct 8 20:25 push.elc | |
b8d4c8d0 GM |
197 | @end group |
198 | @end example | |
199 | @end deffn | |
200 | ||
201 | @deffn Command byte-recompile-directory directory &optional flag force | |
202 | @cindex library compilation | |
203 | This command recompiles every @samp{.el} file in @var{directory} (or | |
204 | its subdirectories) that needs recompilation. A file needs | |
205 | recompilation if a @samp{.elc} file exists but is older than the | |
206 | @samp{.el} file. | |
207 | ||
208 | When a @samp{.el} file has no corresponding @samp{.elc} file, | |
209 | @var{flag} says what to do. If it is @code{nil}, this command ignores | |
210 | these files. If @var{flag} is 0, it compiles them. If it is neither | |
211 | @code{nil} nor 0, it asks the user whether to compile each such file, | |
212 | and asks about each subdirectory as well. | |
213 | ||
214 | Interactively, @code{byte-recompile-directory} prompts for | |
215 | @var{directory} and @var{flag} is the prefix argument. | |
216 | ||
217 | If @var{force} is non-@code{nil}, this command recompiles every | |
218 | @samp{.el} file that has a @samp{.elc} file. | |
219 | ||
220 | The returned value is unpredictable. | |
221 | @end deffn | |
222 | ||
223 | @defun batch-byte-compile &optional noforce | |
224 | This function runs @code{byte-compile-file} on files specified on the | |
225 | command line. This function must be used only in a batch execution of | |
226 | Emacs, as it kills Emacs on completion. An error in one file does not | |
227 | prevent processing of subsequent files, but no output file will be | |
228 | generated for it, and the Emacs process will terminate with a nonzero | |
229 | status code. | |
230 | ||
231 | If @var{noforce} is non-@code{nil}, this function does not recompile | |
232 | files that have an up-to-date @samp{.elc} file. | |
233 | ||
234 | @example | |
08c0a604 | 235 | $ emacs -batch -f batch-byte-compile *.el |
b8d4c8d0 GM |
236 | @end example |
237 | @end defun | |
238 | ||
b8d4c8d0 GM |
239 | @node Docs and Compilation |
240 | @section Documentation Strings and Compilation | |
241 | @cindex dynamic loading of documentation | |
242 | ||
d6d78511 CY |
243 | When Emacs loads functions and variables from a byte-compiled file, |
244 | it normally does not load their documentation strings into memory. | |
245 | Each documentation string is ``dynamically'' loaded from the | |
246 | byte-compiled file only when needed. This saves memory, and speeds up | |
247 | loading by skipping the processing of the documentation strings. | |
248 | ||
249 | This feature has a drawback: if you delete, move, or alter the | |
250 | compiled file (such as by compiling a new version), Emacs may no | |
251 | longer be able to access the documentation string of previously-loaded | |
252 | functions or variables. Such a problem normally only occurs if you | |
253 | build Emacs yourself, and happen to edit and/or recompile the Lisp | |
254 | source files. To solve it, just reload each file after recompilation. | |
255 | ||
256 | Dynamic loading of documentation strings from byte-compiled files is | |
257 | determined, at compile time, for each byte-compiled file. It can be | |
258 | disabled via the option @code{byte-compile-dynamic-docstrings}. | |
25dec365 | 259 | |
0b128ac4 | 260 | @defopt byte-compile-dynamic-docstrings |
25dec365 CY |
261 | If this is non-@code{nil}, the byte compiler generates compiled files |
262 | that are set up for dynamic loading of documentation strings. | |
d6d78511 CY |
263 | |
264 | To disable the dynamic loading feature for a specific file, set this | |
265 | option to @code{nil} in its header line (@pxref{File Variables, , | |
266 | Local Variables in Files, emacs, The GNU Emacs Manual}), like this: | |
267 | ||
268 | @smallexample | |
269 | -*-byte-compile-dynamic-docstrings: nil;-*- | |
270 | @end smallexample | |
271 | ||
272 | This is useful mainly if you expect to change the file, and you want | |
273 | Emacs sessions that have already loaded it to keep working when the | |
274 | file changes. | |
0b128ac4 | 275 | @end defopt |
25dec365 | 276 | |
d6d78511 CY |
277 | @cindex @samp{#@@@var{count}} |
278 | @cindex @samp{#$} | |
279 | Internally, the dynamic loading of documentation strings is | |
280 | accomplished by writing compiled files with a special Lisp reader | |
281 | construct, @samp{#@@@var{count}}. This construct skips the next | |
282 | @var{count} characters. It also uses the @samp{#$} construct, which | |
283 | stands for ``the name of this file, as a string''. Do not use these | |
284 | constructs in Lisp source files; they are not designed to be clear to | |
285 | humans reading the file. | |
286 | ||
b8d4c8d0 GM |
287 | @node Dynamic Loading |
288 | @section Dynamic Loading of Individual Functions | |
289 | ||
290 | @cindex dynamic loading of functions | |
291 | @cindex lazy loading | |
292 | When you compile a file, you can optionally enable the @dfn{dynamic | |
293 | function loading} feature (also known as @dfn{lazy loading}). With | |
294 | dynamic function loading, loading the file doesn't fully read the | |
295 | function definitions in the file. Instead, each function definition | |
296 | contains a place-holder which refers to the file. The first time each | |
297 | function is called, it reads the full definition from the file, to | |
298 | replace the place-holder. | |
299 | ||
300 | The advantage of dynamic function loading is that loading the file | |
301 | becomes much faster. This is a good thing for a file which contains | |
302 | many separate user-callable functions, if using one of them does not | |
303 | imply you will probably also use the rest. A specialized mode which | |
304 | provides many keyboard commands often has that usage pattern: a user may | |
305 | invoke the mode, but use only a few of the commands it provides. | |
306 | ||
307 | The dynamic loading feature has certain disadvantages: | |
308 | ||
309 | @itemize @bullet | |
310 | @item | |
311 | If you delete or move the compiled file after loading it, Emacs can no | |
312 | longer load the remaining function definitions not already loaded. | |
313 | ||
314 | @item | |
315 | If you alter the compiled file (such as by compiling a new version), | |
316 | then trying to load any function not already loaded will usually yield | |
317 | nonsense results. | |
318 | @end itemize | |
319 | ||
320 | These problems will never happen in normal circumstances with | |
321 | installed Emacs files. But they are quite likely to happen with Lisp | |
322 | files that you are changing. The easiest way to prevent these problems | |
323 | is to reload the new compiled file immediately after each recompilation. | |
324 | ||
325 | The byte compiler uses the dynamic function loading feature if the | |
326 | variable @code{byte-compile-dynamic} is non-@code{nil} at compilation | |
327 | time. Do not set this variable globally, since dynamic loading is | |
328 | desirable only for certain files. Instead, enable the feature for | |
329 | specific source files with file-local variable bindings. For example, | |
330 | you could do it by writing this text in the source file's first line: | |
331 | ||
332 | @example | |
333 | -*-byte-compile-dynamic: t;-*- | |
334 | @end example | |
335 | ||
336 | @defvar byte-compile-dynamic | |
337 | If this is non-@code{nil}, the byte compiler generates compiled files | |
338 | that are set up for dynamic function loading. | |
339 | @end defvar | |
340 | ||
341 | @defun fetch-bytecode function | |
342 | If @var{function} is a byte-code function object, this immediately | |
343 | finishes loading the byte code of @var{function} from its | |
344 | byte-compiled file, if it is not fully loaded already. Otherwise, | |
345 | it does nothing. It always returns @var{function}. | |
346 | @end defun | |
347 | ||
348 | @node Eval During Compile | |
349 | @section Evaluation During Compilation | |
350 | ||
351 | These features permit you to write code to be evaluated during | |
352 | compilation of a program. | |
353 | ||
354 | @defspec eval-and-compile body@dots{} | |
355 | This form marks @var{body} to be evaluated both when you compile the | |
356 | containing code and when you run it (whether compiled or not). | |
357 | ||
358 | You can get a similar result by putting @var{body} in a separate file | |
359 | and referring to that file with @code{require}. That method is | |
360 | preferable when @var{body} is large. Effectively @code{require} is | |
361 | automatically @code{eval-and-compile}, the package is loaded both when | |
362 | compiling and executing. | |
363 | ||
364 | @code{autoload} is also effectively @code{eval-and-compile} too. It's | |
365 | recognized when compiling, so uses of such a function don't produce | |
366 | ``not known to be defined'' warnings. | |
367 | ||
368 | Most uses of @code{eval-and-compile} are fairly sophisticated. | |
369 | ||
370 | If a macro has a helper function to build its result, and that macro | |
371 | is used both locally and outside the package, then | |
372 | @code{eval-and-compile} should be used to get the helper both when | |
373 | compiling and then later when running. | |
374 | ||
375 | If functions are defined programmatically (with @code{fset} say), then | |
376 | @code{eval-and-compile} can be used to have that done at compile-time | |
377 | as well as run-time, so calls to those functions are checked (and | |
378 | warnings about ``not known to be defined'' suppressed). | |
379 | @end defspec | |
380 | ||
381 | @defspec eval-when-compile body@dots{} | |
382 | This form marks @var{body} to be evaluated at compile time but not when | |
383 | the compiled program is loaded. The result of evaluation by the | |
384 | compiler becomes a constant which appears in the compiled program. If | |
385 | you load the source file, rather than compiling it, @var{body} is | |
386 | evaluated normally. | |
387 | ||
388 | @cindex compile-time constant | |
389 | If you have a constant that needs some calculation to produce, | |
390 | @code{eval-when-compile} can do that at compile-time. For example, | |
391 | ||
392 | @lisp | |
393 | (defvar my-regexp | |
394 | (eval-when-compile (regexp-opt '("aaa" "aba" "abb")))) | |
395 | @end lisp | |
396 | ||
397 | @cindex macros, at compile time | |
398 | If you're using another package, but only need macros from it (the | |
399 | byte compiler will expand those), then @code{eval-when-compile} can be | |
400 | used to load it for compiling, but not executing. For example, | |
401 | ||
402 | @lisp | |
403 | (eval-when-compile | |
049bcbcb | 404 | (require 'my-macro-package)) |
b8d4c8d0 GM |
405 | @end lisp |
406 | ||
407 | The same sort of thing goes for macros and @code{defsubst} functions | |
408 | defined locally and only for use within the file. They are needed for | |
409 | compiling the file, but in most cases they are not needed for | |
410 | execution of the compiled file. For example, | |
411 | ||
412 | @lisp | |
413 | (eval-when-compile | |
414 | (unless (fboundp 'some-new-thing) | |
415 | (defmacro 'some-new-thing () | |
416 | (compatibility code)))) | |
417 | @end lisp | |
418 | ||
419 | @noindent | |
420 | This is often good for code that's only a fallback for compatibility | |
421 | with other versions of Emacs. | |
422 | ||
423 | @strong{Common Lisp Note:} At top level, @code{eval-when-compile} is analogous to the Common | |
424 | Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the | |
425 | Common Lisp @samp{#.} reader macro (but not when interpreting) is closer | |
426 | to what @code{eval-when-compile} does. | |
427 | @end defspec | |
428 | ||
429 | @node Compiler Errors | |
430 | @section Compiler Errors | |
431 | @cindex compiler errors | |
432 | ||
81c7d631 CY |
433 | Error and warning messages from byte compilation are printed in a |
434 | buffer named @file{*Compile-Log*}. These messages include file names | |
435 | and line numbers identifying the location of the problem. The usual | |
436 | Emacs commands for operating on compiler output can be used on these | |
355cabc6 CY |
437 | messages. |
438 | ||
439 | When an error is due to invalid syntax in the program, the byte | |
440 | compiler might get confused about the errors' exact location. One way | |
81c7d631 CY |
441 | to investigate is to switch to the buffer @w{@file{ *Compiler |
442 | Input*}}. (This buffer name starts with a space, so it does not show | |
443 | up in the Buffer Menu.) This buffer contains the program being | |
355cabc6 CY |
444 | compiled, and point shows how far the byte compiler was able to read; |
445 | the cause of the error might be nearby. @xref{Syntax Errors}, for | |
446 | some tips for locating syntax errors. | |
447 | ||
81c7d631 CY |
448 | A common type of warning issued by the byte compiler is for |
449 | functions and variables that were used but not defined. Such warnings | |
450 | report the line number for the end of the file, not the locations | |
451 | where the missing functions or variables were used; to find these, you | |
452 | must search the file manually. | |
b8d4c8d0 | 453 | |
81c7d631 CY |
454 | If you are sure that a warning message about a missing function or |
455 | variable is unjustified, there are several ways to suppress it: | |
456 | ||
457 | @itemize @bullet | |
458 | @item | |
459 | You can suppress the warning for a specific call to a function | |
460 | @var{func} by conditionalizing it on an @code{fboundp} test, like | |
461 | this: | |
b8d4c8d0 GM |
462 | |
463 | @example | |
464 | (if (fboundp '@var{func}) ...(@var{func} ...)...) | |
465 | @end example | |
466 | ||
467 | @noindent | |
468 | The call to @var{func} must be in the @var{then-form} of the | |
469 | @code{if}, and @var{func} must appear quoted in the call to | |
470 | @code{fboundp}. (This feature operates for @code{cond} as well.) | |
471 | ||
81c7d631 CY |
472 | @item |
473 | Likewise, you can suppress the warning for a specific use of a | |
474 | variable @var{variable} by conditionalizing it on a @code{boundp} | |
475 | test: | |
b8d4c8d0 GM |
476 | |
477 | @example | |
478 | (if (boundp '@var{variable}) ...@var{variable}...) | |
479 | @end example | |
480 | ||
481 | @noindent | |
482 | The reference to @var{variable} must be in the @var{then-form} of the | |
483 | @code{if}, and @var{variable} must appear quoted in the call to | |
484 | @code{boundp}. | |
485 | ||
81c7d631 CY |
486 | @item |
487 | You can tell the compiler that a function is defined using | |
488 | @code{declare-function}. @xref{Declaring Functions}. | |
489 | ||
490 | @item | |
491 | Likewise, you can tell the compiler that a variable is defined using | |
492 | @code{defvar} with no initial value. (Note that this marks the | |
493 | variable as special.) @xref{Defining Variables}. | |
494 | @end itemize | |
495 | ||
496 | You can also suppress any and all compiler warnings within a certain | |
fc37ae72 | 497 | expression using the construct @code{with-no-warnings}: |
b8d4c8d0 GM |
498 | |
499 | @c This is implemented with a defun, but conceptually it is | |
500 | @c a special form. | |
501 | ||
502 | @defspec with-no-warnings body@dots{} | |
503 | In execution, this is equivalent to @code{(progn @var{body}...)}, | |
504 | but the compiler does not issue warnings for anything that occurs | |
505 | inside @var{body}. | |
506 | ||
507 | We recommend that you use this construct around the smallest | |
cd1181db | 508 | possible piece of code, to avoid missing possible warnings other than |
fc37ae72 | 509 | one you intend to suppress. |
b8d4c8d0 GM |
510 | @end defspec |
511 | ||
81c7d631 CY |
512 | Byte compiler warnings can be controlled more precisely by setting |
513 | the variable @code{byte-compile-warnings}. See its documentation | |
514 | string for details. | |
5bb0cda3 | 515 | |
b8d4c8d0 GM |
516 | @node Byte-Code Objects |
517 | @section Byte-Code Function Objects | |
518 | @cindex compiled function | |
519 | @cindex byte-code function | |
8d0c20ae | 520 | @cindex byte-code object |
b8d4c8d0 GM |
521 | |
522 | Byte-compiled functions have a special data type: they are | |
25dec365 CY |
523 | @dfn{byte-code function objects}. Whenever such an object appears as |
524 | a function to be called, Emacs uses the byte-code interpreter to | |
525 | execute the byte-code. | |
b8d4c8d0 | 526 | |
25dec365 CY |
527 | Internally, a byte-code function object is much like a vector; its |
528 | elements can be accessed using @code{aref}. Its printed | |
529 | representation is like that for a vector, with an additional @samp{#} | |
530 | before the opening @samp{[}. It must have at least four elements; | |
531 | there is no maximum number, but only the first six elements have any | |
532 | normal use. They are: | |
b8d4c8d0 GM |
533 | |
534 | @table @var | |
535 | @item arglist | |
536 | The list of argument symbols. | |
537 | ||
538 | @item byte-code | |
539 | The string containing the byte-code instructions. | |
540 | ||
541 | @item constants | |
542 | The vector of Lisp objects referenced by the byte code. These include | |
543 | symbols used as function names and variable names. | |
544 | ||
545 | @item stacksize | |
546 | The maximum stack size this function needs. | |
547 | ||
548 | @item docstring | |
549 | The documentation string (if any); otherwise, @code{nil}. The value may | |
550 | be a number or a list, in case the documentation string is stored in a | |
551 | file. Use the function @code{documentation} to get the real | |
552 | documentation string (@pxref{Accessing Documentation}). | |
553 | ||
554 | @item interactive | |
555 | The interactive spec (if any). This can be a string or a Lisp | |
556 | expression. It is @code{nil} for a function that isn't interactive. | |
557 | @end table | |
558 | ||
559 | Here's an example of a byte-code function object, in printed | |
560 | representation. It is the definition of the command | |
561 | @code{backward-sexp}. | |
562 | ||
563 | @example | |
564 | #[(&optional arg) | |
565 | "^H\204^F^@@\301^P\302^H[!\207" | |
566 | [arg 1 forward-sexp] | |
567 | 2 | |
568 | 254435 | |
25dec365 | 569 | "^p"] |
b8d4c8d0 GM |
570 | @end example |
571 | ||
572 | The primitive way to create a byte-code object is with | |
573 | @code{make-byte-code}: | |
574 | ||
575 | @defun make-byte-code &rest elements | |
576 | This function constructs and returns a byte-code function object | |
577 | with @var{elements} as its elements. | |
578 | @end defun | |
579 | ||
580 | You should not try to come up with the elements for a byte-code | |
581 | function yourself, because if they are inconsistent, Emacs may crash | |
582 | when you call the function. Always leave it to the byte compiler to | |
583 | create these objects; it makes the elements consistent (we hope). | |
584 | ||
b8d4c8d0 GM |
585 | @node Disassembly |
586 | @section Disassembled Byte-Code | |
587 | @cindex disassembled byte-code | |
588 | ||
c36745c6 CY |
589 | People do not write byte-code; that job is left to the byte |
590 | compiler. But we provide a disassembler to satisfy a cat-like | |
591 | curiosity. The disassembler converts the byte-compiled code into | |
592 | human-readable form. | |
b8d4c8d0 GM |
593 | |
594 | The byte-code interpreter is implemented as a simple stack machine. | |
595 | It pushes values onto a stack of its own, then pops them off to use them | |
596 | in calculations whose results are themselves pushed back on the stack. | |
597 | When a byte-code function returns, it pops a value off the stack and | |
598 | returns it as the value of the function. | |
599 | ||
600 | In addition to the stack, byte-code functions can use, bind, and set | |
601 | ordinary Lisp variables, by transferring values between variables and | |
602 | the stack. | |
603 | ||
604 | @deffn Command disassemble object &optional buffer-or-name | |
605 | This command displays the disassembled code for @var{object}. In | |
606 | interactive use, or if @var{buffer-or-name} is @code{nil} or omitted, | |
2bb0eca1 | 607 | the output goes in a buffer named @file{*Disassemble*}. If |
b8d4c8d0 GM |
608 | @var{buffer-or-name} is non-@code{nil}, it must be a buffer or the |
609 | name of an existing buffer. Then the output goes there, at point, and | |
610 | point is left before the output. | |
611 | ||
612 | The argument @var{object} can be a function name, a lambda expression | |
8d0c20ae EZ |
613 | (@pxref{Lambda Expressions}), or a byte-code object (@pxref{Byte-Code |
614 | Objects}). If it is a lambda expression, @code{disassemble} compiles | |
615 | it and disassembles the resulting compiled code. | |
b8d4c8d0 GM |
616 | @end deffn |
617 | ||
618 | Here are two examples of using the @code{disassemble} function. We | |
619 | have added explanatory comments to help you relate the byte-code to the | |
620 | Lisp source; these do not appear in the output of @code{disassemble}. | |
b8d4c8d0 GM |
621 | |
622 | @example | |
623 | @group | |
624 | (defun factorial (integer) | |
625 | "Compute factorial of an integer." | |
626 | (if (= 1 integer) 1 | |
627 | (* integer (factorial (1- integer))))) | |
628 | @result{} factorial | |
629 | @end group | |
630 | ||
631 | @group | |
632 | (factorial 4) | |
633 | @result{} 24 | |
634 | @end group | |
635 | ||
636 | @group | |
637 | (disassemble 'factorial) | |
638 | @print{} byte-code for factorial: | |
639 | doc: Compute factorial of an integer. | |
640 | args: (integer) | |
641 | @end group | |
642 | ||
643 | @group | |
51d58083 GM |
644 | 0 varref integer ; @r{Get the value of @code{integer} and} |
645 | ; @r{push it onto the stack.} | |
646 | 1 constant 1 ; @r{Push 1 onto stack.} | |
b8d4c8d0 | 647 | @end group |
b8d4c8d0 | 648 | @group |
51d58083 GM |
649 | 2 eqlsign ; @r{Pop top two values off stack, compare} |
650 | ; @r{them, and push result onto stack.} | |
b8d4c8d0 | 651 | @end group |
b8d4c8d0 | 652 | @group |
51d58083 GM |
653 | 3 goto-if-nil 1 ; @r{Pop and test top of stack;} |
654 | ; @r{if @code{nil}, go to 1, else continue.} | |
655 | 6 constant 1 ; @r{Push 1 onto top of stack.} | |
656 | 7 return ; @r{Return the top element of the stack.} | |
b8d4c8d0 | 657 | @end group |
b8d4c8d0 | 658 | @group |
51d58083 GM |
659 | 8:1 varref integer ; @r{Push value of @code{integer} onto stack.} |
660 | 9 constant factorial ; @r{Push @code{factorial} onto stack.} | |
661 | 10 varref integer ; @r{Push value of @code{integer} onto stack.} | |
662 | 11 sub1 ; @r{Pop @code{integer}, decrement value,} | |
663 | ; @r{push new value onto stack.} | |
664 | 12 call 1 ; @r{Call function @code{factorial} using first} | |
1df7defd | 665 | ; @r{(i.e., top) stack element as argument;} |
51d58083 | 666 | ; @r{push returned value onto stack.} |
b8d4c8d0 | 667 | @end group |
b8d4c8d0 | 668 | @group |
51d58083 GM |
669 | 13 mult ; @r{Pop top two values off stack, multiply} |
670 | ; @r{them, and push result onto stack.} | |
671 | 14 return ; @r{Return the top element of the stack.} | |
b8d4c8d0 GM |
672 | @end group |
673 | @end example | |
674 | ||
675 | The @code{silly-loop} function is somewhat more complex: | |
676 | ||
677 | @example | |
678 | @group | |
679 | (defun silly-loop (n) | |
680 | "Return time before and after N iterations of a loop." | |
681 | (let ((t1 (current-time-string))) | |
682 | (while (> (setq n (1- n)) | |
683 | 0)) | |
684 | (list t1 (current-time-string)))) | |
685 | @result{} silly-loop | |
686 | @end group | |
687 | ||
688 | @group | |
689 | (disassemble 'silly-loop) | |
690 | @print{} byte-code for silly-loop: | |
691 | doc: Return time before and after N iterations of a loop. | |
692 | args: (n) | |
51d58083 | 693 | @end group |
b8d4c8d0 | 694 | |
51d58083 GM |
695 | @group |
696 | 0 constant current-time-string ; @r{Push @code{current-time-string}} | |
b8d4c8d0 GM |
697 | ; @r{onto top of stack.} |
698 | @end group | |
b8d4c8d0 | 699 | @group |
51d58083 GM |
700 | 1 call 0 ; @r{Call @code{current-time-string} with no} |
701 | ; @r{argument, push result onto stack.} | |
b8d4c8d0 | 702 | @end group |
b8d4c8d0 | 703 | @group |
51d58083 | 704 | 2 varbind t1 ; @r{Pop stack and bind @code{t1} to popped value.} |
b8d4c8d0 | 705 | @end group |
b8d4c8d0 | 706 | @group |
51d58083 GM |
707 | 3:1 varref n ; @r{Get value of @code{n} from the environment} |
708 | ; @r{and push the value on the stack.} | |
709 | 4 sub1 ; @r{Subtract 1 from top of stack.} | |
b8d4c8d0 | 710 | @end group |
b8d4c8d0 | 711 | @group |
1df7defd | 712 | 5 dup ; @r{Duplicate top of stack; i.e., copy the top} |
51d58083 GM |
713 | ; @r{of the stack and push copy onto stack.} |
714 | 6 varset n ; @r{Pop the top of the stack,} | |
715 | ; @r{and bind @code{n} to the value.} | |
716 | ||
717 | ;; @r{(In effect, the sequence @code{dup varset} copies the top of the stack} | |
718 | ;; @r{into the value of @code{n} without popping it.)} | |
b8d4c8d0 GM |
719 | @end group |
720 | ||
721 | @group | |
51d58083 GM |
722 | 7 constant 0 ; @r{Push 0 onto stack.} |
723 | 8 gtr ; @r{Pop top two values off stack,} | |
724 | ; @r{test if @var{n} is greater than 0} | |
725 | ; @r{and push result onto stack.} | |
b8d4c8d0 | 726 | @end group |
b8d4c8d0 | 727 | @group |
51d58083 GM |
728 | 9 goto-if-not-nil 1 ; @r{Goto 1 if @code{n} > 0} |
729 | ; @r{(this continues the while loop)} | |
730 | ; @r{else continue.} | |
b8d4c8d0 | 731 | @end group |
b8d4c8d0 | 732 | @group |
51d58083 | 733 | 12 varref t1 ; @r{Push value of @code{t1} onto stack.} |
c36745c6 | 734 | 13 constant current-time-string ; @r{Push @code{current-time-string}} |
51d58083 GM |
735 | ; @r{onto the top of the stack.} |
736 | 14 call 0 ; @r{Call @code{current-time-string} again.} | |
b8d4c8d0 | 737 | @end group |
b8d4c8d0 | 738 | @group |
51d58083 GM |
739 | 15 unbind 1 ; @r{Unbind @code{t1} in local environment.} |
740 | 16 list2 ; @r{Pop top two elements off stack, create a} | |
741 | ; @r{list of them, and push it onto stack.} | |
742 | 17 return ; @r{Return value of the top of stack.} | |
b8d4c8d0 GM |
743 | @end group |
744 | @end example |