|
428
|
1
|
|
|
2 @node Running, Packages, Programs, Top
|
|
|
3 @chapter Compiling and Testing Programs
|
|
|
4
|
|
|
5 The previous chapter discusses the Emacs commands that are useful for
|
|
|
6 making changes in programs. This chapter deals with commands that assist
|
|
|
7 in the larger process of developing and maintaining programs.
|
|
|
8
|
|
|
9 @menu
|
|
|
10 * Compilation:: Compiling programs in languages other than Lisp
|
|
|
11 (C, Pascal, etc.)
|
|
|
12 * Modes: Lisp Modes. Various modes for editing Lisp programs, with
|
|
|
13 different facilities for running the Lisp programs.
|
|
|
14 * Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs.
|
|
|
15 * Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
|
|
|
16 * Debug: Lisp Debug. Debugging Lisp programs running in Emacs.
|
|
|
17 * Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
|
|
|
18 * External Lisp:: Communicating through Emacs with a separate Lisp.
|
|
|
19 @end menu
|
|
|
20
|
|
|
21 @node Compilation, Lisp Modes, Running, Running
|
|
|
22 @section Running ``make'', or Compilers Generally
|
|
|
23 @cindex inferior process
|
|
|
24 @cindex make
|
|
|
25 @cindex compilation errors
|
|
|
26 @cindex error log
|
|
|
27
|
|
|
28 Emacs can run compilers for non-interactive languages like C and
|
|
|
29 Fortran as inferior processes, feeding the error log into an Emacs buffer.
|
|
|
30 It can also parse the error messages and visit the files in which errors
|
|
|
31 are found, moving point to the line where the error occurred.
|
|
|
32
|
|
|
33 @table @kbd
|
|
|
34 @item M-x compile
|
|
|
35 Run a compiler asynchronously under Emacs, with error messages to
|
|
|
36 @samp{*compilation*} buffer.
|
|
|
37 @item M-x grep
|
|
|
38 Run @code{grep} asynchronously under Emacs, with matching lines
|
|
|
39 listed in the buffer named @samp{*compilation*}.
|
|
|
40 @item M-x kill-compilation
|
|
|
41 Kill the process made by the @code{M-x compile} command.
|
|
|
42 @item M-x kill-grep
|
|
|
43 Kill the running compilation or @code{grep} subprocess.
|
|
|
44 @item C-x `
|
|
|
45 Visit the next compiler error message or @code{grep} match.
|
|
|
46 @end table
|
|
|
47
|
|
|
48 @findex compile
|
|
|
49 To run @code{make} or another compiler, type @kbd{M-x compile}. This
|
|
|
50 command reads a shell command line using the minibuffer, then executes
|
|
|
51 the specified command line in an inferior shell with output going to the
|
|
|
52 buffer named @samp{*compilation*}. By default, the current buffer's
|
|
|
53 default directory is used as the working directory for the execution of
|
|
|
54 the command; therefore, the makefile comes from this directory.
|
|
|
55
|
|
|
56 @vindex compile-command
|
|
|
57 When the shell command line is read, the minibuffer appears containing a
|
|
|
58 default command line (the command you used the last time you typed
|
|
|
59 @kbd{M-x compile}). If you type just @key{RET}, the same command line is used
|
|
|
60 again. The first @kbd{M-x compile} provides @code{make -k} as the default.
|
|
|
61 The default is taken from the variable @code{compile-command}; if the
|
|
|
62 appropriate compilation command for a file is something other than
|
|
|
63 @code{make -k}, it can be useful to have the file specify a local value for
|
|
|
64 @code{compile-command} (@pxref{File Variables}).
|
|
|
65
|
|
|
66 @cindex compiling files
|
|
|
67 When you start a compilation, the buffer @samp{*compilation*} is
|
|
|
68 displayed in another window but not selected. Its mode line displays
|
|
|
69 the word @samp{run} or @samp{exit} in the parentheses to tell you whether
|
|
|
70 compilation is finished. You do not have to keep this buffer visible;
|
|
|
71 compilation continues in any case.
|
|
|
72
|
|
|
73 @findex kill-compilation
|
|
|
74 To kill the compilation process, type @kbd{M-x-kill-compilation}. The mode
|
|
|
75 line of the @samp{*compilation*} buffer changes to say @samp{signal}
|
|
|
76 instead of @samp{run}. Starting a new compilation also kills any
|
|
|
77 running compilation, as only one can occur at any time. Starting a new
|
|
|
78 compilation prompts for confirmation before actually killing a
|
|
|
79 compilation that is running.@refill
|
|
|
80
|
|
|
81 @kindex C-x `
|
|
|
82 @findex next-error
|
|
|
83 To parse the compiler error messages, type @kbd{C-x `}
|
|
|
84 (@code{next-error}). The character following @kbd{C-x} is the grave
|
|
|
85 accent, not the single quote. The command displays the buffer
|
|
|
86 @samp{*compilation*} in one window and the buffer in which the next
|
|
|
87 error occurred in another window. Point in that buffer is moved to the
|
|
|
88 line where the error was found. The corresponding error message is
|
|
|
89 scrolled to the top of the window in which @samp{*compilation*} is
|
|
|
90 displayed.
|
|
|
91
|
|
|
92 The first time you use @kbd{C-x `} after the start of a compilation, it
|
|
|
93 parses all the error messages, visits all the files that have error
|
|
|
94 messages, and creates markers pointing at the lines the error messages
|
|
|
95 refer to. It then moves to the first error message location. Subsequent
|
|
|
96 uses of @kbd{C-x `} advance down the data set up by the first use. When
|
|
|
97 the preparsed error messages are exhausted, the next @kbd{C-x `} checks for
|
|
|
98 any more error messages that have come in; this is useful if you start
|
|
|
99 editing compiler errors while compilation is still going on. If no
|
|
|
100 additional error messages have come in, @kbd{C-x `} reports an error.
|
|
|
101
|
|
|
102 @kbd{C-u C-x `} discards the preparsed error message data and parses the
|
|
|
103 @samp{*compilation*} buffer again, then displays the first error.
|
|
|
104 This way, you can process the same set of errors again.
|
|
|
105
|
|
|
106 Instead of running a compiler, you can run @code{grep} and see the
|
|
|
107 lines on which matches were found. To do this, type @kbd{M-x grep} with
|
|
|
108 an argument line that contains the same arguments you would give to
|
|
|
109 @code{grep}: a @code{grep}-style regexp (usually in single quotes to
|
|
|
110 quote the shell's special characters) followed by filenames, which may
|
|
|
111 use wildcard characters. The output from @code{grep} goes in the
|
|
|
112 @samp{*compilation*} buffer. You can use @kbd{C-x `} to find the lines that
|
|
|
113 match as if they were compilation errors.
|
|
|
114
|
|
|
115 Note: a shell is used to run the compile command, but the shell is not
|
|
|
116 run in interactive mode. In particular, this means that the shell starts
|
|
|
117 up with no prompt. If you find your usual shell prompt making an
|
|
|
118 unsightly appearance in the @samp{*compilation*} buffer, it means you
|
|
|
119 have made a mistake in your shell's initialization file (@file{.cshrc}
|
|
|
120 or @file{.shrc} or @dots{}) by setting the prompt unconditionally. The
|
|
|
121 shell initialization file should set the prompt only if there already is
|
|
|
122 a prompt. Here's how to do it in @code{csh}:
|
|
|
123
|
|
|
124 @example
|
|
|
125 if ($?prompt) set prompt = ...
|
|
|
126 @end example
|
|
|
127
|
|
|
128 @node Lisp Modes, Lisp Libraries, Compilation, Running
|
|
|
129 @section Major Modes for Lisp
|
|
|
130
|
|
|
131 Emacs has four different major modes for Lisp. They are the same in
|
|
|
132 terms of editing commands, but differ in the commands for executing Lisp
|
|
|
133 expressions.
|
|
|
134
|
|
|
135 @table @asis
|
|
|
136 @item Emacs-Lisp mode
|
|
|
137 The mode for editing source files of programs to run in Emacs Lisp.
|
|
|
138 This mode defines @kbd{C-M-x} to evaluate the current defun.
|
|
|
139 @xref{Lisp Libraries}.
|
|
|
140 @item Lisp Interaction mode
|
|
|
141 The mode for an interactive session with Emacs Lisp. It defines
|
|
|
142 @key{LFD} to evaluate the sexp before point and insert its value in the
|
|
|
143 buffer. @xref{Lisp Interaction}.
|
|
|
144 @item Lisp mode
|
|
|
145 The mode for editing source files of programs that run in other dialects
|
|
|
146 of Lisp than Emacs Lisp. This mode defines @kbd{C-M-x} to send the
|
|
|
147 current defun to an inferior Lisp process. @xref{External Lisp}.
|
|
|
148 @item Inferior Lisp mode
|
|
|
149 The mode for an interactive session with an inferior Lisp process.
|
|
|
150 This mode combines the special features of Lisp mode and Shell mode
|
|
|
151 (@pxref{Shell Mode}).
|
|
|
152 @item Scheme mode
|
|
|
153 Like Lisp mode but for Scheme programs.
|
|
|
154 @item Inferior Scheme mode
|
|
|
155 The mode for an interactive session with an inferior Scheme process.
|
|
|
156 @end table
|
|
|
157
|
|
|
158 @node Lisp Libraries, Lisp Eval, Lisp Modes, Running
|
|
|
159 @section Libraries of Lisp Code for Emacs
|
|
|
160 @cindex libraries
|
|
|
161 @cindex loading Lisp code
|
|
|
162
|
|
|
163 Lisp code for Emacs editing commands is stored in files whose names
|
|
|
164 conventionally end in @file{.el}. This ending tells Emacs to edit them in
|
|
|
165 Emacs-Lisp mode (@pxref{Lisp Modes}).
|
|
|
166
|
|
|
167 @menu
|
|
|
168 * Loading:: Loading libraries of Lisp code into Emacs for use.
|
|
|
169 * Compiling Libraries:: Compiling a library makes it load and run faster.
|
|
|
170 * Mocklisp:: Converting Mocklisp to Lisp so XEmacs can run it.
|
|
|
171 @end menu
|
|
|
172
|
|
|
173 @node Loading, Compiling Libraries, Lisp Libraries, Lisp Libraries
|
|
|
174 @subsection Loading Libraries
|
|
|
175
|
|
|
176 @table @kbd
|
|
|
177 @item M-x load-file @var{file}
|
|
|
178 Load the file @var{file} of Lisp code.
|
|
|
179 @item M-x load-library @var{library}
|
|
|
180 Load the library named @var{library}.
|
|
|
181 @item M-x locate-library @var{library} &optional @var{nosuffix}
|
|
|
182 Show the full path name of Emacs library @var{library}.
|
|
|
183 @end table
|
|
|
184
|
|
|
185 @findex load-file
|
|
|
186 To execute a file of Emacs Lisp, use @kbd{M-x load-file}. This
|
|
|
187 command reads the file name you provide in the minibuffer, then executes
|
|
|
188 the contents of that file as Lisp code. It is not necessary to visit
|
|
|
189 the file first; in fact, this command reads the file as found on
|
|
|
190 disk, not the text in an Emacs buffer.
|
|
|
191
|
|
|
192 @findex load
|
|
|
193 @findex load-library
|
|
|
194 Once a file of Lisp code is installed in the Emacs Lisp library
|
|
|
195 directories, users can load it using @kbd{M-x load-library}. Programs can
|
|
|
196 load it by calling @code{load-library}, or with @code{load}, a more primitive
|
|
|
197 function that is similar but accepts some additional arguments.
|
|
|
198
|
|
|
199 @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it
|
|
|
200 searches a sequence of directories and tries three file names in each
|
|
|
201 directory. The three names are: first, the specified name with @file{.elc}
|
|
|
202 appended; second, the name with @file{.el} appended; third, the specified
|
|
|
203 name alone. A @file{.elc} file would be the result of compiling the Lisp
|
|
|
204 file into byte code; if possible, it is loaded in preference to the Lisp
|
|
|
205 file itself because the compiled file loads and runs faster.
|
|
|
206
|
|
|
207 @cindex loading libraries
|
|
|
208 Because the argument to @code{load-library} is usually not in itself
|
|
|
209 a valid file name, file name completion is not available. In fact, when
|
|
|
210 using this command, you usually do not know exactly what file name
|
|
|
211 will be used.
|
|
|
212
|
|
|
213 @vindex load-path
|
|
|
214 The sequence of directories searched by @kbd{M-x load-library} is
|
|
|
215 specified by the variable @code{load-path}, a list of strings that are
|
|
|
216 directory names. The elements of this list may not begin with "@samp{~}",
|
|
|
217 so you must call @code{expand-file-name} on them before adding them to
|
|
|
218 the list. The default value of the list contains the directory where
|
|
|
219 the Lisp code for Emacs itself is stored. If you have libraries of your
|
|
|
220 own, put them in a single directory and add that directory to
|
|
|
221 @code{load-path}. @code{nil} in this list stands for the current
|
|
|
222 default directory, but it is probably not a good idea to put @code{nil}
|
|
|
223 in the list. If you start wishing that @code{nil} were in the list, you
|
|
|
224 should probably use @kbd{M-x load-file} for this case.
|
|
|
225
|
|
|
226 The variable is initialized by the @b{EMACSLOADPATH} environment
|
|
|
227 variable. If no value is specified, the variable takes the default value
|
|
|
228 specified in the file @file{paths.h} when Emacs was built. If a path
|
|
|
229 isn't specified in @file{paths.h}, a default value is obtained from the
|
|
|
230 file system, near the directory in which the Emacs executable resides.
|
|
|
231
|
|
|
232 @findex locate-library
|
|
|
233 Like @kbd{M-x load-library}, @kbd{M-x locate-library} searches the
|
|
|
234 directories in @code{load-path} to find the file that @kbd{M-x load-library}
|
|
|
235 would load. If the optional second argument @var{nosuffix} is
|
|
|
236 non-@code{nil}, the suffixes @file{.elc} or @file{.el} are not added to
|
|
|
237 the specified name @var{library} (like calling @code{load} instead of
|
|
|
238 @code{load-library}).
|
|
|
239
|
|
|
240 @cindex autoload
|
|
|
241 You often do not have to give any command to load a library, because the
|
|
|
242 commands defined in the library are set up to @dfn{autoload} that library.
|
|
|
243 Running any of those commands causes @code{load} to be called to load the
|
|
|
244 library; this replaces the autoload definitions with the real ones from the
|
|
|
245 library.
|
|
|
246
|
|
|
247 If autoloading a file does not finish, either because of an error or
|
|
|
248 because of a @kbd{C-g} quit, all function definitions made by the file
|
|
|
249 are undone automatically. So are any calls to @code{provide}. As a
|
|
|
250 consequence, the entire file is loaded a second time if you use one of
|
|
|
251 the autoloadable commands again. This prevents problems when the
|
|
|
252 command is no longer autoloading but is working incorrectly because the file
|
|
|
253 was only partially loaded. Function definitions are undone only for
|
|
|
254 autoloading; explicit calls to @code{load} do not undo anything if
|
|
|
255 loading is not completed.
|
|
|
256
|
|
|
257 @vindex after-load-alist
|
|
|
258 The variable @code{after-load-alist} takes an alist of expressions to be
|
|
|
259 evaluated when particular files are loaded. Each element has the form
|
|
|
260 @code{(@var{filename} forms...)}. When @code{load} is run and the filename
|
|
|
261 argument is @var{filename}, the forms in the corresponding element are
|
|
|
262 executed at the end of loading.
|
|
|
263
|
|
|
264 @var{filename} must match exactly. Normally @var{filename} is the
|
|
|
265 name of a library, with no directory specified, since that is how load
|
|
|
266 is normally called. An error in @code{forms} does not undo the load, but
|
|
|
267 it does prevent execution of the rest of the @code{forms}.
|
|
|
268
|
|
|
269 @node Compiling Libraries, Mocklisp, Loading, Lisp Libraries
|
|
|
270 @subsection Compiling Libraries
|
|
|
271
|
|
|
272 @cindex byte code
|
|
|
273 Emacs Lisp code can be compiled into byte-code which loads faster,
|
|
|
274 takes up less space when loaded, and executes faster.
|
|
|
275
|
|
|
276 @table @kbd
|
|
|
277 @item M-x batch-byte-compile
|
|
|
278 Run byte-compile-file on the files remaining on the command line.
|
|
|
279 @item M-x byte-compile-buffer &optional @var{buffer}
|
|
|
280 Byte-compile and evaluate contents of @var{buffer} (default is current
|
|
|
281 buffer).
|
|
|
282 @item M-x byte-compile-file
|
|
|
283 Compile a file of Lisp code named @var{filename} into a file of byte code.
|
|
|
284 @item M-x byte-compile-and-load-file @var{filename}
|
|
|
285 Compile a file of Lisp code named @var{filename} into a file of byte
|
|
|
286 code and load it.
|
|
|
287 @item M-x byte-recompile-directory @var{directory}
|
|
|
288 Recompile every @file{.el} file in @var{directory} that needs recompilation.
|
|
|
289 @item M-x disassemble
|
|
|
290 Print disassembled code for @var{object} on (optional) @var{stream}.
|
|
|
291 @findex make-obsolete
|
|
|
292 @item M-x make-obsolete @var{function new}
|
|
|
293 Make the byte-compiler warn that @var{function} is obsolete and @var{new}
|
|
|
294 should be used instead.
|
|
|
295 @end table
|
|
|
296
|
|
|
297 @findex byte-compile-file
|
|
|
298 @findex byte-compile-and-load-file
|
|
|
299 @findex byte-compile-buffer
|
|
|
300 @kbd{byte-compile-file} creates a byte-code compiled file from an
|
|
|
301 Emacs-Lisp source file. The default argument for this function is the
|
|
|
302 file visited in the current buffer. The function reads the specified
|
|
|
303 file, compiles it into byte code, and writes an output file whose name
|
|
|
304 is made by appending @file{c} to the input file name. Thus, the file
|
|
|
305 @file{rmail.el} would be compiled into @file{rmail.elc}. To compile a
|
|
|
306 file of Lisp code named @var{filename} into a file of byte code and
|
|
|
307 then load it, use @code{byte-compile-and-load-file}. To compile and
|
|
|
308 evaluate Lisp code in a given buffer, use @code{byte-compile-buffer}.
|
|
|
309
|
|
|
310 @findex byte-recompile-directory
|
|
|
311 To recompile all changed Lisp files in a directory, use @kbd{M-x
|
|
|
312 byte-recompile-directory}. Specify just the directory name as an argument.
|
|
|
313 Each @file{.el} file that has been byte-compiled before is byte-compiled
|
|
|
314 again if it has changed since the previous compilation. A numeric argument
|
|
|
315 to this command tells it to offer to compile each @file{.el} file that has
|
|
|
316 not been compiled yet. You must answer @kbd{y} or @kbd{n} to each
|
|
|
317 offer.
|
|
|
318
|
|
|
319 @findex batch-byte-compile
|
|
|
320 You can use the function @code{batch-byte-compile} to invoke Emacs
|
|
|
321 non-interactively from the shell to do byte compilation. When you use
|
|
|
322 this function, the files to be compiled are specified with command-line
|
|
|
323 arguments. Use a shell command of the form:
|
|
|
324
|
|
|
325 @example
|
|
|
326 emacs -batch -f batch-byte-compile @var{files}...
|
|
|
327 @end example
|
|
|
328
|
|
|
329 Directory names may also be given as arguments; in that case,
|
|
|
330 @code{byte-recompile-directory} is invoked on each such directory.
|
|
|
331 @code{batch-byte-compile} uses all remaining command-line arguments as
|
|
|
332 file or directory names, then kills the Emacs process.
|
|
|
333
|
|
|
334 @findex disassemble
|
|
|
335 @kbd{M-x disassemble} explains the result of byte compilation. Its
|
|
|
336 argument is a function name. It displays the byte-compiled code in a help
|
|
|
337 window in symbolic form, one instruction per line. If the instruction
|
|
|
338 refers to a variable or constant, that is shown, too.
|
|
|
339
|
|
|
340 @node Mocklisp,,Compiling Libraries,Lisp Libraries
|
|
|
341 @subsection Converting Mocklisp to Lisp
|
|
|
342
|
|
|
343 @cindex mocklisp
|
|
|
344 @findex convert-mocklisp-buffer
|
|
|
345 XEmacs can run Mocklisp files by converting them to Emacs Lisp first.
|
|
|
346 To convert a Mocklisp file, visit it and then type @kbd{M-x
|
|
|
347 convert-mocklisp-buffer}. Then save the resulting buffer of Lisp file in a
|
|
|
348 file whose name ends in @file{.el} and use the new file as a Lisp library.
|
|
|
349
|
|
|
350 You cannot currently byte-compile converted Mocklisp code.
|
|
|
351 The reason is that converted Mocklisp code uses some special Lisp features
|
|
|
352 to deal with Mocklisp's incompatible ideas of how arguments are evaluated
|
|
|
353 and which values signify ``true'' or ``false''.
|
|
|
354
|
|
|
355 @node Lisp Eval, Lisp Debug, Lisp Libraries, Running
|
|
|
356 @section Evaluating Emacs-Lisp Expressions
|
|
|
357 @cindex Emacs-Lisp mode
|
|
|
358
|
|
|
359 @findex emacs-lisp-mode
|
|
|
360 Lisp programs intended to be run in Emacs should be edited in
|
|
|
361 Emacs-Lisp mode; this will happen automatically for file names ending in
|
|
|
362 @file{.el}. By contrast, Lisp mode itself should be used for editing
|
|
|
363 Lisp programs intended for other Lisp systems. Emacs-Lisp mode can be
|
|
|
364 selected with the command @kbd{M-x emacs-lisp-mode}.
|
|
|
365
|
|
|
366 For testing of Lisp programs to run in Emacs, it is useful to be able
|
|
|
367 to evaluate part of the program as it is found in the Emacs buffer. For
|
|
|
368 example, if you change the text of a Lisp function definition and then
|
|
|
369 evaluate the definition, Emacs installs the change for future calls to the
|
|
|
370 function. Evaluation of Lisp expressions is also useful in any kind of
|
|
|
371 editing task for invoking non-interactive functions (functions that are
|
|
|
372 not commands).
|
|
|
373
|
|
|
374 @table @kbd
|
|
|
375 @item M-@key{ESC}
|
|
|
376 Read a Lisp expression in the minibuffer, evaluate it, and print the
|
|
|
377 value in the minibuffer (@code{eval-expression}).
|
|
|
378 @item C-x C-e
|
|
|
379 Evaluate the Lisp expression before point, and print the value in the
|
|
|
380 minibuffer (@code{eval-last-sexp}).
|
|
|
381 @item C-M-x
|
|
|
382 Evaluate the defun containing point or after point, and print the value in
|
|
|
383 the minibuffer (@code{eval-defun}).
|
|
|
384 @item M-x eval-region
|
|
|
385 Evaluate all the Lisp expressions in the region.
|
|
|
386 @item M-x eval-current-buffer
|
|
|
387 Evaluate all the Lisp expressions in the buffer.
|
|
|
388 @end table
|
|
|
389
|
|
|
390 @kindex M-ESC
|
|
|
391 @findex eval-expression
|
|
|
392 @kbd{M-@key{ESC}} (@code{eval-expression}) is the most basic command
|
|
|
393 for evaluating a Lisp expression interactively. It reads the expression
|
|
|
394 using the minibuffer, so you can execute any expression on a buffer
|
|
|
395 regardless of what the buffer contains. When evaluation is complete,
|
|
|
396 the current buffer is once again the buffer that was current when
|
|
|
397 @kbd{M-@key{ESC}} was typed.
|
|
|
398
|
|
|
399 @kbd{M-@key{ESC}} can easily confuse users, especially on keyboards
|
|
|
400 with autorepeat, where it can result from holding down the @key{ESC} key
|
|
|
401 for too long. Therefore, @code{eval-expression} is normally a disabled
|
|
|
402 command. Attempting to use this command asks for confirmation and gives
|
|
|
403 you the option of enabling it; once you enable the command, you are no
|
|
|
404 longer required to confirm. @xref{Disabling}.@refill
|
|
|
405
|
|
|
406 @kindex C-M-x
|
|
|
407 @findex eval-defun
|
|
|
408 In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the function
|
|
|
409 @code{eval-defun}, which parses the defun containing point or following point
|
|
|
410 as a Lisp expression and evaluates it. The value is printed in the echo
|
|
|
411 area. This command is convenient for installing in the Lisp environment
|
|
|
412 changes that you have just made in the text of a function definition.
|
|
|
413
|
|
|
414 @kindex C-x C-e
|
|
|
415 @findex eval-last-sexp
|
|
|
416 The command @kbd{C-x C-e} (@code{eval-last-sexp}) performs a similar job
|
|
|
417 but is available in all major modes, not just Emacs-Lisp mode. It finds
|
|
|
418 the sexp before point, reads it as a Lisp expression, evaluates it, and
|
|
|
419 prints the value in the echo area. It is sometimes useful to type in an
|
|
|
420 expression and then, with point still after it, type @kbd{C-x C-e}.
|
|
|
421
|
|
|
422 If @kbd{C-M-x} or @kbd{C-x C-e} are given a numeric argument, they
|
|
|
423 print the value by inserting it into the current buffer at point, rather
|
|
|
424 than in the echo area. The argument value does not matter.
|
|
|
425
|
|
|
426 @findex eval-region
|
|
|
427 @findex eval-current-buffer
|
|
|
428 The most general command for evaluating Lisp expressions from a buffer
|
|
|
429 is @code{eval-region}. @kbd{M-x eval-region} parses the text of the
|
|
|
430 region as one or more Lisp expressions, evaluating them one by one.
|
|
|
431 @kbd{M-x eval-current-buffer} is similar, but it evaluates the entire
|
|
|
432 buffer. This is a reasonable way to install the contents of a file of
|
|
|
433 Lisp code that you are just ready to test. After finding and fixing a
|
|
|
434 bug, use @kbd{C-M-x} on each function that you change, to keep the Lisp
|
|
|
435 world in step with the source file.
|
|
|
436
|
|
|
437 @node Lisp Debug, Lisp Interaction, Lisp Eval, Running
|
|
|
438 @section The Emacs-Lisp Debugger
|
|
|
439 @cindex debugger
|
|
|
440
|
|
|
441 @vindex debug-on-error
|
|
|
442 @vindex debug-on-quit
|
|
|
443 XEmacs contains a debugger for Lisp programs executing inside it.
|
|
|
444 This debugger is normally not used; many commands frequently get Lisp
|
|
|
445 errors when invoked in inappropriate contexts (such as @kbd{C-f} at the
|
|
|
446 end of the buffer) and it would be unpleasant to enter a special
|
|
|
447 debugging mode in this case. When you want to make Lisp errors invoke
|
|
|
448 the debugger, you must set the variable @code{debug-on-error} to
|
|
|
449 non-@code{nil}. Quitting with @kbd{C-g} is not considered an error, and
|
|
|
450 @code{debug-on-error} has no effect on the handling of @kbd{C-g}.
|
|
|
451 However, if you set @code{debug-on-quit} to be non-@code{nil}, @kbd{C-g} will
|
|
|
452 invoke the debugger. This can be useful for debugging an infinite loop;
|
|
|
453 type @kbd{C-g} once the loop has had time to reach its steady state.
|
|
|
454 @code{debug-on-quit} has no effect on errors.@refill
|
|
|
455
|
|
|
456 @findex debug-on-entry
|
|
|
457 @findex cancel-debug-on-entry
|
|
|
458 @findex debug
|
|
|
459 You can make Emacs enter the debugger when a specified function
|
|
|
460 is called or at a particular place in Lisp code. Use @kbd{M-x
|
|
|
461 debug-on-entry} with argument @var{fun-name} to have Emacs enter the
|
|
|
462 debugger as soon as @var{fun-name} is called. Use
|
|
|
463 @kbd{M-x cancel-debug-on-entry} to make the function stop entering the
|
|
|
464 debugger when called. (Redefining the function also does this.) To enter
|
|
|
465 the debugger from some other place in Lisp code, you must insert the
|
|
|
466 expression @code{(debug)} there and install the changed code with
|
|
|
467 @kbd{C-M-x}. @xref{Lisp Eval}.@refill
|
|
|
468
|
|
|
469 When the debugger is entered, it displays the previously selected buffer
|
|
|
470 in one window and a buffer named @samp{*Backtrace*} in another window. The
|
|
|
471 backtrace buffer contains one line for each level of Lisp function
|
|
|
472 execution currently going on. At the beginning of the buffer is a message
|
|
|
473 describing the reason that the debugger was invoked, for example, an
|
|
|
474 error message if it was invoked due to an error.
|
|
|
475
|
|
|
476 The backtrace buffer is read-only and is in Backtrace mode, a special
|
|
|
477 major mode in which letters are defined as debugger commands. The
|
|
|
478 usual Emacs editing commands are available; you can switch windows to
|
|
|
479 examine the buffer that was being edited at the time of the error, and
|
|
|
480 you can switch buffers, visit files, and perform any other editing
|
|
|
481 operations. However, the debugger is a recursive editing level
|
|
|
482 (@pxref{Recursive Edit}); it is a good idea to return to the backtrace
|
|
442
|
483 buffer and explicitly exit the debugger when you don't want to use it any
|
|
428
|
484 more. Exiting the debugger kills the backtrace buffer.
|
|
|
485
|
|
|
486 @cindex current stack frame
|
|
|
487 The contents of the backtrace buffer show you the functions that are
|
|
|
488 executing and the arguments that were given to them. It also allows you
|
|
|
489 to specify a stack frame by moving point to the line describing that
|
|
|
490 frame. The frame whose line point is on is considered the @dfn{current
|
|
|
491 frame}. Some of the debugger commands operate on the current frame.
|
|
|
492 Debugger commands are mainly used for stepping through code one
|
|
|
493 expression at a time. Here is a list of them:
|
|
|
494
|
|
|
495 @table @kbd
|
|
|
496 @item c
|
|
|
497 Exit the debugger and continue execution. In most cases, execution of
|
|
|
498 the program continues as if the debugger had never been entered (aside
|
|
|
499 from the effect of any variables or data structures you may have changed
|
|
|
500 while inside the debugger). This includes entry to the debugger due to
|
|
|
501 function entry or exit, explicit invocation, and quitting or certain
|
|
|
502 errors. Most errors cannot be continued; trying to continue an error usually
|
|
|
503 causes the same error to occur again.
|
|
|
504 @item d
|
|
|
505 Continue execution, but enter the debugger the next time a Lisp
|
|
|
506 function is called. This allows you to step through the
|
|
|
507 subexpressions of an expression, and see what the subexpressions do and
|
|
|
508 what values they compute.
|
|
|
509
|
|
|
510 When you enter the debugger this way, Emacs flags the stack frame for the
|
|
|
511 function call from which you entered. The same function is then called
|
|
|
512 when you exit the frame. To cancel this flag, use @kbd{u}.
|
|
|
513 @item b
|
|
|
514 Set up to enter the debugger when the current frame is exited. Frames
|
|
|
515 that invoke the debugger on exit are flagged with stars.
|
|
|
516 @item u
|
|
|
517 Don't enter the debugger when the current frame is exited. This
|
|
|
518 cancels a @kbd{b} command on a frame.
|
|
|
519 @item e
|
|
|
520 Read a Lisp expression in the minibuffer, evaluate it, and print the
|
|
|
521 value in the echo area. This is equivalent to the command @kbd{M-@key{ESC}},
|
|
|
522 except that @kbd{e} is not normally disabled like @kbd{M-@key{ESC}}.
|
|
|
523 @item q
|
|
|
524 Terminate the program being debugged; return to top-level Emacs
|
|
|
525 command execution.
|
|
|
526
|
|
|
527 If the debugger was entered due to a @kbd{C-g} but you really want
|
|
|
528 to quit, not to debug, use the @kbd{q} command.
|
|
|
529 @item r
|
|
|
530 Return a value from the debugger. The value is computed by reading an
|
|
|
531 expression with the minibuffer and evaluating it.
|
|
|
532
|
|
|
533 The value returned by the debugger makes a difference when the debugger
|
|
|
534 was invoked due to exit from a Lisp call frame (as requested with @kbd{b});
|
|
|
535 then the value specified in the @kbd{r} command is used as the value of
|
|
|
536 that frame.
|
|
|
537
|
|
|
538 The debugger's return value also matters with many errors. For example,
|
|
|
539 @code{wrong-type-argument} errors will use the debugger's return value
|
|
|
540 instead of the invalid argument; @code{no-catch} errors will use the
|
|
|
541 debugger value as a throw tag instead of the tag that was not found.
|
|
|
542 If an error was signaled by calling the Lisp function @code{signal},
|
|
|
543 the debugger's return value is returned as the value of @code{signal}.
|
|
|
544 @end table
|
|
|
545
|
|
|
546 @node Lisp Interaction, External Lisp, Lisp Debug, Running
|
|
|
547 @section Lisp Interaction Buffers
|
|
|
548
|
|
|
549 The buffer @samp{*scratch*}, which is selected when Emacs starts up, is
|
|
|
550 provided for evaluating Lisp expressions interactively inside Emacs. Both
|
|
|
551 the expressions you evaluate and their output goes in the buffer.
|
|
|
552
|
|
|
553 The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which
|
|
|
554 is the same as Emacs-Lisp mode except for one command, @key{LFD}. In
|
|
|
555 Emacs-Lisp mode, @key{LFD} is an indentation command. In Lisp
|
|
|
556 Interaction mode, @key{LFD} is bound to @code{eval-print-last-sexp}. This
|
|
|
557 function reads the Lisp expression before point, evaluates it, and inserts
|
|
|
558 the value in printed representation before point.
|
|
|
559
|
|
|
560 The way to use the @samp{*scratch*} buffer is to insert Lisp
|
|
|
561 expressions at the end, ending each one with @key{LFD} so that it will
|
|
|
562 be evaluated. The result is a complete typescript of the expressions
|
|
|
563 you have evaluated and their values.
|
|
|
564
|
|
|
565 @findex lisp-interaction-mode
|
|
|
566 The rationale for this feature is that Emacs must have a buffer when it
|
|
|
567 starts up, but that buffer is not useful for editing files since a new
|
|
|
568 buffer is made for every file that you visit. The Lisp interpreter
|
|
|
569 typescript is the most useful thing I can think of for the initial buffer
|
|
|
570 to do. @kbd{M-x lisp-interaction-mode} will put any buffer in Lisp
|
|
|
571 Interaction mode.
|
|
|
572
|
|
|
573 @node External Lisp,, Lisp Interaction, Running
|
|
|
574 @section Running an External Lisp
|
|
|
575
|
|
|
576 Emacs has facilities for running programs in other Lisp systems. You can
|
|
|
577 run a Lisp process as an inferior of Emacs, and pass expressions to it to
|
|
|
578 be evaluated. You can also pass changed function definitions directly from
|
|
|
579 the Emacs buffers in which you edit the Lisp programs to the inferior Lisp
|
|
|
580 process.
|
|
|
581
|
|
|
582 @findex run-lisp
|
|
|
583 To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runs the
|
|
|
584 program named @code{lisp}, the same program you would run by typing
|
|
|
585 @code{lisp} as a shell command, with both input and output going through an
|
|
|
586 Emacs buffer named @samp{*lisp*}. In other words, any ``terminal output''
|
|
|
587 from Lisp will go into the buffer, advancing point, and any ``terminal
|
|
|
588 input'' for Lisp comes from text in the buffer. To give input to Lisp, go
|
|
|
589 to the end of the buffer and type the input, terminated by @key{RET}. The
|
|
|
590 @samp{*lisp*} buffer is in Inferior Lisp mode, which has all the
|
|
|
591 special characteristics of Lisp mode and Shell mode (@pxref{Shell Mode}).
|
|
|
592
|
|
|
593 @findex lisp-mode
|
|
|
594 Use Lisp mode to run the source files of programs in external Lisps.
|
|
|
595 You can select this mode with @kbd{M-x lisp-mode}. It is used automatically
|
|
|
596 for files whose names end in @file{.l} or @file{.lisp}, as most Lisp
|
|
|
597 systems usually expect.
|
|
|
598
|
|
|
599 @kindex C-M-x
|
|
|
600 @findex lisp-send-defun
|
|
|
601 When you edit a function in a Lisp program you are running, the easiest
|
|
|
602 way to send the changed definition to the inferior Lisp process is the key
|
|
|
603 @kbd{C-M-x}. In Lisp mode, this key runs the function @code{lisp-send-defun},
|
|
|
604 which finds the defun around or following point and sends it as input to
|
|
|
605 the Lisp process. (Emacs can send input to any inferior process regardless
|
|
|
606 of what buffer is current.)
|
|
|
607
|
|
|
608 Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing programs
|
|
|
609 to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
|
|
|
610 programs to be run in Emacs): in both modes it has the effect of installing
|
|
|
611 the function definition that point is in, but the way of doing so is
|
|
|
612 different according to where the relevant Lisp environment is found.
|
|
|
613 @xref{Lisp Modes}.
|
