1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985,86,87,93,94,95,97,2000,2001 Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
4 @node Building, Maintaining, Programs, Top
5 @chapter Compiling and Testing Programs
6 @cindex building programs
7 @cindex program building
8 @cindex running Lisp functions
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.
15 * Compilation:: Compiling programs in languages other
16 than Lisp (C, Pascal, etc.).
17 * Compilation Mode:: The mode for visiting compiler errors.
18 * Compilation Shell:: Customizing your shell properly
19 for use in the compilation buffer.
20 * Grep Searching:: Searching with grep.
21 * Flymake:: Finding syntax errors on the fly.
22 * Debuggers:: Running symbolic debuggers for non-Lisp programs.
23 * Executing Lisp:: Various modes for editing Lisp programs,
24 with different facilities for running
26 * Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs.
27 * Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
28 * Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
29 * External Lisp:: Communicating through Emacs with a separate Lisp.
33 @section Running Compilations under Emacs
34 @cindex inferior process
36 @cindex compilation errors
39 Emacs can run compilers for noninteractive languages such as C and
40 Fortran as inferior processes, feeding the error log into an Emacs buffer.
41 It can also parse the error messages and show you the source lines where
42 compilation errors occurred.
46 Run a compiler asynchronously under Emacs, with error messages going to
47 the @samp{*compilation*} buffer.
49 Invoke a compiler with the same command as in the last invocation of
52 Run @code{grep} asynchronously under Emacs, with matching lines
53 listed in the buffer named @samp{*grep*}.
56 Run @code{grep} via @code{find}, with user-specified arguments, and
57 collect output in the buffer named @samp{*grep*}.
58 @item M-x kill-compilation
60 Kill the running compilation or @code{grep} subprocess.
64 To run @code{make} or another compilation command, do @kbd{M-x
65 compile}. This command reads a shell command line using the minibuffer,
66 and then executes the command in an inferior shell, putting output in
67 the buffer named @samp{*compilation*}. The current buffer's default
68 directory is used as the working directory for the execution of the
69 command; normally, therefore, the compilation happens in this
72 @vindex compile-command
73 When the shell command line is read, the minibuffer appears
74 containing a default command line, which is the command you used the
75 last time you did @kbd{M-x compile}. If you type just @key{RET}, the
76 same command line is used again. For the first @kbd{M-x compile}, the
77 default is @samp{make -k}, which is correct most of the time for
78 nontrivial programs. (@xref{Top,, Make, make, GNU Make Manual}.)
79 The default compilation command comes from the variable
80 @code{compile-command}; if the appropriate compilation command for a
81 file is something other than @samp{make -k}, it can be useful for the
82 file to specify a local value for @code{compile-command} (@pxref{File
85 Starting a compilation displays the buffer @samp{*compilation*} in
86 another window but does not select it. The buffer's mode line tells
87 you whether compilation is finished, with the word @samp{run},
88 @samp{signal} or @samp{exit} inside the parentheses. You do not have
89 to keep this buffer visible; compilation continues in any case. While
90 a compilation is going on, the string @samp{Compiling} appears in the
91 mode lines of all windows. When this string disappears, the
92 compilation is finished.
94 If you want to watch the compilation transcript as it appears, switch
95 to the @samp{*compilation*} buffer and move point to the end of the
96 buffer. When point is at the end, new compilation output is inserted
97 above point, which remains at the end. If point is not at the end of
98 the buffer, it remains fixed while more compilation output is added at
99 the end of the buffer.
101 @cindex compilation buffer, keeping current position at the end
102 @vindex compilation-scroll-output
103 If you set the variable @code{compilation-scroll-output} to a
104 non-@code{nil} value, then the compilation buffer always scrolls to
105 follow output as it comes in.
107 @findex kill-compilation
108 When the compiler process terminates, for whatever reason, the mode
109 line of the @samp{*compilation*} buffer changes to say @samp{exit}
110 (followed by the exit code, @samp{[0]} for a normal exit), or
111 @samp{signal} (if a signal terminated the process), instead of
112 @samp{run}. Starting a new compilation also kills any running
113 compilation, as only one can exist at any time. However, @kbd{M-x
114 compile} asks for confirmation before actually killing a compilation
115 that is running. You can also kill the compilation process with
116 @kbd{M-x kill-compilation}.
119 To rerun the last compilation with the same command, type @kbd{M-x
120 recompile}. This automatically reuses the compilation command from
121 the last invocation of @kbd{M-x compile}. It also reuses the
122 @samp{*compilation*} buffer and starts the compilation in its default
123 directory, which is the directory in which the previous compilation
126 Emacs does not expect a compiler process to launch asynchronous
127 subprocesses; if it does, and they keep running after the main
128 compiler process has terminated, Emacs may kill them or their output
129 may not arrive in Emacs. To avoid this problem, make the main process
130 wait for its subprocesses to finish. In a shell script, you can do this
131 using @samp{$!} and @samp{wait}, like this:
134 (sleep 10; echo 2nd)& pid=$! # @r{Record pid of subprocess}
136 wait $pid # @r{Wait for subprocess}
139 If the background process does not output to the compilation buffer,
140 so you only need to prevent it from being killed when the main
141 compilation process terminates, this is sufficient:
144 nohup @var{command}; sleep 1
147 @vindex compilation-environment
148 You can control the environment passed to the compilation command
149 with the variable @code{compilation-environment}. Its value is a list
150 of environment variable settings; each element should be a string of
151 the form @code{"@var{envvarname}=@var{value}"}. These environment
152 variable settings override the usual ones.
154 @node Compilation Mode
155 @section Compilation Mode
157 @findex compile-goto-error
158 @cindex Compilation mode
159 @cindex mode, Compilation
160 The @samp{*compilation*} buffer uses a special major mode, Compilation
161 mode, whose main feature is to provide a convenient way to look at the
162 source line where the error happened.
164 If you set the variable @code{compilation-scroll-output} to a
165 non-@code{nil} value, then the compilation buffer always scrolls to
166 follow output as it comes in.
172 Visit the locus of the next compiler error message or @code{grep} match.
175 Visit the locus of the previous compiler error message or @code{grep} match.
177 Visit the locus of the error message that point is on.
178 This command is used in the compilation buffer.
180 Visit the locus of the error message that you click on.
182 Find and highlight the locus of the next error message, without
183 selecting the source buffer.
185 Find and highlight the locus of the previous error message, without
186 selecting the source buffer.
188 Move point to the next error for a different file than the current
191 Move point to the previous error for a different file than the current
194 Toggle Next Error Follow minor mode, which makes cursor motion in the
195 compilation buffer produce automatic source display.
202 You can visit the source for any particular error message by moving
203 point in the @samp{*compilation*} buffer to that error message and
204 typing @key{RET} (@code{compile-goto-error}). Alternatively, you can
205 click @kbd{Mouse-2} on the error message; you need not switch to the
206 @samp{*compilation*} buffer first.
208 @vindex next-error-highlight
209 To parse the compiler error messages sequentially, type @kbd{C-x `}
210 (@code{next-error}). The character following the @kbd{C-x} is the
211 backquote or ``grave accent,'' not the single-quote. This command is
212 available in all buffers, not just in @samp{*compilation*}; it
213 displays the next error message at the top of one window and source
214 location of the error in another window. It also momentarily
215 highlights the relevant source line. You can change the behavior of
216 this highlighting with the variable @code{next-error-highlight}.
218 The first time @kbd{C-x `} is used after the start of a compilation,
219 it moves to the first error's location. Subsequent uses of @kbd{C-x `}
220 advance down to subsequent errors. If you visit a specific error
221 message with @key{RET} or @kbd{Mouse-2}, subsequent @kbd{C-x `}
222 commands advance from there. When @kbd{C-x `} gets to the end of the
223 buffer and finds no more error messages to visit, it fails and signals
226 You don't have to be in the compilation buffer in order to use
227 @code{next-error}. If one window on the selected frame can be the
228 target of the @code{next-error} call, it is used. Else, if a buffer
229 previously had @code{next-error} called on it, it is used. Else,
230 if the current buffer can be the target of @code{next-error}, it is
231 used. Else, all the buffers Emacs manages are tried for
232 @code{next-error} support.
234 @kbd{C-u C-x `} starts scanning from the beginning of the compilation
235 buffer. This is one way to process the same set of errors again.
237 @vindex compilation-error-regexp-alist
238 @vindex grep-regexp-alist
239 To parse messages from the compiler, Compilation mode uses the
240 variable @code{compilation-error-regexp-alist} which lists various
241 formats of error messages and tells Emacs how to extract the source file
242 and the line number from the text of a message. If your compiler isn't
243 supported, you can tailor Compilation mode to it by adding elements to
244 that list. A similar variable @code{grep-regexp-alist} tells Emacs how
245 to parse output of a @code{grep} command.
247 @findex compilation-next-error
248 @findex compilation-previous-error
249 @findex compilation-next-file
250 @findex compilation-previous-file
251 Compilation mode also redefines the keys @key{SPC} and @key{DEL} to
252 scroll by screenfuls, and @kbd{M-n} (@code{compilation-next-error})
253 and @kbd{M-p} (@code{compilation-previous-error}) to move to the next
254 or previous error message. You can also use @kbd{M-@{}
255 (@code{compilation-next-file} and @kbd{M-@}}
256 (@code{compilation-previous-file}) to move up or down to an error
257 message for a different source file.
259 @cindex Next Error Follow mode
260 @findex next-error-follow-minor-mode
261 You can type @kbd{C-c C-f} to toggle Next Error Follow mode. In
262 this minor mode, ordinary cursor motion in the compilation buffer
263 automatically updates the source buffer. For instance, moving the
264 cursor to the next error message causes the location of that error to
265 be displayed immediately.
267 The features of Compilation mode are also available in a minor mode
268 called Compilation Minor mode. This lets you parse error messages in
269 any buffer, not just a normal compilation output buffer. Type @kbd{M-x
270 compilation-minor-mode} to enable the minor mode. This defines the keys
271 @key{RET} and @kbd{Mouse-2}, as in the Compilation major mode.
273 Compilation minor mode works in any buffer, as long as the contents
274 are in a format that it understands. In an Rlogin buffer (@pxref{Remote
275 Host}), Compilation minor mode automatically accesses remote source
276 files by FTP (@pxref{File Names}).
278 @node Compilation Shell
279 @section Subshells for Compilation
281 Emacs uses a shell to run the compilation command, but specifies
282 the option for a noninteractive shell. This means, in particular, that
283 the shell should start with no prompt. If you find your usual shell
284 prompt making an unsightly appearance in the @samp{*compilation*}
285 buffer, it means you have made a mistake in your shell's init file by
286 setting the prompt unconditionally. (This init file's name may be
287 @file{.bashrc}, @file{.profile}, @file{.cshrc}, @file{.shrc}, or various
288 other things, depending on the shell you use.) The shell init file
289 should set the prompt only if there already is a prompt. In csh, here
293 if ($?prompt) set prompt = @dots{}
297 And here's how to do it in bash:
300 if [ "$@{PS1+set@}" = set ]
305 There may well be other things that your shell's init file
306 ought to do only for an interactive shell. You can use the same
307 method to conditionalize them.
309 The MS-DOS ``operating system'' does not support asynchronous
310 subprocesses; to work around this lack, @kbd{M-x compile} runs the
311 compilation command synchronously on MS-DOS. As a consequence, you must
312 wait until the command finishes before you can do anything else in
313 Emacs. @xref{MS-DOS}.
316 @section Searching with Grep under Emacs
319 Just as you can run a compiler from Emacs and then visit the lines
320 where there were compilation errors, you can also run @code{grep} and
321 then visit the lines on which matches were found. This works by
322 treating the matches reported by @code{grep} as if they were ``errors.''
324 To do this, type @kbd{M-x grep}, then enter a command line that
325 specifies how to run @code{grep}. Use the same arguments you would give
326 @code{grep} when running it normally: a @code{grep}-style regexp
327 (usually in single-quotes to quote the shell's special characters)
328 followed by file names, which may use wildcards. If you specify a
329 prefix argument for @kbd{M-x grep}, it figures out the tag
330 (@pxref{Tags}) around point, and puts that into the default
333 The output from @code{grep} goes in the @samp{*grep*} buffer. You
334 can find the corresponding lines in the original files using @kbd{C-x
335 `}, @key{RET}, and so forth, just like compilation errors.
337 Some grep programs accept a @samp{--color} option to output special
338 markers around matches for the purpose of highlighting. You can make
339 use of this feature by setting @code{grep-highlight-matches} to t.
340 When displaying a match in the source buffer, the exact match will be
341 highlighted, instead of the entire source line.
345 The command @kbd{M-x grep-find} (also available as @kbd{M-x
346 find-grep}) is similar to @kbd{M-x grep}, but it supplies a different
347 initial default for the command---one that runs both @code{find} and
348 @code{grep}, so as to search every file in a directory tree. See also
349 the @code{find-grep-dired} command, in @ref{Dired and Find}.
352 @section Finding Syntax Errors On The Fly
353 @cindex checking syntax
355 Flymake mode is a minor mode that performs on-the-fly syntax
356 checking for many programming and markup languages, including C, C++,
357 Perl, HTML, and @TeX{}/La@TeX{}. It is somewhat analogous to Flyspell
358 mode, which performs spell checking for ordinary human languages in a
359 similar fashion (@pxref{Spelling}). As you edit a file, Flymake mode
360 runs an appropriate syntax checking tool in the background, using a
361 temporary copy of the buffer. It then parses the error and warning
362 messages, and highlights the erroneous lines in the buffer. The
363 syntax checking tool used depends on the language; for example, for
364 C/C++ files this is usually the C compiler. Flymake can also use
365 build tools such as @code{make} for checking complicated projects.
367 To activate Flymake mode, type @kbd{M-x flymake-mode}. You can move
368 to the errors spotted by Flymake mode with @kbd{M-x
369 flymake-goto-next-error} and @kbd{M-x flymake-goto-prev-error}. To
370 display any error messages associated with the current line, use
371 @kbd{M-x flymake-display-err-menu-for-current-line}.
373 For more details about using Flymake, see @ref{Top, Flymake,
374 Flymake, flymake, The Flymake Manual}.
377 @section Running Debuggers Under Emacs
389 @c Do you believe in GUD?
390 The GUD (Grand Unified Debugger) library provides an interface to
391 various symbolic debuggers from within Emacs. We recommend the
392 debugger GDB, which is free software, but you can also run DBX, SDB or
393 XDB if you have them. GUD can also serve as an interface to Perl's
394 debugging mode, the Python debugger PDB, the bash debugger, and to
395 JDB, the Java Debugger. @xref{Debugging,, The Lisp Debugger, elisp,
396 the Emacs Lisp Reference Manual}, for information on debugging Emacs
400 * Starting GUD:: How to start a debugger subprocess.
401 * Debugger Operation:: Connection between the debugger and source buffers.
402 * Commands of GUD:: Key bindings for common commands.
403 * GUD Customization:: Defining your own commands for GUD.
404 * GDB Graphical Interface:: An enhanced mode that uses GDB features to
405 implement a graphical debugging environment through
410 @subsection Starting GUD
412 There are several commands for starting a debugger, each corresponding
413 to a particular debugger program.
416 @item M-x gdb @key{RET} @var{file} @key{RET}
418 Run GDB as a subprocess of Emacs. By default, this operates in
419 graphical mode; @xref{GDB Graphical Interface}. Graphical mode
420 does not support any other debuggers.
422 @item M-x dbx @key{RET} @var{file} @key{RET}
424 Similar, but run DBX instead of GDB.
426 @item M-x xdb @key{RET} @var{file} @key{RET}
428 @vindex gud-xdb-directories
429 Similar, but run XDB instead of GDB. Use the variable
430 @code{gud-xdb-directories} to specify directories to search for source
433 @item M-x sdb @key{RET} @var{file} @key{RET}
435 Similar, but run SDB instead of GDB.
437 Some versions of SDB do not mention source file names in their
438 messages. When you use them, you need to have a valid tags table
439 (@pxref{Tags}) in order for GUD to find functions in the source code.
440 If you have not visited a tags table or the tags table doesn't list one
441 of the functions, you get a message saying @samp{The sdb support
442 requires a valid tags table to work}. If this happens, generate a valid
443 tags table in the working directory and try again.
445 @item M-x bashdb @key{RET} @var{file} @key{RET}
447 Run the bash debugger to debug @var{file}, a shell script.
449 @item M-x perldb @key{RET} @var{file} @key{RET}
451 Run the Perl interpreter in debug mode to debug @var{file}, a Perl program.
453 @item M-x jdb @key{RET} @var{file} @key{RET}
455 Run the Java debugger to debug @var{file}.
457 @item M-x pdb @key{RET} @var{file} @key{RET}
459 Run the Python debugger to debug @var{file}.
462 Each of these commands takes one argument: a command line to invoke
463 the debugger. In the simplest case, specify just the name of the
464 executable file you want to debug. You may also use options that the
465 debugger supports. However, shell wildcards and variables are not
466 allowed. GUD assumes that the first argument not starting with a
467 @samp{-} is the executable file name.
469 @node Debugger Operation
470 @subsection Debugger Operation
472 @cindex fringes, and current execution line in GUD
473 When you run a debugger with GUD, the debugger uses an Emacs buffer
474 for its ordinary input and output. This is called the GUD buffer. The
475 debugger displays the source files of the program by visiting them in
476 Emacs buffers. An arrow (@samp{=>}) in one of these buffers indicates
477 the current execution line.@footnote{Under a window system, the arrow
478 appears in the left fringe of the Emacs window.} Moving point in this
479 buffer does not move the arrow.
481 You can start editing these source files at any time in the buffers
482 that display them. The arrow is not part of the file's
483 text; it appears only on the screen. If you do modify a source file,
484 keep in mind that inserting or deleting lines will throw off the arrow's
485 positioning; GUD has no way of figuring out which line corresponded
486 before your changes to the line number in a debugger message. Also,
487 you'll typically have to recompile and restart the program for your
488 changes to be reflected in the debugger's tables.
490 If you wish, you can control your debugger process entirely through the
491 debugger buffer, which uses a variant of Shell mode. All the usual
492 commands for your debugger are available, and you can use the Shell mode
493 history commands to repeat them. @xref{Shell Mode}.
495 @cindex tooltips with GUD
496 @vindex tooltip-gud-modes
497 @vindex gud-tooltip-mode
498 @vindex gud-tooltip-echo-area
499 The Tooltip facility (@pxref{Tooltips}) provides support for GUD@.
500 You activate this feature by turning on the minor mode
501 @code{gud-tooltip-mode}. Then you can display a variable's value in a
502 tooltip simply by pointing at it with the mouse. In graphical mode,
503 with a C program, you can also display the @code{#define} directive
504 associated with an identifier when the program is not executing. This
505 operates in the GUD buffer and in source buffers with major modes in
506 the list @code{gud-tooltip-modes}. If the variable
507 @code{gud-tooltip-echo-area} is non-@code{nil} then the help text is
508 displayed in the echo area.
510 @node Commands of GUD
511 @subsection Commands of GUD
513 The GUD interaction buffer uses a variant of Shell mode, so the
514 commands of Shell mode are available (@pxref{Shell Mode}). GUD mode
515 also provides commands for setting and clearing breakpoints, for
516 selecting stack frames, and for stepping through the program. These
517 commands are available both in the GUD buffer and globally, but with
518 different key bindings. It also has its own toolbar from which you
519 can invoke the more common commands by clicking on the appropriate
520 icon. This is particularly useful for repetitive commands like
521 gud-next and gud-step and allows the user to hide the GUD buffer.
523 The breakpoint commands are normally used in source file buffers,
524 because that is the easiest way to specify where to set or clear the
525 breakpoint. Here's the global command to set a breakpoint:
530 Set a breakpoint on the source line that point is on.
533 @kindex C-x C-a @r{(GUD)}
534 Here are the other special commands provided by GUD. The keys
535 starting with @kbd{C-c} are available only in the GUD interaction
536 buffer. The key bindings that start with @kbd{C-x C-a} are available in
537 the GUD interaction buffer and also in source files.
541 @kindex C-c C-l @r{(GUD)}
544 Display in another window the last line referred to in the GUD
545 buffer (that is, the line indicated in the last location message).
546 This runs the command @code{gud-refresh}.
549 @kindex C-c C-s @r{(GUD)}
552 Execute a single line of code (@code{gud-step}). If the line contains
553 a function call, execution stops after entering the called function.
556 @kindex C-c C-n @r{(GUD)}
559 Execute a single line of code, stepping across entire function calls
560 at full speed (@code{gud-next}).
563 @kindex C-c C-i @r{(GUD)}
566 Execute a single machine instruction (@code{gud-stepi}).
570 @kindex C-c C-r @r{(GUD)}
573 Continue execution without specifying any stopping point. The program
574 will run until it hits a breakpoint, terminates, or gets a signal that
575 the debugger is checking for (@code{gud-cont}).
579 @kindex C-c C-d @r{(GUD)}
582 Delete the breakpoint(s) on the current source line, if any
583 (@code{gud-remove}). If you use this command in the GUD interaction
584 buffer, it applies to the line where the program last stopped.
587 @kindex C-c C-t @r{(GUD)}
590 Set a temporary breakpoint on the current source line, if any.
591 If you use this command in the GUD interaction buffer,
592 it applies to the line where the program last stopped.
595 The above commands are common to all supported debuggers. If you are
596 using GDB or (some versions of) DBX, these additional commands are available:
600 @kindex C-c < @r{(GUD)}
603 Select the next enclosing stack frame (@code{gud-up}). This is
604 equivalent to the @samp{up} command.
607 @kindex C-c > @r{(GUD)}
610 Select the next inner stack frame (@code{gud-down}). This is
611 equivalent to the @samp{down} command.
614 If you are using GDB, these additional key bindings are available:
618 @kindex C-c C-r @r{(GUD)}
621 Start execution of the program (@code{gud-run}).
624 @kindex C-c C-u @r{(GUD)}
627 Continue execution to the current line. The program will run until
628 it hits a breakpoint, terminates, gets a signal that the debugger is
629 checking for, or reaches the line on which the cursor currently sits
633 @kindex TAB @r{(GUD)}
634 @findex gud-gdb-complete-command
635 With GDB, complete a symbol name (@code{gud-gdb-complete-command}).
636 This key is available only in the GUD interaction buffer, and requires
637 GDB versions 4.13 and later.
640 @kindex C-c C-f @r{(GUD)}
643 Run the program until the selected stack frame returns (or until it
644 stops for some other reason).
647 @kindex C-x C-a C-j @r{(GUD)}
649 Only useful in a source buffer, (@code{gud-jump}) transfers the
650 program's execution point to the current line. In other words, the
651 next line that the program executes will be the one where you gave the
652 command. If the new execution line is in a different function from
653 the previously one, GDB prompts for confirmation since the results may
654 be bizarre. See the GDB manual entry regarding @code{jump} for
658 These commands interpret a numeric argument as a repeat count, when
661 Because @key{TAB} serves as a completion command, you can't use it to
662 enter a tab as input to the program you are debugging with GDB.
663 Instead, type @kbd{C-q @key{TAB}} to enter a tab.
665 @node GUD Customization
666 @subsection GUD Customization
668 @vindex gdb-mode-hook
669 @vindex dbx-mode-hook
670 @vindex sdb-mode-hook
671 @vindex xdb-mode-hook
672 @vindex perldb-mode-hook
673 @vindex pdb-mode-hook
674 @vindex jdb-mode-hook
675 On startup, GUD runs one of the following hooks: @code{gdb-mode-hook},
676 if you are using GDB; @code{dbx-mode-hook}, if you are using DBX;
677 @code{sdb-mode-hook}, if you are using SDB; @code{xdb-mode-hook}, if you
678 are using XDB; @code{perldb-mode-hook}, for Perl debugging mode;
679 @code{pdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB. You can
680 use these hooks to define custom key bindings for the debugger
681 interaction buffer. @xref{Hooks}.
683 Here is a convenient way to define a command that sends a particular
684 command string to the debugger, and set up a key binding for it in the
685 debugger interaction buffer:
689 (gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring})
692 This defines a command named @var{function} which sends
693 @var{cmdstring} to the debugger process, and gives it the documentation
694 string @var{docstring}. You can then use the command @var{function} in any
695 buffer. If @var{binding} is non-@code{nil}, @code{gud-def} also binds
696 the command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to
697 @kbd{C-x C-a @var{binding}} generally.
699 The command string @var{cmdstring} may contain certain
700 @samp{%}-sequences that stand for data to be filled in at the time
701 @var{function} is called:
705 The name of the current source file. If the current buffer is the GUD
706 buffer, then the ``current source file'' is the file that the program
708 @c This said, ``the name of the file the program counter was in at the last breakpoint.''
709 @c But I suspect it is really the last stop file.
712 The number of the current source line. If the current buffer is the GUD
713 buffer, then the ``current source line'' is the line that the program
717 The text of the C lvalue or function-call expression at or adjacent to point.
720 The text of the hexadecimal address at or adjacent to point.
723 The numeric argument of the called function, as a decimal number. If
724 the command is used without a numeric argument, @samp{%p} stands for the
727 If you don't use @samp{%p} in the command string, the command you define
728 ignores any numeric argument.
731 @node GDB Graphical Interface
732 @subsection GDB Graphical Interface
734 By default, the command @code{gdb} starts GDB using a graphical
735 interface where you view and control the program's data using Emacs
736 windows. You can still interact with GDB through the GUD buffer, but
737 the point of this mode is that you can do it through menus and clicks,
738 without needing to know GDB commands. For example, you can click
739 @kbd{Mouse-1} on a line of the source buffer, in the fringe or display
740 margin, to set a breakpoint there. If a breakpoint already exists on
741 that line, this action will remove it
742 (@code{gdb-mouse-set-clear-breakpoint}). Where Emacs uses the margin
743 to display breakpoints, it is also possible to enable or disable them
744 when you click @kbd{Mouse-3} there
745 (@code{gdb-mouse-toggle--breakpoint}).
747 @vindex gud-gdb-command-name
749 You can also run GDB in text command mode, which creates a buffer
750 for input and output to GDB. To do this, set
751 @code{gud-gdb-command-name} to @code{"gdb --fullname"} or edit the
752 startup command in the minibuffer to say that. You need to do use
753 text command mode to run multiple debugging sessions within one Emacs
754 session. If you have customised @code{gud-gdb-command-name} in that
755 way, then you can use @kbd{M-x gdba} to invoke GDB in graphical mode.
758 * Layout:: Control the number of displayed buffers.
759 * Breakpoints Buffer:: A breakpoint control panel.
760 * Stack Buffer:: Select a frame from the call stack.
761 * Watch Expressions:: Monitor variable values in the speedbar.
762 * Other Buffers:: Input/output, locals, registers, assembler, threads
767 @subsubsection Layout
768 @cindex GDB User Interface layout
770 @findex gdb-many-windows
771 @vindex gdb-many-windows
773 If the variable @code{gdb-many-windows} is @code{nil} (the default
774 value) then gdb just pops up the GUD buffer unless the variable
775 @code{gdb-show-main} is non-@code{nil}. In this case it starts with
776 two windows: one displaying the GUD buffer and the other with the
777 source file with the main routine of the inferior.
779 If @code{gdb-many-windows} is non-@code{nil}, regardless of the value of
780 @code{gdb-show-main}, the layout below will appear unless
781 @code{gdb-use-inferior-io-buffer} is @code{nil}. In this case the
782 source buffer occupies the full width of the frame.
784 @multitable @columnfractions .5 .5
785 @item GUD buffer (I/O of GDB)
790 @tab Input/Output (of inferior) buffer
794 @tab Breakpoints buffer
797 To toggle this layout, do @kbd{M-x gdb-many-windows}.
799 @findex gdb-restore-windows
800 If you change the window layout, for example, while editing and
801 re-compiling your program, then you can restore it with the command
802 @code{gdb-restore-windows}.
804 You may also choose which additional buffers you want to display,
805 either in the same frame or a different one. Select GDB-windows or
806 GDB-Frames from the menu-bar under the heading GUD. If the menu-bar
807 is unavailable, type @code{M-x
808 gdb-display-@var{buffertype}-buffer} or @code{M-x
809 gdb-frame-@var{buffertype}-buffer} respectively, where @var{buffertype}
810 is the relevant buffer type e.g breakpoints.
812 When you finish debugging then kill the GUD buffer with @kbd{C-x k},
813 which will also kill all the buffers associated with the session.
814 However you need not do this if, after editing and re-compiling your
815 source code within Emacs, you wish continue debugging. When you
816 restart execution, GDB will automatically find your new executable.
817 Keeping the GUD buffer has the advantage of keeping the shell history
818 as well as GDB's breakpoints. You need to check, however, that the
819 breakpoints in the recently edited code are still where you want them.
821 @node Breakpoints Buffer
822 @subsubsection Breakpoints Buffer
824 The breakpoints buffer shows the existing breakpoints and watchpoints
825 (@pxref{Breakpoints,,, gdb, The GNU debugger}). It has three special
830 @kindex SPC @r{(GDB breakpoints buffer)}
831 @findex gdb-toggle-breakpoint
832 Enable/disable the breakpoint at the current line
833 (@code{gdb-toggle-breakpoint}). On a graphical display, this changes
834 the color of a bullet in the margin of the source buffer at the
835 relevant line. This is red when the breakpoint is enabled and grey
836 when it is disabled. Text-only terminals correspondingly display
837 a @samp{B} or @samp{b}.
840 @kindex d @r{(GDB breakpoints buffer)}
841 @findex gdb-delete-breakpoint
842 Delete the breakpoint at the current line (@code{gdb-delete-breakpoint}).
845 @kindex RET @r{(GDB breakpoints buffer)}
846 @findex gdb-goto-breakpoint
847 Display the file in the source buffer at the breakpoint specified at
848 the current line (@code{gdb-goto-breakpoint}). Alternatively, click
849 @kbd{Mouse-2} on the breakpoint that you wish to visit.
853 @subsubsection Stack Buffer
855 The stack buffer displays a @dfn{call stack}, with one line for each
856 of the nested subroutine calls (@dfn{stack frames}) now active in the
857 program. @xref{Backtrace,,info stack, gdb, The GNU debugger}.
859 The selected frame is displayed in reverse contrast. Move point to
860 any frame in the stack and type @key{RET} to select it (@code{gdb-frames-select})
861 and display the associated source in the source buffer. Alternatively,
862 click @kbd{Mouse-2} to make the selected frame become the current one.
863 If the locals buffer is displayed then its contents update to display
864 the variables that are local to the new frame.
866 @node Watch Expressions
867 @subsubsection Watch Expressions
868 @cindex Watching expressions in GDB
870 If you want to see how a variable changes each time your program stops
871 then place the cursor over the variable name and click on the watch
872 icon in the toolbar (@code{gud-watch}).
874 Each watch expression is displayed in the speedbar. Complex data
875 types, such as arrays, structures and unions are represented in a tree
876 format. To expand or contract a complex data type, click @kbd{Mouse-2}
877 on the tag to the left of the expression.
879 @kindex RET @r{(GDB speedbar)}
880 @findex gdb-var-delete
881 With the cursor over the root expression of a complex data type, type
882 @kbd{D} to delete it from the speedbar
883 (@code{gdb-var-delete}).
885 @findex gdb-edit-value
886 With the cursor over a simple data type or an element of a complex
887 data type which holds a value, type @key{RET} or click @kbd{Mouse-2} to edit
888 its value. A prompt for a new value appears in the mini-buffer
889 (@code{gdb-edit-value}).
891 If you set the variable @code{gdb-show-changed-values} to
892 non-@code{nil} (the default value), then Emacs will use
893 font-lock-warning-face to display values that have recently changed in
896 If you set the variable @code{gdb-use-colon-colon-notation} to a
897 non-@code{nil} value, then, in C, Emacs will use the
898 FUNCTION::VARIABLE format to display variables in the speedbar.
899 Since this does not work for variables defined in compound statements,
900 the default value is @code{nil}.
903 @subsubsection Other Buffers
906 @item Input/Output Buffer
907 If the variable @code{gdb-use-inferior-io-buffer} is non-@code{nil},
908 the executable program that is being debugged takes its input and
909 displays its output here. Some of the commands from shell mode are
910 available here. @xref{Shell Mode}.
913 The locals buffer displays the values of local variables of the
914 current frame for simple data types (@pxref{Frame Info,,, gdb, The GNU
917 Arrays and structures display their type only. You must display them
918 separately to examine their values. @xref{Watch Expressions}.
920 @item Registers Buffer
921 The registers buffer displays the values held by the registers
922 (@pxref{Registers,,, gdb, The GNU debugger}).
924 @item Assembler Buffer
925 The assembler buffer displays the current frame as machine code. An
926 overlay arrow points to the current instruction and you can set and
927 remove breakpoints as with the source buffer. Breakpoint icons also
928 appear in the fringe or margin.
932 The threads buffer displays a summary of all threads currently in your
933 program (@pxref{Threads,,, gdb, The GNU debugger}). Move point to
934 any thread in the list and type @key{RET} to make it become the
935 current thread (@code{gdb-threads-select}) and display the associated
936 source in the source buffer. Alternatively, click @kbd{Mouse-2} to
937 make the selected thread become the current one.
941 The memory buffer allows the user to examine sections of program
942 memory (@pxref{Memory,,, gdb, The GNU debugger}). Click @kbd{Mouse-1}
943 on the appropriate part of the header line to change the starting
944 address or number of data items that the buffer displays.
945 Click @kbd{Mouse-3} on the header line to select the display format
946 or unit size for these data items.
951 @section Executing Lisp Expressions
953 Emacs has several different major modes for Lisp and Scheme. They are
954 the same in terms of editing commands, but differ in the commands for
955 executing Lisp expressions. Each mode has its own purpose.
958 @item Emacs-Lisp mode
959 The mode for editing source files of programs to run in Emacs Lisp.
960 This mode defines @kbd{C-M-x} to evaluate the current defun.
961 @xref{Lisp Libraries}.
962 @item Lisp Interaction mode
963 The mode for an interactive session with Emacs Lisp. It defines
964 @kbd{C-j} to evaluate the sexp before point and insert its value in the
965 buffer. @xref{Lisp Interaction}.
967 The mode for editing source files of programs that run in Lisps other
968 than Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defun
969 to an inferior Lisp process. @xref{External Lisp}.
970 @item Inferior Lisp mode
971 The mode for an interactive session with an inferior Lisp process.
972 This mode combines the special features of Lisp mode and Shell mode
973 (@pxref{Shell Mode}).
975 Like Lisp mode but for Scheme programs.
976 @item Inferior Scheme mode
977 The mode for an interactive session with an inferior Scheme process.
980 Most editing commands for working with Lisp programs are in fact
981 available globally. @xref{Programs}.
984 @section Libraries of Lisp Code for Emacs
986 @cindex loading Lisp code
988 Lisp code for Emacs editing commands is stored in files whose names
989 conventionally end in @file{.el}. This ending tells Emacs to edit them in
990 Emacs-Lisp mode (@pxref{Executing Lisp}).
993 To execute a file of Emacs Lisp code, use @kbd{M-x load-file}. This
994 command reads a file name using the minibuffer and then executes the
995 contents of that file as Lisp code. It is not necessary to visit the
996 file first; in any case, this command reads the file as found on disk,
997 not text in an Emacs buffer.
1000 @findex load-library
1001 Once a file of Lisp code is installed in the Emacs Lisp library
1002 directories, users can load it using @kbd{M-x load-library}. Programs can
1003 load it by calling @code{load-library}, or with @code{load}, a more primitive
1004 function that is similar but accepts some additional arguments.
1006 @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it
1007 searches a sequence of directories and tries three file names in each
1008 directory. Suppose your argument is @var{lib}; the three names are
1009 @file{@var{lib}.elc}, @file{@var{lib}.el}, and lastly just
1010 @file{@var{lib}}. If @file{@var{lib}.elc} exists, it is by convention
1011 the result of compiling @file{@var{lib}.el}; it is better to load the
1012 compiled file, since it will load and run faster.
1014 If @code{load-library} finds that @file{@var{lib}.el} is newer than
1015 @file{@var{lib}.elc} file, it issues a warning, because it's likely that
1016 somebody made changes to the @file{.el} file and forgot to recompile
1019 Because the argument to @code{load-library} is usually not in itself
1020 a valid file name, file name completion is not available. Indeed, when
1021 using this command, you usually do not know exactly what file name
1025 The sequence of directories searched by @kbd{M-x load-library} is
1026 specified by the variable @code{load-path}, a list of strings that are
1027 directory names. The default value of the list contains the directory where
1028 the Lisp code for Emacs itself is stored. If you have libraries of
1029 your own, put them in a single directory and add that directory
1030 to @code{load-path}. @code{nil} in this list stands for the current default
1031 directory, but it is probably not a good idea to put @code{nil} in the
1032 list. If you find yourself wishing that @code{nil} were in the list,
1033 most likely what you really want to do is use @kbd{M-x load-file}
1037 Often you do not have to give any command to load a library, because
1038 the commands defined in the library are set up to @dfn{autoload} that
1039 library. Trying to run any of those commands calls @code{load} to load
1040 the library; this replaces the autoload definitions with the real ones
1044 Emacs Lisp code can be compiled into byte-code which loads faster,
1045 takes up less space when loaded, and executes faster. @xref{Byte
1046 Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual}.
1047 By convention, the compiled code for a library goes in a separate file
1048 whose name consists of the library source file with @samp{c} appended.
1049 Thus, the compiled code for @file{foo.el} goes in @file{foo.elc}.
1050 That's why @code{load-library} searches for @samp{.elc} files first.
1052 @vindex load-dangerous-libraries
1053 @cindex Lisp files byte-compiled by XEmacs
1054 By default, Emacs refuses to load compiled Lisp files which were
1055 compiled with XEmacs, a modified versions of Emacs---they can cause
1056 Emacs to crash. Set the variable @code{load-dangerous-libraries} to
1057 @code{t} if you want to try loading them.
1060 @section Evaluating Emacs Lisp Expressions
1061 @cindex Emacs-Lisp mode
1062 @cindex mode, Emacs-Lisp
1064 @findex emacs-lisp-mode
1065 Lisp programs intended to be run in Emacs should be edited in
1066 Emacs-Lisp mode; this happens automatically for file names ending in
1067 @file{.el}. By contrast, Lisp mode itself is used for editing Lisp
1068 programs intended for other Lisp systems. To switch to Emacs-Lisp mode
1069 explicitly, use the command @kbd{M-x emacs-lisp-mode}.
1071 For testing of Lisp programs to run in Emacs, it is often useful to
1072 evaluate part of the program as it is found in the Emacs buffer. For
1073 example, after changing the text of a Lisp function definition,
1074 evaluating the definition installs the change for future calls to the
1075 function. Evaluation of Lisp expressions is also useful in any kind of
1076 editing, for invoking noninteractive functions (functions that are
1081 Read a single Lisp expression in the minibuffer, evaluate it, and print
1082 the value in the echo area (@code{eval-expression}).
1084 Evaluate the Lisp expression before point, and print the value in the
1085 echo area (@code{eval-last-sexp}).
1087 Evaluate the defun containing or after point, and print the value in
1088 the echo area (@code{eval-defun}).
1089 @item M-x eval-region
1090 Evaluate all the Lisp expressions in the region.
1091 @item M-x eval-current-buffer
1092 Evaluate all the Lisp expressions in the buffer.
1096 @c This uses ``colon'' instead of a literal `:' because Info cannot
1097 @c cope with a `:' in a menu
1098 @kindex M-@key{colon}
1103 @findex eval-expression
1104 @kbd{M-:} (@code{eval-expression}) is the most basic command for evaluating
1105 a Lisp expression interactively. It reads the expression using the
1106 minibuffer, so you can execute any expression on a buffer regardless of
1107 what the buffer contains. When the expression is evaluated, the current
1108 buffer is once again the buffer that was current when @kbd{M-:} was
1111 @kindex C-M-x @r{(Emacs-Lisp mode)}
1113 In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the command
1114 @code{eval-defun}, which parses the defun containing or following point
1115 as a Lisp expression and evaluates it. The value is printed in the echo
1116 area. This command is convenient for installing in the Lisp environment
1117 changes that you have just made in the text of a function definition.
1119 @kbd{C-M-x} treats @code{defvar} expressions specially. Normally,
1120 evaluating a @code{defvar} expression does nothing if the variable it
1121 defines already has a value. But @kbd{C-M-x} unconditionally resets the
1122 variable to the initial value specified in the @code{defvar} expression.
1123 @code{defcustom} expressions are treated similarly.
1124 This special feature is convenient for debugging Lisp programs.
1125 Typing @kbd{C-M-x} on a @code{defface} expression reinitializes
1126 the face according to the @code{defface} specification.
1129 @findex eval-last-sexp
1130 The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Lisp
1131 expression preceding point in the buffer, and displays the value in the
1132 echo area. It is available in all major modes, not just Emacs-Lisp
1133 mode. It does not treat @code{defvar} specially.
1135 When the result of an evaluation is an integer, you can type
1136 @kbd{C-x C-e} a second time to display the value of the integer result
1137 in additional formats (octal, hexadecimal, and character).
1139 If @kbd{C-M-x}, @kbd{C-x C-e}, or @kbd{M-:} is given a numeric
1140 argument, it inserts the value into the current buffer at point, rather
1141 than displaying it in the echo area. The argument's value does not
1145 @findex eval-current-buffer
1146 The most general command for evaluating Lisp expressions from a buffer
1147 is @code{eval-region}. @kbd{M-x eval-region} parses the text of the
1148 region as one or more Lisp expressions, evaluating them one by one.
1149 @kbd{M-x eval-current-buffer} is similar but evaluates the entire
1150 buffer. This is a reasonable way to install the contents of a file of
1151 Lisp code that you are ready to test. Later, as you find bugs and
1152 change individual functions, use @kbd{C-M-x} on each function that you
1153 change. This keeps the Lisp world in step with the source file.
1155 @vindex eval-expression-print-level
1156 @vindex eval-expression-print-length
1157 @vindex eval-expression-debug-on-error
1158 The customizable variables @code{eval-expression-print-level} and
1159 @code{eval-expression-print-length} control the maximum depth and length
1160 of lists to print in the result of the evaluation commands before
1161 abbreviating them. @code{eval-expression-debug-on-error} controls
1162 whether evaluation errors invoke the debugger when these commands are
1165 @node Lisp Interaction
1166 @section Lisp Interaction Buffers
1168 The buffer @samp{*scratch*} which is selected when Emacs starts up is
1169 provided for evaluating Lisp expressions interactively inside Emacs.
1171 The simplest way to use the @samp{*scratch*} buffer is to insert Lisp
1172 expressions and type @kbd{C-j} after each expression. This command
1173 reads the Lisp expression before point, evaluates it, and inserts the
1174 value in printed representation before point. The result is a complete
1175 typescript of the expressions you have evaluated and their values.
1177 The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which
1178 is the same as Emacs-Lisp mode except for the binding of @kbd{C-j}.
1180 @findex lisp-interaction-mode
1181 The rationale for this feature is that Emacs must have a buffer when
1182 it starts up, but that buffer is not useful for editing files since a
1183 new buffer is made for every file that you visit. The Lisp interpreter
1184 typescript is the most useful thing I can think of for the initial
1185 buffer to do. Type @kbd{M-x lisp-interaction-mode} to put the current
1186 buffer in Lisp Interaction mode.
1189 An alternative way of evaluating Emacs Lisp expressions interactively
1190 is to use Inferior Emacs-Lisp mode, which provides an interface rather
1191 like Shell mode (@pxref{Shell Mode}) for evaluating Emacs Lisp
1192 expressions. Type @kbd{M-x ielm} to create an @samp{*ielm*} buffer
1193 which uses this mode.
1196 @section Running an External Lisp
1198 Emacs has facilities for running programs in other Lisp systems. You can
1199 run a Lisp process as an inferior of Emacs, and pass expressions to it to
1200 be evaluated. You can also pass changed function definitions directly from
1201 the Emacs buffers in which you edit the Lisp programs to the inferior Lisp
1205 @vindex inferior-lisp-program
1207 To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runs
1208 the program named @code{lisp}, the same program you would run by typing
1209 @code{lisp} as a shell command, with both input and output going through
1210 an Emacs buffer named @samp{*lisp*}. That is to say, any ``terminal
1211 output'' from Lisp will go into the buffer, advancing point, and any
1212 ``terminal input'' for Lisp comes from text in the buffer. (You can
1213 change the name of the Lisp executable file by setting the variable
1214 @code{inferior-lisp-program}.)
1216 To give input to Lisp, go to the end of the buffer and type the input,
1217 terminated by @key{RET}. The @samp{*lisp*} buffer is in Inferior Lisp
1218 mode, which combines the special characteristics of Lisp mode with most
1219 of the features of Shell mode (@pxref{Shell Mode}). The definition of
1220 @key{RET} to send a line to a subprocess is one of the features of Shell
1224 For the source files of programs to run in external Lisps, use Lisp
1225 mode. This mode can be selected with @kbd{M-x lisp-mode}, and is used
1226 automatically for files whose names end in @file{.l}, @file{.lsp}, or
1227 @file{.lisp}, as most Lisp systems usually expect.
1229 @kindex C-M-x @r{(Lisp mode)}
1230 @findex lisp-eval-defun
1231 When you edit a function in a Lisp program you are running, the easiest
1232 way to send the changed definition to the inferior Lisp process is the key
1233 @kbd{C-M-x}. In Lisp mode, this runs the function @code{lisp-eval-defun},
1234 which finds the defun around or following point and sends it as input to
1235 the Lisp process. (Emacs can send input to any inferior process regardless
1236 of what buffer is current.)
1238 Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing programs
1239 to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
1240 programs to be run in Emacs): in both modes it has the effect of installing
1241 the function definition that point is in, but the way of doing so is
1242 different according to where the relevant Lisp environment is found.
1243 @xref{Executing Lisp}.
1246 arch-tag: 9c3c2f71-b332-4144-8500-3ff9945a50ed