Commit | Line | Data |
---|---|---|
53f60086 RS |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
b3d90e46 GM |
3 | @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2001, 2002, 2003, 2004, |
4 | @c 2005, 2006, 2007 Free Software Foundation, Inc. | |
53f60086 RS |
5 | @c See the file elisp.texi for copying conditions. |
6 | @setfilename ../info/compile | |
a9f0a989 | 7 | @node Byte Compilation, Advising Functions, Loading, Top |
53f60086 | 8 | @chapter Byte Compilation |
1db203ff | 9 | @cindex byte compilation |
53f60086 RS |
10 | @cindex byte-code |
11 | @cindex compilation | |
12 | ||
969fe9b5 | 13 | Emacs Lisp has a @dfn{compiler} that translates functions written |
53f60086 RS |
14 | in Lisp into a special representation called @dfn{byte-code} that can be |
15 | executed more efficiently. The compiler replaces Lisp function | |
16 | definitions with byte-code. When a byte-code function is called, its | |
17 | definition is evaluated by the @dfn{byte-code interpreter}. | |
18 | ||
19 | Because the byte-compiled code is evaluated by the byte-code | |
20 | interpreter, instead of being executed directly by the machine's | |
21 | hardware (as true compiled code is), byte-code is completely | |
22 | transportable from machine to machine without recompilation. It is not, | |
23 | however, as fast as true compiled code. | |
24 | ||
a9f0a989 RS |
25 | Compiling a Lisp file with the Emacs byte compiler always reads the |
26 | file as multibyte text, even if Emacs was started with @samp{--unibyte}, | |
27 | unless the file specifies otherwise. This is so that compilation gives | |
28 | results compatible with running the same file without compilation. | |
29 | @xref{Loading Non-ASCII}. | |
30 | ||
53f60086 | 31 | In general, any version of Emacs can run byte-compiled code produced |
b57bdd74 | 32 | by recent earlier versions of Emacs, but the reverse is not true. |
53f60086 | 33 | |
d7810bda RS |
34 | @vindex no-byte-compile |
35 | If you do not want a Lisp file to be compiled, ever, put a file-local | |
36 | variable binding for @code{no-byte-compile} into it, like this: | |
37 | ||
38 | @example | |
39 | ;; -*-no-byte-compile: t; -*- | |
40 | @end example | |
41 | ||
53f60086 RS |
42 | @xref{Compilation Errors}, for how to investigate errors occurring in |
43 | byte compilation. | |
44 | ||
45 | @menu | |
a0acfc98 | 46 | * Speed of Byte-Code:: An example of speedup from byte compilation. |
53f60086 | 47 | * Compilation Functions:: Byte compilation functions. |
22697dac KH |
48 | * Docs and Compilation:: Dynamic loading of documentation strings. |
49 | * Dynamic Loading:: Dynamic loading of individual functions. | |
53f60086 | 50 | * Eval During Compile:: Code to be evaluated when you compile. |
d7810bda | 51 | * Compiler Errors:: Handling compiler error messages. |
53f60086 RS |
52 | * Byte-Code Objects:: The data type used for byte-compiled functions. |
53 | * Disassembly:: Disassembling byte-code; how to read byte-code. | |
54 | @end menu | |
55 | ||
a0acfc98 RS |
56 | @node Speed of Byte-Code |
57 | @section Performance of Byte-Compiled Code | |
53f60086 RS |
58 | |
59 | A byte-compiled function is not as efficient as a primitive function | |
60 | written in C, but runs much faster than the version written in Lisp. | |
a0acfc98 | 61 | Here is an example: |
53f60086 RS |
62 | |
63 | @example | |
64 | @group | |
65 | (defun silly-loop (n) | |
66 | "Return time before and after N iterations of a loop." | |
67 | (let ((t1 (current-time-string))) | |
177c0ea7 | 68 | (while (> (setq n (1- n)) |
53f60086 RS |
69 | 0)) |
70 | (list t1 (current-time-string)))) | |
71 | @result{} silly-loop | |
72 | @end group | |
73 | ||
74 | @group | |
75 | (silly-loop 100000) | |
a0acfc98 RS |
76 | @result{} ("Fri Mar 18 17:25:57 1994" |
77 | "Fri Mar 18 17:26:28 1994") ; @r{31 seconds} | |
53f60086 RS |
78 | @end group |
79 | ||
80 | @group | |
81 | (byte-compile 'silly-loop) | |
82 | @result{} @r{[Compiled code not shown]} | |
83 | @end group | |
84 | ||
85 | @group | |
86 | (silly-loop 100000) | |
a0acfc98 RS |
87 | @result{} ("Fri Mar 18 17:26:52 1994" |
88 | "Fri Mar 18 17:26:58 1994") ; @r{6 seconds} | |
53f60086 RS |
89 | @end group |
90 | @end example | |
91 | ||
a0acfc98 RS |
92 | In this example, the interpreted code required 31 seconds to run, |
93 | whereas the byte-compiled code required 6 seconds. These results are | |
53f60086 RS |
94 | representative, but actual results will vary greatly. |
95 | ||
a0acfc98 RS |
96 | @node Compilation Functions |
97 | @comment node-name, next, previous, up | |
98 | @section The Compilation Functions | |
99 | @cindex compilation functions | |
100 | ||
101 | You can byte-compile an individual function or macro definition with | |
102 | the @code{byte-compile} function. You can compile a whole file with | |
103 | @code{byte-compile-file}, or several files with | |
104 | @code{byte-recompile-directory} or @code{batch-byte-compile}. | |
105 | ||
9e2b495b RS |
106 | The byte compiler produces error messages and warnings about each file |
107 | in a buffer called @samp{*Compile-Log*}. These report things in your | |
108 | program that suggest a problem but are not necessarily erroneous. | |
a0acfc98 RS |
109 | |
110 | @cindex macro compilation | |
969fe9b5 RS |
111 | Be careful when writing macro calls in files that you may someday |
112 | byte-compile. Macro calls are expanded when they are compiled, so the | |
113 | macros must already be defined for proper compilation. For more | |
456ced1f RS |
114 | details, see @ref{Compiling Macros}. If a program does not work the |
115 | same way when compiled as it does when interpreted, erroneous macro | |
116 | definitions are one likely cause (@pxref{Problems with Macros}). | |
b57bdd74 RS |
117 | Inline (@code{defsubst}) functions are less troublesome; if you |
118 | compile a call to such a function before its definition is known, the | |
119 | call will still work right, it will just run slower. | |
a0acfc98 RS |
120 | |
121 | Normally, compiling a file does not evaluate the file's contents or | |
bfe721d1 KH |
122 | load the file. But it does execute any @code{require} calls at top |
123 | level in the file. One way to ensure that necessary macro definitions | |
124 | are available during compilation is to require the file that defines | |
125 | them (@pxref{Named Features}). To avoid loading the macro definition files | |
126 | when someone @emph{runs} the compiled program, write | |
127 | @code{eval-when-compile} around the @code{require} calls (@pxref{Eval | |
128 | During Compile}). | |
a0acfc98 | 129 | |
53f60086 | 130 | @defun byte-compile symbol |
a0acfc98 | 131 | This function byte-compiles the function definition of @var{symbol}, |
53f60086 RS |
132 | replacing the previous definition with the compiled one. The function |
133 | definition of @var{symbol} must be the actual code for the function; | |
134 | i.e., the compiler does not follow indirection to another symbol. | |
a0acfc98 RS |
135 | @code{byte-compile} returns the new, compiled definition of |
136 | @var{symbol}. | |
137 | ||
22697dac | 138 | If @var{symbol}'s definition is a byte-code function object, |
a0acfc98 RS |
139 | @code{byte-compile} does nothing and returns @code{nil}. Lisp records |
140 | only one function definition for any symbol, and if that is already | |
141 | compiled, non-compiled code is not available anywhere. So there is no | |
142 | way to ``compile the same definition again.'' | |
53f60086 RS |
143 | |
144 | @example | |
145 | @group | |
146 | (defun factorial (integer) | |
147 | "Compute factorial of INTEGER." | |
148 | (if (= 1 integer) 1 | |
149 | (* integer (factorial (1- integer))))) | |
a0acfc98 | 150 | @result{} factorial |
53f60086 RS |
151 | @end group |
152 | ||
153 | @group | |
154 | (byte-compile 'factorial) | |
a0acfc98 | 155 | @result{} |
53f60086 RS |
156 | #[(integer) |
157 | "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207" | |
158 | [integer 1 * factorial] | |
159 | 4 "Compute factorial of INTEGER."] | |
160 | @end group | |
161 | @end example | |
162 | ||
163 | @noindent | |
a0acfc98 RS |
164 | The result is a byte-code function object. The string it contains is |
165 | the actual byte-code; each character in it is an instruction or an | |
166 | operand of an instruction. The vector contains all the constants, | |
167 | variable names and function names used by the function, except for | |
168 | certain primitives that are coded as special instructions. | |
76865de3 RS |
169 | |
170 | If the argument to @code{byte-compile} is a @code{lambda} expression, | |
171 | it returns the corresponding compiled code, but does not store | |
172 | it anywhere. | |
53f60086 RS |
173 | @end defun |
174 | ||
e75c1a57 | 175 | @deffn Command compile-defun &optional arg |
53f60086 RS |
176 | This command reads the defun containing point, compiles it, and |
177 | evaluates the result. If you use this on a defun that is actually a | |
178 | function definition, the effect is to install a compiled version of that | |
179 | function. | |
e75c1a57 LT |
180 | |
181 | @code{compile-defun} normally displays the result of evaluation in the | |
182 | echo area, but if @var{arg} is non-@code{nil}, it inserts the result | |
183 | in the current buffer after the form it compiled. | |
53f60086 RS |
184 | @end deffn |
185 | ||
e75c1a57 | 186 | @deffn Command byte-compile-file filename &optional load |
a9f0a989 RS |
187 | This function compiles a file of Lisp code named @var{filename} into a |
188 | file of byte-code. The output file's name is made by changing the | |
189 | @samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in | |
190 | @samp{.el}, it adds @samp{.elc} to the end of @var{filename}. | |
53f60086 | 191 | |
a0acfc98 | 192 | Compilation works by reading the input file one form at a time. If it |
53f60086 RS |
193 | is a definition of a function or macro, the compiled function or macro |
194 | definition is written out. Other forms are batched together, then each | |
195 | batch is compiled, and written so that its compiled code will be | |
196 | executed when the file is read. All comments are discarded when the | |
197 | input file is read. | |
198 | ||
e75c1a57 LT |
199 | This command returns @code{t} if there were no errors and @code{nil} |
200 | otherwise. When called interactively, it prompts for the file name. | |
201 | ||
202 | If @var{load} is non-@code{nil}, this command loads the compiled file | |
203 | after compiling it. Interactively, @var{load} is the prefix argument. | |
53f60086 RS |
204 | |
205 | @example | |
206 | @group | |
207 | % ls -l push* | |
208 | -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el | |
209 | @end group | |
210 | ||
211 | @group | |
212 | (byte-compile-file "~/emacs/push.el") | |
213 | @result{} t | |
214 | @end group | |
215 | ||
216 | @group | |
217 | % ls -l push* | |
218 | -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el | |
219 | -rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc | |
220 | @end group | |
221 | @end example | |
222 | @end deffn | |
223 | ||
e75c1a57 | 224 | @deffn Command byte-recompile-directory directory &optional flag force |
53f60086 | 225 | @cindex library compilation |
e75c1a57 LT |
226 | This command recompiles every @samp{.el} file in @var{directory} (or |
227 | its subdirectories) that needs recompilation. A file needs | |
228 | recompilation if a @samp{.elc} file exists but is older than the | |
229 | @samp{.el} file. | |
230 | ||
231 | When a @samp{.el} file has no corresponding @samp{.elc} file, | |
232 | @var{flag} says what to do. If it is @code{nil}, this command ignores | |
233 | these files. If @var{flag} is 0, it compiles them. If it is neither | |
76865de3 RS |
234 | @code{nil} nor 0, it asks the user whether to compile each such file, |
235 | and asks about each subdirectory as well. | |
53f60086 | 236 | |
e75c1a57 LT |
237 | Interactively, @code{byte-recompile-directory} prompts for |
238 | @var{directory} and @var{flag} is the prefix argument. | |
53f60086 | 239 | |
e75c1a57 LT |
240 | If @var{force} is non-@code{nil}, this command recompiles every |
241 | @samp{.el} file that has a @samp{.elc} file. | |
242 | ||
243 | The returned value is unpredictable. | |
53f60086 RS |
244 | @end deffn |
245 | ||
e75c1a57 | 246 | @defun batch-byte-compile &optional noforce |
a0acfc98 RS |
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 | |
f9f59935 RS |
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 | |
252 | status code. | |
53f60086 | 253 | |
e75c1a57 LT |
254 | If @var{noforce} is non-@code{nil}, this function does not recompile |
255 | files that have an up-to-date @samp{.elc} file. | |
256 | ||
53f60086 RS |
257 | @example |
258 | % emacs -batch -f batch-byte-compile *.el | |
259 | @end example | |
260 | @end defun | |
261 | ||
262 | @defun byte-code code-string data-vector max-stack | |
263 | @cindex byte-code interpreter | |
a0acfc98 | 264 | This function actually interprets byte-code. A byte-compiled function |
53f60086 | 265 | is actually defined with a body that calls @code{byte-code}. Don't call |
969fe9b5 | 266 | this function yourself---only the byte compiler knows how to generate |
53f60086 RS |
267 | valid calls to this function. |
268 | ||
969fe9b5 RS |
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}. | |
53f60086 RS |
273 | @end defun |
274 | ||
22697dac KH |
275 | @node Docs and Compilation |
276 | @section Documentation Strings and Compilation | |
277 | @cindex dynamic loading of documentation | |
278 | ||
279 | Functions and variables loaded from a byte-compiled file access their | |
280 | documentation strings dynamically from the file whenever needed. This | |
cc8c51f1 | 281 | saves space within Emacs, and makes loading faster because the |
22697dac KH |
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. | |
285 | ||
286 | Dynamic access to documentation strings does have drawbacks: | |
287 | ||
288 | @itemize @bullet | |
289 | @item | |
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 | |
292 | in the file. | |
293 | ||
294 | @item | |
295 | If you alter the compiled file (such as by compiling a new version), | |
76865de3 RS |
296 | then further access to documentation strings in this file will |
297 | probably give nonsense results. | |
22697dac KH |
298 | @end itemize |
299 | ||
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 | |
304 | expected to be. | |
305 | ||
89dbfd18 | 306 | However, if you have built Emacs yourself and use it from the |
22697dac KH |
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. | |
310 | ||
b57bdd74 RS |
311 | You can turn off this feature at compile time by setting |
312 | @code{byte-compile-dynamic-docstrings} to @code{nil}; this is useful | |
313 | mainly if you expect to change the file, and you want Emacs processes | |
314 | that have already loaded it to keep working when the file changes. | |
315 | You can do this globally, or for one source file by specifying a | |
316 | file-local binding for the variable. One way to do that is by adding | |
317 | this string to the file's first line: | |
22697dac KH |
318 | |
319 | @example | |
320 | -*-byte-compile-dynamic-docstrings: nil;-*- | |
321 | @end example | |
322 | ||
323 | @defvar byte-compile-dynamic-docstrings | |
324 | If this is non-@code{nil}, the byte compiler generates compiled files | |
325 | that are set up for dynamic loading of documentation strings. | |
326 | @end defvar | |
327 | ||
328 | @cindex @samp{#@@@var{count}} | |
329 | @cindex @samp{#$} | |
330 | The dynamic documentation string feature writes compiled files that | |
331 | use a special Lisp reader construct, @samp{#@@@var{count}}. This | |
332 | construct skips the next @var{count} characters. It also uses the | |
333 | @samp{#$} construct, which stands for ``the name of this file, as a | |
969fe9b5 RS |
334 | string.'' It is usually best not to use these constructs in Lisp source |
335 | files, since they are not designed to be clear to humans reading the | |
336 | file. | |
22697dac KH |
337 | |
338 | @node Dynamic Loading | |
339 | @section Dynamic Loading of Individual Functions | |
340 | ||
341 | @cindex dynamic loading of functions | |
342 | @cindex lazy loading | |
343 | When you compile a file, you can optionally enable the @dfn{dynamic | |
344 | function loading} feature (also known as @dfn{lazy loading}). With | |
345 | dynamic function loading, loading the file doesn't fully read the | |
346 | function definitions in the file. Instead, each function definition | |
347 | contains a place-holder which refers to the file. The first time each | |
348 | function is called, it reads the full definition from the file, to | |
349 | replace the place-holder. | |
350 | ||
351 | The advantage of dynamic function loading is that loading the file | |
352 | becomes much faster. This is a good thing for a file which contains | |
969fe9b5 RS |
353 | many separate user-callable functions, if using one of them does not |
354 | imply you will probably also use the rest. A specialized mode which | |
355 | provides many keyboard commands often has that usage pattern: a user may | |
356 | invoke the mode, but use only a few of the commands it provides. | |
22697dac KH |
357 | |
358 | The dynamic loading feature has certain disadvantages: | |
359 | ||
360 | @itemize @bullet | |
361 | @item | |
362 | If you delete or move the compiled file after loading it, Emacs can no | |
363 | longer load the remaining function definitions not already loaded. | |
364 | ||
365 | @item | |
366 | If you alter the compiled file (such as by compiling a new version), | |
76865de3 RS |
367 | then trying to load any function not already loaded will usually yield |
368 | nonsense results. | |
22697dac KH |
369 | @end itemize |
370 | ||
969fe9b5 RS |
371 | These problems will never happen in normal circumstances with |
372 | installed Emacs files. But they are quite likely to happen with Lisp | |
373 | files that you are changing. The easiest way to prevent these problems | |
374 | is to reload the new compiled file immediately after each recompilation. | |
22697dac KH |
375 | |
376 | The byte compiler uses the dynamic function loading feature if the | |
377 | variable @code{byte-compile-dynamic} is non-@code{nil} at compilation | |
378 | time. Do not set this variable globally, since dynamic loading is | |
379 | desirable only for certain files. Instead, enable the feature for | |
969fe9b5 RS |
380 | specific source files with file-local variable bindings. For example, |
381 | you could do it by writing this text in the source file's first line: | |
22697dac KH |
382 | |
383 | @example | |
384 | -*-byte-compile-dynamic: t;-*- | |
385 | @end example | |
386 | ||
387 | @defvar byte-compile-dynamic | |
388 | If this is non-@code{nil}, the byte compiler generates compiled files | |
389 | that are set up for dynamic function loading. | |
390 | @end defvar | |
391 | ||
392 | @defun fetch-bytecode function | |
76865de3 RS |
393 | If @var{function} is a byte-code function object, this immediately |
394 | finishes loading the byte code of @var{function} from its | |
395 | byte-compiled file, if it is not fully loaded already. Otherwise, | |
396 | it does nothing. It always returns @var{function}. | |
22697dac KH |
397 | @end defun |
398 | ||
53f60086 RS |
399 | @node Eval During Compile |
400 | @section Evaluation During Compilation | |
401 | ||
22697dac | 402 | These features permit you to write code to be evaluated during |
53f60086 RS |
403 | compilation of a program. |
404 | ||
3fa2da7a | 405 | @defspec eval-and-compile body@dots{} |
53f60086 RS |
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). | |
408 | ||
409 | You can get a similar result by putting @var{body} in a separate file | |
969fe9b5 | 410 | and referring to that file with @code{require}. That method is |
185d95fc RS |
411 | preferable when @var{body} is large. Effectively @code{require} is |
412 | automatically @code{eval-and-compile}, the package is loaded both when | |
413 | compiling and executing. | |
414 | ||
415 | @code{autoload} is also effectively @code{eval-and-compile} too. It's | |
5a36d834 | 416 | recognized when compiling, so uses of such a function don't produce |
185d95fc RS |
417 | ``not known to be defined'' warnings. |
418 | ||
419 | Most uses of @code{eval-and-compile} are fairly sophisticated. | |
420 | ||
421 | If a macro has a helper function to build its result, and that macro | |
422 | is used both locally and outside the package, then | |
423 | @code{eval-and-compile} should be used to get the helper both when | |
424 | compiling and then later when running. | |
425 | ||
426 | If functions are defined programmatically (with @code{fset} say), then | |
427 | @code{eval-and-compile} can be used to have that done at compile-time | |
428 | as well as run-time, so calls to those functions are checked (and | |
429 | warnings about ``not known to be defined'' suppressed). | |
53f60086 RS |
430 | @end defspec |
431 | ||
3fa2da7a | 432 | @defspec eval-when-compile body@dots{} |
f9f59935 | 433 | This form marks @var{body} to be evaluated at compile time but not when |
78c71a98 | 434 | the compiled program is loaded. The result of evaluation by the |
f9f59935 RS |
435 | compiler becomes a constant which appears in the compiled program. If |
436 | you load the source file, rather than compiling it, @var{body} is | |
437 | evaluated normally. | |
53f60086 | 438 | |
4469ed01 | 439 | @cindex compile-time constant |
185d95fc | 440 | If you have a constant that needs some calculation to produce, |
4469ed01 | 441 | @code{eval-when-compile} can do that at compile-time. For example, |
185d95fc RS |
442 | |
443 | @lisp | |
444 | (defvar my-regexp | |
445 | (eval-when-compile (regexp-opt '("aaa" "aba" "abb")))) | |
446 | @end lisp | |
447 | ||
4469ed01 | 448 | @cindex macros, at compile time |
185d95fc RS |
449 | If you're using another package, but only need macros from it (the |
450 | byte compiler will expand those), then @code{eval-when-compile} can be | |
451 | used to load it for compiling, but not executing. For example, | |
452 | ||
453 | @lisp | |
454 | (eval-when-compile | |
455 | (require 'my-macro-package)) ;; only macros needed from this | |
456 | @end lisp | |
457 | ||
0c47ccd4 RS |
458 | The same sort of thing goes for macros and @code{defsubst} functions |
459 | defined locally and only for use within the file. They are needed for | |
460 | compiling the file, but in most cases they are not needed for | |
461 | execution of the compiled file. For example, | |
185d95fc RS |
462 | |
463 | @lisp | |
464 | (eval-when-compile | |
465 | (unless (fboundp 'some-new-thing) | |
466 | (defmacro 'some-new-thing () | |
467 | (compatibility code)))) | |
468 | @end lisp | |
469 | ||
0c47ccd4 RS |
470 | @noindent |
471 | This is often good for code that's only a fallback for compatibility | |
472 | with other versions of Emacs. | |
473 | ||
185d95fc | 474 | @strong{Common Lisp Note:} At top level, @code{eval-when-compile} is analogous to the Common |
969fe9b5 RS |
475 | Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the |
476 | Common Lisp @samp{#.} reader macro (but not when interpreting) is closer | |
477 | to what @code{eval-when-compile} does. | |
53f60086 RS |
478 | @end defspec |
479 | ||
d7810bda RS |
480 | @node Compiler Errors |
481 | @section Compiler Errors | |
482 | @cindex compiler errors | |
483 | ||
342fd6cd | 484 | Byte compilation outputs all errors and warnings into the buffer |
d7810bda RS |
485 | @samp{*Compile-Log*}. The messages include file names and line |
486 | numbers that identify the location of the problem. The usual Emacs | |
487 | commands for operating on compiler diagnostics work properly on | |
488 | these messages. | |
489 | ||
490 | However, the warnings about functions that were used but not | |
491 | defined are always ``located'' at the end of the file, so these | |
492 | commands won't find the places they are really used. To do that, | |
493 | you must search for the function names. | |
e75c1a57 | 494 | |
fe45b975 | 495 | You can suppress the compiler warning for calling an undefined |
76865de3 | 496 | function @var{func} by conditionalizing the function call on an |
fe45b975 RS |
497 | @code{fboundp} test, like this: |
498 | ||
499 | @example | |
500 | (if (fboundp '@var{func}) ...(@var{func} ...)...) | |
501 | @end example | |
502 | ||
503 | @noindent | |
5c5114b7 RS |
504 | The call to @var{func} must be in the @var{then-form} of the |
505 | @code{if}, and @var{func} must appear quoted in the call to | |
506 | @code{fboundp}. (This feature operates for @code{cond} as well.) | |
507 | ||
508 | Likewise, you can suppress a compiler warning for an unbound variable | |
fe45b975 RS |
509 | @var{variable} by conditionalizing its use on a @code{boundp} test, |
510 | like this: | |
511 | ||
512 | @example | |
513 | (if (boundp '@var{variable}) ...@var{variable}...) | |
514 | @end example | |
515 | ||
516 | @noindent | |
517 | The reference to @var{variable} must be in the @var{then-form} of the | |
518 | @code{if}, and @var{variable} must appear quoted in the call to | |
519 | @code{boundp}. | |
520 | ||
521 | You can suppress any compiler warnings using the construct | |
522 | @code{with-no-warnings}: | |
523 | ||
76865de3 RS |
524 | @c This is implemented with a defun, but conceptually it is |
525 | @c a special form. | |
526 | ||
3fa2da7a | 527 | @defspec with-no-warnings body@dots{} |
fe45b975 RS |
528 | In execution, this is equivalent to @code{(progn @var{body}...)}, |
529 | but the compiler does not issue warnings for anything that occurs | |
530 | inside @var{body}. | |
531 | ||
532 | We recommend that you use this construct around the smallest | |
533 | possible piece of code. | |
76865de3 | 534 | @end defspec |
fe45b975 | 535 | |
53f60086 | 536 | @node Byte-Code Objects |
bfe721d1 | 537 | @section Byte-Code Function Objects |
53f60086 RS |
538 | @cindex compiled function |
539 | @cindex byte-code function | |
540 | ||
541 | Byte-compiled functions have a special data type: they are | |
542 | @dfn{byte-code function objects}. | |
543 | ||
544 | Internally, a byte-code function object is much like a vector; | |
545 | however, the evaluator handles this data type specially when it appears | |
546 | as a function to be called. The printed representation for a byte-code | |
547 | function object is like that for a vector, with an additional @samp{#} | |
548 | before the opening @samp{[}. | |
549 | ||
53f60086 | 550 | A byte-code function object must have at least four elements; there is |
969fe9b5 | 551 | no maximum number, but only the first six elements have any normal use. |
53f60086 RS |
552 | They are: |
553 | ||
554 | @table @var | |
555 | @item arglist | |
556 | The list of argument symbols. | |
557 | ||
558 | @item byte-code | |
559 | The string containing the byte-code instructions. | |
560 | ||
561 | @item constants | |
78c71a98 RS |
562 | The vector of Lisp objects referenced by the byte code. These include |
563 | symbols used as function names and variable names. | |
53f60086 RS |
564 | |
565 | @item stacksize | |
566 | The maximum stack size this function needs. | |
567 | ||
568 | @item docstring | |
bfe721d1 KH |
569 | The documentation string (if any); otherwise, @code{nil}. The value may |
570 | be a number or a list, in case the documentation string is stored in a | |
571 | file. Use the function @code{documentation} to get the real | |
572 | documentation string (@pxref{Accessing Documentation}). | |
53f60086 RS |
573 | |
574 | @item interactive | |
575 | The interactive spec (if any). This can be a string or a Lisp | |
576 | expression. It is @code{nil} for a function that isn't interactive. | |
577 | @end table | |
578 | ||
579 | Here's an example of a byte-code function object, in printed | |
580 | representation. It is the definition of the command | |
581 | @code{backward-sexp}. | |
582 | ||
583 | @example | |
584 | #[(&optional arg) | |
585 | "^H\204^F^@@\301^P\302^H[!\207" | |
586 | [arg 1 forward-sexp] | |
587 | 2 | |
588 | 254435 | |
589 | "p"] | |
590 | @end example | |
591 | ||
592 | The primitive way to create a byte-code object is with | |
593 | @code{make-byte-code}: | |
594 | ||
595 | @defun make-byte-code &rest elements | |
596 | This function constructs and returns a byte-code function object | |
597 | with @var{elements} as its elements. | |
598 | @end defun | |
599 | ||
a0acfc98 RS |
600 | You should not try to come up with the elements for a byte-code |
601 | function yourself, because if they are inconsistent, Emacs may crash | |
78c71a98 | 602 | when you call the function. Always leave it to the byte compiler to |
a0acfc98 | 603 | create these objects; it makes the elements consistent (we hope). |
53f60086 RS |
604 | |
605 | You can access the elements of a byte-code object using @code{aref}; | |
606 | you can also use @code{vconcat} to create a vector with the same | |
607 | elements. | |
608 | ||
609 | @node Disassembly | |
610 | @section Disassembled Byte-Code | |
611 | @cindex disassembled byte-code | |
612 | ||
613 | People do not write byte-code; that job is left to the byte compiler. | |
614 | But we provide a disassembler to satisfy a cat-like curiosity. The | |
615 | disassembler converts the byte-compiled code into humanly readable | |
616 | form. | |
617 | ||
618 | The byte-code interpreter is implemented as a simple stack machine. | |
a0acfc98 | 619 | It pushes values onto a stack of its own, then pops them off to use them |
78c71a98 RS |
620 | in calculations whose results are themselves pushed back on the stack. |
621 | When a byte-code function returns, it pops a value off the stack and | |
622 | returns it as the value of the function. | |
53f60086 | 623 | |
78c71a98 | 624 | In addition to the stack, byte-code functions can use, bind, and set |
a0acfc98 RS |
625 | ordinary Lisp variables, by transferring values between variables and |
626 | the stack. | |
53f60086 | 627 | |
e75c1a57 LT |
628 | @deffn Command disassemble object &optional buffer-or-name |
629 | This command displays the disassembled code for @var{object}. In | |
630 | interactive use, or if @var{buffer-or-name} is @code{nil} or omitted, | |
631 | the output goes in a buffer named @samp{*Disassemble*}. If | |
632 | @var{buffer-or-name} is non-@code{nil}, it must be a buffer or the | |
633 | name of an existing buffer. Then the output goes there, at point, and | |
634 | point is left before the output. | |
53f60086 | 635 | |
e75c1a57 | 636 | The argument @var{object} can be a function name, a lambda expression |
76865de3 RS |
637 | or a byte-code object. If it is a lambda expression, @code{disassemble} |
638 | compiles it and disassembles the resulting compiled code. | |
53f60086 RS |
639 | @end deffn |
640 | ||
641 | Here are two examples of using the @code{disassemble} function. We | |
642 | have added explanatory comments to help you relate the byte-code to the | |
643 | Lisp source; these do not appear in the output of @code{disassemble}. | |
644 | These examples show unoptimized byte-code. Nowadays byte-code is | |
645 | usually optimized, but we did not want to rewrite these examples, since | |
646 | they still serve their purpose. | |
647 | ||
648 | @example | |
649 | @group | |
650 | (defun factorial (integer) | |
651 | "Compute factorial of an integer." | |
652 | (if (= 1 integer) 1 | |
653 | (* integer (factorial (1- integer))))) | |
654 | @result{} factorial | |
655 | @end group | |
656 | ||
657 | @group | |
658 | (factorial 4) | |
659 | @result{} 24 | |
660 | @end group | |
661 | ||
662 | @group | |
663 | (disassemble 'factorial) | |
664 | @print{} byte-code for factorial: | |
665 | doc: Compute factorial of an integer. | |
666 | args: (integer) | |
667 | @end group | |
668 | ||
669 | @group | |
670 | 0 constant 1 ; @r{Push 1 onto stack.} | |
671 | ||
177c0ea7 | 672 | 1 varref integer ; @r{Get value of @code{integer}} |
53f60086 RS |
673 | ; @r{from the environment} |
674 | ; @r{and push the value} | |
675 | ; @r{onto the stack.} | |
676 | @end group | |
677 | ||
678 | @group | |
679 | 2 eqlsign ; @r{Pop top two values off stack,} | |
680 | ; @r{compare them,} | |
681 | ; @r{and push result onto stack.} | |
682 | @end group | |
683 | ||
684 | @group | |
685 | 3 goto-if-nil 10 ; @r{Pop and test top of stack;} | |
686 | ; @r{if @code{nil}, go to 10,} | |
687 | ; @r{else continue.} | |
688 | @end group | |
689 | ||
690 | @group | |
691 | 6 constant 1 ; @r{Push 1 onto top of stack.} | |
692 | ||
693 | 7 goto 17 ; @r{Go to 17 (in this case, 1 will be} | |
694 | ; @r{returned by the function).} | |
695 | @end group | |
696 | ||
697 | @group | |
698 | 10 constant * ; @r{Push symbol @code{*} onto stack.} | |
699 | ||
700 | 11 varref integer ; @r{Push value of @code{integer} onto stack.} | |
701 | @end group | |
702 | ||
703 | @group | |
704 | 12 constant factorial ; @r{Push @code{factorial} onto stack.} | |
705 | ||
706 | 13 varref integer ; @r{Push value of @code{integer} onto stack.} | |
707 | ||
708 | 14 sub1 ; @r{Pop @code{integer}, decrement value,} | |
709 | ; @r{push new value onto stack.} | |
710 | @end group | |
711 | ||
712 | @group | |
713 | ; @r{Stack now contains:} | |
714 | ; @minus{} @r{decremented value of @code{integer}} | |
177c0ea7 | 715 | ; @minus{} @r{@code{factorial}} |
53f60086 RS |
716 | ; @minus{} @r{value of @code{integer}} |
717 | ; @minus{} @r{@code{*}} | |
718 | @end group | |
719 | ||
720 | @group | |
721 | 15 call 1 ; @r{Call function @code{factorial} using} | |
722 | ; @r{the first (i.e., the top) element} | |
723 | ; @r{of the stack as the argument;} | |
724 | ; @r{push returned value onto stack.} | |
725 | @end group | |
726 | ||
727 | @group | |
728 | ; @r{Stack now contains:} | |
78c71a98 | 729 | ; @minus{} @r{result of recursive} |
53f60086 RS |
730 | ; @r{call to @code{factorial}} |
731 | ; @minus{} @r{value of @code{integer}} | |
732 | ; @minus{} @r{@code{*}} | |
733 | @end group | |
734 | ||
735 | @group | |
736 | 16 call 2 ; @r{Using the first two} | |
737 | ; @r{(i.e., the top two)} | |
738 | ; @r{elements of the stack} | |
739 | ; @r{as arguments,} | |
740 | ; @r{call the function @code{*},} | |
741 | ; @r{pushing the result onto the stack.} | |
742 | @end group | |
743 | ||
744 | @group | |
745 | 17 return ; @r{Return the top element} | |
746 | ; @r{of the stack.} | |
747 | @result{} nil | |
748 | @end group | |
749 | @end example | |
750 | ||
751 | The @code{silly-loop} function is somewhat more complex: | |
752 | ||
753 | @example | |
754 | @group | |
755 | (defun silly-loop (n) | |
756 | "Return time before and after N iterations of a loop." | |
757 | (let ((t1 (current-time-string))) | |
177c0ea7 | 758 | (while (> (setq n (1- n)) |
53f60086 RS |
759 | 0)) |
760 | (list t1 (current-time-string)))) | |
761 | @result{} silly-loop | |
762 | @end group | |
763 | ||
764 | @group | |
765 | (disassemble 'silly-loop) | |
766 | @print{} byte-code for silly-loop: | |
767 | doc: Return time before and after N iterations of a loop. | |
768 | args: (n) | |
769 | ||
770 | 0 constant current-time-string ; @r{Push} | |
771 | ; @r{@code{current-time-string}} | |
772 | ; @r{onto top of stack.} | |
773 | @end group | |
774 | ||
775 | @group | |
776 | 1 call 0 ; @r{Call @code{current-time-string}} | |
777 | ; @r{ with no argument,} | |
778 | ; @r{ pushing result onto stack.} | |
779 | @end group | |
780 | ||
781 | @group | |
782 | 2 varbind t1 ; @r{Pop stack and bind @code{t1}} | |
783 | ; @r{to popped value.} | |
784 | @end group | |
785 | ||
786 | @group | |
787 | 3 varref n ; @r{Get value of @code{n} from} | |
788 | ; @r{the environment and push} | |
789 | ; @r{the value onto the stack.} | |
790 | @end group | |
791 | ||
792 | @group | |
793 | 4 sub1 ; @r{Subtract 1 from top of stack.} | |
794 | @end group | |
795 | ||
796 | @group | |
797 | 5 dup ; @r{Duplicate the top of the stack;} | |
a0acfc98 | 798 | ; @r{i.e., copy the top of} |
53f60086 RS |
799 | ; @r{the stack and push the} |
800 | ; @r{copy onto the stack.} | |
801 | @end group | |
802 | ||
803 | @group | |
804 | 6 varset n ; @r{Pop the top of the stack,} | |
805 | ; @r{and bind @code{n} to the value.} | |
806 | ||
807 | ; @r{In effect, the sequence @code{dup varset}} | |
808 | ; @r{copies the top of the stack} | |
809 | ; @r{into the value of @code{n}} | |
810 | ; @r{without popping it.} | |
811 | @end group | |
812 | ||
813 | @group | |
814 | 7 constant 0 ; @r{Push 0 onto stack.} | |
815 | @end group | |
816 | ||
817 | @group | |
818 | 8 gtr ; @r{Pop top two values off stack,} | |
819 | ; @r{test if @var{n} is greater than 0} | |
820 | ; @r{and push result onto stack.} | |
821 | @end group | |
822 | ||
823 | @group | |
78c71a98 RS |
824 | 9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0} |
825 | ; @r{(this exits the while loop).} | |
53f60086 RS |
826 | ; @r{else pop top of stack} |
827 | ; @r{and continue} | |
53f60086 RS |
828 | @end group |
829 | ||
830 | @group | |
831 | 12 constant nil ; @r{Push @code{nil} onto stack} | |
832 | ; @r{(this is the body of the loop).} | |
833 | @end group | |
834 | ||
835 | @group | |
836 | 13 discard ; @r{Discard result of the body} | |
837 | ; @r{of the loop (a while loop} | |
838 | ; @r{is always evaluated for} | |
839 | ; @r{its side effects).} | |
840 | @end group | |
841 | ||
842 | @group | |
843 | 14 goto 3 ; @r{Jump back to beginning} | |
844 | ; @r{of while loop.} | |
845 | @end group | |
846 | ||
847 | @group | |
848 | 17 discard ; @r{Discard result of while loop} | |
849 | ; @r{by popping top of stack.} | |
78c71a98 RS |
850 | ; @r{This result is the value @code{nil} that} |
851 | ; @r{was not popped by the goto at 9.} | |
53f60086 RS |
852 | @end group |
853 | ||
854 | @group | |
855 | 18 varref t1 ; @r{Push value of @code{t1} onto stack.} | |
856 | @end group | |
857 | ||
858 | @group | |
177c0ea7 | 859 | 19 constant current-time-string ; @r{Push} |
53f60086 RS |
860 | ; @r{@code{current-time-string}} |
861 | ; @r{onto top of stack.} | |
862 | @end group | |
863 | ||
864 | @group | |
865 | 20 call 0 ; @r{Call @code{current-time-string} again.} | |
866 | @end group | |
867 | ||
868 | @group | |
869 | 21 list2 ; @r{Pop top two elements off stack,} | |
870 | ; @r{create a list of them,} | |
871 | ; @r{and push list onto stack.} | |
872 | @end group | |
873 | ||
874 | @group | |
875 | 22 unbind 1 ; @r{Unbind @code{t1} in local environment.} | |
876 | ||
877 | 23 return ; @r{Return value of the top of stack.} | |
878 | ||
879 | @result{} nil | |
880 | @end group | |
881 | @end example | |
882 | ||
883 | ||
ab5796a9 MB |
884 | @ignore |
885 | arch-tag: f78e3050-2f0a-4dee-be27-d9979a0a2289 | |
886 | @end ignore |