diff options
Diffstat (limited to '')
| -rw-r--r-- | runtime/doc/terminal.txt | 938 |
1 files changed, 938 insertions, 0 deletions
diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt new file mode 100644 index 0000000..de79ff0 --- /dev/null +++ b/runtime/doc/terminal.txt @@ -0,0 +1,938 @@ +*terminal.txt* For Vim version 8.1. Last change: 2019 Feb 03 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Terminal window support *terminal* *terminal-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-color| + Syntax |:terminal| + Resizing |terminal-resizing| + Terminal Modes |Terminal-mode| + Cursor style |terminal-cursor-style| + Session |terminal-session| + Special keys |terminal-special-keys| + Unix |terminal-unix| + MS-Windows |terminal-ms-windows| +2. Terminal communication |terminal-communication| + Vim to job: term_sendkeys() |terminal-to-job| + Job to Vim: JSON API |terminal-api| + Using the client-server feature |terminal-client-server| +3. Remote testing |terminal-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 variables |termdebug-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 a terminal emulator in a Vim window. A job 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 +terminal window to move keyboard focus elsewhere. + +CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.: + CTRL-W CTRL-W move focus to the next window + CTRL-W : enter an Ex command +See |CTRL-W| for more commands. + +Special in the terminal window: *CTRL-W_.* *CTRL-W_N* + CTRL-W . send a CTRL-W to the job in the terminal + CTRL-W CTRL-\ send a CTRL-\ to the job in the terminal + CTRL-W N go to Terminal-Normal mode, see |Terminal-mode| + CTRL-\ CTRL-N go to Terminal-Normal mode, see |Terminal-mode| + CTRL-W " {reg} paste register {reg} *CTRL-W_quote* + Also works with the = register to insert the result of + evaluating an expression. + CTRL-W CTRL-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 a CTRL-\ to the job in the terminal + 'termwinkey' N go to terminal Normal mode, see below + 'termwinkey' CTRL-N same as CTRL-W N + 'termwinkey' CTRL-C same as |t_CTRL-W_CTRL-C| + *t_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-C* +CTRL-W CTRL-C can be typed to forcefully end the job. On MS-Windows a +CTRL-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 terminal window and setting 'buftype' to "terminal" the +TerminalOpen autocommand 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 a terminal 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 terminal is 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 +terminal window 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=blue +< + *g:terminal_ansi_colors* +In GUI mode or with 'termguicolors', the 16 ANSI colors used by default in new +terminal windows may be configured using the variable +`g:terminal_ansi_colors`, which should be a list of 16 color names or +hexadecimal color codes, similar to those accepted by |highlight-guifg|. When +not using GUI colors, the terminal window 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 it as a job and connect + the input and output to the terminal. + If [command] is not given the 'shell' option is used. + if [command] is NONE no job is 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++close* *term++open* + Supported [options] are: + ++close The terminal window will close + automatically when the job terminates. + ++noclose The terminal window will NOT close + automatically when the job terminates. + ++open When the job terminates and no window + shows it, a window 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 |abandon|ed. + ++hidden Open the terminal in a hidden buffer, + no window will be used. + ++norestore Do not include this terminal window + in a session file. + ++kill={how} When trying to close the terminal + window kill the job with {how}. See + |term_setkill()| for the values. + ++rows={height} Use {height} for the terminal window + 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 terminal window + 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. + ++winpty Use winpty as the virtual console. + ++conpty Use |ConPTY| as the virtual console. + 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 terminal is forcibly unloaded or wiped out +the job is 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 job is 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 job is ended. The text in the window is lost. The buffer +still exists, but getting it in a window 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 terminal window and make the buffer +hidden, the job keeps running. The `:buffer` command can be used to turn the +current window into a terminal 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 make +Note that the window will open at an unexpected moment, this will interrupt +what you are doing. + + *E947* *E948* +So long as the job is 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 a terminal 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 x is upper or lower + case). The terminal size is fixed to the specified number of screen lines + and cells. If the window is bigger there will be unused empty space. + +If the window is 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-mode* *Terminal-Job* +When the job is running the contents of the terminal is 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-W N (or 'termwinkey' N) to switch to Terminal-Normal mode. Now the +contents of the terminal window is 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-Normal* *E946* +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. |:startinsert| is 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 terminal window 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 terminal window 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 terminal window cursor +blinking will also be inverted. + + +Session ~ + *terminal-session* +A terminal window will be restored when using a session file, if possible and +wanted. + +If "terminal" was removed from 'sessionoptions' then no terminal windows 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 '' + endfunc + + +Unix ~ + *terminal-unix* +On Unix a 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:version + + +MS-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. + *ConPTY* +On more recent versions of MS-Windows 10 (beginning with the "October 2018 +Update"), winpty is no longer required. On those versions, |:terminal| will use +Windows' built-in support for hosting terminal applications, "ConPTY". When +ConPTY is in use, there may be rendering artifacts regarding ambiguous-width +characters. If you encounter any such issues, set 'termmode' to winpty (which +you then must have instlled). + +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 is a +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 a job 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 it easy 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, + it must 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:servername is 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 testing *terminal-testing* + +Most Vim tests execute a script 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 a terminal window. The test sends keystrokes to it and +inspects the resulting screen state. + +Functions ~ + +|term_sendkeys()| send keystrokes to a terminal (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 it is possible to take a screen dump of a terminal 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 testing syntax + highlighting. You can also start Vim with en empty buffer. +- Run Vim in a terminal 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.dump + + +Creating a screen dump ~ + *terminal-screendump* + +To create the screen dump, run Vim (or any other program) in a terminal 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-diffscreendump* + +|assert_equalfile()| does not make it easy to see what is different. +To spot the problem use |term_dumpdiff()|: > + call term_dumpdiff("mysyntax.dump", "test.dump") + +This will open a window 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-debug* *terminal-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: + +gdb window A terminal window in which "gdb vim" is executed. Here you + can directly interact with gdb. The buffer name is "!gdb". + +program window A terminal window 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 window is 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 window is modified, another window will be opened +to display the current gdb position. You can use `:Winbar` to add a window +toolbar there. + +Focus the terminal of the executed program to interact with it. This works +the same as any command running in a terminal 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 at a 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 gdb window +(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 a gdb window, in which you need to +specify which command to run using e.g. the gdb `file` 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 a window toolbar with buttons + gdb - you can type gdb commands here + program - the executed program will use this window + +You can use CTRL-W CTRL-W or the mouse to move focus between windows. +Put focus on the gdb window 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 +gdb window 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 gdb window 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 N go 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` is a 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 a window 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 at a 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 gdb window + *: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 gdb window 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 as `a` or `i`. +- The program being debugged will run in a separate window. On MS-Windows + this is a 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 = 1 + + +Communication ~ + *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 gdb window a CTRL-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 gdb is too old. + + +Colors *hl-debugPC* *hl-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 `:Termdebug` is 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: |