|
428
|
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
|
|
|
23 In general, any version of Emacs can run byte-compiled code produced
|
|
|
24 by recent earlier versions of Emacs, but the reverse is not true. In
|
|
|
25 particular, if you compile a program with XEmacs 20, the compiled code
|
|
|
26 may not run in earlier versions.
|
|
|
27
|
|
|
28 The first time a compiled-function object is executed, the byte-code
|
|
|
29 instructions are validated and the byte-code is further optimized. An
|
|
|
30 @code{invalid-byte-code} error is signaled if the byte-code is invalid,
|
|
|
31 for example if it contains invalid opcodes. This usually means a bug in
|
|
|
32 the byte compiler.
|
|
|
33
|
|
|
34 @iftex
|
|
|
35 @xref{Docs and Compilation}.
|
|
|
36 @end iftex
|
|
|
37
|
|
|
38 @xref{Compilation Errors}, for how to investigate errors occurring in
|
|
|
39 byte compilation.
|
|
|
40
|
|
|
41 @menu
|
|
|
42 * Speed of Byte-Code:: An example of speedup from byte compilation.
|
|
|
43 * Compilation Functions:: Byte compilation functions.
|
|
1103
|
44 * Compilation Options:: Controlling the byte compiler's behavior.
|
|
428
|
45 * Docs and Compilation:: Dynamic loading of documentation strings.
|
|
|
46 * Dynamic Loading:: Dynamic loading of individual functions.
|
|
|
47 * Eval During Compile:: Code to be evaluated when you compile.
|
|
|
48 * Compiled-Function Objects:: The data type used for byte-compiled functions.
|
|
|
49 * Disassembly:: Disassembling byte-code; how to read byte-code.
|
|
446
|
50 * Different Behavior:: When compiled code gives different results.
|
|
428
|
51 @end menu
|
|
|
52
|
|
|
53 @node Speed of Byte-Code
|
|
|
54 @section Performance of Byte-Compiled Code
|
|
|
55
|
|
|
56 A byte-compiled function is not as efficient as a primitive function
|
|
|
57 written in C, but runs much faster than the version written in Lisp.
|
|
|
58 Here is an example:
|
|
|
59
|
|
|
60 @example
|
|
|
61 @group
|
|
|
62 (defun silly-loop (n)
|
|
|
63 "Return time before and after N iterations of a loop."
|
|
|
64 (let ((t1 (current-time-string)))
|
|
|
65 (while (> (setq n (1- n))
|
|
|
66 0))
|
|
|
67 (list t1 (current-time-string))))
|
|
|
68 @result{} silly-loop
|
|
|
69 @end group
|
|
|
70
|
|
|
71 @group
|
|
|
72 (silly-loop 5000000)
|
|
|
73 @result{} ("Mon Sep 14 15:51:49 1998"
|
|
|
74 "Mon Sep 14 15:52:07 1998") ; @r{18 seconds}
|
|
|
75 @end group
|
|
|
76
|
|
|
77 @group
|
|
|
78 (byte-compile 'silly-loop)
|
|
|
79 @result{} #<compiled-function
|
|
|
80 (n)
|
|
|
81 "...(23)"
|
|
|
82 [current-time-string t1 n 0]
|
|
|
83 2
|
|
|
84 "Return time before and after N iterations of a loop.">
|
|
|
85 @end group
|
|
|
86
|
|
|
87 @group
|
|
|
88 (silly-loop 5000000)
|
|
|
89 @result{} ("Mon Sep 14 15:53:43 1998"
|
|
|
90 "Mon Sep 14 15:53:49 1998") ; @r{6 seconds}
|
|
|
91 @end group
|
|
|
92 @end example
|
|
|
93
|
|
|
94 In this example, the interpreted code required 18 seconds to run,
|
|
|
95 whereas the byte-compiled code required 6 seconds. These results are
|
|
|
96 representative, but actual results will vary greatly.
|
|
|
97
|
|
|
98 @node Compilation Functions
|
|
|
99 @comment node-name, next, previous, up
|
|
|
100 @section The Compilation Functions
|
|
|
101 @cindex compilation functions
|
|
|
102
|
|
|
103 You can byte-compile an individual function or macro definition with
|
|
|
104 the @code{byte-compile} function. You can compile a whole file with
|
|
|
105 @code{byte-compile-file}, or several files with
|
|
|
106 @code{byte-recompile-directory} or @code{batch-byte-compile}.
|
|
|
107
|
|
|
108 When you run the byte compiler, you may get warnings in a buffer
|
|
|
109 called @samp{*Compile-Log*}. These report things in your program that
|
|
|
110 suggest a problem but are not necessarily erroneous.
|
|
|
111
|
|
|
112 @cindex macro compilation
|
|
|
113 Be careful when byte-compiling code that uses macros. Macro calls are
|
|
|
114 expanded when they are compiled, so the macros must already be defined
|
|
|
115 for proper compilation. For more details, see @ref{Compiling Macros}.
|
|
|
116
|
|
|
117 Normally, compiling a file does not evaluate the file's contents or
|
|
|
118 load the file. But it does execute any @code{require} calls at top
|
|
|
119 level in the file. One way to ensure that necessary macro definitions
|
|
|
120 are available during compilation is to @code{require} the file that defines
|
|
|
121 them (@pxref{Named Features}). To avoid loading the macro definition files
|
|
|
122 when someone @emph{runs} the compiled program, write
|
|
|
123 @code{eval-when-compile} around the @code{require} calls (@pxref{Eval
|
|
|
124 During Compile}).
|
|
|
125
|
|
|
126 @defun byte-compile symbol
|
|
|
127 This function byte-compiles the function definition of @var{symbol},
|
|
|
128 replacing the previous definition with the compiled one. The function
|
|
|
129 definition of @var{symbol} must be the actual code for the function;
|
|
|
130 i.e., the compiler does not follow indirection to another symbol.
|
|
|
131 @code{byte-compile} returns the new, compiled definition of
|
|
|
132 @var{symbol}.
|
|
|
133
|
|
|
134 If @var{symbol}'s definition is a compiled-function object,
|
|
|
135 @code{byte-compile} does nothing and returns @code{nil}. Lisp records
|
|
|
136 only one function definition for any symbol, and if that is already
|
|
|
137 compiled, non-compiled code is not available anywhere. So there is no
|
|
|
138 way to ``compile the same definition again.''
|
|
|
139
|
|
|
140 @example
|
|
|
141 @group
|
|
|
142 (defun factorial (integer)
|
|
|
143 "Compute factorial of INTEGER."
|
|
|
144 (if (= 1 integer) 1
|
|
|
145 (* integer (factorial (1- integer)))))
|
|
|
146 @result{} factorial
|
|
|
147 @end group
|
|
|
148
|
|
|
149 @group
|
|
|
150 (byte-compile 'factorial)
|
|
|
151 @result{} #<compiled-function
|
|
|
152 (integer)
|
|
|
153 "...(21)"
|
|
|
154 [integer 1 factorial]
|
|
|
155 3
|
|
|
156 "Compute factorial of INTEGER.">
|
|
|
157 @end group
|
|
|
158 @end example
|
|
|
159
|
|
|
160 @noindent
|
|
|
161 The result is a compiled-function object. The string it contains is
|
|
|
162 the actual byte-code; each character in it is an instruction or an
|
|
|
163 operand of an instruction. The vector contains all the constants,
|
|
|
164 variable names and function names used by the function, except for
|
|
|
165 certain primitives that are coded as special instructions.
|
|
|
166 @end defun
|
|
|
167
|
|
|
168 @deffn Command compile-defun &optional arg
|
|
|
169 This command reads the defun containing point, compiles it, and
|
|
|
170 evaluates the result. If you use this on a defun that is actually a
|
|
|
171 function definition, the effect is to install a compiled version of that
|
|
|
172 function.
|
|
|
173
|
|
|
174 @c XEmacs feature
|
|
|
175 If @var{arg} is non-@code{nil}, the result is inserted in the current
|
|
|
176 buffer after the form; otherwise, it is printed in the minibuffer.
|
|
|
177 @end deffn
|
|
|
178
|
|
|
179 @deffn Command byte-compile-file filename &optional load
|
|
|
180 This function compiles a file of Lisp code named @var{filename} into
|
|
|
181 a file of byte-code. The output file's name is made by appending
|
|
|
182 @samp{c} to the end of @var{filename}.
|
|
|
183
|
|
|
184 @c XEmacs feature
|
|
|
185 If @code{load} is non-@code{nil}, the file is loaded after having been
|
|
|
186 compiled.
|
|
|
187
|
|
|
188 Compilation works by reading the input file one form at a time. If it
|
|
|
189 is a definition of a function or macro, the compiled function or macro
|
|
|
190 definition is written out. Other forms are batched together, then each
|
|
|
191 batch is compiled, and written so that its compiled code will be
|
|
|
192 executed when the file is read. All comments are discarded when the
|
|
|
193 input file is read.
|
|
|
194
|
|
|
195 This command returns @code{t}. When called interactively, it prompts
|
|
|
196 for the file name.
|
|
|
197
|
|
|
198 @example
|
|
|
199 @group
|
|
|
200 % ls -l push*
|
|
|
201 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
|
|
|
202 @end group
|
|
|
203
|
|
|
204 @group
|
|
|
205 (byte-compile-file "~/emacs/push.el")
|
|
|
206 @result{} t
|
|
|
207 @end group
|
|
|
208
|
|
|
209 @group
|
|
|
210 % ls -l push*
|
|
|
211 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
|
|
|
212 -rw-r--r-- 1 lewis 638 Oct 8 20:25 push.elc
|
|
|
213 @end group
|
|
|
214 @end example
|
|
|
215 @end deffn
|
|
|
216
|
|
|
217 @c flag is not optional in FSF Emacs
|
|
444
|
218 @deffn Command byte-recompile-directory directory &optional flag norecursion force
|
|
428
|
219 @cindex library compilation
|
|
|
220 This function recompiles every @samp{.el} file in @var{directory} that
|
|
|
221 needs recompilation. A file needs recompilation if a @samp{.elc} file
|
|
|
222 exists but is older than the @samp{.el} file.
|
|
|
223
|
|
444
|
224 Files in subdirectories of @var{directory} are also processed unless
|
|
|
225 optional argument @var{norecursion} is non-@code{nil}.
|
|
|
226
|
|
428
|
227 When a @samp{.el} file has no corresponding @samp{.elc} file, then
|
|
|
228 @var{flag} says what to do. If it is @code{nil}, these files are
|
|
|
229 ignored. If it is non-@code{nil}, the user is asked whether to compile
|
|
|
230 each such file.
|
|
|
231
|
|
444
|
232 If the fourth optional argument @var{force} is non-@code{nil},
|
|
|
233 recompile every @samp{.el} file that already has a @samp{.elc} file.
|
|
|
234
|
|
428
|
235 The return value of this command is unpredictable.
|
|
|
236 @end deffn
|
|
|
237
|
|
|
238 @defun batch-byte-compile
|
|
|
239 This function runs @code{byte-compile-file} on files specified on the
|
|
|
240 command line. This function must be used only in a batch execution of
|
|
|
241 Emacs, as it kills Emacs on completion. An error in one file does not
|
|
|
242 prevent processing of subsequent files. (The file that gets the error
|
|
|
243 will not, of course, produce any compiled code.)
|
|
|
244
|
|
|
245 @example
|
|
442
|
246 % xemacs -batch -f batch-byte-compile *.el
|
|
428
|
247 @end example
|
|
|
248 @end defun
|
|
|
249
|
|
|
250 @c XEmacs feature
|
|
|
251 @defun batch-byte-recompile-directory
|
|
|
252 This function is similar to @code{batch-byte-compile} but runs the
|
|
|
253 command @code{byte-recompile-directory} on the files remaining on the
|
|
|
254 command line.
|
|
|
255 @end defun
|
|
|
256
|
|
|
257 @c XEmacs feature
|
|
|
258 @defvar byte-recompile-directory-ignore-errors-p
|
|
1103
|
259 When non-@code{nil}, @code{byte-recompile-directory} will continue
|
|
|
260 compiling even when an error occurs in a file. Default: @code{nil}, but
|
|
|
261 bound to @code{t} by @code{batch-byte-recompile-directory}.
|
|
428
|
262 @end defvar
|
|
|
263
|
|
1103
|
264 @c XEmacs feature (?)
|
|
|
265 @defvar byte-recompile-directory-recursively
|
|
|
266 When non-@code{nil}, @code{byte-recompile-directory} will recurse on
|
|
|
267 subdirectories. Default: @code{t}.
|
|
|
268 @end defvar
|
|
|
269
|
|
|
270
|
|
444
|
271 @defun byte-code instructions constants stack-depth
|
|
428
|
272 @cindex byte-code interpreter
|
|
|
273 This function actually interprets byte-code.
|
|
|
274 Don't call this function yourself. Only the byte compiler knows how to
|
|
|
275 generate valid calls to this function.
|
|
|
276
|
|
|
277 In newer Emacs versions (19 and up), byte code is usually executed as
|
|
|
278 part of a compiled-function object, and only rarely due to an explicit
|
|
|
279 call to @code{byte-code}. A byte-compiled function was once actually
|
|
|
280 defined with a body that calls @code{byte-code}, but in recent versions
|
|
|
281 of Emacs @code{byte-code} is only used to run isolated fragments of lisp
|
|
|
282 code without an associated argument list.
|
|
|
283 @end defun
|
|
|
284
|
|
1103
|
285 @node Compilation Options
|
|
|
286 @section Options for the Byte Compiler
|
|
|
287 @cindex compilation options
|
|
|
288
|
|
|
289 Warning: this node is a quick draft based on docstrings. There may be
|
|
|
290 inaccuracies, as the docstrings occasionally disagree with each other.
|
|
|
291 This has not been checked yet.
|
|
|
292
|
|
|
293 The byte compiler and optimizer are controlled by the following
|
|
|
294 variables. The @code{byte-compiler-options} macro described below
|
|
|
295 provides a convenient way to set most of them on a file-by-file basis.
|
|
|
296
|
|
|
297 @defvar emacs-lisp-file-regexp
|
|
|
298 Regexp which matches Emacs Lisp source files.
|
|
|
299 You may want to redefine @code{byte-compile-dest-file} if you change
|
|
|
300 this. Default: @code{"\\.el$"}.
|
|
|
301 @end defvar
|
|
|
302
|
|
|
303 @defun byte-compile-dest-file filename
|
|
|
304 Convert an Emacs Lisp source file name to a compiled file name. This
|
|
|
305 function may be redefined by the user, if necessary, for compatibility
|
|
|
306 with @code{emacs-lisp-file-regexp}.
|
|
|
307 @end defun
|
|
|
308
|
|
|
309 @c ;; This can be the 'byte-compile property of any symbol.
|
|
|
310 @c (autoload 'byte-compile-inline-expand "byte-optimize")
|
|
|
311
|
|
|
312 @defvar byte-compile-verbose
|
|
|
313 When non-@code{nil}, print messages describing progress of
|
|
|
314 byte-compiler. Default: @code{t} if interactive on a not-too-slow
|
|
|
315 terminal (see @code{search-slow-speed}), otherwise @code{nil}.
|
|
|
316 @end defvar
|
|
|
317
|
|
|
318 @defvar byte-optimize
|
|
|
319 Level of optimization in the byte compiler.
|
|
|
320
|
|
|
321 @table @code
|
|
|
322 @item nil
|
|
|
323 Do no optimization.
|
|
|
324
|
|
|
325 @item t
|
|
|
326 Do all optimizations.
|
|
|
327
|
|
|
328 @item source
|
|
|
329 Do optimizations manipulating the source code only.
|
|
|
330
|
|
|
331 @item byte
|
|
|
332 Do optimizations manipulating the byte code (actually, LAP code) only.
|
|
|
333 @end table
|
|
|
334 Default: @code{t}.
|
|
|
335 @end defvar
|
|
|
336
|
|
|
337 @defvar byte-compile-delete-errors
|
|
|
338 When non-@code{nil}, the optimizer may delete forms that may signal an
|
|
|
339 error if that is the only change in the function's behavior.
|
|
|
340 This includes variable references and calls to functions such as
|
|
|
341 @code{car}.
|
|
|
342 Default: @code{t}.
|
|
|
343 @end defvar
|
|
|
344
|
|
|
345 @defvar byte-optimize-log nil
|
|
|
346 When non-@code{nil}, the byte-compiler logs optimizations into
|
|
|
347 @file{*Compile-Log*}.
|
|
|
348
|
|
|
349 @table @code
|
|
|
350 @item nil
|
|
|
351 Log no optimization.
|
|
|
352
|
|
|
353 @item t
|
|
|
354 Log all optimizations.
|
|
|
355
|
|
|
356 @item source
|
|
|
357 Log optimizations manipulating the source code only.
|
|
|
358
|
|
|
359 @item byte
|
|
|
360 Log optimizations manipulating the byte code (actually, LAP code) only.
|
|
|
361 @end table
|
|
|
362 Default: @code{nil}.
|
|
|
363 @end defvar
|
|
|
364
|
|
|
365 @defvar byte-compile-error-on-warn
|
|
|
366 When non-@code{nil}, the byte-compiler reports warnings with @code{error}.
|
|
|
367 Default: @code{nil}.
|
|
|
368 @end defvar
|
|
|
369
|
|
|
370 @defvar byte-compile-default-warnings
|
|
|
371 The warnings used when @code{byte-compile-warnings} is @code{t}. Called
|
|
|
372 @code{byte-compile-warning-types} in GNU Emacs.
|
|
|
373 Default: @code{(redefine callargs subr-callargs free-vars unresolved
|
|
|
374 unused-vars obsolete)}.
|
|
|
375 @end defvar
|
|
|
376
|
|
|
377 @defvar byte-compile-warnings
|
|
|
378
|
|
|
379 List of warnings that the compiler should issue (@code{t} for the
|
|
|
380 default set). Elements of the list may be:
|
|
|
381
|
|
|
382 @table @code
|
|
|
383 @item free-vars
|
|
|
384 References to variables not in the current lexical scope.
|
|
|
385
|
|
|
386 @item unused-vars
|
|
|
387 References to non-global variables bound but not referenced.
|
|
|
388
|
|
|
389 @item unresolved
|
|
|
390 Calls to unknown functions.
|
|
|
391
|
|
|
392 @item callargs
|
|
|
393 Lambda calls with args that don't match the definition.
|
|
|
394
|
|
|
395 @item subr-callargs
|
|
|
396 Calls to subrs with args that don't match the definition.
|
|
|
397
|
|
|
398 @item redefine
|
|
|
399 Function cell redefined from a macro to a lambda or vice
|
|
|
400 versa, or redefined to take a different number of arguments.
|
|
|
401
|
|
|
402 @item obsolete
|
|
|
403 Use of an obsolete function or variable.
|
|
|
404
|
|
|
405 @item pedantic
|
|
|
406 Warn of use of compatible symbols.
|
|
|
407 @end table
|
|
|
408
|
|
|
409 The default set is specified by @code{byte-compile-default-warnings} and
|
|
|
410 normally encompasses all possible warnings.
|
|
|
411
|
|
|
412 See also the macro @code{byte-compiler-options}. Default: @code{t}.
|
|
|
413 @end defvar
|
|
|
414
|
|
|
415 The compiler can generate a call graph, which gives information about
|
|
|
416 which functions call which functions.
|
|
|
417
|
|
|
418 @defvar byte-compile-generate-call-tree
|
|
|
419 When non-@code{nil}, the compiler generates a call graph. This records
|
|
|
420 functions that were called and from where. If the value is @code{t},
|
|
|
421 compilation displays the call graph when it finishes. If the value is
|
|
|
422 neither @code{t} nor @code{nil}, compilation asks you whether to display
|
|
|
423 the graph.
|
|
|
424
|
|
|
425 The call tree only lists functions called, not macros used. Those
|
|
|
426 functions which the byte-code interpreter knows about directly
|
|
|
427 (@code{eq}, @code{cons}, etc.) are not reported.
|
|
|
428
|
|
|
429 The call tree also lists those functions which are not known to be called
|
|
|
430 (that is, to which no calls have been compiled). Functions which can be
|
|
|
431 invoked interactively are excluded from this list. Default: @code{nil}.
|
|
|
432 @end defvar
|
|
|
433
|
|
|
434 @defvar byte-compile-call-tree nil
|
|
|
435
|
|
|
436 Alist of functions and their call tree, used internally.
|
|
|
437 Each element takes the form
|
|
|
438
|
|
|
439 (@var{function} @var{callers} @var{calls})
|
|
|
440
|
|
|
441 where @var{callers} is a list of functions that call @var{function}, and
|
|
|
442 @var{calls} is a list of functions for which calls were generated while
|
|
|
443 compiling @var{function}.
|
|
|
444 @end defvar
|
|
|
445
|
|
|
446 @defvar byte-compile-call-tree-sort
|
|
|
447 When non-@code{nil}, sort the call tree. The values @code{name},
|
|
|
448 @code{callers}, @code{calls}, and @code{calls+callers} specify different
|
|
|
449 fields to sort on.") Default: @code{name}.
|
|
|
450 @end defvar
|
|
|
451
|
|
|
452 @code{byte-compile-overwrite-file} controls treatment of existing
|
|
|
453 compiled files.
|
|
|
454
|
|
|
455 @defvar byte-compile-overwrite-file
|
|
|
456 When non-@code{nil}, do not preserve backups of @file{.elc}s.
|
|
|
457 Precisely, if @code{nil}, old @file{.elc} files are deleted before the
|
|
|
458 new one is saved, and @file{.elc} files will have the same modes as the
|
|
|
459 corresponding @file{.el} file. Otherwise, existing @file{.elc} files
|
|
|
460 will simply be overwritten, and the existing modes will not be changed.
|
|
|
461 If this variable is @code{nil}, then an @file{.elc} file which is a
|
|
|
462 symbolic link will be turned into a normal file, instead of the file
|
|
|
463 which the link points to being overwritten. Default: @code{t}.
|
|
|
464 @end defvar
|
|
|
465
|
|
|
466 Variables controlling recompiling directories are described elsewhere
|
|
|
467 @xref{Compilation Functions}. They are
|
|
|
468 @code{byte-recompile-directory-ignore-errors-p} and
|
|
|
469 @code{byte-recompile-directory-recursively}.
|
|
|
470
|
|
|
471 The dynamic loading features are described elsewhere. These are
|
|
|
472 controlled by the variables @code{byte-compile-dynamic} (@pxref{Dynamic
|
|
|
473 Loading}) and @code{byte-compile-dynamic-docstrings} (@pxref{Docs and
|
|
|
474 Compilation}).
|
|
|
475
|
|
|
476 The byte compiler is a relatively recent development, and has evolved
|
|
|
477 significantly over the period covering Emacs versions 19 and 20. The
|
|
|
478 following variables control use of newer functionality by the byte
|
|
|
479 compiler. These are rarely needed since the release of XEmacs 21.
|
|
|
480
|
|
|
481 Another set of compatibility issues arises between Mule and non-Mule
|
|
|
482 XEmacsen; there are no known compatibility issues specific to the byte
|
|
|
483 compiler. There are also compatibility issues between XEmacs and GNU
|
|
|
484 Emacs's versions of the byte compiler. While almost all of the byte
|
|
|
485 codes are the same, and code compiled by one version often runs
|
|
|
486 perfectly well on the other, this is very dangerous, and can result in
|
|
|
487 crashes or data loss. Always recompile your Lisp when moving between
|
|
|
488 XEmacs and GNU Emacs.
|
|
|
489
|
|
|
490 @defvar byte-compile-single-version nil
|
|
|
491 When non-@code{nil}, the choice of emacs version (v19 or v20) byte-codes
|
|
|
492 will be hard-coded into bytecomp when it compiles itself. If the
|
|
|
493 compiler itself is compiled with optimization, this causes a speedup.
|
|
|
494 Default: @code{nil}.
|
|
|
495 @end defvar
|
|
|
496
|
|
|
497 @defvar byte-compile-emacs19-compatibility
|
|
|
498 When non-@code{nil} generate output that can run in Emacs 19.
|
|
|
499 Default: @code{nil} when Emacs version is 20 or above, otherwise
|
|
|
500 @code{t}.
|
|
|
501 @end defvar
|
|
|
502
|
|
|
503 @defvar byte-compile-print-gensym
|
|
|
504 When non-@code{nil}, the compiler may generate code that creates unique
|
|
|
505 symbols at run-time. This is achieved by printing uninterned symbols
|
|
2960
|
506 using the @code{#:@var{symbol}} notation, so that they will be read
|
|
2949
|
507 uninterned when run.
|
|
1103
|
508
|
|
|
509 With this feature, code that uses uninterned symbols in macros will
|
|
|
510 not be runnable under pre-21.0 XEmacsen.
|
|
|
511
|
|
|
512 Default: When @code{byte-compile-emacs19-compatibility} is non-nil, this
|
|
|
513 variable is ignored and considered to be @code{nil}. Otherwise
|
|
|
514 @code{t}.
|
|
|
515 @end defvar
|
|
|
516
|
|
|
517 @defvar byte-compile-new-bytecodes
|
|
|
518 This is completely ignored. For backwards compatibility.
|
|
|
519 @end defvar
|
|
|
520
|
|
|
521 @defun byte-compiler-options &rest args
|
|
|
522 Set some compilation-parameters for this file.
|
|
|
523 This will affect only the file in which it appears; this does nothing when
|
|
|
524 evaluated, or when loaded from a @file{.el} file.
|
|
|
525
|
|
|
526 Each argument to this macro must be a list of a key and a value.
|
|
|
527 (#### Need to check whether the newer variables are settable here.)
|
|
|
528
|
|
|
529 @example
|
|
|
530 Keys: Values: Corresponding variable:
|
|
|
531
|
|
|
532 verbose t, nil byte-compile-verbose
|
|
|
533 optimize t, nil, source, byte byte-optimize
|
|
|
534 warnings list of warnings byte-compile-warnings
|
|
|
535 file-format emacs19, emacs20 byte-compile-emacs19-compatibility
|
|
|
536 @end example
|
|
|
537
|
|
|
538 The value specified with the @code{warnings}option must be a list,
|
|
|
539 containing some subset of the following flags:
|
|
|
540
|
|
|
541 @example
|
|
|
542 free-vars references to variables not in the current lexical scope.
|
|
|
543 unused-vars references to non-global variables bound but not referenced.
|
|
|
544 unresolved calls to unknown functions.
|
|
|
545 callargs lambda calls with args that don't match the definition.
|
|
|
546 redefine function cell redefined from a macro to a lambda or vice
|
|
|
547 versa, or redefined to take a different number of arguments.
|
|
|
548 @end example
|
|
|
549
|
|
|
550 If the first element if the list is @code{+} or `@code{} then the
|
|
|
551 specified elements are added to or removed from the current set of
|
|
|
552 warnings, instead of the entire set of warnings being overwritten.
|
|
|
553 (#### Need to check whether the newer warnings are settable here.)
|
|
|
554
|
|
|
555 For example, something like this might appear at the top of a source file:
|
|
|
556
|
|
|
557 @example
|
|
|
558 (byte-compiler-options
|
|
|
559 (optimize t)
|
|
|
560 (warnings (- callargs)) ; Don't warn about arglist mismatch
|
|
|
561 (warnings (+ unused-vars)) ; Do warn about unused bindings
|
|
|
562 (file-format emacs19))
|
|
|
563 @end example
|
|
|
564 @end defun
|
|
|
565
|
|
428
|
566 @node Docs and Compilation
|
|
|
567 @section Documentation Strings and Compilation
|
|
|
568 @cindex dynamic loading of documentation
|
|
|
569
|
|
|
570 Functions and variables loaded from a byte-compiled file access their
|
|
|
571 documentation strings dynamically from the file whenever needed. This
|
|
|
572 saves space within Emacs, and makes loading faster because the
|
|
|
573 documentation strings themselves need not be processed while loading the
|
|
|
574 file. Actual access to the documentation strings becomes slower as a
|
|
|
575 result, but normally not enough to bother users.
|
|
|
576
|
|
|
577 Dynamic access to documentation strings does have drawbacks:
|
|
|
578
|
|
|
579 @itemize @bullet
|
|
|
580 @item
|
|
|
581 If you delete or move the compiled file after loading it, Emacs can no
|
|
|
582 longer access the documentation strings for the functions and variables
|
|
|
583 in the file.
|
|
|
584
|
|
|
585 @item
|
|
|
586 If you alter the compiled file (such as by compiling a new version),
|
|
|
587 then further access to documentation strings in this file will give
|
|
|
588 nonsense results.
|
|
|
589 @end itemize
|
|
|
590
|
|
|
591 If your site installs Emacs following the usual procedures, these
|
|
|
592 problems will never normally occur. Installing a new version uses a new
|
|
|
593 directory with a different name; as long as the old version remains
|
|
|
594 installed, its files will remain unmodified in the places where they are
|
|
|
595 expected to be.
|
|
|
596
|
|
|
597 However, if you have built Emacs yourself and use it from the
|
|
|
598 directory where you built it, you will experience this problem
|
|
|
599 occasionally if you edit and recompile Lisp files. When it happens, you
|
|
|
600 can cure the problem by reloading the file after recompiling it.
|
|
|
601
|
|
|
602 Versions of Emacs up to and including XEmacs 19.14 and FSF Emacs 19.28
|
|
|
603 do not support the dynamic docstrings feature, and so will not be able
|
|
|
604 to load bytecode created by more recent Emacs versions. You can turn
|
|
|
605 off the dynamic docstring feature by setting
|
|
|
606 @code{byte-compile-dynamic-docstrings} to @code{nil}. Once this is
|
|
|
607 done, you can compile files that will load into older Emacs versions.
|
|
|
608 You can do this globally, or for one source file by specifying a
|
|
|
609 file-local binding for the variable. Here's one way to do that:
|
|
|
610
|
|
|
611 @example
|
|
|
612 -*-byte-compile-dynamic-docstrings: nil;-*-
|
|
|
613 @end example
|
|
|
614
|
|
|
615 @defvar byte-compile-dynamic-docstrings
|
|
|
616 If this is non-@code{nil}, the byte compiler generates compiled files
|
|
|
617 that are set up for dynamic loading of documentation strings.
|
|
1103
|
618 Default: t.
|
|
428
|
619 @end defvar
|
|
|
620
|
|
|
621 @cindex @samp{#@@@var{count}}
|
|
|
622 @cindex @samp{#$}
|
|
|
623 The dynamic documentation string feature writes compiled files that
|
|
|
624 use a special Lisp reader construct, @samp{#@@@var{count}}. This
|
|
|
625 construct skips the next @var{count} characters. It also uses the
|
|
|
626 @samp{#$} construct, which stands for ``the name of this file, as a
|
|
|
627 string.'' It is best not to use these constructs in Lisp source files.
|
|
|
628
|
|
|
629 @node Dynamic Loading
|
|
|
630 @section Dynamic Loading of Individual Functions
|
|
|
631
|
|
|
632 @cindex dynamic loading of functions
|
|
|
633 @cindex lazy loading
|
|
|
634 When you compile a file, you can optionally enable the @dfn{dynamic
|
|
|
635 function loading} feature (also known as @dfn{lazy loading}). With
|
|
|
636 dynamic function loading, loading the file doesn't fully read the
|
|
|
637 function definitions in the file. Instead, each function definition
|
|
|
638 contains a place-holder which refers to the file. The first time each
|
|
|
639 function is called, it reads the full definition from the file, to
|
|
|
640 replace the place-holder.
|
|
|
641
|
|
|
642 The advantage of dynamic function loading is that loading the file
|
|
|
643 becomes much faster. This is a good thing for a file which contains
|
|
|
644 many separate commands, provided that using one of them does not imply
|
|
|
645 you will soon (or ever) use the rest. A specialized mode which provides
|
|
|
646 many keyboard commands often has that usage pattern: a user may invoke
|
|
|
647 the mode, but use only a few of the commands it provides.
|
|
|
648
|
|
|
649 The dynamic loading feature has certain disadvantages:
|
|
|
650
|
|
|
651 @itemize @bullet
|
|
|
652 @item
|
|
|
653 If you delete or move the compiled file after loading it, Emacs can no
|
|
|
654 longer load the remaining function definitions not already loaded.
|
|
|
655
|
|
|
656 @item
|
|
|
657 If you alter the compiled file (such as by compiling a new version),
|
|
|
658 then trying to load any function not already loaded will get nonsense
|
|
|
659 results.
|
|
|
660 @end itemize
|
|
|
661
|
|
|
662 If you compile a new version of the file, the best thing to do is
|
|
|
663 immediately load the new compiled file. That will prevent any future
|
|
|
664 problems.
|
|
|
665
|
|
|
666 The byte compiler uses the dynamic function loading feature if the
|
|
|
667 variable @code{byte-compile-dynamic} is non-@code{nil} at compilation
|
|
|
668 time. Do not set this variable globally, since dynamic loading is
|
|
|
669 desirable only for certain files. Instead, enable the feature for
|
|
|
670 specific source files with file-local variable bindings, like this:
|
|
|
671
|
|
|
672 @example
|
|
|
673 -*-byte-compile-dynamic: t;-*-
|
|
|
674 @end example
|
|
|
675
|
|
|
676 @defvar byte-compile-dynamic
|
|
|
677 If this is non-@code{nil}, the byte compiler generates compiled files
|
|
|
678 that are set up for dynamic function loading.
|
|
1103
|
679 Default: nil.
|
|
428
|
680 @end defvar
|
|
|
681
|
|
|
682 @defun fetch-bytecode function
|
|
|
683 This immediately finishes loading the definition of @var{function} from
|
|
|
684 its byte-compiled file, if it is not fully loaded already. The argument
|
|
|
685 @var{function} may be a compiled-function object or a function name.
|
|
|
686 @end defun
|
|
|
687
|
|
|
688 @node Eval During Compile
|
|
|
689 @section Evaluation During Compilation
|
|
|
690
|
|
|
691 These features permit you to write code to be evaluated during
|
|
|
692 compilation of a program.
|
|
|
693
|
|
|
694 @defspec eval-and-compile body
|
|
|
695 This form marks @var{body} to be evaluated both when you compile the
|
|
|
696 containing code and when you run it (whether compiled or not).
|
|
|
697
|
|
|
698 You can get a similar result by putting @var{body} in a separate file
|
|
|
699 and referring to that file with @code{require}. Using @code{require} is
|
|
|
700 preferable if there is a substantial amount of code to be executed in
|
|
|
701 this way.
|
|
|
702 @end defspec
|
|
|
703
|
|
|
704 @defspec eval-when-compile body
|
|
|
705 This form marks @var{body} to be evaluated at compile time and not when
|
|
|
706 the compiled program is loaded. The result of evaluation by the
|
|
|
707 compiler becomes a constant which appears in the compiled program. When
|
|
|
708 the program is interpreted, not compiled at all, @var{body} is evaluated
|
|
|
709 normally.
|
|
|
710
|
|
|
711 At top level, this is analogous to the Common Lisp idiom
|
|
|
712 @code{(eval-when (compile eval) @dots{})}. Elsewhere, the Common Lisp
|
|
|
713 @samp{#.} reader macro (but not when interpreting) is closer to what
|
|
|
714 @code{eval-when-compile} does.
|
|
|
715 @end defspec
|
|
|
716
|
|
|
717 @node Compiled-Function Objects
|
|
|
718 @section Compiled-Function Objects
|
|
|
719 @cindex compiled function
|
|
|
720 @cindex byte-code function
|
|
|
721
|
|
|
722 Byte-compiled functions have a special data type: they are
|
|
|
723 @dfn{compiled-function objects}. The evaluator handles this data type
|
|
|
724 specially when it appears as a function to be called.
|
|
|
725
|
|
|
726 The printed representation for a compiled-function object normally
|
|
|
727 begins with @samp{#<compiled-function} and ends with @samp{>}. However,
|
|
|
728 if the variable @code{print-readably} is non-@code{nil}, the object is
|
|
|
729 printed beginning with @samp{#[} and ending with @samp{]}. This
|
|
|
730 representation can be read directly by the Lisp reader, and is used in
|
|
|
731 byte-compiled files (those ending in @samp{.elc}).
|
|
|
732
|
|
|
733 In Emacs version 18, there was no compiled-function object data type;
|
|
|
734 compiled functions used the function @code{byte-code} to run the byte
|
|
|
735 code.
|
|
|
736
|
|
|
737 A compiled-function object has a number of different attributes.
|
|
|
738 They are:
|
|
|
739
|
|
|
740 @table @var
|
|
|
741 @item arglist
|
|
|
742 The list of argument symbols.
|
|
|
743
|
|
|
744 @item instructions
|
|
|
745 The string containing the byte-code instructions.
|
|
|
746
|
|
|
747 @item constants
|
|
|
748 The vector of Lisp objects referenced by the byte code. These include
|
|
|
749 symbols used as function names and variable names.
|
|
|
750
|
|
444
|
751 @item stack-depth
|
|
428
|
752 The maximum stack size this function needs.
|
|
|
753
|
|
|
754 @item doc-string
|
|
|
755 The documentation string (if any); otherwise, @code{nil}. The value may
|
|
|
756 be a number or a list, in case the documentation string is stored in a
|
|
|
757 file. Use the function @code{documentation} to get the real
|
|
|
758 documentation string (@pxref{Accessing Documentation}).
|
|
|
759
|
|
|
760 @item interactive
|
|
|
761 The interactive spec (if any). This can be a string or a Lisp
|
|
|
762 expression. It is @code{nil} for a function that isn't interactive.
|
|
|
763
|
|
|
764 @item domain
|
|
|
765 The domain (if any). This is only meaningful if I18N3 (message-translation)
|
|
|
766 support was compiled into XEmacs. This is a string defining which
|
|
|
767 domain to find the translation for the documentation string and
|
|
|
768 interactive prompt. @xref{Domain Specification}.
|
|
|
769 @end table
|
|
|
770
|
|
|
771 Here's an example of a compiled-function object, in printed
|
|
|
772 representation. It is the definition of the command
|
|
|
773 @code{backward-sexp}.
|
|
|
774
|
|
|
775 @example
|
|
|
776 (symbol-function 'backward-sexp)
|
|
|
777 @result{} #<compiled-function
|
|
|
778 (&optional arg)
|
|
|
779 "...(15)" [arg 1 forward-sexp] 2 854740 "_p">
|
|
|
780 @end example
|
|
|
781
|
|
|
782 The primitive way to create a compiled-function object is with
|
|
|
783 @code{make-byte-code}:
|
|
|
784
|
|
444
|
785 @defun make-byte-code arglist instructions constants stack-depth &optional doc-string interactive
|
|
428
|
786 This function constructs and returns a compiled-function object
|
|
|
787 with the specified attributes.
|
|
|
788
|
|
|
789 @emph{Please note:} Unlike all other Emacs-lisp functions, calling this with
|
|
|
790 five arguments is @emph{not} the same as calling it with six arguments,
|
|
|
791 the last of which is @code{nil}. If the @var{interactive} arg is
|
|
|
792 specified as @code{nil}, then that means that this function was defined
|
|
|
793 with @code{(interactive)}. If the arg is not specified, then that means
|
|
|
794 the function is not interactive. This is terrible behavior which is
|
|
|
795 retained for compatibility with old @samp{.elc} files which expected
|
|
|
796 these semantics.
|
|
|
797 @end defun
|
|
|
798
|
|
|
799 You should not try to come up with the elements for a compiled-function
|
|
|
800 object yourself, because if they are inconsistent, XEmacs may crash
|
|
|
801 when you call the function. Always leave it to the byte compiler to
|
|
|
802 create these objects; it makes the elements consistent (we hope).
|
|
|
803
|
|
|
804 The following primitives are provided for accessing the elements of
|
|
|
805 a compiled-function object.
|
|
|
806
|
|
|
807 @defun compiled-function-arglist function
|
|
|
808 This function returns the argument list of compiled-function object
|
|
|
809 @var{function}.
|
|
|
810 @end defun
|
|
|
811
|
|
|
812 @defun compiled-function-instructions function
|
|
|
813 This function returns a string describing the byte-code instructions
|
|
|
814 of compiled-function object @var{function}.
|
|
|
815 @end defun
|
|
|
816
|
|
|
817 @defun compiled-function-constants function
|
|
|
818 This function returns the vector of Lisp objects referenced by
|
|
|
819 compiled-function object @var{function}.
|
|
|
820 @end defun
|
|
|
821
|
|
444
|
822 @defun compiled-function-stack-depth function
|
|
428
|
823 This function returns the maximum stack size needed by compiled-function
|
|
|
824 object @var{function}.
|
|
|
825 @end defun
|
|
|
826
|
|
|
827 @defun compiled-function-doc-string function
|
|
|
828 This function returns the doc string of compiled-function object
|
|
|
829 @var{function}, if available.
|
|
|
830 @end defun
|
|
|
831
|
|
|
832 @defun compiled-function-interactive function
|
|
|
833 This function returns the interactive spec of compiled-function object
|
|
|
834 @var{function}, if any. The return value is @code{nil} or a two-element
|
|
|
835 list, the first element of which is the symbol @code{interactive} and
|
|
|
836 the second element is the interactive spec (a string or Lisp form).
|
|
|
837 @end defun
|
|
|
838
|
|
|
839 @defun compiled-function-domain function
|
|
|
840 This function returns the domain of compiled-function object
|
|
|
841 @var{function}, if any. The result will be a string or @code{nil}.
|
|
|
842 @xref{Domain Specification}.
|
|
|
843 @end defun
|
|
|
844
|
|
|
845 @node Disassembly
|
|
|
846 @section Disassembled Byte-Code
|
|
|
847 @cindex disassembled byte-code
|
|
|
848
|
|
|
849 People do not write byte-code; that job is left to the byte compiler.
|
|
|
850 But we provide a disassembler to satisfy a cat-like curiosity. The
|
|
|
851 disassembler converts the byte-compiled code into humanly readable
|
|
|
852 form.
|
|
|
853
|
|
|
854 The byte-code interpreter is implemented as a simple stack machine.
|
|
|
855 It pushes values onto a stack of its own, then pops them off to use them
|
|
|
856 in calculations whose results are themselves pushed back on the stack.
|
|
|
857 When a byte-code function returns, it pops a value off the stack and
|
|
|
858 returns it as the value of the function.
|
|
|
859
|
|
|
860 In addition to the stack, byte-code functions can use, bind, and set
|
|
|
861 ordinary Lisp variables, by transferring values between variables and
|
|
|
862 the stack.
|
|
|
863
|
|
|
864 @deffn Command disassemble object &optional stream
|
|
|
865 This function prints the disassembled code for @var{object}. If
|
|
|
866 @var{stream} is supplied, then output goes there. Otherwise, the
|
|
|
867 disassembled code is printed to the stream @code{standard-output}. The
|
|
|
868 argument @var{object} can be a function name or a lambda expression.
|
|
|
869
|
|
|
870 As a special exception, if this function is used interactively,
|
|
|
871 it outputs to a buffer named @samp{*Disassemble*}.
|
|
|
872 @end deffn
|
|
|
873
|
|
|
874 Here are two examples of using the @code{disassemble} function. We
|
|
|
875 have added explanatory comments to help you relate the byte-code to the
|
|
|
876 Lisp source; these do not appear in the output of @code{disassemble}.
|
|
|
877
|
|
|
878 @example
|
|
|
879 @group
|
|
|
880 (defun factorial (integer)
|
|
|
881 "Compute factorial of an integer."
|
|
|
882 (if (= 1 integer) 1
|
|
|
883 (* integer (factorial (1- integer)))))
|
|
|
884 @result{} factorial
|
|
|
885 @end group
|
|
|
886
|
|
|
887 @group
|
|
|
888 (factorial 4)
|
|
|
889 @result{} 24
|
|
|
890 @end group
|
|
|
891
|
|
|
892 @group
|
|
|
893 (disassemble 'factorial)
|
|
|
894 @print{} byte-code for factorial:
|
|
|
895 doc: Compute factorial of an integer.
|
|
|
896 args: (integer)
|
|
|
897 @end group
|
|
|
898
|
|
|
899 @group
|
|
|
900 0 varref integer ; @r{Get value of @code{integer}}
|
|
|
901 ; @r{from the environment}
|
|
|
902 ; @r{and push the value}
|
|
|
903 ; @r{onto the stack.}
|
|
|
904
|
|
|
905 1 constant 1 ; @r{Push 1 onto stack.}
|
|
|
906 @end group
|
|
|
907
|
|
|
908 @group
|
|
|
909 2 eqlsign ; @r{Pop top two values off stack,}
|
|
|
910 ; @r{compare them,}
|
|
|
911 ; @r{and push result onto stack.}
|
|
|
912 @end group
|
|
|
913
|
|
|
914 @group
|
|
|
915 3 goto-if-nil 1 ; @r{Pop and test top of stack;}
|
|
|
916 ; @r{if @code{nil},}
|
|
|
917 ; @r{go to label 1 (which is also byte 7),}
|
|
|
918 ; @r{else continue.}
|
|
|
919 @end group
|
|
|
920
|
|
|
921 @group
|
|
|
922 5 constant 1 ; @r{Push 1 onto top of stack.}
|
|
|
923
|
|
|
924 6 return ; @r{Return the top element}
|
|
|
925 ; @r{of the stack.}
|
|
|
926 @end group
|
|
|
927
|
|
|
928 7:1 varref integer ; @r{Push value of @code{integer} onto stack.}
|
|
|
929
|
|
|
930 @group
|
|
|
931 8 constant factorial ; @r{Push @code{factorial} onto stack.}
|
|
|
932
|
|
|
933 9 varref integer ; @r{Push value of @code{integer} onto stack.}
|
|
|
934
|
|
|
935 10 sub1 ; @r{Pop @code{integer}, decrement value,}
|
|
|
936 ; @r{push new value onto stack.}
|
|
|
937 @end group
|
|
|
938
|
|
|
939 @group
|
|
|
940 ; @r{Stack now contains:}
|
|
|
941 ; @minus{} @r{decremented value of @code{integer}}
|
|
|
942 ; @minus{} @r{@code{factorial}}
|
|
|
943 ; @minus{} @r{value of @code{integer}}
|
|
|
944 @end group
|
|
|
945
|
|
|
946 @group
|
|
|
947 15 call 1 ; @r{Call function @code{factorial} using}
|
|
|
948 ; @r{the first (i.e., the top) element}
|
|
|
949 ; @r{of the stack as the argument;}
|
|
|
950 ; @r{push returned value onto stack.}
|
|
|
951 @end group
|
|
|
952
|
|
|
953 @group
|
|
|
954 ; @r{Stack now contains:}
|
|
|
955 ; @minus{} @r{result of recursive}
|
|
|
956 ; @r{call to @code{factorial}}
|
|
|
957 ; @minus{} @r{value of @code{integer}}
|
|
|
958 @end group
|
|
|
959
|
|
|
960 @group
|
|
|
961 12 mult ; @r{Pop top two values off the stack,}
|
|
|
962 ; @r{multiply them,}
|
|
|
963 ; @r{pushing the result onto the stack.}
|
|
|
964 @end group
|
|
|
965
|
|
|
966 @group
|
|
|
967 13 return ; @r{Return the top element}
|
|
|
968 ; @r{of the stack.}
|
|
|
969 @result{} nil
|
|
|
970 @end group
|
|
|
971 @end example
|
|
|
972
|
|
|
973 The @code{silly-loop} function is somewhat more complex:
|
|
|
974
|
|
|
975 @example
|
|
|
976 @group
|
|
|
977 (defun silly-loop (n)
|
|
|
978 "Return time before and after N iterations of a loop."
|
|
|
979 (let ((t1 (current-time-string)))
|
|
|
980 (while (> (setq n (1- n))
|
|
|
981 0))
|
|
|
982 (list t1 (current-time-string))))
|
|
|
983 @result{} silly-loop
|
|
|
984 @end group
|
|
|
985
|
|
|
986 @group
|
|
|
987 (disassemble 'silly-loop)
|
|
|
988 @print{} byte-code for silly-loop:
|
|
|
989 doc: Return time before and after N iterations of a loop.
|
|
|
990 args: (n)
|
|
|
991
|
|
|
992 0 constant current-time-string ; @r{Push}
|
|
|
993 ; @r{@code{current-time-string}}
|
|
|
994 ; @r{onto top of stack.}
|
|
|
995 @end group
|
|
|
996
|
|
|
997 @group
|
|
|
998 1 call 0 ; @r{Call @code{current-time-string}}
|
|
|
999 ; @r{ with no argument,}
|
|
|
1000 ; @r{ pushing result onto stack.}
|
|
|
1001 @end group
|
|
|
1002
|
|
|
1003 @group
|
|
|
1004 2 varbind t1 ; @r{Pop stack and bind @code{t1}}
|
|
|
1005 ; @r{to popped value.}
|
|
|
1006 @end group
|
|
|
1007
|
|
|
1008 @group
|
|
|
1009 3:1 varref n ; @r{Get value of @code{n} from}
|
|
|
1010 ; @r{the environment and push}
|
|
|
1011 ; @r{the value onto the stack.}
|
|
|
1012 @end group
|
|
|
1013
|
|
|
1014 @group
|
|
|
1015 4 sub1 ; @r{Subtract 1 from top of stack.}
|
|
|
1016 @end group
|
|
|
1017
|
|
|
1018 @group
|
|
|
1019 5 dup ; @r{Duplicate the top of the stack;}
|
|
|
1020 ; @r{i.e., copy the top of}
|
|
|
1021 ; @r{the stack and push the}
|
|
|
1022 ; @r{copy onto the stack.}
|
|
|
1023
|
|
|
1024 6 varset n ; @r{Pop the top of the stack,}
|
|
|
1025 ; @r{and set @code{n} to the value.}
|
|
|
1026
|
|
|
1027 ; @r{In effect, the sequence @code{dup varset}}
|
|
|
1028 ; @r{copies the top of the stack}
|
|
|
1029 ; @r{into the value of @code{n}}
|
|
|
1030 ; @r{without popping it.}
|
|
|
1031 @end group
|
|
|
1032
|
|
|
1033 @group
|
|
|
1034 7 constant 0 ; @r{Push 0 onto stack.}
|
|
|
1035
|
|
|
1036 8 gtr ; @r{Pop top two values off stack,}
|
|
|
1037 ; @r{test if @var{n} is greater than 0}
|
|
|
1038 ; @r{and push result onto stack.}
|
|
|
1039 @end group
|
|
|
1040
|
|
|
1041 @group
|
|
|
1042 9 goto-if-not-nil 1 ; @r{Goto label 1 (byte 3) if @code{n} <= 0}
|
|
|
1043 ; @r{(this exits the while loop).}
|
|
|
1044 ; @r{else pop top of stack}
|
|
|
1045 ; @r{and continue}
|
|
|
1046 @end group
|
|
|
1047
|
|
|
1048 @group
|
|
|
1049 11 varref t1 ; @r{Push value of @code{t1} onto stack.}
|
|
|
1050 @end group
|
|
|
1051
|
|
|
1052 @group
|
|
|
1053 12 constant current-time-string ; @r{Push}
|
|
|
1054 ; @r{@code{current-time-string}}
|
|
|
1055 ; @r{onto top of stack.}
|
|
|
1056 @end group
|
|
|
1057
|
|
|
1058 @group
|
|
|
1059 13 call 0 ; @r{Call @code{current-time-string} again.}
|
|
|
1060
|
|
|
1061 14 unbind 1 ; @r{Unbind @code{t1} in local environment.}
|
|
|
1062 @end group
|
|
|
1063
|
|
|
1064 @group
|
|
|
1065 15 list2 ; @r{Pop top two elements off stack,}
|
|
|
1066 ; @r{create a list of them,}
|
|
|
1067 ; @r{and push list onto stack.}
|
|
|
1068 @end group
|
|
|
1069
|
|
|
1070 @group
|
|
|
1071 16 return ; @r{Return the top element of the stack.}
|
|
|
1072
|
|
|
1073 @result{} nil
|
|
|
1074 @end group
|
|
|
1075 @end example
|
|
|
1076
|
|
|
1077
|
|
446
|
1078 @node Different Behavior
|
|
|
1079 @section Different Behavior
|
|
|
1080
|
|
|
1081 The intent is that compiled byte-code and the corresponding code
|
|
|
1082 executed by the Lisp interpreter produce identical results. However,
|
|
|
1083 there are some circumstances where the results will differ.
|
|
|
1084
|
|
|
1085 @itemize @bullet
|
|
|
1086 @item
|
|
|
1087 Arithmetic operations may be rearranged for efficiency or compile-time
|
|
|
1088 evaluation. When floating point numbers are involved, this may produce
|
|
|
1089 different values or an overflow.
|
|
|
1090 @item
|
|
|
1091 Some arithmetic operations may be optimized away. For example, the
|
|
|
1092 expression @code{(+ x)} may be optimized to simply @code{x}. If the
|
|
|
1093 value of @code{x} is a marker, then the value will be a marker instead
|
|
|
1094 of an integer. If the value of @samp{x} is a cons cell, then the
|
|
|
1095 interpreter will issue an error, while the bytecode will not.
|
|
|
1096
|
|
|
1097 If you're trying to use @samp{(+ @var{object} 0)} to convert
|
|
|
1098 @var{object} to integer, consider using an explicit conversion function,
|
|
|
1099 which is clearer and guaranteed to work.
|
|
|
1100 Instead of @samp{(+ @var{marker} 0)}, use @samp{(marker-position @var{marker})}.
|
|
|
1101 Instead of @samp{(+ @var{char} 0)}, use @samp{(char-int @var{char})}.
|
|
|
1102 @end itemize
|
|
|
1103
|
|
|
1104 For maximal equivalence between interpreted and compiled code, the
|
|
|
1105 variables @code{byte-compile-delete-errors} and
|
|
|
1106 @code{byte-compile-optimize} can be set to @code{nil}, but this is not
|
|
|
1107 recommended.
|
