Mercurial > emacs
annotate lispref/compile.texi @ 72143:c72f78a4a1c1
*** empty log message ***
author | Nick Roberts <nickrob@snap.net.nz> |
---|---|
date | Thu, 27 Jul 2006 12:17:38 +0000 |
parents | 1d43c64436be |
children | 6d19c76d81c5 e1bbe296602a |
rev | line source |
---|---|
5945 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
64889
e836425ee789
Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
63583
diff
changeset
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2002, 2003, 2004, |
68648
067115a6e738
Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
66505
diff
changeset
|
4 @c 2005, 2006 Free Software Foundation, Inc. |
5945 | 5 @c See the file elisp.texi for copying conditions. |
6 @setfilename ../info/compile | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
7 @node Byte Compilation, Advising Functions, Loading, Top |
5945 | 8 @chapter Byte Compilation |
9 @cindex byte-code | |
10 @cindex compilation | |
11 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
12 Emacs Lisp has a @dfn{compiler} that translates functions written |
5945 | 13 in Lisp into a special representation called @dfn{byte-code} that can be |
14 executed more efficiently. The compiler replaces Lisp function | |
15 definitions with byte-code. When a byte-code function is called, its | |
16 definition is evaluated by the @dfn{byte-code interpreter}. | |
17 | |
18 Because the byte-compiled code is evaluated by the byte-code | |
19 interpreter, instead of being executed directly by the machine's | |
20 hardware (as true compiled code is), byte-code is completely | |
21 transportable from machine to machine without recompilation. It is not, | |
22 however, as fast as true compiled code. | |
23 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
24 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
|
25 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
|
26 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
|
27 results compatible with running the same file without compilation. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
28 @xref{Loading Non-ASCII}. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
29 |
5945 | 30 In general, any version of Emacs can run byte-compiled code produced |
60036
fafa7c0e2b82
(Byte Compilation): Delete 19.29 info.
Richard M. Stallman <rms@gnu.org>
parents:
55733
diff
changeset
|
31 by recent earlier versions of Emacs, but the reverse is not true. |
5945 | 32 |
51919
d51ac8d52e63
(Byte Compilation): Explain no-byte-compile
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
33 @vindex no-byte-compile |
d51ac8d52e63
(Byte Compilation): Explain no-byte-compile
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
34 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
|
35 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
|
36 |
d51ac8d52e63
(Byte Compilation): Explain no-byte-compile
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
37 @example |
d51ac8d52e63
(Byte Compilation): Explain no-byte-compile
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
38 ;; -*-no-byte-compile: t; -*- |
d51ac8d52e63
(Byte Compilation): Explain no-byte-compile
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
39 @end example |
d51ac8d52e63
(Byte Compilation): Explain no-byte-compile
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
40 |
5945 | 41 @xref{Compilation Errors}, for how to investigate errors occurring in |
42 byte compilation. | |
43 | |
44 @menu | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
45 * Speed of Byte-Code:: An example of speedup from byte compilation. |
5945 | 46 * Compilation Functions:: Byte compilation functions. |
12067 | 47 * Docs and Compilation:: Dynamic loading of documentation strings. |
48 * Dynamic Loading:: Dynamic loading of individual functions. | |
5945 | 49 * 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
|
50 * Compiler Errors:: Handling compiler error messages. |
5945 | 51 * Byte-Code Objects:: The data type used for byte-compiled functions. |
52 * Disassembly:: Disassembling byte-code; how to read byte-code. | |
53 @end menu | |
54 | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
55 @node Speed of Byte-Code |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
56 @section Performance of Byte-Compiled Code |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
57 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
58 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
|
59 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
|
60 Here is an example: |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
61 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
62 @example |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
63 @group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
64 (defun silly-loop (n) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
65 "Return time before and after N iterations of a loop." |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
66 (let ((t1 (current-time-string))) |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
38160
diff
changeset
|
67 (while (> (setq n (1- n)) |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
68 0)) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
69 (list t1 (current-time-string)))) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
70 @result{} silly-loop |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
71 @end group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
72 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
73 @group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
74 (silly-loop 100000) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
75 @result{} ("Fri Mar 18 17:25:57 1994" |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
76 "Fri Mar 18 17:26:28 1994") ; @r{31 seconds} |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
77 @end group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
78 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
79 @group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
80 (byte-compile 'silly-loop) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
81 @result{} @r{[Compiled code not shown]} |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
82 @end group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
83 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
84 @group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
85 (silly-loop 100000) |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
86 @result{} ("Fri Mar 18 17:26:52 1994" |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
87 "Fri Mar 18 17:26:58 1994") ; @r{6 seconds} |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
88 @end group |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
89 @end example |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
90 |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
91 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
|
92 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
|
93 representative, but actual results will vary greatly. |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
94 |
5945 | 95 @node Compilation Functions |
96 @comment node-name, next, previous, up | |
97 @section The Compilation Functions | |
98 @cindex compilation functions | |
99 | |
100 You can byte-compile an individual function or macro definition with | |
101 the @code{byte-compile} function. You can compile a whole file with | |
102 @code{byte-compile-file}, or several files with | |
103 @code{byte-recompile-directory} or @code{batch-byte-compile}. | |
104 | |
16736
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
12128
diff
changeset
|
105 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
|
106 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
|
107 program that suggest a problem but are not necessarily erroneous. |
5945 | 108 |
109 @cindex macro compilation | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
110 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
|
111 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
|
112 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
|
113 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
|
114 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
|
115 definitions are one likely cause (@pxref{Problems with Macros}). |
60036
fafa7c0e2b82
(Byte Compilation): Delete 19.29 info.
Richard M. Stallman <rms@gnu.org>
parents:
55733
diff
changeset
|
116 Inline (@code{defsubst}) functions are less troublesome; if you |
fafa7c0e2b82
(Byte Compilation): Delete 19.29 info.
Richard M. Stallman <rms@gnu.org>
parents:
55733
diff
changeset
|
117 compile a call to such a function before its definition is known, the |
fafa7c0e2b82
(Byte Compilation): Delete 19.29 info.
Richard M. Stallman <rms@gnu.org>
parents:
55733
diff
changeset
|
118 call will still work right, it will just run slower. |
5945 | 119 |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
120 Normally, compiling a file does not evaluate the file's contents or |
12098 | 121 load the file. But it does execute any @code{require} calls at top |
122 level in the file. One way to ensure that necessary macro definitions | |
123 are available during compilation is to require the file that defines | |
124 them (@pxref{Named Features}). To avoid loading the macro definition files | |
125 when someone @emph{runs} the compiled program, write | |
126 @code{eval-when-compile} around the @code{require} calls (@pxref{Eval | |
127 During Compile}). | |
5945 | 128 |
129 @defun byte-compile symbol | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
130 This function byte-compiles the function definition of @var{symbol}, |
5945 | 131 replacing the previous definition with the compiled one. The function |
132 definition of @var{symbol} must be the actual code for the function; | |
133 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
|
134 @code{byte-compile} returns the new, compiled definition of |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
135 @var{symbol}. |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
136 |
12067 | 137 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
|
138 @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
|
139 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
|
140 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
|
141 way to ``compile the same definition again.'' |
5945 | 142 |
143 @example | |
144 @group | |
145 (defun factorial (integer) | |
146 "Compute factorial of INTEGER." | |
147 (if (= 1 integer) 1 | |
148 (* integer (factorial (1- integer))))) | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
149 @result{} factorial |
5945 | 150 @end group |
151 | |
152 @group | |
153 (byte-compile 'factorial) | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
154 @result{} |
5945 | 155 #[(integer) |
156 "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207" | |
157 [integer 1 * factorial] | |
158 4 "Compute factorial of INTEGER."] | |
159 @end group | |
160 @end example | |
161 | |
162 @noindent | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
163 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
|
164 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
|
165 operand of an instruction. The vector contains all the constants, |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
166 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
|
167 certain primitives that are coded as special instructions. |
55733 | 168 |
169 If the argument to @code{byte-compile} is a @code{lambda} expression, | |
170 it returns the corresponding compiled code, but does not store | |
171 it anywhere. | |
5945 | 172 @end defun |
173 | |
53585
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
174 @deffn Command compile-defun &optional arg |
5945 | 175 This command reads the defun containing point, compiles it, and |
176 evaluates the result. If you use this on a defun that is actually a | |
177 function definition, the effect is to install a compiled version of that | |
178 function. | |
53585
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
179 |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
180 @code{compile-defun} normally displays the result of evaluation in the |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
181 echo area, but if @var{arg} is non-@code{nil}, it inserts the result |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
182 in the current buffer after the form it compiled. |
5945 | 183 @end deffn |
184 | |
53585
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
185 @deffn Command byte-compile-file filename &optional load |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
186 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
|
187 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
|
188 @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
|
189 @samp{.el}, it adds @samp{.elc} to the end of @var{filename}. |
5945 | 190 |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
191 Compilation works by reading the input file one form at a time. If it |
5945 | 192 is a definition of a function or macro, the compiled function or macro |
193 definition is written out. Other forms are batched together, then each | |
194 batch is compiled, and written so that its compiled code will be | |
195 executed when the file is read. All comments are discarded when the | |
196 input file is read. | |
197 | |
53585
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
198 This command returns @code{t} if there were no errors and @code{nil} |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
199 otherwise. When called interactively, it prompts for the file name. |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
200 |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
201 If @var{load} is non-@code{nil}, this command loads the compiled file |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
202 after compiling it. Interactively, @var{load} is the prefix argument. |
5945 | 203 |
204 @example | |
205 @group | |
206 % ls -l push* | |
207 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el | |
208 @end group | |
209 | |
210 @group | |
211 (byte-compile-file "~/emacs/push.el") | |
212 @result{} t | |
213 @end group | |
214 | |
215 @group | |
216 % ls -l push* | |
217 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el | |
218 -rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc | |
219 @end group | |
220 @end example | |
221 @end deffn | |
222 | |
53585
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
223 @deffn Command byte-recompile-directory directory &optional flag force |
5945 | 224 @cindex library compilation |
53585
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
225 This command recompiles every @samp{.el} file in @var{directory} (or |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
226 its subdirectories) that needs recompilation. A file needs |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
227 recompilation if a @samp{.elc} file exists but is older than the |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
228 @samp{.el} file. |
5945 | 229 |
53585
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
230 When a @samp{.el} file has no corresponding @samp{.elc} file, |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
231 @var{flag} says what to do. If it is @code{nil}, this command ignores |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
232 these files. If @var{flag} is 0, it compiles them. If it is neither |
55733 | 233 @code{nil} nor 0, it asks the user whether to compile each such file, |
234 and asks about each subdirectory as well. | |
5945 | 235 |
53585
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
236 Interactively, @code{byte-recompile-directory} prompts for |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
237 @var{directory} and @var{flag} is the prefix argument. |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
238 |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
239 If @var{force} is non-@code{nil}, this command recompiles every |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
240 @samp{.el} file that has a @samp{.elc} file. |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
241 |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
242 The returned value is unpredictable. |
5945 | 243 @end deffn |
244 | |
53585
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
245 @defun batch-byte-compile &optional noforce |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
246 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
|
247 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
|
248 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
|
249 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
|
250 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
|
251 status code. |
5945 | 252 |
53585
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
253 If @var{noforce} is non-@code{nil}, this function does not recompile |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
254 files that have an up-to-date @samp{.elc} file. |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
255 |
5945 | 256 @example |
257 % emacs -batch -f batch-byte-compile *.el | |
258 @end example | |
259 @end defun | |
260 | |
261 @defun byte-code code-string data-vector max-stack | |
262 @cindex byte-code interpreter | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
263 This function actually interprets byte-code. A byte-compiled function |
5945 | 264 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
|
265 this function yourself---only the byte compiler knows how to generate |
5945 | 266 valid calls to this function. |
267 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
268 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
|
269 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
|
270 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
|
271 explicit call to @code{byte-code}. |
5945 | 272 @end defun |
273 | |
12067 | 274 @node Docs and Compilation |
275 @section Documentation Strings and Compilation | |
276 @cindex dynamic loading of documentation | |
277 | |
278 Functions and variables loaded from a byte-compiled file access their | |
279 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
|
280 saves space within Emacs, and makes loading faster because the |
12067 | 281 documentation strings themselves need not be processed while loading the |
282 file. Actual access to the documentation strings becomes slower as a | |
283 result, but this normally is not enough to bother users. | |
284 | |
285 Dynamic access to documentation strings does have drawbacks: | |
286 | |
287 @itemize @bullet | |
288 @item | |
289 If you delete or move the compiled file after loading it, Emacs can no | |
290 longer access the documentation strings for the functions and variables | |
291 in the file. | |
292 | |
293 @item | |
294 If you alter the compiled file (such as by compiling a new version), | |
55733 | 295 then further access to documentation strings in this file will |
296 probably give nonsense results. | |
12067 | 297 @end itemize |
298 | |
299 If your site installs Emacs following the usual procedures, these | |
300 problems will never normally occur. Installing a new version uses a new | |
301 directory with a different name; as long as the old version remains | |
302 installed, its files will remain unmodified in the places where they are | |
303 expected to be. | |
304 | |
12124 | 305 However, if you have built Emacs yourself and use it from the |
12067 | 306 directory where you built it, you will experience this problem |
307 occasionally if you edit and recompile Lisp files. When it happens, you | |
308 can cure the problem by reloading the file after recompiling it. | |
309 | |
60036
fafa7c0e2b82
(Byte Compilation): Delete 19.29 info.
Richard M. Stallman <rms@gnu.org>
parents:
55733
diff
changeset
|
310 You can turn off this feature at compile time by setting |
fafa7c0e2b82
(Byte Compilation): Delete 19.29 info.
Richard M. Stallman <rms@gnu.org>
parents:
55733
diff
changeset
|
311 @code{byte-compile-dynamic-docstrings} to @code{nil}; this is useful |
fafa7c0e2b82
(Byte Compilation): Delete 19.29 info.
Richard M. Stallman <rms@gnu.org>
parents:
55733
diff
changeset
|
312 mainly if you expect to change the file, and you want Emacs processes |
fafa7c0e2b82
(Byte Compilation): Delete 19.29 info.
Richard M. Stallman <rms@gnu.org>
parents:
55733
diff
changeset
|
313 that have already loaded it to keep working when the file changes. |
fafa7c0e2b82
(Byte Compilation): Delete 19.29 info.
Richard M. Stallman <rms@gnu.org>
parents:
55733
diff
changeset
|
314 You can do this globally, or for one source file by specifying a |
fafa7c0e2b82
(Byte Compilation): Delete 19.29 info.
Richard M. Stallman <rms@gnu.org>
parents:
55733
diff
changeset
|
315 file-local binding for the variable. One way to do that is by adding |
fafa7c0e2b82
(Byte Compilation): Delete 19.29 info.
Richard M. Stallman <rms@gnu.org>
parents:
55733
diff
changeset
|
316 this string to the file's first line: |
12067 | 317 |
318 @example | |
319 -*-byte-compile-dynamic-docstrings: nil;-*- | |
320 @end example | |
321 | |
322 @defvar byte-compile-dynamic-docstrings | |
323 If this is non-@code{nil}, the byte compiler generates compiled files | |
324 that are set up for dynamic loading of documentation strings. | |
325 @end defvar | |
326 | |
327 @cindex @samp{#@@@var{count}} | |
328 @cindex @samp{#$} | |
329 The dynamic documentation string feature writes compiled files that | |
330 use a special Lisp reader construct, @samp{#@@@var{count}}. This | |
331 construct skips the next @var{count} characters. It also uses the | |
332 @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
|
333 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
|
334 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
|
335 file. |
12067 | 336 |
337 @node Dynamic Loading | |
338 @section Dynamic Loading of Individual Functions | |
339 | |
340 @cindex dynamic loading of functions | |
341 @cindex lazy loading | |
342 When you compile a file, you can optionally enable the @dfn{dynamic | |
343 function loading} feature (also known as @dfn{lazy loading}). With | |
344 dynamic function loading, loading the file doesn't fully read the | |
345 function definitions in the file. Instead, each function definition | |
346 contains a place-holder which refers to the file. The first time each | |
347 function is called, it reads the full definition from the file, to | |
348 replace the place-holder. | |
349 | |
350 The advantage of dynamic function loading is that loading the file | |
351 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
|
352 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
|
353 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
|
354 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
|
355 invoke the mode, but use only a few of the commands it provides. |
12067 | 356 |
357 The dynamic loading feature has certain disadvantages: | |
358 | |
359 @itemize @bullet | |
360 @item | |
361 If you delete or move the compiled file after loading it, Emacs can no | |
362 longer load the remaining function definitions not already loaded. | |
363 | |
364 @item | |
365 If you alter the compiled file (such as by compiling a new version), | |
55733 | 366 then trying to load any function not already loaded will usually yield |
367 nonsense results. | |
12067 | 368 @end itemize |
369 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
370 These problems will never happen in normal circumstances with |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
371 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
|
372 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
|
373 is to reload the new compiled file immediately after each recompilation. |
12067 | 374 |
375 The byte compiler uses the dynamic function loading feature if the | |
376 variable @code{byte-compile-dynamic} is non-@code{nil} at compilation | |
377 time. Do not set this variable globally, since dynamic loading is | |
378 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
|
379 specific source files with file-local variable bindings. For example, |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
380 you could do it by writing this text in the source file's first line: |
12067 | 381 |
382 @example | |
383 -*-byte-compile-dynamic: t;-*- | |
384 @end example | |
385 | |
386 @defvar byte-compile-dynamic | |
387 If this is non-@code{nil}, the byte compiler generates compiled files | |
388 that are set up for dynamic function loading. | |
389 @end defvar | |
390 | |
391 @defun fetch-bytecode function | |
55733 | 392 If @var{function} is a byte-code function object, this immediately |
393 finishes loading the byte code of @var{function} from its | |
394 byte-compiled file, if it is not fully loaded already. Otherwise, | |
395 it does nothing. It always returns @var{function}. | |
12067 | 396 @end defun |
397 | |
5945 | 398 @node Eval During Compile |
399 @section Evaluation During Compilation | |
400 | |
12067 | 401 These features permit you to write code to be evaluated during |
5945 | 402 compilation of a program. |
403 | |
66141
2af75f8155de
(Eval During Compile, Compiler Errors):
Juri Linkov <juri@jurta.org>
parents:
64889
diff
changeset
|
404 @defspec eval-and-compile body@dots{} |
5945 | 405 This form marks @var{body} to be evaluated both when you compile the |
406 containing code and when you run it (whether compiled or not). | |
407 | |
408 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
|
409 and referring to that file with @code{require}. That method is |
66505
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
410 preferable when @var{body} is large. Effectively @code{require} is |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
411 automatically @code{eval-and-compile}, the package is loaded both when |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
412 compiling and executing. |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
413 |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
414 @code{autoload} is also effectively @code{eval-and-compile} too. It's |
70506
f7aff7b6d4af
* commands.texi (Event Input Misc):
Romain Francoise <romain@orebokech.com>
parents:
68648
diff
changeset
|
415 recognized when compiling, so uses of such a function don't produce |
66505
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
416 ``not known to be defined'' warnings. |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
417 |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
418 Most uses of @code{eval-and-compile} are fairly sophisticated. |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
419 |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
420 If a macro has a helper function to build its result, and that macro |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
421 is used both locally and outside the package, then |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
422 @code{eval-and-compile} should be used to get the helper both when |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
423 compiling and then later when running. |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
424 |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
425 If functions are defined programmatically (with @code{fset} say), then |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
426 @code{eval-and-compile} can be used to have that done at compile-time |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
427 as well as run-time, so calls to those functions are checked (and |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
428 warnings about ``not known to be defined'' suppressed). |
5945 | 429 @end defspec |
430 | |
66141
2af75f8155de
(Eval During Compile, Compiler Errors):
Juri Linkov <juri@jurta.org>
parents:
64889
diff
changeset
|
431 @defspec eval-when-compile body@dots{} |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
432 This form marks @var{body} to be evaluated at compile time but not when |
7212 | 433 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
|
434 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
|
435 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
|
436 evaluated normally. |
5945 | 437 |
71263
1d43c64436be
(Eval During Compile): Fix a typo. Add index entries for possible uses of
Eli Zaretskii <eliz@gnu.org>
parents:
70506
diff
changeset
|
438 @cindex compile-time constant |
66505
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
439 If you have a constant that needs some calculation to produce, |
71263
1d43c64436be
(Eval During Compile): Fix a typo. Add index entries for possible uses of
Eli Zaretskii <eliz@gnu.org>
parents:
70506
diff
changeset
|
440 @code{eval-when-compile} can do that at compile-time. For example, |
66505
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
441 |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
442 @lisp |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
443 (defvar my-regexp |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
444 (eval-when-compile (regexp-opt '("aaa" "aba" "abb")))) |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
445 @end lisp |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
446 |
71263
1d43c64436be
(Eval During Compile): Fix a typo. Add index entries for possible uses of
Eli Zaretskii <eliz@gnu.org>
parents:
70506
diff
changeset
|
447 @cindex macros, at compile time |
66505
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
448 If you're using another package, but only need macros from it (the |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
449 byte compiler will expand those), then @code{eval-when-compile} can be |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
450 used to load it for compiling, but not executing. For example, |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
451 |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
452 @lisp |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
453 (eval-when-compile |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
454 (require 'my-macro-package)) ;; only macros needed from this |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
455 @end lisp |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
456 |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
457 The same sort of thing goes for macros or @code{defalias}es defined |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
458 locally and only for use within the file. They can be defined while |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
459 compiling, but then not needed when executing. This is good for code |
70506
f7aff7b6d4af
* commands.texi (Event Input Misc):
Romain Francoise <romain@orebokech.com>
parents:
68648
diff
changeset
|
460 that's only a fallback for compatibility with other versions of Emacs. |
66505
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
461 For example. |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
462 |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
463 @lisp |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
464 (eval-when-compile |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
465 (unless (fboundp 'some-new-thing) |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
466 (defmacro 'some-new-thing () |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
467 (compatibility code)))) |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
468 @end lisp |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
469 |
f60cd5bf2c8e
(Eval During Compile): Explain recommended uses
Richard M. Stallman <rms@gnu.org>
parents:
66141
diff
changeset
|
470 @strong{Common Lisp Note:} At top level, @code{eval-when-compile} is analogous to the Common |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
471 Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
472 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
|
473 to what @code{eval-when-compile} does. |
5945 | 474 @end defspec |
475 | |
51919
d51ac8d52e63
(Byte Compilation): Explain no-byte-compile
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
476 @node Compiler Errors |
d51ac8d52e63
(Byte Compilation): Explain no-byte-compile
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
477 @section Compiler Errors |
d51ac8d52e63
(Byte Compilation): Explain no-byte-compile
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
478 @cindex compiler errors |
d51ac8d52e63
(Byte Compilation): Explain no-byte-compile
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
479 |
63583
99e9892a51d9
Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents:
60036
diff
changeset
|
480 Byte compilation outputs all errors and warnings into the buffer |
51919
d51ac8d52e63
(Byte Compilation): Explain no-byte-compile
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
481 @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
|
482 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
|
483 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
|
484 these messages. |
d51ac8d52e63
(Byte Compilation): Explain no-byte-compile
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
485 |
d51ac8d52e63
(Byte Compilation): Explain no-byte-compile
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
486 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
|
487 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
|
488 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
|
489 you must search for the function names. |
53585
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
490 |
52139
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
491 You can suppress the compiler warning for calling an undefined |
55733 | 492 function @var{func} by conditionalizing the function call on an |
52139
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
493 @code{fboundp} test, like this: |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
494 |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
495 @example |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
496 (if (fboundp '@var{func}) ...(@var{func} ...)...) |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
497 @end example |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
498 |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
499 @noindent |
54021
5cd1edd36679
(Compiler Errors): if-boundp feature applies to cond.
Richard M. Stallman <rms@gnu.org>
parents:
53585
diff
changeset
|
500 The call to @var{func} must be in the @var{then-form} of the |
5cd1edd36679
(Compiler Errors): if-boundp feature applies to cond.
Richard M. Stallman <rms@gnu.org>
parents:
53585
diff
changeset
|
501 @code{if}, and @var{func} must appear quoted in the call to |
5cd1edd36679
(Compiler Errors): if-boundp feature applies to cond.
Richard M. Stallman <rms@gnu.org>
parents:
53585
diff
changeset
|
502 @code{fboundp}. (This feature operates for @code{cond} as well.) |
5cd1edd36679
(Compiler Errors): if-boundp feature applies to cond.
Richard M. Stallman <rms@gnu.org>
parents:
53585
diff
changeset
|
503 |
5cd1edd36679
(Compiler Errors): if-boundp feature applies to cond.
Richard M. Stallman <rms@gnu.org>
parents:
53585
diff
changeset
|
504 Likewise, you can suppress a compiler warning for an unbound variable |
52139
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
505 @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
|
506 like this: |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
507 |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
508 @example |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
509 (if (boundp '@var{variable}) ...@var{variable}...) |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
510 @end example |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
511 |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
512 @noindent |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
513 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
|
514 @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
|
515 @code{boundp}. |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
516 |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
517 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
|
518 @code{with-no-warnings}: |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
519 |
55733 | 520 @c This is implemented with a defun, but conceptually it is |
521 @c a special form. | |
522 | |
66141
2af75f8155de
(Eval During Compile, Compiler Errors):
Juri Linkov <juri@jurta.org>
parents:
64889
diff
changeset
|
523 @defspec with-no-warnings body@dots{} |
52139
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
524 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
|
525 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
|
526 inside @var{body}. |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
527 |
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
528 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
|
529 possible piece of code. |
55733 | 530 @end defspec |
52139
6a00e88ede75
(Compiler Errors): Explain with-no-warnings
Richard M. Stallman <rms@gnu.org>
parents:
51919
diff
changeset
|
531 |
5945 | 532 @node Byte-Code Objects |
12098 | 533 @section Byte-Code Function Objects |
5945 | 534 @cindex compiled function |
535 @cindex byte-code function | |
536 | |
537 Byte-compiled functions have a special data type: they are | |
538 @dfn{byte-code function objects}. | |
539 | |
540 Internally, a byte-code function object is much like a vector; | |
541 however, the evaluator handles this data type specially when it appears | |
542 as a function to be called. The printed representation for a byte-code | |
543 function object is like that for a vector, with an additional @samp{#} | |
544 before the opening @samp{[}. | |
545 | |
546 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
|
547 no maximum number, but only the first six elements have any normal use. |
5945 | 548 They are: |
549 | |
550 @table @var | |
551 @item arglist | |
552 The list of argument symbols. | |
553 | |
554 @item byte-code | |
555 The string containing the byte-code instructions. | |
556 | |
557 @item constants | |
7212 | 558 The vector of Lisp objects referenced by the byte code. These include |
559 symbols used as function names and variable names. | |
5945 | 560 |
561 @item stacksize | |
562 The maximum stack size this function needs. | |
563 | |
564 @item docstring | |
12098 | 565 The documentation string (if any); otherwise, @code{nil}. The value may |
566 be a number or a list, in case the documentation string is stored in a | |
567 file. Use the function @code{documentation} to get the real | |
568 documentation string (@pxref{Accessing Documentation}). | |
5945 | 569 |
570 @item interactive | |
571 The interactive spec (if any). This can be a string or a Lisp | |
572 expression. It is @code{nil} for a function that isn't interactive. | |
573 @end table | |
574 | |
575 Here's an example of a byte-code function object, in printed | |
576 representation. It is the definition of the command | |
577 @code{backward-sexp}. | |
578 | |
579 @example | |
580 #[(&optional arg) | |
581 "^H\204^F^@@\301^P\302^H[!\207" | |
582 [arg 1 forward-sexp] | |
583 2 | |
584 254435 | |
585 "p"] | |
586 @end example | |
587 | |
588 The primitive way to create a byte-code object is with | |
589 @code{make-byte-code}: | |
590 | |
591 @defun make-byte-code &rest elements | |
592 This function constructs and returns a byte-code function object | |
593 with @var{elements} as its elements. | |
594 @end defun | |
595 | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
596 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
|
597 function yourself, because if they are inconsistent, Emacs may crash |
7212 | 598 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
|
599 create these objects; it makes the elements consistent (we hope). |
5945 | 600 |
601 You can access the elements of a byte-code object using @code{aref}; | |
602 you can also use @code{vconcat} to create a vector with the same | |
603 elements. | |
604 | |
605 @node Disassembly | |
606 @section Disassembled Byte-Code | |
607 @cindex disassembled byte-code | |
608 | |
609 People do not write byte-code; that job is left to the byte compiler. | |
610 But we provide a disassembler to satisfy a cat-like curiosity. The | |
611 disassembler converts the byte-compiled code into humanly readable | |
612 form. | |
613 | |
614 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
|
615 It pushes values onto a stack of its own, then pops them off to use them |
7212 | 616 in calculations whose results are themselves pushed back on the stack. |
617 When a byte-code function returns, it pops a value off the stack and | |
618 returns it as the value of the function. | |
5945 | 619 |
7212 | 620 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
|
621 ordinary Lisp variables, by transferring values between variables and |
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
622 the stack. |
5945 | 623 |
53585
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
624 @deffn Command disassemble object &optional buffer-or-name |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
625 This command displays the disassembled code for @var{object}. In |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
626 interactive use, or if @var{buffer-or-name} is @code{nil} or omitted, |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
627 the output goes in a buffer named @samp{*Disassemble*}. If |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
628 @var{buffer-or-name} is non-@code{nil}, it must be a buffer or the |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
629 name of an existing buffer. Then the output goes there, at point, and |
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
630 point is left before the output. |
5945 | 631 |
53585
aaa866b1592f
(Compilation Functions): Expand descriptions of `compile-defun',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
632 The argument @var{object} can be a function name, a lambda expression |
55733 | 633 or a byte-code object. If it is a lambda expression, @code{disassemble} |
634 compiles it and disassembles the resulting compiled code. | |
5945 | 635 @end deffn |
636 | |
637 Here are two examples of using the @code{disassemble} function. We | |
638 have added explanatory comments to help you relate the byte-code to the | |
639 Lisp source; these do not appear in the output of @code{disassemble}. | |
640 These examples show unoptimized byte-code. Nowadays byte-code is | |
641 usually optimized, but we did not want to rewrite these examples, since | |
642 they still serve their purpose. | |
643 | |
644 @example | |
645 @group | |
646 (defun factorial (integer) | |
647 "Compute factorial of an integer." | |
648 (if (= 1 integer) 1 | |
649 (* integer (factorial (1- integer))))) | |
650 @result{} factorial | |
651 @end group | |
652 | |
653 @group | |
654 (factorial 4) | |
655 @result{} 24 | |
656 @end group | |
657 | |
658 @group | |
659 (disassemble 'factorial) | |
660 @print{} byte-code for factorial: | |
661 doc: Compute factorial of an integer. | |
662 args: (integer) | |
663 @end group | |
664 | |
665 @group | |
666 0 constant 1 ; @r{Push 1 onto stack.} | |
667 | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
38160
diff
changeset
|
668 1 varref integer ; @r{Get value of @code{integer}} |
5945 | 669 ; @r{from the environment} |
670 ; @r{and push the value} | |
671 ; @r{onto the stack.} | |
672 @end group | |
673 | |
674 @group | |
675 2 eqlsign ; @r{Pop top two values off stack,} | |
676 ; @r{compare them,} | |
677 ; @r{and push result onto stack.} | |
678 @end group | |
679 | |
680 @group | |
681 3 goto-if-nil 10 ; @r{Pop and test top of stack;} | |
682 ; @r{if @code{nil}, go to 10,} | |
683 ; @r{else continue.} | |
684 @end group | |
685 | |
686 @group | |
687 6 constant 1 ; @r{Push 1 onto top of stack.} | |
688 | |
689 7 goto 17 ; @r{Go to 17 (in this case, 1 will be} | |
690 ; @r{returned by the function).} | |
691 @end group | |
692 | |
693 @group | |
694 10 constant * ; @r{Push symbol @code{*} onto stack.} | |
695 | |
696 11 varref integer ; @r{Push value of @code{integer} onto stack.} | |
697 @end group | |
698 | |
699 @group | |
700 12 constant factorial ; @r{Push @code{factorial} onto stack.} | |
701 | |
702 13 varref integer ; @r{Push value of @code{integer} onto stack.} | |
703 | |
704 14 sub1 ; @r{Pop @code{integer}, decrement value,} | |
705 ; @r{push new value onto stack.} | |
706 @end group | |
707 | |
708 @group | |
709 ; @r{Stack now contains:} | |
710 ; @minus{} @r{decremented value of @code{integer}} | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
38160
diff
changeset
|
711 ; @minus{} @r{@code{factorial}} |
5945 | 712 ; @minus{} @r{value of @code{integer}} |
713 ; @minus{} @r{@code{*}} | |
714 @end group | |
715 | |
716 @group | |
717 15 call 1 ; @r{Call function @code{factorial} using} | |
718 ; @r{the first (i.e., the top) element} | |
719 ; @r{of the stack as the argument;} | |
720 ; @r{push returned value onto stack.} | |
721 @end group | |
722 | |
723 @group | |
724 ; @r{Stack now contains:} | |
7212 | 725 ; @minus{} @r{result of recursive} |
5945 | 726 ; @r{call to @code{factorial}} |
727 ; @minus{} @r{value of @code{integer}} | |
728 ; @minus{} @r{@code{*}} | |
729 @end group | |
730 | |
731 @group | |
732 16 call 2 ; @r{Using the first two} | |
733 ; @r{(i.e., the top two)} | |
734 ; @r{elements of the stack} | |
735 ; @r{as arguments,} | |
736 ; @r{call the function @code{*},} | |
737 ; @r{pushing the result onto the stack.} | |
738 @end group | |
739 | |
740 @group | |
741 17 return ; @r{Return the top element} | |
742 ; @r{of the stack.} | |
743 @result{} nil | |
744 @end group | |
745 @end example | |
746 | |
747 The @code{silly-loop} function is somewhat more complex: | |
748 | |
749 @example | |
750 @group | |
751 (defun silly-loop (n) | |
752 "Return time before and after N iterations of a loop." | |
753 (let ((t1 (current-time-string))) | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
38160
diff
changeset
|
754 (while (> (setq n (1- n)) |
5945 | 755 0)) |
756 (list t1 (current-time-string)))) | |
757 @result{} silly-loop | |
758 @end group | |
759 | |
760 @group | |
761 (disassemble 'silly-loop) | |
762 @print{} byte-code for silly-loop: | |
763 doc: Return time before and after N iterations of a loop. | |
764 args: (n) | |
765 | |
766 0 constant current-time-string ; @r{Push} | |
767 ; @r{@code{current-time-string}} | |
768 ; @r{onto top of stack.} | |
769 @end group | |
770 | |
771 @group | |
772 1 call 0 ; @r{Call @code{current-time-string}} | |
773 ; @r{ with no argument,} | |
774 ; @r{ pushing result onto stack.} | |
775 @end group | |
776 | |
777 @group | |
778 2 varbind t1 ; @r{Pop stack and bind @code{t1}} | |
779 ; @r{to popped value.} | |
780 @end group | |
781 | |
782 @group | |
783 3 varref n ; @r{Get value of @code{n} from} | |
784 ; @r{the environment and push} | |
785 ; @r{the value onto the stack.} | |
786 @end group | |
787 | |
788 @group | |
789 4 sub1 ; @r{Subtract 1 from top of stack.} | |
790 @end group | |
791 | |
792 @group | |
793 5 dup ; @r{Duplicate the top of the stack;} | |
6452
8c7032348e93
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
5945
diff
changeset
|
794 ; @r{i.e., copy the top of} |
5945 | 795 ; @r{the stack and push the} |
796 ; @r{copy onto the stack.} | |
797 @end group | |
798 | |
799 @group | |
800 6 varset n ; @r{Pop the top of the stack,} | |
801 ; @r{and bind @code{n} to the value.} | |
802 | |
803 ; @r{In effect, the sequence @code{dup varset}} | |
804 ; @r{copies the top of the stack} | |
805 ; @r{into the value of @code{n}} | |
806 ; @r{without popping it.} | |
807 @end group | |
808 | |
809 @group | |
810 7 constant 0 ; @r{Push 0 onto stack.} | |
811 @end group | |
812 | |
813 @group | |
814 8 gtr ; @r{Pop top two values off stack,} | |
815 ; @r{test if @var{n} is greater than 0} | |
816 ; @r{and push result onto stack.} | |
817 @end group | |
818 | |
819 @group | |
7212 | 820 9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0} |
821 ; @r{(this exits the while loop).} | |
5945 | 822 ; @r{else pop top of stack} |
823 ; @r{and continue} | |
824 @end group | |
825 | |
826 @group | |
827 12 constant nil ; @r{Push @code{nil} onto stack} | |
828 ; @r{(this is the body of the loop).} | |
829 @end group | |
830 | |
831 @group | |
832 13 discard ; @r{Discard result of the body} | |
833 ; @r{of the loop (a while loop} | |
834 ; @r{is always evaluated for} | |
835 ; @r{its side effects).} | |
836 @end group | |
837 | |
838 @group | |
839 14 goto 3 ; @r{Jump back to beginning} | |
840 ; @r{of while loop.} | |
841 @end group | |
842 | |
843 @group | |
844 17 discard ; @r{Discard result of while loop} | |
845 ; @r{by popping top of stack.} | |
7212 | 846 ; @r{This result is the value @code{nil} that} |
847 ; @r{was not popped by the goto at 9.} | |
5945 | 848 @end group |
849 | |
850 @group | |
851 18 varref t1 ; @r{Push value of @code{t1} onto stack.} | |
852 @end group | |
853 | |
854 @group | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
38160
diff
changeset
|
855 19 constant current-time-string ; @r{Push} |
5945 | 856 ; @r{@code{current-time-string}} |
857 ; @r{onto top of stack.} | |
858 @end group | |
859 | |
860 @group | |
861 20 call 0 ; @r{Call @code{current-time-string} again.} | |
862 @end group | |
863 | |
864 @group | |
865 21 list2 ; @r{Pop top two elements off stack,} | |
866 ; @r{create a list of them,} | |
867 ; @r{and push list onto stack.} | |
868 @end group | |
869 | |
870 @group | |
871 22 unbind 1 ; @r{Unbind @code{t1} in local environment.} | |
872 | |
873 23 return ; @r{Return value of the top of stack.} | |
874 | |
875 @result{} nil | |
876 @end group | |
877 @end example | |
878 | |
879 | |
52401 | 880 @ignore |
881 arch-tag: f78e3050-2f0a-4dee-be27-d9979a0a2289 | |
882 @end ignore |