* building.texi (Lisp Libraries): Add example of changing
[bpt/emacs.git] / doc / emacs / building.texi
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
3 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Building, Maintaining, Programs, Top
6 @chapter Compiling and Testing Programs
7 @cindex building programs
8 @cindex program building
9 @cindex running Lisp functions
10
11 The previous chapter discusses the Emacs commands that are useful for
12 making changes in programs. This chapter deals with commands that assist
13 in the larger process of compiling and testing programs.
14
15 @menu
16 * Compilation:: Compiling programs in languages other
17 than Lisp (C, Pascal, etc.).
18 * Compilation Mode:: The mode for visiting compiler errors.
19 * Compilation Shell:: Customizing your shell properly
20 for use in the compilation buffer.
21 * Grep Searching:: Searching with grep.
22 * Flymake:: Finding syntax errors on the fly.
23 * Debuggers:: Running symbolic debuggers for non-Lisp programs.
24 * Executing Lisp:: Various modes for editing Lisp programs,
25 with different facilities for running
26 the Lisp programs.
27 * Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs.
28 * Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
29 * Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
30 * External Lisp:: Communicating through Emacs with a separate Lisp.
31 @end menu
32
33 @node Compilation
34 @section Running Compilations under Emacs
35 @cindex inferior process
36 @cindex make
37 @cindex compilation errors
38 @cindex error log
39
40 Emacs can run compilers for noninteractive languages such as C and
41 Fortran as inferior processes, feeding the error log into an Emacs buffer.
42 It can also parse the error messages and show you the source lines where
43 compilation errors occurred.
44
45 @table @kbd
46 @item M-x compile
47 Run a compiler asynchronously under Emacs, with error messages going to
48 the @samp{*compilation*} buffer.
49 @item M-x recompile
50 Invoke a compiler with the same command as in the last invocation of
51 @kbd{M-x compile}.
52 @item M-x kill-compilation
53 Kill the running compilation subprocess.
54 @end table
55
56 @findex compile
57 To run @code{make} or another compilation command, do @kbd{M-x
58 compile}. This command reads a shell command line using the minibuffer,
59 and then executes the command in an inferior shell, putting output in
60 the buffer named @samp{*compilation*}. The current buffer's default
61 directory is used as the working directory for the execution of the
62 command; normally, therefore, the compilation happens in this
63 directory.
64
65 @vindex compile-command
66 The default for the compilation command is normally @samp{make -k},
67 which is correct most of the time for nontrivial programs.
68 @xref{Top,, Make, make, GNU Make Manual}. If you have done @kbd{M-x
69 compile} before, the default each time is the command you used the
70 previous time. @code{compile} stores this command in the variable
71 @code{compile-command}, so setting that variable specifies the default
72 for the next use of @kbd{M-x compile}. If a file specifies a file
73 local value for @code{compile-command}, that provides the default when
74 you type @kbd{M-x compile} in that file's buffer. @xref{File
75 Variables}.
76
77 Starting a compilation displays the buffer @samp{*compilation*} in
78 another window but does not select it. The buffer's mode line tells
79 you whether compilation is finished, with the word @samp{run},
80 @samp{signal} or @samp{exit} inside the parentheses. You do not have
81 to keep this buffer visible; compilation continues in any case. While
82 a compilation is going on, the string @samp{Compiling} appears in the
83 mode lines of all windows. When this string disappears, the
84 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 @cindex compilation buffer, keeping point at end
94 @vindex compilation-scroll-output
95 If you change the variable @code{compilation-scroll-output} to a
96 non-@code{nil} value, the compilation buffer will scroll automatically
97 to follow the output as it comes in. If the value is
98 @code{first-error}, the scrolling stops at the first error that
99 appears, leaving point at that error. For any other non-@code{nil}
100 value, the buffer continues scrolling until there is no more output.
101
102 @findex recompile
103 To rerun the last compilation with the same command, type @kbd{M-x
104 recompile}. This automatically reuses the compilation command from
105 the last invocation of @kbd{M-x compile}. It also reuses the
106 @samp{*compilation*} buffer and starts the compilation in its default
107 directory, which is the directory in which the previous compilation
108 was started.
109
110 When the compiler process terminates, for whatever reason, the mode
111 line of the @samp{*compilation*} buffer changes to say @samp{exit}
112 (followed by the exit code, @samp{[0]} for a normal exit), or
113 @samp{signal} (if a signal terminated the process), instead of
114 @samp{run}.
115
116 @findex kill-compilation
117 Starting a new compilation also kills any compilation already
118 running in @samp{*compilation*}, as the buffer can only handle one
119 compilation at any time. However, @kbd{M-x compile} asks for
120 confirmation before actually killing a compilation that is running.
121 You can also kill the compilation process with @kbd{M-x
122 kill-compilation}.
123
124 If you want to run two compilations at once, you should start the
125 first one, then rename the @samp{*compilation*} buffer (perhaps using
126 @code{rename-uniquely}; @pxref{Misc Buffer}), and start the other
127 compilation. That will create a new @samp{*compilation*} buffer.
128
129 Emacs does not expect a compiler process to launch asynchronous
130 subprocesses; if it does, and they keep running after the main
131 compiler process has terminated, Emacs may kill them or their output
132 may not arrive in Emacs. To avoid this problem, make the main process
133 wait for its subprocesses to finish. In a shell script, you can do this
134 using @samp{$!} and @samp{wait}, like this:
135
136 @example
137 (sleep 10; echo 2nd)& pid=$! # @r{Record pid of subprocess}
138 echo first message
139 wait $pid # @r{Wait for subprocess}
140 @end example
141
142 If the background process does not output to the compilation buffer,
143 so you only need to prevent it from being killed when the main
144 compilation process terminates, this is sufficient:
145
146 @example
147 nohup @var{command}; sleep 1
148 @end example
149
150 @vindex compilation-environment
151 You can control the environment passed to the compilation command
152 with the variable @code{compilation-environment}. Its value is a list
153 of environment variable settings; each element should be a string of
154 the form @code{"@var{envvarname}=@var{value}"}. These environment
155 variable settings override the usual ones.
156
157 @node Compilation Mode
158 @section Compilation Mode
159
160 @cindex Compilation mode
161 @cindex mode, Compilation
162 The @samp{*compilation*} buffer uses a special major mode,
163 Compilation mode, whose main feature is to provide a convenient way to
164 visit the source line corresponding to an error message. These
165 commands are also available in other special buffers that list
166 locations in files, including those made by @kbd{M-x grep} and
167 @kbd{M-x occur}.
168
169 @table @kbd
170 @item M-g M-n
171 @itemx M-g n
172 @itemx C-x `
173 Visit the locus of the next error message or match.
174 @item M-g M-p
175 @itemx M-g p
176 Visit the locus of the previous error message or match.
177 @item @key{RET}
178 Visit the locus of the error message that point is on.
179 This command is used in the compilation buffer.
180 @item Mouse-2
181 Visit the locus of the error message that you click on.
182 @item M-n
183 Find and highlight the locus of the next error message, without
184 selecting the source buffer.
185 @item M-p
186 Find and highlight the locus of the previous error message, without
187 selecting the source buffer.
188 @item M-@}
189 Move point to the next error for a different file than the current
190 one.
191 @item M-@{
192 Move point to the previous error for a different file than the current
193 one.
194 @item C-c C-f
195 Toggle Next Error Follow minor mode, which makes cursor motion in the
196 compilation buffer produce automatic source display.
197 @end table
198
199 @findex compile-goto-error
200 @vindex compilation-auto-jump-to-first-error
201 You can visit the source for any particular error message by moving
202 point in the @samp{*compilation*} buffer to that error message and
203 typing @key{RET} (@code{compile-goto-error}). Alternatively, you can
204 click @kbd{Mouse-2} on the error message; you need not switch to the
205 @samp{*compilation*} buffer first. If you set the variable
206 @code{compilation-auto-jump-to-first-error} to a non-@code{nil} value,
207 Emacs automatically jumps to the first error, if any, as soon as it
208 appears in the @samp{*compilation*} buffer.
209
210 @kindex M-g M-n
211 @kindex M-g n
212 @kindex C-x `
213 @findex next-error
214 @vindex next-error-highlight
215 To parse the compiler error messages sequentially, type @kbd{C-x `}
216 (@code{next-error}). The character following the @kbd{C-x} is the
217 backquote or ``grave accent,'' not the single-quote. This command is
218 available in all buffers, not just in @samp{*compilation*}; it
219 displays the next error message at the top of one window and source
220 location of the error in another window. It also temporarily
221 highlights the relevant source line, for a period controlled by the
222 variable @code{next-error-highlight}.
223
224 The first time @w{@kbd{C-x `}} is used after the start of a compilation,
225 it moves to the first error's location. Subsequent uses of @kbd{C-x
226 `} advance down to subsequent errors. If you visit a specific error
227 message with @key{RET} or @kbd{Mouse-2}, subsequent @w{@kbd{C-x `}}
228 commands advance from there. When @w{@kbd{C-x `}} gets to the end of the
229 buffer and finds no more error messages to visit, it fails and signals
230 an Emacs error. @w{@kbd{C-u C-x `}} starts scanning from the beginning of
231 the compilation buffer, and goes to the first error's location.
232
233 @vindex compilation-skip-threshold
234 By default, @w{@kbd{C-x `}} skips less important messages. The variable
235 @code{compilation-skip-threshold} controls this. If its value is 2,
236 @w{@kbd{C-x `}} skips anything less than error, 1 skips anything less
237 than warning, and 0 doesn't skip any messages. The default is 1.
238
239 When the window has a left fringe, an arrow in the fringe points to
240 the current message in the compilation buffer. The variable
241 @code{compilation-context-lines} controls the number of lines of
242 leading context to display before the current message. Going to an
243 error message location scrolls the @samp{*compilation*} buffer to put
244 the message that far down from the top. The value @code{nil} is
245 special: if there's a left fringe, the window doesn't scroll at all
246 if the message is already visible. If there is no left fringe,
247 @code{nil} means display the message at the top of the window.
248
249 If you're not in the compilation buffer when you run
250 @code{next-error}, Emacs will look for a buffer that contains error
251 messages. First, it looks for one displayed in the selected frame,
252 then for one that previously had @code{next-error} called on it, and
253 then at the current buffer. Finally, Emacs looks at all the remaining
254 buffers. @code{next-error} signals an error if it can't find any such
255 buffer.
256
257 @vindex compilation-error-regexp-alist
258 @vindex grep-regexp-alist
259 To parse messages from the compiler, Compilation mode uses the
260 variable @code{compilation-error-regexp-alist} which lists various
261 formats of error messages and tells Emacs how to extract the source file
262 and the line number from the text of a message. If your compiler isn't
263 supported, you can tailor Compilation mode to it by adding elements to
264 that list. A similar variable @code{grep-regexp-alist} tells Emacs how
265 to parse output of a @code{grep} command.
266
267 @findex compilation-next-error
268 @findex compilation-previous-error
269 @findex compilation-next-file
270 @findex compilation-previous-file
271 Compilation mode also redefines the keys @key{SPC} and @key{DEL} to
272 scroll by screenfuls, and @kbd{M-n} (@code{compilation-next-error})
273 and @kbd{M-p} (@code{compilation-previous-error}) to move to the next
274 or previous error message. You can also use @kbd{M-@{}
275 (@code{compilation-next-file} and @kbd{M-@}}
276 (@code{compilation-previous-file}) to move up or down to an error
277 message for a different source file.
278
279 @cindex Next Error Follow mode
280 @findex next-error-follow-minor-mode
281 You can type @kbd{C-c C-f} to toggle Next Error Follow mode. In
282 this minor mode, ordinary cursor motion in the compilation buffer
283 automatically updates the source buffer. For instance, moving the
284 cursor to the next error message causes the location of that error to
285 be displayed immediately.
286
287 The features of Compilation mode are also available in a minor mode
288 called Compilation Minor mode. This lets you parse error messages in
289 any buffer, not just a normal compilation output buffer. Type @kbd{M-x
290 compilation-minor-mode} to enable the minor mode. This defines the keys
291 @key{RET} and @kbd{Mouse-2}, as in the Compilation major mode.
292
293 Compilation minor mode works in any buffer, as long as the contents
294 are in a format that it understands. In an Rlogin buffer (@pxref{Remote
295 Host}), Compilation minor mode automatically accesses remote source
296 files by FTP (@pxref{File Names}).
297
298 @node Compilation Shell
299 @section Subshells for Compilation
300
301 Emacs uses a shell to run the compilation command, but specifies the
302 option for a noninteractive shell. This means, in particular, that
303 the shell should start with no prompt. If you find your usual shell
304 prompt making an unsightly appearance in the @samp{*compilation*}
305 buffer, it means you have made a mistake in your shell's init file by
306 setting the prompt unconditionally. (This init file's name may be
307 @file{.bashrc}, @file{.profile}, @file{.cshrc}, @file{.shrc}, or
308 various other things, depending on the shell you use.) The shell init
309 file should set the prompt only if there already is a prompt. Here's
310 how to do it in bash:
311
312 @example
313 if [ "$@{PS1+set@}" = set ]
314 then PS1=@dots{}
315 fi
316 @end example
317
318 @noindent
319 And here's how to do it in csh:
320
321 @example
322 if ($?prompt) set prompt = @dots{}
323 @end example
324
325 There may well be other things that your shell's init file
326 ought to do only for an interactive shell. You can use the same
327 method to conditionalize them.
328
329 The MS-DOS ``operating system'' does not support asynchronous
330 subprocesses; to work around this lack, @kbd{M-x compile} runs the
331 compilation command synchronously on MS-DOS. As a consequence, you must
332 wait until the command finishes before you can do anything else in
333 Emacs.
334 @iftex
335 @inforef{MS-DOS,,emacs-xtra}.
336 @end iftex
337 @ifnottex
338 @xref{MS-DOS}.
339 @end ifnottex
340
341 @node Grep Searching
342 @section Searching with Grep under Emacs
343
344 Just as you can run a compiler from Emacs and then visit the lines
345 with compilation errors, you can also run @code{grep} and then visit
346 the lines on which matches were found. This works by treating the
347 matches reported by @code{grep} as if they were ``errors.'' The
348 buffer of matches uses Grep mode, which is a variant of Compilation
349 mode (@pxref{Compilation Mode}).
350
351 @table @kbd
352 @item M-x grep
353 @itemx M-x lgrep
354 Run @code{grep} asynchronously under Emacs, with matching lines
355 listed in the buffer named @samp{*grep*}.
356 @item M-x grep-find
357 @itemx M-x find-grep
358 @itemx M-x rgrep
359 Run @code{grep} via @code{find}, with user-specified arguments, and
360 collect output in the buffer named @samp{*grep*}.
361 @item M-x kill-grep
362 Kill the running @code{grep} subprocess.
363 @end table
364
365 @findex grep
366 To run @code{grep}, type @kbd{M-x grep}, then enter a command line
367 that specifies how to run @code{grep}. Use the same arguments you
368 would give @code{grep} when running it normally: a @code{grep}-style
369 regexp (usually in single-quotes to quote the shell's special
370 characters) followed by file names, which may use wildcards. If you
371 specify a prefix argument for @kbd{M-x grep}, it finds the tag
372 (@pxref{Tags}) in the buffer around point, and puts that into the
373 default @code{grep} command.
374
375 Your command need not simply run @code{grep}; you can use any shell
376 command that produces output in the same format. For instance, you
377 can chain @code{grep} commands, like this:
378
379 @example
380 grep -nH -e foo *.el | grep bar | grep toto
381 @end example
382
383 The output from @code{grep} goes in the @samp{*grep*} buffer. You
384 can find the corresponding lines in the original files using @w{@kbd{C-x
385 `}}, @key{RET}, and so forth, just like compilation errors.
386
387 Some grep programs accept a @samp{--color} option to output special
388 markers around matches for the purpose of highlighting. You can make
389 use of this feature by setting @code{grep-highlight-matches} to
390 @code{t}. When displaying a match in the source buffer, the exact
391 match will be highlighted, instead of the entire source line.
392
393 @findex grep-find
394 @findex find-grep
395 The command @kbd{M-x grep-find} (also available as @kbd{M-x
396 find-grep}) is similar to @kbd{M-x grep}, but it supplies a different
397 initial default for the command---one that runs both @code{find} and
398 @code{grep}, so as to search every file in a directory tree. See also
399 the @code{find-grep-dired} command, in @ref{Dired and Find}.
400
401 @findex lgrep
402 @findex rgrep
403 The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep}
404 (recursive grep) are more user-friendly versions of @code{grep} and
405 @code{grep-find}, which prompt separately for the regular expression
406 to match, the files to search, and the base directory for the search.
407 Case sensitivity of the search is controlled by the
408 current value of @code{case-fold-search}.
409
410 These commands build the shell commands based on the variables
411 @code{grep-template} (for @code{lgrep}) and @code{grep-find-template}
412 (for @code{rgrep}).
413
414 The files to search can use aliases defined in the variable
415 @code{grep-files-aliases}.
416
417 Subdirectories listed in the variable
418 @code{grep-find-ignored-directories} such as those typically used by
419 various version control systems, like CVS and arch, are automatically
420 skipped by @code{rgrep}.
421
422 @node Flymake
423 @section Finding Syntax Errors On The Fly
424 @cindex checking syntax
425
426 Flymake mode is a minor mode that performs on-the-fly syntax
427 checking for many programming and markup languages, including C, C++,
428 Perl, HTML, and @TeX{}/La@TeX{}. It is somewhat analogous to Flyspell
429 mode, which performs spell checking for ordinary human languages in a
430 similar fashion (@pxref{Spelling}). As you edit a file, Flymake mode
431 runs an appropriate syntax checking tool in the background, using a
432 temporary copy of the buffer. It then parses the error and warning
433 messages, and highlights the erroneous lines in the buffer. The
434 syntax checking tool used depends on the language; for example, for
435 C/C++ files this is usually the C compiler. Flymake can also use
436 build tools such as @code{make} for checking complicated projects.
437
438 To activate Flymake mode, type @kbd{M-x flymake-mode}. You can move
439 to the errors spotted by Flymake mode with @kbd{M-x
440 flymake-goto-next-error} and @kbd{M-x flymake-goto-prev-error}. To
441 display any error messages associated with the current line, use
442 @kbd{M-x flymake-display-err-menu-for-current-line}.
443
444 For more details about using Flymake, see @ref{Top, Flymake,
445 Flymake, flymake, The Flymake Manual}.
446
447 @node Debuggers
448 @section Running Debuggers Under Emacs
449 @cindex debuggers
450 @cindex GUD library
451 @cindex GDB
452 @cindex DBX
453 @cindex SDB
454 @cindex XDB
455 @cindex Perldb
456 @cindex JDB
457 @cindex PDB
458
459 @c Do you believe in GUD?
460 The GUD (Grand Unified Debugger) library provides an Emacs interface
461 to a wide variety of symbolic debuggers. Unlike the GDB graphical
462 interface, which only runs GDB (@pxref{GDB Graphical Interface}), GUD
463 can also run DBX, SDB, XDB, Perl's debugging mode, the Python debugger
464 PDB, or the Java Debugger JDB.
465
466 In addition, Emacs contains a built-in system for debugging Emacs
467 Lisp programs. @xref{Debugging,, The Lisp Debugger, elisp, the Emacs
468 Lisp Reference Manual}, for information on the Emacs Lisp debugger.
469
470 @menu
471 * Starting GUD:: How to start a debugger subprocess.
472 * Debugger Operation:: Connection between the debugger and source buffers.
473 * Commands of GUD:: Key bindings for common commands.
474 * GUD Customization:: Defining your own commands for GUD.
475 * GDB Graphical Interface:: An enhanced mode that uses GDB features to
476 implement a graphical debugging environment through
477 Emacs.
478 @end menu
479
480 @node Starting GUD
481 @subsection Starting GUD
482
483 There are several commands for starting a debugger under GUD, each
484 corresponding to a particular debugger program.
485
486 @table @kbd
487 @item M-x gdb @key{RET} @var{file} @key{RET}
488 @findex gdb
489 Run GDB as a subprocess of Emacs. This uses an IDE-like graphical
490 interface; see @ref{GDB Graphical Interface}. Only GDB works with the
491 graphical interface.
492
493 @item M-x gud-gdb @key{RET} @var{file} @key{RET}
494 @findex gud-gdb
495 Run GDB as a subprocess of Emacs. This command creates a buffer for
496 input and output to GDB, and switches to it. If a GDB buffer already
497 exists, it just switches to that buffer.
498
499 @item M-x dbx @key{RET} @var{file} @key{RET}
500 @findex dbx
501 Run DBX as a subprocess of Emacs. Since Emacs does not implement a
502 graphical interface for DBX, communication with DBX works by typing
503 commands in the GUD interaction buffer. The same is true for all
504 the other supported debuggers.
505
506 @item M-x xdb @key{RET} @var{file} @key{RET}
507 @findex xdb
508 @vindex gud-xdb-directories
509 Run XDB as a subprocess of Emacs. Use the variable
510 @code{gud-xdb-directories} to specify directories to search for source
511 files.
512
513 @item M-x sdb @key{RET} @var{file} @key{RET}
514 @findex sdb
515 Run SDB as a subprocess of Emacs.
516
517 Some versions of SDB do not mention source file names in their
518 messages. When you use them, you need to have a valid tags table
519 (@pxref{Tags}) in order for GUD to find functions in the source code.
520 If you have not visited a tags table or the tags table doesn't list
521 one of the functions, you get a message saying @samp{The sdb support
522 requires a valid tags table to work}. If this happens, generate a
523 valid tags table in the working directory and try again.
524
525 @item M-x perldb @key{RET} @var{file} @key{RET}
526 @findex perldb
527 Run the Perl interpreter in debug mode to debug @var{file}, a Perl program.
528
529 @item M-x jdb @key{RET} @var{file} @key{RET}
530 @findex jdb
531 Run the Java debugger to debug @var{file}.
532
533 @item M-x pdb @key{RET} @var{file} @key{RET}
534 @findex pdb
535 Run the Python debugger to debug @var{file}.
536 @end table
537
538 Each of these commands takes one argument: a command line to invoke
539 the debugger. In the simplest case, specify just the name of the
540 executable file you want to debug. You may also use options that the
541 debugger supports. However, shell wildcards and variables are not
542 allowed. GUD assumes that the first argument not starting with a
543 @samp{-} is the executable file name.
544
545 @cindex remote host, debugging on
546 Tramp provides a facility to debug programs on remote hosts
547 (@pxref{Running a debugger on a remote host, Running a debugger on a
548 remote host,, tramp, The Tramp Manual}), whereby both the debugger and
549 the program being debugged are on the same remote host. This should
550 not be confused with debugging programs remotely, where the program
551 and the debugger run on different machines, as can be done using the
552 GDB remote debugging feature, for example (@pxref{Remote Debugging,,
553 Debugging Remote Programs, gdb, The GNU debugger}).
554
555 @node Debugger Operation
556 @subsection Debugger Operation
557
558 @cindex fringes, and current execution line in GUD
559 Generally when you run a debugger with GUD, the debugger uses an Emacs
560 buffer for its ordinary input and output. This is called the GUD
561 buffer. Input and output from the program you are debugging also use
562 this buffer. We call this @dfn{text command mode}. The GDB Graphical
563 Interface can use further buffers (@pxref{GDB Graphical Interface}).
564
565 The debugger displays the source files of the program by visiting
566 them in Emacs buffers. An arrow in the left fringe indicates the
567 current execution line.@footnote{On a text-only terminal, the arrow
568 appears as @samp{=>} and overlays the first two text columns.} Moving
569 point in this buffer does not move the arrow. The arrow is not part
570 of the file's text; it appears only on the screen.
571
572 You can start editing these source files at any time in the buffers
573 that display them. If you do modify a source file, keep in mind that
574 inserting or deleting lines will throw off the arrow's positioning;
575 GUD has no way of figuring out which line corresponded before your
576 changes to the line number in a debugger message. Also, you'll
577 typically have to recompile and restart the program for your changes
578 to be reflected in the debugger's tables.
579
580 @cindex tooltips with GUD
581 @vindex tooltip-gud-modes
582 @vindex gud-tooltip-mode
583 @vindex gud-tooltip-echo-area
584 The Tooltip facility (@pxref{Tooltips}) provides support for GUD@.
585 You activate this feature by turning on the minor mode
586 @code{gud-tooltip-mode}. Then you can display a variable's value in a
587 tooltip simply by pointing at it with the mouse. This operates in the
588 GUD buffer and in source buffers with major modes in the list
589 @code{gud-tooltip-modes}. If the variable @code{gud-tooltip-echo-area}
590 is non-@code{nil} then the variable's value is displayed in the echo
591 area. When debugging a C program using the GDB Graphical Interface, you
592 can also display macro definitions associated with an identifier when
593 the program is not executing.
594
595 GUD tooltips are disabled when you use GDB in text command mode
596 (@pxref{GDB Graphical Interface}), because displaying an expression's
597 value in GDB can sometimes expand a macro and result in a side effect
598 that interferes with the program's operation. The GDB graphical
599 interface supports GUD tooltips and assures they will not cause side
600 effects.
601
602 @node Commands of GUD
603 @subsection Commands of GUD
604
605 The GUD interaction buffer uses a variant of Shell mode, so the
606 Emacs commands of Shell mode are available (@pxref{Shell Mode}). All
607 the usual commands for your debugger are available, and you can use
608 the Shell mode history commands to repeat them. If you wish, you can
609 control your debugger process entirely through this buffer.
610
611 GUD mode also provides commands for setting and clearing
612 breakpoints, for selecting stack frames, and for stepping through the
613 program. These commands are available both in the GUD buffer and
614 globally, but with different key bindings. It also has its own tool
615 bar from which you can invoke the more common commands by clicking on
616 the appropriate icon. This is particularly useful for repetitive
617 commands like @code{gud-next} and @code{gud-step}, and allows you to
618 keep the GUD buffer hidden.
619
620 The breakpoint commands are normally used in source file buffers,
621 because that is the easiest way to specify where to set or clear the
622 breakpoint. Here's the global command to set a breakpoint:
623
624 @table @kbd
625 @item C-x @key{SPC}
626 @kindex C-x SPC
627 Set a breakpoint on the source line that point is on.
628 @end table
629
630 @kindex C-x C-a @r{(GUD)}
631 Here are the other special commands provided by GUD@. The keys
632 starting with @kbd{C-c} are available only in the GUD interaction
633 buffer. The key bindings that start with @kbd{C-x C-a} are available
634 in the GUD interaction buffer and also in source files. Some of these
635 commands are not available to all the supported debuggers.
636
637 @table @kbd
638 @item C-c C-l
639 @kindex C-c C-l @r{(GUD)}
640 @itemx C-x C-a C-l
641 @findex gud-refresh
642 Display in another window the last line referred to in the GUD
643 buffer (that is, the line indicated in the last location message).
644 This runs the command @code{gud-refresh}.
645
646 @item C-c C-s
647 @kindex C-c C-s @r{(GUD)}
648 @itemx C-x C-a C-s
649 @findex gud-step
650 Execute a single line of code (@code{gud-step}). If the line contains
651 a function call, execution stops after entering the called function.
652
653 @item C-c C-n
654 @kindex C-c C-n @r{(GUD)}
655 @itemx C-x C-a C-n
656 @findex gud-next
657 Execute a single line of code, stepping across entire function calls
658 at full speed (@code{gud-next}).
659
660 @item C-c C-i
661 @kindex C-c C-i @r{(GUD)}
662 @itemx C-x C-a C-i
663 @findex gud-stepi
664 Execute a single machine instruction (@code{gud-stepi}).
665
666 @item C-c C-p
667 @kindex C-c C-p @r{(GUD)}
668 @itemx C-x C-a C-p
669 @findex gud-print
670 Evaluate the expression at point (@code{gud-print}). If Emacs
671 does not print the exact expression that you want, mark it as a region
672 first.
673
674 @need 3000
675 @item C-c C-r
676 @kindex C-c C-r @r{(GUD)}
677 @itemx C-x C-a C-r
678 @findex gud-cont
679 Continue execution without specifying any stopping point. The program
680 will run until it hits a breakpoint, terminates, or gets a signal that
681 the debugger is checking for (@code{gud-cont}).
682
683 @need 1000
684 @item C-c C-d
685 @kindex C-c C-d @r{(GUD)}
686 @itemx C-x C-a C-d
687 @findex gud-remove
688 Delete the breakpoint(s) on the current source line, if any
689 (@code{gud-remove}). If you use this command in the GUD interaction
690 buffer, it applies to the line where the program last stopped.
691
692 @item C-c C-t
693 @kindex C-c C-t @r{(GUD)}
694 @itemx C-x C-a C-t
695 @findex gud-tbreak
696 Set a temporary breakpoint on the current source line, if any
697 (@code{gud-tbreak}). If you use this command in the GUD interaction
698 buffer, it applies to the line where the program last stopped.
699
700 @item C-c <
701 @kindex C-c < @r{(GUD)}
702 @itemx C-x C-a <
703 @findex gud-up
704 Select the next enclosing stack frame (@code{gud-up}). This is
705 equivalent to the GDB command @samp{up}.
706
707 @item C-c >
708 @kindex C-c > @r{(GUD)}
709 @itemx C-x C-a >
710 @findex gud-down
711 Select the next inner stack frame (@code{gud-down}). This is
712 equivalent to the GDB command @samp{down}.
713
714 @item C-c C-u
715 @kindex C-c C-u @r{(GUD)}
716 @itemx C-x C-a C-u
717 @findex gud-until
718 Continue execution to the current line (@code{gud-until}). The
719 program will run until it hits a breakpoint, terminates, gets a signal
720 that the debugger is checking for, or reaches the line on which the
721 cursor currently sits.
722
723 @item C-c C-f
724 @kindex C-c C-f @r{(GUD)}
725 @itemx C-x C-a C-f
726 @findex gud-finish
727 Run the program until the selected stack frame returns or
728 stops for some other reason (@code{gud-finish}).
729 @end table
730
731 If you are using GDB, these additional key bindings are available:
732
733 @table @kbd
734 @item C-x C-a C-j
735 @kindex C-x C-a C-j @r{(GUD)}
736 @findex gud-jump
737 Only useful in a source buffer, @code{gud-jump} transfers the
738 program's execution point to the current line. In other words, the
739 next line that the program executes will be the one where you gave the
740 command. If the new execution line is in a different function from
741 the previously one, GDB prompts for confirmation since the results may
742 be bizarre. See the GDB manual entry regarding @code{jump} for
743 details.
744
745 @item @key{TAB}
746 @kindex TAB @r{(GUD)}
747 @findex gud-gdb-complete-command
748 With GDB, complete a symbol name (@code{gud-gdb-complete-command}).
749 This key is available only in the GUD interaction buffer.
750 @end table
751
752 These commands interpret a numeric argument as a repeat count, when
753 that makes sense.
754
755 Because @key{TAB} serves as a completion command, you can't use it to
756 enter a tab as input to the program you are debugging with GDB.
757 Instead, type @kbd{C-q @key{TAB}} to enter a tab.
758
759 @node GUD Customization
760 @subsection GUD Customization
761
762 @vindex gdb-mode-hook
763 @vindex dbx-mode-hook
764 @vindex sdb-mode-hook
765 @vindex xdb-mode-hook
766 @vindex perldb-mode-hook
767 @vindex pdb-mode-hook
768 @vindex jdb-mode-hook
769 On startup, GUD runs one of the following hooks: @code{gdb-mode-hook},
770 if you are using GDB; @code{dbx-mode-hook}, if you are using DBX;
771 @code{sdb-mode-hook}, if you are using SDB; @code{xdb-mode-hook}, if you
772 are using XDB; @code{perldb-mode-hook}, for Perl debugging mode;
773 @code{pdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB. You can
774 use these hooks to define custom key bindings for the debugger
775 interaction buffer. @xref{Hooks}.
776
777 Here is a convenient way to define a command that sends a particular
778 command string to the debugger, and set up a key binding for it in the
779 debugger interaction buffer:
780
781 @findex gud-def
782 @example
783 (gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring})
784 @end example
785
786 This defines a command named @var{function} which sends
787 @var{cmdstring} to the debugger process, and gives it the documentation
788 string @var{docstring}. You can then use the command @var{function} in any
789 buffer. If @var{binding} is non-@code{nil}, @code{gud-def} also binds
790 the command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to
791 @kbd{C-x C-a @var{binding}} generally.
792
793 The command string @var{cmdstring} may contain certain
794 @samp{%}-sequences that stand for data to be filled in at the time
795 @var{function} is called:
796
797 @table @samp
798 @item %f
799 The name of the current source file. If the current buffer is the GUD
800 buffer, then the ``current source file'' is the file that the program
801 stopped in.
802
803 @item %l
804 The number of the current source line. If the current buffer is the GUD
805 buffer, then the ``current source line'' is the line that the program
806 stopped in.
807
808 @item %e
809 In transient-mark-mode the text in the region, if it is active.
810 Otherwise the text of the C lvalue or function-call expression at or
811 adjacent to point.
812
813 @item %a
814 The text of the hexadecimal address at or adjacent to point.
815
816 @item %p
817 The numeric argument of the called function, as a decimal number. If
818 the command is used without a numeric argument, @samp{%p} stands for the
819 empty string.
820
821 If you don't use @samp{%p} in the command string, the command you define
822 ignores any numeric argument.
823
824 @item %d
825 The name of the directory of the current source file.
826
827 @item %c
828 Fully qualified class name derived from the expression surrounding point
829 (jdb only).
830 @end table
831
832 @node GDB Graphical Interface
833 @subsection GDB Graphical Interface
834
835 The command @code{gdb} starts GDB in a graphical interface, using
836 Emacs windows for display program state information. In effect, this
837 makes Emacs into an IDE (interactive development environment). With
838 it, you do not need to use textual GDB commands; you can control the
839 debugging session with the mouse. For example, you can click in the
840 fringe of a source buffer to set a breakpoint there, or on a stack
841 frame in the stack buffer to select that frame.
842
843 This mode requires telling GDB that its ``screen size'' is
844 unlimited, so it sets the height and width accordingly. For correct
845 operation you must not change these values during the GDB session.
846
847 @vindex gud-gdb-command-name
848 To run GDB in text command mode, like the other debuggers in Emacs,
849 use @kbd{M-x gud-gdb}. You need to use text command mode to debug
850 multiple programs within one Emacs session.
851
852 @menu
853 * GDB-UI Layout:: Control the number of displayed buffers.
854 * Source Buffers:: Use the mouse in the fringe/margin to
855 control your program.
856 * Breakpoints Buffer:: A breakpoint control panel.
857 * Stack Buffer:: Select a frame from the call stack.
858 * Other GDB-UI Buffers:: Input/output, locals, registers,
859 assembler, threads and memory buffers.
860 * Watch Expressions:: Monitor variable values in the speedbar.
861 @end menu
862
863 @node GDB-UI Layout
864 @subsubsection GDB User Interface Layout
865 @cindex GDB User Interface layout
866
867 @vindex gdb-many-windows
868 If the variable @code{gdb-many-windows} is @code{nil} (the default
869 value) then @kbd{M-x gdb} normally displays only the GUD buffer.
870 However, if the variable @code{gdb-show-main} is also non-@code{nil},
871 it starts with two windows: one displaying the GUD buffer, and the
872 other showing the source for the @code{main} function of the program
873 you are debugging.
874
875 If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb}
876 displays the following frame layout:
877
878 @smallexample
879 @group
880 +--------------------------------+--------------------------------+
881 | GUD buffer (I/O of GDB) | Locals/Registers buffer |
882 |--------------------------------+--------------------------------+
883 | Primary Source buffer | I/O buffer for debugged pgm |
884 |--------------------------------+--------------------------------+
885 | Stack buffer | Breakpoints/thread buffer |
886 +--------------------------------+--------------------------------+
887 @end group
888 @end smallexample
889
890 However, if @code{gdb-use-separate-io-buffer} is @code{nil}, the I/O
891 buffer does not appear and the primary source buffer occupies the full
892 width of the frame.
893
894 @findex gdb-restore-windows
895 If you change the window layout, for example, while editing and
896 re-compiling your program, then you can restore this standard window
897 layout with the command @code{gdb-restore-windows}.
898
899 @findex gdb-many-windows
900 To switch between this standard layout and a simple layout
901 containing just the GUD buffer and a source file, type @kbd{M-x
902 gdb-many-windows}.
903
904 You may also specify additional GDB-related buffers to display,
905 either in the same frame or a different one. Select the buffers you
906 want with the @samp{GUD->GDB-windows} and @samp{GUD->GDB-Frames}
907 sub-menus. If the menu-bar is unavailable, type @code{M-x
908 gdb-display-@var{buffertype}-buffer} or @code{M-x
909 gdb-frame-@var{buffertype}-buffer} respectively, where
910 @var{buffertype} is the relevant buffer type, such as
911 @samp{breakpoints}. Most of these buffers are read-only, and typing
912 @kbd{q} in them kills them.
913
914 When you finish debugging, kill the GUD buffer with @kbd{C-x k},
915 which will also kill all the buffers associated with the session.
916 However you need not do this if, after editing and re-compiling your
917 source code within Emacs, you wish continue debugging. When you
918 restart execution, GDB will automatically find your new executable.
919 Keeping the GUD buffer has the advantage of keeping the shell history
920 as well as GDB's breakpoints. You do need to check that the
921 breakpoints in recently edited source files are still in the right
922 places.
923
924 @node Source Buffers
925 @subsubsection Source Buffers
926 @cindex GDB commands in Fringe
927
928 @c @findex gdb-mouse-set-clear-breakpoint
929 @c @findex gdb-mouse-toggle-breakpoint
930 Many GDB commands can be entered using key bindings or the tool bar but
931 sometimes it is quicker to use the fringe. These commands either
932 manipulate breakpoints or control program execution. When there is no
933 fringe, you can use the margin but this is only present when the
934 source file already has a breakpoint.
935
936 You can click @kbd{Mouse-1} in the fringe or display margin of a
937 source buffer to set a breakpoint there and, on a graphical display, a
938 red bullet will appear on that line. If a breakpoint already exists
939 on that line, the same click will remove it. You can also enable or
940 disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet.
941
942 A solid arrow in the left fringe of a source buffer indicates the line
943 of the innermost frame where the debugged program has stopped. A
944 hollow arrow indicates the current execution line of higher level
945 frames.
946
947 If you drag the arrow in the fringe with @kbd{Mouse-1}
948 (@code{gdb-mouse-until}), execution will continue to the line where
949 you release the button, provided it is still in the same frame.
950 Alternatively, you can click @kbd{Mouse-3} at some point in the fringe
951 of this buffer and execution will advance to there. A similar command
952 (@code{gdb-mouse-jump}) allows you to jump to a source line without
953 executing the intermediate lines by clicking @kbd{C-Mouse-3}. This
954 command allows you to go backwards which can be useful for running
955 through code that has already executed, in order to examine its
956 execution in more detail.
957
958 @table @kbd
959 @item Mouse-1
960 Set or clear a breakpoint.
961
962 @item C-Mouse-1
963 Enable or disable a breakpoint.
964
965 @item Mouse-3
966 Continue execution to here.
967
968 @item C-Mouse-3
969 Jump to here.
970 @end table
971
972 If the variable @code{gdb-find-source-frame} is non-@code{nil} and
973 execution stops in a frame for which there is no source code e.g after
974 an interrupt, then Emacs finds and displays the first frame further up
975 stack for which there is source. If it is @code{nil} then the source
976 buffer continues to display the last frame which maybe more useful,
977 for example, when re-setting a breakpoint.
978
979 @node Breakpoints Buffer
980 @subsubsection Breakpoints Buffer
981
982 The breakpoints buffer shows the existing breakpoints, watchpoints and
983 catchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}). It has
984 these special commands, which mostly apply to the @dfn{current
985 breakpoint}, the breakpoint which point is on.
986
987 @table @kbd
988 @item @key{SPC}
989 @kindex SPC @r{(GDB breakpoints buffer)}
990 @findex gdb-toggle-breakpoint
991 Enable/disable the current breakpoint (@code{gdb-toggle-breakpoint}).
992 On a graphical display, this changes the color of a bullet in the
993 margin of a source buffer at the relevant line. This is red when
994 the breakpoint is enabled and grey when it is disabled. Text-only
995 terminals correspondingly display a @samp{B} or @samp{b}.
996
997 @item D
998 @kindex D @r{(GDB breakpoints buffer)}
999 @findex gdb-delete-breakpoint
1000 Delete the current breakpoint (@code{gdb-delete-breakpoint}).
1001
1002 @item @key{RET}
1003 @kindex RET @r{(GDB breakpoints buffer)}
1004 @findex gdb-goto-breakpoint
1005 Visit the source line for the current breakpoint
1006 (@code{gdb-goto-breakpoint}).
1007
1008 @item Mouse-2
1009 @kindex Mouse-2 @r{(GDB breakpoints buffer)}
1010 Visit the source line for the breakpoint you click on.
1011 @end table
1012
1013 When @code{gdb-many-windows} is non-@code{nil}, the breakpoints buffer
1014 shares its window with the threads buffer. To switch from one to the
1015 other click with @kbd{mouse-1} on the relevant button in the header
1016 line.
1017
1018 @node Stack Buffer
1019 @subsubsection Stack Buffer
1020
1021 The stack buffer displays a @dfn{call stack}, with one line for each
1022 of the nested subroutine calls (@dfn{stack frames}) now active in the
1023 program. @xref{Backtrace,, Backtraces, gdb, The GNU debugger}.
1024
1025 @findex gdb-frames-select
1026 An arrow in the fringe points to the selected frame or, if the fringe is
1027 not present, the number of the selected frame is displayed in reverse
1028 contrast. To select a frame in GDB, move point in the stack buffer to
1029 that stack frame and type @key{RET} (@code{gdb-frames-select}), or click
1030 @kbd{Mouse-2} on a stack frame. If the locals buffer is visible,
1031 selecting a stack frame updates it to display the local variables of the
1032 new frame.
1033
1034 @node Other GDB-UI Buffers
1035 @subsubsection Other Buffers
1036
1037 @table @asis
1038 @item Input/Output Buffer
1039 @vindex gdb-use-separate-io-buffer
1040 If the variable @code{gdb-use-separate-io-buffer} is non-@code{nil},
1041 the program being debugged takes its input and displays its output
1042 here. Otherwise it uses the GUD buffer for that. To toggle whether
1043 GUD mode uses this buffer, do @kbd{M-x gdb-use-separate-io-buffer}.
1044 This takes effect when you next restart the program you are debugging.
1045
1046 The history and replay commands from Shell mode are available here,
1047 as are the commands to send signals to the debugged program.
1048 @xref{Shell Mode}.
1049
1050 @item Locals Buffer
1051 The locals buffer displays the values of local variables of the
1052 current frame for simple data types (@pxref{Frame Info, Frame Info,
1053 Information on a frame, gdb, The GNU debugger}). Press @key{RET} or
1054 click @kbd{Mouse-2} on the value if you want to edit it.
1055
1056 Arrays and structures display their type only. With GDB 6.4 or later,
1057 move point to their name and press @key{RET}, or alternatively click
1058 @kbd{Mouse-2} there, to examine their values. With earlier versions
1059 of GDB, use @kbd{Mouse-2} or @key{RET} on the type description
1060 (@samp{[struct/union]} or @samp{[array]}). @xref{Watch Expressions}.
1061
1062 @item Registers Buffer
1063 @findex toggle-gdb-all-registers
1064 The registers buffer displays the values held by the registers
1065 (@pxref{Registers,,, gdb, The GNU debugger}). Press @key{RET} or
1066 click @kbd{Mouse-2} on a register if you want to edit its value.
1067 With GDB 6.4 or later, recently changed register values display with
1068 @code{font-lock-warning-face}. With earlier versions of GDB, you can
1069 press @key{SPC} to toggle the display of floating point registers
1070 (@code{toggle-gdb-all-registers}).
1071
1072 @item Assembler Buffer
1073 The assembler buffer displays the current frame as machine code. An
1074 arrow points to the current instruction, and you can set and remove
1075 breakpoints as in a source buffer. Breakpoint icons also appear in
1076 the fringe or margin.
1077
1078 @item Threads Buffer
1079 @findex gdb-threads-select
1080 The threads buffer displays a summary of all threads currently in your
1081 program (@pxref{Threads, Threads, Debugging programs with multiple
1082 threads, gdb, The GNU debugger}). Move point to any thread in the
1083 list and press @key{RET} to select it (@code{gdb-threads-select}) and
1084 display the associated source in the primary source buffer.
1085 Alternatively, click @kbd{Mouse-2} on a thread to select it. If the
1086 locals buffer is visible, its contents update to display the variables
1087 that are local in the new thread.
1088
1089 When there is more than one main thread and the threads buffer is
1090 present, Emacs displays the selected thread number in the mode line of
1091 many of the GDB-UI Buffers.
1092
1093 @item Memory Buffer
1094 The memory buffer lets you examine sections of program memory
1095 (@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}).
1096 Click @kbd{Mouse-1} on the appropriate part of the header line to
1097 change the starting address or number of data items that the buffer
1098 displays. Alternatively, use @kbd{S} or @kbd{N} respectively. Click
1099 @kbd{Mouse-3} on the header line to select the display format or unit
1100 size for these data items.
1101 @end table
1102
1103 When @code{gdb-many-windows} is non-@code{nil}, the threads buffer
1104 shares its window with the breakpoints buffer, and the locals buffer
1105 with the registers buffer. To switch from one to the other click with
1106 @kbd{mouse-1} on the relevant button in the header line.
1107
1108 @node Watch Expressions
1109 @subsubsection Watch Expressions
1110 @cindex Watching expressions in GDB
1111
1112 @findex gud-watch
1113 @kindex C-x C-a C-w @r{(GUD)}
1114 If you want to see how a variable changes each time your program
1115 stops, move point into the variable name and click on the watch icon
1116 in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}. If you
1117 specify a prefix argument, you can enter the variable name in the
1118 minibuffer.
1119
1120 Each watch expression is displayed in the speedbar. Complex data
1121 types, such as arrays, structures and unions are represented in a tree
1122 format. Leaves and simple data types show the name of the expression
1123 and its value and, when the speedbar frame is selected, display the
1124 type as a tooltip. Higher levels show the name, type and address
1125 value for pointers and just the name and type otherwise. Root expressions
1126 also display the frame address as a tooltip to help identify the frame
1127 in which they were defined.
1128
1129 To expand or contract a complex data type, click @kbd{Mouse-2} or
1130 press @key{SPC} on the tag to the left of the expression. Emacs asks
1131 for confirmation before expanding the expression if its number of
1132 immediate children exceeds the value of the variable
1133 @code{gdb-max-children}.
1134
1135 @kindex D @r{(GDB speedbar)}
1136 @findex gdb-var-delete
1137 To delete a complex watch expression, move point to the root
1138 expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}).
1139
1140 @kindex RET @r{(GDB speedbar)}
1141 @findex gdb-edit-value
1142 To edit a variable with a simple data type, or a simple element of a
1143 complex data type, move point there in the speedbar and type @key{RET}
1144 (@code{gdb-edit-value}). Or you can click @kbd{Mouse-2} on a value to
1145 edit it. Either way, this reads the new value using the minibuffer.
1146
1147 @vindex gdb-show-changed-values
1148 If you set the variable @code{gdb-show-changed-values} to
1149 non-@code{nil} (the default value), Emacs uses
1150 @code{font-lock-warning-face} to highlight values that have recently
1151 changed and @code{shadow} face to make variables which have gone out of
1152 scope less noticeable. When a variable goes out of scope you can't
1153 edit its value.
1154
1155 @vindex gdb-delete-out-of-scope
1156 If the variable @code{gdb-delete-out-of-scope} is non-@code{nil}
1157 (the default value), Emacs automatically deletes watch expressions
1158 which go out of scope. Sometimes, when re-entering the same function,
1159 it may be useful to set this value to @code{nil} so that you don't
1160 need to recreate the watch expression.
1161
1162 @vindex gdb-use-colon-colon-notation
1163 If the variable @code{gdb-use-colon-colon-notation} is
1164 non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}}
1165 format. This allows the user to display watch expressions which share
1166 the same variable name. The default value is @code{nil}.
1167
1168 @vindex gdb-speedbar-auto-raise
1169 To automatically raise the speedbar every time the display of watch
1170 expressions updates, set @code{gdb-speedbar-auto-raise} to
1171 non-@code{nil}. This can be useful if you are debugging with a full
1172 screen Emacs frame.
1173
1174 @node Executing Lisp
1175 @section Executing Lisp Expressions
1176
1177 Emacs has several different major modes for Lisp and Scheme. They are
1178 the same in terms of editing commands, but differ in the commands for
1179 executing Lisp expressions. Each mode has its own purpose.
1180
1181 @table @asis
1182 @item Emacs-Lisp mode
1183 The mode for editing source files of programs to run in Emacs Lisp.
1184 This mode defines @kbd{C-M-x} to evaluate the current defun.
1185 @xref{Lisp Libraries}.
1186 @item Lisp Interaction mode
1187 The mode for an interactive session with Emacs Lisp. It defines
1188 @kbd{C-j} to evaluate the sexp before point and insert its value in the
1189 buffer. @xref{Lisp Interaction}.
1190 @item Lisp mode
1191 The mode for editing source files of programs that run in Lisps other
1192 than Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defun
1193 to an inferior Lisp process. @xref{External Lisp}.
1194 @item Inferior Lisp mode
1195 The mode for an interactive session with an inferior Lisp process.
1196 This mode combines the special features of Lisp mode and Shell mode
1197 (@pxref{Shell Mode}).
1198 @item Scheme mode
1199 Like Lisp mode but for Scheme programs.
1200 @item Inferior Scheme mode
1201 The mode for an interactive session with an inferior Scheme process.
1202 @end table
1203
1204 Most editing commands for working with Lisp programs are in fact
1205 available globally. @xref{Programs}.
1206
1207 @node Lisp Libraries
1208 @section Libraries of Lisp Code for Emacs
1209 @cindex libraries
1210 @cindex loading Lisp code
1211
1212 Lisp code for Emacs editing commands is stored in files whose names
1213 conventionally end in @file{.el}. This ending tells Emacs to edit them in
1214 Emacs-Lisp mode (@pxref{Executing Lisp}).
1215
1216 @cindex byte code
1217 Emacs Lisp code can be compiled into byte-code, which loads faster,
1218 takes up less space, and executes faster. @xref{Byte Compilation,,
1219 Byte Compilation, elisp, the Emacs Lisp Reference Manual}. By
1220 convention, the compiled code for a library goes in a separate file
1221 whose name ends in @samp{.elc}. Thus, the compiled code for
1222 @file{foo.el} goes in @file{foo.elc}.
1223
1224 @findex load-file
1225 To execute a file of Emacs Lisp code, use @kbd{M-x load-file}. This
1226 command reads a file name using the minibuffer and then executes the
1227 contents of that file as Lisp code. It is not necessary to visit the
1228 file first; in any case, this command reads the file as found on disk,
1229 not text in an Emacs buffer.
1230
1231 @findex load
1232 @findex load-library
1233 Once a file of Lisp code is installed in the Emacs Lisp library
1234 directories, users can load it using @kbd{M-x load-library}. Programs
1235 can load it by calling @code{load}, a more primitive function that is
1236 similar but accepts some additional arguments.
1237
1238 @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it
1239 searches a sequence of directories and tries three file names in each
1240 directory. Suppose your argument is @var{lib}; the three names are
1241 @file{@var{lib}.elc}, @file{@var{lib}.el}, and lastly just
1242 @file{@var{lib}}. If @file{@var{lib}.elc} exists, it is by convention
1243 the result of compiling @file{@var{lib}.el}; it is better to load the
1244 compiled file, since it will load and run faster.
1245
1246 If @code{load-library} finds that @file{@var{lib}.el} is newer than
1247 @file{@var{lib}.elc} file, it issues a warning, because it's likely
1248 that somebody made changes to the @file{.el} file and forgot to
1249 recompile it. Nonetheless, it loads @file{@var{lib}.elc}. This is
1250 because people often leave unfinished edits the source file, and don't
1251 recompile it until they think it is ready to use.
1252
1253 @vindex load-path
1254 The variable @code{load-path} specifies the sequence of directories
1255 searched by @kbd{M-x load-library}. Its value should be a list of
1256 strings that are directory names, or @code{nil} for the current
1257 default directory. (Generally, it is not a good idea to put
1258 @code{nil} in the list; if you find yourself wishing that @code{nil}
1259 were in the list, most likely what you really want is to do @kbd{M-x
1260 load-file} this once.)
1261
1262 The default value of @code{load-path} is a list of directories where
1263 the Lisp code for Emacs itself is stored. If you have libraries of
1264 your own, put them in a single directory and add that directory to
1265 @code{load-path}, by adding a line like this to your init file
1266 (@pxref{Init File}):
1267
1268 @example
1269 (add-to-list 'load-path "/path/to/lisp/libraries")
1270 @end example
1271
1272 @cindex autoload
1273 Often you do not have to give any command to load a library, because
1274 the commands defined in the library are set up to @dfn{autoload} that
1275 library. Trying to run any of those commands calls @code{load} to load
1276 the library; this replaces the autoload definitions with the real ones
1277 from the library.
1278
1279 @vindex load-dangerous-libraries
1280 @cindex Lisp files byte-compiled by XEmacs
1281 By default, Emacs refuses to load compiled Lisp files which were
1282 compiled with XEmacs, a modified versions of Emacs---they can cause
1283 Emacs to crash. Set the variable @code{load-dangerous-libraries} to
1284 @code{t} if you want to try loading them.
1285
1286 @node Lisp Eval
1287 @section Evaluating Emacs Lisp Expressions
1288 @cindex Emacs-Lisp mode
1289 @cindex mode, Emacs-Lisp
1290
1291 @findex emacs-lisp-mode
1292 Lisp programs intended to be run in Emacs should be edited in
1293 Emacs-Lisp mode; this happens automatically for file names ending in
1294 @file{.el}. By contrast, Lisp mode itself is used for editing Lisp
1295 programs intended for other Lisp systems. To switch to Emacs-Lisp mode
1296 explicitly, use the command @kbd{M-x emacs-lisp-mode}.
1297
1298 For testing of Lisp programs to run in Emacs, it is often useful to
1299 evaluate part of the program as it is found in the Emacs buffer. For
1300 example, after changing the text of a Lisp function definition,
1301 evaluating the definition installs the change for future calls to the
1302 function. Evaluation of Lisp expressions is also useful in any kind of
1303 editing, for invoking noninteractive functions (functions that are
1304 not commands).
1305
1306 @table @kbd
1307 @item M-:
1308 Read a single Lisp expression in the minibuffer, evaluate it, and print
1309 the value in the echo area (@code{eval-expression}).
1310 @item C-x C-e
1311 Evaluate the Lisp expression before point, and print the value in the
1312 echo area (@code{eval-last-sexp}).
1313 @item C-M-x
1314 Evaluate the defun containing or after point, and print the value in
1315 the echo area (@code{eval-defun}).
1316 @item M-x eval-region
1317 Evaluate all the Lisp expressions in the region.
1318 @item M-x eval-buffer
1319 Evaluate all the Lisp expressions in the buffer.
1320 @end table
1321
1322 @ifinfo
1323 @c This uses ``colon'' instead of a literal `:' because Info cannot
1324 @c cope with a `:' in a menu
1325 @kindex M-@key{colon}
1326 @end ifinfo
1327 @ifnotinfo
1328 @kindex M-:
1329 @end ifnotinfo
1330 @findex eval-expression
1331 @kbd{M-:} (@code{eval-expression}) is the most basic command for evaluating
1332 a Lisp expression interactively. It reads the expression using the
1333 minibuffer, so you can execute any expression on a buffer regardless of
1334 what the buffer contains. When the expression is evaluated, the current
1335 buffer is once again the buffer that was current when @kbd{M-:} was
1336 typed.
1337
1338 @kindex C-M-x @r{(Emacs-Lisp mode)}
1339 @findex eval-defun
1340 In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the command
1341 @code{eval-defun}, which parses the defun containing or following point
1342 as a Lisp expression and evaluates it. The value is printed in the echo
1343 area. This command is convenient for installing in the Lisp environment
1344 changes that you have just made in the text of a function definition.
1345
1346 @kbd{C-M-x} treats @code{defvar} expressions specially. Normally,
1347 evaluating a @code{defvar} expression does nothing if the variable it
1348 defines already has a value. But @kbd{C-M-x} unconditionally resets the
1349 variable to the initial value specified in the @code{defvar} expression.
1350 @code{defcustom} expressions are treated similarly.
1351 This special feature is convenient for debugging Lisp programs.
1352 Typing @kbd{C-M-x} on a @code{defface} expression reinitializes
1353 the face according to the @code{defface} specification.
1354
1355 @kindex C-x C-e
1356 @findex eval-last-sexp
1357 The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Lisp
1358 expression preceding point in the buffer, and displays the value in the
1359 echo area. It is available in all major modes, not just Emacs-Lisp
1360 mode. It does not treat @code{defvar} specially.
1361
1362 When the result of an evaluation is an integer, you can type
1363 @kbd{C-x C-e} a second time to display the value of the integer result
1364 in additional formats (octal, hexadecimal, and character).
1365
1366 If @kbd{C-x C-e}, or @kbd{M-:} is given a numeric argument, it
1367 inserts the value into the current buffer at point, rather than
1368 displaying it in the echo area. The argument's value does not matter.
1369 @kbd{C-M-x} with a numeric argument instruments the function
1370 definition for Edebug (@pxref{Instrumenting, Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}).
1371
1372 @findex eval-region
1373 @findex eval-buffer
1374 The most general command for evaluating Lisp expressions from a buffer
1375 is @code{eval-region}. @kbd{M-x eval-region} parses the text of the
1376 region as one or more Lisp expressions, evaluating them one by one.
1377 @kbd{M-x eval-buffer} is similar but evaluates the entire
1378 buffer. This is a reasonable way to install the contents of a file of
1379 Lisp code that you are ready to test. Later, as you find bugs and
1380 change individual functions, use @kbd{C-M-x} on each function that you
1381 change. This keeps the Lisp world in step with the source file.
1382
1383 @vindex eval-expression-print-level
1384 @vindex eval-expression-print-length
1385 @vindex eval-expression-debug-on-error
1386 The two customizable variables @code{eval-expression-print-level} and
1387 @code{eval-expression-print-length} control the maximum depth and length
1388 of lists to print in the result of the evaluation commands before
1389 abbreviating them. @code{eval-expression-debug-on-error} controls
1390 whether evaluation errors invoke the debugger when these commands are
1391 used; its default is @code{t}.
1392
1393 @node Lisp Interaction
1394 @section Lisp Interaction Buffers
1395
1396 When Emacs starts up, it contains a buffer named @samp{*scratch*},
1397 which is provided for evaluating Lisp expressions interactively inside
1398 Emacs. Its major mode is Lisp Interaction mode.
1399
1400 @findex eval-print-last-sexp
1401 @kindex C-j @r{(Lisp Interaction mode)}
1402 The simplest way to use the @samp{*scratch*} buffer is to insert
1403 Lisp expressions and type @kbd{C-j} (@code{eval-print-last-sexp})
1404 after each expression. This command reads the Lisp expression before
1405 point, evaluates it, and inserts the value in printed representation
1406 before point. The result is a complete typescript of the expressions
1407 you have evaluated and their values.
1408
1409 @vindex initial-scratch-message
1410 At startup, the @samp{*scratch*} buffer contains a short message, in
1411 the form of a Lisp comment, that explains what it is for. This
1412 message is controlled by the variable @code{initial-scratch-message},
1413 which should be either a string or @code{nil}. If you set it to the
1414 empty string, or @code{nil}, the initial message is suppressed.
1415
1416 @findex lisp-interaction-mode
1417 All other commands in Lisp Interaction mode are the same as in Emacs
1418 Lisp mode. You can enable Lisp Interaction mode by typing @kbd{M-x
1419 lisp-interaction-mode}.
1420
1421 @findex ielm
1422 An alternative way of evaluating Emacs Lisp expressions interactively
1423 is to use Inferior Emacs-Lisp mode, which provides an interface rather
1424 like Shell mode (@pxref{Shell Mode}) for evaluating Emacs Lisp
1425 expressions. Type @kbd{M-x ielm} to create an @samp{*ielm*} buffer
1426 which uses this mode. For more information see that command's
1427 documentation.
1428
1429 @node External Lisp
1430 @section Running an External Lisp
1431
1432 Emacs has facilities for running programs in other Lisp systems. You can
1433 run a Lisp process as an inferior of Emacs, and pass expressions to it to
1434 be evaluated. You can also pass changed function definitions directly from
1435 the Emacs buffers in which you edit the Lisp programs to the inferior Lisp
1436 process.
1437
1438 @findex run-lisp
1439 @vindex inferior-lisp-program
1440 @kindex C-x C-z
1441 To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runs
1442 the program named @code{lisp}, the same program you would run by typing
1443 @code{lisp} as a shell command, with both input and output going through
1444 an Emacs buffer named @samp{*lisp*}. That is to say, any ``terminal
1445 output'' from Lisp will go into the buffer, advancing point, and any
1446 ``terminal input'' for Lisp comes from text in the buffer. (You can
1447 change the name of the Lisp executable file by setting the variable
1448 @code{inferior-lisp-program}.)
1449
1450 To give input to Lisp, go to the end of the buffer and type the input,
1451 terminated by @key{RET}. The @samp{*lisp*} buffer is in Inferior Lisp
1452 mode, which combines the special characteristics of Lisp mode with most
1453 of the features of Shell mode (@pxref{Shell Mode}). The definition of
1454 @key{RET} to send a line to a subprocess is one of the features of Shell
1455 mode.
1456
1457 @findex lisp-mode
1458 For the source files of programs to run in external Lisps, use Lisp
1459 mode. You can switch to this mode with @kbd{M-x lisp-mode}, and it is
1460 used automatically for files whose names end in @file{.l},
1461 @file{.lsp}, or @file{.lisp}.
1462
1463 @kindex C-M-x @r{(Lisp mode)}
1464 @findex lisp-eval-defun
1465 When you edit a function in a Lisp program you are running, the easiest
1466 way to send the changed definition to the inferior Lisp process is the key
1467 @kbd{C-M-x}. In Lisp mode, this runs the function @code{lisp-eval-defun},
1468 which finds the defun around or following point and sends it as input to
1469 the Lisp process. (Emacs can send input to any inferior process regardless
1470 of what buffer is current.)
1471
1472 Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing
1473 programs to be run in another Lisp system) and Emacs-Lisp mode (for
1474 editing Lisp programs to be run in Emacs; see @pxref{Lisp Eval}): in
1475 both modes it has the effect of installing the function definition
1476 that point is in, but the way of doing so is different according to
1477 where the relevant Lisp environment is found.
1478
1479
1480 @ignore
1481 arch-tag: 9c3c2f71-b332-4144-8500-3ff9945a50ed
1482 @end ignore