annotate lispref/compile.texi @ 14763:27bcf4090165 libc-960306 libc-960307 libc-960308 libc-960309 libc-960310 libc-960311 libc-960312 libc-960313 libc-960314

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