terminal.txt For Vim version 8.1. Last change: 2018 May 17
VIM REFERENCE MANUAL by Bram Moolenaar
Terminal window support terminalterminal-window
The terminal feature is optional, use this to check if your Vim has it:
echo has('terminal')
If the result is "1" you have it.
1. Basic use terminal-use
Typing terminal-typing
Size and color terminal-size-colorSyntax:terminal
Resizing terminal-resizing
Terminal Modes Terminal-mode
Cursor style terminal-cursor-styleSessionterminal-sessionSpecial keys terminal-special-keysUnixterminal-unixMS-Windowsterminal-ms-windows
2. Terminal communication terminal-communication
Vim to job: term_sendkeys()terminal-to-jobJob to Vim: JSON API terminal-api
Using the client-server feature terminal-client-server
3. Remote testingterminal-testing
4. Diffing screen dumps terminal-diff
Writing a screen dump test for Vim terminal-dumptest
Creating a screen dump terminal-screendump
Comparing screen dumps terminal-diffscreendump
5. Debugging terminal-debug
Starting termdebug-starting
Example session termdebug-example
Stepping through code termdebug-stepping
Inspecting variablestermdebug-variables
Other commands termdebug-commands
Prompt mode termdebug-prompt
Communication termdebug-communication
Customizing termdebug-customizing{Vi does not have any of these commands}{only available when compiled with the |+terminal| feature}
The terminal feature requires the +multi_byte,+job and +channel features.
==============================================================================
1. Basic use terminal-use
This feature is for running aterminal emulator in a Vim window. Ajob can be
started connected to the terminal emulator. For example, to run a shell:
:term bash
Or to run build command:
:term make myprogram
The job runs asynchronously from Vim, the window will be updated to show
output from the job, also while editing in another window.
Typing terminal-typing
When the keyboard focus is in the terminal window, typed keys will be sent to
the job. This uses a pty when possible. You can click outside of the
terminalwindow to move keyboard focus elsewhere.
CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.:
CTRL-WCTRL-W move focus to the next windowCTRL-W: enter an Ex command
See CTRL-W for more commands.
Special in the terminal window: CTRL-W_.CTRL-W_NCTRL-W. send aCTRL-W to the job in the terminalCTRL-WCTRL-\ send aCTRL-\ to the job in the terminalCTRL-WNgo to Terminal-Normal mode, see Terminal-modeCTRL-\CTRL-Ngo to Terminal-Normal mode, see Terminal-modeCTRL-W " {reg} paste register{reg}CTRL-W_quote
Also works with the =register to insert the result of
evaluating an expression.
CTRL-WCTRL-C ends the job, see below t_CTRL-W_CTRL-C
See option 'termwinkey' for specifying another key instead of CTRL-W that
will work like CTRL-W. However, typing 'termwinkey'twice sends 'termwinkey'
to the job. For example:
'termwinkey'CTRL-W move focus to the next window'termwinkey': enter an Ex command
'termwinkey''termwinkey' send 'termwinkey' to the job in the terminal'termwinkey'. send 'termwinkey' to the job in the terminal'termwinkey'CTRL-\ send aCTRL-\ to the job in the terminal'termwinkey'Ngo to terminalNormal mode, see below
'termwinkey'CTRL-N same asCTRL-WN'termwinkey'CTRL-C same ast_CTRL-W_CTRL-Ct_CTRL-\_CTRL-N
The special key combination CTRL-\CTRL-N can be used to switch to Normal
mode, just like this works in any other mode.
t_CTRL-W_CTRL-CCTRL-WCTRL-C can be typed to forcefully end the job. On MS-WindowsaCTRL-BREAK will also kill the job.
If you type CTRL-C the effect depends on what the pty has been configured to
do. For simple commands this causes a SIGINT to be sent to the job, which
would end it. Other commands may ignore the SIGINT or handle the CTRL-C
themselves (like Vim does).
To change the keys you type use terminal mode mappings, see :tmap.
These are defined like any mapping, but apply only when typing keys that are
sent to the job running in the terminal. For example, to make F1 switch
to Terminal-Normal mode:
tnoremap <F1> <C-W>N
You can use Esc, but you need to make sure it won't cause other keys to
break (cursor keys start with an Esc, so they may break):
tnoremap <Esc> <C-W>N set notimeout ttimeout timeoutlen=100
You can also create menus similar to terminal mode mappings, but you have to
use :tlmenu instead of :tmenu.<options-in-terminal
After opening the terminalwindow and setting 'buftype' to "terminal" the
TerminalOpenautocommand event is triggered. This makes it possible to set
options specifically for the window and buffer. Example:
au TerminalOpen * if &buftype == 'terminal' | setlocal bufhidden=hide | endif
The <abuf>is set to the terminal buffer, but if there is no window (hidden
terminal) then setting options will happen in the wrong buffer, therefore the
check for &buftype in the example.
Mouse events (click and drag) are passed to the terminal. Mouse move events
are only passed when Vim itself is receiving them. For aterminal that is
when 'balloonevalterm'is enabled.
Size and color terminal-size-color
See option 'termwinsize' for controlling the size of the terminal window.
(TODO: scrolling when the terminalis larger than the window)
The job running in the terminal can change the colors. The default foreground
and background colors are taken from Vim, the Normal highlight group.
For a color terminal the 'background' option is used to decide whether the
terminalwindow will start with a white or black background.
To use a different color the Terminal highlight group can be used, for
example:
hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blueg:terminal_ansi_colors
In GUI mode or with 'termguicolors', the 16 ANSI colors used by default in new
terminalwindows may be configured using the variable
g:terminal_ansi_colors, which should be alist of 16 color names or
hexadecimal color codes, similar to those accepted by highlight-guifg. When
not using GUI colors, the terminalwindow always uses the 16 ANSI colors of
the underlying terminal.
The term_setansicolors() function can be used to change the colors, and
term_getansicolors() to get the currently used colors.
Syntax
:[range]ter[minal] [options][command]:ter:terminal
Open a new terminal window.
If [command]is provided run itasajob and connect
the input and output to the terminal.
If [command]is not given the 'shell' option is used.
if [command]is NONE no jobis started, the pty of the
terminal can be used by a command like gdb.
If [command]is missing the default behavior is to
close the terminal when the shell exits. This can be
changed with the ++noclose argument.
If [command]is present the default behavior is to
keep the terminal open in Terminal-Normal mode. This
can be changed with the ++close argument.
A new buffer will be created, using [command] or
'shell'as the name, prefixed with a "!". If a buffer
by this name already exists a number is added in
parentheses. E.g. if "gdb" exists the second terminal
buffer will use "!gdb (1)".
If [range]is given the specified lines are used as
input for the job. It will not be possible to type
keys in the terminal window. For MS-Windows see the
++eof argument below.
term++closeterm++open
Supported [options] are:
++close The terminalwindow will close
automatically when the job terminates.
++noclose The terminalwindow will NOT close
automatically when the job terminates.
++open When the job terminates and no window
shows it, awindow will be opened.
Note that this can be interruptive.
The last of ++close, ++noclose and ++open
matters and rules out earlier arguments.
++curwin Open the terminal in the current
window, do not split the current
window. Fails if the current buffer
cannot be abandoned.
++hidden Open the terminal in a hidden buffer,
no window will be used.
++norestore Do not include this terminalwindow
in a session file.
++kill={how} When trying to close the terminalwindow kill the job with {how}. See
term_setkill() for the values.
++rows={height} Use {height} for the terminalwindow
height. If the terminal uses the full
Vim height (no window above or below
the terminal window) the command line
height will be reduced as needed.
++cols={width} Use {width} for the terminalwindow
width. If the terminal uses the full
Vim width (no window left or right of
the terminal window) this value is
ignored.
++eof={text} when using [range]: text to send after
the last line was written. Cannot
contain white space. A CR is
appended. For MS-Windows the default
is to send CTRL-D.
E.g. for a shell use "++eof=exit" and
for Python "++eof=exit()".Special
codes can be used like with :map,
e.g. "<C-Z>" for CTRL-Z.
If you want to use more options use the term_start()
function.
If you want to split the window vertically, use:
:vertical terminal
Or short:
:vert ter
When the buffer associated with the terminalis forcibly unloaded or wiped out
the jobis killed, similar to calling `job_stop(job, "kill")` .
Closing the window normally results in E947. When a kill method was set
with "++kill={how}" or term_setkill() then closing the window will use that
way to kill or interrupt the job. For example:
:term ++kill=term tail -f /tmp/log
So long as the jobis running the window behaves like it contains a modified
buffer. Trying to close the window with `CTRL-W :quit` fails. When using
`CTRL-W :quit!` the jobis ended. The text in the windowis lost. The buffer
still exists, but getting it in awindow with :buffer will show an empty
buffer.
Trying to close the window with `CTRL-W :close` also fails. Using
`CTRL-W :close!` will close the window and make the buffer hidden.
You can use `CTRL-W :hide` to close the terminalwindow and make the buffer
hidden, the job keeps running. The :buffer command can be used to turn the
current window into aterminal window. If there are unsaved changes this
fails, use ! to force, as usual.
To have a background job run without a window, and open the window when it's
done, use options like this:
:term ++hidden ++open makeNote that the window will open at an unexpected moment, this will interrupt
what you are doing.
E947E948
So long as the jobis running, the buffer is considered modified and Vim
cannot be quit easily, see abandon.
When the job has finished and no changes were made to the buffer: closing the
window will wipe out the buffer.
Before changes can be made to aterminal buffer, the 'modifiable' option must
be set. This is only possible when the job has finished. At the first change
the buffer will become a normal buffer and the highlighting is removed.
You may want to change the buffer name with :file to be able to write, since
the buffer name will still be set to the command.
Resizing terminal-resizing
The size of the terminal can be in one of three modes:
1. The 'termwinsize' option is empty: The terminal size follows the window
size. The minimal size is 2 screen lines with 10 cells.
2. The 'termwinsize' option is "rows*cols", where "rows" is the minimal number
of screen rows and "cols" is the minimal number of cells.
3. The 'termwinsize' option is "rowsXcols" (where the xis upper or lower
case). The terminal size is fixed to the specified number of screen lines
and cells. If the windowis bigger there will be unused empty space.
If the windowis smaller than the terminal size, only part of the terminal can
be seen (the lower-left part).
The term_getsize() function can be used to get the current size of the
terminal. term_setsize() can be used only when in the first or second mode,
not when 'termwinsize'is "rowsXcols".Terminal-Job and Terminal-Normal mode Terminal-modeTerminal-Job
When the jobis running the contents of the terminalis under control of the
job. That includes the cursor position. Typed keys are sent to the job.
The terminal contents can change at any time. This is called Terminal-Job
mode.
Use CTRL-WN (or 'termwinkey' N) to switch to Terminal-Normal mode. Now the
contents of the terminalwindowis under control of Vim, the job output is
suspended. CTRL-\CTRL-N does the same.
Terminal-Job mode is where :tmap mappings are applied. Keys sent by
term_sendkeys() are not subject to tmap, but keys from feedkeys() are.
It is not possible to enter Insert mode from Terminal-Job mode.
Terminal-NormalE946
In Terminal-Normal mode you can move the cursor around with the usual Vim
commands, Visually mark text, yank text, etc. But you cannot change the
contents of the buffer. The commands that would start insert mode, such as
'i' and 'a', return to Terminal-Job mode. The window will be updated to show
the contents of the terminal. :startinsertis ineffective.
In Terminal-Normal mode the statusline and window title show "(Terminal)". If
the job ends while in Terminal-Normal mode this changes to
"(Terminal-finished)".
When the job outputs lines in the terminal, such that the contents scrolls off
the top, those lines are remembered and can be seen in Terminal-Normal mode.
The number of lines is limited by the 'termwinscroll' option. When going over
this limit, the first 10% of the scrolled lines are deleted and are lost.
Cursor style terminal-cursor-style
By default the cursor in the terminalwindow uses a not blinking block. The
normal xterm escape sequences can be used to change the blinking state and the
shape. Once focus leaves the terminalwindow Vim will restore the original
cursor.
An exception is when xterm is started with the "-bc" argument, or another way
that causes the cursor to blink. This actually means that the blinking flag
is inverted. Since Vim cannot detect this, the terminalwindow cursor
blinking will also be inverted.
Session terminal-sessionAterminalwindow will be restored when using a session file, if possible and
wanted.
If "terminal" was removed from 'sessionoptions' then no terminalwindows will
be restored.
If the job in the terminal was finished the window will not be restored.
If the terminal can be restored, the command that was used to open it will be
used again. To change this use the term_setrestore() function. This can
also be used to not restore a specific terminal by setting the command to
"NONE".Special keys terminal-special-keys
Since the terminal emulator simulates an xterm, only escape sequences that
both Vim and xterm recognize will be available in the terminal window. If you
want to pass on other escape sequences to the job running in the terminal you
need to set up forwarding. Example:
tmap <expr> <Esc>]b SendToTerm("\<Esc>]b") func SendToTerm(what) call term_sendkeys('', a:what) return '' endfuncUnix terminal-unix
On Unixa pty is used to make it possible to run all kinds of commands. You
can even run Vim in the terminal! That's used for debugging, see below.
Environment variables are used to pass information to the running job:
TERM the name of the terminal, from the 'term' option or
$TERM in the GUI; falls back to "xterm" if it does not
start with "xterm"
ROWS number of rows in the terminal initially
LINES same as ROWS
COLUMNS number of columns in the terminal initially
COLORS number of colors, 't_Co' (256*256*256 in the GUI)
VIM_SERVERNAME v:servername
VIM_TERMINAL v:versionMS-Windows terminal-ms-windows
On MS-Windows winpty is used to make it possible to run all kind of commands.
Obviously, they must be commands that run in a terminal, not open their own
window.
You need the following two files from winpty:
winpty.dll
winpty-agent.exe
You can download them from the following page:
https://github.com/rprichard/winpty
Just put the files somewhere in your PATH. You can set the 'winptydll' option
to point to the right file, if needed. If you have both the 32-bit and 64-bit
version, rename to winpty32.dll and winpty64.dll to match the way Vim was
build.
Environment variables are used to pass information to the running job:
VIM_SERVERNAME v:servername==============================================================================
2. Terminal communication terminal-communication
There are several ways to communicate with the job running in a terminal:
- Use term_sendkeys() to send text and escape sequences from Vim to the job.
- Use the JSON API to send encoded commands from the job to Vim.
- Use the client-server mechanism. This works on machines with an X server
and on MS-Windows.
Vim to job: term_sendkeys() terminal-to-job
This allows for remote controlling the job running in the terminal. It isa
one-way mechanism. The job can update the display to signal back to Vim.
For example, if a shell is running in a terminal, you can do:
call term_sendkeys(buf, "ls *.java\<CR>")
This requires for the job to be in the right state where it will do the right
thing when receiving the keys. For the above example, the shell must be
waiting for a command to be typed.
For ajob that was written for the purpose, you can use the JSON API escape
sequence in the other direction. E.g.:
call term_sendkeys(buf, "\<Esc>]51;["response"]\x07")Job to Vim: JSON API terminal-api
The job can send JSON to Vim, using a special escape sequence. The JSON
encodes a command that Vim understands. Example of such a message:
<Esc>]51;["drop", "README.md"]<07>
The body is always a list, making iteasy to find the end: ]<07>.
The <Esc>]51;msg<07> sequence is reserved by xterm for "Emacs shell", which is
similar to what we are doing here.
Currently supported commands:
call {funcname}{argument}
Call a user defined function with {argument}.
The function is called with two arguments: the buffer number
of the terminal and {argument}, the decoded JSON argument.
The function name must start with "Tapi_" to avoid
accidentally calling a function not meant to be used for the
terminal API.
The user function should sanity check the argument.
The function can use term_sendkeys() to send back a reply.
Example in JSON:
["call", "Tapi_Impression", ["play", 14]]
Calls a function defined like this:
function Tapi_Impression(bufnum, arglist) if len(a:arglist) == 2 echomsg "impression " . a:arglist[0] echomsg "count " . a:arglist[1] endif endfunc
Output from :echo may be erased by a redraw, use :echomsg
to be able to see it with :messages.
drop {filename}[options]
Let Vim open a file, like the :drop command. If {filename}is already open in a window, switch to that window. Otherwise
open a new window to edit {filename}.
Note that both the job and Vim may change the current
directory, thus it's best to use the full path.
[options]is only used when opening a new window. If present,
itmust be a Dict. Similarly to ++opt, These entries are recognized:
"ff" file format: "dos", "mac" or "unix"
"fileformat" idem
"enc" overrides 'fileencoding'
"encoding" idem
"bin" sets 'binary'
"binary" idem
"nobin" resets 'binary'
"nobinary" idem
"bad" specifies behavior for bad characters, see
++bad
Example in JSON:
["drop", "path/file.txt", {"ff": "dos"}]A trick to have Vim send this escape sequence:
exe "set t_ts=\<Esc>]51; t_fs=\x07" let &titlestring = '["call","Tapi_TryThis",["hello",123]]' redraw set t_ts& t_fs&
Rationale: Why not allow for any command or expression? Because that might
create a security problem.
Using the client-server feature terminal-client-server
This only works when v:servernameis not empty. If needed you can set it,
before opening the terminal, with:
call remote_startserver('vim-server')
$VIM_SERVERNAME is set in the terminal to pass on the server name.
In the job you can then do something like:
vim --servername $VIM_SERVERNAME --remote +123 some_file.c
This will open the file "some_file.c" and put the cursor on line 123.
==============================================================================
3. Remote testingterminal-testing
Most Vim tests execute ascript inside Vim. For some tests this does not
work, running the test interferes with the code being tested. To avoid this
Vim is executed in aterminal window. The test sends keystrokes to it and
inspects the resulting screen state.
Functions term_sendkeys() send keystrokes to aterminal (not subject to tmap)
term_wait() wait for screen to be updated
term_scrape() inspect terminal screen
==============================================================================
4. Diffing screen dumps terminal-diff
In some cases it can be bothersome to test that Vim displays the right
characters on the screen. E.g. with syntax highlighting. To make this
simpler itis possible to take a screen dump of aterminal and compare it to
an expected screen dump.
Vim uses the window size, text, color and other attributes as displayed. The
Vim screen size, font and other properties do not matter. Therefore this
mechanism is portable across systems. A conventional screenshot would reflect
all differences, including font size and family.
Writing a screen dump test for Vim terminal-dumptest
For an example see the Test_syntax_c() function in
src/testdir/test_syntax.vim. The main parts are:
- Write a file you want to test with. This is useful for testingsyntax
highlighting. You can also start Vim with en empty buffer.
- Run Vim in aterminal with a specific size. The default is 20 lines of 75
characters. This makes sure the dump is always this size. The function
RunVimInTerminal() takes care of this. Pass it the arguments for the Vim
command.
- Send any commands to Vim using term_sendkeys(). For example:
call term_sendkeys(buf, ":echo &lines &columns\<CR>")- Check that the screen is now in the expected state, using
VerifyScreenDump(). This expects the reference screen dump to be in the
src/testdir/dumps/ directory. Pass the name without ".dump". It is
recommended to use the name of the test function and a sequence number, so
that we know what test is using the file.
- Repeat sending commands and checking the state.
- Finally stop Vim by calling StopVimInTerminal().
The first time you do this you won't have a screen dump yet. Create an empty
file for now, e.g.:
touch src/testdir/dumps/Test_function_name_01.dump
The test will then fail, giving you the command to compare the reference dump
and the failed dump, e.g.:
call term_dumpdiff("Test_func.dump.failed", "dumps/Test_func.dump")
Use this command in Vim, with the current directory set to src/testdir.
Once you are satisfied with the test, move the failed dump in place of the
reference:
:!mv Test_func.dump.failed dumps/Test_func.dumpCreating a screen dump terminal-screendump
To create the screen dump, run Vim (or any other program) in aterminal and
make it show the desired state. Then use the term_dumpwrite() function to
create a screen dump file. For example:
:call term_dumpwrite(77, "mysyntax.dump")
Here "77" is the buffer number of the terminal. Use :ls! to see it.
You can view the screen dump with term_dumpload(): :call term_dumpload("mysyntax.dump")
To verify that Vim still shows exactly the same screen, run Vim again with
exactly the same way to show the desired state. Then create a screen dump
again, using a different file name:
:call term_dumpwrite(88, "test.dump")
To assert that the files are exactly the same use assert_equalfile(): call assert_equalfile("mysyntax.dump", "test.dump")
If there are differences then v:errors will contain the error message.
Comparing screen dumps terminal-diffscreendumpassert_equalfile() does not make iteasy to see what is different.
To spot the problem use term_dumpdiff(): call term_dumpdiff("mysyntax.dump", "test.dump")
This will open awindow consisting of three parts:
1. The contents of the first dump
2. The difference between the first and second dump
3. The contents of the second dump
You can usually see what differs in the second part. Use the 'ruler' to
relate it to the position in the first or second dump. Letters indicate the
kind of difference:
X different character
> cursor in first but not in second
< cursor in second but not in first
w character width differs (single vs double width)
f foreground color differs
b background color differs
a attribute differs (bold, underline, reverse, etc.)
? character missing in both
+ character missing in first
- character missing in second
Alternatively, press "s" to swap the first and second dump. Do this several
times so that you can spot the difference in the context of the text.
==============================================================================
5. Debugging terminal-debugterminal-debugger
The Terminal debugging plugin can be used to debug a program with gdb and view
the source code in a Vim window. Since this is completely contained inside
Vim this also works remotely over an ssh connection.
When the +terminal feature is missing, the plugin will use the "prompt"
buffer type, if possible. The running program will then use a newly opened
terminal window. See termdebug-prompt below for details.
Starting termdebug-starting
Load the plugin with this command:
packadd termdebug:Termdebug
To start debugging use :Termdebug or :TermdebugCommand followed by the
command name, for example:
:Termdebug vim
This opens two windows:
gdbwindowAterminalwindow in which "gdb vim" is executed. Here you
can directly interact with gdb. The buffer name is "!gdb".
program windowAterminalwindow for the executed program. When "run" is
used in gdb the program I/O will happen in this window, so
that it does not interfere with controlling gdb. The buffer
name is "gdb program".
The current windowis used to show the source code. When gdb pauses the
source file location will be displayed, if possible. A sign is used to
highlight the current position, using highlight group debugPC.
If the buffer in the current windowis modified, another window will be opened
to display the current gdb position. You can use :Winbar to add awindow
toolbar there.
Focus the terminal of the executed program to interact with it. This works
the same as any command running in aterminal window.
When the debugger ends, typically by typing "quit" in the gdb window, the two
opened windows are closed.
Only one debugger can be active ata time.
:TermdebugCommand
If you want to give specific commands to the command being debugged, you can
use the :TermdebugCommand command followed by the command name and
additional parameters.
:TermdebugCommand vim --clean -c ':set nu'
Both the :Termdebug and :TermdebugCommand support an optional "!" bang
argument to start the command right away, without pausing at the gdbwindow
(and cursor will be in the debugged window). For example:
:TermdebugCommand! vim --clean
To attach gdb to an already running executable or use a core file, pass extra
arguments. E.g.:
:Termdebug vim core :Termdebug vim 98343
If no argument is given, you'll end up in agdb window, in which you need to
specify which command to run using e.g. the gdbfile command.
Example session termdebug-example
Start in the Vim "src" directory and build Vim:
% make
Start Vim:
% ./vim
Load the termdebug plugin and start debugging Vim:
:packadd termdebug :Termdebug vim
You should now have three windows:
source - where you started, has awindow toolbar with buttons
gdb- you can type gdb commands here
program - the executed program will use this window
You can use CTRL-WCTRL-W or the mouse to move focus between windows.
Put focus on the gdbwindow and type:
break ex_help run
Vim will start running in the program window. Put focus there and type:
:help gui
Gdb will run into the ex_help breakpoint. The source window now shows the
ex_cmds.c file. A red "1 " marker will appear in the signcolumn where the
breakpoint was set. The line where the debugger stopped is highlighted. You
can now step through the program. Let's use the mouse: click on the "Next"
button in the window toolbar. You will see the highlighting move as the
debugger executes a line of source code.
Click "Next" a few times until the for loop is highlighted. Put the cursor on
the end of "eap->arg", then click "Eval" in the toolbar. You will see this
displayed:
"eap->arg": 0x555555e68855 "gui"
This way you can inspect the value of local variables. You can also focus the
gdbwindow and use a "print" command, e.g.:
print *eap
If mouse pointer movements are working, Vim will also show a balloon when the
mouse rests on text that can be evaluated by gdb.
Now go back to the source window and put the cursor on the first line after
the for loop, then type:
:Break
You will see a ">>" marker appear, this indicates the new breakpoint. Now
click "Cont" in the toolbar and the code until the breakpoint will be
executed.
You can type more advanced commands in the gdb window. For example, type:
watch curbuf
Now click "Cont" in the toolbar (or type "cont" in the gdb window). Execution
will now continue until the value of "curbuf" changes, which is in do_ecmd().
To remove this watchpoint again type in the gdb window:
delete 3
You can see the stack by typing in the gdb window:
where
Move through the stack frames, e.g. with:
frame 3
The source window will show the code, at the point where the call was made to
a deeper level.
Stepping through code termdebug-stepping
Put focus on the gdbwindow to type commands there. Some common ones are:
-CTRL-C interrupt the program
- next execute the current line and stop at the next line
- step execute the current line and stop at the next statement,
entering functions- finish execute until leaving the current function
- where show the stack
- frame Ngo to the Nth stack frame
- continue continue execution
:Run:Arguments
In the window showing the source code these commands can be used to control
gdb:
:Run[args] run the program with [args] or the previous arguments
:Arguments{args} set arguments for the next :Run:Break set a breakpoint at the current line; a sign will be displayed
:Clear delete the breakpoint at the current line
:Step execute the gdb "step" command
:Over execute the gdb "next" command (`:Next` isa Vim command)
:Finish execute the gdb "finish" command
:Continue execute the gdb "continue" command
:Stop interrupt the program
If 'mouse'is set the plugin adds awindow toolbar with these entries:
Step :Step
Next :Over
Finish :Finish
Cont :Continue
Stop :Stop
Eval :Evaluate
This way you can use the mouse to perform the most common commands. You need
to have the 'mouse' option set to enable mouse clicks.
:Winbar
You can add the window toolbar in other windows you open with:
:Winbar
If gdb stops ata source line and there is no window currently showing the
source code, a new window will be created for the source code. This also
happens if the buffer in the source code window has been modified and can't be
abandoned.
Gdb gives each breakpoint a number. In Vim the number shows up in the sign
column, with a red background. You can use these gdb commands:
- info break list breakpoints
- delete N delete breakpoint N
You can also use the :Clear command if the cursor is in the line with the
breakpoint, or use the "Clear breakpoint" right-click menu entry.
Inspecting variables termdebug-variables:Evaluate:Evaluate evaluate the expression under the cursor
K same
:Evaluate{expr} evaluate {expr}:'<,'>Evaluate evaluate the Visually selected text
This is similar to using "print" in the gdb window.
You can usually shorten :Evaluate to :Ev.
Other commands termdebug-commands:Gdb jump to the gdbwindow:Program jump to the window with the running program
:Source jump to the window with the source code, create it if there
isn't one
Prompt mode termdebug-prompt
When the +terminal feature is not supported and on MS-Windows, gdb will run
in a buffer with 'buftype' set to "prompt". This works slightly differently:
- The gdbwindow will be in Insert mode while typing commands. Go to Normal
mode with <Esc>, then you can move around in the buffer, copy/paste, etc.
Go back to editing the gdb command with any command that starts Insert mode,
such asa or i.
- The program being debugged will run in a separate window. On MS-Windows
this isa new console window. On Unix, if the +terminal feature is
available a Terminal window will be opened to run the debugged program in.
termdebug_use_prompt
Prompt mode can be used even when the +terminal feature is present with:
let g:termdebug_use_prompt = 1Communication termdebug-communication
There is another, hidden, buffer, which is used for Vim to communicate with
gdb. The buffer name is "gdb communication". Do not delete this buffer, it
will break the debugger.
Gdb has some weird behavior, the plugin does its best to work around that.
For example, after typing "continue" in the gdbwindowaCTRL-C can be used to
interrupt the running program. But after using the MI command
"-exec-continue" pressing CTRL-C does not interrupt. Therefore you will see
"continue" being used for the :Continue command, instead of using the
communication channel.
Customizing
GDB command termdebug-customizing
To change the name of the gdb command, set the "termdebugger" variable before
invoking :Termdebug:
let termdebugger = "mygdb"gdb-version
Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI
interface. The "new-ui" command requires gdb version 7.12 or later. if you
get this error:
Undefined command: "new-ui". Try "help".
Then your gdbis too old.
Colors hl-debugPChl-debugBreakpoint
The color of the signs can be adjusted with these highlight groups:
- debugPC the current position
- debugBreakpoint a breakpoint
The defaults are, when 'background'is "light":
hi debugPC term=reverse ctermbg=lightblue guibg=lightblue
hi debugBreakpoint term=reverse ctermbg=red guibg=red
When 'background'is "dark":
hi debugPC term=reverse ctermbg=darkblue guibg=darkblue
hi debugBreakpoint term=reverse ctermbg=red guibg=red
Shorcuts termdebug_shortcuts
You can define your own shortcuts (mappings) to control gdb, that can work in
any window, using the TermDebugSendCommand() function. Example:
map ,w :call TermDebugSendCommand('where')<CR>
The argument is the gdb command.
Popup menu termdebug_popup
By default the Termdebug plugin sets 'mousemodel' to "popup_setpos" and adds
these entries to the popup menu:
Set breakpoint :Break
Clear breakpoint :Clear
Evaluate :Evaluate
If you don't want this then disable it with:
let g:termdebug_popup = 0
Vim window width termdebug_wide
To change the width of the Vim window when debugging starts, and use a
vertical split:
let g:termdebug_wide = 163
This will set &columns to 163 when :Termdebugis used. The value is restored
when quitting the debugger.
If g:termdebug_wide is set and &columns is already larger than
g:termdebug_wide then a vertical split will be used without changing &columns.
Set it to 1 to get a vertical split without every changing &columns (useful
for when the terminal can't be resized by Vim).
vim:tw=78:ts=8:noet:ft=help:norl: