[Emacs-diffs] Changes to emacs/man/building.texi [lexbind]

[Miles Bader]

Index: emacs/man/building.texi
diff -c emacs/man/building.texi:1.23.2.1 emacs/man/building.texi:1.23.2.2
*** emacs/man/building.texi:1.23.2.1    Fri Apr  4 01:20:46 2003
--- emacs/man/building.texi     Tue Oct 14 18:56:21 2003
***************
*** 73,79 ****
  last time you did @kbd{M-x compile}.  If you type just @key{RET}, the
  same command line is used again.  For the first @kbd{M-x compile}, the
  default is @samp{make -k}, which is correct most of the time for
! nontrivial programs.  (@xref{Make,, Make, make, GNU Make Manual}.)
  The default compilation command comes from the variable
  @code{compile-command}; if the appropriate compilation command for a
  file is something other than @samp{make -k}, it can be useful for the
--- 73,79 ----
  last time you did @kbd{M-x compile}.  If you type just @key{RET}, the
  same command line is used again.  For the first @kbd{M-x compile}, the
  default is @samp{make -k}, which is correct most of the time for
! nontrivial programs.  (@xref{Top,, Make, make, GNU Make Manual}.)
  The default compilation command comes from the variable
  @code{compile-command}; if the appropriate compilation command for a
  file is something other than @samp{make -k}, it can be useful for the
***************
*** 102,123 ****
  follow output as it comes in.
  
  @findex kill-compilation
!   To kill the compilation process, do @kbd{M-x kill-compilation}.  When
! the compiler process terminates, the mode line of the
! @samp{*compilation*} buffer changes to say @samp{signal} instead of
! @samp{run}.  Starting a new compilation also kills any running
! compilation, as only one can exist at any time.  However, @kbd{M-x
! compile} asks for confirmation before actually killing a compilation
! that is running.
  
  @findex recompile
    To rerun the last compilation with the same command, type @kbd{M-x
  recompile}.  This automatically reuses the compilation command from the
  last invocation of @kbd{M-x compile}.
  
!   Emacs does not expect a compiler to launch asynchronous
  subprocesses; if it does, and they keep running after the main
! compiler process has terminated, their output may not arrive in Emacs.
  
  @node Grep Searching
  @section Searching with Grep under Emacs
--- 102,132 ----
  follow output as it comes in.
  
  @findex kill-compilation
!   When the compiler process terminates, for whatever reason, the mode
! line of the @samp{*compilation*} buffer changes to say @samp{signal}
! instead of @samp{run}.  Starting a new compilation also kills any
! running compilation, as only one can exist at any time.  However,
! @kbd{M-x compile} asks for confirmation before actually killing a
! compilation that is running.  You can also kill the compilation
! process with @kbd{M-x kill-compilation}.
  
  @findex recompile
    To rerun the last compilation with the same command, type @kbd{M-x
  recompile}.  This automatically reuses the compilation command from the
  last invocation of @kbd{M-x compile}.
  
!   Emacs does not expect a compiler process to launch asynchronous
  subprocesses; if it does, and they keep running after the main
! compiler process has terminated, Emacs may kill them or their output
! may not arrive in Emacs.  To avoid this problem, make the main process
! wait for its subprocesses to finish.  In a shell script, you can do this
! using @samp{$!} and @samp{wait}, like this:
! 
! @example
! (sleep 10; echo 2nd)& pid=$!  # @r{Record pid of subprocess}
! echo first message
! wait $pid                     # @r{Wait for subprocess}
! @end example
  
  @node Grep Searching
  @section Searching with Grep under Emacs
***************
*** 288,293 ****
--- 297,305 ----
  * Commands of GUD::   Key bindings for common commands.
  * GUD Customization:: Defining your own commands for GUD.
  * GUD Tooltips::        Showing variable values by pointing with the mouse.
+ * GDB Graphical Interface::  An enhanced mode that uses GDB features to
+                         implement a graphical debugging environment through
+                         Emacs.
  @end menu
  
  @node Starting GUD
***************
*** 303,308 ****
--- 315,324 ----
  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}.
+ 
  @item M-x dbx @key{RET} @var{file} @key{RET}
  @findex dbx
  Similar, but run DBX instead of GDB.
***************
*** 478,483 ****
--- 494,514 ----
    If you are using GDB, these additional key bindings are available:
  
  @table @kbd
+ @item C-c C-r
+ @kindex C-c C-r @r{(GUD)}
+ @itemx C-x C-a C-r
+ @findex gud-run
+ Start execution of the program (@code{gud-run}).
+ 
+ @item C-c C-u
+ @kindex C-c C-u @r{(GUD)}
+ @itemx C-x C-a C-u
+ @findex gud-until
+ Continue execution to the current line. The program will run until
+ it hits a breakpoint, terminates, gets a signal that the debugger is
+ checking for, or reaches the line on which the cursor currently sits
+ (@code{gud-until}).
+ 
  @item @key{TAB}
  @kindex TAB @r{(GUD)}
  @findex gud-gdb-complete-command
***************
*** 587,592 ****
--- 618,805 ----
  the mouse in the GUD buffer or in source buffers with major modes in the
  customizable list @code{tooltip-gud-modes}.
  
+ @node GDB Graphical Interface
+ @subsection GDB Graphical Interface
+ 
+ @findex gdba
+ The command @code{gdba} starts GDB using a graphical interface where
+ you view and control the program's data using Emacs windows.  You can
+ 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. 
+ * Data Display::         Display and update expressions in their own buffer.
+ * Display Buffer::       Control the displayed expressions.
+ * 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 
+ (@pxref{Breakpoints,,, gdb, The GNU debugger}).  It has three special
+ commands:
+ 
+ @table @kbd
+ @item @key{SPC} 
+ @kindex SPC @r{(GDB breakpoints buffer)}
+ @findex gdb-toggle-breakpoint
+ Enable/disable the breakpoint at the current line
+ (@code{gdb-toggle-breakpoint}).  On a graphical display, this changes
+ the color of a bullet in the margin of the source buffer at the
+ relevant line.  This is red when the breakpoint is enabled and grey
+ when it is disabled.  Text-only terminals correspondingly display
+ a @samp{B} or @samp{b}.
+ 
+ @item @kbd{d}
+ @kindex d @r{(GDB breakpoints buffer)}
+ @findex gdb-delete-breakpoint
+ Delete the breakpoint at the current line (@code{gdb-delete-breakpoint}).
+ 
+ @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 Data Display
+ @subsubsection Data Display
+ @cindex displaying expressions in GDB
+ 
+ If you want to see how a variable changes each time your program stops
+ then place the cursor over the variable name and click on the display
+ icon in the toolbar (@code{gud-display}).
+ 
+ Each displayed expression has its own frame on a graphical display and
+ its own buffer on a text-only terminal.  Arrays and structures have
+ their own display formats.  To display an array as a slice, at the top
+ of the display window, click @kbd{Mouse-2} on the array index that you
+ want to restrict and you will be prompted in the mini-buffer for a
+ start and a stop value. Click @kbd{Mouse-2} on a pointer to
+ dereference it in the same frame/buffer.  Click @kbd{S-Mouse-2} there
+ to do the same thing but in a new frame/buffer.  There are two special
+ commands for these buffers:
+ 
+ @table @kbd
+ @item @kbd{v}
+ @kindex v @r{(GDB data buffer)}
+ @findex gdb-array-visualise
+ Visualise an array using the graph program from plotutils if this is
+ installed. This only works for one dimensional arrays
+ (@code{gdb-array-visualise}).
+ 
+ @item @kbd{q}
+ @kindex q @r{(GDB data buffer)}
+ @findex gdb-delete-expression
+ Delete the displayed expression and the associated frame
+ (@code{gdb-delete-expression}).
+ @end table
+ 
+ @node Display Buffer
+ @subsubsection Display Buffer
+ 
+ The display buffer shows the list of displayed expressions
+ (@pxref{Auto Display,,, gdb, The GNU debugger}).  As with the
+ breakpoints, you can enable/disable or delete the displayed
+ expressions:
+ 
+ @table @kbd
+ @item @key{SPC}
+ @kindex SPC @r{(GDB display buffer)}
+ @findex gdb-toggle-display
+ Enable/disable the display at the current line
+ (@code{gdb-toggle-display}).
+ 
+ @item @kbd{d}
+ @kindex d @r{(GDB display buffer)}
+ @findex gdb-delete-display
+ Delete the display at the current line (@code{gdb-delete-display}).
+ @end table
+ 
+ @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 frame for simple data types (@pxref{Frame Info,,, gdb, The GNU
+ debugger}).
+ 
+ Arrays and structures display their type only.  You must display them
+ separately to examine their values.  @ref{Data Display}.
+ 
+ @item Registers Buffer
+ The registers buffer displays the values held by the registers
+ (@pxref{Registers,,, gdb, The GNU debugger}).
+ 
+ @item Assembler Buffer
+ The assembler buffer displays the current frame as machine code.  An
+ overlay arrow points to the current instruction and you can set and
+ remove breakpoints as with the source buffer.  Breakpoints also
+ appear in the margin.
+ @end table
+ 
+ @node Layout
+ @subsubsection Layout
+ @cindex GDB User Interface layout
+ You may choose to display the additional buffers described previously
+ 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
+ address@hidden or @code{M-x
+ address@hidden respectively, where @var{buffertype}
+ is the relevant buffer type e.g breakpoints.
+ 
+ @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}.
+ 
  @node Executing Lisp
  @section Executing Lisp Expressions
  
***************
*** 875,877 ****
--- 1088,1094 ----
  the function definition that point is in, but the way of doing so is
  different according to where the relevant Lisp environment is found.
  @xref{Executing Lisp}.
+ 
+ @ignore
+    arch-tag: 9c3c2f71-b332-4144-8500-3ff9945a50ed
+ @end ignore