comparison man/building.texi @ 71253:72b7de925c8d

(Watch Expressions): Move node to end. (GDB Graphical Interface): Move description of clicks in fringe... (GDB commands in the Fringe): ...to here. New node.

71252:de5774b55f7f

  By default, the command @code{gdb} starts GDB using a graphical
interface, using Emacs windows for display program state information.
In effect, this makes Emacs into an IDE (interactive development
environment).  With it, you do not need to use textual GDB commands;
you can control the debugging session with the mouse.

@c @findex gdb-mouse-set-clear-breakpoint
@c @findex gdb-mouse-toggle-breakpoint
  For example, you can click @kbd{Mouse-1} in the fringe or display
margin of a source buffer to set a breakpoint there and, on a
graphical display, a red bullet will appear on that line.  If a
breakpoint already exists on that line, the same click will remove it.
You can also enable or disable a breakpoint by clicking @kbd{C-Mouse-1}
on the bullet.  If you drag the debugger arrow in the fringe with
@kbd{Mouse-1} (@code{gdb-mouse-until}), execution will continue to the
line where you release the button, provided it is still in the same
frame.  Alternatively, you can click @kbd{Mouse-3} at some point in
the fringe of this buffer and execution will advance to there.

  This mode requires telling GDB that its ``screen size'' is
unlimited, so it sets the height and width accordingly.  For correct
operation you must not change these values during the GDB session.

@menu
* GDB User Interface 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 GDB User Interface Buffers:: Input/output, locals, registers,
                                assembler, threads and memory buffers.
@end menu

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

frame and type @key{RET} (@code{gdb-frames-select}), or click
@kbd{Mouse-2} on a stack frame.  If the locals buffer is visible,
selecting a stack frame updates it to display the local variables of
the new frame.

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

@findex gud-watch
@kindex C-x C-a C-w @r{(GUD)}
  If you want to see how a variable changes each time your program
stops, move point into the variable name and click on the watch icon
in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}.  If you
specify a prefix argument, you can enter the variable name in the
minibuffer.

  Each watch expression is displayed in the speedbar.  Complex data
types, such as arrays, structures and unions are represented in a tree
format.  Leaves and simple data types show the name of the expression
and its value and, when the speedbar frame is selected, display the
type as a tooltip.  Higher levels show the name, type and address
value for pointers and just the name and type otherwise.  Root expressions
also display the frame address as a tooltip to help identify the frame
in which they were defined.

  To expand or contract a complex data type, click @kbd{Mouse-2}
on the tag to the left of the expression.

@kindex D @r{(GDB speedbar)}
@findex gdb-var-delete
  To delete a complex watch expression, move point to the root
expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}).

@kindex RET @r{(GDB speedbar)}
@findex gdb-edit-value
  To edit a variable with a simple data type, or a simple element of a
complex data type, move point there in the speedbar and type @key{RET}
(@code{gdb-edit-value}).  Or you can click @kbd{Mouse-2} on a value to
edit it.  Either way, this reads the new value using the minibuffer.

@vindex gdb-show-changed-values
  If you set the variable @code{gdb-show-changed-values} to
non-@code{nil} (the default value), Emacs uses
@code{font-lock-warning-face} to highlight values that have recently
changed and @code{shadow} face to make variables which have gone out of
scope less noticeable.  When a variable goes out of scope you can't
edit its value.

@vindex gdb-use-colon-colon-notation
  If the variable @code{gdb-use-colon-colon-notation} is
non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}}
format.  This allows the user to display watch expressions which share
the same variable name.  The default value is @code{nil}.

@vindex gdb-speedbar-auto-raise
To automatically raise the speedbar every time the display of watch
expressions updates, set @code{gdb-speedbar-auto-raise} to
non-@code{nil}.  This can be useful if you are debugging with a full
screen Emacs frame.

@node Other GDB User Interface Buffers
@subsubsection Other Buffers

@table @asis
@item Input/Output Buffer

(@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}).
Click @kbd{Mouse-1} on the appropriate part of the header line to
change the starting address or number of data items that the buffer
displays.  Click @kbd{Mouse-3} on the header line to select the
display format or unit size for these data items.

@end table

@node Executing Lisp
@section Executing Lisp Expressions

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

71253:72b7de925c8d

  By default, the command @code{gdb} starts GDB using a graphical
interface, using Emacs windows for display program state information.
In effect, this makes Emacs into an IDE (interactive development
environment).  With it, you do not need to use textual GDB commands;
you can control the debugging session with the mouse.  For example,
you can click in the fringe of a source buffer to set a breakpoint
there, or on a stack frame in the stack buffer to select that frame.

  This mode requires telling GDB that its ``screen size'' is
unlimited, so it sets the height and width accordingly.  For correct
operation you must not change these values during the GDB session.

@menu
* GDB User Interface Layout::   Control the number of displayed buffers.
* Breakpoints Buffer::          A breakpoint control panel.
* Stack Buffer::                Select a frame from the call stack.
* Other GDB User Interface Buffers:: Input/output, locals, registers,
                                assembler, threads and memory buffers.
* GDB commands in the Fringe::  Use the mouse in the fringe/margin to
                                control your program.
* Watch Expressions::           Monitor variable values in the speedbar.
@end menu

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

frame and type @key{RET} (@code{gdb-frames-select}), or click
@kbd{Mouse-2} on a stack frame.  If the locals buffer is visible,
selecting a stack frame updates it to display the local variables of
the new frame.

@node Other GDB User Interface Buffers
@subsubsection Other Buffers

@table @asis
@item Input/Output Buffer

(@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}).
Click @kbd{Mouse-1} on the appropriate part of the header line to
change the starting address or number of data items that the buffer
displays.  Click @kbd{Mouse-3} on the header line to select the
display format or unit size for these data items.
@end table

@node GDB commands in the Fringe
@subsubsection GDB commands in the Fringe
@cindex GDB commands in the Fringe

@c @findex gdb-mouse-set-clear-breakpoint
@c @findex gdb-mouse-toggle-breakpoint
Many GDB commands can be entered using keybindings or the tool bar but
sometimes it is quicker to use the fringe.  These commands either
manipulate breakpoints or control program execution.  When there is no
fringe, you can use the margin but this is only present when the
source file already has a breakpoint.

You can click @kbd{Mouse-1} in the fringe or display margin of a
source buffer to set a breakpoint there and, on a graphical display, a
red bullet will appear on that line.  If a breakpoint already exists
on that line, the same click will remove it.  You can also enable or
disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet.

If you drag the debugger arrow in the fringe with @kbd{Mouse-1}
(@code{gdb-mouse-until}), execution will continue to the line where
you release the button, provided it is still in the same frame.
Alternatively, you can click @kbd{Mouse-3} at some point in the fringe
of this buffer and execution will advance to there.  A similar command
(@code{gdb-mouse-jump}) allows you to jump to a source line without
executing the intermediate lines by clicking @kbd{C-Mouse-3}.  This
command allows you to go backwards which can be useful for running
through code that has already executed, in order to examine its
execution in more detail.

@table @kbd
@item Mouse-1
Set or clear a breakpoint.

@item C-Mouse-1
Enable or disable a breakpoint.

@item Mouse-3
Continue execution to here.

@item C-Mouse-3
Jump to here.
@end table

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

@findex gud-watch
@kindex C-x C-a C-w @r{(GUD)}
  If you want to see how a variable changes each time your program
stops, move point into the variable name and click on the watch icon
in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}.  If you
specify a prefix argument, you can enter the variable name in the
minibuffer.

  Each watch expression is displayed in the speedbar.  Complex data
types, such as arrays, structures and unions are represented in a tree
format.  Leaves and simple data types show the name of the expression
and its value and, when the speedbar frame is selected, display the
type as a tooltip.  Higher levels show the name, type and address
value for pointers and just the name and type otherwise.  Root expressions
also display the frame address as a tooltip to help identify the frame
in which they were defined.

  To expand or contract a complex data type, click @kbd{Mouse-2}
on the tag to the left of the expression.

@kindex D @r{(GDB speedbar)}
@findex gdb-var-delete
  To delete a complex watch expression, move point to the root
expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}).

@kindex RET @r{(GDB speedbar)}
@findex gdb-edit-value
  To edit a variable with a simple data type, or a simple element of a
complex data type, move point there in the speedbar and type @key{RET}
(@code{gdb-edit-value}).  Or you can click @kbd{Mouse-2} on a value to
edit it.  Either way, this reads the new value using the minibuffer.

@vindex gdb-show-changed-values
  If you set the variable @code{gdb-show-changed-values} to
non-@code{nil} (the default value), Emacs uses
@code{font-lock-warning-face} to highlight values that have recently
changed and @code{shadow} face to make variables which have gone out of
scope less noticeable.  When a variable goes out of scope you can't
edit its value.

@vindex gdb-use-colon-colon-notation
  If the variable @code{gdb-use-colon-colon-notation} is
non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}}
format.  This allows the user to display watch expressions which share
the same variable name.  The default value is @code{nil}.

@vindex gdb-speedbar-auto-raise
To automatically raise the speedbar every time the display of watch
expressions updates, set @code{gdb-speedbar-auto-raise} to
non-@code{nil}.  This can be useful if you are debugging with a full
screen Emacs frame.

@node Executing Lisp
@section Executing Lisp Expressions

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