@c -*-texinfo-*-
@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.

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

@menu
* Compilation Functions::       Byte compilation functions.
* Disassembly::                 Disassembling byte-code; how to read byte-code.
@end menu

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

  An individual function or macro definition may be byte-compiled with
the @code{byte-compile} function.  A whole file may be byte-compiled
with @code{byte-compile-file} and several files may be byte-compiled
with @code{byte-recompile-directory} or @code{batch-byte-compile}.
Only @code{defun} and @code{defmacro} forms in a file are
byte-compiled; other top-level forms are not altered by byte compilation.

@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 will run much faster than the version written in Lisp.
For a rough comparison, consider the example below:

@example
(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

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

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

(silly-loop 100000)
@result{} ("Thu Jan 12 20:21:04 1989" 
    "Thu Jan 12 20:21:17 1989")  ; @r{13 seconds}
@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 will 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
(defun factorial (integer)
  "Compute factorial of INTEGER."
  (if (= 1 integer) 1
    (* integer (factorial (1- integer)))))
     @result{} factorial

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

@noindent
The string that is the first argument of @code{byte-code} 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.

  The @code{byte-compile} function is not autoloaded as are
@code{byte-compile-file} and @code{byte-recompile-directory}.  
@end defun

@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 copied out unchanged.  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
% ls -l push*
-rw-r--r--  1 lewis             791 Oct  5 20:31 push.el

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

% 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 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.  Each file will be processed,
even if an error occurs while compiling a previous file.  (The file with
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 is the function that 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.
@end defun

@node  Disassembly, , Compilation Functions, Byte Compilation
@comment  node-name,  next,  previous,  up
@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}.

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

(factorial 4)
     @result{} 24

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

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

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

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

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

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).}

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

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

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.}

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

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.}

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

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

17  return                  ; @r{Return the top element of the stack.}

     @result{} nil
@end example

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

@example
(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

(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 @code{current-time-string}}
                                      ;     @r{onto top of stack.}

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

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

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

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

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

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} copies}
                    ; @r{the top of the stack into the value of @code{n}}
                    ; @r{without popping it.}

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

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

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

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

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

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

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

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

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

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

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

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

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

     @result{} nil
@end example


