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 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
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.
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
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.
34 @section Running Compilations under Emacs
35 @cindex inferior process
37 @cindex compilation errors
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.
47 Run a compiler asynchronously under Emacs, with error messages going to
48 the @samp{*compilation*} buffer.
50 Invoke a compiler with the same command as in the last invocation of
52 @item M-x kill-compilation
53 Kill the running compilation subprocess.
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
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
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.
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.
93 @cindex compilation buffer, keeping point at end
94 @vindex compilation-scroll-output
95 If you set the variable @code{compilation-scroll-output} to a
96 non-@code{nil} value, then the compilation buffer always scrolls to
97 follow output as it comes in.
100 To rerun the last compilation with the same command, type @kbd{M-x
101 recompile}. This automatically reuses the compilation command from
102 the last invocation of @kbd{M-x compile}. It also reuses the
103 @samp{*compilation*} buffer and starts the compilation in its default
104 directory, which is the directory in which the previous compilation
107 When the compiler process terminates, for whatever reason, the mode
108 line of the @samp{*compilation*} buffer changes to say @samp{exit}
109 (followed by the exit code, @samp{[0]} for a normal exit), or
110 @samp{signal} (if a signal terminated the process), instead of
113 @findex kill-compilation
114 Starting a new compilation also kills any compilation already
115 running in @samp{*compilation*}, as the buffer can only handle one
116 compilation at any time. However, @kbd{M-x compile} asks for
117 confirmation before actually killing a compilation that is running.
118 You can also kill the compilation process with @kbd{M-x
121 If you want to run two compilations at once, you should start the
122 first one, then rename the @samp{*compilation*} buffer (perhaps using
123 @code{rename-uniquely}; @pxref{Misc Buffer}), and start the other
124 compilation. That will create a new @samp{*compilation*} buffer.
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 @cindex Compilation mode
158 @cindex mode, Compilation
159 The @samp{*compilation*} buffer uses a special major mode,
160 Compilation mode, whose main feature is to provide a convenient way to
161 visit the source line corresponding to an error message. These
162 commands are also available in other special buffers that list
163 locations in files, including those made by @kbd{M-x grep} and
170 Visit the locus of the next error message or match.
173 Visit the locus of the previous error message or match.
175 Visit the locus of the error message that point is on.
176 This command is used in the compilation buffer.
178 Visit the locus of the error message that you click on.
180 Find and highlight the locus of the next error message, without
181 selecting the source buffer.
183 Find and highlight the locus of the previous error message, without
184 selecting the source buffer.
186 Move point to the next error for a different file than the current
189 Move point to the previous error for a different file than the current
192 Toggle Next Error Follow minor mode, which makes cursor motion in the
193 compilation buffer produce automatic source display.
196 @findex compile-goto-error
197 @vindex compilation-auto-jump-to-first-error
198 You can visit the source for any particular error message by moving
199 point in the @samp{*compilation*} buffer to that error message and
200 typing @key{RET} (@code{compile-goto-error}). Alternatively, you can
201 click @kbd{Mouse-2} on the error message; you need not switch to the
202 @samp{*compilation*} buffer first. If you set the variable
203 @code{compilation-auto-jump-to-first-error} to a non-@code{nil} value,
204 Emacs automatically jumps to the first error (if any exists) once
205 compilation finishes.
211 @vindex next-error-highlight
212 To parse the compiler error messages sequentially, type @kbd{C-x `}
213 (@code{next-error}). The character following the @kbd{C-x} is the
214 backquote or ``grave accent,'' not the single-quote. This command is
215 available in all buffers, not just in @samp{*compilation*}; it
216 displays the next error message at the top of one window and source
217 location of the error in another window. It also temporarily
218 highlights the relevant source line, for a period controlled by the
219 variable @code{next-error-highlight}.
221 The first time @w{@kbd{C-x `}} is used after the start of a compilation,
222 it moves to the first error's location. Subsequent uses of @kbd{C-x
223 `} advance down to subsequent errors. If you visit a specific error
224 message with @key{RET} or @kbd{Mouse-2}, subsequent @w{@kbd{C-x `}}
225 commands advance from there. When @w{@kbd{C-x `}} gets to the end of the
226 buffer and finds no more error messages to visit, it fails and signals
227 an Emacs error. @w{@kbd{C-u C-x `}} starts scanning from the beginning of
228 the compilation buffer, and goes to the first error's location.
230 @vindex compilation-skip-threshold
231 By default, @w{@kbd{C-x `}} skips less important messages. The variable
232 @code{compilation-skip-threshold} controls this. If its value is 2,
233 @w{@kbd{C-x `}} skips anything less than error, 1 skips anything less
234 than warning, and 0 doesn't skip any messages. The default is 1.
236 When the window has a left fringe, an arrow in the fringe points to
237 the current message in the compilation buffer. The variable
238 @code{compilation-context-lines} controls the number of lines of
239 leading context to display before the current message. Going to an
240 error message location scrolls the @samp{*compilation*} buffer to put
241 the message that far down from the top. The value @code{nil} is
242 special: if there's a left fringe, the window doesn't scroll at all
243 if the message is already visible. If there is no left fringe,
244 @code{nil} means display the message at the top of the window.
246 If you're not in the compilation buffer when you run
247 @code{next-error}, Emacs will look for a buffer that contains error
248 messages. First, it looks for one displayed in the selected frame,
249 then for one that previously had @code{next-error} called on it, and
250 then at the current buffer. Finally, Emacs looks at all the remaining
251 buffers. @code{next-error} signals an error if it can't find any such
254 @vindex compilation-error-regexp-alist
255 @vindex grep-regexp-alist
256 To parse messages from the compiler, Compilation mode uses the
257 variable @code{compilation-error-regexp-alist} which lists various
258 formats of error messages and tells Emacs how to extract the source file
259 and the line number from the text of a message. If your compiler isn't
260 supported, you can tailor Compilation mode to it by adding elements to
261 that list. A similar variable @code{grep-regexp-alist} tells Emacs how
262 to parse output of a @code{grep} command.
264 @findex compilation-next-error
265 @findex compilation-previous-error
266 @findex compilation-next-file
267 @findex compilation-previous-file
268 Compilation mode also redefines the keys @key{SPC} and @key{DEL} to
269 scroll by screenfuls, and @kbd{M-n} (@code{compilation-next-error})
270 and @kbd{M-p} (@code{compilation-previous-error}) to move to the next
271 or previous error message. You can also use @kbd{M-@{}
272 (@code{compilation-next-file} and @kbd{M-@}}
273 (@code{compilation-previous-file}) to move up or down to an error
274 message for a different source file.
276 @cindex Next Error Follow mode
277 @findex next-error-follow-minor-mode
278 You can type @kbd{C-c C-f} to toggle Next Error Follow mode. In
279 this minor mode, ordinary cursor motion in the compilation buffer
280 automatically updates the source buffer. For instance, moving the
281 cursor to the next error message causes the location of that error to
282 be displayed immediately.
284 The features of Compilation mode are also available in a minor mode
285 called Compilation Minor mode. This lets you parse error messages in
286 any buffer, not just a normal compilation output buffer. Type @kbd{M-x
287 compilation-minor-mode} to enable the minor mode. This defines the keys
288 @key{RET} and @kbd{Mouse-2}, as in the Compilation major mode.
290 Compilation minor mode works in any buffer, as long as the contents
291 are in a format that it understands. In an Rlogin buffer (@pxref{Remote
292 Host}), Compilation minor mode automatically accesses remote source
293 files by FTP (@pxref{File Names}).
295 @node Compilation Shell
296 @section Subshells for Compilation
298 Emacs uses a shell to run the compilation command, but specifies the
299 option for a noninteractive shell. This means, in particular, that
300 the shell should start with no prompt. If you find your usual shell
301 prompt making an unsightly appearance in the @samp{*compilation*}
302 buffer, it means you have made a mistake in your shell's init file by
303 setting the prompt unconditionally. (This init file's name may be
304 @file{.bashrc}, @file{.profile}, @file{.cshrc}, @file{.shrc}, or
305 various other things, depending on the shell you use.) The shell init
306 file should set the prompt only if there already is a prompt. Here's
307 how to do it in bash:
310 if [ "$@{PS1+set@}" = set ]
316 And here's how to do it in csh:
319 if ($?prompt) set prompt = @dots{}
322 There may well be other things that your shell's init file
323 ought to do only for an interactive shell. You can use the same
324 method to conditionalize them.
326 The MS-DOS ``operating system'' does not support asynchronous
327 subprocesses; to work around this lack, @kbd{M-x compile} runs the
328 compilation command synchronously on MS-DOS. As a consequence, you must
329 wait until the command finishes before you can do anything else in
332 @inforef{MS-DOS,,emacs-xtra}.
339 @section Searching with Grep under Emacs
341 Just as you can run a compiler from Emacs and then visit the lines
342 with compilation errors, you can also run @code{grep} and then visit
343 the lines on which matches were found. This works by treating the
344 matches reported by @code{grep} as if they were ``errors.'' The
345 buffer of matches uses Grep mode, which is a variant of Compilation
346 mode (@pxref{Compilation Mode}).
351 Run @code{grep} asynchronously under Emacs, with matching lines
352 listed in the buffer named @samp{*grep*}.
356 Run @code{grep} via @code{find}, with user-specified arguments, and
357 collect output in the buffer named @samp{*grep*}.
359 Kill the running @code{grep} subprocess.
363 To run @code{grep}, type @kbd{M-x grep}, then enter a command line
364 that specifies how to run @code{grep}. Use the same arguments you
365 would give @code{grep} when running it normally: a @code{grep}-style
366 regexp (usually in single-quotes to quote the shell's special
367 characters) followed by file names, which may use wildcards. If you
368 specify a prefix argument for @kbd{M-x grep}, it finds the tag
369 (@pxref{Tags}) in the buffer around point, and puts that into the
370 default @code{grep} command.
372 Your command need not simply run @code{grep}; you can use any shell
373 command that produces output in the same format. For instance, you
374 can chain @code{grep} commands, like this:
377 grep -nH -e foo *.el | grep bar | grep toto
380 The output from @code{grep} goes in the @samp{*grep*} buffer. You
381 can find the corresponding lines in the original files using @w{@kbd{C-x
382 `}}, @key{RET}, and so forth, just like compilation errors.
384 Some grep programs accept a @samp{--color} option to output special
385 markers around matches for the purpose of highlighting. You can make
386 use of this feature by setting @code{grep-highlight-matches} to
387 @code{t}. When displaying a match in the source buffer, the exact
388 match will be highlighted, instead of the entire source line.
392 The command @kbd{M-x grep-find} (also available as @kbd{M-x
393 find-grep}) is similar to @kbd{M-x grep}, but it supplies a different
394 initial default for the command---one that runs both @code{find} and
395 @code{grep}, so as to search every file in a directory tree. See also
396 the @code{find-grep-dired} command, in @ref{Dired and Find}.
400 The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep}
401 (recursive grep) are more user-friendly versions of @code{grep} and
402 @code{grep-find}, which prompt separately for the regular expression
403 to match, the files to search, and the base directory for the search.
404 Case sensitivity of the search is controlled by the
405 current value of @code{case-fold-search}.
407 These commands build the shell commands based on the variables
408 @code{grep-template} (for @code{lgrep}) and @code{grep-find-template}
411 The files to search can use aliases defined in the variable
412 @code{grep-files-aliases}.
414 Subdirectories listed in the variable
415 @code{grep-find-ignored-directories} such as those typically used by
416 various version control systems, like CVS and arch, are automatically
417 skipped by @code{rgrep}.
420 @section Finding Syntax Errors On The Fly
421 @cindex checking syntax
423 Flymake mode is a minor mode that performs on-the-fly syntax
424 checking for many programming and markup languages, including C, C++,
425 Perl, HTML, and @TeX{}/La@TeX{}. It is somewhat analogous to Flyspell
426 mode, which performs spell checking for ordinary human languages in a
427 similar fashion (@pxref{Spelling}). As you edit a file, Flymake mode
428 runs an appropriate syntax checking tool in the background, using a
429 temporary copy of the buffer. It then parses the error and warning
430 messages, and highlights the erroneous lines in the buffer. The
431 syntax checking tool used depends on the language; for example, for
432 C/C++ files this is usually the C compiler. Flymake can also use
433 build tools such as @code{make} for checking complicated projects.
435 To activate Flymake mode, type @kbd{M-x flymake-mode}. You can move
436 to the errors spotted by Flymake mode with @kbd{M-x
437 flymake-goto-next-error} and @kbd{M-x flymake-goto-prev-error}. To
438 display any error messages associated with the current line, use
439 @kbd{M-x flymake-display-err-menu-for-current-line}.
441 For more details about using Flymake, see @ref{Top, Flymake,
442 Flymake, flymake, The Flymake Manual}.
445 @section Running Debuggers Under Emacs
450 Emacs provides two separate facilities for using external symbolic
451 debuggers, which are programs for testing and debugging other
455 The Grand Unified Debugger (GUD) provides a simple, text-based
456 interface for a wide variety of symbolic debuggers, including the GNU
457 Debugger (GDB), the Perl debugger, the Python debugger, and the Java
461 The GDB Graphical Interface is an Emacs package that interacts with
462 GDB to turn Emacs into a graphical ``integrated development
463 environment'', or IDE.
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.
471 * GUD:: The Grand Unified Debugger.
472 * GDB Graphical Interface:: A mode that uses GDB features to implement
473 a graphical Emacs debugging environment.
486 @c Do you believe in GUD?
487 The GUD (Grand Unified Debugger) library provides an Emacs interface
488 to a wide variety of symbolic debuggers. Unlike the GDB graphical
489 interface, which only runs GDB (@pxref{GDB Graphical Interface}), GUD
490 can also run DBX, SDB, XDB, Perl's debugging mode, the Python debugger
491 PDB, or the Java Debugger JDB.
494 * Starting GUD:: How to start a debugger subprocess.
495 * Debugger Operation:: Connection between the debugger and source buffers.
496 * Commands of GUD:: Key bindings for common commands.
497 * GUD Customization:: Defining your own commands for GUD.
501 @subsubsection Starting GUD
503 There are several commands for starting a debugger under GUD, each
504 corresponding to a particular debugger program.
507 @item M-x gud-gdb @key{RET} @var{file} @key{RET}
509 Run GDB as a subprocess of Emacs. This command creates a buffer for
510 input and output to GDB, and switches to it. If a GDB buffer already
511 exists, it just switches to that buffer. (To run GDB in an IDE-like
512 graphical interface instead, see @ref{GDB Graphical Interface}.)
514 @item M-x dbx @key{RET} @var{file} @key{RET}
516 Run DBX as a subprocess of Emacs.
518 @item M-x xdb @key{RET} @var{file} @key{RET}
520 @vindex gud-xdb-directories
521 Run XDB as a subprocess of Emacs. Use the variable
522 @code{gud-xdb-directories} to specify directories to search for source
525 @item M-x sdb @key{RET} @var{file} @key{RET}
527 Run SDB as a subprocess of Emacs.
529 Some versions of SDB do not mention source file names in their
530 messages. When you use them, you need to have a valid tags table
531 (@pxref{Tags}) in order for GUD to find functions in the source code.
532 If you have not visited a tags table or the tags table doesn't list
533 one of the functions, you get a message saying @samp{The sdb support
534 requires a valid tags table to work}. If this happens, generate a
535 valid tags table in the working directory and try again.
537 @item M-x perldb @key{RET} @var{file} @key{RET}
539 Run the Perl interpreter in debug mode to debug @var{file}, a Perl program.
541 @item M-x jdb @key{RET} @var{file} @key{RET}
543 Run the Java debugger to debug @var{file}.
545 @item M-x pdb @key{RET} @var{file} @key{RET}
547 Run the Python debugger to debug @var{file}.
550 Each of these commands takes one argument: a command line to invoke
551 the debugger. In the simplest case, specify just the name of the
552 executable file you want to debug. You may also use options that the
553 debugger supports. However, shell wildcards and variables are not
554 allowed. GUD assumes that the first argument not starting with a
555 @samp{-} is the executable file name.
557 @cindex remote host, debugging on
558 Tramp provides a facility to debug programs on remote hosts
559 (@pxref{Running a debugger on a remote host, Running a debugger on a
560 remote host,, tramp, The Tramp Manual}), whereby both the debugger and
561 the program being debugged are on the same remote host. This should
562 not be confused with debugging programs remotely, where the program
563 and the debugger run on different machines, as can be done using the
564 GDB remote debugging feature, for example (@pxref{Remote Debugging,,
565 Debugging Remote Programs, gdb, The GNU debugger}).
567 @node Debugger Operation
568 @subsubsection Debugger Operation
570 @cindex fringes, and current execution line in GUD
571 Generally when you run a debugger with GUD, the debugger uses an Emacs
572 buffer for its ordinary input and output. This is called the GUD
573 buffer. Input and output from the program you are debugging also use
574 this buffer. We call this @dfn{text command mode}. The GDB Graphical
575 Interface can use further buffers (@pxref{GDB Graphical Interface}).
577 The debugger displays the source files of the program by visiting
578 them in Emacs buffers. An arrow in the left fringe indicates the
579 current execution line.@footnote{On a text-only terminal, the arrow
580 appears as @samp{=>} and overlays the first two text columns.} Moving
581 point in this buffer does not move the arrow. The arrow is not part
582 of the file's text; it appears only on the screen.
584 You can start editing these source files at any time in the buffers
585 that display them. If you do modify a source file, keep in mind that
586 inserting or deleting lines will throw off the arrow's positioning;
587 GUD has no way of figuring out which line corresponded before your
588 changes to the line number in a debugger message. Also, you'll
589 typically have to recompile and restart the program for your changes
590 to be reflected in the debugger's tables.
592 @cindex tooltips with GUD
593 @vindex tooltip-gud-modes
594 @vindex gud-tooltip-mode
595 @vindex gud-tooltip-echo-area
596 The Tooltip facility (@pxref{Tooltips}) provides support for GUD@.
597 You activate this feature by turning on the minor mode
598 @code{gud-tooltip-mode}. Then you can display a variable's value in a
599 tooltip simply by pointing at it with the mouse. This operates in the
600 GUD buffer and in source buffers with major modes in the list
601 @code{gud-tooltip-modes}. If the variable @code{gud-tooltip-echo-area}
602 is non-@code{nil} then the variable's value is displayed in the echo
603 area. When debugging a C program using the GDB Graphical Interface, you
604 can also display macro definitions associated with an identifier when
605 the program is not executing.
607 GUD tooltips are disabled when you use GDB in text command mode
608 (@pxref{GDB Graphical Interface}), because displaying an expression's
609 value in GDB can sometimes expand a macro and result in a side effect
610 that interferes with the program's operation. The GDB graphical
611 interface supports GUD tooltips and assures they will not cause side
614 @node Commands of GUD
615 @subsubsection Commands of GUD
617 The GUD interaction buffer uses a variant of Shell mode, so the
618 Emacs commands of Shell mode are available (@pxref{Shell Mode}). All
619 the usual commands for your debugger are available, and you can use
620 the Shell mode history commands to repeat them. If you wish, you can
621 control your debugger process entirely through this buffer.
623 GUD mode also provides commands for setting and clearing
624 breakpoints, for selecting stack frames, and for stepping through the
625 program. These commands are available both in the GUD buffer and
626 globally, but with different key bindings. It also has its own tool
627 bar from which you can invoke the more common commands by clicking on
628 the appropriate icon. This is particularly useful for repetitive
629 commands like @code{gud-next} and @code{gud-step}, and allows you to
630 keep the GUD buffer hidden.
632 The breakpoint commands are normally used in source file buffers,
633 because that is the easiest way to specify where to set or clear the
634 breakpoint. Here's the global command to set a breakpoint:
639 Set a breakpoint on the source line that point is on.
642 @kindex C-x C-a @r{(GUD)}
643 Here are the other special commands provided by GUD@. The keys
644 starting with @kbd{C-c} are available only in the GUD interaction
645 buffer. The key bindings that start with @kbd{C-x C-a} are available
646 in the GUD interaction buffer and also in source files. Some of these
647 commands are not available to all the supported debuggers.
651 @kindex C-c C-l @r{(GUD)}
654 Display in another window the last line referred to in the GUD
655 buffer (that is, the line indicated in the last location message).
656 This runs the command @code{gud-refresh}.
659 @kindex C-c C-s @r{(GUD)}
662 Execute a single line of code (@code{gud-step}). If the line contains
663 a function call, execution stops after entering the called function.
666 @kindex C-c C-n @r{(GUD)}
669 Execute a single line of code, stepping across entire function calls
670 at full speed (@code{gud-next}).
673 @kindex C-c C-i @r{(GUD)}
676 Execute a single machine instruction (@code{gud-stepi}).
679 @kindex C-c C-p @r{(GUD)}
682 Evaluate the expression at point (@code{gud-print}). If Emacs
683 does not print the exact expression that you want, mark it as a region
688 @kindex C-c C-r @r{(GUD)}
691 Continue execution without specifying any stopping point. The program
692 will run until it hits a breakpoint, terminates, or gets a signal that
693 the debugger is checking for (@code{gud-cont}).
697 @kindex C-c C-d @r{(GUD)}
700 Delete the breakpoint(s) on the current source line, if any
701 (@code{gud-remove}). If you use this command in the GUD interaction
702 buffer, it applies to the line where the program last stopped.
705 @kindex C-c C-t @r{(GUD)}
708 Set a temporary breakpoint on the current source line, if any
709 (@code{gud-tbreak}). If you use this command in the GUD interaction
710 buffer, it applies to the line where the program last stopped.
713 @kindex C-c < @r{(GUD)}
716 Select the next enclosing stack frame (@code{gud-up}). This is
717 equivalent to the GDB command @samp{up}.
720 @kindex C-c > @r{(GUD)}
723 Select the next inner stack frame (@code{gud-down}). This is
724 equivalent to the GDB command @samp{down}.
727 @kindex C-c C-u @r{(GUD)}
730 Continue execution to the current line (@code{gud-until}). The
731 program will run until it hits a breakpoint, terminates, gets a signal
732 that the debugger is checking for, or reaches the line on which the
733 cursor currently sits.
736 @kindex C-c C-f @r{(GUD)}
739 Run the program until the selected stack frame returns or
740 stops for some other reason (@code{gud-finish}).
743 If you are using GDB, these additional key bindings are available:
747 @kindex C-x C-a C-j @r{(GUD)}
749 Only useful in a source buffer, @code{gud-jump} transfers the
750 program's execution point to the current line. In other words, the
751 next line that the program executes will be the one where you gave the
752 command. If the new execution line is in a different function from
753 the previously one, GDB prompts for confirmation since the results may
754 be bizarre. See the GDB manual entry regarding @code{jump} for
758 @kindex TAB @r{(GUD)}
759 @findex gud-gdb-complete-command
760 With GDB, complete a symbol name (@code{gud-gdb-complete-command}).
761 This key is available only in the GUD interaction buffer.
764 These commands interpret a numeric argument as a repeat count, when
767 Because @key{TAB} serves as a completion command, you can't use it to
768 enter a tab as input to the program you are debugging with GDB.
769 Instead, type @kbd{C-q @key{TAB}} to enter a tab.
771 @node GUD Customization
772 @subsubsection GUD Customization
774 @vindex gdb-mode-hook
775 @vindex dbx-mode-hook
776 @vindex sdb-mode-hook
777 @vindex xdb-mode-hook
778 @vindex perldb-mode-hook
779 @vindex pdb-mode-hook
780 @vindex jdb-mode-hook
781 On startup, GUD runs one of the following hooks: @code{gdb-mode-hook},
782 if you are using GDB; @code{dbx-mode-hook}, if you are using DBX;
783 @code{sdb-mode-hook}, if you are using SDB; @code{xdb-mode-hook}, if you
784 are using XDB; @code{perldb-mode-hook}, for Perl debugging mode;
785 @code{pdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB. You can
786 use these hooks to define custom key bindings for the debugger
787 interaction buffer. @xref{Hooks}.
789 Here is a convenient way to define a command that sends a particular
790 command string to the debugger, and set up a key binding for it in the
791 debugger interaction buffer:
795 (gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring})
798 This defines a command named @var{function} which sends
799 @var{cmdstring} to the debugger process, and gives it the documentation
800 string @var{docstring}. You can then use the command @var{function} in any
801 buffer. If @var{binding} is non-@code{nil}, @code{gud-def} also binds
802 the command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to
803 @kbd{C-x C-a @var{binding}} generally.
805 The command string @var{cmdstring} may contain certain
806 @samp{%}-sequences that stand for data to be filled in at the time
807 @var{function} is called:
811 The name of the current source file. If the current buffer is the GUD
812 buffer, then the ``current source file'' is the file that the program
816 The number of the current source line. If the current buffer is the GUD
817 buffer, then the ``current source line'' is the line that the program
821 In transient-mark-mode the text in the region, if it is active.
822 Otherwise the text of the C lvalue or function-call expression at or
826 The text of the hexadecimal address at or adjacent to point.
829 The numeric argument of the called function, as a decimal number. If
830 the command is used without a numeric argument, @samp{%p} stands for the
833 If you don't use @samp{%p} in the command string, the command you define
834 ignores any numeric argument.
837 The name of the directory of the current source file.
840 Fully qualified class name derived from the expression surrounding point
844 @node GDB Graphical Interface
845 @subsection GDB Graphical Interface
847 The command @code{gdb} starts GDB in a graphical interface, using
848 Emacs windows for display program state information. In effect, this
849 makes Emacs into an IDE (interactive development environment). With
850 it, you do not need to use textual GDB commands; you can control the
851 debugging session with the mouse. For example, you can click in the
852 fringe of a source buffer to set a breakpoint there, or on a stack
853 frame in the stack buffer to select that frame.
855 This mode requires telling GDB that its ``screen size'' is
856 unlimited, so it sets the height and width accordingly. For correct
857 operation you must not change these values during the GDB session.
859 @vindex gud-gdb-command-name
860 To run GDB in text command mode, like the other debuggers in Emacs,
861 use @kbd{M-x gud-gdb}. You need to use text command mode to debug
862 multiple programs within one Emacs session.
865 * GDB-UI Layout:: Control the number of displayed buffers.
866 * Source Buffers:: Use the mouse in the fringe/margin to
867 control your program.
868 * Breakpoints Buffer:: A breakpoint control panel.
869 * Stack Buffer:: Select a frame from the call stack.
870 * Other GDB-UI Buffers:: Input/output, locals, registers,
871 assembler, threads and memory buffers.
872 * Watch Expressions:: Monitor variable values in the speedbar.
876 @subsubsection GDB User Interface Layout
877 @cindex GDB User Interface layout
879 @vindex gdb-many-windows
880 If the variable @code{gdb-many-windows} is @code{nil} (the default
881 value) then @kbd{M-x gdb} normally displays only the GUD buffer.
882 However, if the variable @code{gdb-show-main} is also non-@code{nil},
883 it starts with two windows: one displaying the GUD buffer, and the
884 other showing the source for the @code{main} function of the program
887 If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb}
888 displays the following frame layout:
892 +--------------------------------+--------------------------------+
893 | GUD buffer (I/O of GDB) | Locals/Registers buffer |
894 |--------------------------------+--------------------------------+
895 | Primary Source buffer | I/O buffer for debugged pgm |
896 |--------------------------------+--------------------------------+
897 | Stack buffer | Breakpoints/thread buffer |
898 +--------------------------------+--------------------------------+
902 However, if @code{gdb-use-separate-io-buffer} is @code{nil}, the I/O
903 buffer does not appear and the primary source buffer occupies the full
906 @findex gdb-restore-windows
907 If you change the window layout, for example, while editing and
908 re-compiling your program, then you can restore this standard window
909 layout with the command @code{gdb-restore-windows}.
911 @findex gdb-many-windows
912 To switch between this standard layout and a simple layout
913 containing just the GUD buffer and a source file, type @kbd{M-x
916 You may also specify additional GDB-related buffers to display,
917 either in the same frame or a different one. Select the buffers you
918 want with the @samp{GUD->GDB-windows} and @samp{GUD->GDB-Frames}
919 sub-menus. If the menu-bar is unavailable, type @code{M-x
920 gdb-display-@var{buffertype}-buffer} or @code{M-x
921 gdb-frame-@var{buffertype}-buffer} respectively, where
922 @var{buffertype} is the relevant buffer type, such as
923 @samp{breakpoints}. Most of these buffers are read-only, and typing
924 @kbd{q} in them kills them.
926 When you finish debugging, kill the GUD buffer with @kbd{C-x k},
927 which will also kill all the buffers associated with the session.
928 However you need not do this if, after editing and re-compiling your
929 source code within Emacs, you wish continue debugging. When you
930 restart execution, GDB will automatically find your new executable.
931 Keeping the GUD buffer has the advantage of keeping the shell history
932 as well as GDB's breakpoints. You do need to check that the
933 breakpoints in recently edited source files are still in the right
937 @subsubsection Source Buffers
938 @cindex GDB commands in Fringe
940 @c @findex gdb-mouse-set-clear-breakpoint
941 @c @findex gdb-mouse-toggle-breakpoint
942 Many GDB commands can be entered using key bindings or the tool bar but
943 sometimes it is quicker to use the fringe. These commands either
944 manipulate breakpoints or control program execution. When there is no
945 fringe, you can use the margin but this is only present when the
946 source file already has a breakpoint.
948 You can click @kbd{Mouse-1} in the fringe or display margin of a
949 source buffer to set a breakpoint there and, on a graphical display, a
950 red bullet will appear on that line. If a breakpoint already exists
951 on that line, the same click will remove it. You can also enable or
952 disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet.
954 A solid arrow in the left fringe of a source buffer indicates the line
955 of the innermost frame where the debugged program has stopped. A
956 hollow arrow indicates the current execution line of higher level
959 If you drag the arrow in the fringe with @kbd{Mouse-1}
960 (@code{gdb-mouse-until}), execution will continue to the line where
961 you release the button, provided it is still in the same frame.
962 Alternatively, you can click @kbd{Mouse-3} at some point in the fringe
963 of this buffer and execution will advance to there. A similar command
964 (@code{gdb-mouse-jump}) allows you to jump to a source line without
965 executing the intermediate lines by clicking @kbd{C-Mouse-3}. This
966 command allows you to go backwards which can be useful for running
967 through code that has already executed, in order to examine its
968 execution in more detail.
972 Set or clear a breakpoint.
975 Enable or disable a breakpoint.
978 Continue execution to here.
984 If the variable @code{gdb-find-source-frame} is non-@code{nil} and
985 execution stops in a frame for which there is no source code e.g after
986 an interrupt, then Emacs finds and displays the first frame further up
987 stack for which there is source. If it is @code{nil} then the source
988 buffer continues to display the last frame which maybe more useful,
989 for example, when re-setting a breakpoint.
991 @node Breakpoints Buffer
992 @subsubsection Breakpoints Buffer
994 The breakpoints buffer shows the existing breakpoints, watchpoints and
995 catchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}). It has
996 these special commands, which mostly apply to the @dfn{current
997 breakpoint}, the breakpoint which point is on.
1001 @kindex SPC @r{(GDB breakpoints buffer)}
1002 @findex gdb-toggle-breakpoint
1003 Enable/disable the current breakpoint (@code{gdb-toggle-breakpoint}).
1004 On a graphical display, this changes the color of a bullet in the
1005 margin of a source buffer at the relevant line. This is red when
1006 the breakpoint is enabled and grey when it is disabled. Text-only
1007 terminals correspondingly display a @samp{B} or @samp{b}.
1010 @kindex D @r{(GDB breakpoints buffer)}
1011 @findex gdb-delete-breakpoint
1012 Delete the current breakpoint (@code{gdb-delete-breakpoint}).
1015 @kindex RET @r{(GDB breakpoints buffer)}
1016 @findex gdb-goto-breakpoint
1017 Visit the source line for the current breakpoint
1018 (@code{gdb-goto-breakpoint}).
1021 @kindex Mouse-2 @r{(GDB breakpoints buffer)}
1022 Visit the source line for the breakpoint you click on.
1025 When @code{gdb-many-windows} is non-@code{nil}, the breakpoints buffer
1026 shares its window with the threads buffer. To switch from one to the
1027 other click with @kbd{mouse-1} on the relevant button in the header
1031 @subsubsection Stack Buffer
1033 The stack buffer displays a @dfn{call stack}, with one line for each
1034 of the nested subroutine calls (@dfn{stack frames}) now active in the
1035 program. @xref{Backtrace,, Backtraces, gdb, The GNU debugger}.
1037 @findex gdb-frames-select
1038 An arrow in the fringe points to the selected frame or, if the fringe is
1039 not present, the number of the selected frame is displayed in reverse
1040 contrast. To select a frame in GDB, move point in the stack buffer to
1041 that stack frame and type @key{RET} (@code{gdb-frames-select}), or click
1042 @kbd{Mouse-2} on a stack frame. If the locals buffer is visible,
1043 selecting a stack frame updates it to display the local variables of the
1046 @node Other GDB-UI Buffers
1047 @subsubsection Other Buffers
1050 @item Input/Output Buffer
1051 @vindex gdb-use-separate-io-buffer
1052 If the variable @code{gdb-use-separate-io-buffer} is non-@code{nil},
1053 the program being debugged takes its input and displays its output
1054 here. Otherwise it uses the GUD buffer for that. To toggle whether
1055 GUD mode uses this buffer, do @kbd{M-x gdb-use-separate-io-buffer}.
1056 This takes effect when you next restart the program you are debugging.
1058 The history and replay commands from Shell mode are available here,
1059 as are the commands to send signals to the debugged program.
1063 The locals buffer displays the values of local variables of the
1064 current frame for simple data types (@pxref{Frame Info, Frame Info,
1065 Information on a frame, gdb, The GNU debugger}). Press @key{RET} or
1066 click @kbd{Mouse-2} on the value if you want to edit it.
1068 Arrays and structures display their type only. With GDB 6.4 or later,
1069 move point to their name and press @key{RET}, or alternatively click
1070 @kbd{Mouse-2} there, to examine their values. With earlier versions
1071 of GDB, use @kbd{Mouse-2} or @key{RET} on the type description
1072 (@samp{[struct/union]} or @samp{[array]}). @xref{Watch Expressions}.
1074 @item Registers Buffer
1075 @findex toggle-gdb-all-registers
1076 The registers buffer displays the values held by the registers
1077 (@pxref{Registers,,, gdb, The GNU debugger}). Press @key{RET} or
1078 click @kbd{Mouse-2} on a register if you want to edit its value.
1079 With GDB 6.4 or later, recently changed register values display with
1080 @code{font-lock-warning-face}. With earlier versions of GDB, you can
1081 press @key{SPC} to toggle the display of floating point registers
1082 (@code{toggle-gdb-all-registers}).
1084 @item Assembler Buffer
1085 The assembler buffer displays the current frame as machine code. An
1086 arrow points to the current instruction, and you can set and remove
1087 breakpoints as in a source buffer. Breakpoint icons also appear in
1088 the fringe or margin.
1090 @item Threads Buffer
1091 @findex gdb-threads-select
1092 The threads buffer displays a summary of all threads currently in your
1093 program (@pxref{Threads, Threads, Debugging programs with multiple
1094 threads, gdb, The GNU debugger}). Move point to any thread in the
1095 list and press @key{RET} to select it (@code{gdb-threads-select}) and
1096 display the associated source in the primary source buffer.
1097 Alternatively, click @kbd{Mouse-2} on a thread to select it. If the
1098 locals buffer is visible, its contents update to display the variables
1099 that are local in the new thread.
1101 When there is more than one main thread and the threads buffer is
1102 present, Emacs displays the selected thread number in the mode line of
1103 many of the GDB-UI Buffers.
1106 The memory buffer lets you examine sections of program memory
1107 (@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}).
1108 Click @kbd{Mouse-1} on the appropriate part of the header line to
1109 change the starting address or number of data items that the buffer
1110 displays. Alternatively, use @kbd{S} or @kbd{N} respectively. Click
1111 @kbd{Mouse-3} on the header line to select the display format or unit
1112 size for these data items.
1115 When @code{gdb-many-windows} is non-@code{nil}, the threads buffer
1116 shares its window with the breakpoints buffer, and the locals buffer
1117 with the registers buffer. To switch from one to the other click with
1118 @kbd{mouse-1} on the relevant button in the header line.
1120 @node Watch Expressions
1121 @subsubsection Watch Expressions
1122 @cindex Watching expressions in GDB
1125 @kindex C-x C-a C-w @r{(GUD)}
1126 If you want to see how a variable changes each time your program
1127 stops, move point into the variable name and click on the watch icon
1128 in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}. If you
1129 specify a prefix argument, you can enter the variable name in the
1132 Each watch expression is displayed in the speedbar. Complex data
1133 types, such as arrays, structures and unions are represented in a tree
1134 format. Leaves and simple data types show the name of the expression
1135 and its value and, when the speedbar frame is selected, display the
1136 type as a tooltip. Higher levels show the name, type and address
1137 value for pointers and just the name and type otherwise. Root expressions
1138 also display the frame address as a tooltip to help identify the frame
1139 in which they were defined.
1141 To expand or contract a complex data type, click @kbd{Mouse-2} or
1142 press @key{SPC} on the tag to the left of the expression. Emacs asks
1143 for confirmation before expanding the expression if its number of
1144 immediate children exceeds the value of the variable
1145 @code{gdb-max-children}.
1147 @kindex D @r{(GDB speedbar)}
1148 @findex gdb-var-delete
1149 To delete a complex watch expression, move point to the root
1150 expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}).
1152 @kindex RET @r{(GDB speedbar)}
1153 @findex gdb-edit-value
1154 To edit a variable with a simple data type, or a simple element of a
1155 complex data type, move point there in the speedbar and type @key{RET}
1156 (@code{gdb-edit-value}). Or you can click @kbd{Mouse-2} on a value to
1157 edit it. Either way, this reads the new value using the minibuffer.
1159 @vindex gdb-show-changed-values
1160 If you set the variable @code{gdb-show-changed-values} to
1161 non-@code{nil} (the default value), Emacs uses
1162 @code{font-lock-warning-face} to highlight values that have recently
1163 changed and @code{shadow} face to make variables which have gone out of
1164 scope less noticeable. When a variable goes out of scope you can't
1167 @vindex gdb-delete-out-of-scope
1168 If the variable @code{gdb-delete-out-of-scope} is non-@code{nil}
1169 (the default value), Emacs automatically deletes watch expressions
1170 which go out of scope. Sometimes, when re-entering the same function,
1171 it may be useful to set this value to nil so that you don't need to
1172 recreate the watch expression.
1174 @vindex gdb-use-colon-colon-notation
1175 If the variable @code{gdb-use-colon-colon-notation} is
1176 non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}}
1177 format. This allows the user to display watch expressions which share
1178 the same variable name. The default value is @code{nil}.
1180 @vindex gdb-speedbar-auto-raise
1181 To automatically raise the speedbar every time the display of watch
1182 expressions updates, set @code{gdb-speedbar-auto-raise} to
1183 non-@code{nil}. This can be useful if you are debugging with a full
1186 @node Executing Lisp
1187 @section Executing Lisp Expressions
1189 Emacs has several different major modes for Lisp and Scheme. They are
1190 the same in terms of editing commands, but differ in the commands for
1191 executing Lisp expressions. Each mode has its own purpose.
1194 @item Emacs-Lisp mode
1195 The mode for editing source files of programs to run in Emacs Lisp.
1196 This mode defines @kbd{C-M-x} to evaluate the current defun.
1197 @xref{Lisp Libraries}.
1198 @item Lisp Interaction mode
1199 The mode for an interactive session with Emacs Lisp. It defines
1200 @kbd{C-j} to evaluate the sexp before point and insert its value in the
1201 buffer. @xref{Lisp Interaction}.
1203 The mode for editing source files of programs that run in Lisps other
1204 than Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defun
1205 to an inferior Lisp process. @xref{External Lisp}.
1206 @item Inferior Lisp mode
1207 The mode for an interactive session with an inferior Lisp process.
1208 This mode combines the special features of Lisp mode and Shell mode
1209 (@pxref{Shell Mode}).
1211 Like Lisp mode but for Scheme programs.
1212 @item Inferior Scheme mode
1213 The mode for an interactive session with an inferior Scheme process.
1216 Most editing commands for working with Lisp programs are in fact
1217 available globally. @xref{Programs}.
1219 @node Lisp Libraries
1220 @section Libraries of Lisp Code for Emacs
1222 @cindex loading Lisp code
1224 Lisp code for Emacs editing commands is stored in files whose names
1225 conventionally end in @file{.el}. This ending tells Emacs to edit them in
1226 Emacs-Lisp mode (@pxref{Executing Lisp}).
1229 Emacs Lisp code can be compiled into byte-code, which loads faster,
1230 takes up less space, and executes faster. @xref{Byte Compilation,,
1231 Byte Compilation, elisp, the Emacs Lisp Reference Manual}. By
1232 convention, the compiled code for a library goes in a separate file
1233 whose name ends in @samp{.elc}. Thus, the compiled code for
1234 @file{foo.el} goes in @file{foo.elc}.
1237 To execute a file of Emacs Lisp code, use @kbd{M-x load-file}. This
1238 command reads a file name using the minibuffer and then executes the
1239 contents of that file as Lisp code. It is not necessary to visit the
1240 file first; in any case, this command reads the file as found on disk,
1241 not text in an Emacs buffer.
1244 @findex load-library
1245 Once a file of Lisp code is installed in the Emacs Lisp library
1246 directories, users can load it using @kbd{M-x load-library}. Programs
1247 can load it by calling @code{load}, a more primitive function that is
1248 similar but accepts some additional arguments.
1250 @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it
1251 searches a sequence of directories and tries three file names in each
1252 directory. Suppose your argument is @var{lib}; the three names are
1253 @file{@var{lib}.elc}, @file{@var{lib}.el}, and lastly just
1254 @file{@var{lib}}. If @file{@var{lib}.elc} exists, it is by convention
1255 the result of compiling @file{@var{lib}.el}; it is better to load the
1256 compiled file, since it will load and run faster.
1258 If @code{load-library} finds that @file{@var{lib}.el} is newer than
1259 @file{@var{lib}.elc} file, it issues a warning, because it's likely
1260 that somebody made changes to the @file{.el} file and forgot to
1261 recompile it. Nonetheless, it loads @file{@var{lib}.elc}. This is
1262 because people often leave unfinished edits the source file, and don't
1263 recompile it until they think it is ready to use.
1265 Because the argument to @code{load-library} is usually not in itself
1266 a valid file name, file name completion is not available. Indeed, when
1267 using this command, you usually do not know exactly what file name
1271 The sequence of directories searched by @kbd{M-x load-library} is
1272 specified by the variable @code{load-path}, a list of strings that are
1273 directory names. The default value of the list contains the directories where
1274 the Lisp code for Emacs itself is stored. If you have libraries of
1275 your own, put them in a single directory and add that directory
1276 to @code{load-path}. @code{nil} in this list stands for the current default
1277 directory, but it is probably not a good idea to put @code{nil} in the
1278 list. If you find yourself wishing that @code{nil} were in the list,
1279 most likely what you really want to do is use @kbd{M-x load-file}
1283 Often you do not have to give any command to load a library, because
1284 the commands defined in the library are set up to @dfn{autoload} that
1285 library. Trying to run any of those commands calls @code{load} to load
1286 the library; this replaces the autoload definitions with the real ones
1289 @vindex load-dangerous-libraries
1290 @cindex Lisp files byte-compiled by XEmacs
1291 By default, Emacs refuses to load compiled Lisp files which were
1292 compiled with XEmacs, a modified versions of Emacs---they can cause
1293 Emacs to crash. Set the variable @code{load-dangerous-libraries} to
1294 @code{t} if you want to try loading them.
1297 @section Evaluating Emacs Lisp Expressions
1298 @cindex Emacs-Lisp mode
1299 @cindex mode, Emacs-Lisp
1301 @findex emacs-lisp-mode
1302 Lisp programs intended to be run in Emacs should be edited in
1303 Emacs-Lisp mode; this happens automatically for file names ending in
1304 @file{.el}. By contrast, Lisp mode itself is used for editing Lisp
1305 programs intended for other Lisp systems. To switch to Emacs-Lisp mode
1306 explicitly, use the command @kbd{M-x emacs-lisp-mode}.
1308 For testing of Lisp programs to run in Emacs, it is often useful to
1309 evaluate part of the program as it is found in the Emacs buffer. For
1310 example, after changing the text of a Lisp function definition,
1311 evaluating the definition installs the change for future calls to the
1312 function. Evaluation of Lisp expressions is also useful in any kind of
1313 editing, for invoking noninteractive functions (functions that are
1318 Read a single Lisp expression in the minibuffer, evaluate it, and print
1319 the value in the echo area (@code{eval-expression}).
1321 Evaluate the Lisp expression before point, and print the value in the
1322 echo area (@code{eval-last-sexp}).
1324 Evaluate the defun containing or after point, and print the value in
1325 the echo area (@code{eval-defun}).
1326 @item M-x eval-region
1327 Evaluate all the Lisp expressions in the region.
1328 @item M-x eval-buffer
1329 Evaluate all the Lisp expressions in the buffer.
1333 @c This uses ``colon'' instead of a literal `:' because Info cannot
1334 @c cope with a `:' in a menu
1335 @kindex M-@key{colon}
1340 @findex eval-expression
1341 @kbd{M-:} (@code{eval-expression}) is the most basic command for evaluating
1342 a Lisp expression interactively. It reads the expression using the
1343 minibuffer, so you can execute any expression on a buffer regardless of
1344 what the buffer contains. When the expression is evaluated, the current
1345 buffer is once again the buffer that was current when @kbd{M-:} was
1348 @kindex C-M-x @r{(Emacs-Lisp mode)}
1350 In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the command
1351 @code{eval-defun}, which parses the defun containing or following point
1352 as a Lisp expression and evaluates it. The value is printed in the echo
1353 area. This command is convenient for installing in the Lisp environment
1354 changes that you have just made in the text of a function definition.
1356 @kbd{C-M-x} treats @code{defvar} expressions specially. Normally,
1357 evaluating a @code{defvar} expression does nothing if the variable it
1358 defines already has a value. But @kbd{C-M-x} unconditionally resets the
1359 variable to the initial value specified in the @code{defvar} expression.
1360 @code{defcustom} expressions are treated similarly.
1361 This special feature is convenient for debugging Lisp programs.
1362 Typing @kbd{C-M-x} on a @code{defface} expression reinitializes
1363 the face according to the @code{defface} specification.
1366 @findex eval-last-sexp
1367 The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Lisp
1368 expression preceding point in the buffer, and displays the value in the
1369 echo area. It is available in all major modes, not just Emacs-Lisp
1370 mode. It does not treat @code{defvar} specially.
1372 When the result of an evaluation is an integer, you can type
1373 @kbd{C-x C-e} a second time to display the value of the integer result
1374 in additional formats (octal, hexadecimal, and character).
1376 If @kbd{C-x C-e}, or @kbd{M-:} is given a numeric argument, it
1377 inserts the value into the current buffer at point, rather than
1378 displaying it in the echo area. The argument's value does not matter.
1379 @kbd{C-M-x} with a numeric argument instruments the function
1380 definition for Edebug (@pxref{Instrumenting, Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}).
1384 The most general command for evaluating Lisp expressions from a buffer
1385 is @code{eval-region}. @kbd{M-x eval-region} parses the text of the
1386 region as one or more Lisp expressions, evaluating them one by one.
1387 @kbd{M-x eval-buffer} is similar but evaluates the entire
1388 buffer. This is a reasonable way to install the contents of a file of
1389 Lisp code that you are ready to test. Later, as you find bugs and
1390 change individual functions, use @kbd{C-M-x} on each function that you
1391 change. This keeps the Lisp world in step with the source file.
1393 @vindex eval-expression-print-level
1394 @vindex eval-expression-print-length
1395 @vindex eval-expression-debug-on-error
1396 The two customizable variables @code{eval-expression-print-level} and
1397 @code{eval-expression-print-length} control the maximum depth and length
1398 of lists to print in the result of the evaluation commands before
1399 abbreviating them. @code{eval-expression-debug-on-error} controls
1400 whether evaluation errors invoke the debugger when these commands are
1401 used; its default is @code{t}.
1403 @node Lisp Interaction
1404 @section Lisp Interaction Buffers
1406 When Emacs starts up, it contains a buffer named @samp{*scratch*},
1407 which is provided for evaluating Lisp expressions interactively inside
1408 Emacs. Its major mode is Lisp Interaction mode.
1410 @findex eval-print-last-sexp
1411 @kindex C-j @r{(Lisp Interaction mode)}
1412 The simplest way to use the @samp{*scratch*} buffer is to insert
1413 Lisp expressions and type @kbd{C-j} (@code{eval-print-last-sexp})
1414 after each expression. This command reads the Lisp expression before
1415 point, evaluates it, and inserts the value in printed representation
1416 before point. The result is a complete typescript of the expressions
1417 you have evaluated and their values.
1419 @findex lisp-interaction-mode
1420 All other commands in Lisp Interaction mode are the same as in Emacs
1421 Lisp mode. You can enable Lisp Interaction mode by typing @kbd{M-x
1422 lisp-interaction-mode}.
1425 An alternative way of evaluating Emacs Lisp expressions interactively
1426 is to use Inferior Emacs-Lisp mode, which provides an interface rather
1427 like Shell mode (@pxref{Shell Mode}) for evaluating Emacs Lisp
1428 expressions. Type @kbd{M-x ielm} to create an @samp{*ielm*} buffer
1429 which uses this mode. For more information see that command's
1433 @section Running an External Lisp
1435 Emacs has facilities for running programs in other Lisp systems. You can
1436 run a Lisp process as an inferior of Emacs, and pass expressions to it to
1437 be evaluated. You can also pass changed function definitions directly from
1438 the Emacs buffers in which you edit the Lisp programs to the inferior Lisp
1442 @vindex inferior-lisp-program
1444 To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runs
1445 the program named @code{lisp}, the same program you would run by typing
1446 @code{lisp} as a shell command, with both input and output going through
1447 an Emacs buffer named @samp{*lisp*}. That is to say, any ``terminal
1448 output'' from Lisp will go into the buffer, advancing point, and any
1449 ``terminal input'' for Lisp comes from text in the buffer. (You can
1450 change the name of the Lisp executable file by setting the variable
1451 @code{inferior-lisp-program}.)
1453 To give input to Lisp, go to the end of the buffer and type the input,
1454 terminated by @key{RET}. The @samp{*lisp*} buffer is in Inferior Lisp
1455 mode, which combines the special characteristics of Lisp mode with most
1456 of the features of Shell mode (@pxref{Shell Mode}). The definition of
1457 @key{RET} to send a line to a subprocess is one of the features of Shell
1461 For the source files of programs to run in external Lisps, use Lisp
1462 mode. You can switch to this mode with @kbd{M-x lisp-mode}, and it is
1463 used automatically for files whose names end in @file{.l},
1464 @file{.lsp}, or @file{.lisp}.
1466 @kindex C-M-x @r{(Lisp mode)}
1467 @findex lisp-eval-defun
1468 When you edit a function in a Lisp program you are running, the easiest
1469 way to send the changed definition to the inferior Lisp process is the key
1470 @kbd{C-M-x}. In Lisp mode, this runs the function @code{lisp-eval-defun},
1471 which finds the defun around or following point and sends it as input to
1472 the Lisp process. (Emacs can send input to any inferior process regardless
1473 of what buffer is current.)
1475 Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing
1476 programs to be run in another Lisp system) and Emacs-Lisp mode (for
1477 editing Lisp programs to be run in Emacs; see @pxref{Lisp Eval}): in
1478 both modes it has the effect of installing the function definition
1479 that point is in, but the way of doing so is different according to
1480 where the relevant Lisp environment is found.
1484 arch-tag: 9c3c2f71-b332-4144-8500-3ff9945a50ed