@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software
+@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Building, Maintaining, Programs, Top
+@node Building
@chapter Compiling and Testing Programs
@cindex building programs
@cindex program building
@cindex running Lisp functions
- The previous chapter discusses the Emacs commands that are useful for
-making changes in programs. This chapter deals with commands that assist
-in the larger process of compiling and testing programs.
+ The previous chapter discusses the Emacs commands that are useful
+for making changes in programs. This chapter deals with commands that
+assist in the process of compiling and testing programs.
@menu
* Compilation:: Compiling programs in languages other
* Executing Lisp:: Various modes for editing Lisp programs,
with different facilities for running
the Lisp programs.
-* Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs.
+* Libraries: Lisp Libraries. How Lisp programs are loaded into Emacs.
* Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
* External Lisp:: Communicating through Emacs with a separate Lisp.
@cindex compilation errors
@cindex error log
- Emacs can run compilers for noninteractive languages such as C and
-Fortran as inferior processes, feeding the error log into an Emacs buffer.
-It can also parse the error messages and show you the source lines where
-compilation errors occurred.
+ Emacs can run compilers for languages such as C and Fortran, feeding
+the compilation log into an Emacs buffer. It can also parse the error
+messages and show you where the errors occurred.
@table @kbd
@item M-x compile
Run a compiler asynchronously under Emacs, with error messages going to
-the @samp{*compilation*} buffer.
+the @file{*compilation*} buffer.
@item M-x recompile
Invoke a compiler with the same command as in the last invocation of
@kbd{M-x compile}.
@end table
@findex compile
- To run @code{make} or another compilation command, do @kbd{M-x
-compile}. This command reads a shell command line using the minibuffer,
-and then executes the command in an inferior shell, putting output in
-the buffer named @samp{*compilation*}. The current buffer's default
-directory is used as the working directory for the execution of the
-command; normally, therefore, the compilation happens in this
-directory.
+ To run @code{make} or another compilation command, type @kbd{M-x
+compile}. This reads a shell command line using the minibuffer, and
+then executes the command by running a shell as a subprocess (or
+@dfn{inferior process}) of Emacs. The output is inserted in a buffer
+named @file{*compilation*}. The current buffer's default directory is
+used as the working directory for the execution of the command;
+normally, therefore, compilation takes place in this directory.
@vindex compile-command
- The default for the compilation command is normally @samp{make -k},
-which is correct most of the time for nontrivial programs.
-@xref{Top,, Make, make, GNU Make Manual}. If you have done @kbd{M-x
-compile} before, the default each time is the command you used the
-previous time. @code{compile} stores this command in the variable
-@code{compile-command}, so setting that variable specifies the default
-for the next use of @kbd{M-x compile}. If a file specifies a file
-local value for @code{compile-command}, that provides the default when
-you type @kbd{M-x compile} in that file's buffer. @xref{File
-Variables}.
-
- Starting a compilation displays the buffer @samp{*compilation*} in
-another window but does not select it. The buffer's mode line tells
-you whether compilation is finished, with the word @samp{run},
-@samp{signal} or @samp{exit} inside the parentheses. You do not have
-to keep this buffer visible; compilation continues in any case. While
-a compilation is going on, the string @samp{Compiling} appears in the
-mode lines of all windows. When this string disappears, the
-compilation is finished.
-
- If you want to watch the compilation transcript as it appears, switch
-to the @samp{*compilation*} buffer and move point to the end of the
-buffer. When point is at the end, new compilation output is inserted
-above point, which remains at the end. If point is not at the end of
-the buffer, it remains fixed while more compilation output is added at
-the end of the buffer.
+ The default compilation command is @samp{make -k}, which is usually
+correct for programs compiled using the @command{make} utility (the
+@samp{-k} flag tells @command{make} to continue compiling as much as
+possible after an error). @xref{Top,, Make, make, GNU Make Manual}.
+If you have done @kbd{M-x compile} before, the command that you
+specified is automatically stored in the variable
+@code{compile-command}; this is used as the default the next time you
+type @kbd{M-x compile}. A file can also specify a file-local value
+for @code{compile-command} (@pxref{File Variables}).
+
+ Starting a compilation displays the @file{*compilation*} buffer in
+another window but does not select it. While the compilation is
+running, the word @samp{run} is shown in the major mode indicator for
+the @file{*compilation*} buffer, and the word @samp{Compiling} appears
+in all mode lines. You do not have to keep the @file{*compilation*}
+buffer visible while compilation is running; it continues in any case.
+When the compilation ends, for whatever reason, the mode line of the
+@file{*compilation*} buffer changes to say @samp{exit} (followed by
+the exit code: @samp{[0]} for a normal exit), or @samp{signal} (if a
+signal terminated the process).
+
+ If you want to watch the compilation transcript as it appears,
+switch to the @file{*compilation*} buffer and move point to the end of
+the buffer. When point is at the end, new compilation output is
+inserted above point, which remains at the end. Otherwise, point
+remains fixed while compilation output is added at the end of the
+buffer.
@cindex compilation buffer, keeping point at end
@vindex compilation-scroll-output
If you change the variable @code{compilation-scroll-output} to a
-non-@code{nil} value, the compilation buffer will scroll automatically
-to follow the output as it comes in. If the value is
-@code{first-error}, the scrolling stops at the first error that
-appears, leaving point at that error. For any other non-@code{nil}
-value, the buffer continues scrolling until there is no more output.
+non-@code{nil} value, the @file{*compilation*} buffer scrolls
+automatically to follow the output. If the value is
+@code{first-error}, scrolling stops when the first error appears,
+leaving point at that error. For any other non-@code{nil} value,
+scrolling continues until there is no more output.
@findex recompile
To rerun the last compilation with the same command, type @kbd{M-x
-recompile}. This automatically reuses the compilation command from
-the last invocation of @kbd{M-x compile}. It also reuses the
-@samp{*compilation*} buffer and starts the compilation in its default
+recompile}. This reuses the compilation command from the last
+invocation of @kbd{M-x compile}. It also reuses the
+@file{*compilation*} buffer and starts the compilation in its default
directory, which is the directory in which the previous compilation
was started.
- When the compiler process terminates, for whatever reason, the mode
-line of the @samp{*compilation*} buffer changes to say @samp{exit}
-(followed by the exit code, @samp{[0]} for a normal exit), or
-@samp{signal} (if a signal terminated the process), instead of
-@samp{run}.
-
@findex kill-compilation
+@vindex compilation-always-kill
Starting a new compilation also kills any compilation already
-running in @samp{*compilation*}, as the buffer can only handle one
+running in @file{*compilation*}, as the buffer can only handle one
compilation at any time. However, @kbd{M-x compile} asks for
-confirmation before actually killing a compilation that is running.
-You can also kill the compilation process with @kbd{M-x
+confirmation before actually killing a compilation that is running; to
+always automatically kill the compilation without asking, change the
+variable @code{compilation-always-kill} to @code{t}. You can also
+kill a compilation process with the command @kbd{M-x
kill-compilation}.
To run two compilations at once, start the first one, then rename
-the @samp{*compilation*} buffer (perhaps using @code{rename-uniquely};
+the @file{*compilation*} buffer (perhaps using @code{rename-uniquely};
@pxref{Misc Buffer}), then switch buffers and start the other
-compilation. This will create a new @samp{*compilation*} buffer.
-
- Emacs does not expect a compiler process to launch asynchronous
-subprocesses; if it does, and they keep running after the main
-compiler process has terminated, Emacs may kill them or their output
-may not arrive in Emacs. To avoid this problem, make the main process
-wait for its subprocesses to finish. In a shell script, you can do this
-using @samp{$!} and @samp{wait}, like this:
-
-@example
-(sleep 10; echo 2nd)& pid=$! # @r{Record pid of subprocess}
-echo first message
-wait $pid # @r{Wait for subprocess}
-@end example
-
- If the background process does not output to the compilation buffer,
-so you only need to prevent it from being killed when the main
-compilation process terminates, this is sufficient:
-
-@example
-nohup @var{command}; sleep 1
-@end example
+compilation. This will create a new @file{*compilation*} buffer.
@vindex compilation-environment
You can control the environment passed to the compilation command
@cindex Compilation mode
@cindex mode, Compilation
- The @samp{*compilation*} buffer uses a special major mode,
-Compilation mode, whose main feature is to provide a convenient way to
-visit the source line corresponding to an error message. These
-commands are also available in other special buffers that list
-locations in files, including those made by @kbd{M-x grep} and
-@kbd{M-x occur}.
+@cindex locus
+ The @file{*compilation*} buffer uses a major mode called Compilation
+mode. Compilation mode turns each error message in the buffer into a
+hyperlink; you can move point to it and type @key{RET}, or click on it
+with the mouse (@pxref{Mouse References}), to visit the @dfn{locus} of
+the error message in a separate window. The locus is the specific
+position in a file where that error occurred.
+
+@findex compile-goto-error
+@vindex compilation-auto-jump-to-first-error
+ If you change the variable
+@code{compilation-auto-jump-to-first-error} to a non-@code{nil} value,
+Emacs automatically visits the locus of the first error message that
+appears in the @file{*compilation*} buffer.
+
+ Compilation mode provides the following additional commands. These
+commands can also be used in @file{*grep*} buffers, where the
+hyperlinks are search matches rather than error messages (@pxref{Grep
+Searching}).
@table @kbd
@item M-g M-n
@itemx M-g n
@itemx C-x `
-Visit the locus of the next error message or match.
+Visit the locus of the next error message or match (@code{next-error}).
@item M-g M-p
@itemx M-g p
-Visit the locus of the previous error message or match.
-@item @key{RET}
-Visit the locus of the error message that point is on.
-This command is used in the compilation buffer.
-@item Mouse-2
-Visit the locus of the error message that you click on.
+Visit the locus of the previous error message or match
+(@code{previous-error}).
@item M-n
-Find and highlight the locus of the next error message, without
-selecting the source buffer.
+Move point to the next error message or match, without visiting its
+locus (@code{compilation-next-error}).
@item M-p
-Find and highlight the locus of the previous error message, without
-selecting the source buffer.
+Move point to the previous error message or match, without visiting
+its locus (@code{compilation-previous-error}).
@item M-@}
-Move point to the next error for a different file than the current
-one.
+Move point to the next error message or match occurring in a different
+file (@code{compilation-next-file}).
@item M-@{
-Move point to the previous error for a different file than the current
-one.
+Move point to the previous error message or match occurring in a
+different file (@code{compilation-previous-file}).
@item C-c C-f
Toggle Next Error Follow minor mode, which makes cursor motion in the
compilation buffer produce automatic source display.
@end table
-@findex compile-goto-error
-@vindex compilation-auto-jump-to-first-error
- You can visit the source for any particular error message by moving
-point in the @samp{*compilation*} buffer to that error message and
-typing @key{RET} (@code{compile-goto-error}). Alternatively, you can
-click @kbd{Mouse-2} on the error message; you need not switch to the
-@samp{*compilation*} buffer first. If you set the variable
-@code{compilation-auto-jump-to-first-error} to a non-@code{nil} value,
-Emacs automatically jumps to the first error, if any, as soon as it
-appears in the @samp{*compilation*} buffer.
-
@kindex M-g M-n
@kindex M-g n
@kindex C-x `
@findex next-error
@vindex next-error-highlight
- To parse the compiler error messages sequentially, type @kbd{C-x `}
-(@code{next-error}). The character following the @kbd{C-x} is the
-backquote or ``grave accent,'' not the single-quote. This command is
-available in all buffers, not just in @samp{*compilation*}; it
-displays the next error message at the top of one window and source
-location of the error in another window. It also temporarily
-highlights the relevant source line, for a period controlled by the
-variable @code{next-error-highlight}.
-
- The first time @w{@kbd{C-x `}} is used after the start of a compilation,
-it moves to the first error's location. Subsequent uses of @kbd{C-x
-`} advance down to subsequent errors. If you visit a specific error
-message with @key{RET} or @kbd{Mouse-2}, subsequent @w{@kbd{C-x `}}
-commands advance from there. When @w{@kbd{C-x `}} gets to the end of the
-buffer and finds no more error messages to visit, it fails and signals
-an Emacs error. @w{@kbd{C-u C-x `}} starts scanning from the beginning of
-the compilation buffer, and goes to the first error's location.
+ To visit errors sequentially, type @w{@kbd{C-x `}}
+(@code{next-error}), or equivalently @kbd{M-g M-n} or @kbd{M-g n}.
+This command can be invoked from any buffer, not just a Compilation
+mode buffer. The first time you invoke it after a compilation, it
+visits the locus of the first error message. Each subsequent
+@w{@kbd{C-x `}} visits the next error, in a similar fashion. If you
+visit a specific error with @key{RET} or a mouse click in the
+@file{*compilation*} buffer, subsequent @w{@kbd{C-x `}} commands
+advance from there. When @w{@kbd{C-x `}} finds no more error messages
+to visit, it signals an error. @w{@kbd{C-u C-x `}} starts again from
+the beginning of the compilation buffer, and visits the first locus.
+
+ @kbd{M-g M-p} or @kbd{M-g p} (@code{previous-error}) iterates
+through errors in the opposite direction.
+
+ The @code{next-error} and @code{previous-error} commands don't just
+act on the errors or matches listed in @file{*compilation*} and
+@file{*grep*} buffers; they also know how to iterate through error or
+match lists produced by other commands, such as @kbd{M-x occur}
+(@pxref{Other Repeating Search}). If you are already in a buffer
+containing error messages or matches, those are the ones that are
+iterated through; otherwise, Emacs looks for a buffer containing error
+messages or matches amongst the windows of the selected frame, then
+for one that @code{next-error} or @code{previous-error} previously
+iterated through, and finally amongst all other buffers. If the
+buffer chosen for iterating through is not currently displayed in a
+window, it will be displayed.
@vindex compilation-skip-threshold
- By default, @w{@kbd{C-x `}} skips less important messages. The variable
-@code{compilation-skip-threshold} controls this. If its value is 2,
-@w{@kbd{C-x `}} skips anything less than error, 1 skips anything less
-than warning, and 0 doesn't skip any messages. The default is 1.
-
- When the window has a left fringe, an arrow in the fringe points to
-the current message in the compilation buffer. The variable
-@code{compilation-context-lines} controls the number of lines of
-leading context to display before the current message. Going to an
-error message location scrolls the @samp{*compilation*} buffer to put
-the message that far down from the top. The value @code{nil} is
-special: if there's a left fringe, the window doesn't scroll at all
-if the message is already visible. If there is no left fringe,
-@code{nil} means display the message at the top of the window.
-
- If you're not in the compilation buffer when you run
-@code{next-error}, Emacs will look for a buffer that contains error
-messages. First, it looks for one displayed in the selected frame,
-then for one that previously had @code{next-error} called on it, and
-then at the current buffer. Finally, Emacs looks at all the remaining
-buffers. @code{next-error} signals an error if it can't find any such
-buffer.
+ By default, the @code{next-error} and @code{previous-error} commands
+skip less important messages. The variable
+@code{compilation-skip-threshold} controls this. The default value,
+1, means to skip anything less important than a warning. A value of 2
+means to skip anything less important than an error, while 0 means not
+to skip any messages.
+
+ When Emacs visits the locus of an error message, it momentarily
+highlights the relevant source line. The duration of this highlight
+is determined by the variable @code{next-error-highlight}.
+
+@vindex compilation-context-lines
+ If the @file{*compilation*} buffer is shown in a window with a left
+fringe (@pxref{Fringes}), the locus-visiting commands put an arrow in
+the fringe, pointing to the current error message. If the window has
+no left fringe, such as on a text terminal, these commands scroll the
+window so that the current message is at the top of the window. If
+you change the variable @code{compilation-context-lines} to an integer
+value @var{n}, these commands scroll the window so that the current
+error message is @var{n} lines from the top, whether or not there is a
+fringe; the default value, @code{nil}, gives the behavior described
+above.
@vindex compilation-error-regexp-alist
@vindex grep-regexp-alist
To parse messages from the compiler, Compilation mode uses the
variable @code{compilation-error-regexp-alist} which lists various
-formats of error messages and tells Emacs how to extract the source file
-and the line number from the text of a message. If your compiler isn't
-supported, you can tailor Compilation mode to it by adding elements to
-that list. A similar variable @code{grep-regexp-alist} tells Emacs how
-to parse output of a @code{grep} command.
+error message formats and tells Emacs how to extract the locus from
+each. A similar variable, @code{grep-regexp-alist}, tells Emacs how
+to parse output from a @code{grep} command (@pxref{Grep Searching}).
@findex compilation-next-error
@findex compilation-previous-error
@findex compilation-next-file
@findex compilation-previous-file
- Compilation mode also redefines the keys @key{SPC} and @key{DEL} to
-scroll by screenfuls, and @kbd{M-n} (@code{compilation-next-error})
-and @kbd{M-p} (@code{compilation-previous-error}) to move to the next
-or previous error message. You can also use @kbd{M-@{}
-(@code{compilation-next-file} and @kbd{M-@}}
-(@code{compilation-previous-file}) to move up or down to an error
-message for a different source file.
+ Compilation mode also defines the keys @key{SPC} and @key{DEL} to
+scroll by screenfuls; @kbd{M-n} (@code{compilation-next-error}) and
+@kbd{M-p} (@code{compilation-previous-error}) to move to the next or
+previous error message; and @kbd{M-@{} (@code{compilation-next-file})
+and @kbd{M-@}} (@code{compilation-previous-file}) to move to the next
+or previous error message for a different source file.
@cindex Next Error Follow mode
@findex next-error-follow-minor-mode
You can type @kbd{C-c C-f} to toggle Next Error Follow mode. In
this minor mode, ordinary cursor motion in the compilation buffer
-automatically updates the source buffer. For instance, moving the
-cursor to the next error message causes the location of that error to
-be displayed immediately.
+automatically updates the source buffer, i.e., moving the cursor over
+an error message causes the locus of that error to be displayed.
The features of Compilation mode are also available in a minor mode
called Compilation Minor mode. This lets you parse error messages in
-any buffer, not just a normal compilation output buffer. Type @kbd{M-x
-compilation-minor-mode} to enable the minor mode. This defines the keys
-@key{RET} and @kbd{Mouse-2}, as in the Compilation major mode.
-
- Compilation minor mode works in any buffer, as long as the contents
-are in a format that it understands. In an Rlogin buffer (@pxref{Remote
-Host}), Compilation minor mode automatically accesses remote source
-files by FTP (@pxref{File Names}).
+any buffer, not just a normal compilation output buffer. Type
+@kbd{M-x compilation-minor-mode} to enable the minor mode. For
+instance, in an Rlogin buffer (@pxref{Remote Host}), Compilation minor
+mode automatically accesses remote source files by FTP (@pxref{File
+Names}).
@node Compilation Shell
@section Subshells for Compilation
- Emacs uses a shell to run the compilation command, but specifies the
-option for a noninteractive shell. This means, in particular, that
-the shell should start with no prompt. If you find your usual shell
-prompt making an unsightly appearance in the @samp{*compilation*}
-buffer, it means you have made a mistake in your shell's init file by
-setting the prompt unconditionally. (This init file's name may be
-@file{.bashrc}, @file{.profile}, @file{.cshrc}, @file{.shrc}, or
-various other things, depending on the shell you use.) The shell init
+ The @kbd{M-x compile} command uses a shell to run the compilation
+command, but specifies the option for a noninteractive shell. This
+means, in particular, that the shell should start with no prompt. If
+you find your usual shell prompt making an unsightly appearance in the
+@file{*compilation*} buffer, it means you have made a mistake in your
+shell's init file by setting the prompt unconditionally. (This init
+file may be named @file{.bashrc}, @file{.profile}, @file{.cshrc},
+@file{.shrc}, etc., depending on what shell you use.) The shell init
file should set the prompt only if there already is a prompt. Here's
how to do it in bash:
if ($?prompt) set prompt = @dots{}
@end example
- There may well be other things that your shell's init file
-ought to do only for an interactive shell. You can use the same
-method to conditionalize them.
+ Emacs does not expect a compiler process to launch asynchronous
+subprocesses; if it does, and they keep running after the main
+compiler process has terminated, Emacs may kill them or their output
+may not arrive in Emacs. To avoid this problem, make the main
+compilation process wait for its subprocesses to finish. In a shell
+script, you can do this using @samp{$!} and @samp{wait}, like this:
+
+@example
+(sleep 10; echo 2nd)& pid=$! # @r{Record pid of subprocess}
+echo first message
+wait $pid # @r{Wait for subprocess}
+@end example
+
+@noindent
+If the background process does not output to the compilation buffer,
+so you only need to prevent it from being killed when the main
+compilation process terminates, this is sufficient:
+
+@example
+nohup @var{command}; sleep 1
+@end example
- The MS-DOS ``operating system'' does not support asynchronous
-subprocesses; to work around this lack, @kbd{M-x compile} runs the
-compilation command synchronously on MS-DOS. As a consequence, you must
-wait until the command finishes before you can do anything else in
-Emacs.
-@iftex
-@inforef{MS-DOS,,emacs-xtra}.
-@end iftex
@ifnottex
-@xref{MS-DOS}.
+ On the MS-DOS ``operating system'', asynchronous subprocesses are
+not supported, so @kbd{M-x compile} runs the compilation command
+synchronously (i.e., you must wait until the command finishes before
+you can do anything else in Emacs). @xref{MS-DOS}.
@end ifnottex
@node Grep Searching
@section Searching with Grep under Emacs
Just as you can run a compiler from Emacs and then visit the lines
-with compilation errors, you can also run @code{grep} and then visit
-the lines on which matches were found. This works by treating the
-matches reported by @code{grep} as if they were ``errors.'' The
-buffer of matches uses Grep mode, which is a variant of Compilation
+with compilation errors, you can also run @command{grep} and then
+visit the lines on which matches were found. This works by treating
+the matches reported by @command{grep} as if they were ``errors''.
+The output buffer uses Grep mode, which is a variant of Compilation
mode (@pxref{Compilation Mode}).
@table @kbd
@item M-x grep
@itemx M-x lgrep
-Run @code{grep} asynchronously under Emacs, with matching lines
-listed in the buffer named @samp{*grep*}.
+Run @command{grep} asynchronously under Emacs, listing matching lines in
+the buffer named @file{*grep*}.
@item M-x grep-find
@itemx M-x find-grep
@itemx M-x rgrep
-Run @code{grep} via @code{find}, and collect output in the buffer
-named @samp{*grep*}.
+Run @command{grep} via @code{find}, and collect output in the
+@file{*grep*} buffer.
@item M-x zrgrep
-Run @code{zgrep} and collect output in the buffer named @samp{*grep*}.
+Run @code{zgrep} and collect output in the @file{*grep*} buffer.
@item M-x kill-grep
-Kill the running @code{grep} subprocess.
+Kill the running @command{grep} subprocess.
@end table
@findex grep
- To run @code{grep}, type @kbd{M-x grep}, then enter a command line
-that specifies how to run @code{grep}. Use the same arguments you
-would give @code{grep} when running it normally: a @code{grep}-style
+ To run @command{grep}, type @kbd{M-x grep}, then enter a command line
+that specifies how to run @command{grep}. Use the same arguments you
+would give @command{grep} when running it normally: a @command{grep}-style
regexp (usually in single-quotes to quote the shell's special
characters) followed by file names, which may use wildcards. If you
specify a prefix argument for @kbd{M-x grep}, it finds the tag
(@pxref{Tags}) in the buffer around point, and puts that into the
-default @code{grep} command.
+default @command{grep} command.
- Your command need not simply run @code{grep}; you can use any shell
+ Your command need not simply run @command{grep}; you can use any shell
command that produces output in the same format. For instance, you
-can chain @code{grep} commands, like this:
+can chain @command{grep} commands, like this:
@example
grep -nH -e foo *.el | grep bar | grep toto
@end example
- The output from @code{grep} goes in the @samp{*grep*} buffer. You
+ The output from @command{grep} goes in the @file{*grep*} buffer. You
can find the corresponding lines in the original files using @w{@kbd{C-x
`}}, @key{RET}, and so forth, just like compilation errors.
The command @kbd{M-x grep-find} (also available as @kbd{M-x
find-grep}) is similar to @kbd{M-x grep}, but it supplies a different
initial default for the command---one that runs both @code{find} and
-@code{grep}, so as to search every file in a directory tree. See also
+@command{grep}, so as to search every file in a directory tree. See also
the @code{find-grep-dired} command, in @ref{Dired and Find}.
@findex lgrep
@findex rgrep
@findex zrgrep
The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep}
-(recursive grep) are more user-friendly versions of @code{grep} and
+(recursive grep) are more user-friendly versions of @command{grep} and
@code{grep-find}, which prompt separately for the regular expression
to match, the files to search, and the base directory for the search.
Case sensitivity of the search is controlled by the current value of
@code{case-fold-search}. The command @kbd{M-x zrgrep} is similar to
-@code{rgrep}, but it calls @code{zgrep} instead of @code{grep} to
-search the contents of gzipped files.
+@kbd{M-x rgrep}, but it calls @command{zgrep} instead of
+@command{grep} to search the contents of gzipped files.
These commands build the shell commands based on the variables
@code{grep-template} (for @code{lgrep}) and @code{grep-find-template}
(for @code{rgrep}). The files to search can use aliases defined in
the variable @code{grep-files-aliases}.
- Subdirectories listed in the variable
-@code{grep-find-ignored-directories} such as those typically used by
-various version control systems, like CVS and arch, are automatically
-skipped by @code{rgrep}.
+@vindex grep-find-ignored-directories
+ Directories listed in the variable
+@code{grep-find-ignored-directories} are automatically skipped by
+@kbd{M-x rgrep}. The default value includes the data directories used
+by various version control systems.
@node Flymake
@section Finding Syntax Errors On The Fly
Flymake mode is a minor mode that performs on-the-fly syntax
checking for many programming and markup languages, including C, C++,
-Perl, HTML, and @TeX{}/La@TeX{}. It is somewhat analogous to Flyspell
+Perl, HTML, and @TeX{}/@LaTeX{}. It is somewhat analogous to Flyspell
mode, which performs spell checking for ordinary human languages in a
similar fashion (@pxref{Spelling}). As you edit a file, Flymake mode
runs an appropriate syntax checking tool in the background, using a
C/C++ files this is usually the C compiler. Flymake can also use
build tools such as @code{make} for checking complicated projects.
- To enable Flymake mode, type @kbd{M-x flymake-mode}. You can go to
-the errors found by Flymake mode with @kbd{M-x
-flymake-goto-next-error} and @kbd{M-x flymake-goto-prev-error}. To
-display any error messages associated with the current line, use
-@kbd{M-x flymake-display-err-menu-for-current-line}.
+ To enable Flymake mode, type @kbd{M-x flymake-mode}. You can jump
+to the errors that it finds by using @kbd{M-x flymake-goto-next-error}
+and @kbd{M-x flymake-goto-prev-error}. To display any error messages
+associated with the current line, type @kbd{M-x
+flymake-display-err-menu-for-current-line}.
- For more details about using Flymake, see @ref{Top, Flymake,
-Flymake, flymake, The Flymake Manual}.
+ For more details about using Flymake,
+@ifnottex
+see @ref{Top, Flymake, Flymake, flymake, The Flymake Manual}.
+@end ifnottex
+@iftex
+see the Flymake Info manual, which is distributed with Emacs.
+@end iftex
@node Debuggers
@section Running Debuggers Under Emacs
@cindex JDB
@cindex PDB
-@c Do you believe in GUD?
The GUD (Grand Unified Debugger) library provides an Emacs interface
-to a wide variety of symbolic debuggers. Unlike the GDB graphical
-interface, which only runs GDB (@pxref{GDB Graphical Interface}), GUD
-can also run DBX, SDB, XDB, Perl's debugging mode, the Python debugger
-PDB, or the Java Debugger JDB.
+to a wide variety of symbolic debuggers. It can run the GNU Debugger
+(GDB), as well as DBX, SDB, XDB, Perl's debugging mode, the Python
+debugger PDB, and the Java Debugger JDB.
+
+ Emacs provides a special interface to GDB, which uses extra Emacs
+windows to display the state of the debugged program. @xref{GDB
+Graphical Interface}.
- In addition, Emacs contains a built-in system for debugging Emacs
-Lisp programs. @xref{Debugging,, The Lisp Debugger, elisp, the Emacs
-Lisp Reference Manual}, for information on the Emacs Lisp debugger.
+ Emacs also has a built-in debugger for Emacs Lisp programs.
+@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference
+Manual}.
@menu
* Starting GUD:: How to start a debugger subprocess.
* Commands of GUD:: Key bindings for common commands.
* GUD Customization:: Defining your own commands for GUD.
* GDB Graphical Interface:: An enhanced mode that uses GDB features to
- implement a graphical debugging environment through
- Emacs.
+ implement a graphical debugging environment.
@end menu
@node Starting GUD
@subsection Starting GUD
- There are several commands for starting a debugger under GUD, each
+ There are several commands for starting a debugger subprocess, each
corresponding to a particular debugger program.
@table @kbd
-@item M-x gdb @key{RET} @var{file} @key{RET}
+@item M-x gdb
@findex gdb
-Run GDB as a subprocess of Emacs. This uses an IDE-like graphical
-interface; see @ref{GDB Graphical Interface}. Only GDB works with the
-graphical interface.
+Run GDB as a subprocess, and interact with it via an IDE-like Emacs
+interface. @xref{GDB Graphical Interface}, for more information about
+this command.
-@item M-x gud-gdb @key{RET} @var{file} @key{RET}
+@item M-x gud-gdb
@findex gud-gdb
-Run GDB as a subprocess of Emacs. This command creates a buffer for
-input and output to GDB, and switches to it. If a GDB buffer already
-exists, it just switches to that buffer.
-
-@item M-x dbx @key{RET} @var{file} @key{RET}
-@findex dbx
-Run DBX as a subprocess of Emacs. Since Emacs does not implement a
-graphical interface for DBX, communication with DBX works by typing
-commands in the GUD interaction buffer. The same is true for all
-the other supported debuggers.
-
-@item M-x xdb @key{RET} @var{file} @key{RET}
-@findex xdb
-@vindex gud-xdb-directories
-Run XDB as a subprocess of Emacs. Use the variable
-@code{gud-xdb-directories} to specify directories to search for source
-files.
-
-@item M-x sdb @key{RET} @var{file} @key{RET}
-@findex sdb
-Run SDB as a subprocess of Emacs.
+Run GDB, using a GUD interaction buffer for input and output to the
+GDB subprocess (@pxref{Debugger Operation}). If such a buffer already
+exists, switch to it; otherwise, create the buffer and switch to it.
-Some versions of SDB do not mention source file names in their
-messages. When you use them, you need to have a valid tags table
-(@pxref{Tags}) in order for GUD to find functions in the source code.
-If you have not visited a tags table or the tags table doesn't list
-one of the functions, you get a message saying @samp{The sdb support
-requires a valid tags table to work}. If this happens, generate a
-valid tags table in the working directory and try again.
+The other commands in this list do the same, for other debugger
+programs.
-@item M-x perldb @key{RET} @var{file} @key{RET}
+@item M-x perldb
@findex perldb
-Run the Perl interpreter in debug mode to debug @var{file}, a Perl program.
+Run the Perl interpreter in debug mode.
-@item M-x jdb @key{RET} @var{file} @key{RET}
+@item M-x jdb
@findex jdb
-Run the Java debugger to debug @var{file}.
+Run the Java debugger.
-@item M-x pdb @key{RET} @var{file} @key{RET}
+@item M-x pdb
@findex pdb
-Run the Python debugger to debug @var{file}.
+Run the Python debugger.
+
+@item M-x dbx
+@findex dbx
+Run the DBX debugger.
+
+@item M-x xdb
+@findex xdb
+@vindex gud-xdb-directories
+Run the XDB debugger.
+
+@item M-x sdb
+@findex sdb
+Run the SDB debugger.
@end table
- Each of these commands takes one argument: a command line to invoke
-the debugger. In the simplest case, specify just the name of the
-executable file you want to debug. You may also use options that the
-debugger supports. However, shell wildcards and variables are not
-allowed. GUD assumes that the first argument not starting with a
-@samp{-} is the executable file name.
+ Each of these commands reads a command line to invoke the debugger,
+using the minibuffer. The minibuffer's initial contents contain the
+standard executable name and options for the debugger, and sometimes
+also a guess for the name of the executable file you want to debug.
+Shell wildcards and variables are not allowed in this command line.
+Emacs assumes that the first command argument which does not start
+with a @samp{-} is the executable file name.
@cindex remote host, debugging on
-Tramp provides a facility to debug programs on remote hosts
-(@pxref{Running a debugger on a remote host, Running a debugger on a
-remote host,, tramp, The Tramp Manual}), whereby both the debugger and
-the program being debugged are on the same remote host. This should
-not be confused with debugging programs remotely, where the program
-and the debugger run on different machines, as can be done using the
-GDB remote debugging feature, for example (@pxref{Remote Debugging,,
-Debugging Remote Programs, gdb, The GNU debugger}).
+ Tramp provides a facility for remote debugging, whereby both the
+debugger and the program being debugged are on the same remote host.
+@xref{Running a debugger on a remote host,,, tramp, The Tramp Manual},
+for details. This is separate from GDB's remote debugging feature,
+where the program and the debugger run on different machines
+(@pxref{Remote Debugging,, Debugging Remote Programs, gdb, The GNU
+debugger}).
@node Debugger Operation
@subsection Debugger Operation
+@cindex GUD interaction buffer
+
+ The @dfn{GUD interaction buffer} is an Emacs buffer which is used to
+send text commands to a debugger subprocess, and record its output.
+This is the basic interface for interacting with a debugger, used by
+@kbd{M-x gud-gdb} and other commands listed in
+@iftex
+the preceding section.
+@end iftex
+@ifnottex
+@ref{Starting GUD}.
+@end ifnottex
+The @kbd{M-x gdb} command extends this interface with additional
+specialized buffers for controlling breakpoints, stack frames, and
+other aspects of the debugger state (@pxref{GDB Graphical Interface}).
-@cindex fringes, and current execution line in GUD
- Generally when you run a debugger with GUD, the debugger uses an Emacs
-buffer for its ordinary input and output. This is called the GUD
-buffer. Input and output from the program you are debugging also use
-this buffer. We call this @dfn{text command mode}. The GDB Graphical
-Interface can use further buffers (@pxref{GDB Graphical Interface}).
-
- The debugger displays the source files of the program by visiting
-them in Emacs buffers. An arrow in the left fringe indicates the
-current execution line.@footnote{On a text-only terminal, the arrow
-appears as @samp{=>} and overlays the first two text columns.} Moving
-point in this buffer does not move the arrow. The arrow is not part
-of the file's text; it appears only on the screen.
-
- You can start editing these source files at any time in the buffers
-that display them. If you do modify a source file, keep in mind that
-inserting or deleting lines will throw off the arrow's positioning;
-GUD has no way of figuring out which line corresponded before your
-changes to the line number in a debugger message. Also, you'll
-typically have to recompile and restart the program for your changes
-to be reflected in the debugger's tables.
-
-@cindex tooltips with GUD
-@vindex tooltip-gud-modes
-@vindex gud-tooltip-mode
+ The GUD interaction buffer uses a variant of Shell mode, so the
+Emacs commands defined by Shell mode are available (@pxref{Shell
+Mode}). Completion is available for most debugger commands
+(@pxref{Completion}), and you can use the usual Shell mode history
+commands to repeat them.
+@iftex
+See the next section
+@end iftex
+@ifnottex
+@xref{Commands of GUD},
+@end ifnottex
+for special commands that can be used in the GUD interaction buffer.
+
+ As you debug a program, Emacs displays the relevant source files by
+visiting them in Emacs buffers, with an arrow in the left fringe
+indicating the current execution line. (On a text terminal, the arrow
+appears as @samp{=>}, overlaid on the first two text columns.) Moving
+point in such a buffer does not move the arrow. You are free to edit
+these source files, but note that inserting or deleting lines will
+throw off the arrow's positioning, as Emacs has no way to figure out
+which edited source line corresponds to the line reported by the
+debugger subprocess. To update this information, you typically have
+to recompile and restart the program.
+
+@cindex GUD Tooltip mode
+@cindex mode, GUD Tooltip
+@findex gud-tooltip-mode
@vindex gud-tooltip-echo-area
- The Tooltip facility (@pxref{Tooltips}) provides support for GUD@.
-You activate this feature by turning on the minor mode
-@code{gud-tooltip-mode}. Then you can display a variable's value in a
-tooltip simply by pointing at it with the mouse. This operates in the
-GUD buffer and in source buffers with major modes in the list
-@code{gud-tooltip-modes}. If the variable @code{gud-tooltip-echo-area}
-is non-@code{nil} then the variable's value is displayed in the echo
-area. When debugging a C program using the GDB Graphical Interface, you
-can also display macro definitions associated with an identifier when
-the program is not executing.
-
- GUD tooltips are disabled when you use GDB in text command mode
-(@pxref{GDB Graphical Interface}), because displaying an expression's
-value in GDB can sometimes expand a macro and result in a side effect
-that interferes with the program's operation. The GDB graphical
-interface supports GUD tooltips and assures they will not cause side
-effects.
+ GUD Tooltip mode is a global minor mode that adds tooltip support to
+GUD@. To toggle this mode, type @kbd{M-x gud-tooltip-mode}. It is
+disabled by default. If enabled, you can move the mouse cursor over a
+variable, a function, or a macro (collectively called
+@dfn{identifiers}) to show their values in tooltips
+(@pxref{Tooltips}). Alternatively, mark an identifier or an
+expression by dragging the mouse over it, then leave the mouse in the
+marked area to have the value of the expression displayed in a
+tooltip. The GUD Tooltip mode takes effect in the GUD interaction
+buffer, and in all source buffers with major modes listed in the
+variable @code{gud-tooltip-modes}. If the variable
+@code{gud-tooltip-echo-area} is non-@code{nil}, or if you turned off
+the tooltip mode, values are shown in the echo area instead of a
+tooltip.
+
+ When using GUD Tooltip mode with @kbd{M-x gud-gdb}, displaying an
+expression's value in GDB can sometimes expand a macro, potentially
+causing side effects in the debugged program. For that reason, using
+tooltips in @code{gud-gdb} is disabled. If you use the @kbd{M-x gdb}
+interface, this problem does not occur, as there is special code to
+avoid side-effects; furthermore, you can display macro definitions
+associated with an identifier when the program is not executing.
@node Commands of GUD
@subsection Commands of GUD
- The GUD interaction buffer uses a variant of Shell mode, so the
-Emacs commands of Shell mode are available (@pxref{Shell Mode}). All
-the usual commands for your debugger are available, and you can use
-the Shell mode history commands to repeat them. If you wish, you can
-control your debugger process entirely through this buffer.
-
- GUD mode also provides commands for setting and clearing
-breakpoints, for selecting stack frames, and for stepping through the
-program. These commands are available both in the GUD buffer and
-globally, but with different key bindings. It also has its own tool
-bar from which you can invoke the more common commands by clicking on
-the appropriate icon. This is particularly useful for repetitive
-commands like @code{gud-next} and @code{gud-step}, and allows you to
-keep the GUD buffer hidden.
-
- The breakpoint commands are normally used in source file buffers,
-because that is the easiest way to specify where to set or clear the
-breakpoint. Here's the global command to set a breakpoint:
+ GUD provides commands for setting and clearing breakpoints,
+selecting stack frames, and stepping through the program.
@table @kbd
-@item C-x @key{SPC}
-@kindex C-x SPC
+@item C-x C-a C-b
+@kindex C-x C-a C-b
Set a breakpoint on the source line that point is on.
@end table
+ @kbd{C-x C-a C-b} (@code{gud-break}), when called in a source
+buffer, sets a debugger breakpoint on the current source line. This
+command is available only after starting GUD@. If you call it in a
+buffer that is not associated with any debugger subprocess, it signals
+a error.
+
@kindex C-x C-a @r{(GUD)}
- Here are the other special commands provided by GUD@. The keys
+ The following commands are available both in the GUD interaction
+buffer and globally, but with different key bindings. The keys
starting with @kbd{C-c} are available only in the GUD interaction
-buffer. The key bindings that start with @kbd{C-x C-a} are available
-in the GUD interaction buffer and also in source files. Some of these
-commands are not available to all the supported debuggers.
+buffer, while those starting with @kbd{C-x C-a} are available
+globally. Some of these commands are also available via the tool bar;
+some are not supported by certain debuggers.
@table @kbd
@item C-c C-l
@kindex C-c C-l @r{(GUD)}
@itemx C-x C-a C-l
@findex gud-refresh
-Display in another window the last line referred to in the GUD
-buffer (that is, the line indicated in the last location message).
-This runs the command @code{gud-refresh}.
+Display, in another window, the last source line referred to in the
+GUD interaction buffer (@code{gud-refresh}).
@item C-c C-s
@kindex C-c C-s @r{(GUD)}
@itemx C-x C-a C-s
@findex gud-step
-Execute a single line of code (@code{gud-step}). If the line contains
-a function call, execution stops after entering the called function.
+Execute the next single line of code (@code{gud-step}). If the line
+contains a function call, execution stops after entering the called
+function.
@item C-c C-n
@kindex C-c C-n @r{(GUD)}
@itemx C-x C-a C-n
@findex gud-next
-Execute a single line of code, stepping across entire function calls
-at full speed (@code{gud-next}).
+Execute the next single line of code, stepping across function calls
+without stopping inside the functions (@code{gud-next}).
@item C-c C-i
@kindex C-c C-i @r{(GUD)}
that makes sense.
Because @key{TAB} serves as a completion command, you can't use it to
-enter a tab as input to the program you are debugging with GDB.
+enter a tab as input to the program you are debugging with GDB@.
Instead, type @kbd{C-q @key{TAB}} to enter a tab.
@node GUD Customization
@vindex perldb-mode-hook
@vindex pdb-mode-hook
@vindex jdb-mode-hook
- On startup, GUD runs one of the following hooks: @code{gdb-mode-hook},
-if you are using GDB; @code{dbx-mode-hook}, if you are using DBX;
-@code{sdb-mode-hook}, if you are using SDB; @code{xdb-mode-hook}, if you
-are using XDB; @code{perldb-mode-hook}, for Perl debugging mode;
-@code{pdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB. You can
-use these hooks to define custom key bindings for the debugger
-interaction buffer. @xref{Hooks}.
-
- Here is a convenient way to define a command that sends a particular
-command string to the debugger, and set up a key binding for it in the
-debugger interaction buffer:
+ On startup, GUD runs one of the following hooks:
+@code{gdb-mode-hook}, if you are using GDB; @code{dbx-mode-hook}, if
+you are using DBX; @code{sdb-mode-hook}, if you are using SDB;
+@code{xdb-mode-hook}, if you are using XDB; @code{perldb-mode-hook},
+for Perl debugging mode; @code{pdb-mode-hook}, for PDB;
+@code{jdb-mode-hook}, for JDB@. @xref{Hooks}.
+
+ The @code{gud-def} Lisp macro (@pxref{Defining Macros,,, elisp, the
+Emacs Lisp Reference Manual}) provides a convenient way to define an
+Emacs command that sends a particular command string to the debugger,
+and set up a key binding for in the GUD interaction buffer:
@findex gud-def
@example
@node GDB Graphical Interface
@subsection GDB Graphical Interface
- The command @code{gdb} starts GDB in a graphical interface, using
-Emacs windows for display program state information. With it, you do
-not need to use textual GDB commands; you can control the debugging
-session with the mouse. For example, you can click in the fringe of a
-source buffer to set a breakpoint there, or on a stack frame in the
-stack buffer to select that frame.
-
- This mode requires telling GDB that its ``screen size'' is
-unlimited, so it sets the height and width accordingly. For correct
-operation you must not change these values during the GDB session.
+ The command @kbd{M-x gdb} starts GDB in an IDE-like interface, with
+specialized buffers for controlling breakpoints, stack frames, and
+other aspects of the debugger state. It also provides additional ways
+to control the debugging session with the mouse, such as clicking in
+the fringe of a source buffer to set a breakpoint there.
@vindex gud-gdb-command-name
- To run GDB in text command mode, like the other debuggers in Emacs,
-use @kbd{M-x gud-gdb}. You need to use text command mode to debug
-multiple programs within one Emacs session.
+ To run GDB using just the GUD interaction buffer interface, without
+these additional features, use @kbd{M-x gud-gdb} (@pxref{Starting
+GUD}). You must use this if you want to debug multiple programs
+within one Emacs session, as that is currently unsupported by @kbd{M-x
+gdb}.
+
+ Internally, @kbd{M-x gdb} informs GDB that its ``screen size'' is
+unlimited; for correct operation, you must not change GDB's screen
+height and width values during the debugging session.
@menu
-* GDB-UI Layout:: Control the number of displayed buffers.
+* GDB User Interface Layout:: Control the number of displayed buffers.
* Source Buffers:: Use the mouse in the fringe/margin to
control your program.
* Breakpoints Buffer:: A breakpoint control panel.
+* Threads Buffer:: Displays your threads.
* Stack Buffer:: Select a frame from the call stack.
-* Other GDB-UI Buffers:: Input/output, locals, registers,
- assembler, threads and memory buffers.
+* Other GDB Buffers:: Other buffers for controlling the GDB state.
* Watch Expressions:: Monitor variable values in the speedbar.
-* Reverse Debugging:: Execute and reverse debug your program.
+* Multithreaded Debugging:: Debugging programs with several threads.
@end menu
-@node GDB-UI Layout
+@node GDB User Interface Layout
@subsubsection GDB User Interface Layout
@cindex GDB User Interface layout
@vindex gdb-many-windows
- If the variable @code{gdb-many-windows} is @code{nil} (the default
-value) then @kbd{M-x gdb} normally displays only the GUD buffer.
+ If the variable @code{gdb-many-windows} is @code{nil} (the default),
+@kbd{M-x gdb} normally displays only the GUD interaction buffer.
However, if the variable @code{gdb-show-main} is also non-@code{nil},
-it starts with two windows: one displaying the GUD buffer, and the
-other showing the source for the @code{main} function of the program
-you are debugging.
+it starts with two windows: one displaying the GUD interaction buffer,
+and the other showing the source for the @code{main} function of the
+program you are debugging.
If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb}
displays the following frame layout:
@smallexample
@group
+--------------------------------+--------------------------------+
-| GUD buffer (I/O of GDB) | Locals/Registers buffer |
+| GUD interaction buffer | Locals/Registers buffer |
|--------------------------------+--------------------------------+
| Primary Source buffer | I/O buffer for debugged pgm |
|--------------------------------+--------------------------------+
@end group
@end smallexample
- However, if @code{gdb-use-separate-io-buffer} is @code{nil}, the I/O
-buffer does not appear and the primary source buffer occupies the full
-width of the frame.
-
@findex gdb-restore-windows
- If you change the window layout, for example, while editing and
-re-compiling your program, then you can restore this standard window
-layout with the command @code{gdb-restore-windows}.
-
@findex gdb-many-windows
- To switch between this standard layout and a simple layout
-containing just the GUD buffer and a source file, type @kbd{M-x
-gdb-many-windows}.
+ If you ever change the window layout, you can restore the ``many
+windows'' layout by typing @kbd{M-x gdb-restore-windows}. To toggle
+between the many windows layout and a simple layout with just the GUD
+interaction buffer and a source file, type @kbd{M-x gdb-many-windows}.
You may also specify additional GDB-related buffers to display,
either in the same frame or a different one. Select the buffers you
-want with the @samp{GUD->GDB-Windows} and @samp{GUD->GDB-Frames}
-sub-menus. If the menu-bar is unavailable, type @code{M-x
-gdb-display-@var{buffertype}-buffer} or @code{M-x
-gdb-frame-@var{buffertype}-buffer} respectively, where
-@var{buffertype} is the relevant buffer type, such as
-@samp{breakpoints}. Most of these buffers are read-only, and typing
-@kbd{q} in them kills them.
-
- When you finish debugging, kill the GUD buffer with @kbd{C-x k},
-which will also kill all the buffers associated with the session.
-However you need not do this if, after editing and re-compiling your
-source code within Emacs, you wish continue debugging. When you
-restart execution, GDB will automatically find your new executable.
-Keeping the GUD buffer has the advantage of keeping the shell history
-as well as GDB's breakpoints. You do need to check that the
-breakpoints in recently edited source files are still in the right
-places.
+want by typing @code{M-x gdb-display-@var{buffertype}-buffer} or
+@code{M-x gdb-frame-@var{buffertype}-buffer}, where @var{buffertype}
+is the relevant buffer type, such as @samp{breakpoints}. You can do
+the same with the menu bar, with the @samp{GDB-Windows} and
+@samp{GDB-Frames} sub-menus of the @samp{GUD} menu.
+
+ When you finish debugging, kill the GUD interaction buffer with
+@kbd{C-x k}, which will also kill all the buffers associated with the
+session. However you need not do this if, after editing and
+re-compiling your source code within Emacs, you wish to continue
+debugging. When you restart execution, GDB automatically finds the
+new executable. Keeping the GUD interaction buffer has the advantage
+of keeping the shell history as well as GDB's breakpoints. You do
+need to check that the breakpoints in recently edited source files are
+still in the right places.
@node Source Buffers
@subsubsection Source Buffers
-@cindex GDB commands in Fringe
-
-@c @findex gdb-mouse-set-clear-breakpoint
-@c @findex gdb-mouse-toggle-breakpoint
-Many GDB commands can be entered using key bindings or the tool bar but
-sometimes it is quicker to use the fringe. These commands either
-manipulate breakpoints or control program execution. When there is no
-fringe, you can use the margin but this is only present when the
-source file already has a breakpoint.
-
-You can click @kbd{Mouse-1} in the fringe or display margin of a
-source buffer to set a breakpoint there and, on a graphical display, a
-red bullet will appear on that line. If a breakpoint already exists
-on that line, the same click will remove it. You can also enable or
-disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet.
-
-A solid arrow in the left fringe of a source buffer indicates the line
-of the innermost frame where the debugged program has stopped. A
-hollow arrow indicates the current execution line of higher level
-frames.
-
-If you drag the arrow in the fringe with @kbd{Mouse-1}
-(@code{gdb-mouse-until}), execution will continue to the line where
-you release the button, provided it is still in the same frame.
-Alternatively, you can click @kbd{Mouse-3} at some point in the fringe
-of this buffer and execution will advance to there. A similar command
-(@code{gdb-mouse-jump}) allows you to jump to a source line without
-executing the intermediate lines by clicking @kbd{C-Mouse-3}. This
-command allows you to go backwards which can be useful for running
-through code that has already executed, in order to examine its
-execution in more detail.
+@cindex fringes, for debugging
-@table @kbd
-@item Mouse-1
-Set or clear a breakpoint.
+@table @asis
+@item @kbd{Mouse-1} (in fringe)
+Set or clear a breakpoint on that line.
-@item C-Mouse-1
-Enable or disable a breakpoint.
+@item @kbd{C-Mouse-1} (in fringe)
+Enable or disable a breakpoint on that line.
-@item Mouse-3
-Continue execution to here.
+@item @kbd{Mouse-3} (in fringe)
+Continue execution to that line.
-@item C-Mouse-3
-Jump to here.
+@item @kbd{C-Mouse-3} (in fringe)
+Jump to that line.
@end table
-If the variable @code{gdb-find-source-frame} is non-@code{nil} and
-execution stops in a frame for which there is no source code e.g after
-an interrupt, then Emacs finds and displays the first frame further up
-stack for which there is source. If it is @code{nil} then the source
-buffer continues to display the last frame which maybe more useful,
-for example, when re-setting a breakpoint.
+ On a graphical display, you can click @kbd{Mouse-1} in the fringe of
+a source buffer, to set a breakpoint on that line (@pxref{Fringes}).
+A red dot appears in the fringe, where you clicked. If a breakpoint
+already exists there, the click removes it. A @kbd{C-Mouse-1} click
+enables or disables an existing breakpoint; a breakpoint that is
+disabled, but not unset, is indicated by a gray dot.
+
+ On a text terminal, or when fringes are disabled, enabled
+breakpoints are indicated with a @samp{B} character in the left margin
+of the window. Disabled breakpoints are indicated with @samp{b}.
+(The margin is only displayed if a breakpoint is present.)
+
+ A solid arrow in the left fringe of a source buffer indicates the
+line of the innermost frame where the debugged program has stopped. A
+hollow arrow indicates the current execution line of a higher-level
+frame. If you drag the arrow in the fringe with @kbd{Mouse-1}, that
+causes execution to advance to the line where you release the button.
+Alternatively, you can click @kbd{Mouse-3} in the fringe to advance to
+that line. You can click @kbd{C-Mouse-3} in the fringe to jump to
+that line without executing the intermediate lines. This command
+allows you to go backwards, which can be useful for running through
+code that has already executed, in order to examine its execution in
+more detail.
@node Breakpoints Buffer
@subsubsection Breakpoints Buffer
- The breakpoints buffer shows the existing breakpoints, watchpoints and
-catchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}). It has
-these special commands, which mostly apply to the @dfn{current
-breakpoint}, the breakpoint which point is on.
+ The GDB Breakpoints buffer shows the breakpoints, watchpoints and
+catchpoints in the debugger session. @xref{Breakpoints,,, gdb, The
+GNU debugger}. It provides the following commands, which mostly apply
+to the @dfn{current breakpoint} (the breakpoint which point is on):
@table @kbd
@item @key{SPC}
-@kindex SPC @r{(GDB breakpoints buffer)}
+@kindex SPC @r{(GDB Breakpoints buffer)}
@findex gdb-toggle-breakpoint
-Enable/disable current breakpoint (@code{gdb-toggle-breakpoint}).
-On a graphical display, this changes the color of a bullet in the
-margin of a source buffer at the relevant line. This is red when
-the breakpoint is enabled and grey when it is disabled. Text-only
-terminals correspondingly display a @samp{B} or @samp{b}.
+Enable/disable current breakpoint (@code{gdb-toggle-breakpoint}). On
+a graphical display, this changes the color of the dot in the fringe
+of the source buffer at that line. The dot is red when the breakpoint
+is enabled, and gray when it is disabled.
@item D
-@kindex D @r{(GDB breakpoints buffer)}
+@kindex D @r{(GDB Breakpoints buffer)}
@findex gdb-delete-breakpoint
Delete the current breakpoint (@code{gdb-delete-breakpoint}).
@item @key{RET}
-@kindex RET @r{(GDB breakpoints buffer)}
+@kindex RET @r{(GDB Breakpoints buffer)}
@findex gdb-goto-breakpoint
Visit the source line for the current breakpoint
(@code{gdb-goto-breakpoint}).
@item Mouse-2
-@kindex Mouse-2 @r{(GDB breakpoints buffer)}
+@kindex Mouse-2 @r{(GDB Breakpoints buffer)}
Visit the source line for the breakpoint you click on.
@end table
-When @code{gdb-many-windows} is non-@code{nil}, the breakpoints buffer
-shares its window with the threads buffer. To switch from one to the
-other click with @kbd{Mouse-1} on the relevant button in the header
-line.
+@vindex gdb-show-threads-by-default
+ When @code{gdb-many-windows} is non-@code{nil}, the GDB Breakpoints
+buffer shares its window with the GDB Threads buffer. To switch from
+one to the other click with @kbd{Mouse-1} on the relevant button in
+the header line. If @code{gdb-show-threads-by-default} is
+non-@code{nil}, the GDB Threads buffer is the one shown by default.
+
+@node Threads Buffer
+@subsubsection Threads Buffer
+
+@findex gdb-select-thread
+ The GDB Threads buffer displays a summary of the threads in the
+debugged program. @xref{Threads, Threads, Debugging programs with
+multiple threads, gdb, The GNU debugger}. To select a thread, move
+point there and press @key{RET} (@code{gdb-select-thread}), or click on
+it with @kbd{Mouse-2}. This also displays the associated source
+buffer, and updates the contents of the other GDB buffers.
+
+ You can customize variables under @code{gdb-buffers} group to select
+fields included in GDB Threads buffer.
+
+@table @code
+@item gdb-thread-buffer-verbose-names
+@vindex gdb-thread-buffer-verbose-names
+Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)}.
+
+@item gdb-thread-buffer-arguments
+@vindex gdb-thread-buffer-arguments
+Show arguments of thread top frames.
+
+@item gdb-thread-buffer-locations
+@vindex gdb-thread-buffer-locations
+Show file information or library names.
+
+@item gdb-thread-buffer-addresses
+@vindex gdb-thread-buffer-addresses
+Show addresses for thread frames in threads buffer.
+@end table
+
+ To view information for several threads simultaneously, use the
+following commands from the GDB Threads buffer.
+
+@table @kbd
+@item d
+@kindex d @r{(GDB threads buffer)}
+@findex gdb-display-disassembly-for-thread
+Display disassembly buffer for the thread at current line
+(@code{gdb-display-disassembly-for-thread}).
+
+@item f
+@kindex f @r{(GDB threads buffer)}
+@findex gdb-display-stack-for-thread
+Display the GDB Stack buffer for the thread at current line
+(@code{gdb-display-stack-for-thread}).
+
+@item l
+@kindex l @r{(GDB threads buffer)}
+@findex gdb-display-locals-for-thread
+Display the GDB Locals buffer for the thread at current line
+(@code{gdb-display-locals-for-thread}).
+
+@item r
+@kindex r @r{(GDB threads buffer)}
+@findex gdb-display-registers-for-thread
+Display the GDB Registers buffer for the thread at current line
+(@code{gdb-display-registers-for-thread}).
+@end table
+
+@noindent
+Their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and @kbd{R},
+display the corresponding buffer in a new frame.
+
+ When you create a buffer showing information about some specific
+thread, it becomes bound to that thread and keeps showing actual
+information while you debug your program. The mode indicator for each
+GDB buffer shows the number of thread it is showing information about.
+The thread number is also included in the buffer name of bound
+buffers.
+
+ Further commands are available in the GDB Threads buffer which
+depend on the mode of GDB that is used for controlling execution of
+your program. @xref{Multithreaded Debugging}.
@node Stack Buffer
@subsubsection Stack Buffer
- The stack buffer displays a @dfn{call stack}, with one line for each
-of the nested subroutine calls (@dfn{stack frames}) now active in the
-program. @xref{Backtrace,, Backtraces, gdb, The GNU debugger}.
+ The GDB Stack buffer displays a @dfn{call stack}, with one line for
+each of the nested subroutine calls (@dfn{stack frames}) in the
+debugger session. @xref{Backtrace,, Backtraces, gdb, The GNU
+debugger}.
@findex gdb-frames-select
-An arrow in the fringe points to the selected frame or, if the fringe is
-not present, the number of the selected frame is displayed in reverse
-contrast. To select a frame in GDB, move point in the stack buffer to
-that stack frame and type @key{RET} (@code{gdb-frames-select}), or click
-@kbd{Mouse-2} on a stack frame. If the locals buffer is visible,
-selecting a stack frame updates it to display the local variables of the
-new frame.
+ On graphical displays, the selected stack frame is indicated by an
+arrow in the fringe. On text terminals, or when fringes are disabled,
+the selected stack frame is displayed in reverse contrast. To select
+a stack frame, move point in its line and type @key{RET}
+(@code{gdb-frames-select}), or click @kbd{Mouse-2} on it. Doing so
+also updates the Locals buffer
+@ifnottex
+(@pxref{Other GDB Buffers}).
+@end ifnottex
+@iftex
+(described in the next section).
+@end iftex
-@node Other GDB-UI Buffers
-@subsubsection Other Buffers
+@node Other GDB Buffers
+@subsubsection Other GDB Buffers
@table @asis
-@item Input/Output Buffer
-@vindex gdb-use-separate-io-buffer
-If the variable @code{gdb-use-separate-io-buffer} is non-@code{nil},
-the program being debugged takes its input and displays its output
-here. Otherwise it uses the GUD buffer for that. To toggle whether
-GUD mode uses this buffer, do @kbd{M-x gdb-use-separate-io-buffer}.
-This takes effect when you next restart the program you are debugging.
-
-The history and replay commands from Shell mode are available here,
-as are the commands to send signals to the debugged program.
-@xref{Shell Mode}.
-
@item Locals Buffer
-The locals buffer displays the values of local variables of the
-current frame for simple data types (@pxref{Frame Info, Frame Info,
+This buffer displays the values of local variables of the current
+frame for simple data types (@pxref{Frame Info, Frame Info,
Information on a frame, gdb, The GNU debugger}). Press @key{RET} or
click @kbd{Mouse-2} on the value if you want to edit it.
Arrays and structures display their type only. With GDB 6.4 or later,
-move point to their name and press @key{RET}, or alternatively click
-@kbd{Mouse-2} there, to examine their values. With earlier versions
-of GDB, use @kbd{Mouse-2} or @key{RET} on the type description
+you can examine the value of the local variable at point by typing
+@key{RET}, or with a @kbd{Mouse-2} click. With earlier versions of
+GDB, use @key{RET} or @kbd{Mouse-2} on the type description
(@samp{[struct/union]} or @samp{[array]}). @xref{Watch Expressions}.
@item Registers Buffer
@findex toggle-gdb-all-registers
-The registers buffer displays the values held by the registers
+This buffer displays the values held by the registers
(@pxref{Registers,,, gdb, The GNU debugger}). Press @key{RET} or
-click @kbd{Mouse-2} on a register if you want to edit its value.
-With GDB 6.4 or later, recently changed register values display with
-@code{font-lock-warning-face}. With earlier versions of GDB, you can
-press @key{SPC} to toggle the display of floating point registers
-(@code{toggle-gdb-all-registers}).
+click @kbd{Mouse-2} on a register if you want to edit its value. With
+GDB 6.4 or later, recently changed register values display with
+@code{font-lock-warning-face}.
@item Assembler Buffer
The assembler buffer displays the current frame as machine code. An
breakpoints as in a source buffer. Breakpoint icons also appear in
the fringe or margin.
-@item Threads Buffer
-@findex gdb-threads-select
-The threads buffer displays a summary of all threads currently in your
-program (@pxref{Threads, Threads, Debugging programs with multiple
-threads, gdb, The GNU debugger}). Move point to any thread in the
-list and press @key{RET} to select it (@code{gdb-threads-select}) and
-display the associated source in the primary source buffer.
-Alternatively, click @kbd{Mouse-2} on a thread to select it. If the
-locals buffer is visible, its contents update to display the variables
-that are local in the new thread.
-
-When there is more than one main thread and the threads buffer is
-present, Emacs displays the selected thread number in the mode line of
-many of the GDB-UI Buffers.
-
@item Memory Buffer
The memory buffer lets you examine sections of program memory
(@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}).
size for these data items.
@end table
-When @code{gdb-many-windows} is non-@code{nil}, the threads buffer
-shares its window with the breakpoints buffer, and the locals buffer
-with the registers buffer. To switch from one to the other click with
+When @code{gdb-many-windows} is non-@code{nil}, the locals buffer
+shares its window with the registers buffer, just like breakpoints and
+threads buffers. To switch from one to the other, click with
@kbd{Mouse-1} on the relevant button in the header line.
@node Watch Expressions
specify a prefix argument, you can enter the variable name in the
minibuffer.
- Each watch expression is displayed in the speedbar. Complex data
-types, such as arrays, structures and unions are represented in a tree
-format. Leaves and simple data types show the name of the expression
-and its value and, when the speedbar frame is selected, display the
-type as a tooltip. Higher levels show the name, type and address
-value for pointers and just the name and type otherwise. Root expressions
-also display the frame address as a tooltip to help identify the frame
-in which they were defined.
+ Each watch expression is displayed in the speedbar
+(@pxref{Speedbar}). Complex data types, such as arrays, structures
+and unions are represented in a tree format. Leaves and simple data
+types show the name of the expression and its value and, when the
+speedbar frame is selected, display the type as a tooltip. Higher
+levels show the name, type and address value for pointers and just the
+name and type otherwise. Root expressions also display the frame
+address as a tooltip to help identify the frame in which they were
+defined.
To expand or contract a complex data type, click @kbd{Mouse-2} or
press @key{SPC} on the tag to the left of the expression. Emacs asks
non-@code{nil}. This can be useful if you are debugging with a full
screen Emacs frame.
-@node Reverse Debugging
-@subsubsection Reverse Debugging
-
- The GDB tool bar shares many buttons with the other GUD debuggers
-for tasks like stepping and printing expressions. It also has a
-further set of buttons that allow reverse debugging (@pxref{Process
-Record and Replay, , ,gdb, The GNU debugger}). This is useful when it
-takes a long time to reproduce the conditions where your program fails
-or for transient problems, like race conditions in multi-threaded
-programs, where a failure might otherwise be hard to reproduce.
-
-To use reverse debugging, set a breakpoint slightly before the
-location of interest and run your program to that point. Enable
-process recording by clicking on the record button. At this point, a
-new set of buttons appear. These buttons allow program execution in
-the reverse direction. Run your program over the code where the
-problem occurs, and then use the new set of buttons to retrace your
-steps, examine values, and analyze the problem. When analysis is
-complete, turn off process recording by clicking on the record button
-again.
+@node Multithreaded Debugging
+@subsubsection Multithreaded Debugging
+@cindex Multithreaded debugging in GDB
+@cindex Non-stop debugging in GDB
+
+ In GDB's @dfn{all-stop mode}, whenever your program stops, all
+execution threads stop. Likewise, whenever you restart the program,
+all threads start executing. @xref{All-Stop Mode, , All-Stop Mode,
+gdb, The GNU debugger}. For some multi-threaded targets, GDB supports
+a further mode of operation, called @dfn{non-stop mode}, in which you
+can examine stopped program threads in the debugger while other
+threads continue to execute freely. @xref{Non-Stop Mode, , Non-Stop
+Mode, gdb, The GNU debugger}. Versions of GDB prior to 7.0 do not
+support non-stop mode, and it does not work on all targets.
+
+@vindex gdb-non-stop-setting
+ The variable @code{gdb-non-stop-setting} determines whether Emacs
+runs GDB in all-stop mode or non-stop mode. The default is @code{t},
+which means it tries to use non-stop mode if that is available. If
+you change the value to @code{nil}, or if non-stop mode is
+unavailable, Emacs runs GDB in all-stop mode. The variable takes
+effect when Emacs begins a debugging session; if you change its value,
+you should restart any active debugging session.
+
+@vindex gdb-switch-when-another-stopped
+ When a thread stops in non-stop mode, Emacs usually switches to that
+thread. If you don't want Emacs to do this switch if another stopped
+thread is already selected, change the variable
+@code{gdb-switch-when-another-stopped} to @code{nil}.
+
+@vindex gdb-switch-reasons
+ Emacs can decide whether or not to switch to the stopped thread
+depending on the reason which caused the stop. Customize the variable
+@code{gdb-switch-reasons} to select the stop reasons which will cause
+a thread switch.
+
+@vindex gdb-stopped-functions
+ The variable @code{gdb-stopped-functions} allows you to execute your
+functions whenever some thread stops.
+
+ In non-stop mode, you can switch between different modes for GUD
+execution control commands.
+
+@vindex gdb-gud-control-all-threads
+@table @dfn
+@item Non-stop/A
+
+ When @code{gdb-gud-control-all-threads} is @code{t} (the default
+value), interruption and continuation commands apply to all threads,
+so you can halt or continue all your threads with one command using
+@code{gud-stop-subjob} and @code{gud-cont}, respectively. The
+@samp{Go} button is shown on the toolbar when at least one thread is
+stopped, whereas @samp{Stop} button is shown when at least one thread
+is running.
+
+@item Non-stop/T
+
+When @code{gdb-gud-control-all-threads} is @code{nil}, only the
+current thread is stopped/continued. @samp{Go} and @samp{Stop}
+buttons on the GUD toolbar are shown depending on the state of current
+thread.
+@end table
+
+You can change the current value of @code{gdb-gud-control-all-threads}
+from the tool bar or from @samp{GUD->GDB-MI} menu.
+
+ Stepping commands always apply to the current thread.
+
+ In non-stop mode, you can interrupt/continue your threads without
+selecting them. Hitting @kbd{i} in threads buffer interrupts thread
+under point, @kbd{c} continues it, @kbd{s} steps through. More such
+commands may be added in the future.
+
+ Note that when you interrupt a thread, it stops with the
+@samp{signal received} reason. If that reason is included in your
+@code{gdb-switch-reasons} (it is by default), Emacs will switch to
+that thread.
@node Executing Lisp
@section Executing Lisp Expressions
- Emacs has several different major modes for Lisp and Scheme. They are
-the same in terms of editing commands, but differ in the commands for
-executing Lisp expressions. Each mode has its own purpose.
+ Emacs has major modes for several variants of Lisp. They use the
+same editing commands as other programming language modes
+(@pxref{Programs}). In addition, they provide special commands for
+executing Lisp expressions.
@table @asis
-@item Emacs-Lisp mode
-The mode for editing source files of programs to run in Emacs Lisp.
-This mode defines @kbd{C-M-x} to evaluate the current defun.
-@xref{Lisp Libraries}.
+@item Emacs Lisp mode
+The mode for editing Emacs Lisp source files. It defines @kbd{C-M-x}
+to evaluate the current top-level Lisp expression. @xref{Lisp Eval}.
+
@item Lisp Interaction mode
-The mode for an interactive session with Emacs Lisp. It defines
-@kbd{C-j} to evaluate the sexp before point and insert its value in the
+The mode for an interactive Emacs Lisp session. It defines @kbd{C-j}
+to evaluate the expression before point and insert its value in the
buffer. @xref{Lisp Interaction}.
+
@item Lisp mode
The mode for editing source files of programs that run in Lisps other
-than Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defun
-to an inferior Lisp process. @xref{External Lisp}.
+than Emacs Lisp. It defines @kbd{C-M-x} to evaluate the current
+top-level expression in an external Lisp. @xref{External Lisp}.
+
@item Inferior Lisp mode
-The mode for an interactive session with an inferior Lisp process.
-This mode combines the special features of Lisp mode and Shell mode
-(@pxref{Shell Mode}).
+The mode for an interactive session with an external Lisp which is
+being run as a subprocess (or @dfn{inferior process}) of Emacs.
+@ifnottex
+@xref{External Lisp}.
+@end ifnottex
+
@item Scheme mode
-Like Lisp mode but for Scheme programs.
+Like Lisp mode, but for Scheme programs.
+
@item Inferior Scheme mode
-The mode for an interactive session with an inferior Scheme process.
+Like Inferior Lisp mode, but for Scheme.
@end table
- Most editing commands for working with Lisp programs are in fact
-available globally. @xref{Programs}.
-
@node Lisp Libraries
@section Libraries of Lisp Code for Emacs
@cindex libraries
@cindex loading Lisp code
- Lisp code for Emacs editing commands is stored in files whose names
-conventionally end in @file{.el}. This ending tells Emacs to edit them in
-Emacs-Lisp mode (@pxref{Executing Lisp}).
+ Emacs Lisp code is stored in files whose names conventionally end in
+@file{.el}. Such files are automatically visited in Emacs Lisp mode.
@cindex byte code
Emacs Lisp code can be compiled into byte-code, which loads faster,
-takes up less space, and executes faster. @xref{Byte Compilation,,
-Byte Compilation, elisp, the Emacs Lisp Reference Manual}. By
-convention, the compiled code for a library goes in a separate file
-whose name ends in @samp{.elc}. Thus, the compiled code for
-@file{foo.el} goes in @file{foo.elc}.
+takes up less space, and executes faster. By convention, compiled
+Emacs Lisp code goes in a separate file whose name ends in
+@samp{.elc}. For example, the compiled code for @file{foo.el} goes in
+@file{foo.elc}. @xref{Byte Compilation,, Byte Compilation, elisp, the
+Emacs Lisp Reference Manual}.
@findex load-file
- To execute a file of Emacs Lisp code, use @kbd{M-x load-file}. This
-command reads a file name using the minibuffer and then executes the
-contents of that file as Lisp code. It is not necessary to visit the
-file first; in any case, this command reads the file as found on disk,
-not text in an Emacs buffer.
+ To @dfn{load} an Emacs Lisp file, type @kbd{M-x load-file}. This
+command reads a file name using the minibuffer, and executes the
+contents of that file as Emacs Lisp code. It is not necessary to
+visit the file first; this command reads the file directly from disk,
+not from an existing Emacs buffer.
@findex load
@findex load-library
- Once a file of Lisp code is installed in the Emacs Lisp library
-directories, users can load it using @kbd{M-x load-library}. Programs
-can load it by calling @code{load}, a more primitive function that is
-similar but accepts some additional arguments.
-
- @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it
-searches a sequence of directories and tries three file names in each
-directory. Suppose your argument is @var{lib}; the three names are
-@file{@var{lib}.elc}, @file{@var{lib}.el}, and lastly just
-@file{@var{lib}}. If @file{@var{lib}.elc} exists, it is by convention
-the result of compiling @file{@var{lib}.el}; it is better to load the
-compiled file, since it will load and run faster.
-
- If @code{load-library} finds that @file{@var{lib}.el} is newer than
-@file{@var{lib}.elc} file, it issues a warning, because it's likely
-that somebody made changes to the @file{.el} file and forgot to
-recompile it. Nonetheless, it loads @file{@var{lib}.elc}. This is
-because people often leave unfinished edits the source file, and don't
-recompile it until they think it is ready to use.
+@vindex load-prefer-newer
+@cindex load path for Emacs Lisp
+ If an Emacs Lisp file is installed in the Emacs Lisp @dfn{load path}
+(defined below), you can load it by typing @kbd{M-x load-library},
+instead of using @kbd{M-x load-file}. The @kbd{M-x load-library}
+command prompts for a @dfn{library name} rather than a file name; it
+searches through each directory in the Emacs Lisp load path, trying to
+find a file matching that library name. If the library name is
+@samp{@var{foo}}, it tries looking for files named
+@file{@var{foo}.elc}, @file{@var{foo}.el}, and @file{@var{foo}}. The
+default behaviour is to load the first file found. This command
+prefers @file{.elc} files over @file{.el} files because compiled files
+load and run faster. If it finds that @file{@var{lib}.el} is newer
+than @file{@var{lib}.elc}, it issues a warning, in case someone made
+changes to the @file{.el} file and forgot to recompile it, but loads
+the @file{.elc} file anyway. (Due to this behavior, you can save
+unfinished edits to Emacs Lisp source files, and not recompile until
+your changes are ready for use.) If you set the option
+@code{load-prefer-newer} to a non-@code{nil} value, however, then
+rather than the procedure described above, Emacs loads whichever
+version of the file is newest.
+
+ Emacs Lisp programs usually load Emacs Lisp files using the
+@code{load} function. This is similar to @code{load-library}, but is
+lower-level and accepts additional arguments. @xref{How Programs Do
+Loading,,, elisp, the Emacs Lisp Reference Manual}.
@vindex load-path
- The variable @code{load-path} specifies the sequence of directories
-searched by @kbd{M-x load-library}. Its value should be a list of
-strings that are directory names; in addition, @code{nil} in this list
-stands for the current default directory. (Generally, it is not a
-good idea to put @code{nil} in the list; if you find yourself wishing
+ The Emacs Lisp load path is specified by the variable
+@code{load-path}. Its value should be a list of directory names
+(strings). These directories are searched, in the specified order, by
+the @kbd{M-x load-library} command, the lower-level @code{load}
+function, and other Emacs functions that find Emacs Lisp libraries. A
+list entry in @code{load-path} can also have the special value
+@code{nil}, which stands for the current default directory, but it is
+almost always a bad idea to use this. (If you find yourself wishing
that @code{nil} were in the list, most likely what you really want is
-to do @kbd{M-x load-file} this once.)
+to use @kbd{M-x load-file}.)
The default value of @code{load-path} is a list of directories where
the Lisp code for Emacs itself is stored. If you have libraries of
-your own, put them in a single directory and add that directory to
-@code{load-path}, by adding a line like this to your init file
-(@pxref{Init File}):
+your own in another directory, you can add that directory to the load
+path. Unlike most other variables described in this manual,
+@code{load-path} cannot be changed via the Customize interface
+(@pxref{Easy Customization}), but you can add a directory to it by
+putting a line like this in your init file (@pxref{Init File}):
@example
-(add-to-list 'load-path "/path/to/lisp/libraries")
+(add-to-list 'load-path "/path/to/my/lisp/library")
@end example
@cindex autoload
- Some commands are @dfn{autoloaded}: when you run them, Emacs will
-automatically load the associated library first. For instance, the
-@code{compile} and @code{compilation-mode} commands
-(@pxref{Compilation}) are autoloaded; if you call either command,
-Emacs automatically loads the @code{compile} library. In contrast,
-the command @code{recompile} is not autoloaded, so it is unavailable
-until you load the @code{compile} library.
+ Some commands are @dfn{autoloaded}; when you run them, Emacs
+automatically loads the associated library first. For instance, the
+@kbd{M-x compile} command (@pxref{Compilation}) is autoloaded; if you
+call it, Emacs automatically loads the @code{compile} library first.
+In contrast, the command @kbd{M-x recompile} is not autoloaded, so it
+is unavailable until you load the @code{compile} library.
+
+@vindex help-enable-auto-load
+ Automatic loading can also occur when you look up the documentation
+of an autoloaded command (@pxref{Name Help}), if the documentation
+refers to other functions and variables in its library (loading the
+library lets Emacs properly set up the hyperlinks in the @file{*Help*}
+buffer). To disable this feature, change the variable
+@code{help-enable-auto-load} to @code{nil}.
@vindex load-dangerous-libraries
@cindex Lisp files byte-compiled by XEmacs
@node Lisp Eval
@section Evaluating Emacs Lisp Expressions
-@cindex Emacs-Lisp mode
-@cindex mode, Emacs-Lisp
+@cindex Emacs Lisp mode
+@cindex mode, Emacs Lisp
+@cindex evaluation, Emacs Lisp
@findex emacs-lisp-mode
- Lisp programs intended to be run in Emacs should be edited in
-Emacs-Lisp mode; this happens automatically for file names ending in
-@file{.el}. By contrast, Lisp mode itself is used for editing Lisp
-programs intended for other Lisp systems. To switch to Emacs-Lisp mode
-explicitly, use the command @kbd{M-x emacs-lisp-mode}.
-
- For testing of Lisp programs to run in Emacs, it is often useful to
-evaluate part of the program as it is found in the Emacs buffer. For
-example, after changing the text of a Lisp function definition,
-evaluating the definition installs the change for future calls to the
-function. Evaluation of Lisp expressions is also useful in any kind of
-editing, for invoking noninteractive functions (functions that are
-not commands).
+ Emacs Lisp mode is the major mode for editing Emacs Lisp. Its mode
+command is @kbd{M-x emacs-lisp-mode}.
-@table @kbd
-@item M-:
-Read a single Lisp expression in the minibuffer, evaluate it, and print
-the value in the echo area (@code{eval-expression}).
-@item C-x C-e
-Evaluate the Lisp expression before point, and print the value in the
-echo area (@code{eval-last-sexp}).
-@item C-M-x
+ Emacs provides several commands for evaluating Emacs Lisp
+expressions. You can use these commands in Emacs Lisp mode, to test
+your Emacs Lisp code as it is being written. For example, after
+re-writing a function, you can evaluate the function definition to
+make it take effect for subsequent function calls. These commands are
+also available globally, and can be used outside Emacs Lisp mode.
+
+@table @asis
+@item @kbd{M-:}
+Read a single Emacs Lisp expression in the minibuffer, evaluate it,
+and print the value in the echo area (@code{eval-expression}).
+@item @kbd{C-x C-e}
+Evaluate the Emacs Lisp expression before point, and print the value
+in the echo area (@code{eval-last-sexp}).
+@item @kbd{C-M-x} @r{(in Emacs Lisp mode)}
+@itemx @kbd{M-x eval-defun}
Evaluate the defun containing or after point, and print the value in
the echo area (@code{eval-defun}).
-@item M-x eval-region
-Evaluate all the Lisp expressions in the region.
-@item M-x eval-buffer
-Evaluate all the Lisp expressions in the buffer.
+@item @kbd{M-x eval-region}
+Evaluate all the Emacs Lisp expressions in the region.
+@item @kbd{M-x eval-buffer}
+Evaluate all the Emacs Lisp expressions in the buffer.
@end table
@ifinfo
@kindex M-:
@end ifnotinfo
@findex eval-expression
- @kbd{M-:} (@code{eval-expression}) is the most basic command for evaluating
-a Lisp expression interactively. It reads the expression using the
-minibuffer, so you can execute any expression on a buffer regardless of
-what the buffer contains. When the expression is evaluated, the current
-buffer is once again the buffer that was current when @kbd{M-:} was
-typed.
-
-@kindex C-M-x @r{(Emacs-Lisp mode)}
-@findex eval-defun
- In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the command
-@code{eval-defun}, which parses the defun containing or following point
-as a Lisp expression and evaluates it. The value is printed in the echo
-area. This command is convenient for installing in the Lisp environment
-changes that you have just made in the text of a function definition.
-
- @kbd{C-M-x} treats @code{defvar} expressions specially. Normally,
-evaluating a @code{defvar} expression does nothing if the variable it
-defines already has a value. But @kbd{C-M-x} unconditionally resets the
-variable to the initial value specified in the @code{defvar} expression.
-@code{defcustom} expressions are treated similarly.
-This special feature is convenient for debugging Lisp programs.
-Typing @kbd{C-M-x} on a @code{defface} expression reinitializes
-the face according to the @code{defface} specification.
+ @kbd{M-:} (@code{eval-expression}) reads an expression using the
+minibuffer, and evaluates it. (Before evaluating the expression, the
+current buffer switches back to the buffer that was current when you
+typed @kbd{M-:}, not the minibuffer into which you typed the
+expression.)
@kindex C-x C-e
@findex eval-last-sexp
- The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Lisp
-expression preceding point in the buffer, and displays the value in the
-echo area. It is available in all major modes, not just Emacs-Lisp
-mode. It does not treat @code{defvar} specially.
-
- When the result of an evaluation is an integer, you can type
-@kbd{C-x C-e} a second time to display the value of the integer result
-in additional formats (octal, hexadecimal, and character).
-
- If @kbd{C-x C-e}, or @kbd{M-:} is given a numeric argument, it
-inserts the value into the current buffer at point, rather than
-displaying it in the echo area. The argument's value does not matter.
-@kbd{C-M-x} with a numeric argument instruments the function
-definition for Edebug (@pxref{Instrumenting, Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}).
+ The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the
+Emacs Lisp expression preceding point in the buffer, and displays the
+value in the echo area. When the result of an evaluation is an
+integer, it is displayed together with the value in other formats
+(octal, hexadecimal, and character).
+
+ If @kbd{M-:} or @kbd{C-x C-e} is given a prefix argument, it inserts
+the value into the current buffer at point, rather than displaying it
+in the echo area. If the prefix argument is zero, any integer output
+is inserted together with its value in other formats (octal,
+hexadecimal, and character). Such a prefix argument also prevents
+abbreviation of the output according to the variables
+@code{eval-expression-print-level} and @code{eval-expression-print-length}
+(see below).
+
+@kindex C-M-x @r{(Emacs Lisp mode)}
+@findex eval-defun
+ The @code{eval-defun} command is bound to @kbd{C-M-x} in Emacs Lisp
+mode. It evaluates the top-level Lisp expression containing or
+following point, and prints the value in the echo area. In this
+context, a top-level expression is referred to as a ``defun'', but it
+need not be an actual @code{defun} (function definition). In
+particular, this command treats @code{defvar} expressions specially.
+Normally, evaluating a @code{defvar} expression does nothing if the
+variable it defines already has a value. But this command
+unconditionally resets the variable to the initial value specified by
+the @code{defvar}; this is convenient for debugging Emacs Lisp
+programs. @code{defcustom} and @code{defface} expressions are treated
+similarly. Note that the other commands documented in this section do
+not have this special feature.
+
+ With a prefix argument, @kbd{C-M-x} instruments the function
+definition for Edebug, the Emacs Lisp Debugger. @xref{Instrumenting,
+Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}.
@findex eval-region
@findex eval-buffer
- The most general command for evaluating Lisp expressions from a buffer
-is @code{eval-region}. @kbd{M-x eval-region} parses the text of the
-region as one or more Lisp expressions, evaluating them one by one.
-@kbd{M-x eval-buffer} is similar but evaluates the entire
-buffer. This is a reasonable way to install the contents of a file of
-Lisp code that you are ready to test. Later, as you find bugs and
-change individual functions, use @kbd{C-M-x} on each function that you
-change. This keeps the Lisp world in step with the source file.
+ The command @kbd{M-x eval-region} parses the text of the region as
+one or more Lisp expressions, evaluating them one by one. @kbd{M-x
+eval-buffer} is similar but evaluates the entire buffer.
@vindex eval-expression-print-level
@vindex eval-expression-print-length
@vindex eval-expression-debug-on-error
- The two customizable variables @code{eval-expression-print-level} and
-@code{eval-expression-print-length} control the maximum depth and length
-of lists to print in the result of the evaluation commands before
-abbreviating them. @code{eval-expression-debug-on-error} controls
+ The options @code{eval-expression-print-level} and
+@code{eval-expression-print-length} control the maximum depth and
+length of lists to print in the result of the evaluation commands
+before abbreviating them. Supplying a zero prefix argument to
+@code{eval-expression} or @code{eval-last-sexp} causes lists to be
+printed in full. @code{eval-expression-debug-on-error} controls
whether evaluation errors invoke the debugger when these commands are
used; its default is @code{t}.
@node Lisp Interaction
@section Lisp Interaction Buffers
- When Emacs starts up, it contains a buffer named @samp{*scratch*},
-which is provided for evaluating Lisp expressions interactively inside
-Emacs. Its major mode is Lisp Interaction mode.
+@findex lisp-interaction-mode
+ When Emacs starts up, it contains a buffer named @file{*scratch*},
+which is provided for evaluating Emacs Lisp expressions interactively.
+Its major mode is Lisp Interaction mode. You can also enable Lisp
+Interaction mode by typing @kbd{M-x lisp-interaction-mode}.
@findex eval-print-last-sexp
@kindex C-j @r{(Lisp Interaction mode)}
- The simplest way to use the @samp{*scratch*} buffer is to insert
-Lisp expressions and type @kbd{C-j} (@code{eval-print-last-sexp})
-after each expression. This command reads the Lisp expression before
-point, evaluates it, and inserts the value in printed representation
-before point. The result is a complete typescript of the expressions
-you have evaluated and their values.
+ In the @file{*scratch*} buffer, and other Lisp Interaction mode
+buffers, @kbd{C-j} (@code{eval-print-last-sexp}) evaluates the Lisp
+expression before point, and inserts the value at point. Thus, as you
+type expressions into the buffer followed by @kbd{C-j} after each
+expression, the buffer records a transcript of the evaluated
+expressions and their values. All other commands in Lisp Interaction
+mode are the same as in Emacs Lisp mode.
@vindex initial-scratch-message
- At startup, the @samp{*scratch*} buffer contains a short message, in
+ At startup, the @file{*scratch*} buffer contains a short message, in
the form of a Lisp comment, that explains what it is for. This
message is controlled by the variable @code{initial-scratch-message},
-which should be either a string or @code{nil}. If you set it to the
-empty string, or @code{nil}, the initial message is suppressed.
-
-@findex lisp-interaction-mode
- All other commands in Lisp Interaction mode are the same as in Emacs
-Lisp mode. You can enable Lisp Interaction mode by typing @kbd{M-x
-lisp-interaction-mode}.
+which should be either a string, or @code{nil} (which means to
+suppress the message).
@findex ielm
- An alternative way of evaluating Emacs Lisp expressions interactively
-is to use Inferior Emacs-Lisp mode, which provides an interface rather
-like Shell mode (@pxref{Shell Mode}) for evaluating Emacs Lisp
-expressions. Type @kbd{M-x ielm} to create an @samp{*ielm*} buffer
-which uses this mode. For more information see that command's
-documentation.
+ An alternative way of evaluating Emacs Lisp expressions
+interactively is to use Inferior Emacs Lisp mode, which provides an
+interface rather like Shell mode (@pxref{Shell Mode}) for evaluating
+Emacs Lisp expressions. Type @kbd{M-x ielm} to create an
+@file{*ielm*} buffer which uses this mode. For more information, see
+that command's documentation.
@node External Lisp
@section Running an External Lisp
+@cindex Lisp mode
+@cindex mode, Lisp
+@cindex Common Lisp
- Emacs has facilities for running programs in other Lisp systems. You can
-run a Lisp process as an inferior of Emacs, and pass expressions to it to
-be evaluated. You can also pass changed function definitions directly from
-the Emacs buffers in which you edit the Lisp programs to the inferior Lisp
-process.
+ Lisp mode is the major mode for editing programs written in
+general-purpose Lisp dialects, such as Common Lisp. Its mode command
+is @kbd{M-x lisp-mode}. Emacs uses Lisp mode automatically for files
+whose names end in @file{.l}, @file{.lsp}, or @file{.lisp}.
@findex run-lisp
@vindex inferior-lisp-program
@kindex C-x C-z
- To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runs
-the program named @code{lisp}, the same program you would run by typing
-@code{lisp} as a shell command, with both input and output going through
-an Emacs buffer named @samp{*lisp*}. That is to say, any ``terminal
-output'' from Lisp will go into the buffer, advancing point, and any
-``terminal input'' for Lisp comes from text in the buffer. (You can
-change the name of the Lisp executable file by setting the variable
-@code{inferior-lisp-program}.)
-
- To give input to Lisp, go to the end of the buffer and type the input,
-terminated by @key{RET}. The @samp{*lisp*} buffer is in Inferior Lisp
-mode, which combines the special characteristics of Lisp mode with most
-of the features of Shell mode (@pxref{Shell Mode}). The definition of
-@key{RET} to send a line to a subprocess is one of the features of Shell
-mode.
-
-@findex lisp-mode
- For the source files of programs to run in external Lisps, use Lisp
-mode. You can switch to this mode with @kbd{M-x lisp-mode}, and it is
-used automatically for files whose names end in @file{.l},
-@file{.lsp}, or @file{.lisp}.
+ You can run an external Lisp session as a subprocess or
+@dfn{inferior process} of Emacs, and pass expressions to it to be
+evaluated. To begin an external Lisp session, type @kbd{M-x
+run-lisp}. This runs the program named @command{lisp}, and sets it up
+so that both input and output go through an Emacs buffer named
+@file{*inferior-lisp*}. To change the name of the Lisp program run by
+@kbd{M-x run-lisp}, change the variable @code{inferior-lisp-program}.
+
+ The major mode for the @file{*lisp*} buffer is Inferior Lisp mode,
+which combines the characteristics of Lisp mode and Shell mode
+(@pxref{Shell Mode}). To send input to the Lisp session, go to the
+end of the @file{*lisp*} buffer and type the input, followed by
+@key{RET}. Terminal output from the Lisp session is automatically
+inserted in the buffer.
@kindex C-M-x @r{(Lisp mode)}
@findex lisp-eval-defun
- When you edit a function in a Lisp program you are running, the easiest
-way to send the changed definition to the inferior Lisp process is the key
-@kbd{C-M-x}. In Lisp mode, this runs the function @code{lisp-eval-defun},
-which finds the defun around or following point and sends it as input to
-the Lisp process. (Emacs can send input to any inferior process regardless
-of what buffer is current.)
-
- Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing
-programs to be run in another Lisp system) and Emacs-Lisp mode (for
-editing Lisp programs to be run in Emacs; see @pxref{Lisp Eval}): in
-both modes it has the effect of installing the function definition
-that point is in, but the way of doing so is different according to
-where the relevant Lisp environment is found.
-
-
-@ignore
- arch-tag: 9c3c2f71-b332-4144-8500-3ff9945a50ed
-@end ignore
+ When you edit a Lisp program in Lisp mode, you can type @kbd{C-M-x}
+(@code{lisp-eval-defun}) to send an expression from the Lisp mode
+buffer to a Lisp session that you had started with @kbd{M-x run-lisp}.
+The expression sent is the top-level Lisp expression at or following
+point. The resulting value goes as usual into the
+@file{*inferior-lisp*} buffer. Note that the effect of @kbd{C-M-x} in
+Lisp mode is thus very similar to its effect in Emacs Lisp mode
+(@pxref{Lisp Eval}), except that the expression is sent to a different
+Lisp environment instead of being evaluated in Emacs.
+
+@findex scheme-mode
+@findex run-scheme
+@cindex Scheme mode
+@cindex mode, Scheme
+@kindex C-M-x @r{(Scheme mode)}
+ The facilities for editing Scheme code, and for sending expressions
+to a Scheme subprocess, are very similar. Scheme source files are
+edited in Scheme mode, which can be explicitly enabled with @kbd{M-x
+scheme-mode}. You can initiate a Scheme session by typing @kbd{M-x
+run-scheme} (the buffer for interacting with Scheme is named
+@file{*scheme*}), and send expressions to it by typing @kbd{C-M-x}.