*gdbmgr.txt* Gnu Debugger Manager for Vim Feb 18, 2016 Author: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM> (remove NOSPAM from Campbell's email first) Copyright: (c) 2008-2015 by Charles E. Campbell *gdbmgr-copyright* The VIM LICENSE applies to gdbmgr.vim and gdbmgr.txt (see |copyright|) except use "gdbmgr" instead of "Vim" NO WARRANTY, EXPRESS OR IMPLIED. USE AT-YOUR-OWN-RISK. NO MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. ============================================================================== 1. Contents *gdbmgr* *gdbmgr-contents* {{{1 1. Contents................................................: |gdbmgr-contents| 3. Tutorial................................................: |gdbmgr-tutorial| Example 1: Initializing gdbmgr.........................: |gdbmgr-ex1| Example 2: Using breakpoints and expressions...........: |gdbmgr-ex2| Example 3: The function stack and temporary breakpoints: |gdbmgr-ex3| Example 4: Watchpoints.................................: |gdbmgr-ex4| Example 5: Interacting with a Program..................: |gdbmgr-ex5| Example 6: Working with Core Dumps.....................: |gdbmgr-ex6| Example 7: Working with Assembly and Window Stacking...: |gdbmgr-ex7| Suggestion.............................................: |gdbmgr-suggest| 4. Manual..................................................: |gdbmgr-manual| Gdbmgr commands........................................: |gdbmgr-cmd| Gdbmgr maps............................................: |gdbmgr-maps| Window Control....................................Code.: |gdbmgr-winctrl| Assembly Window.....................................A..: |gdbmgr-assembly| Breakpt Window.......(non-writable).................B..: |gdbmgr-breakpt| Checkpoint Window....(non-writable).................H..: |gdbmgr-checkpt| Command Window.......(writable).....................C..: |gdbmgr-cmdwin| Expressions Window...(writable).....................E..: |gdbmgr-expr| Messages Window......(non-writable).................M..: |gdbmgr-mesg| Source Window........(varies).......................S..: |gdbmgr-source| Threads Window.......(non-writable).................T..: |gdbmgr-threads| Watchpoint Window....(writable).....................W..: |gdbmgr-watchpt| Foreign Apps...........................................: |gdbmgr-foreignapp| Bufexplorer Window..(non-writable).................b..: |gdbmgr-bufexplorer| Netrw Window........(non-writable).................N..: |gdbmgr-netrw| Tags Window.........(non-writable)................h/t.: |gdbmgr-tags| Gdbmgr Options.........................................: |gdbmgr-options| 5. History.................................................: |gdbmgr-history| ============================================================================== 2. Installing gdbmgr *gdbmgr-install* {{{1 Gdbmgr needs linux; it definitely won't work under Windows, and needs some dynamic library loading help with the Makefile before it will work with a Mac (as I don't have a Mac, it is difficult for me to do this). 1. To run gdbmgr, you need to have a vim compiled with huge and which supports the forkpty() function. To get this support, you may * Configure with: > configure --with-features=huge --enable-perlinterp < * Configure with: > configure --with-features=huge --enable-pythoninterp < * Configure with: > configure --with-features=huge < and modify vim's Makefile to include the line > EXTRA_LIBS = -lutil < GdbMgr does not use perl or python (or ruby, mzscheme, tcl, ...). The "-lutil" supports a function (forkpty, for those who are curious) that is used by gdbmgr.so (shared object library) to interface with gdb. For the last method, that using EXTRA_LIBS, use vim on src/Makefile, search for libefence.a, and append the line > EXTRA_LIBS = -lutil < 2. Get the following file: > gdbmgr.tar.gz < 3. Install the plugin: > cd ~/.vim tar -xf gdbmgr.tar.gz < The "progs" subdirectory extracted by this command is only needed for the tutorial. 5. Compile the shared library code: > cd ~/.vim/gdbmgr/src make < The shared library "gdbmgr.so" needs to be made available for vim to find it. One way to do this: (ksh,bash,sh) > export LD_LIBRARY_PATH="$HOME/.vim/gdbmgr/src:default" < Of course, if you already have a LD_LIBRARY_PATH set up and a directory devoted to shared libraries, you may wish instead simply to move the gdbmgr.so file there. 6. If you get the error: "undefined symbol: forkpty", and you followed the directions in step#1, then try adding the following line to your startup script (.profile, etc): > export LD_PRELOAD="${LD_PRELOAD}:/usr/lib/libutil.so" < One should also note that there are similar plugins available at http://pyclewn.wiki.sourceforge.net/ (clewn, pyclewn, and vimgdb). They require a patch to vim, python, and/or the netbeans interface. ============================================================================== 3. gdbmgr Tutorial *gdbmgr-tutorial* {{{1 This tutorial assumes that you've already successfully installed gdbmgr as described in |gdbmgr-install| above. The gdbmgr example programs (none of which, I'm afraid, do anything at all useful) are in > cd ~/.vim/gdbmgr/progs Move them, if you wish, to any directory of your choice. > < (I'll be using "vi" to mean either "vim" or "gvim", your choice, in the text below) EXAMPLE 1: Initializing gdbmgr *gdbmgr-ex1* {{{2 Compile the first example program: > cc -g prog1.c -o prog1 vi prog1.c :DI < This initializes the program in a new tab (DI means Debug Initialize). You should see a display resembling: > +----------+------------+-----------------+ | Netrw Dir| Messages | Function Stack | | | | | | ( a +------------+-----------------+ | netrw | Source Window | | listing | (prog1.c listing) | | ) | | | +-------+---------+------------+ | | Expr | Breakpt | Watchpoint | | | | | | +----------+-------+---------+------------+ < with the cursor in the Source Window. Type: > :DR < This command runs the prog1 program, generating a SIGSEGV fault. The current line in the Source window should be on the line which caused the problem. To further investigate what the cause of the crash was, find out what values the variables on that line are (in this case, there's only px). You may do this several ways with gdbmgr: - Using the mouse and hovering: Place the mouse over "px" and let it "hover" (stay still) for a moment. Assuming your vim has balloon evaluation enabled, a balloon will appear giving the value of px. - Using the Expressions window: > <c-w>j ipx=<esc> < (ie. insert "px=" into the Expressions window) Expressions in the Expressions window are updated every time a breakpoint or other stoppage occurs. The "=" is then followed by the current value of the expression. - Using the Messages window: > :D p px < The Messages window contains output messages from gdb. The command > :D gdbcmd [args] < sends the gdb command "gdbcmd" (and any arguments) along to gdb and displays its output in the Messages window. EXAMPLE 2: Using breakpoints and expressions *gdbmgr-ex2* {{{2 Compile the first example program if you haven't done so already: > cc -g prog1.c -o prog1 vi prog1.c :DI < This initializes the program in a new tab. You should see a display resembling: > +----------+------------+-----------------+ | Netrw Dir| Messages | Function Stack | | | | | | ( a +------------+-----------------+ | netrw | Source Window | | listing | (prog1.c listing) | | ) | | | +-------+---------+------------+ | | Expr | Breakpt | Watchpoint | | | | | | +----------+-------+---------+------------+ < with the cursor in the Source Window. Move the cursor to line 52: > 52G < Press > <F6> < This will place a breakpoint at <prog1.c:52>. You should see an orange disk on a white background show up in the signs column next to line#52 and a line appearing in the Breakpoints window. The "=>" arrow in the signs column will still be pointing to the next line to be executed. Begin running the program by typing > :DR < The current line should now be line#52. Note that the Function Stack window is automatically updated, and "Breakpoint 1, main... at prog1.c:52" appears in the Messages window. Switch to the Expressions window and insert the following: > i= < You'll see "i = 0" show up; the Expressions window shows the result of the expressions in its window as soon as you type the "=". It will also update that window; to see this, return to the Source window and type > s < to single step the program counter. You'll see that the Expressions window is now showing "i = 1". Repeat the single step and you'll see "i = 2" appear in the Expressions window, automatically. EXAMPLE 3: The function stack and temporary breakpoints *gdbmgr-ex3* {{{2 Compile the second example program if you haven't done so already: > cc -g prog2.c -o prog2 vi prog2.c :DI < This initializes the program in a new tab. You should see a display like that for Examples 1 and 2 but with the prog2.c source. The current line should be line#53. Press > <s-F6> < and you'll see a small orange disk inside an orange circle. This icon signifies the presence of a temporary break. Begin running the program by typing: > :DR < The current line should not change ("int ret= 0;"). Begin stepping; as a further example, you may do multiple steps by preceding the command with a count: > 2s < This should cause the current line to become #64 (int ret= 0;) inside the func1() function. Note that the Function Stack window shows the current set of frames. Continuing to press > s < will eventually advance the program counter into the func3() function, and then begin returning. In func3() there's a division-by-zero (a SIGFPE results); if you fix it, re-compile, and re-run gdbmgr, eventually the program will return from main. While gdbmgr:gdb is running your program, the signs column shows your current program counter location with => and where your breakpoints are. You may not edit the file during this time. However, when the program exits, gdbmgr will remove the signs column and remove the no-editing restriction. EXAMPLE 4: Watchpoints *gdbmgr-ex4* {{{2 Compile the third example program if you haven't done so already: > cc -g prog3.c -o prog3 vi prog3.c :DI < This initializes the program in a new tab. You should see a display like that for the previous Examples but with the prog3.c source. The current line should be line#51. Enter a temporary breakpoint and run gdb: > <s-F6> :DR < Then enter the Watchpoints window, and insert: > x[3]= < You'll see the line change from "x[3]=" to > w x[3] = 0 < which means that x[3] is a write-watchpoint; the current value of x[3] is 0. A write watchpoint will stop the program from executing immediately after the variable in question has changed value. You could have explicitly written > w x[3]= < instead. There are two other choices: "r varname=" for read-watchpoint (when the variable is read from) or "a varname=", for all-watchpoint (which does both read and write watchpointing). To see this work, I suggest first putting > i= < in the Expressions window, returning to the Source window, and typing > c < which tells gdb to continue running the program. The current line becomes line#56, > if(i == 3) y= x[i]; < which is immediately after "x[i]= z[i]" with i=3; x[3] had just changed value. You'll note that the Watchpoint window shows x[3] being equal to 40. EXAMPLE 5: Interacting with a Program *gdbmgr-ex5* {{{2 Compile the fourth and fifth example programs if you haven't done so already: > cc -g prog4.c -o prog4 vi prog4.c :DI < This initializes the program in a new tab. You should see a display like that for the previous Examples but with the prog4.c source. When you run this program: > :DR < you'll see in the Commands window the string: > "What happens to this string?" < The commands window is where one may interact with the program and see its output. The fifth example program, compiled with: > cc -g prog5.c -o prog5 vi prog5.c :DI < shows a prompt, "Enter something: ". Type > aok<cr> < where the <cr> is a carriage return. You'll see the program respond with > Entered buf<ok > < (since you entered the string ok<cr>, the carriage return also shows up in the output). EXAMPLE 6: Working with Core Dumps *gdbmgr-ex6* *gdbmgr-core* {{{2 There are several ways to work with core dumps. Try running prog1: > prog1 < This operation should result in a core dump. If you're not getting core dumps, try typing > ulimit -c unlimited < and then re-run prog1. The following ways get gdbmgr working with core dumps: (assuming that the core dump is named "core.946") 1. Method 1: > :GdbMgr prog1 core.946 < This method creates a new tab, reads the core dump, and initializes the gdbmgr windows. 2. Method 2: > :GdbMgr prog1 :D core core.946 < This method starts the gdbmgr session with prog1, and then reads the symbol table and stack information from the core dump. 3. Method 3: > :GdbMgr prog1 :D target core core.946 < This method starts the gdbmgr session with prog1, and then reads the symbol table and stack information from the core dump. 4. Method 4: Assuming that you've implemented |gdbmgr-suggest|, then > vi prog1 :D core core.946 < or > vi prog1 :D target core core.946 < will use the core dump and prog1 programs. 5. Method 5: This method uses the netrw window: > vi prog1 (switch to Netrw window) (place cursor atop core.* file) x < The "x" key uses the |g:Netrw_corehandler| function reference to interface with gdbmgr. It updates the message, expression, function stack, and source windows. EXAMPLE 7: Working with Assembly and Window Stacking *gdbmgr-ex7* {{{2 Compile the seventh example program if you haven't done so already: > cc -g prog7.c -o prog7 vi prog7.c :DI < As before, this will initialize the program in a new tab. The default window control string (see |gdbmgr-winctrl|) does not include the assembly window (code "A"; see |gdbmgr-assembly|). So, usually one will need to get an assembly window available. Choose a currently existing window where the Assembly window will be stacked: this tutorial will use the Source code window. So, type > CA < and you will see a message "***note*** choose a window and use :Dstack A". Type > CS :Dstack A < and you will see the Assembly window instead of the window holding the Source buffer. Not to worry -- typing <c-F6> will cycle through the buffers in the same window, so you normally will see the window toggle between the Source buffer and the Assembly buffer. At this point you'll get "No frame selected." showing in the Assembly window; assembly won't show up until the program is running (and so a frame will then be selected). Type > <c-F6> 35G <F6> :DR < which will switch you to the Source buffer, go to line 35, install a breakpoint there, and then run the program. The end result is the cursor on line 35 in the Source buffer. Switch to the Assembly buffer with: > <c-F6> < and you will see the associated assembly source obtained by gdb's disassembly command. SUGGESTION: *gdbmgr-suggest* *gdbmgr-auto* {{{2 If you'd like to "edit" an executable and have GdbMgr come up automatically, then, assuming it doesn't yet exist, create a file called > $HOME/.vim/scripts.vim < The scripts.vim file is used when extension-based filetype recognition doesn't find an associated filetype. Install therein the following code snippet: > " Automatic GdbMgr Invocation: if has("unix") && executable("file") && !&l:binary if executable(expand("<afile>")) let file_type= system("file ".expand("<afile>")) if file_type =~ '\<executable\>' && file_type !~ '\<shell\>' && file_type !~ '\<script\>' call gdbmgr#GdbMgrInit(expand("<afile>")) endif unlet file_type endif endif < What this does: * if you're using Unix/Linux, and * the "file" command is available on your system and, furthermore, * the binary option is not set (which might imply that you really want to edit the file, perhaps with xxd; see |using-xxd|), then the "file" system command is used to examine the file being edited. If the "file" command finds that the file is an executable and you have execution privileges, then the equivalent of :GdbMgr [executable-filename] is issued. With this code in ~/.vim/scripts.vim, one could then type > vi pgmname < and GdbMgr will then be automatically invoked. ============================================================================== 4. gdbmgr Manual *gdbmgr-manual* {{{1 GDBMGR COMMANDS *gdbmgr-cmd* {{{2 *gdbmgr-gdbmgr* GdbMgr initializes gdbmgr with the program executable GdbMgr pgmname named pgmname. If not present, the current GdbMgr pgmname core source file's name less its suffix will be GdbMgr winctrl used, if an executable by that name exists. GdbMgr winctrl pgmname Currently, all insert-mode abbreviations GdbMgr winctrl pgmname core are cleared during initialization as they can interfere with the operation of the Commands window. *gdbmgr-D* D gdbcmd [args] Sends the gdbcmd and any optional arguments along to gdb. Any command supported by gdb may be sent this way. (Debug ...) *gdbmgr-DA* DA pgmname Initialize GdbMgr by attaching to a process DA pid given its name or its pid *gdbmgr-DC* DC Set the Source window to display what gdb has as the current file and line. (Debug Current) *gdbmgr-DF* DF pgmname Set the program name to progname. Same as :D file progname *gdbmgr-DI* DI [progname] same as :GdbMgr DI pgmname (Debug Initialize) DI pgmname core DI winctrl DI winctrl pgmname DI winctrl pgmname core *gdbmgr-DK* DK kill program being debugged (gdb's "kill") (Debug Kill) *gdbmgr-DR* DR [args] Run the program with optional arguments. Like gdb's run "args" command. (Debug Run) *gdbmgr-Dstack* Dstack [code] Stack the requested coded buffer in the current window. If the coded buffer currently resides in a different window/stack, it will be moved to the current window. *gdbmgr-Dunstack* Dunstack Unstack the currently displayed coded buffer from the current window. *gdbmgr-DQ* DQ Quit gdbmgr and most of its tab, but leaves vim running and the Source window showing. (Debug Quit) GDBMGR MAPS *gdbmgr-maps* {{{2 Most maps that Gdbmgr installs are associated with specific coded windows and will be discussed for each such coded window (ie. |gdbmgr-breakpt|, |gdbmgr-expressions|, |gdbmgr-source|, etc). The mappings mentioned below are available from any window in the Gdbmgr tab: > CA Go to Assembly CB Go to Breakpoints CH Go to Checkpoints CC Go to Commands CE Go to Expressions CF Go to Funcstack CM Go to Messages CN Go to Netrw CS Go to Source CW Go to Watchpoints < In addition, similar mappings are supported for "foreign app" coded windows. WINDOW CONTROL *gdbmgr-winctrl* {{{2 gdbmgr's display may be customized using window control lists. One may set the window control list in three ways; in the order of precedence: > :DI [winctrl list] (.vimrc) let g:gdbmgr_winctrl = ... (default) [['c25','r-,N-'],['c-','r5,M-,F-','r-,SC-','r5,E-,B-,W-']] < I will explain window control lists from the bottom up. First, a dictionary of abbreviations: Dictionary: ~ WP window primitive |gdbmgr-WP| RS row string |gdbmgr-RS| CL column list |gdbmgr-CL| RL row list |gdbmgr-RL| *gdbmgr-WP* (WP) gdbmgr window primitives have an application code letter and a sizing specification: > c#cols specifies qty of columns in a RL r#rows specifies qty of rows in a CL A#cols Assembly window B#cols Breakpoint window C#cols Command window E#cols Expression window F#cols Function Stack window M#cols Messages window N#cols Netrw window S#cols Source code window W#cols Watchpoint window < Additionally there are several |gdbmgr-foreignapp| windows available: > b#cols Bufexplorer window (for exploring via buffers) c#cols CtagsExpl window (for exploring with ctags) h#cols Hdrtag window (for exploring with hdrtags) < A "-" for #cols or #rows is a wildcard; it'll grow to whatever is needed to fit the display, equally split up amongst co-equal "-" specifications. Example: > B#15 < This window will support breakpoints and be 15 columns wide. Overlaying Windows:~ Multiple windows can be overlaid atop one another by placing multiple window codes next to one another. Example: > SC#10 < So the Source and Command windows will take up the same physical space on the screen (with 10 columns). One may switch between them by typing > <c-F6> < *gdbmgr-RS* (RS) A comma-delimited set of WPs in a string comprises a Row String. Example: > 'r8,M10,F-' < which means that the row of windows for this RS will have a Messages window 10 columns wide, with a Function Stack window taking up the rest of the width. A RS normally begins with a "r#rows" WP which specifies the quantity of rows for all windows in the RS; in this example, all the windows specified by this RS will have 8 rows. *gdbmgr-CL* (CL) A list of Row Strings specifies a Column List. Each RS in a CL must begin with its own "r#rows" specification. Example: > ['r5,M10,F-','r-,S-'] < which means that this column list has a row with two windows (Message, Function Stack) atop another row containing one window (the Source Window). The two rows are vertically arranged in a column, hence the name "column list". The Message&Function Stack windows are 5 rows high; the Source window will take the rest of the rows available (and be a full-width window due to the wildcard column's "-" specifier). *gdbmgr-RL* (RL) A Row List is composed of one or more CLs; it is a list of lists. Each CL in a RL must begin with a "c#cols" specification. There may only be one RL in a window control specification. Consider the default window control list: > [['c25','r-,N-'],['c-','r5,M-,F-','r-,SC-','r5,E-,B-,W-']] WP , WP,WP WP , WP,WP,WP , WP,WP , WP,WP,WP,WP <- Window Primitives '.RS₁.' '...RS₂..' '..RS₃.' '....RS₄....' <- Row Strings [.....CL₁.....] [...............CL₂...................] <- Column Lists [.......................RL...............................] <- Row List < ..CL#1.... ...........CL#2............... +----------+------------+-----------------+ . | Netrw Dir| Messages | Function Stack | . . | | | | RS#2 (5 rows) . | ( a +------------+-----------------+ . | netrw | Source Window | . RL | listing | (prog1.c listing) | RS#3 (wild rows) . | ) | | . . | +-------+---------+------------+ . | | Expr | Breakpt | Watchpoint | . . | | | | | RS#4 (5 rows) +----------+-------+---------+------------+ (25 columns)(..... wild columns .........) There is one WP specifying two windows overlying one another (the "SC-"). ASSEMBLY WINDOW: non-writable *gdbmgr-assembly* {{{2 CODE: A This window shows a disassembly version of the source code surrounding the pc of the selected frame, interleaved with associated source code lines. This window utilizes gdb's "disassemble \m" command. As the default window control (see |gdbmgr-winctrl|) normally does not include the assembly window, one may wish to include it as gdbmgr is running. See |gdbmgr-Dstack| on how to include an assembly window in a running gdbmgr session. Active Keys: > <F1> help for assembly window <c-F6> switch to overlaid window (if any) [#]<c-up> go up frame stack (by # frames) [#]<c-down> go down frame stack (by # frames) c continue running program (gdb's c command) [#]n step to next instruction (gdb's ni command) [#]s step to next instruction (gdb's si command) < BREAKPT WINDOW: non-writable *gdbmgr-breakpt* {{{2 CODE: B One may not write breakpoints directly into the Breakpoints window; its for display only. To enter breakpoints, one presses <F6> or <s-F6> while in the Source window. The current line will then be made into a breakpoint or a temporary breakpoint, respectively. Active Keys: > <F1> help for breakpt window <F6> disable/enable a breakpoint :D b breakpoint-spec enters a breakpoint at the breakpoint-spec :D tbreak breakpoint-spec enters a temporary breakpoint at the breakpoint-spec c open commands gvim for current breakpoint < The breakpoint-spec is the same set of file/line specifications that one may use directly with gdb. *gdbmgr-breakpt-c* *gdbmgr-breakpt-cmd* When the "c" key is pressed while atop a breakpoint in the Breakpoints window a remote server gvim will be opened (see |clientserver|). One may then place gdb commands (after the 3-line header) that, subsequently, will be executed by gdb when the selected breakpoint is reached. CHECKPOINT WINDOW: non-writable *gdbmgr-checkpt* {{{2 CODE: H The checkpoint window shows all available checkpoints. A checkpoint is gdb's way of supporting "undo"; one may return the program and gdb to the state prevailing when a checkpoint was made; much is restored, including changes in memory, registers, and even (within some limits) system state. Things not restored include bytes sent out over ports, bytes written to files, etc. As the default window control (see |gdbmgr-winctrl|) normally does not include the checkpoint window, one may wish to include it as gdbmgr is running. See |gdbmgr-Dstack| on how to include a checkpoint window in a running gdbmgr session. Active Keys: > <F1> help for command window <c-F6> switch to overlaid window (if any) <s-F7> generate a new checkpoint <cr> restart with checkpoint under cursor <del> delete checkpoint under cursor < COMMAND WINDOW: writable *gdbmgr-cmdwin* *gdbmgr-command* {{{2 CODE: C By default, the Commands window is overlaid under the Source window. One may switch to the Commands window using the default window setup by typing > <c-F6> < when the Source window is active. Press <c-F6> again to return to the Source window (ie. when the Commands window is active). One may write commands directly into the Commands window; when one presses a <cr>, the current line will be sent as a command to gdb. This action occurs in either normal or insert modes. Many commands are recorded in the Commands window. One may re-execute them by copying such a line to the last line and pressing a <cr>. Of course, one may edit the Commands window and send new or modified commands, too. The Commands window is most often used when running a program via gdb. The program's output is displayed on the Commands window. In order to allow access to both vim and gdb, one normally would multiplex -- but that would require patching vim. So, there are two alternatives: 1. (default) gdbmgr will poll for updates at a 10Hz rate (ie. every 0.1 seconds) 2. Manual Polling: press <s-F6> with the Commands window active whenever you feel that the program's output may have been updated but not yet displayed. To use this, put > let g:gdbmgr_poll= 0 < into your .vimrc. Active Keys: > <F1> help for command window <c-F6> switch to overlaid window (if any) <s-F6> manual polling -- query gdb for recent output <cr> execute current line (normal or insert modes) <s-F7> generate a checkpoint EXPRESSIONS WINDOW: writable *gdbmgr-expr* *gdbmgr-expressions* {{{2 CODE: E Each line in the Expressions window is an expression which will occasionally be sent on to gdb to find out what its current value is. It will be updated at stoppages (breakpoints, watchpoints, stepping). Simply enter an expression followed by an "=" sign into the Expressions window. That "=" will cause the Expressions window to be updated with the current values. Active Keys: > <F1> help for expressions window <F6> refresh Expressions window (normal mode) <c-F6> switch to overlaid window (if any) = refresh Expressions window (insert mode) < Example: (include the "=" to indicate end of expression) > x = < As an additional way to display variable values: for those whose vim has +balloon_eval (see |balloon-eval|): letting the mouse cursor hover over a variable name in the source window will result in a balloon holding that variable's value. FUNCTION STACK WINDOW: non-writable *gdbmgr-funcstack* *gdbmgr-stack* {{{2 CODE: F This window isn't writable; instead, it is automatically updated with gdb's "where" command at stoppages (such as at prompts and breakpoints). Active keys: > <F1> help for the funcstack window <c-F6> switch to overlaid window (if any) <up> go up frame stack <down> go down frame stack < When the cursor is in the Source or Breakpt windows, one may use > [#]<c-up> go up frame stack [#]<c-down> go down frame stack < to go up and down the frame stack. Note that the Source window will change the current line (and file) to reflect the current frame stack line. MESSAGES WINDOW: non-writable *gdbmgr-mesg* *gdbmgr-messages* {{{2 CODE: M This window shows various messages from gdb. Active keys: > <F1> help for messages window <c-F6> switch to overlaid window (if any) < SOURCE WINDOW: varies *gdbmgr-source* {{{2 CODE: S The source window is used to display various source code files. As one steps through a program, the window is updated. When the program stops running due to a breakpoint, watchpoint, an "until", or otherwise, the source window will be updated to reflect the current file and line. Using the default window configuration, the source window and the command window will be alternately displayed (the source window at stoppages and the command window during program execution). As an additional way to display variable values: for those whose vim has +balloon_eval (see |balloon-eval|): letting the mouse cursor hover over a variable name in the source window will result in a balloon holding that variable's value. Active Keys: > <F1> help for the source window <F6> place/remove breakpoint from current line <s-F6> place/remove temporary-breakpoint from current line <c-F6> switch to overlaid window (if any) <s-F7> generate a checkpoint <F7> toggle editability/gdb mode for source window [#]<c-up> go up frame stack (by # frames) [#]<c-down> go down frame stack (by # frames) c continue running program (gdb's c command) f finish to end of frame (gdb's f command) [#]n step to next instruction (gdb's n command) [#]s step to next instruction (gdb's s command) [#]S step to next instruction (gdb's S command) [#]u execute until the program reaches a source line greater than the current location (gdb's u command) < When the gdb is active and the program has stopped, and if your vim has +balloon_eval (see |+balloon_eval|), then when the cursor hovers over a variable that variable's value will be displayed in a "balloon". The <F7> key can be used to toggle editability/gdb mode; the <F7> is the only gdbmgr source-window map retained when entering editing mode. However, if one edits the source, then the binary no longer matches the source. Hence, line numbers, etc, may be mismatched for the edited source file (at the least). For <s-F7>: see |gdbmgr-checkpt| for more about checkpoints. THREADS WINDOW: non-writable *gdbmgr-threads* {{{2 CODE: T The threads window shows the results of gdb's "info threads" command. As the default window control (see |gdbmgr-winctrl|) normally does not include the threads window, one may wish to include it as gdbmgr is running. See |gdbmgr-Dstack| on how to include a threads window in a running gdbmgr session. Active Keys: > <F1> help for Watchpoint window <F6> refresh Watchpoint window (normal mode) <cr> selects a thread to become the active thread < Activation of a thread uses gdb's "thread #", where # is the gdb-issued number of a thread. WATCHPOINT WINDOW: writable *gdbmgr-watchpt* *gdbmgr-watchpoints* {{{2 CODE: W Each line in the Watchpt window is an expression which will stop the program's execution whenever its value changes. The expressions may optionally be preceded by a letter: > w (write) watchpoint expression follows (default) r read-watchpoint expression follows a both read and write watchpoint expression follows < A "write" watchpoint expression will stop the program when the expression changes value. A read-watchpoint changes when the expression (ie. a variable) is read from. An "a" watchpoint variable acts simultaneously as both a read and write watchpoint. To enter a watchpoint, simply insert the desired watchpoint expression into the Watchpoint window. Follow the expression by an " ="; this lets gdbmgr know that it now has a complete watchpoint expression. It will then install the watchpoint expression in gdb. Active Keys: > <F1> help for Watchpoint window <F6> refresh Watchpoint window (normal mode) <c-F6> switch to overlaid window (if any) = refresh Watchpoint window (insert mode) < Example: (include the "=" to indicate end of expression) > x = r y = < In order to permit expressions containing "="s (such as ==, >=, etc): the expression is considered "finished" when a " =" is encountered, not simply a "=". FOREIGN APPS *gdbmgr-foreignapp* {{{2 Foreign "apps" are applications/vimscripts that are external to gdbmgr itself. Gdbmgr provides interfaces for four such apps: bufexplorer (interface: gdbmgrb.vim) CtagExpl (interface: gdbmgrt.vim). Hdrtag (interface: gdbmgrh.vim), and netrw (the interface is built-in), We'll consider gdbmgrh.vim as an example in what follows. Foreign App Key~ The foreign app key is a letter which designates the application. These letters are used in window primitives (see |gdbmgr-WP|). For gdbmgrh.vim, that key is "h". Foreign App Initialization:~ Assume that the foreign app key is "h": then, upon initialization, a dictionary function (see |E124| and look for [dict]) > gdbmgrh#Init() < will be called. It should, minimally: * open a new unnamed buffer (|:enew|) and name that buffer * set up <c-f6> to support buffer switching * set up its dictionary entry's bufnum member to bufnr("%") Note that this initialization does not need to actually call the foreign application to initialize the contents of the window; see Foreign App Updates below for that. Foreign App Updates:~ Upon updates, a dictionary function > gdbmgrh#Update(srcbufnum) < is called. Updates occur when ctrl-f6 is used to bring the application to the fore, and is used to initialize the Foreign App window's contents. Foreign applications often need to modify and/or select the source; thus the foreign app update function is passed the source's buffer number. One may use this with: > let Hwin= bufwinnr(a:srcbufnum) : get window associated with the source buffer self.bufnum : the buffer number associated with the foreign app exe Hwin."wincmd w" : switch to the foreign app "H"'s window < Foreign App Function Reference:~ The foreign app may change the file and/or line number in the Source window; however, Source windows are expected to support various maps under gdbmgr. The foreign application also needs to register the (new) source buffer with gdbmgr's window registry (dictionary). The easiest way for a foreign app to do this is for it to support the use of function references when it makes a source file change; then the foreign app initialization function can set up the function reference to have the foreign app call gdbmgr#ForeignAppFuncRef(). CtagExpl: g:CtagExpl_funcref (called after CtagExpl opens a file for editing) Hdrtag : g:Hdrtag_funcref (called after Hdrtag opens a file for editing) Netrw : |g:Netrw_funcref| (called after netrw opens a file for editing) For example, the Hdrtag explorer contains in its initialization function: > let g:Hdrtag_funcref= function("gdbmgr#ForeignAppFuncref") < to do this. You may get CtagExpl from http://www.drchip.org/astronaut/vim/index.html#CTAGEXPL It works with plain ctags and exuberant ctags (see |Exuberant_ctags|). You may get Hdrtag from http://www.drchip.org/astronaut/vim/index.html#HDRTAGEXPLORER The Hdrtag plugin uses the hdrtag program, available from http://www.drchip.org/astronaut/src/index.html#HDRTAG You'll need to compile it. BUFEXPLORER WINDOW: non-writable *gdbmgr-bufexplorer* {{{2 CODE: b Jeff Lanzarotta's bufexplorer is supported by gdbmgr as a "foreign app". > ( http://www.vim.org/scripts/script.php?script_id=42 ) < As of bufexplorer version 7.2.8, bufexplorer and gdbmgr work together with no patches required. Gdbmgr and bufexplorer cooperate by gdbmgr's setting up a function reference (|Funcref|) (|g:BufExplorerFuncRef|) and a variable (|g:bufExplorerFindActive|); normal operation of bufexplorer is unaffected when these variables are left unset. (the latter two links should work if you have bufexplorer) To use JL's bufexplorer with gdbmgr, use the window control string with the "b" code (see |gdbmgr-winctrl|), or one may wish to include it as gdbmgr is running. See |gdbmgr-Dstack| on how to include a bufexplorer window in a running gdbmgr session. bufexplorer code b uses gdbmgrb.vim~ For example, the following window control list makes use of a bufexplorer window: (see |gdbmgr-winctrl|) > [['c25','r-,Nb-'],['c-','r5,M-,F-','r-,SC-','r5,E-,B-,W-']] < Upon startup, gdbmgr will be showing a netrw window on the far left of display; to see the bufexplorer there, make that window active and then press the <ctrl-f6> key. NETRW WINDOW: non-writable *gdbmgr-netrw* {{{2 CODE: N The netrw window holds directory listings as provided by the netrw plugin. Selection of a file will display it in the Source window (|gdbmgr-source|). There are a large number of active keys in this window, but they're nearly all provided by netrw, not gdbmgr, except for one. The netrw is internally coded as a "foreign app". Additional Active Key: > <c-F6> switch to overlaid window (if any) < TAGS WINDOW: non-writable *gdbmgr-tags* {{{2 CODE: h (hdrtags) CODE: t (ctags) There are actually two types of tags windows; one is for hdrtag, and the other is for ctags. These are "foreign app" windows; ie. they are supported by code outside the main gdbmgr.vim plugin. Use the window control string to set them up. As the default window control (see |gdbmgr-winctrl|) normally does not include either of the tags windows, one may wish to include a tags window as gdbmgr is running. See |gdbmgr-Dstack| on how to include a new window in a running gdbmgr session. ctags: code t uses gdbmgrt.vim {{{3 ~ A sample window control list making a t-style tags window available: > [['c25','r-,Nt-'],['c-','r5,M-,F-','r-,SC-','r5,E-,B-,W-']] < This list will overlay the netrw and tags buffers in one window on the left, with netrw showing on top at startup. Use <c-f6> to switch with the cursor in the netrw/ctags window. The window uses the CtagExpl.vim plugin (see |CtagExpl|). The CtagExpl plugin preferentially uses a pre-existing tags file, so one may run ctags over all the files in a project. To use CtagExpl, you need: CtagExpl.vim : http://www.drchip.org/astronaut/vim/index.html#CTAGEXPL gdbmgrt.vim : comes with the gdbmgr plugin package hdrtag: code h uses gdbmgrh.vim {{{3 ~ Sample window control list making a h-style tags window available: > [['c25','r-,Nh-'],['c-','r5,M-,F-','r-,SC-','r5,E-,B-,W-']] < This list will overlay the netrw and tags buffers in one window on the left, with netrw showing on top at startup. Use <c-f6> to switch with the cursor in the netrw/hdrtag window. The window uses the Hdrtag.vim plugin (see |hdrtag|). Like CtagExpl, the Hdrtag plugin preferentially uses a pre-existing tags file, so one may run hdrtag over all the files in a project. You can get hdrtag from: http://www.drchip.org/astronaut/src/index.html and clicking on > hdrtag.tar.gz < To use Hdrtag, you need: hdrtag : see website just above Hdrtag.vim : http://www.drchip.org/astronaut/vim/index.html#HDRTAG gdbmgrh.vim : comes with the gdbmgr plugin package GDBMGR OPTIONS *gdbmgr-options* {{{2 *g:gdbmgr_bexpr_priority* (default: does not exist) If this variable exists, then gdbmgr will override any previously existing |'bexpr'| value. It may, however, be itself overridden by a plugin which is loaded later. *g:gdbmgr_clearansi* (default=1) By default, gdbmgr will remove Ansi colorizing sequences from the Commands window. They're popular for prompts, but make a mess on the Commands window. Future work: to test if the currently running vim supports conceal mode (has("conceal") is true). In that case the colorizing and spacing can be made correct. (see the AnsiEsc plugin at http://www.drchip.org/astronaut/vim/index.html#ANSIESC ) *g:gdbmgr_poll* (default=1) polling is enabled if true. If you'd rather do manual polling, set this variable to 0 and use <s-F6> when in the Commands window. *g:gdbmgr_srcpath* a comma-delimited sequence of directories which hold source code files. This path is also given to gdb via its "directory" command so it too can search for source files. *g:gdbmgr_nobeval* (default: doesn't exist, balloon evaluation is enabled) By letting this variable exist, gdbmgr will not use balloon evaluation. (see |'beval'|) KNOWN LIMITATIONS *gdbmgr-limitations* {{{2 * One known limitation: gdbmgr supports resizing by using the window control string; however, if one had changed the window layout (via :q, :split, etc) then the window control string is unlikely to be correct. Subsequently resizing the vim window is then unlikely to work nicely. * Editing a source file when using gdbmgr invalidates the associated executable binary which gdbmgr and gdb are using. As a result, line numbers, breakpoints, assembly, etc are problematic. * Issuing the following commands to gdb will undoubtedly cause difficulties: D set annotate -- gdbmgr sets the annotation level to 3; changing it will invalidate the finite state automata in gdbmgr.c D set height -- gdbmgr sets height to 0 so that gdb won't be inserting unwanted newlines and prompts. Changing height to non-zero is likely to cause "unexpected behavior" messages from gdbmgr. D set width -- gdbmgr sets width to 0 so that gdb won't be inserting unwanted newlines and prompts. Changing width to non-zero is likely to cause "unexpected behavior" messages from gdbmgr. ============================================================================== 5. gdbmgr History *gdbmgr-history* {{{1 v2 Nov 02, 2012 * protected all |:windo| operations with |:noautocmd| Jul 02, 2015 * changed %d to %d _ (delete to blackhole register) Jul 08, 2015 * changed %15s to %15S in a few printf() calls Feb 18, 2016 * changed =~ to =~# where appropriate v1 Jan 16, 2009 * initial alpha release Mar 30, 2010 * Given :DI with no arguments, will look for an executable in the current directory Jul 08, 2010 * added balloon display Aug 09, 2010 * included cecutil as part of the distribution Sep 22, 2010 * prevented a hang-up when trying to set a breakpoint in a source file not compiled for debugging. Also included a note about how to automate having GdbMgr handle executable files (|gdbmgr-suggest|) Oct 14, 2010 * Command window works better * Netrw+Source+breakpoints work better * GdbMgrForeground was only handling two overlays; a third was causing an infinite loop. Fixed. Oct 18, 2010 * Included a core dump example, plus some improved initialization when working with core dumps. Oct 19, 2010 * Improved :DA (for attaching to external processes) (rejection of plain newlines from gdb as responses, confirm()-based selection of multiple programs, confirm()-based selection of same-name files in various libraries, etc) Oct 20, 2010 * Using s:GdbMgr[Open|Closed]CodedBuf more often Oct 26, 2010 * Implemented Threads window. * Debugged problem with text disappearing from currently hidden windows (due to s:GdbMgrCloseCodedBuf using "sil q!" instead of "sil! q") * Moved "foreign apps"' codes (hdrtag, ctagexpl, bufexplorer) to lower case letters (h, t, and b, respectively). Oct 27, 2010 * Wrote a number of syntax highlighting files for several of the windows. Oct 28, 2010 * Annoyance: SourceInitFile would ask "Select which <file>" given multiple choices,more than once per function. Installed a dictionary so that gdbmgr would remember which file a function came from. Nov 09, 2010 * Numerous changes to gdbmgr.c to regularize the finite state automaton, and corresponding changes to gdbmgr.vim. Gdbmgr.c now initializes gdb with set width 0 to avoid unwanted wrapping of output. Nov 17, 2010 * Dstack and Dunstack commands implemented (see |gdbmgr-Dstack| and |gdbmgr-Dunstack|) * (dis)Assembly coded buffer included (code A) * s:GdbMgrVimResized() ends with the cursor in the S buffer; the menu now reflects that Nov 18, 2010 * Fixed some stacking/unstacking bugs associated with foreign app buffers * Bufexplorer window wasn't updating properly when a new source buffer was edited Nov 23, 2010 * Included capability to enable/disable breakpoints Dec 15, 2010 * D commands ... D end now works * Included CA, CB, CH, ... CW go-to-code commands and menu entries Dec 20, 2010 * Remote gvim support for breakpoint commands included (see |gdbmgr-breakpt-c|) Jun 02, 2011 * Bypassed |'spr'| and |'sb'| options during WinCtrl() vim: fdm=marker cole=3