Mercurial > hg > xemacs-beta
annotate man/xemacs/building.texi @ 5922:4b055de36bb9 cygwin
merging heads 2
author | Henry Thompson <ht@markup.co.uk> |
---|---|
date | Fri, 27 Feb 2015 17:47:15 +0000 |
parents | 7c7262c47538 |
children |
rev | line source |
---|---|
428 | 1 |
444 | 2 @node Running, Abbrevs, Programs, Top |
428 | 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 | |
444 | 74 To kill the compilation process, type @kbd{M-x kill-compilation}. The mode |
428 | 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 | |
2757 | 142 @kbd{C-j} to evaluate the sexp before point and insert its value in the |
428 | 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 @end menu | |
171 | |
172 @node Loading, Compiling Libraries, Lisp Libraries, Lisp Libraries | |
173 @subsection Loading Libraries | |
174 | |
175 @table @kbd | |
176 @item M-x load-file @var{file} | |
177 Load the file @var{file} of Lisp code. | |
178 @item M-x load-library @var{library} | |
179 Load the library named @var{library}. | |
180 @item M-x locate-library @var{library} &optional @var{nosuffix} | |
181 Show the full path name of Emacs library @var{library}. | |
182 @end table | |
183 | |
184 @findex load-file | |
185 To execute a file of Emacs Lisp, use @kbd{M-x load-file}. This | |
186 command reads the file name you provide in the minibuffer, then executes | |
187 the contents of that file as Lisp code. It is not necessary to visit | |
188 the file first; in fact, this command reads the file as found on | |
189 disk, not the text in an Emacs buffer. | |
190 | |
191 @findex load | |
192 @findex load-library | |
193 Once a file of Lisp code is installed in the Emacs Lisp library | |
194 directories, users can load it using @kbd{M-x load-library}. Programs can | |
195 load it by calling @code{load-library}, or with @code{load}, a more primitive | |
196 function that is similar but accepts some additional arguments. | |
197 | |
198 @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it | |
199 searches a sequence of directories and tries three file names in each | |
200 directory. The three names are: first, the specified name with @file{.elc} | |
201 appended; second, the name with @file{.el} appended; third, the specified | |
202 name alone. A @file{.elc} file would be the result of compiling the Lisp | |
203 file into byte code; if possible, it is loaded in preference to the Lisp | |
204 file itself because the compiled file loads and runs faster. | |
205 | |
206 @cindex loading libraries | |
207 Because the argument to @code{load-library} is usually not in itself | |
208 a valid file name, file name completion is not available. In fact, when | |
209 using this command, you usually do not know exactly what file name | |
210 will be used. | |
211 | |
212 @vindex load-path | |
213 The sequence of directories searched by @kbd{M-x load-library} is | |
214 specified by the variable @code{load-path}, a list of strings that are | |
215 directory names. The elements of this list may not begin with "@samp{~}", | |
216 so you must call @code{expand-file-name} on them before adding them to | |
217 the list. The default value of the list contains the directory where | |
218 the Lisp code for Emacs itself is stored. If you have libraries of your | |
219 own, put them in a single directory and add that directory to | |
220 @code{load-path}. @code{nil} in this list stands for the current | |
221 default directory, but it is probably not a good idea to put @code{nil} | |
222 in the list. If you start wishing that @code{nil} were in the list, you | |
223 should probably use @kbd{M-x load-file} for this case. | |
224 | |
225 The variable is initialized by the @b{EMACSLOADPATH} environment | |
226 variable. If no value is specified, the variable takes the default value | |
227 specified in the file @file{paths.h} when Emacs was built. If a path | |
228 isn't specified in @file{paths.h}, a default value is obtained from the | |
229 file system, near the directory in which the Emacs executable resides. | |
230 | |
231 @findex locate-library | |
232 Like @kbd{M-x load-library}, @kbd{M-x locate-library} searches the | |
233 directories in @code{load-path} to find the file that @kbd{M-x load-library} | |
234 would load. If the optional second argument @var{nosuffix} is | |
235 non-@code{nil}, the suffixes @file{.elc} or @file{.el} are not added to | |
236 the specified name @var{library} (like calling @code{load} instead of | |
237 @code{load-library}). | |
238 | |
239 @cindex autoload | |
240 You often do not have to give any command to load a library, because the | |
241 commands defined in the library are set up to @dfn{autoload} that library. | |
242 Running any of those commands causes @code{load} to be called to load the | |
243 library; this replaces the autoload definitions with the real ones from the | |
244 library. | |
245 | |
246 If autoloading a file does not finish, either because of an error or | |
247 because of a @kbd{C-g} quit, all function definitions made by the file | |
248 are undone automatically. So are any calls to @code{provide}. As a | |
249 consequence, the entire file is loaded a second time if you use one of | |
250 the autoloadable commands again. This prevents problems when the | |
251 command is no longer autoloading but is working incorrectly because the file | |
252 was only partially loaded. Function definitions are undone only for | |
253 autoloading; explicit calls to @code{load} do not undo anything if | |
254 loading is not completed. | |
255 | |
256 @vindex after-load-alist | |
257 The variable @code{after-load-alist} takes an alist of expressions to be | |
258 evaluated when particular files are loaded. Each element has the form | |
259 @code{(@var{filename} forms...)}. When @code{load} is run and the filename | |
260 argument is @var{filename}, the forms in the corresponding element are | |
261 executed at the end of loading. | |
262 | |
263 @var{filename} must match exactly. Normally @var{filename} is the | |
264 name of a library, with no directory specified, since that is how load | |
265 is normally called. An error in @code{forms} does not undo the load, but | |
266 it does prevent execution of the rest of the @code{forms}. | |
267 | |
4601
7c7262c47538
Remove any reference to mocklisp as an active technology.
Aidan Kehoe <kehoea@parhasard.net>
parents:
3260
diff
changeset
|
268 @node Compiling Libraries, , Loading, Lisp Libraries |
428 | 269 @subsection Compiling Libraries |
270 | |
271 @cindex byte code | |
272 Emacs Lisp code can be compiled into byte-code which loads faster, | |
273 takes up less space when loaded, and executes faster. | |
274 | |
275 @table @kbd | |
276 @item M-x batch-byte-compile | |
277 Run byte-compile-file on the files remaining on the command line. | |
278 @item M-x byte-compile-buffer &optional @var{buffer} | |
279 Byte-compile and evaluate contents of @var{buffer} (default is current | |
280 buffer). | |
281 @item M-x byte-compile-file | |
282 Compile a file of Lisp code named @var{filename} into a file of byte code. | |
283 @item M-x byte-compile-and-load-file @var{filename} | |
284 Compile a file of Lisp code named @var{filename} into a file of byte | |
285 code and load it. | |
286 @item M-x byte-recompile-directory @var{directory} | |
287 Recompile every @file{.el} file in @var{directory} that needs recompilation. | |
288 @item M-x disassemble | |
289 Print disassembled code for @var{object} on (optional) @var{stream}. | |
290 @findex make-obsolete | |
291 @item M-x make-obsolete @var{function new} | |
292 Make the byte-compiler warn that @var{function} is obsolete and @var{new} | |
293 should be used instead. | |
294 @end table | |
295 | |
296 @findex byte-compile-file | |
297 @findex byte-compile-and-load-file | |
298 @findex byte-compile-buffer | |
299 @kbd{byte-compile-file} creates a byte-code compiled file from an | |
300 Emacs-Lisp source file. The default argument for this function is the | |
301 file visited in the current buffer. The function reads the specified | |
302 file, compiles it into byte code, and writes an output file whose name | |
303 is made by appending @file{c} to the input file name. Thus, the file | |
304 @file{rmail.el} would be compiled into @file{rmail.elc}. To compile a | |
305 file of Lisp code named @var{filename} into a file of byte code and | |
306 then load it, use @code{byte-compile-and-load-file}. To compile and | |
307 evaluate Lisp code in a given buffer, use @code{byte-compile-buffer}. | |
308 | |
309 @findex byte-recompile-directory | |
310 To recompile all changed Lisp files in a directory, use @kbd{M-x | |
311 byte-recompile-directory}. Specify just the directory name as an argument. | |
312 Each @file{.el} file that has been byte-compiled before is byte-compiled | |
313 again if it has changed since the previous compilation. A numeric argument | |
314 to this command tells it to offer to compile each @file{.el} file that has | |
315 not been compiled yet. You must answer @kbd{y} or @kbd{n} to each | |
316 offer. | |
317 | |
318 @findex batch-byte-compile | |
319 You can use the function @code{batch-byte-compile} to invoke Emacs | |
320 non-interactively from the shell to do byte compilation. When you use | |
321 this function, the files to be compiled are specified with command-line | |
322 arguments. Use a shell command of the form: | |
323 | |
324 @example | |
325 emacs -batch -f batch-byte-compile @var{files}... | |
326 @end example | |
327 | |
328 Directory names may also be given as arguments; in that case, | |
329 @code{byte-recompile-directory} is invoked on each such directory. | |
330 @code{batch-byte-compile} uses all remaining command-line arguments as | |
331 file or directory names, then kills the Emacs process. | |
332 | |
333 @findex disassemble | |
334 @kbd{M-x disassemble} explains the result of byte compilation. Its | |
335 argument is a function name. It displays the byte-compiled code in a help | |
336 window in symbolic form, one instruction per line. If the instruction | |
337 refers to a variable or constant, that is shown, too. | |
338 | |
339 @node Lisp Eval, Lisp Debug, Lisp Libraries, Running | |
340 @section Evaluating Emacs-Lisp Expressions | |
341 @cindex Emacs-Lisp mode | |
342 | |
343 @findex emacs-lisp-mode | |
344 Lisp programs intended to be run in Emacs should be edited in | |
345 Emacs-Lisp mode; this will happen automatically for file names ending in | |
346 @file{.el}. By contrast, Lisp mode itself should be used for editing | |
347 Lisp programs intended for other Lisp systems. Emacs-Lisp mode can be | |
348 selected with the command @kbd{M-x emacs-lisp-mode}. | |
349 | |
350 For testing of Lisp programs to run in Emacs, it is useful to be able | |
351 to evaluate part of the program as it is found in the Emacs buffer. For | |
352 example, if you change the text of a Lisp function definition and then | |
353 evaluate the definition, Emacs installs the change for future calls to the | |
354 function. Evaluation of Lisp expressions is also useful in any kind of | |
355 editing task for invoking non-interactive functions (functions that are | |
356 not commands). | |
357 | |
358 @table @kbd | |
359 @item M-@key{ESC} | |
360 Read a Lisp expression in the minibuffer, evaluate it, and print the | |
361 value in the minibuffer (@code{eval-expression}). | |
362 @item C-x C-e | |
363 Evaluate the Lisp expression before point, and print the value in the | |
364 minibuffer (@code{eval-last-sexp}). | |
365 @item C-M-x | |
366 Evaluate the defun containing point or after point, and print the value in | |
367 the minibuffer (@code{eval-defun}). | |
368 @item M-x eval-region | |
369 Evaluate all the Lisp expressions in the region. | |
370 @item M-x eval-current-buffer | |
371 Evaluate all the Lisp expressions in the buffer. | |
372 @end table | |
373 | |
374 @kindex M-ESC | |
375 @findex eval-expression | |
376 @kbd{M-@key{ESC}} (@code{eval-expression}) is the most basic command | |
377 for evaluating a Lisp expression interactively. It reads the expression | |
378 using the minibuffer, so you can execute any expression on a buffer | |
379 regardless of what the buffer contains. When evaluation is complete, | |
380 the current buffer is once again the buffer that was current when | |
381 @kbd{M-@key{ESC}} was typed. | |
382 | |
383 @kbd{M-@key{ESC}} can easily confuse users, especially on keyboards | |
384 with autorepeat, where it can result from holding down the @key{ESC} key | |
385 for too long. Therefore, @code{eval-expression} is normally a disabled | |
386 command. Attempting to use this command asks for confirmation and gives | |
387 you the option of enabling it; once you enable the command, you are no | |
388 longer required to confirm. @xref{Disabling}.@refill | |
389 | |
390 @kindex C-M-x | |
391 @findex eval-defun | |
392 In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the function | |
393 @code{eval-defun}, which parses the defun containing point or following point | |
394 as a Lisp expression and evaluates it. The value is printed in the echo | |
395 area. This command is convenient for installing in the Lisp environment | |
396 changes that you have just made in the text of a function definition. | |
397 | |
398 @kindex C-x C-e | |
399 @findex eval-last-sexp | |
400 The command @kbd{C-x C-e} (@code{eval-last-sexp}) performs a similar job | |
401 but is available in all major modes, not just Emacs-Lisp mode. It finds | |
402 the sexp before point, reads it as a Lisp expression, evaluates it, and | |
403 prints the value in the echo area. It is sometimes useful to type in an | |
404 expression and then, with point still after it, type @kbd{C-x C-e}. | |
405 | |
406 If @kbd{C-M-x} or @kbd{C-x C-e} are given a numeric argument, they | |
407 print the value by inserting it into the current buffer at point, rather | |
408 than in the echo area. The argument value does not matter. | |
409 | |
410 @findex eval-region | |
411 @findex eval-current-buffer | |
412 The most general command for evaluating Lisp expressions from a buffer | |
413 is @code{eval-region}. @kbd{M-x eval-region} parses the text of the | |
414 region as one or more Lisp expressions, evaluating them one by one. | |
415 @kbd{M-x eval-current-buffer} is similar, but it evaluates the entire | |
416 buffer. This is a reasonable way to install the contents of a file of | |
417 Lisp code that you are just ready to test. After finding and fixing a | |
418 bug, use @kbd{C-M-x} on each function that you change, to keep the Lisp | |
419 world in step with the source file. | |
420 | |
421 @node Lisp Debug, Lisp Interaction, Lisp Eval, Running | |
422 @section The Emacs-Lisp Debugger | |
423 @cindex debugger | |
424 | |
425 @vindex debug-on-error | |
426 @vindex debug-on-quit | |
427 XEmacs contains a debugger for Lisp programs executing inside it. | |
428 This debugger is normally not used; many commands frequently get Lisp | |
429 errors when invoked in inappropriate contexts (such as @kbd{C-f} at the | |
430 end of the buffer) and it would be unpleasant to enter a special | |
431 debugging mode in this case. When you want to make Lisp errors invoke | |
432 the debugger, you must set the variable @code{debug-on-error} to | |
433 non-@code{nil}. Quitting with @kbd{C-g} is not considered an error, and | |
434 @code{debug-on-error} has no effect on the handling of @kbd{C-g}. | |
435 However, if you set @code{debug-on-quit} to be non-@code{nil}, @kbd{C-g} will | |
436 invoke the debugger. This can be useful for debugging an infinite loop; | |
437 type @kbd{C-g} once the loop has had time to reach its steady state. | |
438 @code{debug-on-quit} has no effect on errors.@refill | |
439 | |
440 @findex debug-on-entry | |
441 @findex cancel-debug-on-entry | |
442 @findex debug | |
443 You can make Emacs enter the debugger when a specified function | |
444 is called or at a particular place in Lisp code. Use @kbd{M-x | |
445 debug-on-entry} with argument @var{fun-name} to have Emacs enter the | |
446 debugger as soon as @var{fun-name} is called. Use | |
447 @kbd{M-x cancel-debug-on-entry} to make the function stop entering the | |
448 debugger when called. (Redefining the function also does this.) To enter | |
449 the debugger from some other place in Lisp code, you must insert the | |
450 expression @code{(debug)} there and install the changed code with | |
451 @kbd{C-M-x}. @xref{Lisp Eval}.@refill | |
452 | |
453 When the debugger is entered, it displays the previously selected buffer | |
454 in one window and a buffer named @samp{*Backtrace*} in another window. The | |
455 backtrace buffer contains one line for each level of Lisp function | |
456 execution currently going on. At the beginning of the buffer is a message | |
457 describing the reason that the debugger was invoked, for example, an | |
458 error message if it was invoked due to an error. | |
459 | |
460 The backtrace buffer is read-only and is in Backtrace mode, a special | |
461 major mode in which letters are defined as debugger commands. The | |
462 usual Emacs editing commands are available; you can switch windows to | |
463 examine the buffer that was being edited at the time of the error, and | |
464 you can switch buffers, visit files, and perform any other editing | |
465 operations. However, the debugger is a recursive editing level | |
466 (@pxref{Recursive Edit}); it is a good idea to return to the backtrace | |
442 | 467 buffer and explicitly exit the debugger when you don't want to use it any |
428 | 468 more. Exiting the debugger kills the backtrace buffer. |
469 | |
470 @cindex current stack frame | |
471 The contents of the backtrace buffer show you the functions that are | |
472 executing and the arguments that were given to them. It also allows you | |
473 to specify a stack frame by moving point to the line describing that | |
474 frame. The frame whose line point is on is considered the @dfn{current | |
475 frame}. Some of the debugger commands operate on the current frame. | |
476 Debugger commands are mainly used for stepping through code one | |
477 expression at a time. Here is a list of them: | |
478 | |
479 @table @kbd | |
480 @item c | |
481 Exit the debugger and continue execution. In most cases, execution of | |
482 the program continues as if the debugger had never been entered (aside | |
483 from the effect of any variables or data structures you may have changed | |
484 while inside the debugger). This includes entry to the debugger due to | |
485 function entry or exit, explicit invocation, and quitting or certain | |
486 errors. Most errors cannot be continued; trying to continue an error usually | |
487 causes the same error to occur again. | |
488 @item d | |
489 Continue execution, but enter the debugger the next time a Lisp | |
490 function is called. This allows you to step through the | |
491 subexpressions of an expression, and see what the subexpressions do and | |
492 what values they compute. | |
493 | |
494 When you enter the debugger this way, Emacs flags the stack frame for the | |
495 function call from which you entered. The same function is then called | |
496 when you exit the frame. To cancel this flag, use @kbd{u}. | |
497 @item b | |
498 Set up to enter the debugger when the current frame is exited. Frames | |
499 that invoke the debugger on exit are flagged with stars. | |
500 @item u | |
501 Don't enter the debugger when the current frame is exited. This | |
502 cancels a @kbd{b} command on a frame. | |
503 @item e | |
504 Read a Lisp expression in the minibuffer, evaluate it, and print the | |
505 value in the echo area. This is equivalent to the command @kbd{M-@key{ESC}}, | |
506 except that @kbd{e} is not normally disabled like @kbd{M-@key{ESC}}. | |
507 @item q | |
508 Terminate the program being debugged; return to top-level Emacs | |
509 command execution. | |
510 | |
511 If the debugger was entered due to a @kbd{C-g} but you really want | |
512 to quit, not to debug, use the @kbd{q} command. | |
513 @item r | |
514 Return a value from the debugger. The value is computed by reading an | |
515 expression with the minibuffer and evaluating it. | |
516 | |
517 The value returned by the debugger makes a difference when the debugger | |
518 was invoked due to exit from a Lisp call frame (as requested with @kbd{b}); | |
519 then the value specified in the @kbd{r} command is used as the value of | |
520 that frame. | |
521 | |
522 The debugger's return value also matters with many errors. For example, | |
523 @code{wrong-type-argument} errors will use the debugger's return value | |
524 instead of the invalid argument; @code{no-catch} errors will use the | |
525 debugger value as a throw tag instead of the tag that was not found. | |
526 If an error was signaled by calling the Lisp function @code{signal}, | |
527 the debugger's return value is returned as the value of @code{signal}. | |
528 @end table | |
529 | |
530 @node Lisp Interaction, External Lisp, Lisp Debug, Running | |
531 @section Lisp Interaction Buffers | |
532 | |
533 The buffer @samp{*scratch*}, which is selected when Emacs starts up, is | |
534 provided for evaluating Lisp expressions interactively inside Emacs. Both | |
535 the expressions you evaluate and their output goes in the buffer. | |
536 | |
537 The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which | |
2757 | 538 is the same as Emacs-Lisp mode except for one command, @kbd{C-j}. In |
539 Emacs-Lisp mode, @kbd{C-j} is an indentation command. In Lisp | |
540 Interaction mode, @kbd{C-j} is bound to @code{eval-print-last-sexp}. This | |
428 | 541 function reads the Lisp expression before point, evaluates it, and inserts |
542 the value in printed representation before point. | |
543 | |
544 The way to use the @samp{*scratch*} buffer is to insert Lisp | |
2757 | 545 expressions at the end, ending each one with @kbd{C-j} so that it will |
428 | 546 be evaluated. The result is a complete typescript of the expressions |
547 you have evaluated and their values. | |
548 | |
549 @findex lisp-interaction-mode | |
550 The rationale for this feature is that Emacs must have a buffer when it | |
551 starts up, but that buffer is not useful for editing files since a new | |
552 buffer is made for every file that you visit. The Lisp interpreter | |
553 typescript is the most useful thing I can think of for the initial buffer | |
554 to do. @kbd{M-x lisp-interaction-mode} will put any buffer in Lisp | |
555 Interaction mode. | |
556 | |
557 @node External Lisp,, Lisp Interaction, Running | |
558 @section Running an External Lisp | |
559 | |
560 Emacs has facilities for running programs in other Lisp systems. You can | |
561 run a Lisp process as an inferior of Emacs, and pass expressions to it to | |
562 be evaluated. You can also pass changed function definitions directly from | |
563 the Emacs buffers in which you edit the Lisp programs to the inferior Lisp | |
564 process. | |
565 | |
566 @findex run-lisp | |
3260 | 567 To run an inferior Lisp process, type @kbd{M-x run-lisp}. |
568 (You need to the @file{os-utils} package installed for this.) This runs the | |
428 | 569 program named @code{lisp}, the same program you would run by typing |
570 @code{lisp} as a shell command, with both input and output going through an | |
571 Emacs buffer named @samp{*lisp*}. In other words, any ``terminal output'' | |
572 from Lisp will go into the buffer, advancing point, and any ``terminal | |
573 input'' for Lisp comes from text in the buffer. To give input to Lisp, go | |
574 to the end of the buffer and type the input, terminated by @key{RET}. The | |
575 @samp{*lisp*} buffer is in Inferior Lisp mode, which has all the | |
576 special characteristics of Lisp mode and Shell mode (@pxref{Shell Mode}). | |
577 | |
578 @findex lisp-mode | |
579 Use Lisp mode to run the source files of programs in external Lisps. | |
580 You can select this mode with @kbd{M-x lisp-mode}. It is used automatically | |
581 for files whose names end in @file{.l} or @file{.lisp}, as most Lisp | |
582 systems usually expect. | |
583 | |
584 @kindex C-M-x | |
585 @findex lisp-send-defun | |
586 When you edit a function in a Lisp program you are running, the easiest | |
587 way to send the changed definition to the inferior Lisp process is the key | |
588 @kbd{C-M-x}. In Lisp mode, this key runs the function @code{lisp-send-defun}, | |
589 which finds the defun around or following point and sends it as input to | |
590 the Lisp process. (Emacs can send input to any inferior process regardless | |
591 of what buffer is current.) | |
592 | |
593 Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing programs | |
594 to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp | |
595 programs to be run in Emacs): in both modes it has the effect of installing | |
596 the function definition that point is in, but the way of doing so is | |
597 different according to where the relevant Lisp environment is found. | |
598 @xref{Lisp Modes}. |