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