Mercurial > emacs
comparison doc/emacs/building.texi @ 107550:2931d193b6c2
Restore GDB/MI fuctionality removed by r99212:
added:
lisp/progmodes/gdb-mi.el
removed:
lisp/progmodes/gdb-ui.el
modified:
doc/emacs/building.texi
doc/emacs/emacs.texi
etc/NEWS
lisp/Makefile.in
lisp/progmodes/gud.el
author | Nick Roberts <nickrob@snap.net.nz> |
---|---|
date | Sun, 28 Mar 2010 02:27:43 +1300 |
parents | 1d1d5d9bd884 |
children | 973b5bc5fcfe |
comparison
equal
deleted
inserted
replaced
107549:0be378fcb83b | 107550:2931d193b6c2 |
---|---|
851 To run GDB in text command mode, like the other debuggers in Emacs, | 851 To run GDB in text command mode, like the other debuggers in Emacs, |
852 use @kbd{M-x gud-gdb}. You need to use text command mode to debug | 852 use @kbd{M-x gud-gdb}. You need to use text command mode to debug |
853 multiple programs within one Emacs session. | 853 multiple programs within one Emacs session. |
854 | 854 |
855 @menu | 855 @menu |
856 * GDB-UI Layout:: Control the number of displayed buffers. | 856 * GDB User Interface Layout:: Control the number of displayed buffers. |
857 * Source Buffers:: Use the mouse in the fringe/margin to | 857 * Source Buffers:: Use the mouse in the fringe/margin to |
858 control your program. | 858 control your program. |
859 * Breakpoints Buffer:: A breakpoint control panel. | 859 * Breakpoints Buffer:: A breakpoint control panel. |
860 * Threads Buffer:: Displays your threads. | |
860 * Stack Buffer:: Select a frame from the call stack. | 861 * Stack Buffer:: Select a frame from the call stack. |
861 * Other GDB-UI Buffers:: Input/output, locals, registers, | 862 * Other GDB Buffers:: Input/output, locals, registers, |
862 assembler, threads and memory buffers. | 863 assembler, threads and memory buffers. |
863 * Watch Expressions:: Monitor variable values in the speedbar. | 864 * Watch Expressions:: Monitor variable values in the speedbar. |
864 * Reverse Debugging:: Execute and reverse debug your program. | 865 * Multithreaded Debugging:: Debugging programs with several threads. |
865 @end menu | 866 @end menu |
866 | 867 |
867 @node GDB-UI Layout | 868 @node GDB User Interface Layout |
868 @subsubsection GDB User Interface Layout | 869 @subsubsection GDB User Interface Layout |
869 @cindex GDB User Interface layout | 870 @cindex GDB User Interface layout |
870 | 871 |
871 @vindex gdb-many-windows | 872 @vindex gdb-many-windows |
872 If the variable @code{gdb-many-windows} is @code{nil} (the default | 873 If the variable @code{gdb-many-windows} is @code{nil} (the default |
1012 @item Mouse-2 | 1013 @item Mouse-2 |
1013 @kindex Mouse-2 @r{(GDB breakpoints buffer)} | 1014 @kindex Mouse-2 @r{(GDB breakpoints buffer)} |
1014 Visit the source line for the breakpoint you click on. | 1015 Visit the source line for the breakpoint you click on. |
1015 @end table | 1016 @end table |
1016 | 1017 |
1018 @vindex gdb-show-threads-by-default | |
1017 When @code{gdb-many-windows} is non-@code{nil}, the breakpoints buffer | 1019 When @code{gdb-many-windows} is non-@code{nil}, the breakpoints buffer |
1018 shares its window with the threads buffer. To switch from one to the | 1020 shares its window with the threads buffer. To switch from one to the |
1019 other click with @kbd{Mouse-1} on the relevant button in the header | 1021 other click with @kbd{Mouse-1} on the relevant button in the header |
1020 line. | 1022 line. If @code{gdb-show-threads-by-default} is non-@code{nil}, the |
1023 threads buffer, rather than the breakpoints buffer, is shown at start | |
1024 up. | |
1025 | |
1026 @node Threads Buffer | |
1027 @subsubsection Threads Buffer | |
1028 | |
1029 @findex gdb-select-thread | |
1030 The threads buffer displays a summary of all threads currently in your | |
1031 program (@pxref{Threads, Threads, Debugging programs with multiple | |
1032 threads, gdb, The GNU debugger}). Move point to any thread in the list | |
1033 and press @key{RET} to select it (@code{gdb-select-thread}) and | |
1034 display the associated source in the primary source buffer. | |
1035 Alternatively, click @kbd{Mouse-2} on a thread to select it. Contents | |
1036 of all GDB buffers are updated whenever you select a thread. | |
1037 | |
1038 You can customize variables under @code{gdb-buffers} group to select | |
1039 fields included in threads buffer. | |
1040 | |
1041 @table @code | |
1042 @item gdb-thread-buffer-verbose-names | |
1043 @vindex gdb-thread-buffer-verbose-names | |
1044 Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)} in | |
1045 threads buffer. | |
1046 | |
1047 @item gdb-thread-buffer-arguments | |
1048 @vindex gdb-thread-buffer-arguments | |
1049 Show arguments of thread top frames in threads buffer. | |
1050 | |
1051 @item gdb-thread-buffer-locations | |
1052 @vindex gdb-thread-buffer-locations | |
1053 Show file information or library names in threads buffer. | |
1054 | |
1055 @item gdb-thread-buffer-addresses | |
1056 @vindex gdb-thread-buffer-addresses | |
1057 Show addresses for thread frames in threads buffer. | |
1058 @end table | |
1059 | |
1060 It’s possible to observe information for several threads | |
1061 simultaneously (in addition to buffers which show information for | |
1062 currently selected thread) using the following keys from the threads | |
1063 buffer. | |
1064 | |
1065 @table @kbd | |
1066 @item d | |
1067 @kindex d @r{(GDB threads buffer)} | |
1068 @findex gdb-display-disassembly-for-thread | |
1069 Display disassembly buffer for the thread at current line. | |
1070 (@code{gdb-display-disassembly-for-thread}) | |
1071 | |
1072 @item f | |
1073 @kindex f @r{(GDB threads buffer)} | |
1074 @findex gdb-display-stack-for-thread | |
1075 Display stack buffer for the thread at current line. | |
1076 (@code{gdb-display-stack-for-thread}). | |
1077 | |
1078 @item l | |
1079 @kindex l @r{(GDB threads buffer)} | |
1080 @findex gdb-display-locals-for-thread | |
1081 Display locals buffer for the thread at current line. | |
1082 (@code{gdb-display-locals-for-thread}). | |
1083 | |
1084 @item r | |
1085 @kindex r @r{(GDB threads buffer)} | |
1086 @findex gdb-display-registers-for-thread | |
1087 Display registers buffer for the thread at current line. | |
1088 (@code{gdb-display-registers-for-thread}). | |
1089 @end table | |
1090 | |
1091 Pressing their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and | |
1092 @kbd{R} displays the corresponding buffer in a new frame. | |
1093 | |
1094 When you create a buffer showing information about some specific | |
1095 thread, it becomes bound to that thread and keeps showing actual | |
1096 information while you debug your program. Every GDB buffer contains a | |
1097 number of thread it shows information for in its mode name. Thread | |
1098 number is also included in the buffer name of bound buffers to prevent | |
1099 buffer names clashing. | |
1100 | |
1101 Further commands are available in the threads buffer which depend on the | |
1102 mode of GDB that is used for controlling execution of your program. | |
1103 (@pxref{Multithreaded Debugging, Stopping and Starting Multi-threaded Programs}). | |
1021 | 1104 |
1022 @node Stack Buffer | 1105 @node Stack Buffer |
1023 @subsubsection Stack Buffer | 1106 @subsubsection Stack Buffer |
1024 | 1107 |
1025 The stack buffer displays a @dfn{call stack}, with one line for each | 1108 The stack buffer displays a @dfn{call stack}, with one line for each |
1033 that stack frame and type @key{RET} (@code{gdb-frames-select}), or click | 1116 that stack frame and type @key{RET} (@code{gdb-frames-select}), or click |
1034 @kbd{Mouse-2} on a stack frame. If the locals buffer is visible, | 1117 @kbd{Mouse-2} on a stack frame. If the locals buffer is visible, |
1035 selecting a stack frame updates it to display the local variables of the | 1118 selecting a stack frame updates it to display the local variables of the |
1036 new frame. | 1119 new frame. |
1037 | 1120 |
1038 @node Other GDB-UI Buffers | 1121 @node Other GDB Buffers |
1039 @subsubsection Other Buffers | 1122 @subsubsection Other Buffers |
1040 | 1123 |
1041 @table @asis | 1124 @table @asis |
1042 @item Input/Output Buffer | 1125 @item Input/Output Buffer |
1043 @vindex gdb-use-separate-io-buffer | 1126 @vindex gdb-use-separate-io-buffer |
1077 The assembler buffer displays the current frame as machine code. An | 1160 The assembler buffer displays the current frame as machine code. An |
1078 arrow points to the current instruction, and you can set and remove | 1161 arrow points to the current instruction, and you can set and remove |
1079 breakpoints as in a source buffer. Breakpoint icons also appear in | 1162 breakpoints as in a source buffer. Breakpoint icons also appear in |
1080 the fringe or margin. | 1163 the fringe or margin. |
1081 | 1164 |
1082 @item Threads Buffer | |
1083 @findex gdb-threads-select | |
1084 The threads buffer displays a summary of all threads currently in your | |
1085 program (@pxref{Threads, Threads, Debugging programs with multiple | |
1086 threads, gdb, The GNU debugger}). Move point to any thread in the | |
1087 list and press @key{RET} to select it (@code{gdb-threads-select}) and | |
1088 display the associated source in the primary source buffer. | |
1089 Alternatively, click @kbd{Mouse-2} on a thread to select it. If the | |
1090 locals buffer is visible, its contents update to display the variables | |
1091 that are local in the new thread. | |
1092 | |
1093 When there is more than one main thread and the threads buffer is | |
1094 present, Emacs displays the selected thread number in the mode line of | |
1095 many of the GDB-UI Buffers. | |
1096 | |
1097 @item Memory Buffer | 1165 @item Memory Buffer |
1098 The memory buffer lets you examine sections of program memory | 1166 The memory buffer lets you examine sections of program memory |
1099 (@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}). | 1167 (@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}). |
1100 Click @kbd{Mouse-1} on the appropriate part of the header line to | 1168 Click @kbd{Mouse-1} on the appropriate part of the header line to |
1101 change the starting address or number of data items that the buffer | 1169 change the starting address or number of data items that the buffer |
1102 displays. Alternatively, use @kbd{S} or @kbd{N} respectively. Click | 1170 displays. Alternatively, use @kbd{S} or @kbd{N} respectively. Click |
1103 @kbd{Mouse-3} on the header line to select the display format or unit | 1171 @kbd{Mouse-3} on the header line to select the display format or unit |
1104 size for these data items. | 1172 size for these data items. |
1105 @end table | 1173 @end table |
1106 | 1174 |
1107 When @code{gdb-many-windows} is non-@code{nil}, the threads buffer | 1175 When @code{gdb-many-windows} is non-@code{nil}, the locals buffer |
1108 shares its window with the breakpoints buffer, and the locals buffer | 1176 shares its window with the registers buffer, just like breakpoints |
1109 with the registers buffer. To switch from one to the other click with | 1177 and threads buffers. To switch from one to the other click with |
1110 @kbd{Mouse-1} on the relevant button in the header line. | 1178 @kbd{Mouse-1} on the relevant button in the header line. |
1111 | 1179 |
1112 @node Watch Expressions | 1180 @node Watch Expressions |
1113 @subsubsection Watch Expressions | 1181 @subsubsection Watch Expressions |
1114 @cindex Watching expressions in GDB | 1182 @cindex Watching expressions in GDB |
1173 To automatically raise the speedbar every time the display of watch | 1241 To automatically raise the speedbar every time the display of watch |
1174 expressions updates, set @code{gdb-speedbar-auto-raise} to | 1242 expressions updates, set @code{gdb-speedbar-auto-raise} to |
1175 non-@code{nil}. This can be useful if you are debugging with a full | 1243 non-@code{nil}. This can be useful if you are debugging with a full |
1176 screen Emacs frame. | 1244 screen Emacs frame. |
1177 | 1245 |
1178 @node Reverse Debugging | 1246 @node Multithreaded Debugging |
1179 @subsubsection Reverse Debugging | 1247 @subsubsection Stopping and Starting Multi-threaded Programs |
1180 | 1248 @cindex Multithreaded debugging in GDB |
1181 The GDB tool bar shares many buttons with the other GUD debuggers | 1249 |
1182 for tasks like stepping and printing expressions. It also has a | 1250 @subsubheading All-stop Debugging |
1183 further set of buttons that allow reverse debugging (@pxref{Process | 1251 |
1184 Record and Replay, , ,gdb, The GNU debugger}). This is useful when it | 1252 In all-stop mode, whenever your program stops, @emph{all} threads of |
1185 takes a long time to reproduce the conditions where your program fails | 1253 execution stop. Likewise, whenever you restart the program, all |
1186 or for transient problems, like race conditions in multi-threaded | 1254 threads start executing. @xref{All-Stop Mode, , All-Stop Mode, gdb, |
1187 programs, where a failure might otherwise be hard to reproduce. | 1255 The GNU debugger}. You can enable this behaviour in Emacs by setting |
1188 | 1256 @code{gdb-non-stop-setting} to @code{nil} before starting a debugging |
1189 To use reverse debugging, set a breakpoint slightly before the | 1257 session. |
1190 location of interest and run your program to that point. Enable | 1258 |
1191 process recording by clicking on the record button. At this point, a | 1259 @subsubheading Non-stop Debugging |
1192 new set of buttons appear. These buttons allow program execution in | 1260 @cindex Non-stop debugging in GDB |
1193 the reverse direction. Run your program over the code where the | 1261 |
1194 problem occurs, and then use the new set of buttons to retrace your | 1262 For some multi-threaded targets, GDB supports a further mode of |
1195 steps, examine values, and analyze the problem. When analysis is | 1263 operation in which you can examine stopped program threads in the |
1196 complete, turn off process recording by clicking on the record button | 1264 debugger while other threads continue to execute freely. |
1197 again. | 1265 @xref{Non-Stop Mode, , Non-Stop Mode, gdb, The GNU debugger}. |
1266 This is referred to as @dfn{non-stop} mode. | |
1267 | |
1268 Versions of GDB prior to 7.0 do not support non-stop mode and it does | |
1269 not work on all targets. In such cases, Emacs uses all-stop mode | |
1270 regardless of the value of @code{gdb-non-stop-setting}. | |
1271 | |
1272 @vindex gdb-non-stop-setting | |
1273 If the variable @code{gdb-non-stop-setting} is non-@code{nil} (the | |
1274 default value), Emacs tries to start GDB in non-stop mode. Note that | |
1275 GDB debugging session needs to be restarted for change of this setting | |
1276 to take effect. | |
1277 | |
1278 @vindex gdb-switch-when-another-stopped | |
1279 When a thread stops in non-stop mode, Emacs automatically switches to | |
1280 that thread. It may be undesirable to allow switching of current | |
1281 thread when some other stopped thread is already selected. Set | |
1282 @code{gdb-switch-when-another-stopped} to @code{nil} to prevent this. | |
1283 | |
1284 @vindex gdb-switch-reasons | |
1285 Emacs can decide whether or not to switch to the stopped thread | |
1286 depending on the reason which caused the stop. Customize | |
1287 @code{gdb-switch-reasons} to select stop reasons which make Emacs | |
1288 switch thread. | |
1289 | |
1290 @vindex gdb-stopped-hooks | |
1291 The variable @code{gdb-stopped-hooks} allows you to execute your | |
1292 functions whenever some thread stops. | |
1293 | |
1294 In non-stop mode, you can switch between different modes for GUD | |
1295 execution control commands. | |
1296 | |
1297 @vindex gdb-gud-control-all-threads | |
1298 @table @dfn | |
1299 @item Non-stop/A | |
1300 | |
1301 When @code{gdb-gud-control-all-threads} is @code{t} (the default | |
1302 value), interruption and continuation commands apply to all threads, | |
1303 so you can halt or continue all your threads with one command using | |
1304 @code{gud-stop-subjob} and @code{gud-cont}, respectively. The | |
1305 @samp{Go} button is shown on the toolbar when at least one thread is | |
1306 stopped, whereas @samp{Stop} button is shown when at least one thread | |
1307 is running. | |
1308 | |
1309 @item Non-stop/T | |
1310 | |
1311 When @code{gdb-gud-control-all-threads} is @code{nil}, only the | |
1312 current thread is stopped/continued. @samp{Go} and @samp{Stop} | |
1313 buttons on the GUD toolbar are shown depending on the state of current | |
1314 thread. | |
1315 @end table | |
1316 | |
1317 You can change the current value of @code{gdb-gud-control-all-threads} | |
1318 from the tool bar or from @samp{GUD->GDB-MI} menu. | |
1319 | |
1320 Stepping commands always apply to the current thread. | |
1321 | |
1322 @subsubheading Fine Thread Control | |
1323 | |
1324 In non-stop mode, you can interrupt/continue your threads without | |
1325 selecting them. Hitting @kbd{i} in threads buffer interrupts thread | |
1326 under point, @kbd{c} continues it, @kbd{s} steps through. More such | |
1327 commands may be added in the future. | |
1328 | |
1329 Combined with creating bound buffers for any thread, this allows you | |
1330 to change and track state of many threads in the same time. | |
1331 | |
1332 Note that when you interrupt a thread, it stops with @samp{signal | |
1333 received} reason. If that reason is included in your | |
1334 @code{gdb-switch-reasons} (it is by default), Emacs will switch to | |
1335 that thread. | |
1198 | 1336 |
1199 @node Executing Lisp | 1337 @node Executing Lisp |
1200 @section Executing Lisp Expressions | 1338 @section Executing Lisp Expressions |
1201 | 1339 |
1202 Emacs has several different major modes for Lisp and Scheme. They are | 1340 Emacs has several different major modes for Lisp and Scheme. They are |