*conque_gdb.txt*    Vim version 7.3   Last change: 2013 May 7

This help file explains the Conque GDB Vim plugin.

==============================================================================

Introduction

The Conque GDB plugin extends the Conque (Conque Term) plugin. Like Conque
Term, Conque GDB is a terminal emulator. The |ConqueGdb|, |ConqueGdbSplit|,
|ConqueGdbVsplit| and |ConqueGdbTab| commands will turn a Vim buffer into a
GDB command line interface (CLI).

When debugging a program with one of the |ConqueGdb|* commands, Conque GDB will
automatically open the appropriate source files when break points are hit,
and highlight the line where program execution has stopped. And if you install
Conque GDB on a Unix system with GDB 7.0+ compiled with python support, Conque
GDB will place signs on lines to mark where you have placed break points.

Conque GDB ships with a modified version of Conque Term 2.3. This new version
of Conque Term comes with new options and new features. Please see the
|conque_term.txt| help file for help regarding Conque Term. Most of the Conque
Term options also apply to Conque GDB, so even if you don't plan on using
Conque Term it's a good idea to take a look at the Conque Term options.
Especially regarding the |ConqueTerm_ReadUnfocused| option, which is now fully
functional.

==============================================================================

Contents

1. Installation                              |conque-gdb-setup|
   1.1 Requirements for Unix                 |conque-gdb-unix-requirements|
   1.2 Requirements for Windows              |conque-gdb-window-requirements|
   1.3 Vimball installation                  |conque-gdb-installation|
2. Usage                                     |conque-gdb-usage|
   2.1 Opening Conque GDB CLI                |conque-gdb-open|
   2.2 Delete unneeded buffers               |conque-gdb-delete-buffers|
   2.3 Send command to GDB                   |conque-gdb-command|
   2.4 Send command to GDB                   |conque-gdb-exe|
3. Options                                   |conque-gdb-options|
   3.1 GDB Source code split                 |conque-gdb-src-split|
   3.2 Path to GDB                           |conque-gdb-path|
   3.3 Disable GDB commands                  |conque-gdb-disable|
   3.4 Save command history                  |conque-gdb-save-history|
   3.5 Set Read Timeout For GDB Resposes     |conque-gdb-read-timeout|
   3.6 Keyboard Mappings                     |conque-gdb-mappings|
       3.6.1 Mappings leader                 |conque-gdb-leader|
       3.6.2 Run program mapping             |conque-gdb-run-mapping|
       3.6.3 Continue program mapping        |conque-gdb-continue-mapping|
       3.6.4 Next line mapping               |conque-gdb-next-mapping|
       3.6.5 Step line mapping               |conque-gdb-step-mapping|
       3.6.6 Print identifier under cursor   |conque-gdb-print-mapping|
       3.6.7 Toggle break point mapping      |conque-gdb-toggle-mapping|
       3.6.8 Set break point mapping         |conque-gdb-break-mapping|
       3.6.9 Delete break point mapping      |conque-gdb-delete-break-mapping|
       3.6.10 Finish mapping                 |conque-gdb-finish-mapping|
       3.6.11 Backtrace mapping              |conque-gdb-backtrace-mapping|
4. Custom key mappings                       |conque-gdb-custom-key-mappings|

==============================================================================

1. Installation                              *conque-gdb-setup*

Conque GDB works on both Unix and Windows. The requirements are slightly
different though. Note that Conque GDB supports some features on Unix which
are not supported on Windows.

1.1 Requirements for Unix                    *conque-gdb-unix-requirements*

 * [G]Vim 7.3+ with +python
 * Python 2.3+
 * Unix-like OS: Linux, OS X, Solaris, Cygwin, etc
 * GDB 7.0+ (see note below)

Note: Conque GDB actually works with older versions of GDB (GDB 6.3+).
However GDB 7.0+ is recommended since it is likely to support all the Conque
GDB features.

Even tough you have GDB 7.0+ installed on your system it is not 100% sure that
it will support all the Conque GDB features, namely the ability to place signs
on lines to mark where break points are currently placed. If you encounter
this problem with GDB 7.0+ installed on your system, then go ahead and build
GDB 7.0+ from source with python support by specifying the '--with-python'
configuration option.

1.2 Requirements for Windows                 *conque-gdb-windows-requirements*

 * [G]Vim 7.3 with +python
 * Python 2.7
 * Modern Windows OS (XP or later)
 * MinGW GDB 7.0+

See http://www.mingw.org/wiki/Getting_Started for an explanation on how to
install MinGW. If you don't install MinGW in the C:\MinGW directory and you
haven't specified a path to the path\to\MinGW\bin directory in your PATH
environment variable. Then you have to tell Conque GDB where MinGW GDB is
installed on your system. See the |ConqueGdb_GdbExe| option for an explanation
on how to do this.

1.3 Vimball Installation                     *conque-gdb-installation*

Download the latest conque_gdb.vmb vimball from http://www.vim.org.

Open conque_gdb.vmb with Vim and run the following commands:
>
    :so %
    :q
<
Next time you open Vim the |ConqueTerm|* and |ConqueGdb|* commands will be
available.

==============================================================================

2. Usage                                     *conque-gdb-usage*

This section describes the usage of Conque GDB. See the Conque Term specific
file |conque_term.txt|, for Conque Term usage.

2.1 Opening Conque GDB CLI                   *conque-gdb-open* 
                                             *ConqueGdb*    *ConqueGdbVSplit* 
                                             *ConqueGdbTab* *ConqueGdbSplit*

Type :ConqueGdb <gdb-arguments> to launch GDB in the current window. E.g.:
>
    :ConqueGdb
    :ConqueGdb program
    :ConqueGdb -d dir --args program [arguments] 
<
Use :ConqueGdbSplit or :ConqueGdbVSplit to open GDB in a new horizontal or
vertical buffer. When opening GDB with one of the split commands, it will
use the current window as its destination window for source files when
break points are hit. Use :ConqueGdbTab to open GDB in a new tab.

When issuing the :ConqueGdbTab or :ConqueGdb commands Conque GDB will open a
new split window for the source files. See |g:ConqueGdb_SrcSplit| to change how
Conque should split the GDB window.

2.2 Delete unneeded buffers                  *conque-gdb-delete-buffers*
                                             *ConqueGdbBDelete*

Once you have debugged a program with one of the |ConqueGdb|* commands, you
might experience that a lot of new source files have been opened in buffers.
If you want Conque to get rid of some of these buffers, you can use the
|ConqueGdbBDelete| command. This command deletes the buffers ConqueGdb opened
while you were debugging.

Note that only buffers opened by Conque GDB will be deleted, and if you have
modified a buffer opened by Conque GDB, this buffer will not be deleted either.
>
    :ConqueGdbBDelete
>
2.3 Send command to GDB                      *conque-gdb-command*
                                             *ConqueGdbCommand*

If you are currently outside the GDB CLI window and would like to send a
command to GDB use |ConqueGdbCommand| to send any command to GDB. E.g.
>
    :ConqueGdbCommand disable 1
>
This will only work properly if the |ConqueTerm_ReadUnfocused| option is
enabled. See the help file |conque_term.txt| for information.

2.4 Set path to GDB                          *conque-gdb-exe*
                                             *ConqueGdbExe*

If switch is needed between different GDB executables, for instance, during
cross-development, you can specify path to a GDB executable as follows:
>
    :ConqueGdbExe /path/to/gdb-cross
    :ConqueGdbExe
>
When zero arguments are given to the |ConqueGdbExe| command, Conque GDB will
use the default path to GDB, as specified by the |g:ConqueGdb_GdbExe| option
on startup. See |g:ConqueGdb_GdbExe|.
==============================================================================

3. Options                                   *conque-gdb-options*

This section describes the modifiable options Conque Gdb offers. Please take
a look at the |conque_term.txt| help file for Conque Term options. Most of
these options also apply to Conque Gdb.

3.1 GDB Source code split                    *conque-gdb-src-split*
                                             *g:ConqueGdb_SrcSplit*

When Conque GDB splits the GDB CLI window to open source files it will by
defaut split the window such that the source code will appear above the GDB
CLI window. You can change the value of |g:ConqueGdb_SrcSplit| to 'above',
'below', 'left' or 'right' if you want Conque GDB to split the GDB window
such that the source code will spilt above, below, left or right to the
GDB CLI window.
>
    let g:ConqueGdb_SrcSplit = 'above'
<
3.2 Path to GDB                              *conque-gdb-path*
                                             *g:ConqueGdb_GdbExe*

If the |ConqueGdb| commands can't find GDB in the system path, then you might
need to specify the path to the GDB executable manually. However on Windows
Conque will also look for GDB in C:\MinGW\bin. To define the path to the GDB
executable you can change the value of |g:ConqueGdb_GdbExe|. By default this
option is:
>
   let g:ConqueGdb_GdbExe = ''
<
Note that you have to restart Vim before changes to |g:ConqueGdb_GdbExe| are
recognized. If you would like to change path to the GDB executable at runtime,
use the |ConqueGdbExe| command.

3.3 Disable GDB commands                     *conque-gdb-disable*
                                             *g:ConqueGdb_Disable*

With this option you can disable the Conque GDB plugin. By default it is
enabled:
>
    let g:ConqueGdb_Disable = 0
<
3.4 Save command history                     *conque-gdb-save-history*
                                             *g:ConqueGdb_SaveHistory*

With this option you can tell whether Conque GDB should save history of
commands that are issued by keyboard mappings. By default the keyboard mapping
command history is not saved, which implies you will not see the commands
issued by keyboard mappings when pressing <Up> to view previous GDB commands
in the CLI window.
>
    let g:ConqueGdb_SaveHistory = 0

3.5 Set Read Timeout For GDB Resposes        *conque-gdb-read-timeout*
                                             *g:ConqueGdb_ReadTimeout*

This will allow you to set the timeout before Conque GDB tries to read output
from GDB. You may have to change the time depending on the amount of output
GDB makes and system performance. The default is 50 milliseconds.

    let g:ConqueGdb_ReadTimeout = 50


3.6 Keyboard Mappings                        *conque-gdb-mappings*

Conque GDB defines keyboard mappings to some of the most common gdb commands.
By default these Keyboard mappings use the |mapleader| (|<leader>|) as prefix.
However you can change this with the |g:ConqueGdb_Leader| option.

Note that you need to enable the |ConqueTerm_ReadUnfocused| option for the
keyboard mappings to work properly. See the help file |conque_term.txt|.

3.6.1 Mappings leader                        *conque-gdb-leader*
                                             *g:ConqueGdb_Leader*

This option specifies which keyboard key is used as prefix for the Conque GDB
keyboard mappings described below. By default it is:
>
    let g:ConqueGdb_Leader = '<Leader>'
>
Note that |<Leader>| is usually defined as \ (backslash). You don't have to
use the |g:ConqueGdb_Leader| when defining new keyboard mappings as described
below.

3.6.2 Run program mapping                    *conque-gdb-run-mapping*
                                             *g:ConqueGdb_Run*

This option defines the keyboard mapping used to issue the GDB command run
from any buffer. By default this is:
>
    let g:ConqueGdb_Run = g:ConqueGdb_Leader . 'r'
>
3.6.3 Continue program mapping               *conque-gdb-continue-mapping*
                                             *g:ConqueGdb_Continue*

This option defines the mapping used to issue the continue command. This
is by default:
>
    let g:ConqueGdb_Continue = g:ConqueGdb_Leader . 'c'
>
3.6.4 Next line mapping                      *conque-gdb-next-mapping*
                                             *g:ConqueGdb_Next*

Mapping to issue GDB command next. Default:
>
    let g:ConqueGdb_Next = g:ConqueGdb_Leader . 'n'
>
3.6.5 Step line mapping                      *conque-gdb-step-mapping*
                                             *g:ConqueGdb_Step*

Mapping to send the step command to GDB. Default:
>
    let g:ConqueGdb_Step = g:ConqueGdb_Leader . 's'
>
3.6.6 Print identifier under cursor          *conque-gdb-print-mapping*
                                             *g:ConqueGdb_Print*

This mapping is used to issue the print GDB command, to print value of the
identifier under the cursor. By default it is:
>
    let g:ConqueGdb_Print = g:ConqueGdb_Leader . 'p'
>
3.6.7 Toggle break point mapping             *conque-gdb-toggle-mapping*
                                             *g:ConqueGdb_ToggleBreak*

This is a special mapping used to toggle a break point on the current line.
I.e. if there is a break point on the current line already it will delete
the break point, otherwise it will create a new break point on the current
line.

This mapping is only supported on Unix having GDB 7.0+ with full python
support. See |conque-gdb-unix-requirements|. By default this mapping is:
>
    let g:ConqueGdb_ToggleBreak = g:ConqueGdb_Leader . 'b'
>
3.6.8 Set break point mapping                *conque-gdb-break-mapping*
                                             *g:ConqueGdb_SetBreak*

This mapping is specific to Conque GDB installations on Windows and Unix
systems where GDB does not have full python support. See |conque-gdb-setup|.

It will issue the GDB command break to place a break point on the current
line. By default this mapping is:
>
    let g:ConqueGdb_SetBreak = g:ConqueGdb_Leader . 'b'
>
3.6.9 Delete break point mapping             *conque-gdb-delete-break-mapping*
                                             *g:ConqueGdb_DeleteBreak*

This mapping is specific to Conque GDB installations on Windows and Unix
systems where GDB does not have full python support. See |conque-gdb-setup|.

It will issue the GDB command clear to delete the break point on the current
line. Default:
>
    let g:ConqueGdb_DeleteBreak = g:ConqueGdb_Leader . 'd'
>
3.6.10 Finish mapping                              *conque-gdb-finish-mapping*
                                                   *g:ConqueGdb_Finish*

Mapping to issue the finish command. Default:
>
    let g:ConqueGdb_Finish = g:ConqueGdb_Leader . 'f'
>
3.6.11 Backtrace mapping                        *conque-gdb-backtrace-mapping*
                                                *g:ConqueGdb_Backtrace*

Mapping to execute the backtrace command. By default it is:
>
    let g:ConqueGdb_Backtrace = g:ConqueGdb_Leader . 't'
>
4. Custom key mappings                        *conque-gdb-custom-key-mappings*

This section shows you how you can use |ConqueGdbCommand| to setup your
own customized Conque GDB key mappings.

You might want to be able answer GDB confirmations (say y or n) without
having to go to the Conque GDB window. You can use the |ConqueGdbCommand|
command to achieve this:
>
    nnoremap <silent> <Leader>Y :ConqueGdbCommand y<CR>
    nnoremap <silent> <Leader>N :ConqueGdbCommand n<CR>
>
With those 2 lines in your vimrc file you can type the leader key followed
by a capital Y to answer yes to GDB confirmations and leader followed by
capital N to answer no to GDB confirmations.

==============================================================================

vim:tw=78:ts=8:ft=help:norl:
