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