comparison man/building.texi @ 55577:66ec9893d229

(GDB Graphical Interface): Update and describe layout first.

55576:77a79f33714b

@c Do you believe in GUD?
The GUD (Grand Unified Debugger) library provides an interface to
various symbolic debuggers from within Emacs.  We recommend the debugger
GDB, which is free software, but you can also run DBX, SDB or XDB if you
have them.  GUD can also serve as an interface to the Perl's debugging
mode, the Python debugger PDB, and to JDB, the Java Debugger.
@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference Manual},
for information on debugging Emacs Lisp programs.

@menu

to a particular debugger program.

@table @kbd
@item M-x gdb @key{RET} @var{file} @key{RET}
@findex gdb
Run GDB as a subprocess of Emacs.  This command creates a buffer
for input and output to GDB, and switches to it.  If a GDB buffer
already exists, it just switches to that buffer.

@item M-x gdba @key{RET} @var{file} @key{RET}
Run GDB as a subprocess of Emacs, providing a graphical interface
to GDB features through Emacs.  @xref{GDB Graphical Interface}.

still interact with GDB through the GUD buffer, but the point of this
mode is that you can do it through menus and clicks, without needing
to know GDB commands.

@menu
* Breakpoints Buffer::   A breakpoint control panel.
* Stack Buffer::         Select a frame from the call stack. 
* Watch Expressions::    Monitor variable values in the speedbar.
* Other Buffers::        Input/output, locals, registers and assembler buffers.
* Layout::               Control the number of displayed buffers.
@end menu

@node Breakpoints Buffer
@subsubsection Breakpoints Buffer

The breakpoints buffer shows the existing breakpoints and watchpoints 

on the tag to the left of the expression.

@kindex RET @r{(GDB speedbar)}
@findex gdb-var-delete
With the cursor over the root expression of a complex data type, type
@key{D} to delete it from the speedbar
(@code{gdb-var-delete}).

@findex gdb-edit-value
With the cursor over a simple data type or an element of a complex
data type which holds a value, type @key{RET} or click @kbd{Mouse-2} to edit

@node Other Buffers
@subsubsection Other Buffers

@table @asis
@item Input/Output Buffer
The executable program that is being debugged takes its input and
displays its output here.  Some of the commands from shell mode are
available here.  @xref{Shell Mode}.

@item Locals Buffer
The locals buffer displays the values of local variables of the

current thread (@code{gdb-threads-select}) and display the associated
source in the source buffer.  Alternatively, click @kbd{Mouse-2} to
make the selected thread become the current one.

@end table

@node Layout
@subsubsection Layout
@cindex GDB User Interface layout

@findex gdb-many-windows
@vindex gdb-many-windows
If @code{gdb-many-windows} is @code{nil} (the default value), then GDB starts
with just two windows: the GUD and the source buffer.  If it is @code{t}, then
six windows with the following layout will appear:

@multitable @columnfractions .5 .5
@item GUD buffer (I/O of GDB)
@tab Locals buffer
@item
@tab
@item Source buffer
@tab Input/Output (of debuggee) buffer
@item
@tab
@item Stack buffer
@tab Breakpoints buffer
@end multitable

To toggle this layout, do @kbd{M-x gdb-many-windows}.

@findex gdb-restore-windows
If you change the window layout, for example, while editing and
re-compiling your program, then you can restore it with
@code{gdb-restore-windows}.

You may also choose which additional buffers you want to display,
either in the same frame or a different one.  Select GDB-windows or
GDB-Frames from the menu-bar under the heading GUD.  If the menu-bar
is unavailable, type @code{M-x
gdb-display-@var{buffertype}-buffer} or @code{M-x
gdb-frame-@var{buffertype}-buffer} respectively, where @var{buffertype}
is the relevant buffer type e.g breakpoints.

@node Executing Lisp
@section Executing Lisp Expressions

  Emacs has several different major modes for Lisp and Scheme.  They are

55577:66ec9893d229

@c Do you believe in GUD?
The GUD (Grand Unified Debugger) library provides an interface to
various symbolic debuggers from within Emacs.  We recommend the debugger
GDB, which is free software, but you can also run DBX, SDB or XDB if you
have them.  GUD can also serve as an interface to Perl's debugging
mode, the Python debugger PDB, and to JDB, the Java Debugger.
@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference Manual},
for information on debugging Emacs Lisp programs.

@menu

to a particular debugger program.

@table @kbd
@item M-x gdb @key{RET} @var{file} @key{RET}
@findex gdb
Run GDB as a subprocess of Emacs.  If the variable
@code{gud-gdb-command-name} is ``gdb --annotate=3'' (the default
value) then GDB starts as for @kbd{M-x gdba} below.  If you want to
GDB to start as in Emacs 21.3 and earlier then set
@code{gud-gdb-command-name} to ``gdb --fullname''.  In this case, the
command creates a buffer for input and output to GDB, and switches to
it.  If a GDB buffer already exists, it just switches to that buffer.

@item M-x gdba @key{RET} @var{file} @key{RET}
Run GDB as a subprocess of Emacs, providing a graphical interface
to GDB features through Emacs.  @xref{GDB Graphical Interface}.

still interact with GDB through the GUD buffer, but the point of this
mode is that you can do it through menus and clicks, without needing
to know GDB commands.

@menu
* Layout::               Control the number of displayed buffers.
* Breakpoints Buffer::   A breakpoint control panel.
* Stack Buffer::         Select a frame from the call stack. 
* Watch Expressions::    Monitor variable values in the speedbar.
* Other Buffers::        Input/output, locals, registers and assembler buffers.
@end menu

@node Layout
@subsubsection Layout
@cindex GDB User Interface layout

@findex gdb-many-windows
@vindex gdb-many-windows

If the variable @code{gdb-many-windows} is @code{nil} (the default
value) then gdb just pops up the GUD buffer unless the variable
@code{gdb-show-main} is non-@code{nil}.  In this case it starts with
two windows: one displaying the GUD buffer and the other with the
source file with the main routine of the inferior.

If @code{gdb-many-windows} is non-@code{nil}, regardless of the value of
@code{gdb-show-main}, the layout below will appear unless
@code{gdb-use-inferior-io-buffer} is @code{nil}.  In this case the
source buffer occupies the full width of the frame.

@multitable @columnfractions .5 .5
@item GUD buffer (I/O of GDB)
@tab Locals buffer
@item
@tab
@item Source buffer
@tab Input/Output (of inferior) buffer
@item
@tab
@item Stack buffer
@tab Breakpoints buffer
@end multitable

To toggle this layout, do @kbd{M-x gdb-many-windows}.

@findex gdb-restore-windows
If you change the window layout, for example, while editing and
re-compiling your program, then you can restore it with the command
@code{gdb-restore-windows}.

You may also choose which additional buffers you want to display,
either in the same frame or a different one.  Select GDB-windows or
GDB-Frames from the menu-bar under the heading GUD.  If the menu-bar
is unavailable, type @code{M-x
gdb-display-@var{buffertype}-buffer} or @code{M-x
gdb-frame-@var{buffertype}-buffer} respectively, where @var{buffertype}
is the relevant buffer type e.g breakpoints.

@node Breakpoints Buffer
@subsubsection Breakpoints Buffer

The breakpoints buffer shows the existing breakpoints and watchpoints 

on the tag to the left of the expression.

@kindex RET @r{(GDB speedbar)}
@findex gdb-var-delete
With the cursor over the root expression of a complex data type, type
@kbd{D} to delete it from the speedbar
(@code{gdb-var-delete}).

@findex gdb-edit-value
With the cursor over a simple data type or an element of a complex
data type which holds a value, type @key{RET} or click @kbd{Mouse-2} to edit

@node Other Buffers
@subsubsection Other Buffers

@table @asis
@item Input/Output Buffer
If the variable @code{gdb-use-inferior-io-buffer} is non-@code{nil},
the executable program that is being debugged takes its input and
displays its output here.  Some of the commands from shell mode are
available here.  @xref{Shell Mode}.

@item Locals Buffer
The locals buffer displays the values of local variables of the

current thread (@code{gdb-threads-select}) and display the associated
source in the source buffer.  Alternatively, click @kbd{Mouse-2} to
make the selected thread become the current one.

@end table

@node Executing Lisp
@section Executing Lisp Expressions

  Emacs has several different major modes for Lisp and Scheme.  They are