From 0df6175ca5efd81a9558fa5034e952caff640cea Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Wed, 30 Dec 2009 05:39:47 -0500 Subject: [PATCH] * doc/emacs/building.texi: Re-apply 2009-12-29T07:15:34Z!nickrob@snap.net.nz, which was accidentally overwritten in the last change. --- doc/emacs/building.texi | 225 ++++++++-------------------------------- 1 file changed, 43 insertions(+), 182 deletions(-) diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index 619e1b0271d..d4209558e62 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -857,12 +857,11 @@ multiple programs within one Emacs session. * Source Buffers:: Use the mouse in the fringe/margin to control your program. * Breakpoints Buffer:: A breakpoint control panel. -* Threads Buffer:: Displays your threads. * Stack Buffer:: Select a frame from the call stack. * Other GDB-UI Buffers:: Input/output, locals, registers, assembler, threads and memory buffers. * Watch Expressions:: Monitor variable values in the speedbar. -* Multithreaded Debugging:: Debugging programs with several threads. +* Reverse Debugging:: Execute and reverse debug your program. @end menu @node GDB-UI Layout @@ -887,7 +886,7 @@ displays the following frame layout: |--------------------------------+--------------------------------+ | Primary Source buffer | I/O buffer for debugged pgm | |--------------------------------+--------------------------------+ -| Stack buffer | Breakpoints/Thread buffer | +| Stack buffer | Breakpoints/Threads buffer | +--------------------------------+--------------------------------+ @end group @end smallexample @@ -1015,92 +1014,10 @@ Visit the source line for the current breakpoint Visit the source line for the breakpoint you click on. @end table -@vindex gdb-show-threads-by-default When @code{gdb-many-windows} is non-@code{nil}, the breakpoints buffer shares its window with the threads buffer. To switch from one to the other click with @kbd{Mouse-1} on the relevant button in the header -line, or press @kbd{TAB} inside that buffer. If -@code{gdb-show-threads-by-default} is non-@code{nil}, the threads -buffer, rather than the breakpoints buffer, is shown at start up. - -@node Threads Buffer -@subsubsection Threads Buffer - -@findex gdb-select-thread -The threads buffer displays a summary of all threads currently in your -program (@pxref{Threads, Threads, Debugging programs with multiple -threads, gdb, The GNU debugger}). Move point to any thread in the list -and press @key{RET} to select it (@code{gdb-select-thread}) and -display the associated source in the primary source buffer. -Alternatively, click @kbd{Mouse-2} on a thread to select it. Contents -of all GDB buffers are updated whenever you select a thread. - - You can customize variables under @code{gdb-buffers} group to select -fields included in threads buffer. - -@table @code -@item gdb-thread-buffer-verbose-names -@vindex gdb-thread-buffer-verbose-names -Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)} in -threads buffer. - -@item gdb-thread-buffer-arguments -@vindex gdb-thread-buffer-arguments -Show arguments of thread top frames in threads buffer. - -@item gdb-thread-buffer-locations -@vindex gdb-thread-buffer-locations -Show file information or library names in threads buffer. - -@item gdb-thread-buffer-addresses -@vindex gdb-thread-buffer-addresses -Show addresses for thread frames in threads buffer. -@end table - - It’s possible to observe information for several threads -simultaneously (in addition to buffers which show information for -currently selected thread) using the following keys from the threads -buffer. - -@table @kbd -@item d -@kindex d @r{(GDB threads buffer)} -@findex gdb-display-disassembly-for-thread -Display disassembly buffer for the thread at current line. -(@code{gdb-display-disassembly-for-thread}) - -@item f -@kindex f @r{(GDB threads buffer)} -@findex gdb-display-stack-for-thread -Display stack buffer for the thread at current line. -(@code{gdb-display-stack-for-thread}). - -@item l -@kindex l @r{(GDB threads buffer)} -@findex gdb-display-locals-for-thread -Display locals buffer for the thread at current line. -(@code{gdb-display-locals-for-thread}). - -@item r -@kindex r @r{(GDB threads buffer)} -@findex gdb-display-registers-for-thread -Display registers buffer for the thread at current line. -(@code{gdb-display-registers-for-thread}). -@end table - -Pressing their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and -@kbd{R} displays the corresponding buffer in a new frame. - - When you create a buffer showing information about some specific -thread, it becomes bound to that thread and keeps showing actual -information while you debug your program. Every GDB buffer contains a -number of thread it shows information for in its mode name. Thread -number is also included in the buffer name of bound buffers to prevent -buffer names clashing. - -Further commands are available in the threads buffer which depend on the -mode of GDB that is used for controlling execution of your program. -(@pxref{Multithreaded Debugging, Stopping and Starting Multi-threaded Programs}). +line. @node Stack Buffer @subsubsection Stack Buffer @@ -1137,7 +1054,7 @@ as are the commands to send signals to the debugged program. @item Locals Buffer The locals buffer displays the values of local variables of the current frame for simple data types (@pxref{Frame Info, Frame Info, -Information on a frame, gdb, The GNU debugger}). Press @key{RET} or +Information on a frame, gdb, The GNU debugger}). Press @key{RET} or click @kbd{Mouse-2} on the value if you want to edit it. Arrays and structures display their type only. With GDB 6.4 or later, @@ -1156,12 +1073,27 @@ With GDB 6.4 or later, recently changed register values display with press @key{SPC} to toggle the display of floating point registers (@code{toggle-gdb-all-registers}). -@item Disassembly Buffer -The disassembly buffer displays the current frame as machine code. An +@item Assembler Buffer +The assembler buffer displays the current frame as machine code. An arrow points to the current instruction, and you can set and remove breakpoints as in a source buffer. Breakpoint icons also appear in the fringe or margin. +@item Threads Buffer +@findex gdb-threads-select +The threads buffer displays a summary of all threads currently in your +program (@pxref{Threads, Threads, Debugging programs with multiple +threads, gdb, The GNU debugger}). Move point to any thread in the +list and press @key{RET} to select it (@code{gdb-threads-select}) and +display the associated source in the primary source buffer. +Alternatively, click @kbd{Mouse-2} on a thread to select it. If the +locals buffer is visible, its contents update to display the variables +that are local in the new thread. + +When there is more than one main thread and the threads buffer is +present, Emacs displays the selected thread number in the mode line of +many of the GDB-UI Buffers. + @item Memory Buffer The memory buffer lets you examine sections of program memory (@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}). @@ -1174,9 +1106,8 @@ size for these data items. When @code{gdb-many-windows} is non-@code{nil}, the threads buffer shares its window with the breakpoints buffer, and the locals buffer -with the registers buffer. To switch from one to the other click with -@kbd{Mouse-1} on the relevant button in the header line or press -@kbd{TAB} inside the buffer. +with the registers buffer. To switch from one to the other click with +@kbd{Mouse-1} on the relevant button in the header line. @node Watch Expressions @subsubsection Watch Expressions @@ -1244,96 +1175,26 @@ 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 Multithreaded Debugging -@subsubsection Stopping and Starting Multi-threaded Programs -@cindex Multithreaded debugging in GDB - -@subsubheading All-stop Debugging - -In all-stop mode, whenever your program stops, @emph{all} threads of -execution stop. Likewise, whenever you restart the program, all -threads start executing. @xref{All-Stop Mode, , All-Stop Mode, gdb, -The GNU debugger}. You can enable this behaviour in Emacs by setting -@code{gdb-non-stop-setting} to @code{nil} before starting a debugging -session. - -@subsubheading Non-stop Debugging -@cindex Non-stop debugging in GDB - -For some multi-threaded targets, GDB supports a further mode of -operation in which you can examine stopped program threads in the -debugger while other threads continue to execute freely. -@xref{Non-Stop Mode, , Non-Stop Mode, gdb, The GNU debugger}. -This is referred to as @dfn{non-stop} mode. - -Versions of GDB prior to 7.0 do not support non-stop mode and it does -not work on all targets. In such cases, Emacs uses all-stop mode -regardless of the value of @code{gdb-non-stop-setting}. - -@vindex gdb-non-stop-setting -If the variable @code{gdb-non-stop-setting} is non-@code{nil} (the -default value), Emacs tries to start GDB in non-stop mode. Note that -GDB debugging session needs to be restarted for change of this setting -to take effect. - -@vindex gdb-switch-when-another-stopped -When a thread stops in non-stop mode, Emacs automatically switches to -that thread. It may be undesirable to allow switching of current -thread when some other stopped thread is already selected. Set -@code{gdb-switch-when-another-stopped} to @code{nil} to prevent this. - -@vindex gdb-switch-reasons -Emacs can decide whether or not to switch to the stopped thread -depending on the reason which caused the stop. Customize -@code{gdb-switch-reasons} to select stop reasons which make Emacs -switch thread. - -@vindex gdb-stopped-hooks -The variable @code{gdb-stopped-hooks} allows you to execute your -functions whenever some thread stops. - - In non-stop mode, you can switch between different modes for GUD -execution control commands. - -@vindex gdb-gud-control-all-threads -@table @dfn -@item Non-stop/A - -When @code{gdb-gud-control-all-threads} is @code{t} (the default -value), interruption and continuation commands apply to all threads, -so you can halt or continue all your threads with one command using -@code{gud-stop-subjob} and @code{gud-cont}, respectively. The -@samp{Go} button is shown on the toolbar when at least one thread is -stopped, whereas @samp{Stop} button is shown when at least one thread -is running. - -@item Non-stop/T - -When @code{gdb-gud-control-all-threads} is @code{nil}, only the -current thread is stopped/continued. @samp{Go} and @samp{Stop} -buttons on the GUD toolbar are shown depending on the state of current -thread. -@end table - -You can change the current value of @code{gdb-gud-control-all-threads} -from the tool bar or from @samp{GUD->GDB-MI} menu. - - Stepping commands always apply to the current thread. - -@subsubheading Fine Thread Control - - In non-stop mode, you can interrupt/continue your threads without -selecting them. Hitting @kbd{i} in threads buffer interrupts thread -under point, @kbd{c} continues it, @kbd{s} steps through. More such -commands may be added in the future. - -Combined with creating bound buffers for any thread, this allows you -to change and track state of many threads in the same time. - - Note that when you interrupt a thread, it stops with @samp{signal -received} reason. If that reason is included in your -@code{gdb-switch-reasons} (it is by default), Emacs will switch to -that thread. +@node Reverse Debugging +@subsubsection Reverse Debugging + + The GDB tool bar shares many buttons with the other GUD debuggers +for tasks like stepping and printing expressions. It also has a +further set of buttons that allow reverse debugging (@pxref{Process +Record and Replay, , ,gdb, The GNU debugger}). This is useful when it +takes a long time to reproduce the conditions where your program fails +or for transient problems, like race conditions in multi-threaded +programs, where a failure might otherwise be hard to reproduce. + +To use reverse debugging, set a breakpoint slightly before the +location of interest and run your program to that point. Enable +process recording by clicking on the record button. At this point, a +new set of buttons appear. These buttons allow program execution in +the reverse direction. Run your program over the code where the +problem occurs, and then use the new set of buttons to retrace your +steps, examine values, and analyze the problem. When analysis is +complete, turn off process recording by clicking on the record button +again. @node Executing Lisp @section Executing Lisp Expressions -- 2.39.2