Mercurial > emacs
annotate man/building.texi @ 31170:84ec8b66d634
(redisplay_internal): If considering all windows on all
frames, update the display for each frame as soon as possible,
instead of first building all desired matrices for all frames, and
then updating them all.
(try_cursor_movement): Handle case that last_cursor.vpos is -1.
author | Gerd Moellmann <gerd@gnu.org> |
---|---|
date | Fri, 25 Aug 2000 13:21:21 +0000 |
parents | 561ef681eab5 |
children | 390058c38d27 |
rev | line source |
---|---|
25829 | 1 @c This is part of the Emacs manual. |
27223 | 2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000 Free Software Foundation, Inc. |
25829 | 3 @c See file emacs.texi for copying conditions. |
4 @node Building, Abbrevs, Programs, Top | |
5 @chapter Compiling and Testing Programs | |
6 @cindex building programs | |
7 @cindex program building | |
8 @cindex running Lisp functions | |
9 | |
10 The previous chapter discusses the Emacs commands that are useful for | |
11 making changes in programs. This chapter deals with commands that assist | |
12 in the larger process of developing and maintaining programs. | |
13 | |
14 @menu | |
15 * Compilation:: Compiling programs in languages other | |
16 than Lisp (C, Pascal, etc.). | |
17 * Grep Searching:: Running grep as if it were a compiler. | |
18 * Compilation Mode:: The mode for visiting compiler errors. | |
19 * Compilation Shell:: Customizing your shell properly | |
20 for use in the compilation buffer. | |
21 * Debuggers:: Running symbolic debuggers for non-Lisp programs. | |
22 * Executing Lisp:: Various modes for editing Lisp programs, | |
23 with different facilities for running | |
24 the Lisp programs. | |
25 * Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs. | |
26 * Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer. | |
27 * Eval: Lisp Eval. Executing a single Lisp expression in Emacs. | |
28 * External Lisp:: Communicating through Emacs with a separate Lisp. | |
29 @end menu | |
30 | |
31 @node Compilation | |
32 @section Running Compilations under Emacs | |
33 @cindex inferior process | |
34 @cindex make | |
35 @cindex compilation errors | |
36 @cindex error log | |
37 | |
38 Emacs can run compilers for noninteractive languages such as C and | |
39 Fortran as inferior processes, feeding the error log into an Emacs buffer. | |
40 It can also parse the error messages and show you the source lines where | |
41 compilation errors occurred. | |
42 | |
43 @table @kbd | |
44 @item M-x compile | |
45 Run a compiler asynchronously under Emacs, with error messages to | |
46 @samp{*compilation*} buffer. | |
47 @item M-x grep | |
48 Run @code{grep} asynchronously under Emacs, with matching lines | |
49 listed in the buffer named @samp{*grep*}. | |
50 @item M-x grep-find | |
51 Run @code{grep} via @code{find}, with user-specified arguments, and | |
52 collect output in the buffer named @samp{*grep*}. | |
53 @item M-x kill-compilation | |
54 @itemx M-x kill-grep | |
55 Kill the running compilation or @code{grep} subprocess. | |
56 @end table | |
57 | |
58 @findex compile | |
59 To run @code{make} or another compilation command, do @kbd{M-x | |
60 compile}. This command reads a shell command line using the minibuffer, | |
61 and then executes the command in an inferior shell, putting output in | |
62 the buffer named @samp{*compilation*}. The current buffer's default | |
63 directory is used as the working directory for the execution of the | |
64 command; normally, therefore, the compilation happens in this | |
65 directory. | |
66 | |
67 @vindex compile-command | |
68 When the shell command line is read, the minibuffer appears containing | |
69 a default command line, which is the command you used the last time you | |
70 did @kbd{M-x compile}. If you type just @key{RET}, the same command | |
71 line is used again. For the first @kbd{M-x compile}, the default is | |
72 @samp{make -k}. The default compilation command comes from the variable | |
73 @code{compile-command}; if the appropriate compilation command for a | |
74 file is something other than @samp{make -k}, it can be useful for the | |
75 file to specify a local value for @code{compile-command} (@pxref{File | |
76 Variables}). | |
77 | |
78 Starting a compilation displays the buffer @samp{*compilation*} in | |
79 another window but does not select it. The buffer's mode line tells you | |
80 whether compilation is finished, with the word @samp{run} or @samp{exit} | |
81 inside the parentheses. You do not have to keep this buffer visible; | |
82 compilation continues in any case. While a compilation is going on, the | |
83 string @samp{Compiling} appears in the mode lines of all windows. When | |
84 this string disappears, the compilation is finished. | |
85 | |
86 If you want to watch the compilation transcript as it appears, switch | |
87 to the @samp{*compilation*} buffer and move point to the end of the | |
88 buffer. When point is at the end, new compilation output is inserted | |
89 above point, which remains at the end. If point is not at the end of | |
90 the buffer, it remains fixed while more compilation output is added at | |
91 the end of the buffer. | |
92 | |
93 @vindex compilation-scroll-output | |
94 If you set the variable @code{compilation-scroll-output} to a | |
95 non-@code{nil} value, then the compilation buffer always scrolls to | |
96 follow output as it comes in. | |
97 | |
98 @findex kill-compilation | |
99 To kill the compilation process, do @kbd{M-x kill-compilation}. When | |
100 the compiler process terminates, the mode line of the | |
101 @samp{*compilation*} buffer changes to say @samp{signal} instead of | |
102 @samp{run}. Starting a new compilation also kills any running | |
103 compilation, as only one can exist at any time. However, @kbd{M-x | |
104 compile} asks for confirmation before actually killing a compilation | |
105 that is running. | |
106 | |
107 @node Grep Searching | |
108 @section Searching with Grep under Emacs | |
109 | |
110 @findex grep | |
111 Just as you can run a compiler from Emacs and then visit the lines | |
112 where there were compilation errors, you can also run @code{grep} and | |
113 then visit the lines on which matches were found. This works by | |
114 treating the matches reported by @code{grep} as if they were ``errors.'' | |
115 | |
116 To do this, type @kbd{M-x grep}, then enter a command line that | |
117 specifies how to run @code{grep}. Use the same arguments you would give | |
118 @code{grep} when running it normally: a @code{grep}-style regexp | |
119 (usually in single-quotes to quote the shell's special characters) | |
120 followed by file names, which may use wildcards. The output from | |
121 @code{grep} goes in the @samp{*grep*} buffer. You can find the | |
122 corresponding lines in the original files using @kbd{C-x `} and | |
123 @key{RET}, as with compilation errors. | |
124 | |
125 If you specify a prefix argument for @kbd{M-x grep}, it figures out | |
126 the tag (@pxref{Tags}) around point, and puts that into the default | |
127 @code{grep} command. | |
128 | |
129 @findex grep-find | |
130 The command @kbd{M-x grep-find} is similar to @kbd{M-x grep}, but it | |
131 supplies a different initial default for the command---one that runs | |
132 both @code{find} and @code{grep}, so as to search every file in a | |
133 directory tree. See also the @code{find-grep-dired} command, | |
134 in @ref{Dired and Find}. | |
135 | |
136 @node Compilation Mode | |
137 @section Compilation Mode | |
138 | |
139 @findex compile-goto-error | |
140 @cindex Compilation mode | |
141 @cindex mode, Compilation | |
142 The @samp{*compilation*} buffer uses a special major mode, Compilation | |
143 mode, whose main feature is to provide a convenient way to look at the | |
144 source line where the error happened. | |
145 | |
146 @table @kbd | |
147 @item C-x ` | |
148 Visit the locus of the next compiler error message or @code{grep} match. | |
149 @item @key{RET} | |
150 Visit the locus of the error message that point is on. | |
151 This command is used in the compilation buffer. | |
152 @item Mouse-2 | |
153 Visit the locus of the error message that you click on. | |
154 @end table | |
155 | |
156 @kindex C-x ` | |
157 @findex next-error | |
158 You can visit the source for any particular error message by moving | |
159 point in @samp{*compilation*} to that error message and typing @key{RET} | |
160 (@code{compile-goto-error}). Or click @kbd{Mouse-2} on the error message; | |
161 you need not switch to the @samp{*compilation*} buffer first. | |
162 | |
163 To parse the compiler error messages sequentially, type @kbd{C-x `} | |
164 (@code{next-error}). The character following the @kbd{C-x} is the | |
165 backquote or ``grave accent,'' not the single-quote. This command is | |
166 available in all buffers, not just in @samp{*compilation*}; it displays | |
167 the next error message at the top of one window and source location of | |
168 the error in another window. | |
169 | |
170 The first time @kbd{C-x `} is used after the start of a compilation, | |
171 it moves to the first error's location. Subsequent uses of @kbd{C-x `} | |
172 advance down to subsequent errors. If you visit a specific error | |
173 message with @key{RET} or @kbd{Mouse-2}, subsequent @kbd{C-x `} | |
174 commands advance from there. When @kbd{C-x `} gets to the end of the | |
175 buffer and finds no more error messages to visit, it fails and signals | |
176 an Emacs error. | |
177 | |
178 @kbd{C-u C-x `} starts scanning from the beginning of the compilation | |
179 buffer. This is one way to process the same set of errors again. | |
180 | |
181 Compilation mode also redefines the keys @key{SPC} and @key{DEL} to | |
182 scroll by screenfuls, and @kbd{M-n} and @kbd{M-p} to move to the next or | |
183 previous error message. You can also use @kbd{M-@{} and @kbd{M-@}} to | |
184 move up or down to an error message for a different source file. | |
185 | |
186 The features of Compilation mode are also available in a minor mode | |
187 called Compilation Minor mode. This lets you parse error messages in | |
188 any buffer, not just a normal compilation output buffer. Type @kbd{M-x | |
189 compilation-minor-mode} to enable the minor mode. This defines the keys | |
190 @key{RET} and @kbd{Mouse-2}, as in the Compilation major mode. | |
191 | |
192 Compilation minor mode works in any buffer, as long as the contents | |
193 are in a format that it understands. In an Rlogin buffer (@pxref{Remote | |
194 Host}), Compilation minor mode automatically accesses remote source | |
195 files by FTP (@pxref{File Names}). | |
196 | |
197 @node Compilation Shell | |
198 @section Subshells for Compilation | |
199 | |
200 Emacs uses a shell to run the compilation command, but specifies | |
201 the option for a noninteractive shell. This means, in particular, that | |
202 the shell should start with no prompt. If you find your usual shell | |
203 prompt making an unsightly appearance in the @samp{*compilation*} | |
204 buffer, it means you have made a mistake in your shell's init file by | |
205 setting the prompt unconditionally. (This init file's name may be | |
206 @file{.bashrc}, @file{.profile}, @file{.cshrc}, @file{.shrc}, or various | |
207 other things, depending on the shell you use.) The shell init file | |
208 should set the prompt only if there already is a prompt. In csh, here | |
209 is how to do it: | |
210 | |
211 @example | |
212 if ($?prompt) set prompt = @dots{} | |
213 @end example | |
214 | |
215 @noindent | |
216 And here's how to do it in bash: | |
217 | |
218 @example | |
219 if [ "$@{PS1+set@}" = set ] | |
220 then PS1=@dots{} | |
221 fi | |
222 @end example | |
223 | |
224 There may well be other things that your shell's init file | |
225 ought to do only for an interactive shell. You can use the same | |
226 method to conditionalize them. | |
227 | |
228 The MS-DOS ``operating system'' does not support asynchronous | |
229 subprocesses; to work around this lack, @kbd{M-x compile} runs the | |
230 compilation command synchronously on MS-DOS. As a consequence, you must | |
231 wait until the command finishes before you can do anything else in | |
232 Emacs. @xref{MS-DOS}. | |
233 | |
234 @node Debuggers | |
235 @section Running Debuggers Under Emacs | |
236 @cindex debuggers | |
237 @cindex GUD library | |
238 @cindex GDB | |
239 @cindex DBX | |
240 @cindex SDB | |
241 @cindex XDB | |
242 @cindex Perldb | |
243 @cindex JDB | |
244 @cindex PDB | |
245 | |
246 @c Do you believe in GUD? | |
247 The GUD (Grand Unified Debugger) library provides an interface to | |
248 various symbolic debuggers from within Emacs. We recommend the debugger | |
249 GDB, which is free software, but you can also run DBX, SDB or XDB if you | |
250 have them. GUD can also serve as an interface to the Perl's debugging | |
251 mode, the Python debugger PDB, and to JDB, the Java Debugger. | |
252 | |
253 @menu | |
254 * Starting GUD:: How to start a debugger subprocess. | |
255 * Debugger Operation:: Connection between the debugger and source buffers. | |
256 * Commands of GUD:: Key bindings for common commands. | |
257 * GUD Customization:: Defining your own commands for GUD. | |
27223 | 258 * GUD Tooltips:: Showing variable values by pointing with the mouse. |
25829 | 259 @end menu |
260 | |
261 @node Starting GUD | |
262 @subsection Starting GUD | |
263 | |
264 There are several commands for starting a debugger, each corresponding | |
265 to a particular debugger program. | |
266 | |
267 @table @kbd | |
268 @item M-x gdb @key{RET} @var{file} @key{RET} | |
269 @findex gdb | |
270 Run GDB as a subprocess of Emacs. This command creates a buffer for | |
271 input and output to GDB, and switches to it. If a GDB buffer already | |
272 exists, it just switches to that buffer. | |
273 | |
274 @item M-x dbx @key{RET} @var{file} @key{RET} | |
275 @findex dbx | |
276 Similar, but run DBX instead of GDB. | |
277 | |
278 @item M-x xdb @key{RET} @var{file} @key{RET} | |
279 @findex xdb | |
280 @vindex gud-xdb-directories | |
281 Similar, but run XDB instead of GDB. Use the variable | |
282 @code{gud-xdb-directories} to specify directories to search for source | |
283 files. | |
284 | |
285 @item M-x sdb @key{RET} @var{file} @key{RET} | |
286 @findex sdb | |
287 Similar, but run SDB instead of GDB. | |
288 | |
289 Some versions of SDB do not mention source file names in their | |
290 messages. When you use them, you need to have a valid tags table | |
291 (@pxref{Tags}) in order for GUD to find functions in the source code. | |
292 If you have not visited a tags table or the tags table doesn't list one | |
293 of the functions, you get a message saying @samp{The sdb support | |
294 requires a valid tags table to work}. If this happens, generate a valid | |
295 tags table in the working directory and try again. | |
296 | |
297 @item M-x perldb @key{RET} @var{file} @key{RET} | |
298 @findex perldb | |
299 Run the Perl interpreter in debug mode to debug @var{file}, a Perl program. | |
300 | |
301 @item M-x jdb @key{RET} @var{file} @key{RET} | |
302 @findex jdb | |
303 Run the Java debugger to debug @var{file}. | |
304 | |
305 @item M-x pdb @key{RET} @var{file} @key{RET} | |
306 @findex pdb | |
307 Run the Python debugger to debug @var{file}. | |
308 @end table | |
309 | |
310 Each of these commands takes one argument: a command line to invoke | |
311 the debugger. In the simplest case, specify just the name of the | |
312 executable file you want to debug. You may also use options that the | |
313 debugger supports. However, shell wildcards and variables are not | |
314 allowed. GUD assumes that the first argument not starting with a | |
315 @samp{-} is the executable file name. | |
316 | |
317 Emacs can only run one debugger process at a time. | |
318 | |
319 @node Debugger Operation | |
320 @subsection Debugger Operation | |
321 | |
322 When you run a debugger with GUD, the debugger uses an Emacs buffer | |
323 for its ordinary input and output. This is called the GUD buffer. The | |
324 debugger displays the source files of the program by visiting them in | |
325 Emacs buffers. An arrow (@samp{=>}) in one of these buffers indicates | |
28431
315d6e79ea38
Overlay arrow in margin. eval-expression variables.
Dave Love <fx@gnu.org>
parents:
27223
diff
changeset
|
326 the current execution line.@footnote{Under a window system the arrow is |
315d6e79ea38
Overlay arrow in margin. eval-expression variables.
Dave Love <fx@gnu.org>
parents:
27223
diff
changeset
|
327 displayed in the marginal area of the Emacs window.} Moving point in |
315d6e79ea38
Overlay arrow in margin. eval-expression variables.
Dave Love <fx@gnu.org>
parents:
27223
diff
changeset
|
328 this buffer does not move the arrow. |
25829 | 329 |
330 You can start editing these source files at any time in the buffers | |
331 that were made to display them. The arrow is not part of the file's | |
332 text; it appears only on the screen. If you do modify a source file, | |
333 keep in mind that inserting or deleting lines will throw off the arrow's | |
334 positioning; GUD has no way of figuring out which line corresponded | |
335 before your changes to the line number in a debugger message. Also, | |
336 you'll typically have to recompile and restart the program for your | |
337 changes to be reflected in the debugger's tables. | |
338 | |
339 If you wish, you can control your debugger process entirely through the | |
340 debugger buffer, which uses a variant of Shell mode. All the usual | |
341 commands for your debugger are available, and you can use the Shell mode | |
342 history commands to repeat them. @xref{Shell Mode}. | |
343 | |
344 @node Commands of GUD | |
345 @subsection Commands of GUD | |
346 | |
347 The GUD interaction buffer uses a variant of Shell mode, so the | |
348 commands of Shell mode are available (@pxref{Shell Mode}). GUD mode | |
349 also provides commands for setting and clearing breakpoints, for | |
350 selecting stack frames, and for stepping through the program. These | |
351 commands are available both in the GUD buffer and globally, but with | |
352 different key bindings. | |
353 | |
354 The breakpoint commands are usually used in source file buffers, | |
355 because that is the way to specify where to set or clear the breakpoint. | |
356 Here's the global command to set a breakpoint: | |
357 | |
358 @table @kbd | |
359 @item C-x @key{SPC} | |
360 @kindex C-x SPC | |
361 Set a breakpoint on the source line that point is on. | |
362 @end table | |
363 | |
364 @kindex C-x C-a @r{(GUD)} | |
365 Here are the other special commands provided by GUD. The keys | |
366 starting with @kbd{C-c} are available only in the GUD interaction | |
367 buffer. The key bindings that start with @kbd{C-x C-a} are available in | |
368 the GUD interaction buffer and also in source files. | |
369 | |
370 @table @kbd | |
371 @item C-c C-l | |
372 @kindex C-c C-l @r{(GUD)} | |
373 @itemx C-x C-a C-l | |
374 @findex gud-refresh | |
375 Display in another window the last line referred to in the GUD | |
376 buffer (that is, the line indicated in the last location message). | |
377 This runs the command @code{gud-refresh}. | |
378 | |
379 @item C-c C-s | |
380 @kindex C-c C-s @r{(GUD)} | |
381 @itemx C-x C-a C-s | |
382 @findex gud-step | |
383 Execute a single line of code (@code{gud-step}). If the line contains | |
384 a function call, execution stops after entering the called function. | |
385 | |
386 @item C-c C-n | |
387 @kindex C-c C-n @r{(GUD)} | |
388 @itemx C-x C-a C-n | |
389 @findex gud-next | |
390 Execute a single line of code, stepping across entire function calls | |
391 at full speed (@code{gud-next}). | |
392 | |
393 @item C-c C-i | |
394 @kindex C-c C-i @r{(GUD)} | |
395 @itemx C-x C-a C-i | |
396 @findex gud-stepi | |
397 Execute a single machine instruction (@code{gud-stepi}). | |
398 | |
399 @need 3000 | |
400 @item C-c C-r | |
401 @kindex C-c C-r @r{(GUD)} | |
402 @itemx C-x C-a C-r | |
403 @findex gud-cont | |
404 Continue execution without specifying any stopping point. The program | |
405 will run until it hits a breakpoint, terminates, or gets a signal that | |
406 the debugger is checking for (@code{gud-cont}). | |
407 | |
408 @need 1000 | |
409 @item C-c C-d | |
410 @kindex C-c C-d @r{(GUD)} | |
411 @itemx C-x C-a C-d | |
412 @findex gud-remove | |
413 Delete the breakpoint(s) on the current source line, if any | |
414 (@code{gud-remove}). If you use this command in the GUD interaction | |
415 buffer, it applies to the line where the program last stopped. | |
416 | |
417 @item C-c C-t | |
418 @kindex C-c C-t @r{(GUD)} | |
419 @itemx C-x C-a C-t | |
420 @findex gud-tbreak | |
421 Set a temporary breakpoint on the current source line, if any. | |
422 If you use this command in the GUD interaction buffer, | |
423 it applies to the line where the program last stopped. | |
424 @end table | |
425 | |
426 The above commands are common to all supported debuggers. If you are | |
427 using GDB or (some versions of) DBX, these additional commands are available: | |
428 | |
429 @table @kbd | |
430 @item C-c < | |
431 @kindex C-c < @r{(GUD)} | |
432 @itemx C-x C-a < | |
433 @findex gud-up | |
434 Select the next enclosing stack frame (@code{gud-up}). This is | |
435 equivalent to the @samp{up} command. | |
436 | |
437 @item C-c > | |
438 @kindex C-c > @r{(GUD)} | |
439 @itemx C-x C-a > | |
440 @findex gud-down | |
441 Select the next inner stack frame (@code{gud-down}). This is | |
442 equivalent to the @samp{down} command. | |
443 @end table | |
444 | |
445 If you are using GDB, these additional key bindings are available: | |
446 | |
447 @table @kbd | |
448 @item @key{TAB} | |
449 @kindex TAB @r{(GUD)} | |
450 @findex gud-gdb-complete-command | |
451 With GDB, complete a symbol name (@code{gud-gdb-complete-command}). | |
452 This key is available only in the GUD interaction buffer, and requires | |
453 GDB versions 4.13 and later. | |
454 | |
455 @item C-c C-f | |
456 @kindex C-c C-f @r{(GUD)} | |
457 @itemx C-x C-a C-f | |
458 @findex gud-finish | |
459 Run the program until the selected stack frame returns (or until it | |
460 stops for some other reason). | |
461 @end table | |
462 | |
463 These commands interpret a numeric argument as a repeat count, when | |
464 that makes sense. | |
465 | |
466 Because @key{TAB} serves as a completion command, you can't use it to | |
467 enter a tab as input to the program you are debugging with GDB. | |
468 Instead, type @kbd{C-q @key{TAB}} to enter a tab. | |
469 | |
470 @node GUD Customization | |
471 @subsection GUD Customization | |
472 | |
473 @vindex gdb-mode-hook | |
474 @vindex dbx-mode-hook | |
475 @vindex sdb-mode-hook | |
476 @vindex xdb-mode-hook | |
477 @vindex perldb-mode-hook | |
478 @vindex pdb-mode-hook | |
479 @vindex jdb-mode-hook | |
480 On startup, GUD runs one of the following hooks: @code{gdb-mode-hook}, | |
481 if you are using GDB; @code{dbx-mode-hook}, if you are using DBX; | |
482 @code{sdb-mode-hook}, if you are using SDB; @code{xdb-mode-hook}, if you | |
483 are using XDB; @code{perldb-mode-hook}, for Perl debugging mode; | |
484 @code{jdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB. You can | |
485 use these hooks to define custom key bindings for the debugger | |
486 interaction buffer. @xref{Hooks}. | |
487 | |
488 Here is a convenient way to define a command that sends a particular | |
489 command string to the debugger, and set up a key binding for it in the | |
490 debugger interaction buffer: | |
491 | |
492 @findex gud-def | |
493 @example | |
494 (gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring}) | |
495 @end example | |
496 | |
497 This defines a command named @var{function} which sends | |
498 @var{cmdstring} to the debugger process, and gives it the documentation | |
499 string @var{docstring}. You can use the command thus defined in any | |
500 buffer. If @var{binding} is non-@code{nil}, @code{gud-def} also binds | |
501 the command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to | |
502 @kbd{C-x C-a @var{binding}} generally. | |
503 | |
504 The command string @var{cmdstring} may contain certain | |
505 @samp{%}-sequences that stand for data to be filled in at the time | |
506 @var{function} is called: | |
507 | |
508 @table @samp | |
509 @item %f | |
510 The name of the current source file. If the current buffer is the GUD | |
511 buffer, then the ``current source file'' is the file that the program | |
512 stopped in. | |
513 @c This said, ``the name of the file the program counter was in at the last breakpoint.'' | |
514 @c But I suspect it is really the last stop file. | |
515 | |
516 @item %l | |
517 The number of the current source line. If the current buffer is the GUD | |
518 buffer, then the ``current source line'' is the line that the program | |
519 stopped in. | |
520 | |
521 @item %e | |
522 The text of the C lvalue or function-call expression at or adjacent to point. | |
523 | |
524 @item %a | |
525 The text of the hexadecimal address at or adjacent to point. | |
526 | |
527 @item %p | |
528 The numeric argument of the called function, as a decimal number. If | |
529 the command is used without a numeric argument, @samp{%p} stands for the | |
530 empty string. | |
531 | |
532 If you don't use @samp{%p} in the command string, the command you define | |
533 ignores any numeric argument. | |
534 @end table | |
535 | |
27223 | 536 @node GUD Tooltips |
537 @subsection GUD Tooltips | |
538 | |
539 @cindex tooltips with GUD | |
540 The Tooltip facility (@pxref{Tooltips}) provides support for GUD@. If | |
541 GUD support is activated by customizing the @code{tooltip} group, | |
542 variable values can be displayed in tooltips by pointing at them with | |
543 the mouse in the GUD buffer or in source buffers with major modes in the | |
544 customizable list @code{tooltip-gud-modes}. | |
545 | |
25829 | 546 @node Executing Lisp |
547 @section Executing Lisp Expressions | |
548 | |
549 Emacs has several different major modes for Lisp and Scheme. They are | |
550 the same in terms of editing commands, but differ in the commands for | |
551 executing Lisp expressions. Each mode has its own purpose. | |
552 | |
553 @table @asis | |
554 @item Emacs-Lisp mode | |
555 The mode for editing source files of programs to run in Emacs Lisp. | |
556 This mode defines @kbd{C-M-x} to evaluate the current defun. | |
557 @xref{Lisp Libraries}. | |
558 @item Lisp Interaction mode | |
559 The mode for an interactive session with Emacs Lisp. It defines | |
560 @kbd{C-j} to evaluate the sexp before point and insert its value in the | |
561 buffer. @xref{Lisp Interaction}. | |
562 @item Lisp mode | |
563 The mode for editing source files of programs that run in Lisps other | |
564 than Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defun | |
565 to an inferior Lisp process. @xref{External Lisp}. | |
566 @item Inferior Lisp mode | |
567 The mode for an interactive session with an inferior Lisp process. | |
568 This mode combines the special features of Lisp mode and Shell mode | |
569 (@pxref{Shell Mode}). | |
570 @item Scheme mode | |
571 Like Lisp mode but for Scheme programs. | |
572 @item Inferior Scheme mode | |
573 The mode for an interactive session with an inferior Scheme process. | |
574 @end table | |
575 | |
576 Most editing commands for working with Lisp programs are in fact | |
577 available globally. @xref{Programs}. | |
578 | |
579 @node Lisp Libraries | |
580 @section Libraries of Lisp Code for Emacs | |
581 @cindex libraries | |
582 @cindex loading Lisp code | |
583 | |
584 Lisp code for Emacs editing commands is stored in files whose names | |
585 conventionally end in @file{.el}. This ending tells Emacs to edit them in | |
586 Emacs-Lisp mode (@pxref{Executing Lisp}). | |
587 | |
588 @findex load-file | |
589 To execute a file of Emacs Lisp code, use @kbd{M-x load-file}. This | |
590 command reads a file name using the minibuffer and then executes the | |
591 contents of that file as Lisp code. It is not necessary to visit the | |
592 file first; in any case, this command reads the file as found on disk, | |
593 not text in an Emacs buffer. | |
594 | |
595 @findex load | |
596 @findex load-library | |
597 Once a file of Lisp code is installed in the Emacs Lisp library | |
598 directories, users can load it using @kbd{M-x load-library}. Programs can | |
599 load it by calling @code{load-library}, or with @code{load}, a more primitive | |
600 function that is similar but accepts some additional arguments. | |
601 | |
602 @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it | |
603 searches a sequence of directories and tries three file names in each | |
604 directory. Suppose your argument is @var{lib}; the three names are | |
605 @file{@var{lib}.elc}, @file{@var{lib}.el}, and lastly just | |
606 @file{@var{lib}}. If @file{@var{lib}.elc} exists, it is by convention | |
607 the result of compiling @file{@var{lib}.el}; it is better to load the | |
608 compiled file, since it will load and run faster. | |
609 | |
610 If @code{load-library} finds that @file{@var{lib}.el} is newer than | |
611 @file{@var{lib}.elc} file, it prints a warning, because it's likely that | |
612 somebody made changes to the @file{.el} file and forgot to recompile | |
613 it. | |
614 | |
615 Because the argument to @code{load-library} is usually not in itself | |
616 a valid file name, file name completion is not available. Indeed, when | |
617 using this command, you usually do not know exactly what file name | |
618 will be used. | |
619 | |
620 @vindex load-path | |
621 The sequence of directories searched by @kbd{M-x load-library} is | |
622 specified by the variable @code{load-path}, a list of strings that are | |
623 directory names. The default value of the list contains the directory where | |
624 the Lisp code for Emacs itself is stored. If you have libraries of | |
625 your own, put them in a single directory and add that directory | |
626 to @code{load-path}. @code{nil} in this list stands for the current default | |
627 directory, but it is probably not a good idea to put @code{nil} in the | |
628 list. If you find yourself wishing that @code{nil} were in the list, | |
629 most likely what you really want to do is use @kbd{M-x load-file} | |
630 this once. | |
631 | |
632 @cindex autoload | |
633 Often you do not have to give any command to load a library, because | |
634 the commands defined in the library are set up to @dfn{autoload} that | |
635 library. Trying to run any of those commands calls @code{load} to load | |
636 the library; this replaces the autoload definitions with the real ones | |
637 from the library. | |
638 | |
639 @cindex byte code | |
640 Emacs Lisp code can be compiled into byte-code which loads faster, | |
641 takes up less space when loaded, and executes faster. @xref{Byte | |
642 Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual}. | |
643 By convention, the compiled code for a library goes in a separate file | |
644 whose name consists of the library source file with @samp{c} appended. | |
645 Thus, the compiled code for @file{foo.el} goes in @file{foo.elc}. | |
646 That's why @code{load-library} searches for @samp{.elc} files first. | |
647 | |
31027
561ef681eab5
Document load-dangerous-libraries.
Eli Zaretskii <eliz@gnu.org>
parents:
28431
diff
changeset
|
648 @vindex load-dangerous-libraries |
561ef681eab5
Document load-dangerous-libraries.
Eli Zaretskii <eliz@gnu.org>
parents:
28431
diff
changeset
|
649 @cindex Lisp files byte-compiled by XEmacs |
561ef681eab5
Document load-dangerous-libraries.
Eli Zaretskii <eliz@gnu.org>
parents:
28431
diff
changeset
|
650 By default, Emacs refuses to load compiled Lisp files which weren't |
561ef681eab5
Document load-dangerous-libraries.
Eli Zaretskii <eliz@gnu.org>
parents:
28431
diff
changeset
|
651 compiled with Emacs. This is because an incompatible change was |
561ef681eab5
Document load-dangerous-libraries.
Eli Zaretskii <eliz@gnu.org>
parents:
28431
diff
changeset
|
652 introduced into XEmacs' byte compiler, which could produce files with |
561ef681eab5
Document load-dangerous-libraries.
Eli Zaretskii <eliz@gnu.org>
parents:
28431
diff
changeset
|
653 byte codes that cause Emacs to crash. Set the variable |
561ef681eab5
Document load-dangerous-libraries.
Eli Zaretskii <eliz@gnu.org>
parents:
28431
diff
changeset
|
654 @code{load-dangerous-libraries} to t if you want to change this |
561ef681eab5
Document load-dangerous-libraries.
Eli Zaretskii <eliz@gnu.org>
parents:
28431
diff
changeset
|
655 behavior. |
561ef681eab5
Document load-dangerous-libraries.
Eli Zaretskii <eliz@gnu.org>
parents:
28431
diff
changeset
|
656 |
25829 | 657 @node Lisp Eval |
658 @section Evaluating Emacs-Lisp Expressions | |
659 @cindex Emacs-Lisp mode | |
660 @cindex mode, Emacs-Lisp | |
661 | |
662 @findex emacs-lisp-mode | |
663 Lisp programs intended to be run in Emacs should be edited in | |
664 Emacs-Lisp mode; this happens automatically for file names ending in | |
665 @file{.el}. By contrast, Lisp mode itself is used for editing Lisp | |
666 programs intended for other Lisp systems. To switch to Emacs-Lisp mode | |
667 explicitly, use the command @kbd{M-x emacs-lisp-mode}. | |
668 | |
669 For testing of Lisp programs to run in Emacs, it is often useful to | |
670 evaluate part of the program as it is found in the Emacs buffer. For | |
671 example, after changing the text of a Lisp function definition, | |
672 evaluating the definition installs the change for future calls to the | |
673 function. Evaluation of Lisp expressions is also useful in any kind of | |
674 editing, for invoking noninteractive functions (functions that are | |
675 not commands). | |
676 | |
677 @table @kbd | |
678 @item M-: | |
679 Read a single Lisp expression in the minibuffer, evaluate it, and print | |
680 the value in the echo area (@code{eval-expression}). | |
681 @item C-x C-e | |
682 Evaluate the Lisp expression before point, and print the value in the | |
683 echo area (@code{eval-last-sexp}). | |
684 @item C-M-x | |
685 Evaluate the defun containing or after point, and print the value in | |
686 the echo area (@code{eval-defun}). | |
687 @item M-x eval-region | |
688 Evaluate all the Lisp expressions in the region. | |
689 @item M-x eval-current-buffer | |
690 Evaluate all the Lisp expressions in the buffer. | |
691 @end table | |
692 | |
693 @kindex M-: | |
694 @findex eval-expression | |
695 @kbd{M-:} (@code{eval-expression}) is the most basic command for evaluating | |
696 a Lisp expression interactively. It reads the expression using the | |
697 minibuffer, so you can execute any expression on a buffer regardless of | |
698 what the buffer contains. When the expression is evaluated, the current | |
699 buffer is once again the buffer that was current when @kbd{M-:} was | |
700 typed. | |
701 | |
702 @kindex C-M-x @r{(Emacs-Lisp mode)} | |
703 @findex eval-defun | |
704 In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the command | |
705 @code{eval-defun}, which parses the defun containing or following point | |
706 as a Lisp expression and evaluates it. The value is printed in the echo | |
707 area. This command is convenient for installing in the Lisp environment | |
708 changes that you have just made in the text of a function definition. | |
709 | |
710 @kbd{C-M-x} treats @code{defvar} expressions specially. Normally, | |
711 evaluating a @code{defvar} expression does nothing if the variable it | |
712 defines already has a value. But @kbd{C-M-x} unconditionally resets the | |
713 variable to the initial value specified in the @code{defvar} expression. | |
28431
315d6e79ea38
Overlay arrow in margin. eval-expression variables.
Dave Love <fx@gnu.org>
parents:
27223
diff
changeset
|
714 @code{defcustom} expressions are treated similarly. |
25829 | 715 This special feature is convenient for debugging Lisp programs. |
716 | |
717 @kindex C-x C-e | |
718 @findex eval-last-sexp | |
719 The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Lisp | |
720 expression preceding point in the buffer, and displays the value in the | |
721 echo area. It is available in all major modes, not just Emacs-Lisp | |
722 mode. It does not treat @code{defvar} specially. | |
723 | |
724 If @kbd{C-M-x}, @kbd{C-x C-e}, or @kbd{M-:} is given a numeric | |
725 argument, it inserts the value into the current buffer at point, rather | |
726 than displaying it in the echo area. The argument's value does not | |
727 matter. | |
728 | |
729 @findex eval-region | |
730 @findex eval-current-buffer | |
731 The most general command for evaluating Lisp expressions from a buffer | |
732 is @code{eval-region}. @kbd{M-x eval-region} parses the text of the | |
733 region as one or more Lisp expressions, evaluating them one by one. | |
734 @kbd{M-x eval-current-buffer} is similar but evaluates the entire | |
735 buffer. This is a reasonable way to install the contents of a file of | |
736 Lisp code that you are just ready to test. Later, as you find bugs and | |
737 change individual functions, use @kbd{C-M-x} on each function that you | |
738 change. This keeps the Lisp world in step with the source file. | |
739 | |
28431
315d6e79ea38
Overlay arrow in margin. eval-expression variables.
Dave Love <fx@gnu.org>
parents:
27223
diff
changeset
|
740 @vindex eval-expression-print-level |
315d6e79ea38
Overlay arrow in margin. eval-expression variables.
Dave Love <fx@gnu.org>
parents:
27223
diff
changeset
|
741 @vindex eval-expression-print-length |
315d6e79ea38
Overlay arrow in margin. eval-expression variables.
Dave Love <fx@gnu.org>
parents:
27223
diff
changeset
|
742 @vindex eval-expression-debug-on-error |
315d6e79ea38
Overlay arrow in margin. eval-expression variables.
Dave Love <fx@gnu.org>
parents:
27223
diff
changeset
|
743 The customizable variables @code{eval-expression-print-level} and |
315d6e79ea38
Overlay arrow in margin. eval-expression variables.
Dave Love <fx@gnu.org>
parents:
27223
diff
changeset
|
744 @code{eval-expression-print-length} control the maximum depth and length |
315d6e79ea38
Overlay arrow in margin. eval-expression variables.
Dave Love <fx@gnu.org>
parents:
27223
diff
changeset
|
745 of lists to print in the result of the evaluation commands before |
315d6e79ea38
Overlay arrow in margin. eval-expression variables.
Dave Love <fx@gnu.org>
parents:
27223
diff
changeset
|
746 abbreviating them. @code{eval-expression-debug-on-error} controls |
315d6e79ea38
Overlay arrow in margin. eval-expression variables.
Dave Love <fx@gnu.org>
parents:
27223
diff
changeset
|
747 whether evaluation errors invoke the debugger when these commands are |
315d6e79ea38
Overlay arrow in margin. eval-expression variables.
Dave Love <fx@gnu.org>
parents:
27223
diff
changeset
|
748 used. |
315d6e79ea38
Overlay arrow in margin. eval-expression variables.
Dave Love <fx@gnu.org>
parents:
27223
diff
changeset
|
749 |
25829 | 750 @node Lisp Interaction |
751 @section Lisp Interaction Buffers | |
752 | |
753 The buffer @samp{*scratch*} which is selected when Emacs starts up is | |
754 provided for evaluating Lisp expressions interactively inside Emacs. | |
755 | |
756 The simplest way to use the @samp{*scratch*} buffer is to insert Lisp | |
757 expressions and type @kbd{C-j} after each expression. This command | |
758 reads the Lisp expression before point, evaluates it, and inserts the | |
759 value in printed representation before point. The result is a complete | |
760 typescript of the expressions you have evaluated and their values. | |
761 | |
762 The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which | |
763 is the same as Emacs-Lisp mode except for the binding of @kbd{C-j}. | |
764 | |
765 @findex lisp-interaction-mode | |
766 The rationale for this feature is that Emacs must have a buffer when | |
767 it starts up, but that buffer is not useful for editing files since a | |
768 new buffer is made for every file that you visit. The Lisp interpreter | |
769 typescript is the most useful thing I can think of for the initial | |
770 buffer to do. Type @kbd{M-x lisp-interaction-mode} to put the current | |
771 buffer in Lisp Interaction mode. | |
772 | |
773 @findex ielm | |
774 An alternative way of evaluating Emacs Lisp expressions interactively | |
775 is to use Inferior Emacs-Lisp mode, which provides an interface rather | |
776 like Shell mode (@pxref{Shell Mode}) for evaluating Emacs Lisp | |
777 expressions. Type @kbd{M-x ielm} to create an @samp{*ielm*} buffer | |
778 which uses this mode. | |
779 | |
780 @node External Lisp | |
781 @section Running an External Lisp | |
782 | |
783 Emacs has facilities for running programs in other Lisp systems. You can | |
784 run a Lisp process as an inferior of Emacs, and pass expressions to it to | |
785 be evaluated. You can also pass changed function definitions directly from | |
786 the Emacs buffers in which you edit the Lisp programs to the inferior Lisp | |
787 process. | |
788 | |
789 @findex run-lisp | |
790 @vindex inferior-lisp-program | |
791 @kindex C-x C-z | |
792 To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runs | |
793 the program named @code{lisp}, the same program you would run by typing | |
794 @code{lisp} as a shell command, with both input and output going through | |
795 an Emacs buffer named @samp{*lisp*}. That is to say, any ``terminal | |
796 output'' from Lisp will go into the buffer, advancing point, and any | |
797 ``terminal input'' for Lisp comes from text in the buffer. (You can | |
798 change the name of the Lisp executable file by setting the variable | |
799 @code{inferior-lisp-program}.) | |
800 | |
801 To give input to Lisp, go to the end of the buffer and type the input, | |
802 terminated by @key{RET}. The @samp{*lisp*} buffer is in Inferior Lisp | |
803 mode, which combines the special characteristics of Lisp mode with most | |
804 of the features of Shell mode (@pxref{Shell Mode}). The definition of | |
805 @key{RET} to send a line to a subprocess is one of the features of Shell | |
806 mode. | |
807 | |
808 @findex lisp-mode | |
809 For the source files of programs to run in external Lisps, use Lisp | |
810 mode. This mode can be selected with @kbd{M-x lisp-mode}, and is used | |
811 automatically for files whose names end in @file{.l}, @file{.lsp}, or | |
812 @file{.lisp}, as most Lisp systems usually expect. | |
813 | |
814 @kindex C-M-x @r{(Lisp mode)} | |
815 @findex lisp-eval-defun | |
816 When you edit a function in a Lisp program you are running, the easiest | |
817 way to send the changed definition to the inferior Lisp process is the key | |
818 @kbd{C-M-x}. In Lisp mode, this runs the function @code{lisp-eval-defun}, | |
819 which finds the defun around or following point and sends it as input to | |
820 the Lisp process. (Emacs can send input to any inferior process regardless | |
821 of what buffer is current.) | |
822 | |
823 Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing programs | |
824 to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp | |
825 programs to be run in Emacs): in both modes it has the effect of installing | |
826 the function definition that point is in, but the way of doing so is | |
827 different according to where the relevant Lisp environment is found. | |
828 @xref{Executing Lisp}. |