comparison man/building.texi @ 90128:13796b0653c7

Revision: [e-mail]--gnu-2005/emacs--unicode--0--patch-29 Merge from emacs--cvs-trunk--0 Patches applied: * emacs--cvs-trunk--0 (patch 192-205) - Update from CVS - Use gdb-ui breakpoint faces on ttys too - Tweak gdb-ui breakpoint faces - Tweak info/.arch-inventory to identify info/.cvsignore as source - Clean up gdb-ui breakpoint faces

90127:30ad2795fdab

in the larger process of developing and maintaining programs.

@menu
* Compilation::         Compiling programs in languages other
                          than Lisp (C, Pascal, etc.).
* Grep Searching::      Running grep as if it were a compiler.
* Compilation Mode::    The mode for visiting compiler errors.
* Compilation Shell::   Customizing your shell properly
                          for use in the compilation buffer.
* Debuggers::	        Running symbolic debuggers for non-Lisp programs.
* Executing Lisp::      Various modes for editing Lisp programs,
                          with different facilities for running
                          the Lisp programs.
* Libraries: Lisp Libraries.      Creating Lisp programs to run in Emacs.

with the variable @code{compilation-environment}.  Its value is a list
of environment variable settings; each element should be a string of
the form @code{"@var{envvarname}=@var{value}"}.  These environment
variable settings override the usual ones.

@node Grep Searching
@section Searching with Grep under Emacs

@findex grep
  Just as you can run a compiler from Emacs and then visit the lines
where there were compilation errors, you can also run @code{grep} and
then visit the lines on which matches were found.  This works by
treating the matches reported by @code{grep} as if they were ``errors.''

  To do this, type @kbd{M-x grep}, then enter a command line that
specifies how to run @code{grep}.  Use the same arguments you would give
@code{grep} when running it normally: a @code{grep}-style regexp
(usually in single-quotes to quote the shell's special characters)
followed by file names, which may use wildcards.  The output from
@code{grep} goes in the @samp{*grep*} buffer.  You can find the
corresponding lines in the original files using @kbd{C-x `} and
@key{RET}, as with compilation errors.

  If you specify a prefix argument for @kbd{M-x grep}, it figures out
the tag (@pxref{Tags}) around point, and puts that into the default
@code{grep} command.

@findex grep-find
@findex find-grep
  The command @kbd{M-x grep-find} (also available as @kbd{M-x
find-grep}) is similar to @kbd{M-x grep}, but it supplies a different
initial default for the command---one that runs both @code{find} and
@code{grep}, so as to search every file in a directory tree.  See also
the @code{find-grep-dired} command, in @ref{Dired and Find}.

@node Compilation Mode
@section Compilation Mode

@findex compile-goto-error
@cindex Compilation mode

@item @key{RET}
Visit the locus of the error message that point is on.
This command is used in the compilation buffer.
@item Mouse-2
Visit the locus of the error message that you click on.
@end table

@kindex C-x `
@findex next-error
  You can visit the source for any particular error message by moving
point in the @samp{*compilation*} buffer to that error message and
typing @key{RET} (@code{compile-goto-error}).  Alternatively, you can
click @kbd{Mouse-2} on the error message; you need not switch to the
@samp{*compilation*} buffer first.

  To parse the compiler error messages sequentially, type @kbd{C-x `}
(@code{next-error}).  The character following the @kbd{C-x} is the
backquote or ``grave accent,'' not the single-quote.  This command is
available in all buffers, not just in @samp{*compilation*}; it displays
the next error message at the top of one window and source location of
the error in another window.

  The first time @kbd{C-x `} is used after the start of a compilation,
it moves to the first error's location.  Subsequent uses of @kbd{C-x `}
advance down to subsequent errors.  If you visit a specific error
message with @key{RET} or @kbd{Mouse-2}, subsequent @kbd{C-x `}

and the line number from the text of a message.  If your compiler isn't
supported, you can tailor Compilation mode to it by adding elements to
that list.  A similar variable @code{grep-regexp-alist} tells Emacs how
to parse output of a @code{grep} command.

  Compilation mode also redefines the keys @key{SPC} and @key{DEL} to
scroll by screenfuls, and @kbd{M-n} and @kbd{M-p} to move to the next or
previous error message.  You can also use @kbd{M-@{} and @kbd{M-@}} to
move up or down to an error message for a different source file.

  The features of Compilation mode are also available in a minor mode
called Compilation Minor mode.  This lets you parse error messages in
any buffer, not just a normal compilation output buffer.  Type @kbd{M-x
compilation-minor-mode} to enable the minor mode.  This defines the keys

subprocesses; to work around this lack, @kbd{M-x compile} runs the
compilation command synchronously on MS-DOS.  As a consequence, you must
wait until the command finishes before you can do anything else in
Emacs.  @xref{MS-DOS}.

@node Debuggers
@section Running Debuggers Under Emacs
@cindex debuggers
@cindex GUD library
@cindex GDB
@cindex DBX
@cindex SDB
@cindex XDB
@cindex Perldb
@cindex JDB
@cindex PDB

@c Do you believe in GUD?
The GUD (Grand Unified Debugger) library provides an interface to

(@pxref{Tags}) in order for GUD to find functions in the source code.
If you have not visited a tags table or the tags table doesn't list one
of the functions, you get a message saying @samp{The sdb support
requires a valid tags table to work}.  If this happens, generate a valid
tags table in the working directory and try again.

@item M-x perldb @key{RET} @var{file} @key{RET}
@findex perldb
Run the Perl interpreter in debug mode to debug @var{file}, a Perl program.

@item @key{RET}
@kindex RET @r{(GDB breakpoints buffer)}
@findex gdb-goto-breakpoint
Display the file in the source buffer at the breakpoint specified at
the current line (@code{gdb-goto-breakpoint}).  Alternatively, click @kbd{Mouse-2} on the breakpoint that you wish to visit.
@end table

@node Stack Buffer
@subsubsection Stack Buffer

The stack buffer displays a @dfn{call stack}, with one line for each
of the nested subroutine calls (@dfn{stack frames}) now active in the
program.  @xref{Backtrace,,info stack, gdb, The GNU debugger}.

Move point to any frame in the stack and type @key{RET} to make it
become the current frame (@code{gdb-frames-select}) and display the
associated source in the source buffer.  Alternatively, click
@kbd{Mouse-2} to make the selected frame become the current one.  If the
locals buffer is displayed then its contents update to display the
variables that are local to the new frame.

@node Watch Expressions
@subsubsection Watch Expressions
@cindex Watching expressions in GDB

  The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Lisp
expression preceding point in the buffer, and displays the value in the
echo area.  It is available in all major modes, not just Emacs-Lisp
mode.  It does not treat @code{defvar} specially.

  If @kbd{C-M-x}, @kbd{C-x C-e}, or @kbd{M-:} is given a numeric
argument, it inserts the value into the current buffer at point, rather
than displaying it in the echo area.  The argument's value does not
matter.

90128:13796b0653c7

in the larger process of developing and maintaining programs.

@menu
* Compilation::         Compiling programs in languages other
                          than Lisp (C, Pascal, etc.).
* Compilation Mode::    The mode for visiting compiler errors.
* Compilation Shell::   Customizing your shell properly
                          for use in the compilation buffer.
* Grep Searching::      Searching with grep.
* Debuggers::	        Running symbolic debuggers for non-Lisp programs.
* Executing Lisp::      Various modes for editing Lisp programs,
                          with different facilities for running
                          the Lisp programs.
* Libraries: Lisp Libraries.      Creating Lisp programs to run in Emacs.

with the variable @code{compilation-environment}.  Its value is a list
of environment variable settings; each element should be a string of
the form @code{"@var{envvarname}=@var{value}"}.  These environment
variable settings override the usual ones.

@node Compilation Mode
@section Compilation Mode

@findex compile-goto-error
@cindex Compilation mode

@item @key{RET}
Visit the locus of the error message that point is on.
This command is used in the compilation buffer.
@item Mouse-2
Visit the locus of the error message that you click on.
@item M-n
Find and highlight the locus of the next error message, without
selecting the source buffer.
@item M-p
Find and highlight the locus of the previous error message, without
selecting the source buffer.
@item M-@}
Move point to the next error for a different file than the current
one.
@item M-@{
Move point to the previous error for a different file than the current
one.
@item C-c C-f
Toggle Next Error Follow minor mode, which makes cursor motion in the
compilation buffer produce automatic source display.
@end table

@kindex C-x `
@findex next-error
  You can visit the source for any particular error message by moving
point in the @samp{*compilation*} buffer to that error message and
typing @key{RET} (@code{compile-goto-error}).  Alternatively, you can
click @kbd{Mouse-2} on the error message; you need not switch to the
@samp{*compilation*} buffer first.

@vindex next-error-highlight
  To parse the compiler error messages sequentially, type @kbd{C-x `}
(@code{next-error}).  The character following the @kbd{C-x} is the
backquote or ``grave accent,'' not the single-quote.  This command is
available in all buffers, not just in @samp{*compilation*}; it
displays the next error message at the top of one window and source
location of the error in another window.  It also momentarily
highlights the relevant source line.  You can change the behavior of
this highlighting with the variable @code{next-error-highlight}.

  The first time @kbd{C-x `} is used after the start of a compilation,
it moves to the first error's location.  Subsequent uses of @kbd{C-x `}
advance down to subsequent errors.  If you visit a specific error
message with @key{RET} or @kbd{Mouse-2}, subsequent @kbd{C-x `}

and the line number from the text of a message.  If your compiler isn't
supported, you can tailor Compilation mode to it by adding elements to
that list.  A similar variable @code{grep-regexp-alist} tells Emacs how
to parse output of a @code{grep} command.

@findex compilation-next-error
@findex compilation-previous-error
@findex compilation-next-file
@findex compilation-previous-file
  Compilation mode also redefines the keys @key{SPC} and @key{DEL} to
scroll by screenfuls, and @kbd{M-n} (@code{compilation-next-error})
and @kbd{M-p} (@code{compilation-previous-error}) to move to the next
or previous error message.  You can also use @kbd{M-@{}
(@code{compilation-next-file} and @kbd{M-@}}
(@code{compilation-previous-file}) to move up or down to an error
message for a different source file.

@cindex Next Error Follow mode
@findex next-error-follow-minor-mode
  You can type @kbd{C-c C-f} to toggle Next Error Follow mode.  In
this minor mode, ordinary cursor motion in the compilation buffer
automatically updates the source buffer.  For instance, moving the
cursor to the next error message causes the location of that error to
be displayed immediately.

  The features of Compilation mode are also available in a minor mode
called Compilation Minor mode.  This lets you parse error messages in
any buffer, not just a normal compilation output buffer.  Type @kbd{M-x
compilation-minor-mode} to enable the minor mode.  This defines the keys

subprocesses; to work around this lack, @kbd{M-x compile} runs the
compilation command synchronously on MS-DOS.  As a consequence, you must
wait until the command finishes before you can do anything else in
Emacs.  @xref{MS-DOS}.

@node Grep Searching
@section Searching with Grep under Emacs

@findex grep
  Just as you can run a compiler from Emacs and then visit the lines
where there were compilation errors, you can also run @code{grep} and
then visit the lines on which matches were found.  This works by
treating the matches reported by @code{grep} as if they were ``errors.''

  To do this, type @kbd{M-x grep}, then enter a command line that
specifies how to run @code{grep}.  Use the same arguments you would give
@code{grep} when running it normally: a @code{grep}-style regexp
(usually in single-quotes to quote the shell's special characters)
followed by file names, which may use wildcards.  If you specify a
prefix argument for @kbd{M-x grep}, it figures out the tag
(@pxref{Tags}) around point, and puts that into the default
@code{grep} command.

  The output from @code{grep} goes in the @samp{*grep*} buffer.  You
can find the corresponding lines in the original files using @kbd{C-x
`}, @key{RET}, and so forth, just like compilation errors.

  Some grep programs accept a @samp{--color} option to output special
markers around matches for the purpose of highlighting.  You can make
use of this feature by setting @code{grep-highlight-matches} to t.
When displaying a match in the source buffer, the exact match will be
highlighted, instead of the entire source line.

@findex grep-find
@findex find-grep
  The command @kbd{M-x grep-find} (also available as @kbd{M-x
find-grep}) is similar to @kbd{M-x grep}, but it supplies a different
initial default for the command---one that runs both @code{find} and
@code{grep}, so as to search every file in a directory tree.  See also
the @code{find-grep-dired} command, in @ref{Dired and Find}.

@node Debuggers
@section Running Debuggers Under Emacs
@cindex debuggers
@cindex GUD library
@cindex GDB
@cindex DBX
@cindex SDB
@cindex XDB
@cindex Perldb
@cindex bashdb
@cindex JDB
@cindex PDB

@c Do you believe in GUD?
The GUD (Grand Unified Debugger) library provides an interface to

(@pxref{Tags}) in order for GUD to find functions in the source code.
If you have not visited a tags table or the tags table doesn't list one
of the functions, you get a message saying @samp{The sdb support
requires a valid tags table to work}.  If this happens, generate a valid
tags table in the working directory and try again.

@item M-x bashdb @key{RET} @var{file} @key{RET}
@findex bashdb
Run the bash debugger to debug @var{file}, a shell script.

@item M-x perldb @key{RET} @var{file} @key{RET}
@findex perldb
Run the Perl interpreter in debug mode to debug @var{file}, a Perl program.

@item @key{RET}
@kindex RET @r{(GDB breakpoints buffer)}
@findex gdb-goto-breakpoint
Display the file in the source buffer at the breakpoint specified at
the current line (@code{gdb-goto-breakpoint}).  Alternatively, click
@kbd{Mouse-2} on the breakpoint that you wish to visit.
@end table

@node Stack Buffer
@subsubsection Stack Buffer

The stack buffer displays a @dfn{call stack}, with one line for each
of the nested subroutine calls (@dfn{stack frames}) now active in the
program.  @xref{Backtrace,,info stack, gdb, The GNU debugger}.

The selected frame is displayed in reverse contrast.  Move point to
any frame in the stack and type @key{RET} to select it (@code{gdb-frames-select})
and display the associated source in the source buffer. Alternatively,
click @kbd{Mouse-2} to make the selected frame become the current one.
If the locals buffer is displayed then its contents update to display
the variables that are local to the new frame.

@node Watch Expressions
@subsubsection Watch Expressions
@cindex Watching expressions in GDB

  The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Lisp
expression preceding point in the buffer, and displays the value in the
echo area.  It is available in all major modes, not just Emacs-Lisp
mode.  It does not treat @code{defvar} specially.

  When the result of an evaluation is an integer, you can type
@kbd{C-x C-e} a second time to display the value of the integer result
in additional formats (octal, hexadecimal, and character).

  If @kbd{C-M-x}, @kbd{C-x C-e}, or @kbd{M-:} is given a numeric
argument, it inserts the value into the current buffer at point, rather
than displaying it in the echo area.  The argument's value does not
matter.