0001: @c This is part of the Emacs manual.
0002: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software
0003: @c Foundation, Inc.
0004: @c See file emacs.texi for copying conditions.
0005: @node Building
0006: @chapter Compiling and Testing Programs
0007: @cindex building programs
0008: @cindex program building
0009: @cindex running Lisp functions
0010: 
0011:   The previous chapter discusses the Emacs commands that are useful
0012: for making changes in programs.  This chapter deals with commands that
0013: assist in the process of compiling and testing programs.
0014: 
0015: @menu
0016: * Compilation::         Compiling programs in languages other
0017:                           than Lisp (C, Pascal, etc.).
0018: * Compilation Mode::    The mode for visiting compiler errors.
0019: * Compilation Shell::   Customizing your shell properly
0020:                           for use in the compilation buffer.
0021: * Grep Searching::      Searching with grep.
0022: * Flymake::             Finding syntax errors on the fly.
0023: * Debuggers::           Running symbolic debuggers for non-Lisp programs.
0024: * Executing Lisp::      Various modes for editing Lisp programs,
0025:                           with different facilities for running
0026:                           the Lisp programs.
0027: * Libraries: Lisp Libraries.      How Lisp programs are loaded into Emacs.
0028: * Eval: Lisp Eval.      Executing a single Lisp expression in Emacs.
0029: * Interaction: Lisp Interaction.  Executing Lisp in an Emacs buffer.
0030: * External Lisp::       Communicating through Emacs with a separate Lisp.
0031: @end menu
0032: 
0033: @node Compilation
0034: @section Running Compilations under Emacs
0035: @cindex inferior process
0036: @cindex make
0037: @cindex compilation errors
0038: @cindex error log
0039: 
0040:   Emacs can run compilers for languages such as C and Fortran, feeding
0041: the compilation log into an Emacs buffer.  It can also parse the error
0042: messages and show you where the errors occurred.
0043: 
0044: @table @kbd
0045: @item M-x compile
0046: Run a compiler asynchronously under Emacs, with error messages going to
0047: the @file{*compilation*} buffer.
0048: 
0049: @item M-x recompile
0050: @itemx g@r{ (Compilation mode)}
0051: Invoke a compiler with the same command as in the last invocation of
0052: @kbd{M-x compile}.
0053: 
0054: @item M-x kill-compilation
0055: Kill the running compilation subprocess.
0056: @end table
0057: 
0058: @findex compile
0059:   To run @code{make} or another compilation command, type @kbd{M-x
0060: compile}.  This reads a shell command line using the minibuffer, and
0061: then executes the command by running a shell as a subprocess (or
0062: @dfn{inferior process}) of Emacs.  The output is inserted in a buffer
0063: named @file{*compilation*}.  The current buffer's default directory is
0064: used as the working directory for the execution of the command, so by
0065: default compilation takes place in that directory.
0066: 
0067: @vindex compile-command
0068:   The default compilation command is @samp{make -k}, which is usually
0069: correct for programs compiled using the @command{make} utility (the
0070: @samp{-k} flag tells @command{make} to continue compiling as much as
0071: possible after an error).  @xref{Top,, Make, make, GNU Make Manual}.
0072: If you have done @kbd{M-x compile} before, the command that you
0073: specified is automatically stored in the variable
0074: @code{compile-command}; this is used as the default the next time you
0075: type @kbd{M-x compile}.  A file can also specify a file-local value
0076: for @code{compile-command} (@pxref{File Variables}).
0077: 
0078:   Starting a compilation displays the @file{*compilation*} buffer in
0079: another window but does not select it.  While the compilation is
0080: running, the word @samp{run} is shown in the major mode indicator for
0081: the @file{*compilation*} buffer, and the word @samp{Compiling} appears
0082: in all mode lines.  You do not have to keep the @file{*compilation*}
0083: buffer visible while compilation is running; it continues in any case.
0084: When the compilation ends, for whatever reason, the mode line of the
0085: @file{*compilation*} buffer changes to say @samp{exit} (followed by
0086: the exit code: @samp{[0]} for a normal exit), or @samp{signal} (if a
0087: signal terminated the process).
0088: 
0089:   If you want to watch the compilation transcript as it appears,
0090: switch to the @file{*compilation*} buffer and move point to the end of
0091: the buffer.  When point is at the end, new compilation output is
0092: inserted above point, which remains at the end.  Otherwise, point
0093: remains fixed while compilation output is added at the end of the
0094: buffer.
0095: 
0096:   While compilation proceeds, the mode line shows the number of
0097: errors, warnings, and informational messages emitted by the compiler
0098: so far.
0099: 
0100: @cindex compilation buffer, keeping point at end
0101: @vindex compilation-scroll-output
0102:   If you change the variable @code{compilation-scroll-output} to a
0103: non-@code{nil} value, the @file{*compilation*} buffer scrolls
0104: automatically to follow the output.  If the value is
0105: @code{first-error}, scrolling stops when the first error appears,
0106: leaving point at that error.  For any other non-@code{nil} value,
0107: scrolling continues until there is no more output.
0108: 
0109: @findex recompile
0110:   To rerun the last compilation with the same command, type @kbd{M-x
0111: recompile}.  This reuses the compilation command from the last
0112: invocation of @kbd{M-x compile}.  It also reuses the
0113: @file{*compilation*} buffer and starts the compilation in its default
0114: directory, which is the directory in which the previous compilation
0115: was started.  In @file{*compilation*} buffers this command is bound to
0116: @kbd{g}.
0117: 
0118: @findex kill-compilation
0119: @vindex compilation-always-kill
0120:   Starting a new compilation also kills any compilation already
0121: running in @file{*compilation*}, as the buffer can only handle one
0122: compilation at any time.  However, @kbd{M-x compile} and @kbd{M-x
0123: recompile} ask for confirmation before actually killing a compilation
0124: that is running; to always automatically kill the compilation without
0125: asking, change the variable @code{compilation-always-kill} to
0126: @code{t}.  You can also kill a compilation process with the command
0127: @kbd{M-x kill-compilation}.
0128: 
0129:   To run two compilations at once, start the first one, then rename
0130: the @file{*compilation*} buffer (perhaps using @code{rename-uniquely};
0131: @pxref{Misc Buffer}), then switch buffers and start the other
0132: compilation.  This will create a new @file{*compilation*} buffer.
0133: 
0134: @vindex compilation-environment
0135:   You can control the environment passed to the compilation command
0136: with the variable @code{compilation-environment}.  Its value is a list
0137: of environment variable settings; each element should be a string of
0138: the form @code{"@var{envvarname}=@var{value}"}.  These environment
0139: variable settings override the usual ones.
0140: 
0141: @node Compilation Mode
0142: @section Compilation Mode
0143: 
0144: @cindex Compilation mode
0145: @cindex mode, Compilation
0146: @cindex locus
0147:   The @file{*compilation*} buffer uses a major mode called Compilation
0148: mode.  Compilation mode turns each error message in the buffer into a
0149: hyperlink; you can move point to it and type @key{RET}, or click on it
0150: with the mouse (@pxref{Mouse References}), to visit the @dfn{locus} of
0151: the error message in a separate window.  The locus is the specific
0152: position in a file where that error occurred.
0153: 
0154: @findex compile-goto-error
0155: @vindex compilation-auto-jump-to-first-error
0156:   If you change the variable
0157: @code{compilation-auto-jump-to-first-error} to a non-@code{nil} value,
0158: Emacs automatically visits the locus of the first error message that
0159: appears in the @file{*compilation*} buffer.
0160: 
0161:   Compilation mode provides the following additional commands.  These
0162: commands can also be used in @file{*grep*} buffers, where the
0163: hyperlinks are search matches rather than error messages (@pxref{Grep
0164: Searching}).
0165: 
0166: @table @kbd
0167: @item M-g M-n
0168: @itemx M-g n
0169: @itemx C-x `
0170: Visit the locus of the next error message or match (@code{next-error}).
0171: @item M-g M-p
0172: @itemx M-g p
0173: Visit the locus of the previous error message or match
0174: (@code{previous-error}).
0175: @item M-n
0176: Move point to the next error message or match, without visiting its
0177: locus (@code{compilation-next-error}).
0178: @item M-p
0179: Move point to the previous error message or match, without visiting
0180: its locus (@code{compilation-previous-error}).
0181: @item M-@}
0182: Move point to the next error message or match occurring in a different
0183: file (@code{compilation-next-file}).
0184: @item M-@{
0185: Move point to the previous error message or match occurring in a
0186: different file (@code{compilation-previous-file}).
0187: @item C-c C-f
0188: Toggle Next Error Follow minor mode, which makes cursor motion in the
0189: compilation buffer produce automatic source display.
0190: @item g
0191: Re-run the last command whose output is shown in the
0192: @file{*compilation*} buffer.
0193: @item M-x next-error-select-buffer
0194: Select a buffer to be used by next invocation of @code{next-error} and
0195: @code{previous-error}.
0196: @end table
0197: 
0198: @kindex M-g M-n
0199: @kindex M-g n
0200: @kindex C-x `
0201: @findex next-error
0202: @vindex next-error-highlight
0203:   To visit errors sequentially, type @w{@kbd{C-x `}}
0204: (@code{next-error}), or equivalently @kbd{M-g M-n} or @kbd{M-g n}.
0205: This command can be invoked from any buffer, not just a Compilation
0206: mode buffer.  The first time you invoke it after a compilation, it
0207: visits the locus of the first error message.  Each subsequent
0208: @w{@kbd{M-g M-n}} visits the next error, in a similar fashion.  If you
0209: visit a specific error with @key{RET} or a mouse click in the
0210: @file{*compilation*} buffer, subsequent @w{@kbd{M-g M-n}} commands
0211: advance from there.  When @w{@kbd{M-g M-n}} finds no more error messages
0212: to visit, it signals an error.  @w{@kbd{C-u M-g M-n}} starts again from
0213: the beginning of the compilation buffer, and visits the first locus.
0214: 
0215:   @kbd{M-g M-p} or @kbd{M-g p} (@code{previous-error}) iterates
0216: through errors in the opposite direction.
0217: 
0218: @vindex next-error-find-buffer-function
0219: @findex next-error-select-buffer
0220:   The @code{next-error} and @code{previous-error} commands don't just
0221: act on the errors or matches listed in @file{*compilation*} and
0222: @file{*grep*} buffers; they also know how to iterate through error or
0223: match lists produced by other commands, such as @kbd{M-x occur}
0224: (@pxref{Other Repeating Search}).  If the current buffer contains
0225: error messages or matches, these commands will iterate through them;
0226: otherwise, Emacs looks for a buffer containing error messages or
0227: matches amongst the windows of the selected frame (if the variable
0228: @code{next-error-find-buffer-function} is customized to the value
0229: @code{next-error-buffer-on-selected-frame}), then for a buffer used
0230: previously by @code{next-error} or @code{previous-error}, and finally
0231: all other buffers.  Any buffer these commands iterate through that is
0232: not currently displayed in a window will be displayed.  You can use
0233: the @command{next-error-select-buffer} command to switch to
0234: a different buffer to be used by the subsequent invocation of
0235: @code{next-error}.
0236: 
0237: @vindex compilation-skip-threshold
0238:   By default, the @code{next-error} and @code{previous-error} commands
0239: skip less important messages.  The variable
0240: @code{compilation-skip-threshold} controls this.  The default value,
0241: 1, means to skip anything less important than a warning.  A value of 2
0242: means to skip anything less important than an error, while 0 means not
0243: to skip any messages.
0244: 
0245:   When Emacs visits the locus of an error message, it momentarily
0246: highlights the relevant source line.  The duration of this highlight
0247: is determined by the variable @code{next-error-highlight}.
0248: 
0249: @vindex compilation-context-lines
0250:   If the @file{*compilation*} buffer is shown in a window with a left
0251: fringe (@pxref{Fringes}), the locus-visiting commands put an arrow in
0252: the fringe, pointing to the current error message.  If the window has
0253: no left fringe, such as on a text terminal, these commands scroll the
0254: window so that the current message is at the top of the window.  If
0255: you change the variable @code{compilation-context-lines} to an integer
0256: value @var{n}, these commands scroll the window so that the current
0257: error message is @var{n} lines from the top, whether or not there is a
0258: fringe; the default value, @code{nil}, gives the behavior described
0259: above.
0260: 
0261: @vindex compilation-error-regexp-alist
0262: @vindex grep-regexp-alist
0263:   To parse messages from the compiler, Compilation mode uses the
0264: variable @code{compilation-error-regexp-alist} which lists various
0265: error message formats and tells Emacs how to extract the locus from
0266: each.  A similar variable, @code{grep-regexp-alist}, tells Emacs how
0267: to parse output from a @code{grep} command (@pxref{Grep Searching}).
0268: 
0269: @findex compilation-next-error
0270: @findex compilation-previous-error
0271: @findex compilation-next-file
0272: @findex compilation-previous-file
0273:   Compilation mode also defines the keys @key{SPC} and @key{DEL} to
0274: scroll by screenfuls; @kbd{M-n} (@code{compilation-next-error}) and
0275: @kbd{M-p} (@code{compilation-previous-error}) to move to the next or
0276: previous error message; and @kbd{M-@{} (@code{compilation-next-file})
0277: and @kbd{M-@}} (@code{compilation-previous-file}) to move to the next
0278: or previous error message for a different source file.
0279: 
0280: @cindex Next Error Follow mode
0281: @findex next-error-follow-minor-mode
0282:   You can type @kbd{C-c C-f} to toggle Next Error Follow mode.  In
0283: this minor mode, ordinary cursor motion in the compilation buffer
0284: automatically updates the source buffer, i.e., moving the cursor over
0285: an error message causes the locus of that error to be displayed.
0286: 
0287:   The features of Compilation mode are also available in a minor mode
0288: called Compilation Minor mode.  This lets you parse error messages in
0289: any buffer, not just a normal compilation output buffer.  Type
0290: @kbd{M-x compilation-minor-mode} to enable the minor mode.  For
0291: instance, in an Rlogin buffer (@pxref{Remote Host}), Compilation minor
0292: mode automatically accesses remote source files by FTP (@pxref{File
0293: Names}).
0294: 
0295: @node Compilation Shell
0296: @section Subshells for Compilation
0297: 
0298:   This section includes various techniques and advice for using a
0299: shell and its features in compilation buffers.  This material is
0300: specific to local compilations, and will most probably not work in (or
0301: be irrelevant to) compilation buffers whose default directory is on
0302: remote hosts.
0303: 
0304:   The @kbd{M-x compile} command uses a shell to run the compilation
0305: command, but specifies the option for a noninteractive shell.  This
0306: means, in particular, that the shell should start with no prompt.  If
0307: you find your usual shell prompt making an unsightly appearance in the
0308: @file{*compilation*} buffer, it means you have made a mistake in your
0309: shell's init file by setting the prompt unconditionally.  (This init
0310: file may be named @file{.bashrc}, @file{.profile}, @file{.cshrc},
0311: @file{.shrc}, etc., depending on what shell you use.)  The shell init
0312: file should set the prompt only if there already is a prompt.  Here's
0313: how to do it in bash:
0314: 
0315: @example
0316: if [ "$@{PS1+set@}" = set ]
0317: then PS1=@dots{}
0318: fi
0319: @end example
0320: 
0321: @noindent
0322: And here's how to do it in csh:
0323: 
0324: @example
0325: if ($?prompt) set prompt = @dots{}
0326: @end example
0327: 
0328: @vindex TERM@r{, environment variable, in compilation mode}
0329:   If you want to customize the value of the @env{TERM} environment
0330: variable passed to the compilation subshell, customize the variable
0331: @code{comint-terminfo-terminal} (@pxref{Shell Options}).
0332: 
0333:   Emacs does not expect a compiler process to launch asynchronous
0334: subprocesses; if it does, and they keep running after the main
0335: compiler process has terminated, Emacs may kill them or their output
0336: may not arrive in Emacs.  To avoid this problem, make the main
0337: compilation process wait for its subprocesses to finish.  In a shell
0338: script, you can do this using @samp{$!} and @samp{wait}, like this:
0339: 
0340: @example
0341: (sleep 10; echo 2nd)& pid=$!  # @r{Record pid of subprocess}
0342: echo first message
0343: wait $pid                     # @r{Wait for subprocess}
0344: @end example
0345: 
0346: @noindent
0347: If the background process does not output to the compilation buffer,
0348: so you only need to prevent it from being killed when the main
0349: compilation process terminates, this is sufficient:
0350: 
0351: @example
0352: nohup @var{command}; sleep 1
0353: @end example
0354: 
0355: @ifnottex
0356:   On MS-DOS, asynchronous subprocesses are
0357: not supported, so @kbd{M-x compile} runs the compilation command
0358: synchronously (i.e., you must wait until the command finishes before
0359: you can do anything else in Emacs).  @xref{MS-DOS}.
0360: @end ifnottex
0361: 
0362: @node Grep Searching
0363: @section Searching with Grep under Emacs
0364: 
0365:   Just as you can run a compiler from Emacs and then visit the lines
0366: with compilation errors, you can also run @command{grep} and then
0367: visit the lines on which matches were found.  This works by treating
0368: the matches reported by @command{grep} as if they were errors.
0369: The output buffer uses Grep mode, which is a variant of Compilation
0370: mode (@pxref{Compilation Mode}).
0371: 
0372: @table @kbd
0373: @item M-x grep
0374: @itemx M-x lgrep
0375: Run @command{grep} asynchronously under Emacs, listing matching lines in
0376: the buffer named @file{*grep*}.
0377: @item M-x grep-find
0378: @itemx M-x find-grep
0379: @itemx M-x rgrep
0380: Run @command{grep} via @code{find}, and collect output in the
0381: @file{*grep*} buffer.
0382: @item M-x zrgrep
0383: Run @code{zgrep} and collect output in the @file{*grep*} buffer.
0384: @item M-x kill-grep
0385: Kill the running @command{grep} subprocess.
0386: @end table
0387: 
0388: @findex grep
0389:   To run @command{grep}, type @kbd{M-x grep}, then enter a command line
0390: that specifies how to run @command{grep}.  Use the same arguments you
0391: would give @command{grep} when running it normally: a @command{grep}-style
0392: regexp (usually in single-quotes to quote the shell's special
0393: characters) followed by file names, which may use wildcards.  If you
0394: specify a prefix argument for @kbd{M-x grep}, it finds the identifier
0395: (@pxref{Xref}) in the buffer around point, and puts that into the
0396: default @command{grep} command.
0397: 
0398:   Your command need not simply run @command{grep}; you can use any shell
0399: command that produces output in the same format.  For instance, you
0400: can chain @command{grep} commands, like this:
0401: 
0402: @example
0403: grep -nH -e foo *.el | grep bar | grep toto
0404: @end example
0405: 
0406:   The output from @command{grep} goes in the @file{*grep*} buffer.  You
0407: can find the corresponding lines in the original files using @w{@kbd{M-g
0408: M-n}}, @key{RET}, and so forth, just like compilation errors.
0409: @xref{Compilation Mode}, for detailed description of commands and key
0410: bindings available in the @file{*grep*} buffer.
0411: 
0412:   Some grep programs accept a @samp{--color} option to output special
0413: markers around matches for the purpose of highlighting.  You can make
0414: use of this feature by setting @code{grep-highlight-matches} to
0415: @code{t}.  When displaying a match in the source buffer, the exact
0416: match will be highlighted, instead of the entire source line.
0417: 
0418:   As with compilation commands (@pxref{Compilation}), while the grep
0419: command runs, the mode line shows the running number of matches found
0420: and highlighted so far.
0421: 
0422:   The @command{grep} commands will offer to save buffers before
0423: running.  This is controlled by the @code{grep-save-buffers} variable.
0424: The possible values are either @code{nil} (don't save), @code{ask}
0425: (ask before saving), or a function which will be used as a predicate
0426: (and is called with the file name as the parameter and should return
0427: non-@code{nil} if the buffer is to be saved).  Any other
0428: non-@code{nil} value means that all buffers should be saved without
0429: asking.  The default is @code{ask}.
0430: 
0431: @findex grep-find
0432: @findex find-grep
0433:   The command @kbd{M-x grep-find} (also available as @kbd{M-x
0434: find-grep}) is similar to @kbd{M-x grep}, but it supplies a different
0435: initial default for the command---one that runs both @code{find} and
0436: @command{grep}, so as to search every file in a directory tree.  See also
0437: the @code{find-grep-dired} command, in @ref{Dired and Find}.
0438: 
0439: @findex lgrep
0440: @findex rgrep
0441: @findex zrgrep
0442:   The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep}
0443: (recursive grep) are more user-friendly versions of @command{grep} and
0444: @code{grep-find}, which prompt separately for the regular expression
0445: to match, the files to search, and the base directory for the search.
0446: Case sensitivity of the search is controlled by the current value of
0447: @code{case-fold-search}.  The command @kbd{M-x zrgrep} is similar to
0448: @kbd{M-x rgrep}, but it calls @command{zgrep} instead of
0449: @command{grep} to search the contents of gzipped files.
0450: 
0451:   These commands build the shell commands based on the variables
0452: @code{grep-template} (for @code{lgrep}) and @code{grep-find-template}
0453: (for @code{rgrep}).  The files to search can use aliases defined in
0454: the variable @code{grep-files-aliases}.
0455: 
0456: @vindex grep-find-ignored-directories
0457:   Directories listed in the variable
0458: @code{grep-find-ignored-directories} are automatically skipped by
0459: @kbd{M-x rgrep}.  The default value includes the data directories used
0460: by various version control systems.
0461: 
0462: @vindex grep-find-abbreviate
0463: @findex grep-find-toggle-abbreviation
0464:   By default, the shell commands constructed for @code{lgrep},
0465: @code{rgrep}, and @code{zgrep} are abbreviated for display by
0466: concealing the part that contains a long list of files and directories
0467: to ignore.  You can reveal the concealed part by clicking on the
0468: button with ellipsis, which represents them.  You can also
0469: interactively toggle viewing the concealed part by typing @kbd{M-x
0470: grep-find-toggle-abbreviation}.  To disable this abbreviation of the
0471: shell commands, customize the option @code{grep-find-abbreviate} to a
0472: @code{nil} value.
0473: 
0474: @node Flymake
0475: @section Finding Syntax Errors On The Fly
0476: @cindex checking syntax
0477: 
0478:   Flymake mode is a minor mode that performs on-the-fly syntax
0479: checking for many programming and markup languages, including C, C++,
0480: Perl, HTML, and @TeX{}/@LaTeX{}.  It is somewhat analogous to Flyspell
0481: mode, which performs spell checking for ordinary human languages in a
0482: similar fashion (@pxref{Spelling}).  As you edit a file, Flymake mode
0483: runs an appropriate syntax checking tool in the background, using a
0484: temporary copy of the buffer.  It then parses the error and warning
0485: messages, and highlights the erroneous lines in the buffer.  The
0486: syntax checking tool used depends on the language; for example, for
0487: C/C++ files this is usually the C compiler.  Flymake can also use
0488: build tools such as @code{make} for checking complicated projects.
0489: 
0490:   To enable Flymake mode, type @kbd{M-x flymake-mode}.  You can jump
0491: to the errors that it finds by using @kbd{M-x flymake-goto-next-error}
0492: and @kbd{M-x flymake-goto-prev-error}.  To display any error messages
0493: associated with the current line, type @kbd{M-x
0494: flymake-display-err-menu-for-current-line}.
0495: 
0496:   For more details about using Flymake,
0497: @ifnottex
0498: see @ref{Top, Flymake, Flymake, flymake, The Flymake Manual}.
0499: @end ifnottex
0500: @iftex
0501: see the Flymake Info manual, which is distributed with Emacs.
0502: @end iftex
0503: 
0504: @node Debuggers
0505: @section Running Debuggers Under Emacs
0506: @cindex debuggers
0507: @cindex GUD library
0508: @cindex GDB
0509: @cindex DBX
0510: @cindex SDB
0511: @cindex XDB
0512: @cindex Perldb
0513: @cindex JDB
0514: @cindex PDB
0515: 
0516: The GUD (Grand Unified Debugger) library provides an Emacs interface
0517: to a wide variety of symbolic debuggers.  It can run the GNU Debugger
0518: (GDB), as well as DBX, SDB, XDB, Guile REPL debug commands, Perl's
0519: debugging mode, the Python debugger PDB, and the Java Debugger JDB.
0520: 
0521:   Emacs provides a special interface to GDB, which uses extra Emacs
0522: windows to display the state of the debugged program.  @xref{GDB
0523: Graphical Interface}.
0524: 
0525:   Emacs also has a built-in debugger for Emacs Lisp programs.
0526: @xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference
0527: Manual}.
0528: 
0529: @menu
0530: * Starting GUD::        How to start a debugger subprocess.
0531: * Debugger Operation::  Connection between the debugger and source buffers.
0532: * Commands of GUD::     Key bindings for common commands.
0533: * GUD Customization::   Defining your own commands for GUD.
0534: * GDB Graphical Interface::  An enhanced mode that uses GDB features to
0535:                         implement a graphical debugging environment.
0536: @end menu
0537: 
0538: @node Starting GUD
0539: @subsection Starting GUD
0540: 
0541:   There are several commands for starting a debugger subprocess, each
0542: corresponding to a particular debugger program.
0543: 
0544: @table @kbd
0545: @item M-x gdb
0546: @findex gdb
0547: Run GDB as a subprocess, and interact with it via an IDE-like Emacs
0548: interface.  @xref{GDB Graphical Interface}, for more information about
0549: this command.
0550: 
0551: @item M-x gud-gdb
0552: @findex gud-gdb
0553: Run GDB, using a GUD interaction buffer for input and output to the
0554: GDB subprocess (@pxref{Debugger Operation}).  If such a buffer already
0555: exists, switch to it; otherwise, create the buffer and switch to it.
0556: 
0557: The other commands in this list do the same, for other debugger
0558: programs.
0559: 
0560: @item M-x perldb
0561: @findex perldb
0562: Run the Perl interpreter in debug mode.
0563: 
0564: @item M-x jdb
0565: @findex jdb
0566: Run the Java debugger.
0567: 
0568: @item M-x pdb
0569: @findex pdb
0570: Run the Python debugger.
0571: 
0572: @item M-x guiler
0573: @findex guiler
0574: Run Guile REPL for debugging Guile Scheme programs.
0575: 
0576: @item M-x dbx
0577: @findex dbx
0578: Run the DBX debugger.
0579: 
0580: @item M-x xdb
0581: @findex xdb
0582: @vindex gud-xdb-directories
0583: Run the XDB debugger.
0584: 
0585: @item M-x sdb
0586: @findex sdb
0587: Run the SDB debugger.
0588: @end table
0589: 
0590:   Each of these commands reads a command line to invoke the debugger,
0591: using the minibuffer.  The minibuffer's initial contents contain the
0592: standard executable name and options for the debugger, and sometimes
0593: also a guess for the name of the executable file you want to debug.
0594: Shell wildcards and variables are not allowed in this command line.
0595: Emacs assumes that the first command argument which does not start
0596: with a @samp{-} is the executable file name.
0597: 
0598: @cindex remote host, debugging on
0599:   Tramp provides a facility for remote debugging, whereby both the
0600: debugger and the program being debugged are on the same remote host.
0601: @xref{Running a debugger on a remote host,,, tramp, The Tramp Manual},
0602: for details.  This is separate from GDB's remote debugging feature,
0603: where the program and the debugger run on different machines
0604: (@pxref{Remote Debugging,, Debugging Remote Programs, gdb, The GNU
0605: debugger}).
0606: 
0607: @node Debugger Operation
0608: @subsection Debugger Operation
0609: @cindex GUD interaction buffer
0610: 
0611:   The @dfn{GUD interaction buffer} is an Emacs buffer which is used to
0612: send text commands to a debugger subprocess, and record its output.
0613: This is the basic interface for interacting with a debugger, used by
0614: @kbd{M-x gud-gdb} and other commands listed in
0615: @iftex
0616: the preceding section.
0617: @end iftex
0618: @ifnottex
0619: @ref{Starting GUD}.
0620: @end ifnottex
0621: The @kbd{M-x gdb} command extends this interface with additional
0622: specialized buffers for controlling breakpoints, stack frames, and
0623: other aspects of the debugger state (@pxref{GDB Graphical Interface}).
0624: 
0625:   The GUD interaction buffer uses a variant of Shell mode, so the
0626: Emacs commands defined by Shell mode are available (@pxref{Shell
0627: Mode}).  Completion is available for most debugger commands
0628: (@pxref{Completion}), and you can use the usual Shell mode history
0629: commands to repeat them.
0630: @iftex
0631: See the next section
0632: @end iftex
0633: @ifnottex
0634: @xref{Commands of GUD},
0635: @end ifnottex
0636: for special commands that can be used in the GUD interaction buffer.
0637: 
0638:   As you debug a program, Emacs displays the relevant source files by
0639: visiting them in Emacs buffers, with an arrow in the left fringe
0640: indicating the current execution line.  (On a text terminal, the arrow
0641: appears as @samp{=>}, overlaid on the first two text columns.)  Moving
0642: point in such a buffer does not move the arrow.  You are free to edit
0643: these source files, but note that inserting or deleting lines will
0644: throw off the arrow's positioning, as Emacs has no way to figure out
0645: which edited source line corresponds to the line reported by the
0646: debugger subprocess.  To update this information, you typically have
0647: to recompile and restart the program.
0648: 
0649: @cindex GUD Tooltip mode
0650: @cindex mode, GUD Tooltip
0651: @findex gud-tooltip-mode
0652: @vindex gud-tooltip-echo-area
0653:   GUD Tooltip mode is a global minor mode that adds tooltip support to
0654: GUD@.  To toggle this mode, type @kbd{M-x gud-tooltip-mode}.  It is
0655: disabled by default.  If enabled, you can move the mouse pointer over a
0656: variable, a function, or a macro (collectively called
0657: @dfn{identifiers}) to show their values in tooltips
0658: (@pxref{Tooltips}).  If just placing the mouse pointer over an
0659: expression doesn't show the value of the expression you had in mind,
0660: you can tell Emacs more explicitly what expression to evaluate by
0661: dragging the mouse over the expression, then leaving the mouse inside
0662: the marked area.  The GUD Tooltip mode takes effect in the GUD
0663: interaction buffer, and in all source buffers with major modes listed
0664: in the variable @code{gud-tooltip-modes}.  If the variable
0665: @code{gud-tooltip-echo-area} is non-@code{nil}, or if you turned off
0666: the tooltip mode, values are shown in the echo area instead of a
0667: tooltip.
0668: 
0669:   When using GUD Tooltip mode with @kbd{M-x gud-gdb}, displaying an
0670: expression's value in GDB can sometimes expand a macro, potentially
0671: causing side effects in the debugged program.  For that reason, using
0672: tooltips in @code{gud-gdb} is disabled.  If you use the @kbd{M-x gdb}
0673: interface, this problem does not occur, as there is special code to
0674: avoid side-effects; furthermore, you can display macro definitions
0675: associated with an identifier when the program is not executing.
0676: 
0677: @node Commands of GUD
0678: @subsection Commands of GUD
0679: 
0680:   GUD provides commands for setting and clearing breakpoints,
0681: selecting stack frames, and stepping through the program.
0682: 
0683: @table @kbd
0684: @item C-x C-a C-b
0685: @kindex C-x C-a C-b
0686: Set a breakpoint on the source line that point is on.
0687: @end table
0688: 
0689:   @kbd{C-x C-a C-b} (@code{gud-break}), when called in a source
0690: buffer, sets a debugger breakpoint on the current source line.  This
0691: command is available only after starting GUD@.  If you call it in a
0692: buffer that is not associated with any debugger subprocess, it signals
0693: an error.
0694: 
0695: @kindex C-x C-a @r{(GUD)}
0696:   The following commands are available both in the GUD interaction
0697: buffer and globally, but with different key bindings.  The keys
0698: starting with @kbd{C-c} are available only in the GUD interaction
0699: buffer, while those starting with @kbd{C-x C-a} are available
0700: globally.  Some of these commands are also available via the tool bar;
0701: some are not supported by certain debuggers.
0702: 
0703: @table @kbd
0704: @item C-c C-l
0705: @kindex C-c C-l @r{(GUD)}
0706: @itemx C-x C-a C-l
0707: @findex gud-refresh
0708: Display, in another window, the last source line referred to in the
0709: GUD interaction buffer (@code{gud-refresh}).
0710: 
0711: @item C-c C-s
0712: @kindex C-c C-s @r{(GUD)}
0713: @itemx C-x C-a C-s
0714: @findex gud-step
0715: Execute the next single line of code (@code{gud-step}).  If the line
0716: contains a function call, execution stops after entering the called
0717: function.
0718: 
0719: @item C-c C-n
0720: @kindex C-c C-n @r{(GUD)}
0721: @itemx C-x C-a C-n
0722: @findex gud-next
0723: Execute the next single line of code, stepping across function calls
0724: without stopping inside the functions (@code{gud-next}).
0725: 
0726: @item C-c C-i
0727: @kindex C-c C-i @r{(GUD)}
0728: @itemx C-x C-a C-i
0729: @findex gud-stepi
0730: Execute a single machine instruction (@code{gud-stepi}).
0731: 
0732: @item C-c C-p
0733: @kindex C-c C-p @r{(GUD)}
0734: @itemx C-x C-a C-p
0735: @findex gud-print
0736: Evaluate the expression at point (@code{gud-print}).  If Emacs
0737: does not print the exact expression that you want, mark it as a region
0738: first.
0739: 
0740: @need 3000
0741: @item C-c C-r
0742: @kindex C-c C-r @r{(GUD)}
0743: @itemx C-x C-a C-r
0744: @findex gud-cont
0745: Continue execution without specifying any stopping point.  The program
0746: will run until it hits a breakpoint, terminates, or gets a signal that
0747: the debugger is checking for (@code{gud-cont}).
0748: 
0749: @need 1000
0750: @item C-c C-d
0751: @kindex C-c C-d @r{(GUD)}
0752: @itemx C-x C-a C-d
0753: @findex gud-remove
0754: Delete the breakpoint(s) on the current source line, if any
0755: (@code{gud-remove}).  If you use this command in the GUD interaction
0756: buffer, it applies to the line where the program last stopped.
0757: 
0758: @item C-c C-t
0759: @kindex C-c C-t @r{(GUD)}
0760: @itemx C-x C-a C-t
0761: @findex gud-tbreak
0762: Set a temporary breakpoint on the current source line, if any
0763: (@code{gud-tbreak}).  If you use this command in the GUD interaction
0764: buffer, it applies to the line where the program last stopped.
0765: 
0766: @item C-c <
0767: @kindex C-c < @r{(GUD)}
0768: @itemx C-x C-a <
0769: @findex gud-up
0770: Select the next enclosing stack frame (@code{gud-up}).  This is
0771: equivalent to the GDB command @samp{up}.
0772: 
0773: @item C-c >
0774: @kindex C-c > @r{(GUD)}
0775: @itemx C-x C-a >
0776: @findex gud-down
0777: Select the next inner stack frame (@code{gud-down}).  This is
0778: equivalent to the GDB command @samp{down}.
0779: 
0780: @item C-c C-u
0781: @kindex C-c C-u @r{(GUD)}
0782: @itemx C-x C-a C-u
0783: @findex gud-until
0784: Continue execution to the current line (@code{gud-until}).  The
0785: program will run until it hits a breakpoint, terminates, gets a signal
0786: that the debugger is checking for, or reaches the line on which the
0787: cursor currently sits.
0788: 
0789: @item C-c C-f
0790: @kindex C-c C-f @r{(GUD)}
0791: @itemx C-x C-a C-f
0792: @findex gud-finish
0793: Run the program until the selected stack frame returns or
0794: stops for some other reason (@code{gud-finish}).
0795: @end table
0796: 
0797:   If you are using GDB, these additional key bindings are available:
0798: 
0799: @table @kbd
0800: @item C-x C-a C-j
0801: @kindex C-x C-a C-j @r{(GUD)}
0802: @findex gud-jump
0803: Only useful in a source buffer, @code{gud-jump} transfers the
0804: program's execution point to the current line.  In other words, the
0805: next line that the program executes will be the one where you gave the
0806: command.  If the new execution line is in a different function from
0807: the previously one, GDB prompts for confirmation since the results may
0808: be bizarre.  See the GDB manual entry regarding @code{jump} for
0809: details.
0810: 
0811: @item @key{TAB}
0812: @kindex TAB @r{(GUD)}
0813: @findex gud-gdb-complete-command
0814: With GDB, complete a symbol name (@code{gud-gdb-complete-command}).
0815: This key is available only in the GUD interaction buffer.
0816: @end table
0817: 
0818:   These commands interpret a numeric argument as a repeat count, when
0819: that makes sense.
0820: 
0821:   Because @key{TAB} serves as a completion command, you can't use it to
0822: enter a tab as input to the program you are debugging with GDB@.
0823: Instead, type @kbd{C-q @key{TAB}} to enter a tab.
0824: 
0825: @node GUD Customization
0826: @subsection GUD Customization
0827: 
0828: @vindex gdb-mode-hook
0829: @vindex dbx-mode-hook
0830: @vindex sdb-mode-hook
0831: @vindex xdb-mode-hook
0832: @vindex perldb-mode-hook
0833: @vindex pdb-mode-hook
0834: @vindex jdb-mode-hook
0835: @vindex guiler-mode-hook
0836:   On startup, GUD runs one of the following hooks:
0837: @code{gdb-mode-hook}, if you are using GDB; @code{dbx-mode-hook}, if
0838: you are using DBX; @code{sdb-mode-hook}, if you are using SDB;
0839: @code{xdb-mode-hook}, if you are using XDB; @code{guiler-mode-hook}
0840: for Guile REPL debugging; @code{perldb-mode-hook}, for Perl debugging
0841: mode; @code{pdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB@.
0842: @xref{Hooks}.
0843: 
0844:   The @code{gud-def} Lisp macro (@pxref{Defining Macros,,, elisp, the
0845: Emacs Lisp Reference Manual}) provides a convenient way to define an
0846: Emacs command that sends a particular command string to the debugger,
0847: and set up a key binding for in the GUD interaction buffer:
0848: 
0849: @findex gud-def
0850: @example
0851: (gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring})
0852: @end example
0853: 
0854:   This defines a command named @var{function} which sends
0855: @var{cmdstring} to the debugger process, and gives it the documentation
0856: string @var{docstring}.  You can then use the command @var{function} in any
0857: buffer.  If @var{binding} is non-@code{nil}, @code{gud-def} also binds
0858: the command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to
0859: @kbd{C-x C-a @var{binding}} generally.
0860: 
0861:   The command string @var{cmdstring} may contain certain
0862: @samp{%}-sequences that stand for data to be filled in at the time
0863: @var{function} is called:
0864: 
0865: @table @samp
0866: @item %f
0867: The name of the current source file.  If the current buffer is the GUD
0868: buffer, then the current source file is the file that the program
0869: stopped in.
0870: 
0871: @item %l
0872: The number of the current source line.  If the current buffer is the GUD
0873: buffer, then the current source line is the line that the program
0874: stopped in.
0875: 
0876: @item %e
0877: In transient-mark-mode the text in the region, if it is active.
0878: Otherwise the text of the C lvalue or function-call expression at or
0879: adjacent to point.
0880: 
0881: @item %a
0882: The text of the hexadecimal address at or adjacent to point.
0883: 
0884: @item %p
0885: The numeric argument of the called function, as a decimal number.  If
0886: the command is used without a numeric argument, @samp{%p} stands for the
0887: empty string.
0888: 
0889: If you don't use @samp{%p} in the command string, the command you define
0890: ignores any numeric argument.
0891: 
0892: @item %d
0893: The name of the directory of the current source file.
0894: 
0895: @item %c
0896: Fully qualified class name derived from the expression surrounding point
0897: (jdb only).
0898: @end table
0899: 
0900: @node GDB Graphical Interface
0901: @subsection GDB Graphical Interface
0902: 
0903:   The command @kbd{M-x gdb} starts GDB in an IDE-like interface, with
0904: specialized buffers for controlling breakpoints, stack frames, and
0905: other aspects of the debugger state.  It also provides additional ways
0906: to control the debugging session with the mouse, such as clicking in
0907: the fringe of a source buffer to set a breakpoint there.
0908: 
0909: @vindex gud-gdb-command-name
0910:   To run GDB using just the GUD interaction buffer interface, without
0911: these additional features, use @kbd{M-x gud-gdb} (@pxref{Starting
0912: GUD}).  You must use this if you want to debug multiple programs
0913: within one Emacs session, as that is currently unsupported by @kbd{M-x
0914: gdb}.
0915: 
0916:   Internally, @kbd{M-x gdb} informs GDB that its screen size is
0917: unlimited; for correct operation, you must not change GDB's screen
0918: height and width values during the debugging session.
0919: 
0920: @menu
0921: * GDB User Interface Layout::   Control the number of displayed buffers.
0922: * Source Buffers::              Use the mouse in the fringe/margin to
0923:                                 control your program.
0924: * Breakpoints Buffer::          A breakpoint control panel.
0925: * Threads Buffer::              Displays your threads.
0926: * Stack Buffer::                Select a frame from the call stack.
0927: * Other GDB Buffers::           Other buffers for controlling the GDB state.
0928: * Watch Expressions::           Monitor variable values in the speedbar.
0929: * Multithreaded Debugging::     Debugging programs with several threads.
0930: @end menu
0931: 
0932: @node GDB User Interface Layout
0933: @subsubsection GDB User Interface Layout
0934: @cindex GDB User Interface layout
0935: 
0936: @vindex gdb-many-windows
0937:   If the variable @code{gdb-many-windows} is @code{nil} (the default),
0938: @kbd{M-x gdb} normally displays only the GUD interaction buffer.
0939: However, if the variable @code{gdb-show-main} is also non-@code{nil},
0940: it starts with two windows: one displaying the GUD interaction buffer,
0941: and the other showing the source for the @code{main} function of the
0942: program you are debugging.
0943: 
0944:   If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb}
0945: displays the following frame layout:
0946: 
0947: @smallexample
0948: @group
0949: +--------------------------------+--------------------------------+
0950: |   GUD interaction buffer       |   Locals/Registers buffer      |
0951: |--------------------------------+--------------------------------+
0952: |   Primary Source buffer        |   I/O buffer for debugged pgm  |
0953: |--------------------------------+--------------------------------+
0954: |   Stack buffer                 |   Breakpoints/Threads buffer   |
0955: +--------------------------------+--------------------------------+
0956: @end group
0957: @end smallexample
0958: 
0959: @findex gdb-restore-windows
0960: @findex gdb-many-windows
0961:   If you ever change the window layout, you can restore the many-windows
0962: layout by typing @kbd{M-x gdb-restore-windows}.  To toggle
0963: between the many windows layout and a simple layout with just the GUD
0964: interaction buffer and a source file, type @kbd{M-x gdb-many-windows}.
0965: 
0966:   If you have an elaborate window setup, and don't want
0967: @code{gdb-many-windows} to disrupt that, it is better to invoke
0968: @kbd{M-x gdb} in a separate frame to begin with, then the arrangement
0969: of windows on your original frame will not be affected.  A separate
0970: frame for GDB sessions can come in especially handy if you work on a
0971: text-mode terminal, where the screen estate for windows could be at a
0972: premium.
0973: 
0974:   You may also specify additional GDB-related buffers to display,
0975: either in the same frame or a different one.  Select the buffers you
0976: want by typing @kbd{M-x gdb-display-@var{buffertype}-buffer} or
0977: @kbd{M-x gdb-frame-@var{buffertype}-buffer}, where @var{buffertype}
0978: is the relevant buffer type, such as @samp{breakpoints}.  You can do
0979: the same with the menu bar, with the @samp{GDB-Windows} and
0980: @samp{GDB-Frames} sub-menus of the @samp{GUD} menu.
0981: 
0982:   When you finish debugging, kill the GUD interaction buffer with
0983: @kbd{C-x k}, which will also kill all the buffers associated with the
0984: session.  However you need not do this if, after editing and
0985: re-compiling your source code within Emacs, you wish to continue
0986: debugging.  When you restart execution, GDB automatically finds the
0987: new executable.  Keeping the GUD interaction buffer has the advantage
0988: of keeping the shell history as well as GDB's breakpoints.  You do
0989: need to check that the breakpoints in recently edited source files are
0990: still in the right places.
0991: 
0992: @node Source Buffers
0993: @subsubsection Source Buffers
0994: @cindex fringes, for debugging
0995: 
0996: @table @asis
0997: @item @kbd{mouse-1} (in fringe)
0998: Set or clear a breakpoint on that line
0999: (@code{gdb-mouse-set-clear-breakpoint}).
1000: 
1001: @item @kbd{C-mouse-1} (in fringe)
1002: Enable or disable a breakpoint on that line
1003: (@code{gdb-mouse-toggle-breakpoint-margin}).
1004: 
1005: @item @kbd{mouse-3} (in fringe)
1006: Continue execution to that line (@code{gdb-mouse-until}).
1007: 
1008: @item @kbd{C-mouse-3} (in fringe)
1009: Jump to that line (@code{gdb-mouse-jump}).
1010: @end table
1011: 
1012:   On a graphical display, you can click @kbd{mouse-1} in the fringe of
1013: a source buffer, to set a breakpoint on that line (@pxref{Fringes}).
1014: A red dot appears in the fringe, where you clicked.  If a breakpoint
1015: already exists there, the click removes it.  A @kbd{C-mouse-1} click
1016: enables or disables an existing breakpoint; a breakpoint that is
1017: disabled, but not unset, is indicated by a gray dot.
1018: 
1019:   On a text terminal, or when fringes are disabled, enabled
1020: breakpoints are indicated with a @samp{B} character in the left margin
1021: of the window.  Disabled breakpoints are indicated with @samp{b}.
1022: (The margin is only displayed if a breakpoint is present.)
1023: 
1024:   A solid arrow in the left fringe of a source buffer indicates the
1025: line of the innermost frame where the debugged program has stopped.  A
1026: hollow arrow indicates the current execution line of a higher-level
1027: frame.  If you drag the arrow in the fringe with @kbd{mouse-1}, that
1028: causes execution to advance to the line where you release the button.
1029: Alternatively, you can click @kbd{mouse-3} in the fringe to advance to
1030: that line.  You can click @kbd{C-mouse-3} in the fringe to jump to
1031: that line without executing the intermediate lines.  This command
1032: allows you to go backwards, which can be useful for running through
1033: code that has already executed, in order to examine its execution in
1034: more detail.
1035: 
1036: @node Breakpoints Buffer
1037: @subsubsection Breakpoints Buffer
1038: 
1039:   The GDB Breakpoints buffer shows the breakpoints, watchpoints and
1040: catchpoints in the debugger session.  @xref{Breakpoints,,, gdb, The
1041: GNU debugger}.  It provides the following commands, which mostly apply
1042: to the @dfn{current breakpoint} (the breakpoint which point is on):
1043: 
1044: @table @kbd
1045: @item @key{SPC}
1046: @kindex SPC @r{(GDB Breakpoints buffer)}
1047: @findex gdb-toggle-breakpoint
1048: Enable/disable current breakpoint (@code{gdb-toggle-breakpoint}).  On
1049: a graphical display, this changes the color of the dot in the fringe
1050: of the source buffer at that line.  The dot is red when the breakpoint
1051: is enabled, and gray when it is disabled.
1052: 
1053: @item D
1054: @kindex D @r{(GDB Breakpoints buffer)}
1055: @findex gdb-delete-breakpoint
1056: Delete the current breakpoint (@code{gdb-delete-breakpoint}).
1057: 
1058: @item @key{RET}
1059: @kindex RET @r{(GDB Breakpoints buffer)}
1060: @findex gdb-goto-breakpoint
1061: Visit the source line for the current breakpoint
1062: (@code{gdb-goto-breakpoint}).
1063: 
1064: @item mouse-2
1065: @kindex mouse-2 @r{(GDB Breakpoints buffer)}
1066: Visit the source line for the breakpoint you click on
1067: (@code{gdb-goto-breakpoint}).
1068: @end table
1069: 
1070: @vindex gdb-show-threads-by-default
1071:   When @code{gdb-many-windows} is non-@code{nil}, the GDB Breakpoints
1072: buffer shares its window with the GDB Threads buffer.  To switch from
1073: one to the other click with @kbd{mouse-1} on the relevant button in
1074: the header line.  If @code{gdb-show-threads-by-default} is
1075: non-@code{nil}, the GDB Threads buffer is the one shown by default.
1076: 
1077: @node Threads Buffer
1078: @subsubsection Threads Buffer
1079: 
1080: @findex gdb-select-thread
1081:   The GDB Threads buffer displays a summary of the threads in the
1082: debugged program.  @xref{Threads, Threads, Debugging programs with
1083: multiple threads, gdb, The GNU debugger}.  To select a thread, move
1084: point there and press @key{RET} (@code{gdb-select-thread}), or click on
1085: it with @kbd{mouse-2}.  This also displays the associated source
1086: buffer, and updates the contents of the other GDB buffers.
1087: 
1088:   You can customize variables in the @code{gdb-buffers} group to
1089: select fields included in GDB Threads buffer.
1090: 
1091: @table @code
1092: @item gdb-thread-buffer-verbose-names
1093: @vindex gdb-thread-buffer-verbose-names
1094: Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)}.
1095: 
1096: @item gdb-thread-buffer-arguments
1097: @vindex gdb-thread-buffer-arguments
1098: Show arguments of thread top frames.
1099: 
1100: @item gdb-thread-buffer-locations
1101: @vindex gdb-thread-buffer-locations
1102: Show file information or library names.
1103: 
1104: @item gdb-thread-buffer-addresses
1105: @vindex gdb-thread-buffer-addresses
1106: Show addresses for thread frames in threads buffer.
1107: @end table
1108: 
1109:   To view information for several threads simultaneously, use the
1110: following commands from the GDB Threads buffer.
1111: 
1112: @table @kbd
1113: @item d
1114: @kindex d @r{(GDB threads buffer)}
1115: @findex gdb-display-disassembly-for-thread
1116: Display disassembly buffer for the thread at current line
1117: (@code{gdb-display-disassembly-for-thread}).
1118: 
1119: @item f
1120: @kindex f @r{(GDB threads buffer)}
1121: @findex gdb-display-stack-for-thread
1122: Display the GDB Stack buffer for the thread at current line
1123: (@code{gdb-display-stack-for-thread}).
1124: 
1125: @item l
1126: @kindex l @r{(GDB threads buffer)}
1127: @findex gdb-display-locals-for-thread
1128: Display the GDB Locals buffer for the thread at current line
1129: (@code{gdb-display-locals-for-thread}).
1130: 
1131: @item r
1132: @kindex r @r{(GDB threads buffer)}
1133: @findex gdb-display-registers-for-thread
1134: Display the GDB Registers buffer for the thread at current line
1135: (@code{gdb-display-registers-for-thread}).
1136: @end table
1137: 
1138: @noindent
1139: Their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and @kbd{R},
1140: display the corresponding buffer in a new frame.
1141: 
1142:   When you create a buffer showing information about some specific
1143: thread, it becomes bound to that thread and keeps showing actual
1144: information while you debug your program.  The mode indicator for each
1145: GDB buffer shows the number of the thread whose information that
1146: buffer displays.  The thread number is also included in the name of
1147: each bound buffer.
1148: 
1149:   Further commands are available in the GDB Threads buffer which
1150: depend on the mode of GDB that is used for controlling execution of
1151: your program.  @xref{Multithreaded Debugging}.
1152: 
1153: @node Stack Buffer
1154: @subsubsection Stack Buffer
1155: 
1156:   The GDB Stack buffer displays a @dfn{call stack}, with one line for
1157: each of the nested subroutine calls (@dfn{stack frames}) in the
1158: debugger session.  @xref{Backtrace,, Backtraces, gdb, The GNU
1159: debugger}.
1160: 
1161: @findex gdb-frames-select
1162:   On graphical displays, the selected stack frame is indicated by an
1163: arrow in the fringe.  On text terminals, or when fringes are disabled,
1164: the selected stack frame is displayed in reverse contrast.  To select
1165: a stack frame, move point in its line and type @key{RET}
1166: (@code{gdb-frames-select}), or click @kbd{mouse-2} on it.  Doing so
1167: also updates the Locals buffer
1168: @ifnottex
1169: (@pxref{Other GDB Buffers}).
1170: @end ifnottex
1171: @iftex
1172: (described in the next section).
1173: @end iftex
1174: 
1175: @node Other GDB Buffers
1176: @subsubsection Other GDB Buffers
1177: 
1178: @table @asis
1179: @item Locals Buffer
1180: This buffer displays the values of local variables of the current
1181: frame for simple data types (@pxref{Frame Info, Frame Info,
1182: Information on a frame, gdb, The GNU debugger}).  Press @key{RET} or
1183: click @kbd{mouse-2} on the value if you want to edit it.
1184: 
1185: Arrays and structures display their type only.  With GDB 6.4 or later,
1186: you can examine the value of the local variable at point by typing
1187: @key{RET}, or with a @kbd{mouse-2} click.  With earlier versions of
1188: GDB, use @key{RET} or @kbd{mouse-2} on the type description
1189: (@samp{[struct/union]} or @samp{[array]}).  @xref{Watch Expressions}.
1190: 
1191: @item Registers Buffer
1192: @findex toggle-gdb-all-registers
1193: This buffer displays the values held by the registers
1194: (@pxref{Registers,,, gdb, The GNU debugger}).  Press @key{RET} or
1195: click @kbd{mouse-2} on a register if you want to edit its value.  With
1196: GDB 6.4 or later, recently changed register values display with
1197: @code{font-lock-warning-face}.
1198: 
1199: @item Assembler Buffer
1200: The assembler buffer displays the current frame as machine code.  An
1201: arrow points to the current instruction, and you can set and remove
1202: breakpoints as in a source buffer.  Breakpoint icons also appear in
1203: the fringe or margin.
1204: 
1205: @item Memory Buffer
1206: The memory buffer lets you examine sections of program memory
1207: (@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}).
1208: Click @kbd{mouse-1} on the appropriate part of the header line to
1209: change the starting address or number of data items that the buffer
1210: displays.  Alternatively, use @kbd{S} or @kbd{N} respectively.  Click
1211: @kbd{mouse-3} on the header line to select the display format or unit
1212: size for these data items.
1213: @end table
1214: 
1215: When @code{gdb-many-windows} is non-@code{nil}, the locals buffer
1216: shares its window with the registers buffer, just like breakpoints and
1217: threads buffers.  To switch from one to the other, click with
1218: @kbd{mouse-1} on the relevant button in the header line.
1219: 
1220: @node Watch Expressions
1221: @subsubsection Watch Expressions
1222: @cindex Watching expressions in GDB
1223: 
1224: @findex gud-watch
1225: @kindex C-x C-a C-w @r{(GUD)}
1226:   If you want to see how a variable changes each time your program
1227: stops, move point into the variable name and click on the watch icon
1228: in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}.  If you
1229: specify a prefix argument, you can enter the variable name in the
1230: minibuffer.
1231: 
1232:   Each watch expression is displayed in the speedbar
1233: (@pxref{Speedbar}).  Complex data types, such as arrays, structures
1234: and unions are represented in a tree format.  Leaves and simple data
1235: types show the name of the expression and its value and, when the
1236: speedbar frame is selected, display the type as a tooltip.  Higher
1237: levels show the name, type and address value for pointers and just the
1238: name and type otherwise.  Root expressions also display the frame
1239: address as a tooltip to help identify the frame in which they were
1240: defined.
1241: 
1242:   To expand or contract a complex data type, click @kbd{mouse-2} or
1243: press @key{SPC} on the tag to the left of the expression.  Emacs asks
1244: for confirmation before expanding the expression if its number of
1245: immediate children exceeds the value of the variable
1246: @code{gdb-max-children}.
1247: 
1248: @kindex D @r{(GDB speedbar)}
1249: @findex gdb-var-delete
1250:   To delete a complex watch expression, move point to the root
1251: expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}).
1252: 
1253: @kindex RET @r{(GDB speedbar)}
1254: @findex gdb-edit-value
1255:   To edit a variable with a simple data type, or a simple element of a
1256: complex data type, move point there in the speedbar and type @key{RET}
1257: (@code{gdb-edit-value}).  Or you can click @kbd{mouse-2} on a value to
1258: edit it.  Either way, this reads the new value using the minibuffer.
1259: 
1260: @vindex gdb-show-changed-values
1261:   If you set the variable @code{gdb-show-changed-values} to
1262: non-@code{nil} (the default value), Emacs uses
1263: @code{font-lock-warning-face} to highlight values that have recently
1264: changed and @code{shadow} face to make variables which have gone out of
1265: scope less noticeable.  When a variable goes out of scope you can't
1266: edit its value.
1267: 
1268: @vindex gdb-delete-out-of-scope
1269:   If the variable @code{gdb-delete-out-of-scope} is non-@code{nil}
1270: (the default value), Emacs automatically deletes watch expressions
1271: which go out of scope.  Sometimes, when your program re-enters the
1272: same function many times, it may be useful to set this value to
1273: @code{nil} so that you don't need to recreate the watch expression.
1274: 
1275: @vindex gdb-use-colon-colon-notation
1276:   If the variable @code{gdb-use-colon-colon-notation} is
1277: non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}}
1278: format.  This allows the user to display watch expressions which share
1279: the same variable name.  The default value is @code{nil}.
1280: 
1281: @vindex gdb-speedbar-auto-raise
1282: To automatically raise the speedbar every time the display of watch
1283: expressions updates, set @code{gdb-speedbar-auto-raise} to
1284: non-@code{nil}.  This can be useful if you are debugging with a full
1285: screen Emacs frame.
1286: 
1287: @node Multithreaded Debugging
1288: @subsubsection Multithreaded Debugging
1289: @cindex Multithreaded debugging in GDB
1290: @cindex Non-stop debugging in GDB
1291: 
1292:   In GDB's @dfn{all-stop mode}, whenever your program stops, all
1293: execution threads stop.  Likewise, whenever you restart the program,
1294: all threads start executing.  @xref{All-Stop Mode, , All-Stop Mode,
1295: gdb, The GNU debugger}.  For some multi-threaded targets, GDB supports
1296: a further mode of operation, called @dfn{non-stop mode}, in which you
1297: can examine stopped program threads in the debugger while other
1298: threads continue to execute freely.  @xref{Non-Stop Mode, , Non-Stop
1299: Mode, gdb, The GNU debugger}.  Versions of GDB prior to 7.0 do not
1300: support non-stop mode, and it does not work on all targets.
1301: 
1302: @vindex gdb-non-stop-setting
1303:   The variable @code{gdb-non-stop-setting} determines whether Emacs
1304: runs GDB in all-stop mode or non-stop mode.  The default is @code{t},
1305: which means it tries to use non-stop mode if that is available.  If
1306: you change the value to @code{nil}, or if non-stop mode is
1307: unavailable, Emacs runs GDB in all-stop mode.  The variable takes
1308: effect when Emacs begins a debugging session; if you change its value,
1309: you should restart any active debugging session.
1310: 
1311: @vindex gdb-switch-when-another-stopped
1312:   When a thread stops in non-stop mode, Emacs usually switches to that
1313: thread.  If you don't want Emacs to do this switch if another stopped
1314: thread is already selected, change the variable
1315: @code{gdb-switch-when-another-stopped} to @code{nil}.
1316: 
1317: @vindex gdb-switch-reasons
1318:   Emacs can decide whether or not to switch to the stopped thread
1319: depending on the reason which caused the stop.  Customize the variable
1320: @code{gdb-switch-reasons} to select the stop reasons which will cause
1321: a thread switch.
1322: 
1323: @vindex gdb-stopped-functions
1324:   The variable @code{gdb-stopped-functions} allows you to execute your
1325: functions whenever some thread stops.
1326: 
1327:   In non-stop mode, you can switch between different modes for GUD
1328: execution control commands.
1329: 
1330: @vindex gdb-gud-control-all-threads
1331: @table @dfn
1332: @item Non-stop/A
1333: 
1334:   When @code{gdb-gud-control-all-threads} is @code{t} (the default
1335: value), interruption and continuation commands apply to all threads,
1336: so you can halt or continue all your threads with one command using
1337: @code{gud-stop-subjob} and @code{gud-cont}, respectively.  The
1338: @samp{Go} button is shown on the tool bar when at least one thread is
1339: stopped, whereas @samp{Stop} button is shown when at least one thread
1340: is running.
1341: 
1342: @item Non-stop/T
1343: 
1344: When @code{gdb-gud-control-all-threads} is @code{nil}, only the
1345: current thread is stopped/continued.  @samp{Go} and @samp{Stop}
1346: buttons on the GUD tool bar are shown depending on the state of
1347: current thread.
1348: @end table
1349: 
1350: You can change the current value of @code{gdb-gud-control-all-threads}
1351: from the tool bar or from @samp{GUD->GDB-MI} menu.
1352: 
1353:   Stepping commands always apply to the current thread.
1354: 
1355:   In non-stop mode, you can interrupt/continue your threads without
1356: selecting them.  Hitting @kbd{i} in threads buffer interrupts thread
1357: under point, @kbd{c} continues it, @kbd{s} steps through.  More such
1358: commands may be added in the future.
1359: 
1360:   Note that when you interrupt a thread, it stops with the
1361: @samp{signal received} reason.  If that reason is included in your
1362: @code{gdb-switch-reasons} (it is by default), Emacs will switch to
1363: that thread.
1364: 
1365: @node Executing Lisp
1366: @section Executing Lisp Expressions
1367: 
1368:   Emacs has major modes for several variants of Lisp.  They use the
1369: same editing commands as other programming language modes
1370: (@pxref{Programs}).  In addition, they provide special commands for
1371: executing Lisp expressions.
1372: 
1373: @table @asis
1374: @item Emacs Lisp mode
1375: The mode for editing Emacs Lisp source files.  It defines @kbd{C-M-x}
1376: to evaluate the current top-level Lisp expression.  @xref{Lisp Eval}.
1377: 
1378: @item Lisp Interaction mode
1379: The mode for an interactive Emacs Lisp session.  It defines @kbd{C-j}
1380: to evaluate the expression before point and insert its value in the
1381: buffer.  @xref{Lisp Interaction}.
1382: 
1383: @item Lisp mode
1384: The mode for editing source files of programs that run in Lisps other
1385: than Emacs Lisp.  It defines @kbd{C-M-x} to evaluate the current
1386: top-level expression in an external Lisp.  @xref{External Lisp}.
1387: 
1388: @item Inferior Lisp mode
1389: The mode for an interactive session with an external Lisp which is
1390: being run as a subprocess (or @dfn{inferior process}) of Emacs.
1391: @ifnottex
1392: @xref{External Lisp}.
1393: @end ifnottex
1394: 
1395: @item Scheme mode
1396: Like Lisp mode, but for Scheme programs.
1397: 
1398: @item Inferior Scheme mode
1399: Like Inferior Lisp mode, but for Scheme.
1400: @end table
1401: 
1402: @node Lisp Libraries
1403: @section Libraries of Lisp Code for Emacs
1404: @cindex libraries
1405: @cindex loading Lisp code
1406: 
1407:   Emacs Lisp code is stored in files whose names conventionally end in
1408: @file{.el}.  Such files are automatically visited in Emacs Lisp mode.
1409: 
1410: @cindex byte code
1411:   Emacs Lisp code can be compiled into byte-code, which loads faster,
1412: takes up less space, and executes faster.  By convention, compiled
1413: Emacs Lisp code goes in a separate file whose name ends in
1414: @samp{.elc}.  For example, the compiled code for @file{foo.el} goes in
1415: @file{foo.elc}.  @xref{Byte Compilation,, Byte Compilation, elisp, the
1416: Emacs Lisp Reference Manual}.
1417: 
1418: @findex load-file
1419:   To @dfn{load} an Emacs Lisp file, type @kbd{M-x load-file}.  This
1420: command reads a file name using the minibuffer, and executes the
1421: contents of that file as Emacs Lisp code.  It is not necessary to
1422: visit the file first; this command reads the file directly from disk,
1423: not from an existing Emacs buffer.
1424: 
1425: @findex load
1426: @findex load-library
1427: @vindex load-prefer-newer
1428: @cindex load path for Emacs Lisp
1429:   If an Emacs Lisp file is installed in the Emacs Lisp @dfn{load path}
1430: (defined below), you can load it by typing @kbd{M-x load-library},
1431: instead of using @kbd{M-x load-file}.  The @kbd{M-x load-library}
1432: command prompts for a @dfn{library name} rather than a file name; it
1433: searches through each directory in the Emacs Lisp load path, trying to
1434: find a file matching that library name.  If the library name is
1435: @samp{@var{foo}}, it tries looking for files named
1436: @file{@var{foo}.elc}, @file{@var{foo}.el}, and @file{@var{foo}}.  The
1437: default behavior is to load the first file found.  This command
1438: prefers @file{.elc} files over @file{.el} files because compiled files
1439: load and run faster.  If it finds that @file{@var{lib}.el} is newer
1440: than @file{@var{lib}.elc}, it issues a warning, in case someone made
1441: changes to the @file{.el} file and forgot to recompile it, but loads
1442: the @file{.elc} file anyway.  (Due to this behavior, you can save
1443: unfinished edits to Emacs Lisp source files, and not recompile until
1444: your changes are ready for use.)  If you set the option
1445: @code{load-prefer-newer} to a non-@code{nil} value, however, then
1446: rather than the procedure described above, Emacs loads whichever
1447: version of the file is newest.
1448: 
1449:   Emacs Lisp programs usually load Emacs Lisp files using the
1450: @code{load} function.  This is similar to @code{load-library}, but is
1451: lower-level and accepts additional arguments.  @xref{How Programs Do
1452: Loading,,, elisp, the Emacs Lisp Reference Manual}.
1453: 
1454: @vindex load-path
1455:   The Emacs Lisp load path is specified by the variable
1456: @code{load-path}.  Its value should be a list of directories
1457: (strings).  These directories are searched, in the specified order, by
1458: the @kbd{M-x load-library} command, the lower-level @code{load}
1459: function, and other Emacs functions that find Emacs Lisp libraries.
1460: An entry in @code{load-path} can also have the special value
1461: @code{nil}, which stands for the current default directory, but it is
1462: almost always a bad idea to use this, because its meaning will depend
1463: on the buffer that is current when @code{load-path} is used by Emacs.
1464: (If you find yourself wishing that @code{nil} were in the list, most
1465: likely what you really want is to use @kbd{M-x load-file}.)
1466: 
1467:   The default value of @code{load-path} is a list of directories where
1468: the Lisp code for Emacs itself is stored.  If you have libraries of
1469: your own in another directory, you can add that directory to the load
1470: path.  Unlike most other variables described in this manual,
1471: @code{load-path} cannot be changed via the Customize interface
1472: (@pxref{Easy Customization}), but you can add a directory to it by
1473: putting a line like this in your init file (@pxref{Init File}):
1474: 
1475: @example
1476: (add-to-list 'load-path "/path/to/my/lisp/library")
1477: @end example
1478: 
1479: @cindex autoload
1480:   Some commands are @dfn{autoloaded}; when you run them, Emacs
1481: automatically loads the associated library first.  For instance, the
1482: @kbd{M-x compile} command (@pxref{Compilation}) is autoloaded; if you
1483: call it, Emacs automatically loads the @code{compile} library first.
1484: In contrast, the command @kbd{M-x recompile} is not autoloaded, so it
1485: is unavailable until you load the @code{compile} library.
1486: 
1487: @vindex help-enable-auto-load
1488:   Automatic loading can also occur when you look up the documentation
1489: of an autoloaded command (@pxref{Name Help}), if the documentation
1490: refers to other functions and variables in its library (loading the
1491: library lets Emacs properly set up the hyperlinks in the @file{*Help*}
1492: buffer).  To disable this feature, change the variable
1493: @code{help-enable-auto-load} to @code{nil}.
1494: 
1495: @vindex load-dangerous-libraries
1496: @cindex Lisp files byte-compiled by XEmacs
1497:   By default, Emacs refuses to load compiled Lisp files which were
1498: compiled with XEmacs, a modified version of Emacs---they can cause
1499: Emacs to crash.  Set the variable @code{load-dangerous-libraries} to
1500: @code{t} if you want to try loading them.
1501: 
1502: @node Lisp Eval
1503: @section Evaluating Emacs Lisp Expressions
1504: @cindex Emacs Lisp mode
1505: @cindex mode, Emacs Lisp
1506: @cindex evaluation, Emacs Lisp
1507: 
1508: @findex emacs-lisp-mode
1509:   Emacs Lisp mode is the major mode for editing Emacs Lisp.  Its mode
1510: command is @kbd{M-x emacs-lisp-mode}.
1511: 
1512:   Emacs provides several commands for evaluating Emacs Lisp
1513: expressions.  You can use these commands in Emacs Lisp mode, to test
1514: your Emacs Lisp code as it is being written.  For example, after
1515: re-writing a function, you can evaluate the function definition to
1516: make it take effect for subsequent function calls.  These commands are
1517: also available globally, and can be used outside Emacs Lisp mode.
1518: 
1519: @table @asis
1520: @item @kbd{M-:}
1521: Read a single Emacs Lisp expression in the minibuffer, evaluate it,
1522: and print the value in the echo area (@code{eval-expression}).
1523: @item @kbd{C-x C-e}
1524: Evaluate the Emacs Lisp expression before point, and print the value
1525: in the echo area (@code{eval-last-sexp}).
1526: @item @kbd{C-M-x} @r{(in Emacs Lisp mode)}
1527: @itemx @kbd{M-x eval-defun}
1528: Evaluate the defun containing or after point, and print the value in
1529: the echo area (@code{eval-defun}).
1530: @item @kbd{M-x eval-region}
1531: Evaluate all the Emacs Lisp expressions in the region.
1532: @item @kbd{M-x eval-buffer}
1533: Evaluate all the Emacs Lisp expressions in the buffer.
1534: @end table
1535: 
1536: @ifinfo
1537: @c This uses 'colon' instead of a literal ':' because Info cannot
1538: @c cope with a ':' in a menu.
1539: @kindex M-colon
1540: @end ifinfo
1541: @ifnotinfo
1542: @kindex M-:
1543: @end ifnotinfo
1544: @findex eval-expression
1545:   @kbd{M-:} (@code{eval-expression}) reads an expression using the
1546: minibuffer, and evaluates it.  (Before evaluating the expression, the
1547: current buffer switches back to the buffer that was current when you
1548: typed @kbd{M-:}, not the minibuffer into which you typed the
1549: expression.)
1550: 
1551: @kindex C-x C-e
1552: @findex eval-last-sexp
1553:   The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the
1554: Emacs Lisp expression preceding point in the buffer, and displays the
1555: value in the echo area.  When the result of an evaluation is an
1556: integer, it is displayed together with the value in other formats
1557: (octal, hexadecimal, and character if
1558: @code{eval-expression-print-maximum-character}, described below,
1559: allows it).
1560: 
1561:   If @kbd{M-:} or @kbd{C-x C-e} is given a prefix argument, it inserts
1562: the value into the current buffer at point, rather than displaying it
1563: in the echo area.  If the prefix argument is zero, any integer output
1564: is inserted together with its value in other formats (octal,
1565: hexadecimal, and character).  Such a prefix argument also prevents
1566: abbreviation of the output according to the variables
1567: @code{eval-expression-print-level} and
1568: @code{eval-expression-print-length} (see below).  Similarly, a prefix
1569: argument of @code{-1} overrides the effect of
1570: @code{eval-expression-print-length}.
1571: 
1572: @kindex C-M-x @r{(Emacs Lisp mode)}
1573: @findex eval-defun
1574:   The @code{eval-defun} command is bound to @kbd{C-M-x} in Emacs Lisp
1575: mode.  It evaluates the top-level Lisp expression containing or
1576: following point, and prints the value in the echo area.  In this
1577: context, a top-level expression is referred to as a ``defun'', but it
1578: need not be an actual @code{defun} (function definition).  In
1579: particular, this command treats @code{defvar} expressions specially.
1580: Normally, evaluating a @code{defvar} expression does nothing if the
1581: variable it defines already has a value.  But this command
1582: unconditionally resets the variable to the initial value specified by
1583: the @code{defvar}; this is convenient for debugging Emacs Lisp
1584: programs.  @code{defcustom} and @code{defface} expressions are treated
1585: similarly.  Note that the other commands documented in this section do
1586: not have this special feature.
1587: 
1588:   With a prefix argument, @kbd{C-M-x} instruments the function
1589: definition for Edebug, the Emacs Lisp Debugger.  @xref{Instrumenting,
1590: Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}.
1591: 
1592: @findex eval-region
1593: @findex eval-buffer
1594:   The command @kbd{M-x eval-region} parses the text of the region as
1595: one or more Lisp expressions, evaluating them one by one.  @kbd{M-x
1596: eval-buffer} is similar but evaluates the entire buffer.
1597: 
1598: @vindex eval-expression-print-level
1599: @vindex eval-expression-print-length
1600: @vindex eval-expression-print-maximum-character
1601: @vindex eval-expression-debug-on-error
1602:   The options @code{eval-expression-print-level} and
1603: @code{eval-expression-print-length} control the maximum depth and
1604: length of lists to print in the result of the evaluation commands
1605: before abbreviating them.  Supplying a zero prefix argument to
1606: @code{eval-expression} or @code{eval-last-sexp} causes lists to be
1607: printed in full.  @code{eval-expression-debug-on-error} controls
1608: whether evaluation errors invoke the debugger when these commands are
1609: used; its default is @code{t}.
1610: @code{eval-expression-print-maximum-character} prevents integers which
1611: are larger than it from being displayed as characters.
1612: 
1613: @node Lisp Interaction
1614: @section Lisp Interaction Buffers
1615: 
1616: @findex lisp-interaction-mode
1617:   When Emacs starts up, it contains a buffer named @file{*scratch*},
1618: which is provided for evaluating Emacs Lisp expressions interactively.
1619: Its major mode is Lisp Interaction mode.  You can also enable Lisp
1620: Interaction mode by typing @kbd{M-x lisp-interaction-mode}.
1621: 
1622: @findex eval-print-last-sexp
1623: @kindex C-j @r{(Lisp Interaction mode)}
1624:   In the @file{*scratch*} buffer, and other Lisp Interaction mode
1625: buffers, @kbd{C-j} (@code{eval-print-last-sexp}) evaluates the Lisp
1626: expression before point, and inserts the value at point.  Thus, as you
1627: type expressions into the buffer followed by @kbd{C-j} after each
1628: expression, the buffer records a transcript of the evaluated
1629: expressions and their values.  All other commands in Lisp Interaction
1630: mode are the same as in Emacs Lisp mode.
1631: 
1632: @vindex initial-scratch-message
1633:   At startup, the @file{*scratch*} buffer contains a short message, in
1634: the form of a Lisp comment, that explains what it is for.  This
1635: message is controlled by the variable @code{initial-scratch-message},
1636: which should be either a documentation string, or @code{nil} (which means to
1637: suppress the message).
1638: 
1639: @findex ielm
1640:   An alternative way of evaluating Emacs Lisp expressions
1641: interactively is to use Inferior Emacs Lisp mode, which provides an
1642: interface rather like Shell mode (@pxref{Shell Mode}) for evaluating
1643: Emacs Lisp expressions.  Type @kbd{M-x ielm} to create an
1644: @file{*ielm*} buffer which uses this mode.  For more information, see
1645: that command's documentation.
1646: 
1647: @node External Lisp
1648: @section Running an External Lisp
1649: @cindex Lisp mode
1650: @cindex mode, Lisp
1651: @cindex Common Lisp
1652: 
1653:   Lisp mode is the major mode for editing programs written in
1654: general-purpose Lisp dialects, such as Common Lisp.  Its mode command
1655: is @kbd{M-x lisp-mode}.  Emacs uses Lisp mode automatically for files
1656: whose names end in @file{.l}, @file{.lsp}, or @file{.lisp}.
1657: 
1658: @findex run-lisp
1659: @vindex inferior-lisp-program
1660: @kindex C-x C-z
1661:   You can run an external Lisp session as a subprocess or
1662: @dfn{inferior process} of Emacs, and pass expressions to it to be
1663: evaluated.  To begin an external Lisp session, type @kbd{M-x
1664: run-lisp}.  This runs the program named @command{lisp}, and sets it up
1665: so that both input and output go through an Emacs buffer named
1666: @file{*inferior-lisp*}.  To change the name of the Lisp program run by
1667: @kbd{M-x run-lisp}, change the variable @code{inferior-lisp-program}.
1668: 
1669:   The major mode for the @file{*lisp*} buffer is Inferior Lisp mode,
1670: which combines the characteristics of Lisp mode and Shell mode
1671: (@pxref{Shell Mode}).  To send input to the Lisp session, go to the
1672: end of the @file{*lisp*} buffer and type the input, followed by
1673: @key{RET}.  Terminal output from the Lisp session is automatically
1674: inserted in the buffer.
1675: 
1676: @kindex C-M-x @r{(Lisp mode)}
1677: @findex lisp-eval-defun
1678:   When you edit a Lisp program in Lisp mode, you can type @kbd{C-M-x}
1679: (@code{lisp-eval-defun}) to send an expression from the Lisp mode
1680: buffer to a Lisp session that you had started with @kbd{M-x run-lisp}.
1681: The expression sent is the top-level Lisp expression at or following
1682: point.  The resulting value goes as usual into the
1683: @file{*inferior-lisp*} buffer.  Note that the effect of @kbd{C-M-x} in
1684: Lisp mode is thus very similar to its effect in Emacs Lisp mode
1685: (@pxref{Lisp Eval}), except that the expression is sent to a different
1686: Lisp environment instead of being evaluated in Emacs.
1687: 
1688: @findex scheme-mode
1689: @findex run-scheme
1690: @cindex Scheme mode
1691: @cindex mode, Scheme
1692: @kindex C-M-x @r{(Scheme mode)}
1693:   The facilities for editing Scheme code, and for sending expressions
1694: to a Scheme subprocess, are very similar.  Scheme source files are
1695: edited in Scheme mode, which can be explicitly enabled with @kbd{M-x
1696: scheme-mode}.  You can initiate a Scheme session by typing @kbd{M-x
1697: run-scheme} (the buffer for interacting with Scheme is named
1698: @file{*scheme*}), and send expressions to it by typing @kbd{C-M-x}.
1699: