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