Mercurial > emacs
annotate lispref/compile.texi @ 6668:5ab295d49e7f
(generate-calendar-month): Add mouse-face properties.
author | Karl Heuer <kwzh@gnu.org> |
---|---|
date | Mon, 04 Apr 1994 22:59:59 +0000 |
parents | 8c7032348e93 |
children | 2f1305fcecf6 |
rev | line source |
---|---|
5945 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. |
5945 | 4 @c See the file elisp.texi for copying conditions. |
5 @setfilename ../info/compile | |
6 @node Byte Compilation, Debugging, Loading, Top | |
7 @chapter Byte Compilation | |
8 @cindex byte-code | |
9 @cindex compilation | |
10 | |
11 GNU Emacs Lisp has a @dfn{compiler} that translates functions written | |
12 in Lisp into a special representation called @dfn{byte-code} that can be | |
13 executed more efficiently. The compiler replaces Lisp function | |
14 definitions with byte-code. When a byte-code function is called, its | |
15 definition is evaluated by the @dfn{byte-code interpreter}. | |
16 | |
17 Because the byte-compiled code is evaluated by the byte-code | |
18 interpreter, instead of being executed directly by the machine's | |
19 hardware (as true compiled code is), byte-code is completely | |
20 transportable from machine to machine without recompilation. It is not, | |
21 however, as fast as true compiled code. | |
22 | |
23 In general, any version of Emacs can run byte-compiled code produced | |
24 by recent earlier versions of Emacs, but the reverse is not true. In | |
25 particular, if you compile a program with Emacs 18, you can run the | |
26 compiled code in Emacs 19, but not vice versa. | |
27 | |
28 @xref{Compilation Errors}, for how to investigate errors occurring in | |
29 byte compilation. | |
30 | |
31 @menu | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
32 * Speed of Byte-Code:: An example of speedup from byte compilation. |
5945 | 33 * Compilation Functions:: Byte compilation functions. |
34 * Eval During Compile:: Code to be evaluated when you compile. | |
35 * Byte-Code Objects:: The data type used for byte-compiled functions. | |
36 * Disassembly:: Disassembling byte-code; how to read byte-code. | |
37 @end menu | |
38 | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
39 @node Speed of Byte-Code |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
40 @section Performance of Byte-Compiled Code |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
41 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
42 A byte-compiled function is not as efficient as a primitive function |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
43 written in C, but runs much faster than the version written in Lisp. |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
44 Here is an example: |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
45 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
46 @example |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
47 @group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
48 (defun silly-loop (n) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
49 "Return time before and after N iterations of a loop." |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
50 (let ((t1 (current-time-string))) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
51 (while (> (setq n (1- n)) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
52 0)) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
53 (list t1 (current-time-string)))) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
54 @result{} silly-loop |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
55 @end group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
56 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
57 @group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
58 (silly-loop 100000) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
59 @result{} ("Fri Mar 18 17:25:57 1994" |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
60 "Fri Mar 18 17:26:28 1994") ; @r{31 seconds} |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
61 @end group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
62 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
63 @group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
64 (byte-compile 'silly-loop) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
65 @result{} @r{[Compiled code not shown]} |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
66 @end group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
67 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
68 @group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
69 (silly-loop 100000) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
70 @result{} ("Fri Mar 18 17:26:52 1994" |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
71 "Fri Mar 18 17:26:58 1994") ; @r{6 seconds} |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
72 @end group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
73 @end example |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
74 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
75 In this example, the interpreted code required 31 seconds to run, |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
76 whereas the byte-compiled code required 6 seconds. These results are |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
77 representative, but actual results will vary greatly. |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
78 |
5945 | 79 @node Compilation Functions |
80 @comment node-name, next, previous, up | |
81 @section The Compilation Functions | |
82 @cindex compilation functions | |
83 | |
84 You can byte-compile an individual function or macro definition with | |
85 the @code{byte-compile} function. You can compile a whole file with | |
86 @code{byte-compile-file}, or several files with | |
87 @code{byte-recompile-directory} or @code{batch-byte-compile}. | |
88 | |
89 When you run the byte compiler, you may get warnings in a buffer called | |
90 @samp{*Compile-Log*}. These report usage in your program that suggest a | |
91 problem, but are not necessarily erroneous. | |
92 | |
93 @cindex macro compilation | |
94 Be careful when byte-compiling code that uses macros. Macro calls are | |
95 expanded when they are compiled, so the macros must already be defined | |
96 for proper compilation. For more details, see @ref{Compiling Macros}. | |
97 | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
98 Normally, compiling a file does not evaluate the file's contents or |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
99 load the file. But it does execute any @code{require} calls at |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
100 top-level in the file. One way to ensure that necessary macro |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
101 definitions are available during compilation is to require the file that |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
102 defines them. @xref{Features}. |
5945 | 103 |
104 @defun byte-compile symbol | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
105 This function byte-compiles the function definition of @var{symbol}, |
5945 | 106 replacing the previous definition with the compiled one. The function |
107 definition of @var{symbol} must be the actual code for the function; | |
108 i.e., the compiler does not follow indirection to another symbol. | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
109 @code{byte-compile} returns the new, compiled definition of |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
110 @var{symbol}. |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
111 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
112 If @var{symbol}'s definition is a byte-code function object, |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
113 @code{byte-compile} does nothing and returns @code{nil}. Lisp records |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
114 only one function definition for any symbol, and if that is already |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
115 compiled, non-compiled code is not available anywhere. So there is no |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
116 way to ``compile the same definition again.'' |
5945 | 117 |
118 @example | |
119 @group | |
120 (defun factorial (integer) | |
121 "Compute factorial of INTEGER." | |
122 (if (= 1 integer) 1 | |
123 (* integer (factorial (1- integer))))) | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
124 @result{} factorial |
5945 | 125 @end group |
126 | |
127 @group | |
128 (byte-compile 'factorial) | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
129 @result{} |
5945 | 130 #[(integer) |
131 "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207" | |
132 [integer 1 * factorial] | |
133 4 "Compute factorial of INTEGER."] | |
134 @end group | |
135 @end example | |
136 | |
137 @noindent | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
138 The result is a byte-code function object. The string it contains is |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
139 the actual byte-code; each character in it is an instruction or an |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
140 operand of an instruction. The vector contains all the constants, |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
141 variable names and function names used by the function, except for |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
142 certain primitives that are coded as special instructions. |
5945 | 143 @end defun |
144 | |
145 @deffn Command compile-defun | |
146 This command reads the defun containing point, compiles it, and | |
147 evaluates the result. If you use this on a defun that is actually a | |
148 function definition, the effect is to install a compiled version of that | |
149 function. | |
150 @end deffn | |
151 | |
152 @deffn Command byte-compile-file filename | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
153 This function compiles a file of Lisp code named @var{filename} into |
5945 | 154 a file of byte-code. The output file's name is made by appending |
155 @samp{c} to the end of @var{filename}. | |
156 | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
157 Compilation works by reading the input file one form at a time. If it |
5945 | 158 is a definition of a function or macro, the compiled function or macro |
159 definition is written out. Other forms are batched together, then each | |
160 batch is compiled, and written so that its compiled code will be | |
161 executed when the file is read. All comments are discarded when the | |
162 input file is read. | |
163 | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
164 This command returns @code{t}. When called interactively, it prompts |
5945 | 165 for the file name. |
166 | |
167 @example | |
168 @group | |
169 % ls -l push* | |
170 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el | |
171 @end group | |
172 | |
173 @group | |
174 (byte-compile-file "~/emacs/push.el") | |
175 @result{} t | |
176 @end group | |
177 | |
178 @group | |
179 % ls -l push* | |
180 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el | |
181 -rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc | |
182 @end group | |
183 @end example | |
184 @end deffn | |
185 | |
186 @deffn Command byte-recompile-directory directory flag | |
187 @cindex library compilation | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
188 This function recompiles every @samp{.el} file in @var{directory} that |
5945 | 189 needs recompilation. A file needs recompilation if a @samp{.elc} file |
190 exists but is older than the @samp{.el} file. | |
191 | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
192 If a @samp{.el} file exists, but there is no corresponding @samp{.elc} |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
193 file, then @var{flag} says what to do. If it is @code{nil}, the file is |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
194 ignored. If it is non-@code{nil}, the user is asked whether to compile |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
195 the file. |
5945 | 196 |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
197 The returned value of this command is unpredictable. |
5945 | 198 @end deffn |
199 | |
200 @defun batch-byte-compile | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
201 This function runs @code{byte-compile-file} on files specified on the |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
202 command line. This function must be used only in a batch execution of |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
203 Emacs, as it kills Emacs on completion. An error in one file does not |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
204 prevent processing of subsequent files. (The file which gets the error |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
205 will not, of course, produce any compiled code.) |
5945 | 206 |
207 @example | |
208 % emacs -batch -f batch-byte-compile *.el | |
209 @end example | |
210 @end defun | |
211 | |
212 @defun byte-code code-string data-vector max-stack | |
213 @cindex byte-code interpreter | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
214 This function actually interprets byte-code. A byte-compiled function |
5945 | 215 is actually defined with a body that calls @code{byte-code}. Don't call |
216 this function yourself. Only the byte compiler knows how to generate | |
217 valid calls to this function. | |
218 | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
219 In newer Emacs versions (19 and up), byte-code is usually executed as |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
220 part of a byte-code function object, and only rarely due to an explicit |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
221 call to @code{byte-code}. |
5945 | 222 @end defun |
223 | |
224 @node Eval During Compile | |
225 @section Evaluation During Compilation | |
226 | |
227 These features permit you to write code to be evaluated during | |
228 compilation of a program. | |
229 | |
230 @defspec eval-and-compile body | |
231 This form marks @var{body} to be evaluated both when you compile the | |
232 containing code and when you run it (whether compiled or not). | |
233 | |
234 You can get a similar result by putting @var{body} in a separate file | |
235 and referring to that file with @code{require}. Using @code{require} is | |
236 preferable if there is a substantial amount of code to be executed in | |
237 this way. | |
238 @end defspec | |
239 | |
240 @defspec eval-when-compile body | |
241 This form marks @var{body} to be evaluated at compile time @emph{only}. | |
242 The result of evaluation by the compiler becomes a constant which | |
243 appears in the compiled program. When the program is interpreted, not | |
244 compiled at all, @var{body} is evaluated normally. | |
245 | |
246 At top-level, this is analogous to the Common Lisp idiom | |
247 @code{(eval-when (compile eval) @dots{})}. Elsewhere, the Common Lisp | |
248 @samp{#.} reader macro (but not when interpreting) is closer to what | |
249 @code{eval-when-compile} does. | |
250 @end defspec | |
251 | |
252 @node Byte-Code Objects | |
253 @section Byte-Code Objects | |
254 @cindex compiled function | |
255 @cindex byte-code function | |
256 | |
257 Byte-compiled functions have a special data type: they are | |
258 @dfn{byte-code function objects}. | |
259 | |
260 Internally, a byte-code function object is much like a vector; | |
261 however, the evaluator handles this data type specially when it appears | |
262 as a function to be called. The printed representation for a byte-code | |
263 function object is like that for a vector, with an additional @samp{#} | |
264 before the opening @samp{[}. | |
265 | |
266 In Emacs version 18, there was no byte-code function object data type; | |
267 compiled functions used the function @code{byte-code} to run the byte | |
268 code. | |
269 | |
270 A byte-code function object must have at least four elements; there is | |
271 no maximum number, but only the first six elements are actually used. | |
272 They are: | |
273 | |
274 @table @var | |
275 @item arglist | |
276 The list of argument symbols. | |
277 | |
278 @item byte-code | |
279 The string containing the byte-code instructions. | |
280 | |
281 @item constants | |
282 The vector of constants referenced by the byte code. | |
283 | |
284 @item stacksize | |
285 The maximum stack size this function needs. | |
286 | |
287 @item docstring | |
288 The documentation string (if any); otherwise, @code{nil}. For functions | |
289 preloaded before Emacs is dumped, this is usually an integer which is an | |
290 index into the @file{DOC} file; use @code{documentation} to convert this | |
291 into a string (@pxref{Accessing Documentation}). | |
292 | |
293 @item interactive | |
294 The interactive spec (if any). This can be a string or a Lisp | |
295 expression. It is @code{nil} for a function that isn't interactive. | |
296 @end table | |
297 | |
298 Here's an example of a byte-code function object, in printed | |
299 representation. It is the definition of the command | |
300 @code{backward-sexp}. | |
301 | |
302 @example | |
303 #[(&optional arg) | |
304 "^H\204^F^@@\301^P\302^H[!\207" | |
305 [arg 1 forward-sexp] | |
306 2 | |
307 254435 | |
308 "p"] | |
309 @end example | |
310 | |
311 The primitive way to create a byte-code object is with | |
312 @code{make-byte-code}: | |
313 | |
314 @defun make-byte-code &rest elements | |
315 This function constructs and returns a byte-code function object | |
316 with @var{elements} as its elements. | |
317 @end defun | |
318 | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
319 You should not try to come up with the elements for a byte-code |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
320 function yourself, because if they are inconsistent, Emacs may crash |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
321 when you call the function. Always leave it to the byte-compiler to |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
322 create these objects; it makes the elements consistent (we hope). |
5945 | 323 |
324 You can access the elements of a byte-code object using @code{aref}; | |
325 you can also use @code{vconcat} to create a vector with the same | |
326 elements. | |
327 | |
328 @node Disassembly | |
329 @section Disassembled Byte-Code | |
330 @cindex disassembled byte-code | |
331 | |
332 People do not write byte-code; that job is left to the byte compiler. | |
333 But we provide a disassembler to satisfy a cat-like curiosity. The | |
334 disassembler converts the byte-compiled code into humanly readable | |
335 form. | |
336 | |
337 The byte-code interpreter is implemented as a simple stack machine. | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
338 It pushes values onto a stack of its own, then pops them off to use them |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
339 in calculations and push the result back on the stack. When a byte-code |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
340 function returns, it pops a value off the stack and returns it as the |
5945 | 341 value of the function. |
342 | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
343 In addition to the stack, byte-code functions can use, bind and set |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
344 ordinary Lisp variables, by transferring values between variables and |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
345 the stack. |
5945 | 346 |
347 @deffn Command disassemble object &optional stream | |
348 This function prints the disassembled code for @var{object}. If | |
349 @var{stream} is supplied, then output goes there. Otherwise, the | |
350 disassembled code is printed to the stream @code{standard-output}. The | |
351 argument @var{object} can be a function name or a lambda expression. | |
352 | |
353 As a special exception, if this function is used interactively, | |
354 it outputs to a buffer named @samp{*Disassemble*}. | |
355 @end deffn | |
356 | |
357 Here are two examples of using the @code{disassemble} function. We | |
358 have added explanatory comments to help you relate the byte-code to the | |
359 Lisp source; these do not appear in the output of @code{disassemble}. | |
360 These examples show unoptimized byte-code. Nowadays byte-code is | |
361 usually optimized, but we did not want to rewrite these examples, since | |
362 they still serve their purpose. | |
363 | |
364 @example | |
365 @group | |
366 (defun factorial (integer) | |
367 "Compute factorial of an integer." | |
368 (if (= 1 integer) 1 | |
369 (* integer (factorial (1- integer))))) | |
370 @result{} factorial | |
371 @end group | |
372 | |
373 @group | |
374 (factorial 4) | |
375 @result{} 24 | |
376 @end group | |
377 | |
378 @group | |
379 (disassemble 'factorial) | |
380 @print{} byte-code for factorial: | |
381 doc: Compute factorial of an integer. | |
382 args: (integer) | |
383 @end group | |
384 | |
385 @group | |
386 0 constant 1 ; @r{Push 1 onto stack.} | |
387 | |
388 1 varref integer ; @r{Get value of @code{integer}} | |
389 ; @r{from the environment} | |
390 ; @r{and push the value} | |
391 ; @r{onto the stack.} | |
392 @end group | |
393 | |
394 @group | |
395 2 eqlsign ; @r{Pop top two values off stack,} | |
396 ; @r{compare them,} | |
397 ; @r{and push result onto stack.} | |
398 @end group | |
399 | |
400 @group | |
401 3 goto-if-nil 10 ; @r{Pop and test top of stack;} | |
402 ; @r{if @code{nil}, go to 10,} | |
403 ; @r{else continue.} | |
404 @end group | |
405 | |
406 @group | |
407 6 constant 1 ; @r{Push 1 onto top of stack.} | |
408 | |
409 7 goto 17 ; @r{Go to 17 (in this case, 1 will be} | |
410 ; @r{returned by the function).} | |
411 @end group | |
412 | |
413 @group | |
414 10 constant * ; @r{Push symbol @code{*} onto stack.} | |
415 | |
416 11 varref integer ; @r{Push value of @code{integer} onto stack.} | |
417 @end group | |
418 | |
419 @group | |
420 12 constant factorial ; @r{Push @code{factorial} onto stack.} | |
421 | |
422 13 varref integer ; @r{Push value of @code{integer} onto stack.} | |
423 | |
424 14 sub1 ; @r{Pop @code{integer}, decrement value,} | |
425 ; @r{push new value onto stack.} | |
426 @end group | |
427 | |
428 @group | |
429 ; @r{Stack now contains:} | |
430 ; @minus{} @r{decremented value of @code{integer}} | |
431 ; @minus{} @r{@code{factorial}} | |
432 ; @minus{} @r{value of @code{integer}} | |
433 ; @minus{} @r{@code{*}} | |
434 @end group | |
435 | |
436 @group | |
437 15 call 1 ; @r{Call function @code{factorial} using} | |
438 ; @r{the first (i.e., the top) element} | |
439 ; @r{of the stack as the argument;} | |
440 ; @r{push returned value onto stack.} | |
441 @end group | |
442 | |
443 @group | |
444 ; @r{Stack now contains:} | |
445 ; @minus{} @r{result of result of recursive} | |
446 ; @r{call to @code{factorial}} | |
447 ; @minus{} @r{value of @code{integer}} | |
448 ; @minus{} @r{@code{*}} | |
449 @end group | |
450 | |
451 @group | |
452 16 call 2 ; @r{Using the first two} | |
453 ; @r{(i.e., the top two)} | |
454 ; @r{elements of the stack} | |
455 ; @r{as arguments,} | |
456 ; @r{call the function @code{*},} | |
457 ; @r{pushing the result onto the stack.} | |
458 @end group | |
459 | |
460 @group | |
461 17 return ; @r{Return the top element} | |
462 ; @r{of the stack.} | |
463 @result{} nil | |
464 @end group | |
465 @end example | |
466 | |
467 The @code{silly-loop} function is somewhat more complex: | |
468 | |
469 @example | |
470 @group | |
471 (defun silly-loop (n) | |
472 "Return time before and after N iterations of a loop." | |
473 (let ((t1 (current-time-string))) | |
474 (while (> (setq n (1- n)) | |
475 0)) | |
476 (list t1 (current-time-string)))) | |
477 @result{} silly-loop | |
478 @end group | |
479 | |
480 @group | |
481 (disassemble 'silly-loop) | |
482 @print{} byte-code for silly-loop: | |
483 doc: Return time before and after N iterations of a loop. | |
484 args: (n) | |
485 | |
486 0 constant current-time-string ; @r{Push} | |
487 ; @r{@code{current-time-string}} | |
488 ; @r{onto top of stack.} | |
489 @end group | |
490 | |
491 @group | |
492 1 call 0 ; @r{Call @code{current-time-string}} | |
493 ; @r{ with no argument,} | |
494 ; @r{ pushing result onto stack.} | |
495 @end group | |
496 | |
497 @group | |
498 2 varbind t1 ; @r{Pop stack and bind @code{t1}} | |
499 ; @r{to popped value.} | |
500 @end group | |
501 | |
502 @group | |
503 3 varref n ; @r{Get value of @code{n} from} | |
504 ; @r{the environment and push} | |
505 ; @r{the value onto the stack.} | |
506 @end group | |
507 | |
508 @group | |
509 4 sub1 ; @r{Subtract 1 from top of stack.} | |
510 @end group | |
511 | |
512 @group | |
513 5 dup ; @r{Duplicate the top of the stack;} | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
514 ; @r{i.e., copy the top of} |
5945 | 515 ; @r{the stack and push the} |
516 ; @r{copy onto the stack.} | |
517 @end group | |
518 | |
519 @group | |
520 6 varset n ; @r{Pop the top of the stack,} | |
521 ; @r{and bind @code{n} to the value.} | |
522 | |
523 ; @r{In effect, the sequence @code{dup varset}} | |
524 ; @r{copies the top of the stack} | |
525 ; @r{into the value of @code{n}} | |
526 ; @r{without popping it.} | |
527 @end group | |
528 | |
529 @group | |
530 7 constant 0 ; @r{Push 0 onto stack.} | |
531 @end group | |
532 | |
533 @group | |
534 8 gtr ; @r{Pop top two values off stack,} | |
535 ; @r{test if @var{n} is greater than 0} | |
536 ; @r{and push result onto stack.} | |
537 @end group | |
538 | |
539 @group | |
540 9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} > 0} | |
541 ; @r{else pop top of stack} | |
542 ; @r{and continue} | |
543 ; @r{(this exits the while loop).} | |
544 @end group | |
545 | |
546 @group | |
547 12 constant nil ; @r{Push @code{nil} onto stack} | |
548 ; @r{(this is the body of the loop).} | |
549 @end group | |
550 | |
551 @group | |
552 13 discard ; @r{Discard result of the body} | |
553 ; @r{of the loop (a while loop} | |
554 ; @r{is always evaluated for} | |
555 ; @r{its side effects).} | |
556 @end group | |
557 | |
558 @group | |
559 14 goto 3 ; @r{Jump back to beginning} | |
560 ; @r{of while loop.} | |
561 @end group | |
562 | |
563 @group | |
564 17 discard ; @r{Discard result of while loop} | |
565 ; @r{by popping top of stack.} | |
566 @end group | |
567 | |
568 @group | |
569 18 varref t1 ; @r{Push value of @code{t1} onto stack.} | |
570 @end group | |
571 | |
572 @group | |
573 19 constant current-time-string ; @r{Push} | |
574 ; @r{@code{current-time-string}} | |
575 ; @r{onto top of stack.} | |
576 @end group | |
577 | |
578 @group | |
579 20 call 0 ; @r{Call @code{current-time-string} again.} | |
580 @end group | |
581 | |
582 @group | |
583 21 list2 ; @r{Pop top two elements off stack,} | |
584 ; @r{create a list of them,} | |
585 ; @r{and push list onto stack.} | |
586 @end group | |
587 | |
588 @group | |
589 22 unbind 1 ; @r{Unbind @code{t1} in local environment.} | |
590 | |
591 23 return ; @r{Return value of the top of stack.} | |
592 | |
593 @result{} nil | |
594 @end group | |
595 @end example | |
596 | |
597 |