@c This is part of the Emacs manual.
-@c Copyright (C) 1985,86,87,93,94,95,97,2000,2001 Free Software Foundation, Inc.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
+@c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Building, Maintaining, Programs, Top
@chapter 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 larger process of developing and maintaining programs.
+in the larger process of compiling and testing programs.
@menu
* Compilation:: Compiling programs in languages other
than Lisp (C, Pascal, etc.).
-* Grep Searching:: Running grep as if it were a compiler.
* Compilation Mode:: The mode for visiting compiler errors.
* Compilation Shell:: Customizing your shell properly
for use in the compilation buffer.
+* Grep Searching:: Searching with grep.
+* Flymake:: Finding syntax errors on the fly.
* Debuggers:: Running symbolic debuggers for non-Lisp programs.
* 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.
-* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
* 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.
@end menu
@item M-x recompile
Invoke a compiler with the same command as in the last invocation of
@kbd{M-x compile}.
-@item M-x grep
-Run @code{grep} asynchronously under Emacs, with matching lines
-listed in the buffer named @samp{*grep*}.
-@item M-x grep-find
-Run @code{grep} via @code{find}, with user-specified arguments, and
-collect output in the buffer named @samp{*grep*}.
@item M-x kill-compilation
-@itemx M-x kill-grep
-Kill the running compilation or @code{grep} subprocess.
+Kill the running compilation subprocess.
@end table
@findex compile
directory.
@vindex compile-command
- When the shell command line is read, the minibuffer appears
-containing a default command line, which is the command you used the
-last time you did @kbd{M-x compile}. If you type just @key{RET}, the
-same command line is used again. For the first @kbd{M-x compile}, the
-default is @samp{make -k}, which is correct most of the time for
-nontrivial programs. (@xref{Top,, Make, make, GNU Make Manual}.)
-The default compilation command comes from the variable
-@code{compile-command}; if the appropriate compilation command for a
-file is something other than @samp{make -k}, it can be useful for the
-file to specify a local value for @code{compile-command} (@pxref{File
-Variables}).
+ 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} 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.
+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
the buffer, it remains fixed while more compilation output is added at
the end of the buffer.
-@cindex compilation buffer, keeping current position at the end
+@cindex compilation buffer, keeping point at end
@vindex compilation-scroll-output
If you set the variable @code{compilation-scroll-output} to a
non-@code{nil} value, then the compilation buffer always scrolls to
follow output as it comes in.
-@findex kill-compilation
- When the compiler process terminates, for whatever reason, the mode
-line of the @samp{*compilation*} buffer changes to say @samp{signal}
-instead of @samp{run}. Starting a new compilation also kills any
-running compilation, as only one can exist 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 kill-compilation}.
-
@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}.
+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
+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
+ Starting a new compilation also kills any compilation
+running in @samp{*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
+kill-compilation}.
+
+ If you want to run two compilations at once, you should start the
+first one, then rename the @samp{*compilation*} buffer (perhaps using
+@code{rename-uniquely}; @pxref{Misc Buffer}), and start the other
+compilation. That 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
wait $pid # @r{Wait for subprocess}
@end example
-@node Grep Searching
-@section Searching with Grep under Emacs
-
-@findex grep
- Just as you can run a compiler from Emacs and then visit the lines
-where there were 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.''
+ 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:
- To do this, 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 regexp
-(usually in single-quotes to quote the shell's special characters)
-followed by file names, which may use wildcards. The output from
-@code{grep} goes in the @samp{*grep*} buffer. You can find the
-corresponding lines in the original files using @kbd{C-x `} and
-@key{RET}, as with compilation errors.
-
- If you specify a prefix argument for @kbd{M-x grep}, it figures out
-the tag (@pxref{Tags}) around point, and puts that into the default
-@code{grep} command.
+@example
+nohup @var{command}; sleep 1
+@end example
-@findex grep-find
- The command @kbd{M-x grep-find} 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 the @code{find-grep-dired} command,
-in @ref{Dired and Find}.
+@vindex compilation-environment
+ You can control the environment passed to the compilation command
+with the variable @code{compilation-environment}. Its value is a list
+of environment variable settings; each element should be a string of
+the form @code{"@var{envvarname}=@var{value}"}. These environment
+variable settings override the usual ones.
@node Compilation Mode
@section Compilation Mode
-@findex compile-goto-error
@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 look at the
-source line where the error happened.
-
- If you set the variable @code{compilation-scroll-output} to a
-non-@code{nil} value, then the compilation buffer always scrolls to
-follow output as it comes in.
+ 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}.
@table @kbd
-@item C-x `
-Visit the locus of the next compiler error message or @code{grep} match.
+@item M-g M-n
+@itemx M-g n
+@itemx C-x `
+Visit the locus of the next error message or match.
+@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.
+@item M-n
+Find and highlight the locus of the next error message, without
+selecting the source buffer.
+@item M-p
+Find and highlight the locus of the previous error message, without
+selecting the source buffer.
+@item M-@}
+Move point to the next error for a different file than the current
+one.
+@item M-@{
+Move point to the previous error for a different file than the current
+one.
+@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
-@kindex C-x `
-@findex next-error
+@findex compile-goto-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.
+@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.
-
- The first time @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 @kbd{C-x `}
-commands advance from there. When @kbd{C-x `} gets to the end of the
+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 momentarily
+highlights the relevant source line. You can change the behavior of
+this highlighting with 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.
-
- @kbd{C-u C-x `} starts scanning from the beginning of the compilation
-buffer. This is one way to process the same set of errors again.
+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.
+
+@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.
@vindex compilation-error-regexp-alist
@vindex grep-regexp-alist
that list. A similar variable @code{grep-regexp-alist} tells Emacs how
to parse output of a @code{grep} command.
+@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} and @kbd{M-p} to move to the next or
-previous error message. You can also use @kbd{M-@{} and @kbd{M-@}} to
-move up or down to an error message for a different source file.
+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.
+
+@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.
The features of Compilation mode are also available in a minor mode
called Compilation Minor mode. This lets you parse error messages in
@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
+ 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 file
-should set the prompt only if there already is a prompt. In csh, here
-is how to do it:
+@file{.bashrc}, @file{.profile}, @file{.cshrc}, @file{.shrc}, or
+various other things, depending on the 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:
@example
-if ($?prompt) set prompt = @dots{}
+if [ "$@{PS1+set@}" = set ]
+then PS1=@dots{}
+fi
@end example
@noindent
-And here's how to do it in bash:
+And here's how to do it in csh:
@example
-if [ "$@{PS1+set@}" = set ]
-then PS1=@dots{}
-fi
+if ($?prompt) set prompt = @dots{}
@end example
There may well be other things that your shell's init file
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. @xref{MS-DOS}.
+Emacs. @xref{MS-DOS,,,emacs-xtra,Specialized Emacs Features}.
+
+@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.''
+
+@table @kbd
+@item M-x grep
+@item M-x lgrep
+Run @code{grep} asynchronously under Emacs, with matching lines
+listed in the buffer named @samp{*grep*}.
+@item M-x grep-find
+@itemx M-x find-grep
+@itemx M-x rgrep
+Run @code{grep} via @code{find}, with user-specified arguments, and
+collect output in the buffer named @samp{*grep*}.
+@item M-x kill-grep
+Kill the running @code{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
+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 detects the tag
+(@pxref{Tags}) around point, and puts that into the default
+@code{grep} command.
+
+ The output from @code{grep} goes in the @samp{*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.
+
+ Some grep programs accept a @samp{--color} option to output special
+markers around matches for the purpose of highlighting. You can make
+use of this feature by setting @code{grep-highlight-matches} to
+@code{t}. When displaying a match in the source buffer, the exact
+match will be highlighted, instead of the entire source line.
+
+@findex grep-find
+@findex find-grep
+ 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
+the @code{find-grep-dired} command, in @ref{Dired and Find}.
+
+@findex lgrep
+@findex rgrep
+ The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep}
+(recursive grep) are more user-friendly versions of @code{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
+(rgrep only). Case sensitivitivy of the search is controlled by the
+current value of @code{case-fold-search}.
+
+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}.
+
+@node Flymake
+@section Finding Syntax Errors On The Fly
+@cindex checking syntax
+
+ 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
+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
+temporary copy of the buffer. It then parses the error and warning
+messages, and highlights the erroneous lines in the buffer. The
+syntax checking tool used depends on the language; for example, for
+C/C++ files this is usually the C compiler. Flymake can also use
+build tools such as @code{make} for checking complicated projects.
+
+ To activate Flymake mode, type @kbd{M-x flymake-mode}. You can move
+to the errors spotted 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}.
+
+ For more details about using Flymake, see @ref{Top, Flymake,
+Flymake, flymake, The Flymake Manual}.
@node Debuggers
@section Running Debuggers Under Emacs
@cindex SDB
@cindex XDB
@cindex Perldb
+@cindex bashdb
@cindex JDB
@cindex PDB
@c Do you believe in GUD?
The GUD (Grand Unified Debugger) library provides an interface to
-various symbolic debuggers from within Emacs. We recommend the debugger
-GDB, which is free software, but you can also run DBX, SDB or XDB if you
-have them. GUD can also serve as an interface to the Perl's debugging
-mode, the Python debugger PDB, and to JDB, the Java Debugger.
-@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference Manual},
-for information on debugging Emacs Lisp programs.
+various symbolic debuggers from within Emacs. We recommend the
+debugger GDB, which is free software, but GUD can also run DBX, SDB or
+XDB. GUD can also serve as an interface to Perl's debugging mode, the
+Python debugger PDB, the Bash debugger, and to JDB, the Java Debugger.
+@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference
+Manual}, for information on debugging Emacs Lisp programs.
@menu
* Starting GUD:: How to start a debugger subprocess.
* Debugger Operation:: Connection between the debugger and source buffers.
* Commands of GUD:: Key bindings for common commands.
* GUD Customization:: Defining your own commands for GUD.
-* GUD Tooltips:: Showing variable values by pointing with the mouse.
* GDB Graphical Interface:: An enhanced mode that uses GDB features to
implement a graphical debugging environment through
Emacs.
@table @kbd
@item M-x gdb @key{RET} @var{file} @key{RET}
@findex 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 gdba @key{RET} @var{file} @key{RET}
-Run GDB as a subprocess of Emacs, providing a graphical interface
-to GDB features through Emacs. @xref{GDB Graphical Interface}.
+Run GDB as a subprocess of Emacs. By default, this uses an IDE-like
+graphical interface; see @ref{GDB Graphical Interface}. Only GDB
+works with the graphical interface.
@item M-x dbx @key{RET} @var{file} @key{RET}
@findex dbx
-Similar, but run DBX instead of GDB.
+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
-Similar, but run XDB instead of GDB. Use the variable
+Similar, but run XDB. 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
-Similar, but run SDB instead of GDB.
+Similar, but run SDB.
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
requires a valid tags table to work}. If this happens, generate a valid
tags table in the working directory and try again.
+@item M-x bashdb @key{RET} @var{file} @key{RET}
+@findex bashdb
+Run the bash debugger to debug @var{file}, a shell script.
+
@item M-x perldb @key{RET} @var{file} @key{RET}
@findex perldb
Run the Perl interpreter in debug mode to debug @var{file}, a Perl program.
allowed. GUD assumes that the first argument not starting with a
@samp{-} is the executable file name.
- Emacs can only run one debugger process at a time.
-
@node Debugger Operation
@subsection Debugger Operation
@cindex fringes, and current execution line in GUD
- 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. The
-debugger displays the source files of the program by visiting them in
-Emacs buffers. An arrow (@samp{=>}) in one of these buffers indicates
-the current execution line.@footnote{Under a window system, the arrow
-appears in the left fringe of the Emacs window.} Moving point in this
-buffer does not move the arrow.
+ When you run a debugger with GUD using the textual interface, 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.
+
+ 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. The arrow is not part of the file's
-text; it appears only on the screen. 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.
-
- If you wish, you can control your debugger process entirely through the
-debugger buffer, which uses a variant of Shell mode. All the usual
-commands for your debugger are available, and you can use the Shell mode
-history commands to repeat them. @xref{Shell Mode}.
+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
+@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. In graphical mode,
+with a C program, you can also display the @code{#define} directive
+associated with an identifier when the program is not executing. 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.
+
+ 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.
@node Commands of GUD
@subsection Commands of GUD
The GUD interaction buffer uses a variant of Shell mode, so the
-commands of Shell mode are available (@pxref{Shell Mode}). 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.
+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
@end table
@kindex C-x C-a @r{(GUD)}
- Here are the other special commands provided by GUD. The keys
+ Here are the other special commands provided by GUD@. 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.
@kindex C-c C-t @r{(GUD)}
@itemx C-x C-a C-t
@findex gud-tbreak
-Set a temporary breakpoint on the current source line, if any.
-If you use this command in the GUD interaction buffer,
-it applies to the line where the program last stopped.
+Set a temporary breakpoint on the current source line, if any
+(@code{gud-tbreak}). If you use this command in the GUD interaction
+buffer, it applies to the line where the program last stopped.
@end table
The above commands are common to all supported debuggers. If you are
@itemx C-x C-a <
@findex gud-up
Select the next enclosing stack frame (@code{gud-up}). This is
-equivalent to the @samp{up} command.
+equivalent to the GDB command @samp{up}.
@item C-c >
@kindex C-c > @r{(GUD)}
@itemx C-x C-a >
@findex gud-down
Select the next inner stack frame (@code{gud-down}). This is
-equivalent to the @samp{down} command.
+equivalent to the GDB command @samp{down}.
@end table
If you are using GDB, these additional key bindings are available:
@kindex C-c C-u @r{(GUD)}
@itemx C-x C-a C-u
@findex gud-until
-Continue execution to the current line. The program will run until
-it hits a breakpoint, terminates, gets a signal that the debugger is
-checking for, or reaches the line on which the cursor currently sits
-(@code{gud-until}).
+Continue execution to the current line (@code{gud-until}). The
+program will run until it hits a breakpoint, terminates, gets a signal
+that the debugger is checking for, or reaches the line on which the
+cursor currently sits.
@item @key{TAB}
@kindex TAB @r{(GUD)}
@findex gud-gdb-complete-command
With GDB, complete a symbol name (@code{gud-gdb-complete-command}).
-This key is available only in the GUD interaction buffer, and requires
-GDB versions 4.13 and later.
+This key is available only in the GUD interaction buffer.
@item C-c C-f
@kindex C-c C-f @r{(GUD)}
@itemx C-x C-a C-f
@findex gud-finish
-Run the program until the selected stack frame returns (or until it
-stops for some other reason).
+Run the program until the selected stack frame returns or
+stops for some other reason (@code{gud-finish}).
@item C-x C-a C-j
@kindex C-x C-a C-j @r{(GUD)}
@findex gud-jump
-Only useful in a source buffer, (@code{gud-jump}) transfers the
+Only useful in a source buffer, @code{gud-jump} transfers the
program's execution point to the current line. In other words, the
next line that the program executes will be the one where you gave the
command. If the new execution line is in a different function from
@vindex perldb-mode-hook
@vindex pdb-mode-hook
@vindex jdb-mode-hook
+@vindex bashdb-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
+@code{pdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB;
+@code{bashdb-mode-hook}, for the Bash debugger. You can
use these hooks to define custom key bindings for the debugger
interaction buffer. @xref{Hooks}.
The name of the current source file. If the current buffer is the GUD
buffer, then the ``current source file'' is the file that the program
stopped in.
-@c This said, ``the name of the file the program counter was in at the last breakpoint.''
-@c But I suspect it is really the last stop file.
@item %l
The number of the current source line. If the current buffer is the GUD
stopped in.
@item %e
-The text of the C lvalue or function-call expression at or adjacent to point.
+In transient-mark-mode the text in the region, if it is active.
+Otherwise the text of the C lvalue or function-call expression at or
+adjacent to point.
@item %a
The text of the hexadecimal address at or adjacent to point.
If you don't use @samp{%p} in the command string, the command you define
ignores any numeric argument.
-@end table
-@node GUD Tooltips
-@subsection GUD Tooltips
+@item %d
+The name of the directory of the current source file.
-@cindex tooltips with GUD
-The Tooltip facility (@pxref{Tooltips}) provides support for GUD@. If
-GUD support is activated by customizing the @code{tooltip} group,
-variable values can be displayed in tooltips by pointing at them with
-the mouse in the GUD buffer or in source buffers with major modes in the
-customizable list @code{tooltip-gud-modes}.
+@item %c
+Fully qualified class name derived from the expression surrounding point
+(jdb only).
+@end table
@node GDB Graphical Interface
@subsection GDB Graphical Interface
+ By default, the command @code{gdb} starts GDB using a graphical
+interface, using Emacs windows for display program state information.
+In effect, this makes Emacs into an IDE (interactive development
+environment). With it, you do not need to use textual GDB commands;
+you can control the debugging session with the mouse.
+
+@c @findex gdb-mouse-set-clear-breakpoint
+@c @findex gdb-mouse-toggle-breakpoint
+ For example, 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{Mouse-3}
+on the bullet. If you drag the debugger 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-2} at some point in
+the fringe of this buffer and execution will advance to there.
+
+ 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.
+
+@vindex gud-gdb-command-name
@findex gdba
-The command @code{gdba} starts GDB using a graphical interface where
-you view and control the program's data using Emacs windows. You can
-still interact with GDB through the GUD buffer, but the point of this
-mode is that you can do it through menus and clicks, without needing
-to know GDB commands.
+ You can also run GDB in text command mode, like other debuggers. To
+do this, set @code{gud-gdb-command-name} to @code{"gdb --fullname"} or
+edit the startup command in the minibuffer to say that. You need to
+do use text command mode to run multiple debugging sessions within one
+Emacs session. If you have customized @code{gud-gdb-command-name} in
+that way, you can use @kbd{M-x gdba} to invoke GDB in graphical mode.
@menu
-* Breakpoints Buffer:: A breakpoint control panel.
-* Stack Buffer:: Select a frame from the call stack.
-* Watch Expressions:: Watch expressions and their values in the speedbar.
-* Other Buffers:: Input/output, locals, registers and assembler buffers.
-* Layout:: Control the number of displayed buffers.
+* GDB User Interface Layout:: Control the number of displayed buffers.
+* Breakpoints Buffer:: A breakpoint control panel.
+* Stack Buffer:: Select a frame from the call stack.
+* Watch Expressions:: Monitor variable values in the speedbar.
+* Other GDB User Interface Buffers:: Input/output, locals, registers,
+ assembler, threads and memory buffers.
@end menu
+@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.
+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.
+
+ If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb}
+displays the following frame layout:
+
+@example
++--------------------------------+--------------------------------+
+| | |
+| GUD buffer (I/O of GDB) | Locals buffer |
+| | |
+|--------------------------------+--------------------------------+
+| | |
+| Source buffer | I/O buffer for debugged pgm |
+| | |
+|--------------------------------+--------------------------------+
+| | |
+| Stack buffer | Breakpoints buffer |
+| | |
++--------------------------------+--------------------------------+
+@end example
+
+ However, if @code{gdb-use-separate-io-buffer} is @code{nil}, the I/O
+buffer does not appear and the 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}.
+
+ You may also specify additional GUD-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.
+
@node Breakpoints Buffer
@subsubsection Breakpoints Buffer
-The breakpoints buffer shows the existing breakpoints and watchpoints
-(@pxref{Breakpoints,,, gdb, The GNU debugger}). It has three special
-commands:
+ The breakpoints buffer shows the existing breakpoints and
+watchpoints (@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.
@table @kbd
-@item @key{SPC}
+@item @key{SPC}
@kindex SPC @r{(GDB breakpoints buffer)}
@findex gdb-toggle-breakpoint
-Enable/disable the breakpoint at the current line
-(@code{gdb-toggle-breakpoint}). On a graphical display, this changes
-the color of a bullet in the margin of the 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}.
-
-@item @kbd{d}
-@kindex d @r{(GDB breakpoints buffer)}
+Enable/disable the current breakpoint (@code{gdb-toggle-breakpoint}).
+On a graphical display, this changes the color of a bullet in the
+margin of the 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}.
+
+@item D
+@kindex D @r{(GDB breakpoints buffer)}
@findex gdb-delete-breakpoint
-Delete the breakpoint at the current line (@code{gdb-delete-breakpoint}).
+Delete the current breakpoint (@code{gdb-delete-breakpoint}).
@item @key{RET}
@kindex RET @r{(GDB breakpoints buffer)}
@findex gdb-goto-breakpoint
-Display the file in the source buffer at the breakpoint specified at
-the current line (@code{gdb-goto-breakpoint}). Alternatively, click @kbd{Mouse-2} on the breakpoint that you wish to visit.
+Visit the source line for the current breakpoint
+(@code{gdb-goto-breakpoint}).
+
+@item Mouse-2
+@kindex Mouse-2 @r{(GDB breakpoints buffer)}
+Visit the source line for the breakpoint you click on.
@end table
@node Stack Buffer
@subsubsection Stack Buffer
-The stack buffer displays a @dfn{call stack}, with one line for each
+ 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,,info stack, gdb, The GNU debugger}.
+program. @xref{Backtrace,, Backtraces, gdb, The GNU debugger}.
-Move point to any frame in the stack and type @key{RET} to make it
-become the current frame (@code{gdb-frames-select}) and display the
-associated source in the source buffer. Alternatively, click
-@kbd{Mouse-2} to make the selected frame become the current one. If the
-locals buffer is displayed then its contents update to display the
-variables that are local to the new frame.
+@findex gdb-frames-select
+ The selected frame number 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.
@node Watch Expressions
@subsubsection Watch Expressions
@cindex Watching expressions in GDB
-If you want to see how a variable changes each time your program stops
-then place the cursor over the variable name and click on the watch
-icon in the toolbar (@code{gud-watch}).
-
-Each watch expression is displayed in the speedbar. To expand or contract
-an array or structure, click @kbd{Mouse-2} on the tag to the left of the
-expression.
-
-@kindex RET @r{(GDB speedbar)}
+@findex gud-watch
+@kindex C-x C-a C-w @r{(GUD)}
+ If you want to see how a variable changes each time your program
+stops, move point into the variable name and click on the watch icon
+in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}. If you
+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.
+
+ To expand or contract a complex data type, click @kbd{Mouse-2}
+on the tag to the left of the expression.
+
+@kindex D @r{(GDB speedbar)}
@findex gdb-var-delete
-With the cursor over a root expression i.e not an array index or
-structure component, type @key{RET} or click @kbd{Mouse-2} to delete
-it from the speedbar (@code{gdb-var-delete}).
+ To delete a complex watch expression, move point to the root
+expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}).
-@node Other Buffers
+@kindex RET @r{(GDB speedbar)}
+@findex gdb-edit-value
+ To edit a variable with a simple data type, or a simple element of a
+complex data type, move point there in the speedbar and type @key{RET}
+(@code{gdb-edit-value}). Or you can click @kbd{Mouse-2} on a value to
+edit it. Either way, this reads the new value using the minibuffer.
+
+@vindex gdb-show-changed-values
+ If you set the variable @code{gdb-show-changed-values} to
+non-@code{nil} (the default value), Emacs uses
+@code{font-lock-warning-face} to highlight values that have recently
+changed and @code{shadow} face to make variables which have gone out of
+scope less noticeable. When a variable goes out of scope you can't
+edit its value.
+
+@vindex gdb-use-colon-colon-notation
+ If the variable @code{gdb-use-colon-colon-notation} is
+non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}}
+format. This allows the user to display watch expressions which share
+the same variable name. The default value is @code{nil}.
+
+@vindex gdb-speedbar-auto-raise
+To automatically raise the speedbar every time the display of watch
+expressions updates, set @code{gdb-speedbar-auto-raise} to
+non-@code{nil}. This can be useful if you are debugging with a full
+screen Emacs frame.
+
+@node Other GDB User Interface Buffers
@subsubsection Other Buffers
@table @asis
@item Input/Output Buffer
-The executable program that is being debugged takes its input and
-displays its output here. Some of the commands from shell mode are
-available here. @xref{Shell Mode}.
+@vindex gdb-use-separate-io-buffer
+If the variable @code{gdb-use-separate-io-buffer} is non-@code{nil},
+the executable program that is 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}. That 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 program you are debugging.
+@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,,, gdb, The GNU
-debugger}).
+current frame for simple data types (@pxref{Frame Info, Frame Info,
+Information on a frame, gdb, The GNU debugger}).
-Arrays and structures display their type only. You must display them
-separately to examine their values. @ref{Watch Expressions}.
+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
+(@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
-(@pxref{Registers,,, gdb, The GNU debugger}).
+(@pxref{Registers,,, gdb, The GNU debugger}). Press @key{RET} or
+click @kbd{Mouse-2} on a register if you want to change 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}).
@item Assembler Buffer
The assembler buffer displays the current frame as machine code. An
-overlay arrow points to the current instruction and you can set and
-remove breakpoints as with the source buffer. Breakpoints also
-appear in the margin.
-@end table
+arrow points to the current instruction, and you can set and remove
+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 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.
+
+@item Memory Buffer
+The memory buffer lets you examine sections of program memory
+(@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}).
+Click @kbd{Mouse-1} on the appropriate part of the header line to
+change the starting address or number of data items that the buffer
+displays. Click @kbd{Mouse-3} on the header line to select the
+display format or unit size for these data items.
-@node Layout
-@subsubsection Layout
-@cindex GDB User Interface layout
-You may choose to display the additional buffers described previously
-either in the same frame or a different one. Select GDB-windows or
-GDB-Frames from the menu-bar under the heading GUD. 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 e.g breakpoints.
-
-@findex gdb-many-windows
-@vindex gdb-many-windows
-If @code{gdb-many-windows} is @code{nil} (the default value), then GDB starts
-with just two windows: the GUD and the source buffer. If it is @code{t}, then
-six windows with the following layout will appear:
-
-@multitable @columnfractions .5 .5
-@item GUD buffer (I/O of GDB)
-@tab Locals buffer
-@item
-@tab
-@item Source buffer
-@tab Input/Output (of debuggee) buffer
-@item
-@tab
-@item Stack buffer
-@tab Breakpoints buffer
-@end multitable
-
-To toggle this layout, do @kbd{M-x gdb-many-windows}.
-
-@findex gdb-restore-windows
-If you change the window layout, for example, while editing and
-re-compiling your program, then you can restore it with
-@code{gdb-restore-windows}.
+@end table
@node Executing Lisp
@section Executing Lisp Expressions
conventionally end in @file{.el}. This ending tells Emacs to edit them in
Emacs-Lisp mode (@pxref{Executing Lisp}).
+@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}.
+
@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
@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-library}, or with @code{load}, a more primitive
-function that is similar but accepts some additional arguments.
+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
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.
+@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.
Because the argument to @code{load-library} is usually not in itself
a valid file name, file name completion is not available. Indeed, when
@vindex load-path
The sequence of directories searched by @kbd{M-x load-library} is
specified by the variable @code{load-path}, a list of strings that are
-directory names. The default value of the list contains the directory where
+directory names. The default value of the list contains the 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}. @code{nil} in this list stands for the current default
the library; this replaces the autoload definitions with the real ones
from the library.
-@cindex byte code
- Emacs Lisp code can be compiled into byte-code which loads faster,
-takes up less space when loaded, 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 consists of the library source file with @samp{c} appended.
-Thus, the compiled code for @file{foo.el} goes in @file{foo.elc}.
-That's why @code{load-library} searches for @samp{.elc} files first.
-
@vindex load-dangerous-libraries
@cindex Lisp files byte-compiled by XEmacs
By default, Emacs refuses to load compiled Lisp files which were
@code{t} if you want to try loading them.
@node Lisp Eval
-@section Evaluating Emacs-Lisp Expressions
+@section Evaluating Emacs Lisp Expressions
@cindex Emacs-Lisp mode
@cindex mode, Emacs-Lisp
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.
@kindex C-x C-e
@findex eval-last-sexp
echo area. It is available in all major modes, not just Emacs-Lisp
mode. It does not treat @code{defvar} specially.
- If @kbd{C-M-x}, @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.
+ 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}).
@findex eval-region
@findex eval-current-buffer
of lists to print in the result of the evaluation commands before
abbreviating them. @code{eval-expression-debug-on-error} controls
whether evaluation errors invoke the debugger when these commands are
-used.
+used; its default is @code{t}.
@node Lisp Interaction
@section Lisp Interaction Buffers
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.
+which uses this mode. For more information see that command's
+documentation.
@node External Lisp
@section Running an External Lisp
@findex lisp-mode
For the source files of programs to run in external Lisps, use Lisp
-mode. This mode can be selected with @kbd{M-x lisp-mode}, and is used
-automatically for files whose names end in @file{.l}, @file{.lsp}, or
-@file{.lisp}, as most Lisp systems usually expect.
+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}.
@kindex C-M-x @r{(Lisp mode)}
@findex lisp-eval-defun
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): 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.
-@xref{Executing Lisp}.
+ 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