annotate lispref/compile.texi @ 83400:03934708f1e9

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