@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1994, 2001-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/compile
@node Byte Compilation, Advising Functions, Loading, Top
transportable from machine to machine without recompilation. It is not,
however, as fast as true compiled code.
- Compiling a Lisp file with the Emacs byte compiler always reads the
-file as multibyte text, even if Emacs was started with @samp{--unibyte},
-unless the file specifies otherwise. This is so that compilation gives
-results compatible with running the same file without compilation.
-@xref{Loading Non-ASCII}.
-
In general, any version of Emacs can run byte-compiled code produced
by recent earlier versions of Emacs, but the reverse is not true.
;; -*-no-byte-compile: t; -*-
@end example
- @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.
* Docs and Compilation:: Dynamic loading of documentation strings.
* Dynamic Loading:: Dynamic loading of individual functions.
-* Eval During Compile:: Code to be evaluated when you compile.
+* Eval During Compile:: Code to be evaluated when you compile.
* Compiler Errors:: Handling compiler error messages.
-* Byte-Code Objects:: The data type used for byte-compiled functions.
+* Byte-Code Objects:: The data type used for byte-compiled functions.
* Disassembly:: Disassembling byte-code; how to read byte-code.
@end menu
@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))))
+ "Return the time, in seconds, to run N iterations of a loop."
+ (let ((t1 (float-time)))
+ (while (> (setq n (1- n)) 0))
+ (- (float-time) t1)))
@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}
+(silly-loop 50000000)
+@result{} 10.235304117202759
@end group
@group
@end group
@group
-(silly-loop 100000)
-@result{} ("Fri Mar 18 17:26:52 1994"
- "Fri Mar 18 17:26:58 1994") ; @r{6 seconds}
+(silly-loop 50000000)
+@result{} 3.705854892730713
@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.
+ In this example, the interpreted code required 10 seconds to run,
+whereas the byte-compiled code required less than 4 seconds. These
+results are representative, but actual results may vary.
@node Compilation Functions
@comment node-name, next, previous, up
-@section The Compilation Functions
+@section Byte-Compilation Functions
@cindex compilation functions
You can byte-compile an individual function or macro definition with
@code{byte-compile-file}, or several files with
@code{byte-recompile-directory} or @code{batch-byte-compile}.
- The byte compiler produces error messages and warnings about each file
-in a buffer called @samp{*Compile-Log*}. These report things in your
-program that suggest a problem but are not necessarily erroneous.
+ Sometimes, the byte compiler produces warning and/or error messages
+(@pxref{Compiler Errors}, for details). These messages are recorded
+in a buffer called @samp{*Compile-Log*}, which uses Compilation mode.
+@xref{Compilation Mode,,,emacs, The GNU Emacs Manual}.
@cindex macro compilation
- Be careful when writing macro calls in files that you may someday
-byte-compile. 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}. If a program does not work the
-same way when compiled as it does when interpreted, erroneous macro
-definitions are one likely cause (@pxref{Problems with Macros}).
-Inline (@code{defsubst}) functions are less troublesome; if you
+ Be careful when writing macro calls in files that you intend to
+byte-compile. Since macro calls are expanded when they are compiled,
+the macros need to be loaded into Emacs or the byte compiler will not
+do the right thing. The usual way to handle this is with
+@code{require} forms which specify the files containing the needed
+macro definitions (@pxref{Named Features}). Normally, the
+byte compiler does not evaluate the code that it is compiling, but it
+handles @code{require} forms specially, by loading the specified
+libraries. To avoid loading the macro definition files when someone
+@emph{runs} the compiled program, write @code{eval-when-compile}
+around the @code{require} calls (@pxref{Eval During Compile}). For
+more details, @xref{Compiling Macros}.
+
+ Inline (@code{defsubst}) functions are less troublesome; if you
compile a call to such a function before its definition is known, the
call will still work right, it will just run slower.
- 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 (@pxref{Named Features}). To avoid loading the macro definition files
-when someone @emph{runs} the compiled program, write
-@code{eval-when-compile} around the @code{require} calls (@pxref{Eval
-During Compile}).
-
@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.''
+@code{byte-compile} does not handle function indirection. The return
+value is the byte-code function object which is the compiled
+definition of @var{symbol} (@pxref{Byte-Code Objects}).
@example
@group
@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.
-
-If the argument to @code{byte-compile} is a @code{lambda} expression,
-it returns the corresponding compiled code, but does not store
-it anywhere.
+If @var{symbol}'s definition is a byte-code function object,
+@code{byte-compile} does nothing and returns @code{nil}. It does not
+``compile the symbol's definition again'', since the original
+(non-compiled) code has already been replaced in the symbol's function
+cell by the byte-compiled code.
+
+The argument to @code{byte-compile} can also be a @code{lambda}
+expression. In that case, the function returns the corresponding
+compiled code but does not store it anywhere.
@end defun
@deffn Command compile-defun &optional arg
@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 Emacs version 18, byte-code was always executed by way of a call to
-the function @code{byte-code}. Nowadays, byte-code is usually executed
-as part of a byte-code function object, and only rarely through an
-explicit call to @code{byte-code}.
-@end defun
-
@node Docs and Compilation
@section Documentation Strings and Compilation
@cindex dynamic loading of documentation
probably give nonsense results.
@end itemize
- If your site installs Emacs following the usual procedures, these
-problems will never normally occur. Installing a new version uses a new
-directory with a different name; as long as the old version remains
-installed, its files will remain unmodified in the places where they are
-expected to be.
-
- However, if you have built Emacs yourself and use it from the
-directory where you built it, you will experience this problem
-occasionally if you edit and recompile Lisp files. When it happens, you
-can cure the problem by reloading the file after recompiling it.
-
- You can turn off this feature at compile time by setting
-@code{byte-compile-dynamic-docstrings} to @code{nil}; this is useful
-mainly if you expect to change the file, and you want Emacs processes
-that have already loaded it to keep working when the file changes.
-You can do this globally, or for one source file by specifying a
-file-local binding for the variable. One way to do that is by adding
-this string to the file's first line:
-
-@example
--*-byte-compile-dynamic-docstrings: nil;-*-
-@end example
-
-@defvar byte-compile-dynamic-docstrings
-If this is non-@code{nil}, the byte compiler generates compiled files
-that are set up for dynamic loading of documentation strings.
-@end defvar
+@noindent
+These problems normally occur only if you build Emacs yourself and use
+it from the directory where you built it, and you happen to edit
+and/or recompile the Lisp source files. They can be easily cured by
+reloading each file after recompiling it.
@cindex @samp{#@@@var{count}}
@cindex @samp{#$}
files, since they are not designed to be clear to humans reading the
file.
+ You can disable the dynamic documentation string feature at compile
+time by setting @code{byte-compile-dynamic-docstrings} to @code{nil};
+this is useful mainly if you expect to change the file, and you want
+Emacs processes that have already loaded it to keep working when the
+file changes. You can do this globally, or for one source file by
+specifying a file-local binding for the variable. One way to do that
+is by adding this string to the file's first line:
+
+@example
+-*-byte-compile-dynamic-docstrings: nil;-*-
+@end example
+
+@defvar byte-compile-dynamic-docstrings
+If this is non-@code{nil}, the byte compiler generates compiled files
+that are set up for dynamic loading of documentation strings.
+@end defvar
+
@node Dynamic Loading
@section Dynamic Loading of Individual Functions
@lisp
(eval-when-compile
- (require 'my-macro-package)) ;; only macros needed from this
+ (require 'my-macro-package))
@end lisp
The same sort of thing goes for macros and @code{defsubst} functions
Byte compilation outputs all errors and warnings into the buffer
@samp{*Compile-Log*}. The messages include file names and line
numbers that identify the location of the problem. The usual Emacs
-commands for operating on compiler diagnostics work properly on
-these messages.
-
- However, the warnings about functions that were used but not
-defined are always ``located'' at the end of the file, so these
-commands won't find the places they are really used. To do that,
-you must search for the function names.
+commands for operating on compiler diagnostics work properly on these
+messages.
+
+ When an error is due to invalid syntax in the program, the byte
+compiler might get confused about the errors' exact location. One way
+to investigate is to switch to the buffer @w{@samp{*Compiler Input*}}.
+(This buffer name starts with a space, so it does not show up in
+@kbd{M-x list-buffers}.) This buffer contains the program being
+compiled, and point shows how far the byte compiler was able to read;
+the cause of the error might be nearby. @xref{Syntax Errors}, for
+some tips for locating syntax errors.
+
+ When the byte compiler warns about functions that were used but not
+defined, it always reports the line number for the end of the file,
+not the locations where the missing functions were called. To find
+the latter, you must search for the function names.
You can suppress the compiler warning for calling an undefined
function @var{func} by conditionalizing the function call on an
inside @var{body}.
We recommend that you use this construct around the smallest
-possible piece of code, to avoid missing possible warnings other than one
+possible piece of code, to avoid missing possible warnings other than
one you intend to suppress.
@end defspec
@cindex byte-code function
Byte-compiled functions have a special data type: they are
-@dfn{byte-code function objects}.
+@dfn{byte-code function objects}. Whenever such an object appears as
+a function to be called, Emacs uses the byte-code interpreter to
+execute the byte-code.
- 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{[}.
-
- A byte-code function object must have at least four elements; there is
-no maximum number, but only the first six elements have any normal use.
-They are:
+ Internally, a byte-code function object is much like a vector; its
+elements can be accessed using @code{aref}. Its printed
+representation is like that for a vector, with an additional @samp{#}
+before the opening @samp{[}. It must have at least four elements;
+there is no maximum number, but only the first six elements have any
+normal use. They are:
@table @var
@item arglist
[arg 1 forward-sexp]
2
254435
- "p"]
+ "^p"]
@end example
The primitive way to create a byte-code object is with
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.
-
@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.
+ 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
+human-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
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
@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.}
+0 varref integer ; @r{Get the value of @code{integer}}
+ ; @r{and push it onto the stack.}
+1 constant 1 ; @r{Push 1 onto stack.}
@end group
@group
-2 eqlsign ; @r{Pop top two values off stack,}
- ; @r{compare them,}
- ; @r{and push result onto stack.}
+2 eqlsign ; @r{Pop top two values off stack, compare}
+ ; @r{them, 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,}
+3 goto-if-nil 1 ; @r{Pop and test top of stack;}
+ ; @r{if @code{nil}, go to 1,}
; @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.}
+7 return ; @r{Return the top element}
+ ; @r{of the 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,}
+8:1 varref integer ; @r{Push value of @code{integer} onto stack.}
+9 constant factorial ; @r{Push @code{factorial} onto stack.}
+10 varref integer ; @r{Push value of @code{integer} onto stack.}
+11 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}
+12 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 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
+13 mult ; @r{Pop top two values off stack, multiply}
+ ; @r{them, and push result onto stack.}
+14 return ; @r{Return the top element of stack.}
@end group
@end example
@group
1 call 0 ; @r{Call @code{current-time-string}}
- ; @r{ with no argument,}
- ; @r{ pushing result onto stack.}
+ ; @r{with no argument,}
+ ; @r{pushing result onto stack.}
@end group
@group
@end group
@group
-3 varref n ; @r{Get value of @code{n} from}
+3:1 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
; @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.}
@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{(this exits the while loop).}
- ; @r{else pop top of stack}
- ; @r{and continue}
-@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.}
- ; @r{This result is the value @code{nil} that}
- ; @r{was not popped by the goto at 9.}
-@end group
-
-@group
-18 varref t1 ; @r{Push value of @code{t1} onto stack.}
+9 goto-if-not-nil 1 ; @r{Goto 1 if @code{n} > 0}
+ ; @r{(this continues the while loop)}
+ ; @r{else continue.}
@end group
@group
-19 constant current-time-string ; @r{Push}
- ; @r{@code{current-time-string}}
+12 varref t1 ; @r{Push value of @code{t1} onto stack.}
+13 constant current-time-string ; @r{Push @code{current-time-string}}
; @r{onto top of stack.}
+14 call 0 ; @r{Call @code{current-time-string} again.}
@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,}
+15 unbind 1 ; @r{Unbind @code{t1} in local environment.}
+16 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
+17 return ; @r{Return value of the top of stack.}
@end group
@end example
-
-@ignore
- arch-tag: f78e3050-2f0a-4dee-be27-d9979a0a2289
-@end ignore
HCoop / bpt / emacs.git / blobdiff