Mercurial > emacs
annotate doc/lispref/compile.texi @ 97774:cf6404e22e31
*** empty log message ***
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Wed, 27 Aug 2008 20:21:31 +0000 |
parents | 107ccd98fa12 |
children | cb5d2387102c |
rev | line source |
---|---|
84054 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2001, 2002, 2003, 2004, | |
87649 | 4 @c 2005, 2006, 2007, 2008 Free Software Foundation, Inc. |
84054 | 5 @c See the file elisp.texi for copying conditions. |
84116
0ba80d073e27
(setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents:
84054
diff
changeset
|
6 @setfilename ../../info/compile |
84054 | 7 @node Byte Compilation, Advising Functions, Loading, Top |
8 @chapter Byte Compilation | |
9 @cindex byte compilation | |
10 @cindex byte-code | |
11 @cindex compilation (Emacs Lisp) | |
12 | |
13 Emacs Lisp has a @dfn{compiler} that translates functions written | |
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 | |
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 | |
31 In general, any version of Emacs can run byte-compiled code produced | |
32 by recent earlier versions of Emacs, but the reverse is not true. | |
33 | |
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 | |
42 @xref{Compilation Errors}, for how to investigate errors occurring in | |
43 byte compilation. | |
44 | |
45 @menu | |
46 * Speed of Byte-Code:: An example of speedup from byte compilation. | |
47 * Compilation Functions:: Byte compilation functions. | |
48 * Docs and Compilation:: Dynamic loading of documentation strings. | |
49 * Dynamic Loading:: Dynamic loading of individual functions. | |
50 * Eval During Compile:: Code to be evaluated when you compile. | |
51 * Compiler Errors:: Handling compiler error messages. | |
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 | |
56 @node Speed of Byte-Code | |
57 @section Performance of Byte-Compiled Code | |
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. | |
61 Here is an example: | |
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))) | |
68 (while (> (setq n (1- n)) | |
69 0)) | |
70 (list t1 (current-time-string)))) | |
71 @result{} silly-loop | |
72 @end group | |
73 | |
74 @group | |
75 (silly-loop 100000) | |
76 @result{} ("Fri Mar 18 17:25:57 1994" | |
77 "Fri Mar 18 17:26:28 1994") ; @r{31 seconds} | |
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) | |
87 @result{} ("Fri Mar 18 17:26:52 1994" | |
88 "Fri Mar 18 17:26:58 1994") ; @r{6 seconds} | |
89 @end group | |
90 @end example | |
91 | |
92 In this example, the interpreted code required 31 seconds to run, | |
93 whereas the byte-compiled code required 6 seconds. These results are | |
94 representative, but actual results will vary greatly. | |
95 | |
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 | |
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. | |
109 | |
110 @cindex macro compilation | |
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 | |
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}). | |
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. | |
120 | |
121 Normally, compiling a file does not evaluate the file's contents or | |
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}). | |
129 | |
130 @defun byte-compile symbol | |
131 This function byte-compiles the function definition of @var{symbol}, | |
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. | |
135 @code{byte-compile} returns the new, compiled definition of | |
136 @var{symbol}. | |
137 | |
138 If @var{symbol}'s definition is a byte-code function object, | |
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.'' | |
143 | |
144 @example | |
145 @group | |
146 (defun factorial (integer) | |
147 "Compute factorial of INTEGER." | |
148 (if (= 1 integer) 1 | |
149 (* integer (factorial (1- integer))))) | |
150 @result{} factorial | |
151 @end group | |
152 | |
153 @group | |
154 (byte-compile 'factorial) | |
155 @result{} | |
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 | |
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. | |
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. | |
173 @end defun | |
174 | |
175 @deffn Command compile-defun &optional arg | |
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. | |
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. | |
184 @end deffn | |
185 | |
186 @deffn Command byte-compile-file filename &optional load | |
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}. | |
191 | |
192 Compilation works by reading the input file one form at a time. If it | |
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 | |
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. | |
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 | |
224 @deffn Command byte-recompile-directory directory &optional flag force | |
225 @cindex library compilation | |
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 | |
234 @code{nil} nor 0, it asks the user whether to compile each such file, | |
235 and asks about each subdirectory as well. | |
236 | |
237 Interactively, @code{byte-recompile-directory} prompts for | |
238 @var{directory} and @var{flag} is the prefix argument. | |
239 | |
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. | |
244 @end deffn | |
245 | |
246 @defun batch-byte-compile &optional noforce | |
247 This function runs @code{byte-compile-file} on files specified on the | |
248 command line. This function must be used only in a batch execution of | |
249 Emacs, as it kills Emacs on completion. An error in one file does not | |
250 prevent processing of subsequent files, but no output file will be | |
251 generated for it, and the Emacs process will terminate with a nonzero | |
252 status code. | |
253 | |
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 | |
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 | |
264 This function actually interprets byte-code. A byte-compiled function | |
265 is actually defined with a body that calls @code{byte-code}. Don't call | |
266 this function yourself---only the byte compiler knows how to generate | |
267 valid calls to this function. | |
268 | |
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}. | |
273 @end defun | |
274 | |
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 | |
281 saves space within Emacs, and makes loading faster because the | |
282 documentation strings themselves need not be processed while loading the | |
283 file. Actual access to the documentation strings becomes slower as a | |
284 result, but this normally is not enough to bother users. | |
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), | |
296 then further access to documentation strings in this file will | |
297 probably give nonsense results. | |
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 | |
306 However, if you have built Emacs yourself and use it from the | |
307 directory where you built it, you will experience this problem | |
308 occasionally if you edit and recompile Lisp files. When it happens, you | |
309 can cure the problem by reloading the file after recompiling it. | |
310 | |
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: | |
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 | |
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. | |
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 | |
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. | |
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), | |
367 then trying to load any function not already loaded will usually yield | |
368 nonsense results. | |
369 @end itemize | |
370 | |
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. | |
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 | |
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: | |
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 | |
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}. | |
397 @end defun | |
398 | |
399 @node Eval During Compile | |
400 @section Evaluation During Compilation | |
401 | |
402 These features permit you to write code to be evaluated during | |
403 compilation of a program. | |
404 | |
405 @defspec eval-and-compile body@dots{} | |
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 | |
410 and referring to that file with @code{require}. That method is | |
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 | |
416 recognized when compiling, so uses of such a function don't produce | |
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). | |
430 @end defspec | |
431 | |
432 @defspec eval-when-compile body@dots{} | |
433 This form marks @var{body} to be evaluated at compile time but not when | |
434 the compiled program is loaded. The result of evaluation by the | |
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. | |
438 | |
439 @cindex compile-time constant | |
440 If you have a constant that needs some calculation to produce, | |
441 @code{eval-when-compile} can do that at compile-time. For example, | |
442 | |
443 @lisp | |
444 (defvar my-regexp | |
445 (eval-when-compile (regexp-opt '("aaa" "aba" "abb")))) | |
446 @end lisp | |
447 | |
448 @cindex macros, at compile time | |
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 | |
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, | |
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 | |
470 @noindent | |
471 This is often good for code that's only a fallback for compatibility | |
472 with other versions of Emacs. | |
473 | |
474 @strong{Common Lisp Note:} At top level, @code{eval-when-compile} is analogous to the Common | |
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. | |
478 @end defspec | |
479 | |
480 @node Compiler Errors | |
481 @section Compiler Errors | |
482 @cindex compiler errors | |
483 | |
484 Byte compilation outputs all errors and warnings into the buffer | |
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. | |
494 | |
495 You can suppress the compiler warning for calling an undefined | |
496 function @var{func} by conditionalizing the function call on an | |
497 @code{fboundp} test, like this: | |
498 | |
499 @example | |
500 (if (fboundp '@var{func}) ...(@var{func} ...)...) | |
501 @end example | |
502 | |
503 @noindent | |
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 | |
86407
82fbd29a8553
(Compiler Errors): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents:
86384
diff
changeset
|
508 You can tell the compiler that a function is defined using |
82fbd29a8553
(Compiler Errors): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents:
86384
diff
changeset
|
509 @code{declare-function} (@pxref{Declaring Functions}). Likewise, you |
82fbd29a8553
(Compiler Errors): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents:
86384
diff
changeset
|
510 can tell the compiler that a variable is defined using @code{defvar} |
82fbd29a8553
(Compiler Errors): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents:
86384
diff
changeset
|
511 with no initial value. |
86384
cb294fc4a594
(Compiler Errors): Mention declaring functions, defvar with no
Glenn Morris <rgm@gnu.org>
parents:
84116
diff
changeset
|
512 |
86407
82fbd29a8553
(Compiler Errors): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents:
86384
diff
changeset
|
513 You can suppress the compiler warning for a specific use of an |
82fbd29a8553
(Compiler Errors): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents:
86384
diff
changeset
|
514 undefined variable @var{variable} by conditionalizing its use on a |
82fbd29a8553
(Compiler Errors): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents:
86384
diff
changeset
|
515 @code{boundp} test, like this: |
84054 | 516 |
517 @example | |
518 (if (boundp '@var{variable}) ...@var{variable}...) | |
519 @end example | |
520 | |
521 @noindent | |
522 The reference to @var{variable} must be in the @var{then-form} of the | |
523 @code{if}, and @var{variable} must appear quoted in the call to | |
524 @code{boundp}. | |
525 | |
86407
82fbd29a8553
(Compiler Errors): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents:
86384
diff
changeset
|
526 You can suppress any and all compiler warnings within a certain |
82fbd29a8553
(Compiler Errors): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents:
86384
diff
changeset
|
527 expression using the construct @code{with-no-warnings}: |
84054 | 528 |
529 @c This is implemented with a defun, but conceptually it is | |
530 @c a special form. | |
531 | |
532 @defspec with-no-warnings body@dots{} | |
533 In execution, this is equivalent to @code{(progn @var{body}...)}, | |
534 but the compiler does not issue warnings for anything that occurs | |
535 inside @var{body}. | |
536 | |
537 We recommend that you use this construct around the smallest | |
86407
82fbd29a8553
(Compiler Errors): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents:
86384
diff
changeset
|
538 possible piece of code, to avoid missing possible warnings other than one |
82fbd29a8553
(Compiler Errors): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents:
86384
diff
changeset
|
539 one you intend to suppress. |
84054 | 540 @end defspec |
541 | |
86407
82fbd29a8553
(Compiler Errors): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents:
86384
diff
changeset
|
542 More precise control of warnings is possible by setting the variable |
86384
cb294fc4a594
(Compiler Errors): Mention declaring functions, defvar with no
Glenn Morris <rgm@gnu.org>
parents:
84116
diff
changeset
|
543 @code{byte-compile-warnings}. |
cb294fc4a594
(Compiler Errors): Mention declaring functions, defvar with no
Glenn Morris <rgm@gnu.org>
parents:
84116
diff
changeset
|
544 |
84054 | 545 @node Byte-Code Objects |
546 @section Byte-Code Function Objects | |
547 @cindex compiled function | |
548 @cindex byte-code function | |
549 | |
550 Byte-compiled functions have a special data type: they are | |
551 @dfn{byte-code function objects}. | |
552 | |
553 Internally, a byte-code function object is much like a vector; | |
554 however, the evaluator handles this data type specially when it appears | |
555 as a function to be called. The printed representation for a byte-code | |
556 function object is like that for a vector, with an additional @samp{#} | |
557 before the opening @samp{[}. | |
558 | |
559 A byte-code function object must have at least four elements; there is | |
560 no maximum number, but only the first six elements have any normal use. | |
561 They are: | |
562 | |
563 @table @var | |
564 @item arglist | |
565 The list of argument symbols. | |
566 | |
567 @item byte-code | |
568 The string containing the byte-code instructions. | |
569 | |
570 @item constants | |
571 The vector of Lisp objects referenced by the byte code. These include | |
572 symbols used as function names and variable names. | |
573 | |
574 @item stacksize | |
575 The maximum stack size this function needs. | |
576 | |
577 @item docstring | |
578 The documentation string (if any); otherwise, @code{nil}. The value may | |
579 be a number or a list, in case the documentation string is stored in a | |
580 file. Use the function @code{documentation} to get the real | |
581 documentation string (@pxref{Accessing Documentation}). | |
582 | |
583 @item interactive | |
584 The interactive spec (if any). This can be a string or a Lisp | |
585 expression. It is @code{nil} for a function that isn't interactive. | |
586 @end table | |
587 | |
588 Here's an example of a byte-code function object, in printed | |
589 representation. It is the definition of the command | |
590 @code{backward-sexp}. | |
591 | |
592 @example | |
593 #[(&optional arg) | |
594 "^H\204^F^@@\301^P\302^H[!\207" | |
595 [arg 1 forward-sexp] | |
596 2 | |
597 254435 | |
598 "p"] | |
599 @end example | |
600 | |
601 The primitive way to create a byte-code object is with | |
602 @code{make-byte-code}: | |
603 | |
604 @defun make-byte-code &rest elements | |
605 This function constructs and returns a byte-code function object | |
606 with @var{elements} as its elements. | |
607 @end defun | |
608 | |
609 You should not try to come up with the elements for a byte-code | |
610 function yourself, because if they are inconsistent, Emacs may crash | |
611 when you call the function. Always leave it to the byte compiler to | |
612 create these objects; it makes the elements consistent (we hope). | |
613 | |
614 You can access the elements of a byte-code object using @code{aref}; | |
615 you can also use @code{vconcat} to create a vector with the same | |
616 elements. | |
617 | |
618 @node Disassembly | |
619 @section Disassembled Byte-Code | |
620 @cindex disassembled byte-code | |
621 | |
622 People do not write byte-code; that job is left to the byte compiler. | |
623 But we provide a disassembler to satisfy a cat-like curiosity. The | |
624 disassembler converts the byte-compiled code into humanly readable | |
625 form. | |
626 | |
627 The byte-code interpreter is implemented as a simple stack machine. | |
628 It pushes values onto a stack of its own, then pops them off to use them | |
629 in calculations whose results are themselves pushed back on the stack. | |
630 When a byte-code function returns, it pops a value off the stack and | |
631 returns it as the value of the function. | |
632 | |
633 In addition to the stack, byte-code functions can use, bind, and set | |
634 ordinary Lisp variables, by transferring values between variables and | |
635 the stack. | |
636 | |
637 @deffn Command disassemble object &optional buffer-or-name | |
638 This command displays the disassembled code for @var{object}. In | |
639 interactive use, or if @var{buffer-or-name} is @code{nil} or omitted, | |
640 the output goes in a buffer named @samp{*Disassemble*}. If | |
641 @var{buffer-or-name} is non-@code{nil}, it must be a buffer or the | |
642 name of an existing buffer. Then the output goes there, at point, and | |
643 point is left before the output. | |
644 | |
645 The argument @var{object} can be a function name, a lambda expression | |
646 or a byte-code object. If it is a lambda expression, @code{disassemble} | |
647 compiles it and disassembles the resulting compiled code. | |
648 @end deffn | |
649 | |
650 Here are two examples of using the @code{disassemble} function. We | |
651 have added explanatory comments to help you relate the byte-code to the | |
652 Lisp source; these do not appear in the output of @code{disassemble}. | |
653 These examples show unoptimized byte-code. Nowadays byte-code is | |
654 usually optimized, but we did not want to rewrite these examples, since | |
655 they still serve their purpose. | |
656 | |
657 @example | |
658 @group | |
659 (defun factorial (integer) | |
660 "Compute factorial of an integer." | |
661 (if (= 1 integer) 1 | |
662 (* integer (factorial (1- integer))))) | |
663 @result{} factorial | |
664 @end group | |
665 | |
666 @group | |
667 (factorial 4) | |
668 @result{} 24 | |
669 @end group | |
670 | |
671 @group | |
672 (disassemble 'factorial) | |
673 @print{} byte-code for factorial: | |
674 doc: Compute factorial of an integer. | |
675 args: (integer) | |
676 @end group | |
677 | |
678 @group | |
679 0 constant 1 ; @r{Push 1 onto stack.} | |
680 | |
681 1 varref integer ; @r{Get value of @code{integer}} | |
682 ; @r{from the environment} | |
683 ; @r{and push the value} | |
684 ; @r{onto the stack.} | |
685 @end group | |
686 | |
687 @group | |
688 2 eqlsign ; @r{Pop top two values off stack,} | |
689 ; @r{compare them,} | |
690 ; @r{and push result onto stack.} | |
691 @end group | |
692 | |
693 @group | |
694 3 goto-if-nil 10 ; @r{Pop and test top of stack;} | |
695 ; @r{if @code{nil}, go to 10,} | |
696 ; @r{else continue.} | |
697 @end group | |
698 | |
699 @group | |
700 6 constant 1 ; @r{Push 1 onto top of stack.} | |
701 | |
702 7 goto 17 ; @r{Go to 17 (in this case, 1 will be} | |
703 ; @r{returned by the function).} | |
704 @end group | |
705 | |
706 @group | |
707 10 constant * ; @r{Push symbol @code{*} onto stack.} | |
708 | |
709 11 varref integer ; @r{Push value of @code{integer} onto stack.} | |
710 @end group | |
711 | |
712 @group | |
713 12 constant factorial ; @r{Push @code{factorial} onto stack.} | |
714 | |
715 13 varref integer ; @r{Push value of @code{integer} onto stack.} | |
716 | |
717 14 sub1 ; @r{Pop @code{integer}, decrement value,} | |
718 ; @r{push new value onto stack.} | |
719 @end group | |
720 | |
721 @group | |
722 ; @r{Stack now contains:} | |
723 ; @minus{} @r{decremented value of @code{integer}} | |
724 ; @minus{} @r{@code{factorial}} | |
725 ; @minus{} @r{value of @code{integer}} | |
726 ; @minus{} @r{@code{*}} | |
727 @end group | |
728 | |
729 @group | |
730 15 call 1 ; @r{Call function @code{factorial} using} | |
731 ; @r{the first (i.e., the top) element} | |
732 ; @r{of the stack as the argument;} | |
733 ; @r{push returned value onto stack.} | |
734 @end group | |
735 | |
736 @group | |
737 ; @r{Stack now contains:} | |
738 ; @minus{} @r{result of recursive} | |
739 ; @r{call to @code{factorial}} | |
740 ; @minus{} @r{value of @code{integer}} | |
741 ; @minus{} @r{@code{*}} | |
742 @end group | |
743 | |
744 @group | |
745 16 call 2 ; @r{Using the first two} | |
746 ; @r{(i.e., the top two)} | |
747 ; @r{elements of the stack} | |
748 ; @r{as arguments,} | |
749 ; @r{call the function @code{*},} | |
750 ; @r{pushing the result onto the stack.} | |
751 @end group | |
752 | |
753 @group | |
754 17 return ; @r{Return the top element} | |
755 ; @r{of the stack.} | |
756 @result{} nil | |
757 @end group | |
758 @end example | |
759 | |
760 The @code{silly-loop} function is somewhat more complex: | |
761 | |
762 @example | |
763 @group | |
764 (defun silly-loop (n) | |
765 "Return time before and after N iterations of a loop." | |
766 (let ((t1 (current-time-string))) | |
767 (while (> (setq n (1- n)) | |
768 0)) | |
769 (list t1 (current-time-string)))) | |
770 @result{} silly-loop | |
771 @end group | |
772 | |
773 @group | |
774 (disassemble 'silly-loop) | |
775 @print{} byte-code for silly-loop: | |
776 doc: Return time before and after N iterations of a loop. | |
777 args: (n) | |
778 | |
779 0 constant current-time-string ; @r{Push} | |
780 ; @r{@code{current-time-string}} | |
781 ; @r{onto top of stack.} | |
782 @end group | |
783 | |
784 @group | |
785 1 call 0 ; @r{Call @code{current-time-string}} | |
786 ; @r{ with no argument,} | |
787 ; @r{ pushing result onto stack.} | |
788 @end group | |
789 | |
790 @group | |
791 2 varbind t1 ; @r{Pop stack and bind @code{t1}} | |
792 ; @r{to popped value.} | |
793 @end group | |
794 | |
795 @group | |
796 3 varref n ; @r{Get value of @code{n} from} | |
797 ; @r{the environment and push} | |
798 ; @r{the value onto the stack.} | |
799 @end group | |
800 | |
801 @group | |
802 4 sub1 ; @r{Subtract 1 from top of stack.} | |
803 @end group | |
804 | |
805 @group | |
806 5 dup ; @r{Duplicate the top of the stack;} | |
807 ; @r{i.e., copy the top of} | |
808 ; @r{the stack and push the} | |
809 ; @r{copy onto the stack.} | |
810 @end group | |
811 | |
812 @group | |
813 6 varset n ; @r{Pop the top of the stack,} | |
814 ; @r{and bind @code{n} to the value.} | |
815 | |
816 ; @r{In effect, the sequence @code{dup varset}} | |
817 ; @r{copies the top of the stack} | |
818 ; @r{into the value of @code{n}} | |
819 ; @r{without popping it.} | |
820 @end group | |
821 | |
822 @group | |
823 7 constant 0 ; @r{Push 0 onto stack.} | |
824 @end group | |
825 | |
826 @group | |
827 8 gtr ; @r{Pop top two values off stack,} | |
828 ; @r{test if @var{n} is greater than 0} | |
829 ; @r{and push result onto stack.} | |
830 @end group | |
831 | |
832 @group | |
833 9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0} | |
834 ; @r{(this exits the while loop).} | |
835 ; @r{else pop top of stack} | |
836 ; @r{and continue} | |
837 @end group | |
838 | |
839 @group | |
840 12 constant nil ; @r{Push @code{nil} onto stack} | |
841 ; @r{(this is the body of the loop).} | |
842 @end group | |
843 | |
844 @group | |
845 13 discard ; @r{Discard result of the body} | |
846 ; @r{of the loop (a while loop} | |
847 ; @r{is always evaluated for} | |
848 ; @r{its side effects).} | |
849 @end group | |
850 | |
851 @group | |
852 14 goto 3 ; @r{Jump back to beginning} | |
853 ; @r{of while loop.} | |
854 @end group | |
855 | |
856 @group | |
857 17 discard ; @r{Discard result of while loop} | |
858 ; @r{by popping top of stack.} | |
859 ; @r{This result is the value @code{nil} that} | |
860 ; @r{was not popped by the goto at 9.} | |
861 @end group | |
862 | |
863 @group | |
864 18 varref t1 ; @r{Push value of @code{t1} onto stack.} | |
865 @end group | |
866 | |
867 @group | |
868 19 constant current-time-string ; @r{Push} | |
869 ; @r{@code{current-time-string}} | |
870 ; @r{onto top of stack.} | |
871 @end group | |
872 | |
873 @group | |
874 20 call 0 ; @r{Call @code{current-time-string} again.} | |
875 @end group | |
876 | |
877 @group | |
878 21 list2 ; @r{Pop top two elements off stack,} | |
879 ; @r{create a list of them,} | |
880 ; @r{and push list onto stack.} | |
881 @end group | |
882 | |
883 @group | |
884 22 unbind 1 ; @r{Unbind @code{t1} in local environment.} | |
885 | |
886 23 return ; @r{Return value of the top of stack.} | |
887 | |
888 @result{} nil | |
889 @end group | |
890 @end example | |
891 | |
892 | |
893 @ignore | |
894 arch-tag: f78e3050-2f0a-4dee-be27-d9979a0a2289 | |
895 @end ignore |