|
0
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
|
|
|
4 @c See the file lispref.texi for copying conditions.
|
|
|
5 @setfilename ../../info/compile.info
|
|
|
6 @node Byte Compilation, Debugging, Loading, Top
|
|
|
7 @chapter Byte Compilation
|
|
|
8 @cindex byte-code
|
|
|
9 @cindex compilation
|
|
|
10
|
|
|
11 XEmacs 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-coded 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
|
|
217
|
23 In general, any version of Emacs can run byte-compiled code produced
|
|
0
|
24 by recent earlier versions of Emacs, but the reverse is not true. In
|
|
217
|
25 particular, if you compile a program with XEmacs 20, the compiled code
|
|
|
26 may not run in earlier versions.
|
|
0
|
27 @iftex
|
|
|
28 @xref{Docs and Compilation}.
|
|
|
29 @end iftex
|
|
|
30
|
|
|
31 @xref{Compilation Errors}, for how to investigate errors occurring in
|
|
|
32 byte compilation.
|
|
|
33
|
|
|
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.
|
|
|
39 * Eval During Compile:: Code to be evaluated when you compile.
|
|
|
40 * Compiled-Function Objects:: The data type used for byte-compiled functions.
|
|
|
41 * Disassembly:: Disassembling byte-code; how to read byte-code.
|
|
|
42 @end menu
|
|
|
43
|
|
|
44 @node Speed of Byte-Code
|
|
|
45 @section Performance of Byte-Compiled Code
|
|
|
46
|
|
|
47 A byte-compiled function is not as efficient as a primitive function
|
|
|
48 written in C, but runs much faster than the version written in Lisp.
|
|
|
49 Here is an example:
|
|
|
50
|
|
|
51 @example
|
|
|
52 @group
|
|
|
53 (defun silly-loop (n)
|
|
|
54 "Return time before and after N iterations of a loop."
|
|
|
55 (let ((t1 (current-time-string)))
|
|
|
56 (while (> (setq n (1- n))
|
|
|
57 0))
|
|
|
58 (list t1 (current-time-string))))
|
|
|
59 @result{} silly-loop
|
|
|
60 @end group
|
|
|
61
|
|
|
62 @group
|
|
219
|
63 (silly-loop 5000000)
|
|
|
64 @result{} ("Fri Nov 28 20:56:16 1997"
|
|
|
65 "Fri Nov 28 20:56:39 1997") ; @r{23 seconds}
|
|
0
|
66 @end group
|
|
|
67
|
|
|
68 @group
|
|
|
69 (byte-compile 'silly-loop)
|
|
219
|
70 @result{} #<compiled-function
|
|
|
71 (from "loadup.el")
|
|
|
72 (n)
|
|
|
73 "...(23)"
|
|
|
74 [current-time-string t1 n 0]
|
|
|
75 2
|
|
|
76 "Return time before and after N iterations of a loop.">
|
|
0
|
77 @end group
|
|
|
78
|
|
|
79 @group
|
|
219
|
80 (silly-loop 5000000)
|
|
|
81 @result{} ("Fri Nov 28 20:57:49 1997"
|
|
|
82 "Fri Nov 28 20:57:55 1997") ; @r{6 seconds}
|
|
0
|
83 @end group
|
|
|
84 @end example
|
|
|
85
|
|
219
|
86 In this example, the interpreted code required 23 seconds to run,
|
|
0
|
87 whereas the byte-compiled code required 6 seconds. These results are
|
|
|
88 representative, but actual results will vary greatly.
|
|
|
89
|
|
|
90 @node Compilation Functions
|
|
|
91 @comment node-name, next, previous, up
|
|
|
92 @section The Compilation Functions
|
|
|
93 @cindex compilation functions
|
|
|
94
|
|
|
95 You can byte-compile an individual function or macro definition with
|
|
|
96 the @code{byte-compile} function. You can compile a whole file with
|
|
|
97 @code{byte-compile-file}, or several files with
|
|
|
98 @code{byte-recompile-directory} or @code{batch-byte-compile}.
|
|
|
99
|
|
|
100 When you run the byte compiler, you may get warnings in a buffer
|
|
|
101 called @samp{*Compile-Log*}. These report things in your program that
|
|
|
102 suggest a problem but are not necessarily erroneous.
|
|
|
103
|
|
|
104 @cindex macro compilation
|
|
|
105 Be careful when byte-compiling code that uses macros. Macro calls are
|
|
|
106 expanded when they are compiled, so the macros must already be defined
|
|
|
107 for proper compilation. For more details, see @ref{Compiling Macros}.
|
|
|
108
|
|
|
109 Normally, compiling a file does not evaluate the file's contents or
|
|
|
110 load the file. But it does execute any @code{require} calls at top
|
|
|
111 level in the file. One way to ensure that necessary macro definitions
|
|
|
112 are available during compilation is to require the file that defines
|
|
|
113 them (@pxref{Named Features}). To avoid loading the macro definition files
|
|
|
114 when someone @emph{runs} the compiled program, write
|
|
|
115 @code{eval-when-compile} around the @code{require} calls (@pxref{Eval
|
|
|
116 During Compile}).
|
|
|
117
|
|
|
118 @defun byte-compile symbol
|
|
|
119 This function byte-compiles the function definition of @var{symbol},
|
|
|
120 replacing the previous definition with the compiled one. The function
|
|
|
121 definition of @var{symbol} must be the actual code for the function;
|
|
|
122 i.e., the compiler does not follow indirection to another symbol.
|
|
|
123 @code{byte-compile} returns the new, compiled definition of
|
|
|
124 @var{symbol}.
|
|
|
125
|
|
|
126 If @var{symbol}'s definition is a compiled-function object,
|
|
|
127 @code{byte-compile} does nothing and returns @code{nil}. Lisp records
|
|
|
128 only one function definition for any symbol, and if that is already
|
|
|
129 compiled, non-compiled code is not available anywhere. So there is no
|
|
|
130 way to ``compile the same definition again.''
|
|
|
131
|
|
|
132 @example
|
|
|
133 @group
|
|
|
134 (defun factorial (integer)
|
|
|
135 "Compute factorial of INTEGER."
|
|
|
136 (if (= 1 integer) 1
|
|
|
137 (* integer (factorial (1- integer)))))
|
|
|
138 @result{} factorial
|
|
|
139 @end group
|
|
|
140
|
|
|
141 @group
|
|
|
142 (byte-compile 'factorial)
|
|
219
|
143 @result{} #<compiled-function
|
|
|
144 (from "loadup.el")
|
|
|
145 (integer)
|
|
|
146 "...(21)"
|
|
|
147 [integer 1 factorial]
|
|
|
148 3
|
|
|
149 "Compute factorial of INTEGER.">
|
|
0
|
150 @end group
|
|
|
151 @end example
|
|
|
152
|
|
|
153 @noindent
|
|
|
154 The result is a compiled-function object. The string it contains is
|
|
|
155 the actual byte-code; each character in it is an instruction or an
|
|
|
156 operand of an instruction. The vector contains all the constants,
|
|
|
157 variable names and function names used by the function, except for
|
|
|
158 certain primitives that are coded as special instructions.
|
|
|
159 @end defun
|
|
|
160
|
|
|
161 @deffn Command compile-defun &optional arg
|
|
|
162 This command reads the defun containing point, compiles it, and
|
|
|
163 evaluates the result. If you use this on a defun that is actually a
|
|
|
164 function definition, the effect is to install a compiled version of that
|
|
|
165 function.
|
|
|
166
|
|
|
167 @c XEmacs feature
|
|
|
168 If @var{arg} is non-@code{nil}, the result is inserted in the current
|
|
|
169 buffer after the form; otherwise, it is printed in the minibuffer.
|
|
|
170 @end deffn
|
|
|
171
|
|
|
172 @deffn Command byte-compile-file filename &optional load
|
|
|
173 This function compiles a file of Lisp code named @var{filename} into
|
|
|
174 a file of byte-code. The output file's name is made by appending
|
|
|
175 @samp{c} to the end of @var{filename}.
|
|
|
176
|
|
|
177 @c XEmacs feature
|
|
|
178 If @code{load} is non-@code{nil}, the file is loaded after having been
|
|
|
179 compiled.
|
|
|
180
|
|
|
181 Compilation works by reading the input file one form at a time. If it
|
|
|
182 is a definition of a function or macro, the compiled function or macro
|
|
|
183 definition is written out. Other forms are batched together, then each
|
|
|
184 batch is compiled, and written so that its compiled code will be
|
|
|
185 executed when the file is read. All comments are discarded when the
|
|
|
186 input file is read.
|
|
|
187
|
|
|
188 This command returns @code{t}. When called interactively, it prompts
|
|
|
189 for the file name.
|
|
|
190
|
|
|
191 @example
|
|
|
192 @group
|
|
|
193 % ls -l push*
|
|
|
194 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
|
|
|
195 @end group
|
|
|
196
|
|
|
197 @group
|
|
|
198 (byte-compile-file "~/emacs/push.el")
|
|
|
199 @result{} t
|
|
|
200 @end group
|
|
|
201
|
|
|
202 @group
|
|
|
203 % ls -l push*
|
|
|
204 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
|
|
|
205 -rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc
|
|
|
206 @end group
|
|
|
207 @end example
|
|
|
208 @end deffn
|
|
|
209
|
|
|
210 @c flag is not optional in FSF Emacs
|
|
|
211 @deffn Command byte-recompile-directory directory &optional flag
|
|
|
212 @cindex library compilation
|
|
|
213 This function recompiles every @samp{.el} file in @var{directory} that
|
|
|
214 needs recompilation. A file needs recompilation if a @samp{.elc} file
|
|
|
215 exists but is older than the @samp{.el} file.
|
|
|
216
|
|
|
217 When a @samp{.el} file has no corresponding @samp{.elc} file, then
|
|
|
218 @var{flag} says what to do. If it is @code{nil}, these files are
|
|
|
219 ignored. If it is non-@code{nil}, the user is asked whether to compile
|
|
|
220 each such file.
|
|
|
221
|
|
|
222 The returned value of this command is unpredictable.
|
|
|
223 @end deffn
|
|
|
224
|
|
|
225 @defun batch-byte-compile
|
|
|
226 This function runs @code{byte-compile-file} on files specified on the
|
|
|
227 command line. This function must be used only in a batch execution of
|
|
|
228 Emacs, as it kills Emacs on completion. An error in one file does not
|
|
|
229 prevent processing of subsequent files. (The file that gets the error
|
|
|
230 will not, of course, produce any compiled code.)
|
|
|
231
|
|
|
232 @example
|
|
|
233 % emacs -batch -f batch-byte-compile *.el
|
|
|
234 @end example
|
|
|
235 @end defun
|
|
|
236
|
|
|
237 @c XEmacs feature
|
|
|
238 @defun batch-byte-recompile-directory
|
|
|
239 This function is similar to @code{batch-byte-compile} but runs the
|
|
|
240 command @code{byte-recompile-directory} on the files remaining on the
|
|
|
241 command line.
|
|
|
242 @end defun
|
|
|
243
|
|
|
244 @c XEmacs feature
|
|
|
245 @defvar byte-recompile-directory-ignore-errors-p
|
|
|
246 If non-@code{nil}, this specifies that @code{byte-recompile-directory}
|
|
|
247 will continue compiling even when an error occurs in a file. This is
|
|
|
248 normally @code{nil}, but is bound to @code{t} by
|
|
|
249 @code{batch-byte-recompile-directory}.
|
|
|
250 @end defvar
|
|
|
251
|
|
|
252 @defun byte-code code-string data-vector max-stack
|
|
|
253 @cindex byte-code interpreter
|
|
|
254 This function actually interprets byte-code. A byte-compiled function
|
|
|
255 is actually defined with a body that calls @code{byte-code}. Don't call
|
|
|
256 this function yourself. Only the byte compiler knows how to generate
|
|
|
257 valid calls to this function.
|
|
|
258
|
|
|
259 In newer Emacs versions (19 and up), byte-code is usually executed as
|
|
|
260 part of a compiled-function object, and only rarely due to an explicit
|
|
|
261 call to @code{byte-code}.
|
|
|
262 @end defun
|
|
|
263
|
|
|
264 @node Docs and Compilation
|
|
|
265 @section Documentation Strings and Compilation
|
|
|
266 @cindex dynamic loading of documentation
|
|
|
267
|
|
|
268 Functions and variables loaded from a byte-compiled file access their
|
|
|
269 documentation strings dynamically from the file whenever needed. This
|
|
|
270 saves space within Emacs, and makes loading faster because the
|
|
|
271 documentation strings themselves need not be processed while loading the
|
|
|
272 file. Actual access to the documentation strings becomes slower as a
|
|
|
273 result, but normally not enough to bother users.
|
|
|
274
|
|
|
275 Dynamic access to documentation strings does have drawbacks:
|
|
|
276
|
|
|
277 @itemize @bullet
|
|
|
278 @item
|
|
|
279 If you delete or move the compiled file after loading it, Emacs can no
|
|
|
280 longer access the documentation strings for the functions and variables
|
|
|
281 in the file.
|
|
|
282
|
|
|
283 @item
|
|
|
284 If you alter the compiled file (such as by compiling a new version),
|
|
|
285 then further access to documentation strings in this file will give
|
|
|
286 nonsense results.
|
|
|
287 @end itemize
|
|
|
288
|
|
|
289 If your site installs Emacs following the usual procedures, these
|
|
|
290 problems will never normally occur. Installing a new version uses a new
|
|
|
291 directory with a different name; as long as the old version remains
|
|
|
292 installed, its files will remain unmodified in the places where they are
|
|
|
293 expected to be.
|
|
|
294
|
|
|
295 However, if you have built Emacs yourself and use it from the
|
|
|
296 directory where you built it, you will experience this problem
|
|
|
297 occasionally if you edit and recompile Lisp files. When it happens, you
|
|
|
298 can cure the problem by reloading the file after recompiling it.
|
|
|
299
|
|
|
300 Byte-compiled files made with Emacs 19.29 will not load into older
|
|
|
301 versions because the older versions don't support this feature. You can
|
|
|
302 turn off this feature by setting @code{byte-compile-dynamic-docstrings}
|
|
|
303 to @code{nil}. Once this is done, you can compile files that will load
|
|
|
304 into older Emacs versions. You can do this globally, or for one source
|
|
|
305 file by specifying a file-local binding for the variable. Here's one
|
|
|
306 way to do that:
|
|
|
307
|
|
|
308 @example
|
|
|
309 -*-byte-compile-dynamic-docstrings: nil;-*-
|
|
|
310 @end example
|
|
|
311
|
|
|
312 @defvar byte-compile-dynamic-docstrings
|
|
|
313 If this is non-@code{nil}, the byte compiler generates compiled files
|
|
|
314 that are set up for dynamic loading of documentation strings.
|
|
|
315 @end defvar
|
|
|
316
|
|
|
317 @cindex @samp{#@@@var{count}}
|
|
|
318 @cindex @samp{#$}
|
|
|
319 The dynamic documentation string feature writes compiled files that
|
|
|
320 use a special Lisp reader construct, @samp{#@@@var{count}}. This
|
|
|
321 construct skips the next @var{count} characters. It also uses the
|
|
|
322 @samp{#$} construct, which stands for ``the name of this file, as a
|
|
|
323 string.'' It is best not to use these constructs in Lisp source files.
|
|
|
324
|
|
|
325 @node Dynamic Loading
|
|
|
326 @section Dynamic Loading of Individual Functions
|
|
|
327
|
|
|
328 @cindex dynamic loading of functions
|
|
|
329 @cindex lazy loading
|
|
|
330 When you compile a file, you can optionally enable the @dfn{dynamic
|
|
|
331 function loading} feature (also known as @dfn{lazy loading}). With
|
|
|
332 dynamic function loading, loading the file doesn't fully read the
|
|
|
333 function definitions in the file. Instead, each function definition
|
|
|
334 contains a place-holder which refers to the file. The first time each
|
|
|
335 function is called, it reads the full definition from the file, to
|
|
|
336 replace the place-holder.
|
|
|
337
|
|
|
338 The advantage of dynamic function loading is that loading the file
|
|
|
339 becomes much faster. This is a good thing for a file which contains
|
|
|
340 many separate commands, provided that using one of them does not imply
|
|
|
341 you will soon (or ever) use the rest. A specialized mode which provides
|
|
|
342 many keyboard commands often has that usage pattern: a user may invoke
|
|
|
343 the mode, but use only a few of the commands it provides.
|
|
|
344
|
|
|
345 The dynamic loading feature has certain disadvantages:
|
|
|
346
|
|
|
347 @itemize @bullet
|
|
|
348 @item
|
|
|
349 If you delete or move the compiled file after loading it, Emacs can no
|
|
|
350 longer load the remaining function definitions not already loaded.
|
|
|
351
|
|
|
352 @item
|
|
|
353 If you alter the compiled file (such as by compiling a new version),
|
|
|
354 then trying to load any function not already loaded will get nonsense
|
|
|
355 results.
|
|
|
356 @end itemize
|
|
|
357
|
|
|
358 If you compile a new version of the file, the best thing to do is
|
|
|
359 immediately load the new compiled file. That will prevent any future
|
|
|
360 problems.
|
|
|
361
|
|
|
362 The byte compiler uses the dynamic function loading feature if the
|
|
|
363 variable @code{byte-compile-dynamic} is non-@code{nil} at compilation
|
|
|
364 time. Do not set this variable globally, since dynamic loading is
|
|
|
365 desirable only for certain files. Instead, enable the feature for
|
|
|
366 specific source files with file-local variable bindings, like this:
|
|
|
367
|
|
|
368 @example
|
|
|
369 -*-byte-compile-dynamic: t;-*-
|
|
|
370 @end example
|
|
|
371
|
|
|
372 @defvar byte-compile-dynamic
|
|
|
373 If this is non-@code{nil}, the byte compiler generates compiled files
|
|
|
374 that are set up for dynamic function loading.
|
|
|
375 @end defvar
|
|
|
376
|
|
|
377 @defun fetch-bytecode function
|
|
|
378 This immediately finishes loading the definition of @var{function} from
|
|
|
379 its byte-compiled file, if it is not fully loaded already. The argument
|
|
|
380 @var{function} may be a compiled-function object or a function name.
|
|
|
381 @end defun
|
|
|
382
|
|
|
383 @node Eval During Compile
|
|
|
384 @section Evaluation During Compilation
|
|
|
385
|
|
|
386 These features permit you to write code to be evaluated during
|
|
|
387 compilation of a program.
|
|
|
388
|
|
|
389 @defspec eval-and-compile body
|
|
|
390 This form marks @var{body} to be evaluated both when you compile the
|
|
|
391 containing code and when you run it (whether compiled or not).
|
|
|
392
|
|
|
393 You can get a similar result by putting @var{body} in a separate file
|
|
|
394 and referring to that file with @code{require}. Using @code{require} is
|
|
|
395 preferable if there is a substantial amount of code to be executed in
|
|
|
396 this way.
|
|
|
397 @end defspec
|
|
|
398
|
|
|
399 @defspec eval-when-compile body
|
|
|
400 This form marks @var{body} to be evaluated at compile time and not when
|
|
|
401 the compiled program is loaded. The result of evaluation by the
|
|
|
402 compiler becomes a constant which appears in the compiled program. When
|
|
|
403 the program is interpreted, not compiled at all, @var{body} is evaluated
|
|
|
404 normally.
|
|
|
405
|
|
|
406 At top level, this is analogous to the Common Lisp idiom
|
|
|
407 @code{(eval-when (compile eval) @dots{})}. Elsewhere, the Common Lisp
|
|
|
408 @samp{#.} reader macro (but not when interpreting) is closer to what
|
|
|
409 @code{eval-when-compile} does.
|
|
|
410 @end defspec
|
|
|
411
|
|
|
412 @node Compiled-Function Objects
|
|
|
413 @section Compiled-Function Objects
|
|
|
414 @cindex compiled function
|
|
|
415 @cindex byte-code function
|
|
|
416
|
|
|
417 Byte-compiled functions have a special data type: they are
|
|
|
418 @dfn{compiled-function objects}.
|
|
|
419
|
|
|
420 A compiled-function object is a bit like a vector; however, the
|
|
|
421 evaluator handles this data type specially when it appears as a function
|
|
|
422 to be called. The printed representation for a compiled-function
|
|
|
423 object normally begins with @samp{#<compiled-function} and ends with
|
|
|
424 @samp{>}. However, if the variable @code{print-readably} is
|
|
|
425 non-@code{nil}, the object is printed beginning with @samp{#[} and
|
|
|
426 ending with @samp{]}. This representation can be read directly
|
|
|
427 by the Lisp reader, and is used in byte-compiled files (those ending
|
|
|
428 in @samp{.elc}).
|
|
|
429
|
|
|
430 In Emacs version 18, there was no compiled-function object data type;
|
|
|
431 compiled functions used the function @code{byte-code} to run the byte
|
|
|
432 code.
|
|
|
433
|
|
|
434 A compiled-function object has a number of different elements.
|
|
|
435 They are:
|
|
|
436
|
|
|
437 @table @var
|
|
|
438 @item arglist
|
|
|
439 The list of argument symbols.
|
|
|
440
|
|
|
441 @item instructions
|
|
|
442 The string containing the byte-code instructions.
|
|
|
443
|
|
|
444 @item constants
|
|
|
445 The vector of Lisp objects referenced by the byte code. These include
|
|
|
446 symbols used as function names and variable names.
|
|
|
447
|
|
|
448 @item stacksize
|
|
|
449 The maximum stack size this function needs.
|
|
|
450
|
|
|
451 @item doc-string
|
|
|
452 The documentation string (if any); otherwise, @code{nil}. The value may
|
|
|
453 be a number or a list, in case the documentation string is stored in a
|
|
|
454 file. Use the function @code{documentation} to get the real
|
|
|
455 documentation string (@pxref{Accessing Documentation}).
|
|
|
456
|
|
|
457 @item interactive
|
|
|
458 The interactive spec (if any). This can be a string or a Lisp
|
|
|
459 expression. It is @code{nil} for a function that isn't interactive.
|
|
|
460
|
|
|
461 @item domain
|
|
|
462 The domain (if any). This is only meaningful if I18N3 (message-translation)
|
|
|
463 support was compiled into XEmacs. This is a string defining which
|
|
|
464 domain to find the translation for the documentation string and
|
|
|
465 interactive prompt. @xref{Domain Specification}.
|
|
|
466 @end table
|
|
|
467
|
|
|
468 Here's an example of a compiled-function object, in printed
|
|
|
469 representation. It is the definition of the command
|
|
|
470 @code{backward-sexp}.
|
|
|
471
|
|
|
472 @example
|
|
|
473 #<compiled-function
|
|
219
|
474 (from "lisp.elc")
|
|
|
475 (&optional arg)
|
|
|
476 "...(15)" [arg 1 forward-sexp] 2 854740 "_p">
|
|
0
|
477 @end example
|
|
|
478
|
|
|
479 The primitive way to create a compiled-function object is with
|
|
|
480 @code{make-byte-code}:
|
|
|
481
|
|
|
482 @defun make-byte-code &rest elements
|
|
|
483 This function constructs and returns a compiled-function object
|
|
|
484 with @var{elements} as its elements.
|
|
|
485
|
|
|
486 @emph{NOTE:} Unlike all other Emacs-lisp functions, calling this with
|
|
|
487 five arguments is @emph{not} the same as calling it with six arguments,
|
|
|
488 the last of which is @code{nil}. If the @var{interactive} arg is
|
|
|
489 specified as @code{nil}, then that means that this function was defined
|
|
|
490 with @code{(interactive)}. If the arg is not specified, then that means
|
|
|
491 the function is not interactive. This is terrible behavior which is
|
|
|
492 retained for compatibility with old @samp{.elc} files which expected
|
|
|
493 these semantics.
|
|
|
494 @end defun
|
|
|
495
|
|
|
496 You should not try to come up with the elements for a compiled-function
|
|
|
497 object yourself, because if they are inconsistent, XEmacs may crash
|
|
|
498 when you call the function. Always leave it to the byte compiler to
|
|
|
499 create these objects; it makes the elements consistent (we hope).
|
|
|
500
|
|
|
501 The following primitives are provided for accessing the elements of
|
|
|
502 a compiled-function object.
|
|
|
503
|
|
|
504 @defun compiled-function-arglist function
|
|
|
505 This function returns the argument list of compiled-function object
|
|
|
506 @var{function}.
|
|
|
507 @end defun
|
|
|
508
|
|
|
509 @defun compiled-function-instructions function
|
|
|
510 This function returns a string describing the byte-code instructions
|
|
|
511 of compiled-function object @var{function}.
|
|
|
512 @end defun
|
|
|
513
|
|
|
514 @defun compiled-function-constants function
|
|
|
515 This function returns the vector of Lisp objects referenced by
|
|
|
516 compiled-function object @var{function}.
|
|
|
517 @end defun
|
|
|
518
|
|
|
519 @defun compiled-function-stack-size function
|
|
|
520 This function returns the maximum stack size needed by compiled-function
|
|
|
521 object @var{function}.
|
|
|
522 @end defun
|
|
|
523
|
|
|
524 @defun compiled-function-doc-string function
|
|
|
525 This function returns the doc string of compiled-function object
|
|
|
526 @var{function}, if available.
|
|
|
527 @end defun
|
|
|
528
|
|
|
529 @defun compiled-function-interactive function
|
|
|
530 This function returns the interactive spec of compiled-function object
|
|
|
531 @var{function}, if any. The return value is @code{nil} or a two-element
|
|
|
532 list, the first element of which is the symbol @code{interactive} and
|
|
|
533 the second element is the interactive spec (a string or Lisp form).
|
|
|
534 @end defun
|
|
|
535
|
|
|
536 @defun compiled-function-domain function
|
|
|
537 This function returns the domain of compiled-function object
|
|
|
538 @var{function}, if any. The result will be a string or @code{nil}.
|
|
|
539 @xref{Domain Specification}.
|
|
|
540 @end defun
|
|
|
541
|
|
|
542 @node Disassembly
|
|
|
543 @section Disassembled Byte-Code
|
|
|
544 @cindex disassembled byte-code
|
|
|
545
|
|
|
546 People do not write byte-code; that job is left to the byte compiler.
|
|
|
547 But we provide a disassembler to satisfy a cat-like curiosity. The
|
|
|
548 disassembler converts the byte-compiled code into humanly readable
|
|
|
549 form.
|
|
|
550
|
|
|
551 The byte-code interpreter is implemented as a simple stack machine.
|
|
|
552 It pushes values onto a stack of its own, then pops them off to use them
|
|
|
553 in calculations whose results are themselves pushed back on the stack.
|
|
|
554 When a byte-code function returns, it pops a value off the stack and
|
|
|
555 returns it as the value of the function.
|
|
|
556
|
|
|
557 In addition to the stack, byte-code functions can use, bind, and set
|
|
|
558 ordinary Lisp variables, by transferring values between variables and
|
|
|
559 the stack.
|
|
|
560
|
|
|
561 @deffn Command disassemble object &optional stream
|
|
|
562 This function prints the disassembled code for @var{object}. If
|
|
|
563 @var{stream} is supplied, then output goes there. Otherwise, the
|
|
|
564 disassembled code is printed to the stream @code{standard-output}. The
|
|
|
565 argument @var{object} can be a function name or a lambda expression.
|
|
|
566
|
|
|
567 As a special exception, if this function is used interactively,
|
|
|
568 it outputs to a buffer named @samp{*Disassemble*}.
|
|
|
569 @end deffn
|
|
|
570
|
|
|
571 Here are two examples of using the @code{disassemble} function. We
|
|
|
572 have added explanatory comments to help you relate the byte-code to the
|
|
|
573 Lisp source; these do not appear in the output of @code{disassemble}.
|
|
|
574 These examples show unoptimized byte-code. Nowadays byte-code is
|
|
|
575 usually optimized, but we did not want to rewrite these examples, since
|
|
|
576 they still serve their purpose.
|
|
|
577
|
|
|
578 @example
|
|
|
579 @group
|
|
|
580 (defun factorial (integer)
|
|
|
581 "Compute factorial of an integer."
|
|
|
582 (if (= 1 integer) 1
|
|
|
583 (* integer (factorial (1- integer)))))
|
|
|
584 @result{} factorial
|
|
|
585 @end group
|
|
|
586
|
|
|
587 @group
|
|
|
588 (factorial 4)
|
|
|
589 @result{} 24
|
|
|
590 @end group
|
|
|
591
|
|
|
592 @group
|
|
|
593 (disassemble 'factorial)
|
|
|
594 @print{} byte-code for factorial:
|
|
|
595 doc: Compute factorial of an integer.
|
|
|
596 args: (integer)
|
|
|
597 @end group
|
|
|
598
|
|
|
599 @group
|
|
|
600 0 constant 1 ; @r{Push 1 onto stack.}
|
|
|
601
|
|
|
602 1 varref integer ; @r{Get value of @code{integer}}
|
|
|
603 ; @r{from the environment}
|
|
|
604 ; @r{and push the value}
|
|
|
605 ; @r{onto the stack.}
|
|
|
606 @end group
|
|
|
607
|
|
|
608 @group
|
|
|
609 2 eqlsign ; @r{Pop top two values off stack,}
|
|
|
610 ; @r{compare them,}
|
|
|
611 ; @r{and push result onto stack.}
|
|
|
612 @end group
|
|
|
613
|
|
|
614 @group
|
|
|
615 3 goto-if-nil 10 ; @r{Pop and test top of stack;}
|
|
|
616 ; @r{if @code{nil}, go to 10,}
|
|
|
617 ; @r{else continue.}
|
|
|
618 @end group
|
|
|
619
|
|
|
620 @group
|
|
|
621 6 constant 1 ; @r{Push 1 onto top of stack.}
|
|
|
622
|
|
|
623 7 goto 17 ; @r{Go to 17 (in this case, 1 will be}
|
|
|
624 ; @r{returned by the function).}
|
|
|
625 @end group
|
|
|
626
|
|
|
627 @group
|
|
|
628 10 constant * ; @r{Push symbol @code{*} onto stack.}
|
|
|
629
|
|
|
630 11 varref integer ; @r{Push value of @code{integer} onto stack.}
|
|
|
631 @end group
|
|
|
632
|
|
|
633 @group
|
|
|
634 12 constant factorial ; @r{Push @code{factorial} onto stack.}
|
|
|
635
|
|
|
636 13 varref integer ; @r{Push value of @code{integer} onto stack.}
|
|
|
637
|
|
|
638 14 sub1 ; @r{Pop @code{integer}, decrement value,}
|
|
|
639 ; @r{push new value onto stack.}
|
|
|
640 @end group
|
|
|
641
|
|
|
642 @group
|
|
|
643 ; @r{Stack now contains:}
|
|
|
644 ; @minus{} @r{decremented value of @code{integer}}
|
|
|
645 ; @minus{} @r{@code{factorial}}
|
|
|
646 ; @minus{} @r{value of @code{integer}}
|
|
|
647 ; @minus{} @r{@code{*}}
|
|
|
648 @end group
|
|
|
649
|
|
|
650 @group
|
|
|
651 15 call 1 ; @r{Call function @code{factorial} using}
|
|
|
652 ; @r{the first (i.e., the top) element}
|
|
|
653 ; @r{of the stack as the argument;}
|
|
|
654 ; @r{push returned value onto stack.}
|
|
|
655 @end group
|
|
|
656
|
|
|
657 @group
|
|
|
658 ; @r{Stack now contains:}
|
|
|
659 ; @minus{} @r{result of recursive}
|
|
|
660 ; @r{call to @code{factorial}}
|
|
|
661 ; @minus{} @r{value of @code{integer}}
|
|
|
662 ; @minus{} @r{@code{*}}
|
|
|
663 @end group
|
|
|
664
|
|
|
665 @group
|
|
|
666 16 call 2 ; @r{Using the first two}
|
|
|
667 ; @r{(i.e., the top two)}
|
|
|
668 ; @r{elements of the stack}
|
|
|
669 ; @r{as arguments,}
|
|
|
670 ; @r{call the function @code{*},}
|
|
|
671 ; @r{pushing the result onto the stack.}
|
|
|
672 @end group
|
|
|
673
|
|
|
674 @group
|
|
|
675 17 return ; @r{Return the top element}
|
|
|
676 ; @r{of the stack.}
|
|
|
677 @result{} nil
|
|
|
678 @end group
|
|
|
679 @end example
|
|
|
680
|
|
|
681 The @code{silly-loop} function is somewhat more complex:
|
|
|
682
|
|
|
683 @example
|
|
|
684 @group
|
|
|
685 (defun silly-loop (n)
|
|
|
686 "Return time before and after N iterations of a loop."
|
|
|
687 (let ((t1 (current-time-string)))
|
|
|
688 (while (> (setq n (1- n))
|
|
|
689 0))
|
|
|
690 (list t1 (current-time-string))))
|
|
|
691 @result{} silly-loop
|
|
|
692 @end group
|
|
|
693
|
|
|
694 @group
|
|
|
695 (disassemble 'silly-loop)
|
|
|
696 @print{} byte-code for silly-loop:
|
|
|
697 doc: Return time before and after N iterations of a loop.
|
|
|
698 args: (n)
|
|
|
699
|
|
|
700 0 constant current-time-string ; @r{Push}
|
|
|
701 ; @r{@code{current-time-string}}
|
|
|
702 ; @r{onto top of stack.}
|
|
|
703 @end group
|
|
|
704
|
|
|
705 @group
|
|
|
706 1 call 0 ; @r{Call @code{current-time-string}}
|
|
|
707 ; @r{ with no argument,}
|
|
|
708 ; @r{ pushing result onto stack.}
|
|
|
709 @end group
|
|
|
710
|
|
|
711 @group
|
|
|
712 2 varbind t1 ; @r{Pop stack and bind @code{t1}}
|
|
|
713 ; @r{to popped value.}
|
|
|
714 @end group
|
|
|
715
|
|
|
716 @group
|
|
|
717 3 varref n ; @r{Get value of @code{n} from}
|
|
|
718 ; @r{the environment and push}
|
|
|
719 ; @r{the value onto the stack.}
|
|
|
720 @end group
|
|
|
721
|
|
|
722 @group
|
|
|
723 4 sub1 ; @r{Subtract 1 from top of stack.}
|
|
|
724 @end group
|
|
|
725
|
|
|
726 @group
|
|
|
727 5 dup ; @r{Duplicate the top of the stack;}
|
|
|
728 ; @r{i.e., copy the top of}
|
|
|
729 ; @r{the stack and push the}
|
|
|
730 ; @r{copy onto the stack.}
|
|
|
731 @end group
|
|
|
732
|
|
|
733 @group
|
|
|
734 6 varset n ; @r{Pop the top of the stack,}
|
|
|
735 ; @r{and bind @code{n} to the value.}
|
|
|
736
|
|
|
737 ; @r{In effect, the sequence @code{dup varset}}
|
|
|
738 ; @r{copies the top of the stack}
|
|
|
739 ; @r{into the value of @code{n}}
|
|
|
740 ; @r{without popping it.}
|
|
|
741 @end group
|
|
|
742
|
|
|
743 @group
|
|
|
744 7 constant 0 ; @r{Push 0 onto stack.}
|
|
|
745 @end group
|
|
|
746
|
|
|
747 @group
|
|
|
748 8 gtr ; @r{Pop top two values off stack,}
|
|
|
749 ; @r{test if @var{n} is greater than 0}
|
|
|
750 ; @r{and push result onto stack.}
|
|
|
751 @end group
|
|
|
752
|
|
|
753 @group
|
|
|
754 9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0}
|
|
|
755 ; @r{(this exits the while loop).}
|
|
|
756 ; @r{else pop top of stack}
|
|
|
757 ; @r{and continue}
|
|
|
758 @end group
|
|
|
759
|
|
|
760 @group
|
|
|
761 12 constant nil ; @r{Push @code{nil} onto stack}
|
|
|
762 ; @r{(this is the body of the loop).}
|
|
|
763 @end group
|
|
|
764
|
|
|
765 @group
|
|
|
766 13 discard ; @r{Discard result of the body}
|
|
|
767 ; @r{of the loop (a while loop}
|
|
|
768 ; @r{is always evaluated for}
|
|
|
769 ; @r{its side effects).}
|
|
|
770 @end group
|
|
|
771
|
|
|
772 @group
|
|
|
773 14 goto 3 ; @r{Jump back to beginning}
|
|
|
774 ; @r{of while loop.}
|
|
|
775 @end group
|
|
|
776
|
|
|
777 @group
|
|
|
778 17 discard ; @r{Discard result of while loop}
|
|
|
779 ; @r{by popping top of stack.}
|
|
|
780 ; @r{This result is the value @code{nil} that}
|
|
|
781 ; @r{was not popped by the goto at 9.}
|
|
|
782 @end group
|
|
|
783
|
|
|
784 @group
|
|
|
785 18 varref t1 ; @r{Push value of @code{t1} onto stack.}
|
|
|
786 @end group
|
|
|
787
|
|
|
788 @group
|
|
|
789 19 constant current-time-string ; @r{Push}
|
|
|
790 ; @r{@code{current-time-string}}
|
|
|
791 ; @r{onto top of stack.}
|
|
|
792 @end group
|
|
|
793
|
|
|
794 @group
|
|
|
795 20 call 0 ; @r{Call @code{current-time-string} again.}
|
|
|
796 @end group
|
|
|
797
|
|
|
798 @group
|
|
|
799 21 list2 ; @r{Pop top two elements off stack,}
|
|
|
800 ; @r{create a list of them,}
|
|
|
801 ; @r{and push list onto stack.}
|
|
|
802 @end group
|
|
|
803
|
|
|
804 @group
|
|
|
805 22 unbind 1 ; @r{Unbind @code{t1} in local environment.}
|
|
|
806
|
|
|
807 23 return ; @r{Return value of the top of stack.}
|
|
|
808
|
|
|
809 @result{} nil
|
|
|
810 @end group
|
|
|
811 @end example
|
|
|
812
|
|
|
813
|
