Mercurial > emacs
annotate lispref/compile.texi @ 21195:169fde4a67c1
(rmail-clear-headers): Make sure an empty line
still separates the headers from the body.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Mon, 16 Mar 1998 18:11:20 +0000 |
parents | 66d807bdc5b4 |
children | 90da2489c498 |
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 | |
12067 | 25 particular, if you compile a program with Emacs 19.29, the compiled |
26 code does not run in earlier versions. | |
12098 | 27 @iftex |
28 @xref{Docs and Compilation}. | |
29 @end iftex | |
30 Files compiled in versions before 19.29 may not work in 19.29 if they | |
31 contain character constants with modifier bits, because the bits were | |
32 renumbered in Emacs 19.29. | |
5945 | 33 |
34 @xref{Compilation Errors}, for how to investigate errors occurring in | |
35 byte compilation. | |
36 | |
37 @menu | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
38 * Speed of Byte-Code:: An example of speedup from byte compilation. |
5945 | 39 * Compilation Functions:: Byte compilation functions. |
12067 | 40 * Docs and Compilation:: Dynamic loading of documentation strings. |
41 * Dynamic Loading:: Dynamic loading of individual functions. | |
5945 | 42 * Eval During Compile:: Code to be evaluated when you compile. |
43 * Byte-Code Objects:: The data type used for byte-compiled functions. | |
44 * Disassembly:: Disassembling byte-code; how to read byte-code. | |
45 @end menu | |
46 | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
47 @node Speed of Byte-Code |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
48 @section Performance of Byte-Compiled Code |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
49 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
50 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
|
51 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
|
52 Here is an example: |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
53 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
54 @example |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
55 @group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
56 (defun silly-loop (n) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
57 "Return time before and after N iterations of a loop." |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
58 (let ((t1 (current-time-string))) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
59 (while (> (setq n (1- n)) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
60 0)) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
61 (list t1 (current-time-string)))) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
62 @result{} silly-loop |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
63 @end group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
64 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
65 @group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
66 (silly-loop 100000) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
67 @result{} ("Fri Mar 18 17:25:57 1994" |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
68 "Fri Mar 18 17:26:28 1994") ; @r{31 seconds} |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
69 @end group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
70 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
71 @group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
72 (byte-compile 'silly-loop) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
73 @result{} @r{[Compiled code not shown]} |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
74 @end group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
75 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
76 @group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
77 (silly-loop 100000) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
78 @result{} ("Fri Mar 18 17:26:52 1994" |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
79 "Fri Mar 18 17:26:58 1994") ; @r{6 seconds} |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
80 @end group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
81 @end example |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
82 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
83 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
|
84 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
|
85 representative, but actual results will vary greatly. |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
86 |
5945 | 87 @node Compilation Functions |
88 @comment node-name, next, previous, up | |
89 @section The Compilation Functions | |
90 @cindex compilation functions | |
91 | |
92 You can byte-compile an individual function or macro definition with | |
93 the @code{byte-compile} function. You can compile a whole file with | |
94 @code{byte-compile-file}, or several files with | |
95 @code{byte-recompile-directory} or @code{batch-byte-compile}. | |
96 | |
16736
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
12128
diff
changeset
|
97 The byte compiler produces error messages and warnings about each file |
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
12128
diff
changeset
|
98 in a buffer called @samp{*Compile-Log*}. These report things in your |
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
12128
diff
changeset
|
99 program that suggest a problem but are not necessarily erroneous. |
5945 | 100 |
101 @cindex macro compilation | |
102 Be careful when byte-compiling code that uses macros. Macro calls are | |
103 expanded when they are compiled, so the macros must already be defined | |
104 for proper compilation. For more details, see @ref{Compiling Macros}. | |
105 | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
106 Normally, compiling a file does not evaluate the file's contents or |
12098 | 107 load the file. But it does execute any @code{require} calls at top |
108 level in the file. One way to ensure that necessary macro definitions | |
109 are available during compilation is to require the file that defines | |
110 them (@pxref{Named Features}). To avoid loading the macro definition files | |
111 when someone @emph{runs} the compiled program, write | |
112 @code{eval-when-compile} around the @code{require} calls (@pxref{Eval | |
113 During Compile}). | |
5945 | 114 |
115 @defun byte-compile symbol | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
116 This function byte-compiles the function definition of @var{symbol}, |
5945 | 117 replacing the previous definition with the compiled one. The function |
118 definition of @var{symbol} must be the actual code for the function; | |
119 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
|
120 @code{byte-compile} returns the new, compiled definition of |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
121 @var{symbol}. |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
122 |
12067 | 123 If @var{symbol}'s definition is a byte-code function object, |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
124 @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
|
125 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
|
126 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
|
127 way to ``compile the same definition again.'' |
5945 | 128 |
129 @example | |
130 @group | |
131 (defun factorial (integer) | |
132 "Compute factorial of INTEGER." | |
133 (if (= 1 integer) 1 | |
134 (* integer (factorial (1- integer))))) | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
135 @result{} factorial |
5945 | 136 @end group |
137 | |
138 @group | |
139 (byte-compile 'factorial) | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
140 @result{} |
5945 | 141 #[(integer) |
142 "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207" | |
143 [integer 1 * factorial] | |
144 4 "Compute factorial of INTEGER."] | |
145 @end group | |
146 @end example | |
147 | |
148 @noindent | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
149 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
|
150 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
|
151 operand of an instruction. The vector contains all the constants, |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
152 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
|
153 certain primitives that are coded as special instructions. |
5945 | 154 @end defun |
155 | |
156 @deffn Command compile-defun | |
157 This command reads the defun containing point, compiles it, and | |
158 evaluates the result. If you use this on a defun that is actually a | |
159 function definition, the effect is to install a compiled version of that | |
160 function. | |
161 @end deffn | |
162 | |
163 @deffn Command byte-compile-file filename | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
164 This function compiles a file of Lisp code named @var{filename} into |
5945 | 165 a file of byte-code. The output file's name is made by appending |
166 @samp{c} to the end of @var{filename}. | |
167 | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
168 Compilation works by reading the input file one form at a time. If it |
5945 | 169 is a definition of a function or macro, the compiled function or macro |
170 definition is written out. Other forms are batched together, then each | |
171 batch is compiled, and written so that its compiled code will be | |
172 executed when the file is read. All comments are discarded when the | |
173 input file is read. | |
174 | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
175 This command returns @code{t}. When called interactively, it prompts |
5945 | 176 for the file name. |
177 | |
178 @example | |
179 @group | |
180 % ls -l push* | |
181 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el | |
182 @end group | |
183 | |
184 @group | |
185 (byte-compile-file "~/emacs/push.el") | |
186 @result{} t | |
187 @end group | |
188 | |
189 @group | |
190 % ls -l push* | |
191 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el | |
192 -rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc | |
193 @end group | |
194 @end example | |
195 @end deffn | |
196 | |
197 @deffn Command byte-recompile-directory directory flag | |
198 @cindex library compilation | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
199 This function recompiles every @samp{.el} file in @var{directory} that |
5945 | 200 needs recompilation. A file needs recompilation if a @samp{.elc} file |
201 exists but is older than the @samp{.el} file. | |
202 | |
12098 | 203 When a @samp{.el} file has no corresponding @samp{.elc} file, then |
204 @var{flag} says what to do. If it is @code{nil}, these files are | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
205 ignored. If it is non-@code{nil}, the user is asked whether to compile |
12098 | 206 each such file. |
5945 | 207 |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
208 The returned value of this command is unpredictable. |
5945 | 209 @end deffn |
210 | |
211 @defun batch-byte-compile | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
212 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
|
213 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
|
214 Emacs, as it kills Emacs on completion. An error in one file does not |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
215 prevent processing of subsequent files, but no output file will be |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
216 generated for it, and the Emacs process will terminate with a nonzero |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
217 status code. |
5945 | 218 |
219 @example | |
220 % emacs -batch -f batch-byte-compile *.el | |
221 @end example | |
222 @end defun | |
223 | |
224 @defun byte-code code-string data-vector max-stack | |
225 @cindex byte-code interpreter | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
226 This function actually interprets byte-code. A byte-compiled function |
5945 | 227 is actually defined with a body that calls @code{byte-code}. Don't call |
228 this function yourself. Only the byte compiler knows how to generate | |
229 valid calls to this function. | |
230 | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
231 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
|
232 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
|
233 call to @code{byte-code}. |
5945 | 234 @end defun |
235 | |
12067 | 236 @node Docs and Compilation |
237 @section Documentation Strings and Compilation | |
238 @cindex dynamic loading of documentation | |
239 | |
240 Functions and variables loaded from a byte-compiled file access their | |
241 documentation strings dynamically from the file whenever needed. This | |
12128
27144f55d1c6
fixed errors that appeared during update to 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents:
12124
diff
changeset
|
242 saves space within Emacs, and makes loading faster because the |
12067 | 243 documentation strings themselves need not be processed while loading the |
244 file. Actual access to the documentation strings becomes slower as a | |
245 result, but this normally is not enough to bother users. | |
246 | |
247 Dynamic access to documentation strings does have drawbacks: | |
248 | |
249 @itemize @bullet | |
250 @item | |
251 If you delete or move the compiled file after loading it, Emacs can no | |
252 longer access the documentation strings for the functions and variables | |
253 in the file. | |
254 | |
255 @item | |
256 If you alter the compiled file (such as by compiling a new version), | |
257 then further access to documentation strings in this file will give | |
258 nonsense results. | |
259 @end itemize | |
260 | |
261 If your site installs Emacs following the usual procedures, these | |
262 problems will never normally occur. Installing a new version uses a new | |
263 directory with a different name; as long as the old version remains | |
264 installed, its files will remain unmodified in the places where they are | |
265 expected to be. | |
266 | |
12124 | 267 However, if you have built Emacs yourself and use it from the |
12067 | 268 directory where you built it, you will experience this problem |
269 occasionally if you edit and recompile Lisp files. When it happens, you | |
270 can cure the problem by reloading the file after recompiling it. | |
271 | |
272 Byte-compiled files made with Emacs 19.29 will not load into older | |
273 versions because the older versions don't support this feature. You can | |
274 turn off this feature by setting @code{byte-compile-dynamic-docstrings} | |
275 to @code{nil}. Once this is done, you can compile files that will load | |
276 into older Emacs versions. You can do this globally, or for one source | |
277 file by specifying a file-local binding for the variable. Here's one | |
12098 | 278 way to do that: |
12067 | 279 |
280 @example | |
281 -*-byte-compile-dynamic-docstrings: nil;-*- | |
282 @end example | |
283 | |
284 @defvar byte-compile-dynamic-docstrings | |
285 If this is non-@code{nil}, the byte compiler generates compiled files | |
286 that are set up for dynamic loading of documentation strings. | |
287 @end defvar | |
288 | |
289 @cindex @samp{#@@@var{count}} | |
290 @cindex @samp{#$} | |
291 The dynamic documentation string feature writes compiled files that | |
292 use a special Lisp reader construct, @samp{#@@@var{count}}. This | |
293 construct skips the next @var{count} characters. It also uses the | |
294 @samp{#$} construct, which stands for ``the name of this file, as a | |
295 string.'' It is best not to use these constructs in Lisp source files. | |
296 | |
297 @node Dynamic Loading | |
298 @section Dynamic Loading of Individual Functions | |
299 | |
300 @cindex dynamic loading of functions | |
301 @cindex lazy loading | |
302 When you compile a file, you can optionally enable the @dfn{dynamic | |
303 function loading} feature (also known as @dfn{lazy loading}). With | |
304 dynamic function loading, loading the file doesn't fully read the | |
305 function definitions in the file. Instead, each function definition | |
306 contains a place-holder which refers to the file. The first time each | |
307 function is called, it reads the full definition from the file, to | |
308 replace the place-holder. | |
309 | |
310 The advantage of dynamic function loading is that loading the file | |
311 becomes much faster. This is a good thing for a file which contains | |
312 many separate commands, provided that using one of them does not imply | |
313 you will soon (or ever) use the rest. A specialized mode which provides | |
314 many keyboard commands often has that usage pattern: a user may invoke | |
315 the mode, but use only a few of the commands it provides. | |
316 | |
317 The dynamic loading feature has certain disadvantages: | |
318 | |
319 @itemize @bullet | |
320 @item | |
321 If you delete or move the compiled file after loading it, Emacs can no | |
322 longer load the remaining function definitions not already loaded. | |
323 | |
324 @item | |
325 If you alter the compiled file (such as by compiling a new version), | |
326 then trying to load any function not already loaded will get nonsense | |
327 results. | |
328 @end itemize | |
329 | |
330 If you compile a new version of the file, the best thing to do is | |
331 immediately load the new compiled file. That will prevent any future | |
332 problems. | |
333 | |
334 The byte compiler uses the dynamic function loading feature if the | |
335 variable @code{byte-compile-dynamic} is non-@code{nil} at compilation | |
336 time. Do not set this variable globally, since dynamic loading is | |
337 desirable only for certain files. Instead, enable the feature for | |
338 specific source files with file-local variable bindings, like this: | |
339 | |
340 @example | |
341 -*-byte-compile-dynamic: t;-*- | |
342 @end example | |
343 | |
344 @defvar byte-compile-dynamic | |
345 If this is non-@code{nil}, the byte compiler generates compiled files | |
346 that are set up for dynamic function loading. | |
347 @end defvar | |
348 | |
349 @defun fetch-bytecode function | |
350 This immediately finishes loading the definition of @var{function} from | |
351 its byte-compiled file, if it is not fully loaded already. The argument | |
352 @var{function} may be a byte-code function object or a function name. | |
353 @end defun | |
354 | |
5945 | 355 @node Eval During Compile |
356 @section Evaluation During Compilation | |
357 | |
12067 | 358 These features permit you to write code to be evaluated during |
5945 | 359 compilation of a program. |
360 | |
361 @defspec eval-and-compile body | |
362 This form marks @var{body} to be evaluated both when you compile the | |
363 containing code and when you run it (whether compiled or not). | |
364 | |
365 You can get a similar result by putting @var{body} in a separate file | |
366 and referring to that file with @code{require}. Using @code{require} is | |
367 preferable if there is a substantial amount of code to be executed in | |
368 this way. | |
369 @end defspec | |
370 | |
371 @defspec eval-when-compile body | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
372 This form marks @var{body} to be evaluated at compile time but not when |
7212 | 373 the compiled program is loaded. The result of evaluation by the |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
374 compiler becomes a constant which appears in the compiled program. If |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
375 you load the source file, rather than compiling it, @var{body} is |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
376 evaluated normally. |
5945 | 377 |
7212 | 378 At top level, this is analogous to the Common Lisp idiom |
5945 | 379 @code{(eval-when (compile eval) @dots{})}. Elsewhere, the Common Lisp |
380 @samp{#.} reader macro (but not when interpreting) is closer to what | |
381 @code{eval-when-compile} does. | |
382 @end defspec | |
383 | |
384 @node Byte-Code Objects | |
12098 | 385 @section Byte-Code Function Objects |
5945 | 386 @cindex compiled function |
387 @cindex byte-code function | |
388 | |
389 Byte-compiled functions have a special data type: they are | |
390 @dfn{byte-code function objects}. | |
391 | |
392 Internally, a byte-code function object is much like a vector; | |
393 however, the evaluator handles this data type specially when it appears | |
394 as a function to be called. The printed representation for a byte-code | |
395 function object is like that for a vector, with an additional @samp{#} | |
396 before the opening @samp{[}. | |
397 | |
398 In Emacs version 18, there was no byte-code function object data type; | |
399 compiled functions used the function @code{byte-code} to run the byte | |
400 code. | |
401 | |
402 A byte-code function object must have at least four elements; there is | |
403 no maximum number, but only the first six elements are actually used. | |
404 They are: | |
405 | |
406 @table @var | |
407 @item arglist | |
408 The list of argument symbols. | |
409 | |
410 @item byte-code | |
411 The string containing the byte-code instructions. | |
412 | |
413 @item constants | |
7212 | 414 The vector of Lisp objects referenced by the byte code. These include |
415 symbols used as function names and variable names. | |
5945 | 416 |
417 @item stacksize | |
418 The maximum stack size this function needs. | |
419 | |
420 @item docstring | |
12098 | 421 The documentation string (if any); otherwise, @code{nil}. The value may |
422 be a number or a list, in case the documentation string is stored in a | |
423 file. Use the function @code{documentation} to get the real | |
424 documentation string (@pxref{Accessing Documentation}). | |
5945 | 425 |
426 @item interactive | |
427 The interactive spec (if any). This can be a string or a Lisp | |
428 expression. It is @code{nil} for a function that isn't interactive. | |
429 @end table | |
430 | |
431 Here's an example of a byte-code function object, in printed | |
432 representation. It is the definition of the command | |
433 @code{backward-sexp}. | |
434 | |
435 @example | |
436 #[(&optional arg) | |
437 "^H\204^F^@@\301^P\302^H[!\207" | |
438 [arg 1 forward-sexp] | |
439 2 | |
440 254435 | |
441 "p"] | |
442 @end example | |
443 | |
444 The primitive way to create a byte-code object is with | |
445 @code{make-byte-code}: | |
446 | |
447 @defun make-byte-code &rest elements | |
448 This function constructs and returns a byte-code function object | |
449 with @var{elements} as its elements. | |
450 @end defun | |
451 | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
452 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
|
453 function yourself, because if they are inconsistent, Emacs may crash |
7212 | 454 when you call the function. Always leave it to the byte compiler to |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
455 create these objects; it makes the elements consistent (we hope). |
5945 | 456 |
457 You can access the elements of a byte-code object using @code{aref}; | |
458 you can also use @code{vconcat} to create a vector with the same | |
459 elements. | |
460 | |
461 @node Disassembly | |
462 @section Disassembled Byte-Code | |
463 @cindex disassembled byte-code | |
464 | |
465 People do not write byte-code; that job is left to the byte compiler. | |
466 But we provide a disassembler to satisfy a cat-like curiosity. The | |
467 disassembler converts the byte-compiled code into humanly readable | |
468 form. | |
469 | |
470 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
|
471 It pushes values onto a stack of its own, then pops them off to use them |
7212 | 472 in calculations whose results are themselves pushed back on the stack. |
473 When a byte-code function returns, it pops a value off the stack and | |
474 returns it as the value of the function. | |
5945 | 475 |
7212 | 476 In addition to the stack, byte-code functions can use, bind, and set |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
477 ordinary Lisp variables, by transferring values between variables and |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
478 the stack. |
5945 | 479 |
480 @deffn Command disassemble object &optional stream | |
481 This function prints the disassembled code for @var{object}. If | |
482 @var{stream} is supplied, then output goes there. Otherwise, the | |
483 disassembled code is printed to the stream @code{standard-output}. The | |
484 argument @var{object} can be a function name or a lambda expression. | |
485 | |
486 As a special exception, if this function is used interactively, | |
487 it outputs to a buffer named @samp{*Disassemble*}. | |
488 @end deffn | |
489 | |
490 Here are two examples of using the @code{disassemble} function. We | |
491 have added explanatory comments to help you relate the byte-code to the | |
492 Lisp source; these do not appear in the output of @code{disassemble}. | |
493 These examples show unoptimized byte-code. Nowadays byte-code is | |
494 usually optimized, but we did not want to rewrite these examples, since | |
495 they still serve their purpose. | |
496 | |
497 @example | |
498 @group | |
499 (defun factorial (integer) | |
500 "Compute factorial of an integer." | |
501 (if (= 1 integer) 1 | |
502 (* integer (factorial (1- integer))))) | |
503 @result{} factorial | |
504 @end group | |
505 | |
506 @group | |
507 (factorial 4) | |
508 @result{} 24 | |
509 @end group | |
510 | |
511 @group | |
512 (disassemble 'factorial) | |
513 @print{} byte-code for factorial: | |
514 doc: Compute factorial of an integer. | |
515 args: (integer) | |
516 @end group | |
517 | |
518 @group | |
519 0 constant 1 ; @r{Push 1 onto stack.} | |
520 | |
521 1 varref integer ; @r{Get value of @code{integer}} | |
522 ; @r{from the environment} | |
523 ; @r{and push the value} | |
524 ; @r{onto the stack.} | |
525 @end group | |
526 | |
527 @group | |
528 2 eqlsign ; @r{Pop top two values off stack,} | |
529 ; @r{compare them,} | |
530 ; @r{and push result onto stack.} | |
531 @end group | |
532 | |
533 @group | |
534 3 goto-if-nil 10 ; @r{Pop and test top of stack;} | |
535 ; @r{if @code{nil}, go to 10,} | |
536 ; @r{else continue.} | |
537 @end group | |
538 | |
539 @group | |
540 6 constant 1 ; @r{Push 1 onto top of stack.} | |
541 | |
542 7 goto 17 ; @r{Go to 17 (in this case, 1 will be} | |
543 ; @r{returned by the function).} | |
544 @end group | |
545 | |
546 @group | |
547 10 constant * ; @r{Push symbol @code{*} onto stack.} | |
548 | |
549 11 varref integer ; @r{Push value of @code{integer} onto stack.} | |
550 @end group | |
551 | |
552 @group | |
553 12 constant factorial ; @r{Push @code{factorial} onto stack.} | |
554 | |
555 13 varref integer ; @r{Push value of @code{integer} onto stack.} | |
556 | |
557 14 sub1 ; @r{Pop @code{integer}, decrement value,} | |
558 ; @r{push new value onto stack.} | |
559 @end group | |
560 | |
561 @group | |
562 ; @r{Stack now contains:} | |
563 ; @minus{} @r{decremented value of @code{integer}} | |
564 ; @minus{} @r{@code{factorial}} | |
565 ; @minus{} @r{value of @code{integer}} | |
566 ; @minus{} @r{@code{*}} | |
567 @end group | |
568 | |
569 @group | |
570 15 call 1 ; @r{Call function @code{factorial} using} | |
571 ; @r{the first (i.e., the top) element} | |
572 ; @r{of the stack as the argument;} | |
573 ; @r{push returned value onto stack.} | |
574 @end group | |
575 | |
576 @group | |
577 ; @r{Stack now contains:} | |
7212 | 578 ; @minus{} @r{result of recursive} |
5945 | 579 ; @r{call to @code{factorial}} |
580 ; @minus{} @r{value of @code{integer}} | |
581 ; @minus{} @r{@code{*}} | |
582 @end group | |
583 | |
584 @group | |
585 16 call 2 ; @r{Using the first two} | |
586 ; @r{(i.e., the top two)} | |
587 ; @r{elements of the stack} | |
588 ; @r{as arguments,} | |
589 ; @r{call the function @code{*},} | |
590 ; @r{pushing the result onto the stack.} | |
591 @end group | |
592 | |
593 @group | |
594 17 return ; @r{Return the top element} | |
595 ; @r{of the stack.} | |
596 @result{} nil | |
597 @end group | |
598 @end example | |
599 | |
600 The @code{silly-loop} function is somewhat more complex: | |
601 | |
602 @example | |
603 @group | |
604 (defun silly-loop (n) | |
605 "Return time before and after N iterations of a loop." | |
606 (let ((t1 (current-time-string))) | |
607 (while (> (setq n (1- n)) | |
608 0)) | |
609 (list t1 (current-time-string)))) | |
610 @result{} silly-loop | |
611 @end group | |
612 | |
613 @group | |
614 (disassemble 'silly-loop) | |
615 @print{} byte-code for silly-loop: | |
616 doc: Return time before and after N iterations of a loop. | |
617 args: (n) | |
618 | |
619 0 constant current-time-string ; @r{Push} | |
620 ; @r{@code{current-time-string}} | |
621 ; @r{onto top of stack.} | |
622 @end group | |
623 | |
624 @group | |
625 1 call 0 ; @r{Call @code{current-time-string}} | |
626 ; @r{ with no argument,} | |
627 ; @r{ pushing result onto stack.} | |
628 @end group | |
629 | |
630 @group | |
631 2 varbind t1 ; @r{Pop stack and bind @code{t1}} | |
632 ; @r{to popped value.} | |
633 @end group | |
634 | |
635 @group | |
636 3 varref n ; @r{Get value of @code{n} from} | |
637 ; @r{the environment and push} | |
638 ; @r{the value onto the stack.} | |
639 @end group | |
640 | |
641 @group | |
642 4 sub1 ; @r{Subtract 1 from top of stack.} | |
643 @end group | |
644 | |
645 @group | |
646 5 dup ; @r{Duplicate the top of the stack;} | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
647 ; @r{i.e., copy the top of} |
5945 | 648 ; @r{the stack and push the} |
649 ; @r{copy onto the stack.} | |
650 @end group | |
651 | |
652 @group | |
653 6 varset n ; @r{Pop the top of the stack,} | |
654 ; @r{and bind @code{n} to the value.} | |
655 | |
656 ; @r{In effect, the sequence @code{dup varset}} | |
657 ; @r{copies the top of the stack} | |
658 ; @r{into the value of @code{n}} | |
659 ; @r{without popping it.} | |
660 @end group | |
661 | |
662 @group | |
663 7 constant 0 ; @r{Push 0 onto stack.} | |
664 @end group | |
665 | |
666 @group | |
667 8 gtr ; @r{Pop top two values off stack,} | |
668 ; @r{test if @var{n} is greater than 0} | |
669 ; @r{and push result onto stack.} | |
670 @end group | |
671 | |
672 @group | |
7212 | 673 9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0} |
674 ; @r{(this exits the while loop).} | |
5945 | 675 ; @r{else pop top of stack} |
676 ; @r{and continue} | |
677 @end group | |
678 | |
679 @group | |
680 12 constant nil ; @r{Push @code{nil} onto stack} | |
681 ; @r{(this is the body of the loop).} | |
682 @end group | |
683 | |
684 @group | |
685 13 discard ; @r{Discard result of the body} | |
686 ; @r{of the loop (a while loop} | |
687 ; @r{is always evaluated for} | |
688 ; @r{its side effects).} | |
689 @end group | |
690 | |
691 @group | |
692 14 goto 3 ; @r{Jump back to beginning} | |
693 ; @r{of while loop.} | |
694 @end group | |
695 | |
696 @group | |
697 17 discard ; @r{Discard result of while loop} | |
698 ; @r{by popping top of stack.} | |
7212 | 699 ; @r{This result is the value @code{nil} that} |
700 ; @r{was not popped by the goto at 9.} | |
5945 | 701 @end group |
702 | |
703 @group | |
704 18 varref t1 ; @r{Push value of @code{t1} onto stack.} | |
705 @end group | |
706 | |
707 @group | |
708 19 constant current-time-string ; @r{Push} | |
709 ; @r{@code{current-time-string}} | |
710 ; @r{onto top of stack.} | |
711 @end group | |
712 | |
713 @group | |
714 20 call 0 ; @r{Call @code{current-time-string} again.} | |
715 @end group | |
716 | |
717 @group | |
718 21 list2 ; @r{Pop top two elements off stack,} | |
719 ; @r{create a list of them,} | |
720 ; @r{and push list onto stack.} | |
721 @end group | |
722 | |
723 @group | |
724 22 unbind 1 ; @r{Unbind @code{t1} in local environment.} | |
725 | |
726 23 return ; @r{Return value of the top of stack.} | |
727 | |
728 @result{} nil | |
729 @end group | |
730 @end example | |
731 | |
732 |