comparison lispref/compile.texi @ 6452:8c7032348e93

*** empty log message ***

6451:8240c0b1d695

@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

  @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."

@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*

@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

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

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

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

6452:8c7032348e93

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 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

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

@menu
* Speed of Byte-Code::          An example of speedup from byte compilation.
* 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 Speed of Byte-Code
@section Performance of Byte-Compiled Code

  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.
Here is an example:

@example
@group
(defun silly-loop (n)
  "Return time before and after N iterations of a loop."

@result{} silly-loop
@end group

@group
(silly-loop 100000)
@result{} ("Fri Mar 18 17:25:57 1994"
    "Fri Mar 18 17:26:28 1994")  ; @r{31 seconds}
@end group

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

@group
(silly-loop 100000)
@result{} ("Fri Mar 18 17:26:52 1994"
    "Fri Mar 18 17:26:58 1994")  ; @r{6 seconds}
@end group
@end example

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

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

  Normally, compiling a file does not evaluate the file's contents or
load the file.  But it does execute any @code{require} calls at
top-level in the file.  One way to ensure that necessary macro
definitions are available during compilation is to require the file that
defines them.  @xref{Features}.

@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} returns the new, compiled definition of
@var{symbol}.

If @var{symbol}'s definition is a byte-code function object,
@code{byte-compile} does nothing and returns @code{nil}.  Lisp records
only one function definition for any symbol, and if that is already
compiled, non-compiled code is not available anywhere.  So there is no
way to ``compile the same definition again.''

@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 byte-code function object.  The string it contains is
the actual byte-code; each character in it is an instruction or an
operand of 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*

@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} says what to do.  If it is @code{nil}, the file is
ignored.  If it is non-@code{nil}, the user is asked whether to compile
the file.

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

@defun batch-byte-compile
This function runs @code{byte-compile-file} on files specified 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 byte-code function object, and only rarely due to an explicit
call to @code{byte-code}.
@end defun

@node Eval During Compile
@section Evaluation During Compilation

@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 makes the elements consistent (we hope).

  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.

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.
It pushes values onto a stack of its own, then pops them off to use them
in calculations and push the result back on the stack.  When a byte-code
function returns, it pops a value off the stack and returns it as the
value of the function.

  In addition to the stack, byte-code functions can use, bind and set
ordinary Lisp variables, by transferring values between variables and
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

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