procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

*** empty log message ***

Browse source
This commit is contained in:
Richard M. Stallman 1994-03-21 17:04:32 +00:00
parent a44af9f249
commit a0acfc98dc
1 changed files with 92 additions and 81 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

173
lispref/compile.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*- @c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual. @c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions. @c See the file elisp.texi for copying conditions.
@setfilename ../info/compile @setfilename ../info/compile
@node Byte Compilation, Debugging, Loading, Top @node Byte Compilation, Debugging, Loading, Top
@ -29,12 +29,53 @@ compiled code in Emacs 19, but not vice versa.
byte compilation. byte compilation.
@menu @menu
* Speed of Byte-Code:: An example of speedup from byte compilation.
* Compilation Functions:: Byte compilation functions. * Compilation Functions:: Byte compilation functions.
* Eval During Compile:: Code to be evaluated when you compile. * Eval During Compile:: Code to be evaluated when you compile.
* 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. * Disassembly:: Disassembling byte-code; how to read byte-code.
@end menu @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."
(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{} ("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 @node Compilation Functions
@comment node-name, next, previous, up @comment node-name, next, previous, up
@section The Compilation Functions @section The Compilation Functions
@ -54,55 +95,25 @@ problem, but are not necessarily erroneous.
expanded when they are compiled, so the macros must already be defined expanded when they are compiled, so the macros must already be defined
for proper compilation. For more details, see @ref{Compiling Macros}. for proper compilation. For more details, see @ref{Compiling Macros}.
While byte-compiling a file, any @code{require} calls at top-level are Normally, compiling a file does not evaluate the file's contents or
executed. One way to ensure that necessary macro definitions are load the file. But it does execute any @code{require} calls at
available during compilation is to require the file that defines them. top-level in the file. One way to ensure that necessary macro
@xref{Features}. 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 @defun byte-compile symbol
This function byte-compiles the function definition of @var{symbol}, This function byte-compiles the function definition of @var{symbol},
replacing the previous definition with the compiled one. The function replacing the previous definition with the compiled one. The function
definition of @var{symbol} must be the actual code for 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. i.e., the compiler does not follow indirection to another symbol.
@code{byte-compile} does not compile macros. @code{byte-compile} @code{byte-compile} returns the new, compiled definition of
returns the new, compiled definition of @var{symbol}. @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 @example
@group @group
@ -110,12 +121,12 @@ returns the new, compiled definition of @var{symbol}.
"Compute factorial of INTEGER." "Compute factorial of INTEGER."
(if (= 1 integer) 1 (if (= 1 integer) 1
(* integer (factorial (1- integer))))) (* integer (factorial (1- integer)))))
@result{} factorial @result{} factorial
@end group @end group
@group @group
(byte-compile 'factorial) (byte-compile 'factorial)
@result{} @result{}
#[(integer) #[(integer)
"^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207" "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207"
[integer 1 * factorial] [integer 1 * factorial]
@ -124,11 +135,11 @@ returns the new, compiled definition of @var{symbol}.
@end example @end example
@noindent @noindent
The result is a compiled function object. The string it contains is the The result is a byte-code function object. The string it contains is
actual byte-code; each character in it is an instruction. The vector the actual byte-code; each character in it is an instruction or an
contains all the constants, variable names and function names used by operand of an instruction. The vector contains all the constants,
the function, except for certain primitives that are coded as special variable names and function names used by the function, except for
instructions. certain primitives that are coded as special instructions.
@end defun @end defun
@deffn Command compile-defun @deffn Command compile-defun
@ -139,18 +150,18 @@ function.
@end deffn @end deffn
@deffn Command byte-compile-file filename @deffn Command byte-compile-file filename
This function compiles a file of Lisp code named @var{filename} into 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 a file of byte-code. The output file's name is made by appending
@samp{c} to the end of @var{filename}. @samp{c} to the end of @var{filename}.
Compilation works by reading the input file one form at a time. If it 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 is a definition of a function or macro, the compiled function or macro
definition is written out. Other forms are batched together, then each definition is written out. Other forms are batched together, then each
batch is compiled, and written so that its compiled code will be batch is compiled, and written so that its compiled code will be
executed when the file is read. All comments are discarded when the executed when the file is read. All comments are discarded when the
input file is read. input file is read.
This command returns @code{t}. When called interactively, it prompts This command returns @code{t}. When called interactively, it prompts
for the file name. for the file name.
@example @example
@ -174,24 +185,24 @@ for the file name.
@deffn Command byte-recompile-directory directory flag @deffn Command byte-recompile-directory directory flag
@cindex library compilation @cindex library compilation
This function recompiles every @samp{.el} file in @var{directory} that This function recompiles every @samp{.el} file in @var{directory} that
needs recompilation. A file needs recompilation if a @samp{.elc} file needs recompilation. A file needs recompilation if a @samp{.elc} file
exists but is older than the @samp{.el} file. exists but is older than the @samp{.el} file.
If a @samp{.el} file exists, but there is no corresponding @samp{.elc} 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 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 the file ignored. If it is non-@code{nil}, the user is asked whether to compile
should be compiled. the file.
The returned value of this command is unpredictable. The returned value of this command is unpredictable.
@end deffn @end deffn
@defun batch-byte-compile @defun batch-byte-compile
This function runs @code{byte-compile-file} on the files remaining on This function runs @code{byte-compile-file} on files specified on the
the command line. This function must be used only in a batch execution command line. This function must be used only in a batch execution of
of Emacs, as it kills Emacs on completion. An error in one file does Emacs, as it kills Emacs on completion. An error in one file does not
not prevent processing of subsequent files. (The file which gets the prevent processing of subsequent files. (The file which gets the error
error will not, of course, produce any compiled code.) will not, of course, produce any compiled code.)
@example @example
% emacs -batch -f batch-byte-compile *.el % emacs -batch -f batch-byte-compile *.el
@ -200,14 +211,14 @@ error will not, of course, produce any compiled code.)
@defun byte-code code-string data-vector max-stack @defun byte-code code-string data-vector max-stack
@cindex byte-code interpreter @cindex byte-code interpreter
This function actually interprets byte-code. A byte-compiled function This function actually interprets byte-code. A byte-compiled function
is actually defined with a body that calls @code{byte-code}. Don't call 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 this function yourself. Only the byte compiler knows how to generate
valid calls to this function. valid calls to this function.
In newer Emacs versions (19 and up), byte-code is usually executed as 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 part of a byte-code function object, and only rarely due to an explicit
@code{byte-code}. call to @code{byte-code}.
@end defun @end defun
@node Eval During Compile @node Eval During Compile
@ -305,10 +316,10 @@ This function constructs and returns a byte-code function object
with @var{elements} as its elements. with @var{elements} as its elements.
@end defun @end defun
You should not try to come up with the elements for a byte-code function You should not try to come up with the elements for a byte-code
yourself, because if they are inconsistent, Emacs may crash when you function yourself, because if they are inconsistent, Emacs may crash
call the function. Always leave it to the byte-compiler to create these when you call the function. Always leave it to the byte-compiler to
objects; it, we hope, always makes the elements consistent. 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 access the elements of a byte-code object using @code{aref};
you can also use @code{vconcat} to create a vector with the same you can also use @code{vconcat} to create a vector with the same
@ -324,14 +335,14 @@ disassembler converts the byte-compiled code into humanly readable
form. form.
The byte-code interpreter is implemented as a simple stack machine. 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 It pushes values onto a stack of its own, then pops them off to use them
manipulated, the results being pushed back onto the stack. When a in calculations and push the result back on the stack. When a byte-code
function returns, the top of the stack is popped and returned as the function returns, it pops a value off the stack and returns it as the
value of the function. value of the function.
In addition to the stack, values used during byte-code execution can In addition to the stack, byte-code functions can use, bind and set
be stored in ordinary Lisp variables. Variable values can be pushed ordinary Lisp variables, by transferring values between variables and
onto the stack, and variables can be set by popping the stack. the stack.
@deffn Command disassemble object &optional stream @deffn Command disassemble object &optional stream
This function prints the disassembled code for @var{object}. If This function prints the disassembled code for @var{object}. If
@ -500,7 +511,7 @@ The @code{silly-loop} function is somewhat more complex:
@group @group
5 dup ; @r{Duplicate the top of the stack;} 5 dup ; @r{Duplicate the top of the stack;}
; @r{i.e. copy the top of} ; @r{i.e., copy the top of}
; @r{the stack and push the} ; @r{the stack and push the}
; @r{copy onto the stack.} ; @r{copy onto the stack.}
@end group @end group