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