/usr/share/doc/geany-plugin-scope/html/scope.html is in geany-plugin-scope 1.29+dfsg-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Scope</title>
<style type="text/css">
.tab { padding-left:1em; }
.tab1 { padding-left:1.5em; }
</style>
</head>
<body>
<center><h2>Scope</h2></center>
<center><h3>A relatively simple GDB front-end</h3></center>
<p align="right">"We are like dwarfs sitting on the shoulders of giants."<br>
-- Bernard of Chartres</p>
<hr>
<h3>Contents</h3>
<ul>
<li><a href="#about">About</a></li>
<li><a href="#requirements">Requirements</a></li>
<li><a href="#quick_start">Quick start</a></li>
<li><a href="#interface">Interface</a><ul>
<li><a href="#debug_menu">Debug menu</a><ul>
<li><a href="#set_program">Setup Program</a></li>
<li><a href="#run_continue">Run/Continue</a></li>
<li><a href="#goto_cursor">Run to cursor</a></li>
<li><a href="#goto_source">Run to source</a></li>
<li><a href="#step_into_over">Step Into / Step Over</a></li>
<li><a href="#terminate">Terminate</a></li>
<li><a href="#gdb_command">GDB Command</a>
<li><a href="#reset_markers">Reset Markers</a></li>
<li><a href="#cleanup_files">Cleanup Files</a></li>
</ul></li>
<li><a href="#debug_panel">Debug panel</a><ul>
<li><a href="#terminal">Program Terminal</a></li>
<li><a href="#threads">Threads</a></li>
<li><a href="#break">Breakpoints</a></li>
<li><a href="#stack">Stack</a></li>
<li><a href="#local">Locals</a></li>
<li><a href="#watch">Watches</a></li>
<li><a href="#memory">Memory</a></li>
<li><a href="#local_watch">Locals/Watches</a></li>
<li><a href="#console">Debug Console</a></li>
</ul></li>
<li><a href="#windows_console">Windows console</a></li>
<li>Side pages<ul>
<li><a href="#inspect">Inspect</a></li>
<li><a href="#register">Registers</a></li>
</ul></li>
</ul></li>
<li><a href="#preferences">Preferences</a></li>
<li><a href="#notes">Notes</a><ul>
<li><a href="#editing_values">Editing values</a></li>
<li><a href="#keeping_modes">Keeping modes</a></li>
<li><a href="#shared_memory">Shared memory</a></li>
<li><a href="#xos4_colors">Sample dark colors</a></li>
</ul></li>
<li><a href="#pre_faq">Pre-FAQ</a>
<li><a href="#bugs">Bugs</a></li>
<li><a href="#todo">TODO</a></li>
<li><a href="#not_todo">Not TODO</a></li>
<li><a href="#legal_info">Legal information</a><ul>
<li><a href="#license">License</a></li>
<li><a href="#copyright">Copyright</a></li>
</ul></li>
</ul>
<hr>
<h3><a name="about">About</a></h3>
<p>Scope is a graphical <a href="http://www.gnu.org/software/gdb">GDB</a> front-end with the
normal functions you would expect (stepping, breakpoints...), and a few notable features:</p>
<ul>
<li>The entire comminication between Scope and gdb is asynchronous.</li>
<li>You can enter any gdb command, at any time (of course, for the command to be executed,
gdb must be[come] available).</li>
<li>All gdb I/O (along with some other messages) is displayed in a terminal-like "Debug
Console".<br>
Whenever you find the GUI lacking, simply switch to that console and work directly with
gdb.</li>
<li>7-bit/Locale/UTF-8 support for values.</li>
</ul>
<p>Scope is currently implemented as a <a href="http://www.geany.org">Geany</a> plugin.</p>
<p>"Source files" refers to the file types supported by gdb: C/C++, D, Objective C,
Fortran, Java, Pascal, Assembler and Ada (ATM).</p>
<p>Trivial topics that require neither description nor comment are not included in this
document.</p>
<hr>
<h3><a name="requirements">Requirements</a></h3>
<p>Geany 1.25 or later and the respective libraries.</p>
<p>GDB 7.3 or later.</p>
<p>*nix only: VTE library.</p>
<p>Windows only: XP or later.</p>
<p>GDB manual (recommended).</p>
<hr>
<h3><a name="quick_start">Quick start</a></h3>
<p>From the main Geany menu, invoke <em>Debug --> Setup Program</em> (or <em>Tools -->
Debug --> Setup Program</em>, if there's no <em>Debug</em> in the main menu).<br>
Choose some small executable file compiled with gdb debug information.<br>
Check <em>Temporary breakpoint on load at</em> and press <em>OK</em>.<br>
Invoke <em>Debug --> Run/Continue</em>.</p>
<div>If everything went all right, several things will happen:</div>
<div class="tab">
- A colored <em>Load</em> label will appear shortly on the right of Geany status bar<br>
- The message window will be shown (if hidden) and the <em>Debug</em> page will be focused<br>
- The cursor will be positioned at the first line of code, opening the corresponding source
file if neccessary<br>
- The first line of code will be marked with brown arrow in the markers margin, or with brown
background<br>
- All source files will be marked as read-only (their tab text will become green)<br>
- The <em>Load</em> label will be replaced with a color-less <em>Debug</em>.
</div>
<p>That's it, you are debugging. Try the other Debug menu commands, select the Debug subpages
from the lower Geany panel etc.</p>
<hr>
<h3><a name="interface">Interface</a></h3>
<p>Consists of:</p>
<ul>
<li>Debug menu in the main Geany menu, containing the most commonly used commands (running,
stepping, toggle breakpoint etc.)<br>
If Scope can't access the main menu, it'll place Debug under Tools.</li>
<li>Debug page in the lower panel, with subpages that display the program output, threads,
breakpoints etc.</li>
<li>Inspect and Registers pages in the side panel.</li>
<li>Local menus for the Debug subpages, Inspect and Registers.</li>
<li>Toolbar items - identical to their Debug menu counterparts.</li>
<li>Command Dialog - to enter gdb commands. Will be closed automatically if gdb exits.</li>
<li>A small label on the right of your Geany status bar, which displays the current debugging
state. The possible states are:
<table border="0">
<tr><td>(no label)</td><td class="tab">[N]</td><td class="tab">Not debugging.</td></tr>
<tr><td><em>Busy</em><td class="tab">[B]</td><td class="tab">Scope and/or gdb is busy. Any
debugging information may be outdated.<br>
<tr><td><em>Ready</em><td class="tab">[R]</td><td class="tab">GDB is ready to accept commands,
but there is no thread selected, or the currently selected thread is running. The execution
and stack-related commands will be disabled. Other commands may fail to execute, depending on
your target.</td></tr>
<tr><td><em>Debug</em></td><td class="tab">[D]</td><td class="tab">A stopped thread is
selected, and gdb is ready to accept commands. This is the normal debugging state.</td></tr>
<tr><td><em>Assem</em><td class="tab">[D]</td><td class="tab">Like <em>Debug</em>, but the
source location can not be determined. The stepping menu commands will do assembler steps, and
the current assembler instruction will be shown in the debug console each time the thread is
stopped.</td></tr>
<tr><td><em>Hang</em></td><td class="tab">[H]</td><td class="tab">GDB is loaded, but the
program is not started yet, or is already terminated. Scope will automatically switch to this
state in some situations.</td></tr>
<tr><td>(blinking)</td><td class="tab"></td><td class="tab">Loading a program, signal
received, error parsing gdb output etc.</td></tr>
</table>
The bracketed letters are used to indicate the states supported by a command. For example,
[RH] means "available in Ready and Hang states only". Debug and Assem are almost identical in
this aspect and share [D].</li>
</ul>
<h3><a name="debug_menu">Debug menu</a></h3>
<p><b><a name="set_program">Setup Program</a></b></p>
<p>You can use non-existent <em>Executable</em>, <em>Working dir</em> and <em>Run Script</em>,
and create them later.</p>
<p><em>Arguments</em> are in gdb syntax.</p>
<p><em>Environment</em> is one varname=value per line.</p>
<p><em>Load script</em> is a gdb script, executed when gdb is loaded. May be used to setup the
program. If no <em>Executable</em> is specified, Scope will assume that the script, if any,
loads the program.</p>
<p><em><a name="auto_run_exit">Auto run program/exit gdb</a></em> - with this box unchecked,
the first <a href="#run_continue">Run/Continue</a> will load and setup the program without
running it, and when the program terminates, gdb will not be unloaded. Useful if you want to
run a program several times without reloading, for example to run it unmodified with different
sets of input data.</p>
<p><em>Non-stop mode</em> - gdb non-stop mode. You'd better activate gdb asynchronous mode
from Scope preferences to take advantage of this.</p>
<p><em>Temporary breakpoint on load at</em> - set a temporary breakpoint when the program is
loaded. If you leave the text field empty, Scope will try to find the 1st line of code and
place a breakpoint on it. Any breakpoint options and location are allowed in the text, for
example <em>main</em> for C/C++ programs. Since setting a breakpoint requires a program, this
option will be disabled if both <em>Executable</em> and <em>Load script</em> are empty.</p>
<p><em>Delete all breakpoints, watches and inspects</em> - usually when setting up a new
program. Scope will ask for confirmation.</p>
<p><em>Update all views</em> - update all relevant debug subpages when the current thread
stops, or a different thread is selected. By default, only the current subpage is updated.</p>
<p>Using <em>Locale</em> text mode requires the same code page for Geany/Scope and the program
being debugged.</p>
<p>Unchecking <em>Display member and argument names</em> or using <em>Name=value</em> are not
guaranteed to work; single-quoted strings ending with backslash will fail. GDB "set
print" commands also affect display.</p>
<p><em>Import</em> - get <em>Executable</em> and <em>Working dir</em> from the second Geany
<em>Execute</em> command (from <em>Tools -> Set Build Commands</em>).</p>
<p>When you start Geany, or open/close a project, Scope will try to load the debugging
settings for a program that matches the second <em>Execute</em> command, if any [N]. The
command will not be expanded. Letter case will be ignored under Windows.</p>
<p><b><a name="run_continue">Run/Continue</a></b> [NHD]</p>
<div>Not debugging state (first run):</div>
<div class="tab">
- Load and setup gdb<br>
- Load the <em>Executable</em> and execute the <em>Load script</em>, if any<br>
- If an executable and/or a load script was processed, and there were no errors so far:<br>
<div class="tab1">
• apply any points and inspects marked as <em>Apply on Run</em> and create the
<em>Temporary breakpoint on load</em><br>
• run the program if <em>Auto run/exit</em> is checked, at least 1 breakpoint was
applied, and there weren't any errors.
</div>
</div>
<p>On errors, Scope will enter Hang state, letting you execute commands manually, and fix or
recreate any points or inspects if needed.</p>
<p>Hang state: try to apply any unapplied points or inspects marked as <em>Apply on Run</em>,
and -exec-run despite any errors.</p>
<p>Debug/Assem: -exec-continue.</p>
<p><b><a name="goto_cursor">Run to Cursor</a></b> [D]</p>
<p>scope_goto_cursor=0: -exec-until with the current filename:line<br>
scope_goto_cursor=1: set temporary breakpoint at the current position and -exec-continue.</p>
<p><b><a name="goto_source">Run to Source</a></b> [D]</p>
<p>Assem state only: -exec-step. See gdb step description.</p>
<p><a name="step_into"><b>Step Into</b> / <b>Step Over</b></a> [D]</p>
<p>Debug state: -exec-step / -exec-next.<br>
Assem state: -exec-step-instruction / -exec-next-instruction.</p>
<p><b><a name="terminate">Terminate</a></b> [^N]</p>
<p>Busy state: terminate gdb, even if <em>Auto Run/exit</em> is unchecked.<br>
If you want to terminate the program without unloading gdb, switch to <em>Threads</em> and
invoke <em>Terminate</em> or <em>Send Signal</em>.</p>
<p>Debug or Ready state with <em>Auto Run/Exit</em> off: (gdb) kill.</p>
<p>Otherwise: -gdb-exit.</p>
<p><b><a name="gdb_command">GDB Command</a></b> [^N]</p>
<p>Commands starting with 0<digit> are used internally by Scope and will be blocked.</p>
<p>Both MI and CLI commands are supported.</p>
<p>Scope tries to keep track of the current gdb thread, and to emit a -thread-select command
on <em>Send</em>/<em>Busy</em> if the gdb thread does not match the one (if any) selected in
<em>Threads</em>. Tracking the current gdb frame asynchronously is impossible, so you must use
a gdb frame selection command or --frame for the non-zero frames.</p>
<p>Writing a full combo box for multi-line text is outside the scope of this project.</p>
<p><b><a name="reset markers">Reset Markers</a></b></p>
<p>Synchronize the breakpoint and execution point markers for the current file with the Scope
data. They can become out of sync if you <em>Save as</em> a file with markers, set a source
file type to non-source and edit it, and possibly in other situations.</p>
<p><b><a name="cleanup files">Cleanup Files</a></b></p>
<p>While debugging a program, Scope will automatically open the source files required to show
the current execution point(s). This command closes such files.</p>
<h3><a name="debug_panel">Debug panel</a></h3>
<p>The sort orders and column widths are not saved. However, the breakpoints and watches are
saved in their current order.</p>
<p>Sorting by file name (including breakpoint location) uses the full locale name, so the
order may be different from the displayed UTF-8 base names.</p>
<p><b><a name="terminal">Program Terminal (*nix only)</a></b></p>
<p>Will be disabled if a pseudo-tty can not be created.</p>
<p>May be displayed either in a Debug panel tab or as a separate window.</p>
<div><em>Window</em>:</div>
<table border="0">
<tr><td class="tab"><em>Auto show</em></td><td class="tab">Switch to separate window display
on program startup (when the first thread is created).</td></tr>
<tr><td class="tab"><em>Auto hide</em></td><td class="tab">Switch to Debug panel tab display
on program shutdown (when the last thread is exited).</td></tr>
<tr><td class="tab"><em>Show on Error</em></td><td class="tab">Switch to separate
window display when a thread group is exited with a non-zero status.<br>Not reliable if
combined with <em>Auto Hide</em> on multi-thread-group programs.</td></tr>
</table>
<p><b><a name="threads">Threads</a></b></p>
<p>The thread list is updated by asynchronous gdb messages. Normally you should not need to
refresh it, and <em>Refresh</em> won't append or remove threads, only update the current
ones.</p>
<p><em>Synchronize</em> - refresh and select the current gdb thread. Shift-click:
-thread-select.</p>
<p><em>Interrupt</em> - *nix: SIGINT, win~1: DebugBreakProcess.</p>
<p><em>Terminate</em> - *nix: SIGTERM, win~1: TerminateProcess.</p>
<p>Both <em>Interrupt</em> and <em>Terminate</em> require an extra <em>Step</em> deliver a
signal/*process to a stopped thread, and an extra <em>Step</em> to terminate a process.</p>
<div><em>Select on</em>:</div>
<table border="0">
<tr><td class="tab"><em>Running</em></td><td class="tab">Select a stopped thread (if any) when
the current thread becomes running. Useful when starting/stopping lots of threads, but may be
annoying in other situations - for example, if you are single-stepping a thread, and another
stopped thread exists, it'll be selected on each step.</td></tr>
<tr><td class="tab"><em>Stopped</em></td><td class="tab">Select a thread when it stops (if
there is no stopped thread already selected).</td></tr>
<tr><td class="tab"><em>Exited</em></td><td class="tab">Select a stopped thread (if any) when
the current thread is exited.</td></tr>
<tr><td class="tab"><em>Follow</em></td><td class="tab">Follow gdb =thread-selected. It'll be
better to clear the other options.</td></tr>
</table>
<p><b><a name="break">Breakpoints</a></b></p>
<p>There is no dialog for adding/editing breakpoints. You can use <em>Debug -> Toggle
Breakpoint</em>, edit the <em>Ignore</em>, <em>Condition</em> and <em>Script</em> columns, or
invoke <em>Add Break / Add Watch</em> [HRD], which brings up the command dialog.</p>
<p>Breakpoints created with MI commands are kept in the list permanently. When a temporary MI
breakpoint is hit, it's <em>Id</em> column is cleared. <em>Toggle breakpoint</em>, <em>Add
Break</em> and <em>Add Watch</em> use MI commands.</p>
<p>Breakpoints created with CLI commands (from scripts or <em>GDB Command</em>) are removed
when the program is unloaded. When a temporary CLI breakpoint is hit, it's removed. If a MI
command produces none or invalid output, and the breapoint appears later (from Refresh or
async message), Scope will consider it CLI.</p>
<p>Scope remembers the total (initial) ignore count, and re-applies it on each run. When a
breakpoint is applied, <em>Ignore</em> shows the current value, followed by the total value
surrounded in brackets. On gdb 'ignore' (or -break-after followed by refresh), the total value
will be set only if the new count is larger: there is no way to tell whether a smaller count
resulted from a command execution or breakpoint hit(s). Edit the <em>Ignore</em> column to set
a smaller count.</p>
<p>The above paragraphs apply to watchpoints and tracepoints as well.</p>
<div>Due to MI limitations and deficiencies:</div>
<div class="tab">
- The catchpoints are displayed incompletely and removed on program unload<br>
- Disposition "dis" is ignored, and "del" (i.e. temporary) is saved for break and trace points
only<br>
- The difference between software and hardware watchpoints is ignored, but gdb will create
hardware watchpoints as needed.</div>
<p>For tracepoints, only the generic breakpoint commands and attributes are supported (with
ignore for passcount), not the tracepoint-specific commands.</p>
<p><em>Apply on run</em> is off by default for watchpoints, because they are often related to
a local expression.</p>
<p>Shift-clicking <em>Apply</em> applies the breakpoint for the currently selected thread
only, if any.</p>
<p>GDB may report an error for invalid <em>Condition</em> and/or <em>Script</em>, but still
accept them, and continue to emit errors each time they are evaluated.</p>
<p>The breakpoint line markers, <em>View Source</em> and double-click use the last known file
name and line, as displayed in <em>Location or expr</em>. They may change when a breakpoint is
applied or resolved.</p>
<p>With gdb 7.4 and later, the breakpoint list is updated by asynchronous gdb messages (except
for <em>async_break_bugs</em>). Use <em>Refresh</em> to fully refresh it.</p>
<p><em>Condition</em>, <em>Script</em> and watchpoint <em>expr</em> use the default 8-bit text
mode.</p>
<p>For multi-address breakpoints, the individual locations are not loaded or saved, and are
deleted as soon as the program is unloaded, so you may prefer to turn <em>Auto run/exit</em>
off when using them. When a breakpoint is disabled, GDB treats all it's locations as disabled,
despite their individual state. However, with at least one enabled location for a file:line,
the marker for enabled breakpoint will be used for that line.</p>
<p><b><a name="stack">Stack</a></b></p>
<p>The function arguments are subject to 8-bit text conversion. Their individual modes may be
set via <em>Locals</em>.</p>
<p><em>Synchronize</em> - select the current gdb frame. Shift-click: -stack-select-frame.</p>
<p><em>Show @entry</em> - display any @entry arguments reported by gdb for the selected frame
function. Depends on GDB "print entry-values". Applies to <em>Locals</em> too.</p>
<p><b><a name="local">Locals</a></b></p>
<p>The first column is "1" for arguments, empty for local variables.</p>
<p><b><a name="watch">Watches</a></b></p>
<p>This is a flat list of expressions, evaluated each time the current thread stops or changes
(subject to <em>Update all views</em>), in the context of the current thread and frame. Unlike
<em>Inspect</em>, any gdb-evaluatable expressions may be used, and there is no need to apply
them.</p>
<p><b><a name="local_watch">Locals/Watches</a></b></p>
<p><em>Modify</em> is useful for setting individual array / structure elements.</p>
<p>Shift-clicking <em>Modify</em> displays strings as "TEXT" instead of 0xADDR, and
characters as 'C' instead of VALUE (see <a href="#editing_values">Editing values</a>).<br>
Any char[] arrays will still be displayed as arrays.</p>
<p><em>Show .names</em> - display member names. Shift+Click resets it to the value specified
in <em>Setup Program</em>.</p>
<p><b><a name="memory">Memory</a></b></p>
<p><em>Group by</em> is for visual convinience only and ignores endian.</p>
<p>Groups are not wrapped, so with <em>Group by</em> > 1, less than
<em>memory_line_bytes</em> may be displayed.</p>
<p>A maximum of 16K may be displayed (128 lines * 128 bytes).</p>
<p><b><a name="console">Debug Console</a></b></p>
<div><table>
<tr><td>Red</td><td class="tab">gdb stderr (or sometimes exec) error messages</td></tr>
<tr><td>Gray</td><td class="tab">normal gdb messages</td></tr>
<tr><td>Cyan</td><td class="tab">commands send to gdb</td></tr>
<tr><td>Magenta</td><td class="tab">Scope messages, mostly parsing errors</td></tr>
</table></div>
<p>Typing a graphical ascii character or pressing Insert brings up the command dialog.</p>
<p>Note that whether the last displayed line is a gdb prompt is <b>not</b> a proper indicator
if GDB is ready to receive commands. For example, in synchronous mode, GDB displays a prompt
immediately resuming the program execution; or the prompt may be followed by asynchronous
messages. The Scope state (Busy, Debug etc.) is more accurate.</p>
<h3><a name="windows_console">Windows console</a></h3>
<p>Displayed automatically by Windows when starting a Windows console program, and closed
automatically when the program terminates. To leave the console open on program termination,
set breakpoints at ExitProcess / TerminateProcess.</p>
<h3>Side pages</h3>
<p><b><a name="inspect">Inspect</a></b></p>
<p>-var-* commands entered from the command line will not update the <em>Inspect</em> view,
because their output does not provide enough information to identify the variable object,
and/or their PRINT-VALUES argument is unknown.</p>
<p><em>Jump To</em> lists the top-level variables, which is useful if you have a lot of
children displayed. It's disabled while gdb is inactive, because all variables are collapsed
anyway.</p>
<p>Double-click or Return applies/unapplies a variable.</p>
<p><em>Add</em> will try to apply the variable object immediately, <em>Edit</em> will
not. <em>Apply on run</em> is off by default, because the variables are often local.</p>
<p><em>Expand</em> is primary to change the expansion options. After a variable is applied,
you can expand it simply by using the keyboard or mouse, like with any other gtk+ tree.</p>
<p>The command "echo ^(Scope)#07<em>name</em>" will try to apply the variable
<em>name</em>. You can include such commands in your breakpoint scripts. The name must start
will a letter ("-" will not do).</p>
<p>When modifying variables, gdb interprets "TEXT" as the identifier TEXT.</p>
<p>The format and 7-bit mode are saved only for the top-level variables, not for children (but
see <a href="#keeping_modes">Keeping modes</a>).</p>
<p><b><a name="registers">Registers</a></b></p>
<p>Scope will query the register names once after a program is loaded, or when the gdb
executable is changed. If you switch to a different architecture, but your gdb name remains
the same, invoke <em>Query</em> from the local menu.</p>
<h3><a name="preferences">Preferences</a></h3>
<p>Once again, trivial items are not included.</p>
<p>[scope]</p>
<p><em>async_break_bugs</em> (win~1 only) - whether gdb escapes slashes twice in the
asynchronous break messages. if true (the default), only <tt>=breakpoint-deleted</tt> will be
handled.</p>
<p><em>var_update_bug</em> - whether -var-update causes internal gdb error if the program is
loaded but not running. If true (the default), the update of inspect expressions (including
<em>Refresh</em>) will be disabled in <em>Hand</em> state. AFAIK, they will always have the
globally initialized values (if any) in that state anyway.</p>
<p><em>auto_view_source</em> - seek in source on single click in threads, breakpoints
and stack.</p>
<p><em>keep_exec_point</em> - do not clear the execution point marker and <em>Threads</em>
location columns when a thread execution is resumed.</p>
<p><em>visual_beep_length</em> - hundreds of seconds to flash the state label on Scope
errors. Default = 25.</p>
<p><em>debug_console_vte</em> (*nix only) - use vte terminal for the debug console. The
alternative is a GtkTextView based console, which has a few quirks, but consumes less CPU
power. That can be useful if you use the console a lot, and have a slow CPU or a limited power
supply. The win~1 version of Scope always uses GtkTextView.</p>
<p><em>sci_marker_first</em> - Scope uses markers 17..19 by default; they may be changed to
avoid conflicts with other plugins.</p>
<p><em>sci_caret_policy</em>, <em>sci_caret_slop</em> - Scintilla Y caret policy when
moving/scrolling to show the current execution point (does not affect the normal navigation
and editing). Default policy = CARET_SLOP | CARET_JUMPS | CARET_EVEN, slop = 3.<br>
See ScintillaDoc.html#SCI_SETYCARETPOLICY and Scintilla.h for more information.</p>
<p><em>unmark_current_line</em> - disable the current line highlighting while debugging.
Useful if the current line background covers the breakpoint or execution point backgrounds.
Affects the source files only.</p>
<p><em>seek_with_navqueue</em> - use Geany navqueue when seeking in source.</p>
<p><em>panel_tab_pos</em> - see GtkPositionType. Some tab names will be shortened in Left
and Right.</p>
<p><em>show_recent_items</em> - number of items to display in <em>Debug --> Recent
Programs</em>. Default = 10, maximum = 28. Note that Scope will always keep the settings
for the last 28 programs; on project open/close and Geany startup, settings which are not
visible in the menu may be loaded.</p>
<p><em>show_toolbar_items</em> - bitmask: 1 = Run/Continue, 2 = Goto Cursor, 4 = Goto
Source, 8 = Step Into, 16 = Step Over, 32 = Step Out, 64 = Terminate and 128 = Toggle
Breakpoint.</p>
<p><em>tooltips_fail_action</em> - 1 = blink on tooltip evaluate errors, 2 = display them as
tooltips.</p>
<p><em>tooltips_send_delay</em> - increase this setting to reduce the CPU time and GDB traffic
used by the tooltips, or decrease it if they appear slower than your gtk+ setting.</p>
<p><em>pref_tooltips_length</em> - maximum length of a tooltip message, 0 = unlimited.
Default = 2048.</p>
<p><em>memory_line_bytes</em> - maximum bytes per <em>Memory</em> line.</p>
<p>[terminal] (*nix only)</p>
<p><em>width</em>, <em>height</em> - VTE widget (not the entire terminal window) size</p>
<p><em>save_pos</em> - auto save window position and widget size</p>
<p><em>padding</em> - whether <em>width</em> and <em>height</em> include the extra VTE widget
padding. If <em>save_pos</em> is active, they will be saved with the padding.</p>
<p>[disabled_break], [enabled_break], [execution_line]</p>
<p><em>mark</em> - Scintilla mark. See Scintilla.h: SC_MARK_.</p>
<h3><a name="notes">Notes</a></h3>
<p>Changes in Geany VTE preferences will be applied when Scope is restarted.</p>
<p>Locale/UTF-8 conversion is fully supported for values only. Filenames not matching your
locale and non-ascii identifiers are not guaranteed to work.</p>
<p>When editing a column while the program is running, it's value will be updated after/if the
respective gdb command is executed.</p>
<p>If you use multiply Geany instances with session management, make sure that only one of
them has Scope enabled. Otherwise, the list of programs and their settings may break.</p>
<p>A disabled check button or check menu item means that the respective functionality is
unavailable; it doesn't matter if the interface element is checked or not.</p>
<p>Frame-dependent commands entered from the command line will not update the respective view,
because their output does not contain thread and frame information.</p>
<p><b><a name="editing_values">Editing values</a></b></p>
<div>GDB often displays values in format unsuitable for assigning. So when editing a value,
Scope will try to:</div>
<div class="tab">
- Cut any member names, because <em>set foo = { i = 4, c = 'x' }</em> actually means
<em>i = 4; c = 'x'; foo = {4, 'x'}</em><br>
- Cut any array indexes<br>
- Cut 0xADDR "TEXT" to 0xADDR. Leaving both is invalid, and "TEXT" always
creates a new string pointer<br>
- Cut VAL 'C' to VAL. Again, leaving both is invalid<br>
- Detect <repeats, <optimized etc. and clear the entire value if editing via the
<em>Value</em> column<br>
- Convert char[] arrays displayed as string to character array, because a string always
includes a trailing '\0', so a char[4] may be displayed as "TEXT", but can not be
assigned like that.<br>
Note that UTF-8 texts will be converted to 8-bit character arrays.
</div>
<p>Of course, you can still enter a "TEXT" or a 'C'haracter.</p>
<p>The above steps are not guaranteed to work; in particular, single-quoted strings ending
with backslash will fail. If parsing errors are detected when editing the <em>Value</em>
column, the entire value will be cleared - but that is not guaranteed to work either.</p>
<p><b><a name="keeping_modes">Keeping modes</a></b></p>
<p>The 7-bit, .names etc. modes for temporary objects, such as local variables, are not saved.
However, there is a global list with names and modes, and when you change a mode, it is saved
in that list. Then, when a temporary object is created, Scope searches the list, and sets the
modes (if any) for that object. For inspect children, the displayed names are used (including
numbers for array elements), not the fully qualified names.</p>
<p><b><a name="shared_memory">Shared memory</a></b></p>
<div>Scope does not know which Inspect/Watch expressions are thread and frame dependent, as
well as whether the Memory address and range are process/thread dependent, so their handling
is a compromise.<br>
In particular:</div>
<div class="tab">
- the values will not be updated if threads exist, but none is selected, or if the selected
thread is running<br>
- for <em>Watches</em> and <em>Inspect</em>, Scope will try to select a frame before
sending the update command(s)<br>
- on a thread or frame change, if the values can not be updated at the moment, they will not
be cleared.</div>
<p><b><a name="xos4_colors">Sample dark colors</a></b></p>
<pre>
[disabled_break]
mark=0
alpha=256
fore=#008000
back=#005000
[enabled_break]
mark=0
alpha=256
fore=#0000E0
back=#000068
[execution_line]
mark=4
alpha=256
fore=#F0F000
back=#707000
</pre>
<h3><a name="pre_faq">Pre-FAQ</a></h3>
<p>Questions which are likely to be asked frequently:</p>
<p>Q. How about tree lists in <em>Locals</em> and <em>Watches</em>?</p>
<p>A. They operate with the entire struct/array values, so creating tree lists would be
completely artificial. Some front ends automatically create/delete gdb variables for the
locals as they come into/go out of scope, or even or each step, but I'm not willing to do
that. The watches can not be represented with variables (see <em>Watches</em>). So, use
<em>Inspect</em> for tree lists.</p>
<p>Why isn't <em>Interrupt</em> implemented as -exec-interrupt?</p>
<p>Because it requires a gdb prompt, and see <em>Bugs</em>. Of course, using target-specific
functions has it's own drawbacks, but you can always try to send an -exec-interrupt from the
GDB command line if you need it.</p>
<p>Q. Why not leave the member names (array indexes) while editing a value?</p>
<p>A. They must be removed before sending the value to GDB. Leaving them while editing gives
the false impression that you can assign selectively, while in fact omitting a "foo =
value," <em>moves</em> all values left by 1, and changing a name or index has
<em>no</em> effect.</p>
<p>Q. A "signal `project-before-save' is invalid" warning is displayed on Geany startup, and
an "assertion `handler_id > 0' failed" message on quit.</p>
<p>A. Your Geany does not support this signal. Either apply the patch from Geany sourceforge
patch tracker <a href="http://sourceforge.net/tracker/?func=detail&aid=3594050&
group_id=153444&atid=787793">ID 3594050</a> and recompile it, or make sure to
<em>Terminate</em> the debugged program before quitting Geany or switching to another project.
Otherwise, your source files will be marked as read-only when the current project is reopened.
Of course, you can awlays unlock them manually (via <em>Document --> Read Only</em>),
so it's nothing serious.</p>
<h3><a name="bugs">Bugs</a></h3>
<p>For some reason, -exec-interrupt under Linux (*nix?) signals gdb and Geany, but not the
program/thread. The other Geany debugger plugin has the same problem.</p>
<p>Report bugs to <dimitar.zhekov@gmail.com></p>
<h3><a name="todo">TODO</a></h3>
<p>Various tests, source code checks etc.<br>
Format (natural, decimal...) for Watches?<br>
Add clear icon to entries? not very useful.<br>
Don't remove [index] along with member names?<br>
libtool support / exec wrapper support.</p>
<h3><a name="not_todo">Not TODO</a></h3>
<table cellpadding="0" cellspacing="0">
<tr><td>"The master programmer knows when to leave things in their simple form."</td></tr>
<tr><td align="right">-- Eloquent Javascript</td></tr>
</table>
<div>Things that will not be implemented in Scope:</div>
<ul>
<li>Support for debuggers other than GDB</li>
<li>"Proper GObject-ification"</li>
<li>Combined subpages, such as <a href="http://projects.gnome.org/nemiver">Nemiver</a> Context
</li>
<li>GUI for functions that don't really need it.</li>
<li>Anything that requires parsing non-MI output.</li>
</ul>
<h3><a name="legal_info">Legal information</a></h3>
<b><a name="license">License</a></b>
<p>Scope is distributed under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at your option) any
later version.</p>
<b><a name="copyright">Copyright</a></b>
<p>Scope 0.94, Copyright (C) 2015 Dimitar Toshkov Zhekov</p>
<p>The menu and toolbar icons are from <a href="http://netbeans.org">Netbeans</a>, except for
BreakPoint.</p>
<p><b>The End</b></p>
</body>
</html>
|