lispref/compile.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Emacs Lisp Reference Manual.
   3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
   4 @c See the file elisp.texi for copying conditions.
   5 @setfilename ../info/compile
   6 @node Byte Compilation, Debugging, Loading, Top
   7 @chapter Byte Compilation
   8 @cindex byte-code
   9 @cindex compilation
  10
  11   GNU Emacs 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-code 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 Emacs 18, you can run the
  26 compiled code in Emacs 19, but not vice versa.
  27
  28   @xref{Compilation Errors}, for how to investigate errors occurring in
  29 byte compilation.
  30
  31 @menu
  32 * Speed of Byte-Code::          An example of speedup from byte compilation.
  33 * Compilation Functions::       Byte compilation functions.
  34 * Eval During Compile::         Code to be evaluated when you compile.
  35 * Byte-Code Objects::           The data type used for byte-compiled functions.
  36 * Disassembly::                 Disassembling byte-code; how to read byte-code.
  37 @end menu
  38
  39 @node Speed of Byte-Code
  40 @section Performance of Byte-Compiled Code
  41
  42   A byte-compiled function is not as efficient as a primitive function
  43 written in C, but runs much faster than the version written in Lisp.
  44 Here is an example:
  45
  46 @example
  47 @group
  48 (defun silly-loop (n)
  49   "Return time before and after N iterations of a loop."
  50   (let ((t1 (current-time-string)))
  51     (while (> (setq n (1- n))
  52               0))
  53     (list t1 (current-time-string))))
  54 @result{} silly-loop
  55 @end group
  56
  57 @group
  58 (silly-loop 100000)
  59 @result{} ("Fri Mar 18 17:25:57 1994"
  60     "Fri Mar 18 17:26:28 1994")  ; @r{31 seconds}
  61 @end group
  62
  63 @group
  64 (byte-compile 'silly-loop)
  65 @result{} @r{[Compiled code not shown]}
  66 @end group
  67
  68 @group
  69 (silly-loop 100000)
  70 @result{} ("Fri Mar 18 17:26:52 1994"
  71     "Fri Mar 18 17:26:58 1994")  ; @r{6 seconds}
  72 @end group
  73 @end example
  74
  75   In this example, the interpreted code required 31 seconds to run,
  76 whereas the byte-compiled code required 6 seconds.  These results are
  77 representative, but actual results will vary greatly.
  78
  79 @node Compilation Functions
  80 @comment  node-name,  next,  previous,  up
  81 @section The Compilation Functions
  82 @cindex compilation functions
  83
  84   You can byte-compile an individual function or macro definition with
  85 the @code{byte-compile} function.  You can compile a whole file with
  86 @code{byte-compile-file}, or several files with
  87 @code{byte-recompile-directory} or @code{batch-byte-compile}.
  88
  89   When you run the byte compiler, you may get warnings in a buffer
  90 called @samp{*Compile-Log*}.  These report things in your program that
  91 suggest a problem but are not necessarily erroneous.
  92
  93 @cindex macro compilation
  94   Be careful when byte-compiling code that uses macros.  Macro calls are
  95 expanded when they are compiled, so the macros must already be defined
  96 for proper compilation.  For more details, see @ref{Compiling Macros}.
  97
  98   Normally, compiling a file does not evaluate the file's contents or
  99 load the file.  But it does execute any @code{require} calls at
 100 top level in the file.  One way to ensure that necessary macro
 101 definitions are available during compilation is to require the file that
 102 defines them.  @xref{Features}.
 103
 104 @defun byte-compile symbol
 105 This function byte-compiles the function definition of @var{symbol},
 106 replacing the previous definition with the compiled one.  The function
 107 definition of @var{symbol} must be the actual code for the function;
 108 i.e., the compiler does not follow indirection to another symbol.
 109 @code{byte-compile} returns the new, compiled definition of
 110 @var{symbol}.
 111
 112 If @var{symbol}'s definition is a byte-code function object,
 113 @code{byte-compile} does nothing and returns @code{nil}.  Lisp records
 114 only one function definition for any symbol, and if that is already
 115 compiled, non-compiled code is not available anywhere.  So there is no
 116 way to ``compile the same definition again.''
 117
 118 @example
 119 @group
 120 (defun factorial (integer)
 121   "Compute factorial of INTEGER."
 122   (if (= 1 integer) 1
 123     (* integer (factorial (1- integer)))))
 124 @result{} factorial
 125 @end group
 126
 127 @group
 128 (byte-compile 'factorial)
 129 @result{}
 130 #[(integer)
 131   "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207"
 132   [integer 1 * factorial]
 133   4 "Compute factorial of INTEGER."]
 134 @end group
 135 @end example
 136
 137 @noindent
 138 The result is a byte-code function object.  The string it contains is
 139 the actual byte-code; each character in it is an instruction or an
 140 operand of an instruction.  The vector contains all the constants,
 141 variable names and function names used by the function, except for
 142 certain primitives that are coded as special instructions.
 143 @end defun
 144
 145 @deffn Command compile-defun
 146 This command reads the defun containing point, compiles it, and
 147 evaluates the result.  If you use this on a defun that is actually a
 148 function definition, the effect is to install a compiled version of that
 149 function.
 150 @end deffn
 151
 152 @deffn Command byte-compile-file filename
 153 This function compiles a file of Lisp code named @var{filename} into
 154 a file of byte-code.  The output file's name is made by appending
 155 @samp{c} to the end of @var{filename}.
 156
 157 Compilation works by reading the input file one form at a time.  If it
 158 is a definition of a function or macro, the compiled function or macro
 159 definition is written out.  Other forms are batched together, then each
 160 batch is compiled, and written so that its compiled code will be
 161 executed when the file is read.  All comments are discarded when the
 162 input file is read.
 163
 164 This command returns @code{t}.  When called interactively, it prompts
 165 for the file name.
 166
 167 @example
 168 @group
 169 % ls -l push*
 170 -rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
 171 @end group
 172
 173 @group
 174 (byte-compile-file "~/emacs/push.el")
 175      @result{} t
 176 @end group
 177
 178 @group
 179 % ls -l push*
 180 -rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
 181 -rw-rw-rw-  1 lewis     638 Oct  8 20:25 push.elc
 182 @end group
 183 @end example
 184 @end deffn
 185
 186 @deffn Command byte-recompile-directory directory flag
 187 @cindex library compilation
 188 This function recompiles every @samp{.el} file in @var{directory} that
 189 needs recompilation.  A file needs recompilation if a @samp{.elc} file
 190 exists but is older than the @samp{.el} file.
 191
 192 If a @samp{.el} file exists, but there is no corresponding @samp{.elc}
 193 file, then @var{flag} says what to do.  If it is @code{nil}, the file is
 194 ignored.  If it is non-@code{nil}, the user is asked whether to compile
 195 the file.
 196
 197 The returned value of this command is unpredictable.
 198 @end deffn
 199
 200 @defun batch-byte-compile
 201 This function runs @code{byte-compile-file} on files specified on the
 202 command line.  This function must be used only in a batch execution of
 203 Emacs, as it kills Emacs on completion.  An error in one file does not
 204 prevent processing of subsequent files.  (The file that gets the error
 205 will not, of course, produce any compiled code.)
 206
 207 @example
 208 % emacs -batch -f batch-byte-compile *.el
 209 @end example
 210 @end defun
 211
 212 @defun byte-code code-string data-vector max-stack
 213 @cindex byte-code interpreter
 214 This function actually interprets byte-code.  A byte-compiled function
 215 is actually defined with a body that calls @code{byte-code}.  Don't call
 216 this function yourself.  Only the byte compiler knows how to generate
 217 valid calls to this function.
 218
 219 In newer Emacs versions (19 and up), byte-code is usually executed as
 220 part of a byte-code function object, and only rarely due to an explicit
 221 call to @code{byte-code}.
 222 @end defun
 223
 224 @node Eval During Compile
 225 @section Evaluation During Compilation
 226
 227 These features permit you to write code to be evaluated during
 228 compilation of a program.
 229
 230 @defspec eval-and-compile body
 231 This form marks @var{body} to be evaluated both when you compile the
 232 containing code and when you run it (whether compiled or not).
 233
 234 You can get a similar result by putting @var{body} in a separate file
 235 and referring to that file with @code{require}.  Using @code{require} is
 236 preferable if there is a substantial amount of code to be executed in
 237 this way.
 238 @end defspec
 239
 240 @defspec eval-when-compile body
 241 This form marks @var{body} to be evaluated at compile time and not when
 242 the compiled program is loaded.  The result of evaluation by the
 243 compiler becomes a constant which appears in the compiled program.  When
 244 the program is interpreted, not compiled at all, @var{body} is evaluated
 245 normally.
 246
 247 At top level, this is analogous to the Common Lisp idiom
 248 @code{(eval-when (compile eval) @dots{})}.  Elsewhere, the Common Lisp
 249 @samp{#.} reader macro (but not when interpreting) is closer to what
 250 @code{eval-when-compile} does.
 251 @end defspec
 252
 253 @node Byte-Code Objects
 254 @section Byte-Code Objects
 255 @cindex compiled function
 256 @cindex byte-code function
 257
 258   Byte-compiled functions have a special data type: they are
 259 @dfn{byte-code function objects}.
 260
 261   Internally, a byte-code function object is much like a vector;
 262 however, the evaluator handles this data type specially when it appears
 263 as a function to be called.  The printed representation for a byte-code
 264 function object is like that for a vector, with an additional @samp{#}
 265 before the opening @samp{[}.
 266
 267   In Emacs version 18, there was no byte-code function object data type;
 268 compiled functions used the function @code{byte-code} to run the byte
 269 code.
 270
 271   A byte-code function object must have at least four elements; there is
 272 no maximum number, but only the first six elements are actually used.
 273 They are:
 274
 275 @table @var
 276 @item arglist
 277 The list of argument symbols.
 278
 279 @item byte-code
 280 The string containing the byte-code instructions.
 281
 282 @item constants
 283 The vector of Lisp objects referenced by the byte code.  These include
 284 symbols used as function names and variable names.
 285
 286 @item stacksize
 287 The maximum stack size this function needs.
 288
 289 @item docstring
 290 The documentation string (if any); otherwise, @code{nil}.  For functions
 291 preloaded before Emacs is dumped, this is usually an integer which is an
 292 index into the @file{DOC} file; use @code{documentation} to convert this
 293 into a string (@pxref{Accessing Documentation}).
 294
 295 @item interactive
 296 The interactive spec (if any).  This can be a string or a Lisp
 297 expression.  It is @code{nil} for a function that isn't interactive.
 298 @end table
 299
 300 Here's an example of a byte-code function object, in printed
 301 representation.  It is the definition of the command
 302 @code{backward-sexp}.
 303
 304 @example
 305 #[(&optional arg)
 306   "^H\204^F^@@\301^P\302^H[!\207"
 307   [arg 1 forward-sexp]
 308   2
 309   254435
 310   "p"]
 311 @end example
 312
 313   The primitive way to create a byte-code object is with
 314 @code{make-byte-code}:
 315
 316 @defun make-byte-code &rest elements
 317 This function constructs and returns a byte-code function object
 318 with @var{elements} as its elements.
 319 @end defun
 320
 321   You should not try to come up with the elements for a byte-code
 322 function yourself, because if they are inconsistent, Emacs may crash
 323 when you call the function.  Always leave it to the byte compiler to
 324 create these objects; it makes the elements consistent (we hope).
 325
 326   You can access the elements of a byte-code object using @code{aref};
 327 you can also use @code{vconcat} to create a vector with the same
 328 elements.
 329
 330 @node Disassembly
 331 @section Disassembled Byte-Code
 332 @cindex disassembled byte-code
 333
 334   People do not write byte-code; that job is left to the byte compiler.
 335 But we provide a disassembler to satisfy a cat-like curiosity.  The
 336 disassembler converts the byte-compiled code into humanly readable
 337 form.
 338
 339   The byte-code interpreter is implemented as a simple stack machine.
 340 It pushes values onto a stack of its own, then pops them off to use them
 341 in calculations whose results are themselves pushed back on the stack.
 342 When a byte-code function returns, it pops a value off the stack and
 343 returns it as the value of the function.
 344
 345   In addition to the stack, byte-code functions can use, bind, and set
 346 ordinary Lisp variables, by transferring values between variables and
 347 the stack.
 348
 349 @deffn Command disassemble object &optional stream
 350 This function prints the disassembled code for @var{object}.  If
 351 @var{stream} is supplied, then output goes there.  Otherwise, the
 352 disassembled code is printed to the stream @code{standard-output}.  The
 353 argument @var{object} can be a function name or a lambda expression.
 354
 355 As a special exception, if this function is used interactively,
 356 it outputs to a buffer named @samp{*Disassemble*}.
 357 @end deffn
 358
 359   Here are two examples of using the @code{disassemble} function.  We
 360 have added explanatory comments to help you relate the byte-code to the
 361 Lisp source; these do not appear in the output of @code{disassemble}.
 362 These examples show unoptimized byte-code.  Nowadays byte-code is
 363 usually optimized, but we did not want to rewrite these examples, since
 364 they still serve their purpose.
 365
 366 @example
 367 @group
 368 (defun factorial (integer)
 369   "Compute factorial of an integer."
 370   (if (= 1 integer) 1
 371     (* integer (factorial (1- integer)))))
 372      @result{} factorial
 373 @end group
 374
 375 @group
 376 (factorial 4)
 377      @result{} 24
 378 @end group
 379
 380 @group
 381 (disassemble 'factorial)
 382      @print{} byte-code for factorial:
 383  doc: Compute factorial of an integer.
 384  args: (integer)
 385 @end group
 386
 387 @group
 388 0   constant 1              ; @r{Push 1 onto stack.}
 389
 390 1   varref   integer        ; @r{Get value of @code{integer}}
 391                             ;   @r{from the environment}
 392                             ;   @r{and push the value}
 393                             ;   @r{onto the stack.}
 394 @end group
 395
 396 @group
 397 2   eqlsign                 ; @r{Pop top two values off stack,}
 398                             ;   @r{compare them,}
 399                             ;   @r{and push result onto stack.}
 400 @end group
 401
 402 @group
 403 3   goto-if-nil 10          ; @r{Pop and test top of stack;}
 404                             ;   @r{if @code{nil}, go to 10,}
 405                             ;   @r{else continue.}
 406 @end group
 407
 408 @group
 409 6   constant 1              ; @r{Push 1 onto top of stack.}
 410
 411 7   goto     17             ; @r{Go to 17 (in this case, 1 will be}
 412                             ;   @r{returned by the function).}
 413 @end group
 414
 415 @group
 416 10  constant *              ; @r{Push symbol @code{*} onto stack.}
 417
 418 11  varref   integer        ; @r{Push value of @code{integer} onto stack.}
 419 @end group
 420
 421 @group
 422 12  constant factorial      ; @r{Push @code{factorial} onto stack.}
 423
 424 13  varref   integer        ; @r{Push value of @code{integer} onto stack.}
 425
 426 14  sub1                    ; @r{Pop @code{integer}, decrement value,}
 427                             ;   @r{push new value onto stack.}
 428 @end group
 429
 430 @group
 431                             ; @r{Stack now contains:}
 432                             ;   @minus{} @r{decremented value of @code{integer}}
 433                             ;   @minus{} @r{@code{factorial}}
 434                             ;   @minus{} @r{value of @code{integer}}
 435                             ;   @minus{} @r{@code{*}}
 436 @end group
 437
 438 @group
 439 15  call     1              ; @r{Call function @code{factorial} using}
 440                             ;   @r{the first (i.e., the top) element}
 441                             ;   @r{of the stack as the argument;}
 442                             ;   @r{push returned value onto stack.}
 443 @end group
 444
 445 @group
 446                             ; @r{Stack now contains:}
 447                             ;   @minus{} @r{result of recursive}
 448                             ;        @r{call to @code{factorial}}
 449                             ;   @minus{} @r{value of @code{integer}}
 450                             ;   @minus{} @r{@code{*}}
 451 @end group
 452
 453 @group
 454 16  call     2              ; @r{Using the first two}
 455                             ;   @r{(i.e., the top two)}
 456                             ;   @r{elements of the stack}
 457                             ;   @r{as arguments,}
 458                             ;   @r{call the function @code{*},}
 459                             ;   @r{pushing the result onto the stack.}
 460 @end group
 461
 462 @group
 463 17  return                  ; @r{Return the top element}
 464                             ;   @r{of the stack.}
 465      @result{} nil
 466 @end group
 467 @end example
 468
 469 The @code{silly-loop} function is somewhat more complex:
 470
 471 @example
 472 @group
 473 (defun silly-loop (n)
 474   "Return time before and after N iterations of a loop."
 475   (let ((t1 (current-time-string)))
 476     (while (> (setq n (1- n))
 477               0))
 478     (list t1 (current-time-string))))
 479      @result{} silly-loop
 480 @end group
 481
 482 @group
 483 (disassemble 'silly-loop)
 484      @print{} byte-code for silly-loop:
 485  doc: Return time before and after N iterations of a loop.
 486  args: (n)
 487
 488 0   constant current-time-string  ; @r{Push}
 489                                   ;   @r{@code{current-time-string}}
 490                                   ;   @r{onto top of stack.}
 491 @end group
 492
 493 @group
 494 1   call     0              ; @r{Call @code{current-time-string}}
 495                             ;   @r{ with no argument,}
 496                             ;   @r{ pushing result onto stack.}
 497 @end group
 498
 499 @group
 500 2   varbind  t1             ; @r{Pop stack and bind @code{t1}}
 501                             ;   @r{to popped value.}
 502 @end group
 503
 504 @group
 505 3   varref   n              ; @r{Get value of @code{n} from}
 506                             ;   @r{the environment and push}
 507                             ;   @r{the value onto the stack.}
 508 @end group
 509
 510 @group
 511 4   sub1                    ; @r{Subtract 1 from top of stack.}
 512 @end group
 513
 514 @group
 515 5   dup                     ; @r{Duplicate the top of the stack;}
 516                             ;   @r{i.e., copy the top of}
 517                             ;   @r{the stack and push the}
 518                             ;   @r{copy onto the stack.}
 519 @end group
 520
 521 @group
 522 6   varset   n              ; @r{Pop the top of the stack,}
 523                             ;   @r{and bind @code{n} to the value.}
 524
 525                             ; @r{In effect, the sequence @code{dup varset}}
 526                             ;   @r{copies the top of the stack}
 527                             ;   @r{into the value of @code{n}}
 528                             ;   @r{without popping it.}
 529 @end group
 530
 531 @group
 532 7   constant 0              ; @r{Push 0 onto stack.}
 533 @end group
 534
 535 @group
 536 8   gtr                     ; @r{Pop top two values off stack,}
 537                             ;   @r{test if @var{n} is greater than 0}
 538                             ;   @r{and push result onto stack.}
 539 @end group
 540
 541 @group
 542 9   goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0}
 543                             ;   @r{(this exits the while loop).}
 544                             ;   @r{else pop top of stack}
 545                             ;   @r{and continue}
 546 @end group
 547
 548 @group
 549 12  constant nil            ; @r{Push @code{nil} onto stack}
 550                             ;   @r{(this is the body of the loop).}
 551 @end group
 552
 553 @group
 554 13  discard                 ; @r{Discard result of the body}
 555                             ;   @r{of the loop (a while loop}
 556                             ;   @r{is always evaluated for}
 557                             ;   @r{its side effects).}
 558 @end group
 559
 560 @group
 561 14  goto     3              ; @r{Jump back to beginning}
 562                             ;   @r{of while loop.}
 563 @end group
 564
 565 @group
 566 17  discard                 ; @r{Discard result of while loop}
 567                             ;   @r{by popping top of stack.}
 568                             ;   @r{This result is the value @code{nil} that}
 569                             ;   @r{was not popped by the goto at 9.}
 570 @end group
 571
 572 @group
 573 18  varref   t1             ; @r{Push value of @code{t1} onto stack.}
 574 @end group
 575
 576 @group
 577 19  constant current-time-string  ; @r{Push}
 578                                   ;   @r{@code{current-time-string}}
 579                                   ;   @r{onto top of stack.}
 580 @end group
 581
 582 @group
 583 20  call     0              ; @r{Call @code{current-time-string} again.}
 584 @end group
 585
 586 @group
 587 21  list2                   ; @r{Pop top two elements off stack,}
 588                             ;   @r{create a list of them,}
 589                             ;   @r{and push list onto stack.}
 590 @end group
 591
 592 @group
 593 22  unbind   1              ; @r{Unbind @code{t1} in local environment.}
 594
 595 23  return                  ; @r{Return value of the top of stack.}
 596
 597      @result{} nil
 598 @end group
 599 @end example
 600
 601