annotate lispref/compile.texi @ 6263:f2b01e6e4a1f

(super-apropos-check-doc-file): Use doc-directory instead of data-directory.

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/compile
@node Byte Compilation, Debugging, Loading, Top
@chapter Byte Compilation
@cindex byte-code
@cindex compilation

  GNU Emacs Lisp has a @dfn{compiler} that translates functions written
in Lisp into a special representation called @dfn{byte-code} that can be
executed more efficiently.  The compiler replaces Lisp function
definitions with byte-code.  When a byte-code function is called, its
definition is evaluated by the @dfn{byte-code interpreter}.

  Because the byte-compiled code is evaluated by the byte-code
interpreter, instead of being executed directly by the machine's
hardware (as true compiled code is), byte-code is completely
transportable from machine to machine without recompilation.  It is not,
however, as fast as true compiled code.

  In general, any version of Emacs can run byte-compiled code produced
by recent earlier versions of Emacs, but the reverse is not true.  In
particular, if you compile a program with Emacs 18, you can run the
compiled code in Emacs 19, but not vice versa.

  @xref{Compilation Errors}, for how to investigate errors occurring in
byte compilation.

@menu
* Compilation Functions::       Byte compilation functions.
* Eval During Compile::  	Code to be evaluated when you compile.
* Byte-Code Objects::		The data type used for byte-compiled functions.
* Disassembly::                 Disassembling byte-code; how to read byte-code.
@end menu

@node Compilation Functions
@comment  node-name,  next,  previous,  up
@section The Compilation Functions
@cindex compilation functions

  You can byte-compile an individual function or macro definition with
the @code{byte-compile} function.  You can compile a whole file with
@code{byte-compile-file}, or several files with
@code{byte-recompile-directory} or @code{batch-byte-compile}.

  When you run the byte compiler, you may get warnings in a buffer called
@samp{*Compile-Log*}.  These report usage in your program that suggest a
problem, but are not necessarily erroneous.

@cindex macro compilation
  Be careful when byte-compiling code that uses macros.  Macro calls are
expanded when they are compiled, so the macros must already be defined
for proper compilation.  For more details, see @ref{Compiling Macros}.

  While byte-compiling a file, any @code{require} calls at top-level are
executed.  One way to ensure that necessary macro definitions are
available during compilation is to require the file that defines them.
@xref{Features}.

  A byte-compiled function is not as efficient as a primitive function
written in C, but runs much faster than the version written in Lisp.
For a rough comparison, consider the example below:

@example
@group
(defun silly-loop (n)
  "Return time before and after N iterations of a loop."
  (let ((t1 (current-time-string)))
    (while (> (setq n (1- n)) 
              0))
    (list t1 (current-time-string))))
@result{} silly-loop
@end group

@group
(silly-loop 100000)
@result{} ("Thu Jan 12 20:18:38 1989" 
    "Thu Jan 12 20:19:29 1989")  ; @r{51 seconds}
@end group

@group
(byte-compile 'silly-loop)
@result{} @r{[Compiled code not shown]}
@end group

@group
(silly-loop 100000)
@result{} ("Thu Jan 12 20:21:04 1989" 
    "Thu Jan 12 20:21:17 1989")  ; @r{13 seconds}
@end group
@end example

  In this example, the interpreted code required 51 seconds to run,
whereas the byte-compiled code required 13 seconds.  These results are
representative, but actual results will vary greatly.

@defun byte-compile symbol
  This function byte-compiles the function definition of @var{symbol},
replacing the previous definition with the compiled one.  The function
definition of @var{symbol} must be the actual code for the function;
i.e., the compiler does not follow indirection to another symbol.
@code{byte-compile} does not compile macros.  @code{byte-compile}
returns the new, compiled definition of @var{symbol}.

@example
@group
(defun factorial (integer)
  "Compute factorial of INTEGER."
  (if (= 1 integer) 1
    (* integer (factorial (1- integer)))))
     @result{} factorial
@end group

@group
(byte-compile 'factorial)
     @result{}
#[(integer)
  "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207"
  [integer 1 * factorial]
  4 "Compute factorial of INTEGER."]
@end group
@end example

@noindent
The result is a compiled function object.  The string it contains is the
actual byte-code; each character in it is an instruction.  The vector
contains all the constants, variable names and function names used by
the function, except for certain primitives that are coded as special
instructions.
@end defun

@deffn Command compile-defun
This command reads the defun containing point, compiles it, and
evaluates the result.  If you use this on a defun that is actually a
function definition, the effect is to install a compiled version of that
function.
@end deffn

@deffn Command byte-compile-file filename
  This function compiles a file of Lisp code named @var{filename} into
a file of byte-code.  The output file's name is made by appending
@samp{c} to the end of @var{filename}.

  Compilation works by reading the input file one form at a time.  If it
is a definition of a function or macro, the compiled function or macro
definition is written out.  Other forms are batched together, then each
batch is compiled, and written so that its compiled code will be
executed when the file is read.  All comments are discarded when the
input file is read.

  This command returns @code{t}.  When called interactively, it prompts
for the file name.

@example
@group
% ls -l push*
-rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
@end group

@group
(byte-compile-file "~/emacs/push.el")
     @result{} t
@end group

@group
% ls -l push*
-rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
-rw-rw-rw-  1 lewis     638 Oct  8 20:25 push.elc
@end group
@end example
@end deffn

@deffn Command byte-recompile-directory directory flag
@cindex library compilation
  This function recompiles every @samp{.el} file in @var{directory} that
needs recompilation.  A file needs recompilation if a @samp{.elc} file
exists but is older than the @samp{.el} file.

  If a @samp{.el} file exists, but there is no corresponding @samp{.elc}
file, then @var{flag} is examined.  If it is @code{nil}, the file is
ignored.  If it is non-@code{nil}, the user is asked whether the file
should be compiled.

  The returned value of this command is unpredictable.
@end deffn

@defun batch-byte-compile
  This function runs @code{byte-compile-file} on the files remaining on
the command line.  This function must be used only in a batch execution
of Emacs, as it kills Emacs on completion.  An error in one file does
not prevent processing of subsequent files.  (The file which gets the
error will not, of course, produce any compiled code.)

@example
% emacs -batch -f batch-byte-compile *.el
@end example
@end defun

@defun byte-code code-string data-vector max-stack
@cindex byte-code interpreter
  This function actually interprets byte-code.  A byte-compiled function
is actually defined with a body that calls @code{byte-code}.  Don't call
this function yourself.  Only the byte compiler knows how to generate
valid calls to this function.

  In newer Emacs versions (19 and up), byte-code is usually executed as
part of a compiled function object, and only rarely as part of a call to
@code{byte-code}.
@end defun

@node Eval During Compile
@section Evaluation During Compilation

These features permit you to write code to be evaluated during
compilation of a program.

@defspec eval-and-compile body
This form marks @var{body} to be evaluated both when you compile the
containing code and when you run it (whether compiled or not).

You can get a similar result by putting @var{body} in a separate file
and referring to that file with @code{require}.  Using @code{require} is
preferable if there is a substantial amount of code to be executed in
this way.
@end defspec

@defspec eval-when-compile body
This form marks @var{body} to be evaluated at compile time @emph{only}.
The result of evaluation by the compiler becomes a constant which
appears in the compiled program.  When the program is interpreted, not
compiled at all, @var{body} is evaluated normally.

At top-level, this is analogous to the Common Lisp idiom
@code{(eval-when (compile eval) @dots{})}.  Elsewhere, the Common Lisp
@samp{#.} reader macro (but not when interpreting) is closer to what
@code{eval-when-compile} does.
@end defspec

@node Byte-Code Objects
@section Byte-Code Objects
@cindex compiled function
@cindex byte-code function

  Byte-compiled functions have a special data type: they are
@dfn{byte-code function objects}.

  Internally, a byte-code function object is much like a vector;
however, the evaluator handles this data type specially when it appears
as a function to be called.  The printed representation for a byte-code
function object is like that for a vector, with an additional @samp{#}
before the opening @samp{[}.

  In Emacs version 18, there was no byte-code function object data type;
compiled functions used the function @code{byte-code} to run the byte
code.

  A byte-code function object must have at least four elements; there is
no maximum number, but only the first six elements are actually used.
They are:

@table @var
@item arglist
The list of argument symbols.

@item byte-code
The string containing the byte-code instructions.

@item constants
The vector of constants referenced by the byte code.

@item stacksize
The maximum stack size this function needs.

@item docstring
The documentation string (if any); otherwise, @code{nil}.  For functions
preloaded before Emacs is dumped, this is usually an integer which is an
index into the @file{DOC} file; use @code{documentation} to convert this
into a string (@pxref{Accessing Documentation}).

@item interactive
The interactive spec (if any).  This can be a string or a Lisp
expression.  It is @code{nil} for a function that isn't interactive.
@end table

Here's an example of a byte-code function object, in printed
representation.  It is the definition of the command
@code{backward-sexp}.

@example
#[(&optional arg)
  "^H\204^F^@@\301^P\302^H[!\207"
  [arg 1 forward-sexp]
  2
  254435
  "p"]
@end example

  The primitive way to create a byte-code object is with
@code{make-byte-code}:

@defun make-byte-code &rest elements
This function constructs and returns a byte-code function object
with @var{elements} as its elements.
@end defun

  You should not try to come up with the elements for a byte-code function
yourself, because if they are inconsistent, Emacs may crash when you
call the function.  Always leave it to the byte-compiler to create these
objects; it, we hope, always makes the elements consistent.

  You can access the elements of a byte-code object using @code{aref};
you can also use @code{vconcat} to create a vector with the same
elements.

@node Disassembly
@section Disassembled Byte-Code
@cindex disassembled byte-code

  People do not write byte-code; that job is left to the byte compiler.
But we provide a disassembler to satisfy a cat-like curiosity.  The
disassembler converts the byte-compiled code into humanly readable
form.

  The byte-code interpreter is implemented as a simple stack machine.
Values get stored by being pushed onto the stack, and are popped off and
manipulated, the results being pushed back onto the stack.  When a
function returns, the top of the stack is popped and returned as the
value of the function.

  In addition to the stack, values used during byte-code execution can
be stored in ordinary Lisp variables.  Variable values can be pushed
onto the stack, and variables can be set by popping the stack.

@deffn Command disassemble object &optional stream
This function prints the disassembled code for @var{object}.  If
@var{stream} is supplied, then output goes there.  Otherwise, the
disassembled code is printed to the stream @code{standard-output}.  The
argument @var{object} can be a function name or a lambda expression.

As a special exception, if this function is used interactively,
it outputs to a buffer named @samp{*Disassemble*}.
@end deffn

  Here are two examples of using the @code{disassemble} function.  We
have added explanatory comments to help you relate the byte-code to the
Lisp source; these do not appear in the output of @code{disassemble}.
These examples show unoptimized byte-code.  Nowadays byte-code is
usually optimized, but we did not want to rewrite these examples, since
they still serve their purpose.

@example
@group
(defun factorial (integer)
  "Compute factorial of an integer."
  (if (= 1 integer) 1
    (* integer (factorial (1- integer)))))
     @result{} factorial
@end group

@group
(factorial 4)
     @result{} 24
@end group

@group
(disassemble 'factorial)
     @print{} byte-code for factorial:
 doc: Compute factorial of an integer.
 args: (integer)
@end group

@group
0   constant 1              ; @r{Push 1 onto stack.}

1   varref   integer        ; @r{Get value of @code{integer}} 
                            ;   @r{from the environment}
                            ;   @r{and push the value}
                            ;   @r{onto the stack.}
@end group

@group
2   eqlsign                 ; @r{Pop top two values off stack,}
                            ;   @r{compare them,}
                            ;   @r{and push result onto stack.}
@end group

@group
3   goto-if-nil 10          ; @r{Pop and test top of stack;}
                            ;   @r{if @code{nil}, go to 10,}
                            ;   @r{else continue.}
@end group

@group
6   constant 1              ; @r{Push 1 onto top of stack.}

7   goto     17             ; @r{Go to 17 (in this case, 1 will be}
                            ;   @r{returned by the function).}
@end group

@group
10  constant *              ; @r{Push symbol @code{*} onto stack.}

11  varref   integer        ; @r{Push value of @code{integer} onto stack.}
@end group

@group
12  constant factorial      ; @r{Push @code{factorial} onto stack.}

13  varref   integer        ; @r{Push value of @code{integer} onto stack.}

14  sub1                    ; @r{Pop @code{integer}, decrement value,}
                            ;   @r{push new value onto stack.}
@end group

@group
                            ; @r{Stack now contains:}
                            ;   @minus{} @r{decremented value of @code{integer}}
                            ;   @minus{} @r{@code{factorial}} 
                            ;   @minus{} @r{value of @code{integer}}
                            ;   @minus{} @r{@code{*}}
@end group

@group
15  call     1              ; @r{Call function @code{factorial} using}
                            ;   @r{the first (i.e., the top) element}
                            ;   @r{of the stack as the argument;}
                            ;   @r{push returned value onto stack.}
@end group

@group
                            ; @r{Stack now contains:}
                            ;   @minus{} @r{result of result of recursive}
                            ;        @r{call to @code{factorial}}
                            ;   @minus{} @r{value of @code{integer}}
                            ;   @minus{} @r{@code{*}}
@end group

@group
16  call     2              ; @r{Using the first two}
                            ;   @r{(i.e., the top two)}
                            ;   @r{elements of the stack}
                            ;   @r{as arguments,}
                            ;   @r{call the function @code{*},}
                            ;   @r{pushing the result onto the stack.}
@end group

@group
17  return                  ; @r{Return the top element}
                            ;   @r{of the stack.}
     @result{} nil
@end group
@end example

The @code{silly-loop} function is somewhat more complex:

@example
@group
(defun silly-loop (n)
  "Return time before and after N iterations of a loop."
  (let ((t1 (current-time-string)))
    (while (> (setq n (1- n)) 
              0))
    (list t1 (current-time-string))))
     @result{} silly-loop
@end group

@group
(disassemble 'silly-loop)
     @print{} byte-code for silly-loop:
 doc: Return time before and after N iterations of a loop.
 args: (n)

0   constant current-time-string  ; @r{Push}
                                  ;   @r{@code{current-time-string}}
                                  ;   @r{onto top of stack.}
@end group

@group
1   call     0              ; @r{Call @code{current-time-string}}
                            ;   @r{ with no argument,}
                            ;   @r{ pushing result onto stack.}
@end group

@group
2   varbind  t1             ; @r{Pop stack and bind @code{t1}}
                            ;   @r{to popped value.}
@end group

@group
3   varref   n              ; @r{Get value of @code{n} from}
                            ;   @r{the environment and push}
                            ;   @r{the value onto the stack.}
@end group

@group
4   sub1                    ; @r{Subtract 1 from top of stack.}
@end group

@group
5   dup                     ; @r{Duplicate the top of the stack;}
                            ;   @r{i.e. copy the top of}
                            ;   @r{the stack and push the}
                            ;   @r{copy onto the stack.}
@end group

@group
6   varset   n              ; @r{Pop the top of the stack,}
                            ;   @r{and bind @code{n} to the value.}

                            ; @r{In effect, the sequence @code{dup varset}}
                            ;   @r{copies the top of the stack}
                            ;   @r{into the value of @code{n}}
                            ;   @r{without popping it.}
@end group

@group
7   constant 0              ; @r{Push 0 onto stack.}
@end group

@group
8   gtr                     ; @r{Pop top two values off stack,}
                            ;   @r{test if @var{n} is greater than 0}
                            ;   @r{and push result onto stack.}
@end group

@group
9   goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} > 0}
                            ;   @r{else pop top of stack}
                            ;   @r{and continue}
                            ;   @r{(this exits the while loop).}
@end group

@group
12  constant nil            ; @r{Push @code{nil} onto stack}
                            ;   @r{(this is the body of the loop).}
@end group

@group
13  discard                 ; @r{Discard result of the body}
                            ;   @r{of the loop (a while loop}
                            ;   @r{is always evaluated for}
                            ;   @r{its side effects).}
@end group

@group
14  goto     3              ; @r{Jump back to beginning}
                            ;   @r{of while loop.}
@end group

@group
17  discard                 ; @r{Discard result of while loop}
                            ;   @r{by popping top of stack.}
@end group

@group
18  varref   t1             ; @r{Push value of @code{t1} onto stack.}
@end group

@group
19  constant current-time-string  ; @r{Push} 
                                  ;   @r{@code{current-time-string}}
                                  ;   @r{onto top of stack.}
@end group

@group
20  call     0              ; @r{Call @code{current-time-string} again.}
@end group

@group
21  list2                   ; @r{Pop top two elements off stack,}
                            ;   @r{create a list of them,}
                            ;   @r{and push list onto stack.}
@end group

@group
22  unbind   1              ; @r{Unbind @code{t1} in local environment.}

23  return                  ; @r{Return value of the top of stack.}

     @result{} nil
@end group
@end example