Dimitry Ishenko | c4bca1d | 2025-07-08 23:13:14 +0200 | [diff] [blame] | 1 | *terminal.txt* For Vim version 9.1. Last change: 2025 Jul 08 |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 2 | |
| 3 | |
| 4 | VIM REFERENCE MANUAL by Bram Moolenaar |
| 5 | |
| 6 | |
Bram Moolenaar | b1c9198 | 2018-05-17 17:04:55 +0200 | [diff] [blame] | 7 | Terminal window support *terminal* *terminal-window* |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 8 | |
| 9 | |
Bram Moolenaar | b6e0ec6 | 2017-07-23 22:12:20 +0200 | [diff] [blame] | 10 | The terminal feature is optional, use this to check if your Vim has it: > |
| 11 | echo has('terminal') |
| 12 | If the result is "1" you have it. |
| 13 | |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 14 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 15 | 1. Basic use |terminal-use| |
| 16 | Typing |terminal-typing| |
| 17 | Size and color |terminal-size-color| |
| 18 | Command syntax |:terminal| |
| 19 | Resizing |terminal-resizing| |
| 20 | Terminal Modes |Terminal-mode| |
| 21 | Cursor style |terminal-cursor-style| |
| 22 | Session |terminal-session| |
| 23 | Special keys |terminal-special-keys| |
| 24 | Unix |terminal-unix| |
| 25 | MS-Windows |terminal-ms-windows| |
| 26 | 2. Terminal functions |terminal-function-details| |
| 27 | 3. Terminal communication |terminal-communication| |
| 28 | Vim to job: term_sendkeys() |terminal-to-job| |
| 29 | Job to Vim: JSON API |terminal-api| |
| 30 | Using the client-server feature |terminal-client-server| |
| 31 | 4. Remote testing |terminal-testing| |
| 32 | 5. Diffing screen dumps |terminal-diff| |
Bram Moolenaar | 938ae28 | 2023-02-20 20:44:55 +0000 | [diff] [blame] | 33 | Writing a screen dump test for Vim |terminal-dumptest| |
| 34 | Creating a screen dump |terminal-screendump| |
| 35 | Comparing screen dumps |terminal-diffscreendump| |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 36 | 6. Debugging |terminal-debug| |
| 37 | Starting |termdebug-starting| |
| 38 | Example session |termdebug-example| |
| 39 | Stepping through code |termdebug-stepping| |
| 40 | Inspecting variables |termdebug-variables| |
Sean Dewar | 3d3a915 | 2023-08-23 17:14:49 +0100 | [diff] [blame] | 41 | Navigating stack frames |termdebug-frames| |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 42 | Other commands |termdebug-commands| |
Bram Moolenaar | 2f0936c | 2022-01-08 21:51:59 +0000 | [diff] [blame] | 43 | Events |termdebug-events| |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 44 | Prompt mode |termdebug-prompt| |
shane.xb.qian | 7fbbd7f | 2023-11-08 21:44:48 +0100 | [diff] [blame] | 45 | Mappings |termdebug-mappings| |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 46 | Communication |termdebug-communication| |
| 47 | Customizing |termdebug-customizing| |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 48 | |
Bram Moolenaar | c572da5 | 2017-08-27 16:52:01 +0200 | [diff] [blame] | 49 | {only available when compiled with the |+terminal| feature} |
Bram Moolenaar | 4c92e75 | 2019-02-17 21:18:32 +0100 | [diff] [blame] | 50 | The terminal feature requires the |+job| and |+channel| features. |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 51 | |
| 52 | ============================================================================== |
| 53 | 1. Basic use *terminal-use* |
| 54 | |
| 55 | This feature is for running a terminal emulator in a Vim window. A job can be |
| 56 | started connected to the terminal emulator. For example, to run a shell: > |
| 57 | :term bash |
| 58 | |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 59 | Or to run build command: > |
| 60 | :term make myprogram |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 61 | |
| 62 | The job runs asynchronously from Vim, the window will be updated to show |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 63 | output from the job, also while editing in another window. |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 64 | |
Bram Moolenaar | 423802d | 2017-07-30 16:52:24 +0200 | [diff] [blame] | 65 | |
Bram Moolenaar | 1f28b4c | 2017-07-28 13:48:34 +0200 | [diff] [blame] | 66 | Typing ~ |
Bram Moolenaar | 69fbc9e | 2017-09-14 20:37:57 +0200 | [diff] [blame] | 67 | *terminal-typing* |
Bram Moolenaar | dd693ce | 2017-08-10 23:15:19 +0200 | [diff] [blame] | 68 | When the keyboard focus is in the terminal window, typed keys will be sent to |
Bram Moolenaar | 1f28b4c | 2017-07-28 13:48:34 +0200 | [diff] [blame] | 69 | the job. This uses a pty when possible. You can click outside of the |
| 70 | terminal window to move keyboard focus elsewhere. |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 71 | |
Bram Moolenaar | 2696761 | 2019-03-17 17:13:16 +0100 | [diff] [blame] | 72 | *t_CTRL-W_CTRL-W* *t_CTRL-W_:* |
Bram Moolenaar | 423802d | 2017-07-30 16:52:24 +0200 | [diff] [blame] | 73 | CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.: |
Bram Moolenaar | 60e73f2 | 2017-11-12 18:02:06 +0100 | [diff] [blame] | 74 | CTRL-W CTRL-W move focus to the next window |
Bram Moolenaar | 423802d | 2017-07-30 16:52:24 +0200 | [diff] [blame] | 75 | CTRL-W : enter an Ex command |
| 76 | See |CTRL-W| for more commands. |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 77 | |
Bram Moolenaar | 664f3cf | 2019-12-07 16:03:51 +0100 | [diff] [blame] | 78 | Special in the terminal window: *t_CTRL-W_.* *t_CTRL-W_N* |
Bram Moolenaar | 423802d | 2017-07-30 16:52:24 +0200 | [diff] [blame] | 79 | CTRL-W . send a CTRL-W to the job in the terminal |
Bram Moolenaar | b59118d | 2018-04-13 22:11:56 +0200 | [diff] [blame] | 80 | CTRL-W CTRL-\ send a CTRL-\ to the job in the terminal |
Bram Moolenaar | dd693ce | 2017-08-10 23:15:19 +0200 | [diff] [blame] | 81 | CTRL-W N go to Terminal-Normal mode, see |Terminal-mode| |
| 82 | CTRL-\ CTRL-N go to Terminal-Normal mode, see |Terminal-mode| |
Bram Moolenaar | 2696761 | 2019-03-17 17:13:16 +0100 | [diff] [blame] | 83 | CTRL-W " {reg} paste register {reg} *t_CTRL-W_quote* |
Bram Moolenaar | f55e4c8 | 2017-08-01 20:44:53 +0200 | [diff] [blame] | 84 | Also works with the = register to insert the result of |
| 85 | evaluating an expression. |
Bram Moolenaar | 8e539c5 | 2017-08-18 22:57:06 +0200 | [diff] [blame] | 86 | CTRL-W CTRL-C ends the job, see below |t_CTRL-W_CTRL-C| |
Bram Moolenaar | 2696761 | 2019-03-17 17:13:16 +0100 | [diff] [blame] | 87 | CTRL-W gt go to next tabpage, same as `gt` *t_CTRL-W_gt* |
| 88 | CTRL-W gT go to previous tabpage, same as `gT` *t_CTRL-W_gT* |
Bram Moolenaar | 423802d | 2017-07-30 16:52:24 +0200 | [diff] [blame] | 89 | |
Bram Moolenaar | 7dda86f | 2018-04-20 22:36:41 +0200 | [diff] [blame] | 90 | See option 'termwinkey' for specifying another key instead of CTRL-W that |
| 91 | will work like CTRL-W. However, typing 'termwinkey' twice sends 'termwinkey' |
| 92 | to the job. For example: |
| 93 | 'termwinkey' CTRL-W move focus to the next window |
| 94 | 'termwinkey' : enter an Ex command |
| 95 | 'termwinkey' 'termwinkey' send 'termwinkey' to the job in the terminal |
Bram Moolenaar | dcdeaaf | 2018-06-17 22:19:12 +0200 | [diff] [blame] | 96 | 'termwinkey' . send 'termwinkey' to the job in the terminal |
| 97 | 'termwinkey' CTRL-\ send a CTRL-\ to the job in the terminal |
Bram Moolenaar | 7dda86f | 2018-04-20 22:36:41 +0200 | [diff] [blame] | 98 | 'termwinkey' N go to terminal Normal mode, see below |
Bram Moolenaar | 2696761 | 2019-03-17 17:13:16 +0100 | [diff] [blame] | 99 | 'termwinkey' CTRL-N same as CTRL-W N |t_CTRL-W_N| |
| 100 | 'termwinkey' CTRL-C same as CTRL-W CTRL-C |t_CTRL-W_CTRL-C| |
Bram Moolenaar | 6919819 | 2017-08-05 14:10:48 +0200 | [diff] [blame] | 101 | *t_CTRL-\_CTRL-N* |
Bram Moolenaar | dd693ce | 2017-08-10 23:15:19 +0200 | [diff] [blame] | 102 | The special key combination CTRL-\ CTRL-N can be used to switch to Normal |
| 103 | mode, just like this works in any other mode. |
Bram Moolenaar | 8e539c5 | 2017-08-18 22:57:06 +0200 | [diff] [blame] | 104 | *t_CTRL-W_CTRL-C* |
| 105 | CTRL-W CTRL-C can be typed to forcefully end the job. On MS-Windows a |
Bram Moolenaar | 63f3260 | 2022-06-09 20:45:54 +0100 | [diff] [blame] | 106 | CTRL-Break will also kill the job. |
Bram Moolenaar | 8e539c5 | 2017-08-18 22:57:06 +0200 | [diff] [blame] | 107 | |
| 108 | If you type CTRL-C the effect depends on what the pty has been configured to |
| 109 | do. For simple commands this causes a SIGINT to be sent to the job, which |
| 110 | would end it. Other commands may ignore the SIGINT or handle the CTRL-C |
| 111 | themselves (like Vim does). |
Bram Moolenaar | 423802d | 2017-07-30 16:52:24 +0200 | [diff] [blame] | 112 | |
Bram Moolenaar | 69fbc9e | 2017-09-14 20:37:57 +0200 | [diff] [blame] | 113 | To change the keys you type use terminal mode mappings, see |:tmap|. |
| 114 | These are defined like any mapping, but apply only when typing keys that are |
Bram Moolenaar | 98ef233 | 2018-03-18 14:44:37 +0100 | [diff] [blame] | 115 | sent to the job running in the terminal. For example, to make F1 switch |
Bram Moolenaar | 24a98a0 | 2017-09-27 22:23:55 +0200 | [diff] [blame] | 116 | to Terminal-Normal mode: > |
Bram Moolenaar | 98ef233 | 2018-03-18 14:44:37 +0100 | [diff] [blame] | 117 | tnoremap <F1> <C-W>N |
| 118 | You can use Esc, but you need to make sure it won't cause other keys to |
Bram Moolenaar | acc2240 | 2020-06-07 21:07:18 +0200 | [diff] [blame] | 119 | break (cursor keys start with an Esc, so they may break), this probably only |
| 120 | works in the GUI: > |
Bram Moolenaar | 24a98a0 | 2017-09-27 22:23:55 +0200 | [diff] [blame] | 121 | tnoremap <Esc> <C-W>N |
Bram Moolenaar | 98ef233 | 2018-03-18 14:44:37 +0100 | [diff] [blame] | 122 | set notimeout ttimeout timeoutlen=100 |
| 123 | |
Bram Moolenaar | 4c5d815 | 2018-10-19 22:36:53 +0200 | [diff] [blame] | 124 | You can also create menus similar to terminal mode mappings, but you have to |
| 125 | use |:tlmenu| instead of |:tmenu|. |
| 126 | |
Bram Moolenaar | 7ceefb3 | 2020-05-01 16:07:38 +0200 | [diff] [blame] | 127 | *options-in-terminal* |
Bram Moolenaar | 24a98a0 | 2017-09-27 22:23:55 +0200 | [diff] [blame] | 128 | After opening the terminal window and setting 'buftype' to "terminal" the |
Bram Moolenaar | 23515b4 | 2020-11-29 14:36:24 +0100 | [diff] [blame] | 129 | |TerminalWinOpen| autocommand event is triggered. This makes it possible to set |
| 130 | options specifically for the terminal window and buffer. Example: > |
| 131 | au TerminalWinOpen * setlocal bufhidden=hide |
Bram Moolenaar | 942db23 | 2021-02-13 18:14:48 +0100 | [diff] [blame] | 132 | This only works properly if the terminal is not hidden. |
Bram Moolenaar | 23515b4 | 2020-11-29 14:36:24 +0100 | [diff] [blame] | 133 | |
Bram Moolenaar | 942db23 | 2021-02-13 18:14:48 +0100 | [diff] [blame] | 134 | For both hidden and non-hidden terminals this works, both for buffer-local and |
| 135 | window-local options: > |
| 136 | au TerminalWinOpen,BufWinEnter * if &buftype == 'terminal' |
| 137 | \ | setlocal bufhidden=hide colorcolumn=123 |
| 138 | \ | endif |
| 139 | Note that for a hidden terminal the options are not set until the terminal is |
| 140 | no longer hidden. |
| 141 | |
| 142 | There is also the |TerminalOpen| event. Keep in mind this may be triggered |
| 143 | for a hidden terminal, then the current window and buffer are not that of the |
| 144 | new terminal. |
Bram Moolenaar | 23515b4 | 2020-11-29 14:36:24 +0100 | [diff] [blame] | 145 | You need to use <abuf>, which is set to the terminal buffer. Example: > |
Bram Moolenaar | 942db23 | 2021-02-13 18:14:48 +0100 | [diff] [blame] | 146 | au TerminalOpen * call setbufvar(expand('<abuf>')->str2nr(), |
| 147 | \ '&termwinscroll', 1000) |
| 148 | For a window-local option, you need to delay setting the option until the |
| 149 | terminal window has been created (this only works for a hidden terminal): > |
| 150 | au TerminalOpen * exe printf( |
| 151 | \ 'au BufWinEnter <buffer=%d> ++once setlocal colorcolumn=%d', |
| 152 | \ expand('<abuf>')->str2nr(), 123) |
| 153 | For a non-hidden terminal use |TerminalWinOpen|. |
Bram Moolenaar | 69fbc9e | 2017-09-14 20:37:57 +0200 | [diff] [blame] | 154 | |
Bram Moolenaar | 52dbb5e | 2017-11-21 18:11:27 +0100 | [diff] [blame] | 155 | Mouse events (click and drag) are passed to the terminal. Mouse move events |
| 156 | are only passed when Vim itself is receiving them. For a terminal that is |
| 157 | when 'balloonevalterm' is enabled. |
| 158 | |
Bram Moolenaar | 1f28b4c | 2017-07-28 13:48:34 +0200 | [diff] [blame] | 159 | |
Bram Moolenaar | 8e539c5 | 2017-08-18 22:57:06 +0200 | [diff] [blame] | 160 | Size and color ~ |
Bram Moolenaar | 7f2e9d7 | 2017-11-11 20:58:53 +0100 | [diff] [blame] | 161 | *terminal-size-color* |
Bram Moolenaar | 7dda86f | 2018-04-20 22:36:41 +0200 | [diff] [blame] | 162 | See option 'termwinsize' for controlling the size of the terminal window. |
Bram Moolenaar | 74675a6 | 2017-07-15 13:53:23 +0200 | [diff] [blame] | 163 | (TODO: scrolling when the terminal is larger than the window) |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 164 | |
Bram Moolenaar | 38baa3e | 2017-09-14 16:10:38 +0200 | [diff] [blame] | 165 | The job running in the terminal can change the colors. The default foreground |
| 166 | and background colors are taken from Vim, the Normal highlight group. |
| 167 | |
| 168 | For a color terminal the 'background' option is used to decide whether the |
| 169 | terminal window will start with a white or black background. |
| 170 | |
Bram Moolenaar | df980db | 2017-12-24 13:22:00 +0100 | [diff] [blame] | 171 | To use a different color the Terminal highlight group can be used, for |
| 172 | example: > |
Bram Moolenaar | 38baa3e | 2017-09-14 16:10:38 +0200 | [diff] [blame] | 173 | hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue |
Bram Moolenaar | 83d4790 | 2020-03-26 20:34:00 +0100 | [diff] [blame] | 174 | Instead of Terminal another group can be specified with the "term_highlight" |
| 175 | option for `term_start()`. |
| 176 | |
Bram Moolenaar | f59c6e8 | 2018-04-10 15:59:11 +0200 | [diff] [blame] | 177 | *g:terminal_ansi_colors* |
Bram Moolenaar | 7dda86f | 2018-04-20 22:36:41 +0200 | [diff] [blame] | 178 | In GUI mode or with 'termguicolors', the 16 ANSI colors used by default in new |
Bram Moolenaar | f59c6e8 | 2018-04-10 15:59:11 +0200 | [diff] [blame] | 179 | terminal windows may be configured using the variable |
| 180 | `g:terminal_ansi_colors`, which should be a list of 16 color names or |
| 181 | hexadecimal color codes, similar to those accepted by |highlight-guifg|. When |
| 182 | not using GUI colors, the terminal window always uses the 16 ANSI colors of |
| 183 | the underlying terminal. |
Bram Moolenaar | 388a5d4 | 2020-05-26 21:20:45 +0200 | [diff] [blame] | 184 | When using `term_start()` the colors can be set with the "ansi_colors" option. |
Bram Moolenaar | f59c6e8 | 2018-04-10 15:59:11 +0200 | [diff] [blame] | 185 | The |term_setansicolors()| function can be used to change the colors, and |
| 186 | |term_getansicolors()| to get the currently used colors. |
Bram Moolenaar | 8e539c5 | 2017-08-18 22:57:06 +0200 | [diff] [blame] | 187 | |
Bram Moolenaar | 423802d | 2017-07-30 16:52:24 +0200 | [diff] [blame] | 188 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 189 | Command syntax ~ |
Bram Moolenaar | 8a77306 | 2017-07-24 22:29:21 +0200 | [diff] [blame] | 190 | |
Bram Moolenaar | dd693ce | 2017-08-10 23:15:19 +0200 | [diff] [blame] | 191 | :[range]ter[minal] [options] [command] *:ter* *:terminal* |
Bram Moolenaar | 8a77306 | 2017-07-24 22:29:21 +0200 | [diff] [blame] | 192 | Open a new terminal window. |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 193 | |
| 194 | If [command] is provided run it as a job and connect |
| 195 | the input and output to the terminal. |
| 196 | If [command] is not given the 'shell' option is used. |
Bram Moolenaar | c572da5 | 2017-08-27 16:52:01 +0200 | [diff] [blame] | 197 | if [command] is NONE no job is started, the pty of the |
| 198 | terminal can be used by a command like gdb. |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 199 | |
Christian Brabandt | 6de7191 | 2024-12-30 10:20:17 +0100 | [diff] [blame] | 200 | If [command] outputs NUL bytes, those will be |
| 201 | converted to new lines |NL-used-for-Nul|. |
| 202 | |
matveyt | a01148d | 2024-11-23 14:19:58 +0100 | [diff] [blame] | 203 | *terminal-nospecial* |
| 204 | Vim itself only recognizes |cmdline-special| |
| 205 | characters inside [command]. Everything else will be |
| 206 | passed untouched. When needed to expand wildcards, |
| 207 | environment variables or other shell specials consider |
| 208 | |term++shell| option. |
| 209 | |
Bram Moolenaar | 1dd9833 | 2018-03-16 22:54:53 +0100 | [diff] [blame] | 210 | If [command] is missing the default behavior is to |
| 211 | close the terminal when the shell exits. This can be |
| 212 | changed with the ++noclose argument. |
| 213 | If [command] is present the default behavior is to |
| 214 | keep the terminal open in Terminal-Normal mode. This |
| 215 | can be changed with the ++close argument. |
| 216 | |
Bram Moolenaar | 7ceefb3 | 2020-05-01 16:07:38 +0200 | [diff] [blame] | 217 | No Vim command can follow, any | is included in |
| 218 | [command]. Use `:execute` if you must have a Vim |
| 219 | command following in the same line. |
| 220 | |
Christian Brabandt | ec9c326 | 2024-02-21 20:40:05 +0100 | [diff] [blame] | 221 | *terminal-bufname* |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 222 | A new buffer will be created, using [command] or |
Bram Moolenaar | f55e4c8 | 2017-08-01 20:44:53 +0200 | [diff] [blame] | 223 | 'shell' as the name, prefixed with a "!". If a buffer |
| 224 | by this name already exists a number is added in |
Bram Moolenaar | dd693ce | 2017-08-10 23:15:19 +0200 | [diff] [blame] | 225 | parentheses. E.g. if "gdb" exists the second terminal |
Bram Moolenaar | f55e4c8 | 2017-08-01 20:44:53 +0200 | [diff] [blame] | 226 | buffer will use "!gdb (1)". |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 227 | |
Bram Moolenaar | b241208 | 2017-08-20 18:09:14 +0200 | [diff] [blame] | 228 | If [range] is given the specified lines are used as |
| 229 | input for the job. It will not be possible to type |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 230 | keys in the terminal window. For MS-Windows see the |
| 231 | ++eof argument below. |
Bram Moolenaar | dd693ce | 2017-08-10 23:15:19 +0200 | [diff] [blame] | 232 | |
Bram Moolenaar | dd693ce | 2017-08-10 23:15:19 +0200 | [diff] [blame] | 233 | *term++close* *term++open* |
| 234 | Supported [options] are: |
| 235 | ++close The terminal window will close |
| 236 | automatically when the job terminates. |
Bram Moolenaar | 4d14bac | 2019-10-20 21:15:15 +0200 | [diff] [blame] | 237 | |terminal-close| |
Bram Moolenaar | 1dd9833 | 2018-03-16 22:54:53 +0100 | [diff] [blame] | 238 | ++noclose The terminal window will NOT close |
| 239 | automatically when the job terminates. |
Bram Moolenaar | dd693ce | 2017-08-10 23:15:19 +0200 | [diff] [blame] | 240 | ++open When the job terminates and no window |
Bram Moolenaar | 8cad930 | 2017-08-12 14:32:32 +0200 | [diff] [blame] | 241 | shows it, a window will be opened. |
Bram Moolenaar | dd693ce | 2017-08-10 23:15:19 +0200 | [diff] [blame] | 242 | Note that this can be interruptive. |
Bram Moolenaar | 1dd9833 | 2018-03-16 22:54:53 +0100 | [diff] [blame] | 243 | The last of ++close, ++noclose and ++open |
| 244 | matters and rules out earlier arguments. |
| 245 | |
Bram Moolenaar | 8cad930 | 2017-08-12 14:32:32 +0200 | [diff] [blame] | 246 | ++curwin Open the terminal in the current |
| 247 | window, do not split the current |
| 248 | window. Fails if the current buffer |
| 249 | cannot be |abandon|ed. |
| 250 | ++hidden Open the terminal in a hidden buffer, |
| 251 | no window will be used. |
Bram Moolenaar | b5b7562 | 2018-03-09 22:22:21 +0100 | [diff] [blame] | 252 | ++norestore Do not include this terminal window |
| 253 | in a session file. |
matveyt | a01148d | 2024-11-23 14:19:58 +0100 | [diff] [blame] | 254 | |
| 255 | *term++shell* |
Bram Moolenaar | 197c6b7 | 2019-11-03 23:37:12 +0100 | [diff] [blame] | 256 | ++shell Instead of executing {command} |
| 257 | directly, use a shell, like with |
Bram Moolenaar | 938ae28 | 2023-02-20 20:44:55 +0000 | [diff] [blame] | 258 | `:!command` *E279* |
Bram Moolenaar | 519cc55 | 2021-11-16 19:18:26 +0000 | [diff] [blame] | 259 | {only works on Unix and MS-Windows} |
matveyt | a01148d | 2024-11-23 14:19:58 +0100 | [diff] [blame] | 260 | The resulting command will look like |
| 261 | 'shell' 'shellcmdflag' [command] |
| 262 | Other options related to `:!command` |
| 263 | have no effect. |
Bram Moolenaar | 25cdd9c | 2018-03-10 20:28:12 +0100 | [diff] [blame] | 264 | ++kill={how} When trying to close the terminal |
| 265 | window kill the job with {how}. See |
| 266 | |term_setkill()| for the values. |
Bram Moolenaar | b241208 | 2017-08-20 18:09:14 +0200 | [diff] [blame] | 267 | ++rows={height} Use {height} for the terminal window |
Bram Moolenaar | 40962ec | 2018-01-28 22:47:25 +0100 | [diff] [blame] | 268 | height. If the terminal uses the full |
| 269 | Vim height (no window above or below |
Bram Moolenaar | 0b0f099 | 2018-05-22 21:41:30 +0200 | [diff] [blame] | 270 | the terminal window) the command line |
Bram Moolenaar | 40962ec | 2018-01-28 22:47:25 +0100 | [diff] [blame] | 271 | height will be reduced as needed. |
Bram Moolenaar | b241208 | 2017-08-20 18:09:14 +0200 | [diff] [blame] | 272 | ++cols={width} Use {width} for the terminal window |
Bram Moolenaar | 40962ec | 2018-01-28 22:47:25 +0100 | [diff] [blame] | 273 | width. If the terminal uses the full |
| 274 | Vim width (no window left or right of |
| 275 | the terminal window) this value is |
| 276 | ignored. |
Bram Moolenaar | d2842ea | 2019-09-26 23:08:54 +0200 | [diff] [blame] | 277 | ++eof={text} When using [range]: text to send after |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 278 | the last line was written. Cannot |
| 279 | contain white space. A CR is |
| 280 | appended. For MS-Windows the default |
| 281 | is to send CTRL-D. |
Bram Moolenaar | ef68e4f | 2017-09-02 16:28:36 +0200 | [diff] [blame] | 282 | E.g. for a shell use "++eof=exit" and |
| 283 | for Python "++eof=exit()". Special |
| 284 | codes can be used like with `:map`, |
| 285 | e.g. "<C-Z>" for CTRL-Z. |
Bram Moolenaar | c6ddce3 | 2019-02-08 12:47:03 +0100 | [diff] [blame] | 286 | ++type={pty} (MS-Windows only): Use {pty} as the |
| 287 | virtual console. See 'termwintype' |
| 288 | for the values. |
Bram Moolenaar | d2842ea | 2019-09-26 23:08:54 +0200 | [diff] [blame] | 289 | ++api={expr} Permit the function name starting with |
| 290 | {expr} to be called as |terminal-api| |
| 291 | function. If {expr} is empty then no |
| 292 | function can be called. |
Bram Moolenaar | c6ddce3 | 2019-02-08 12:47:03 +0100 | [diff] [blame] | 293 | |
Bram Moolenaar | 8cad930 | 2017-08-12 14:32:32 +0200 | [diff] [blame] | 294 | If you want to use more options use the |term_start()| |
| 295 | function. |
Bram Moolenaar | fc65cab | 2018-08-28 22:58:02 +0200 | [diff] [blame] | 296 | If you want to split the window vertically, use: > |
| 297 | :vertical terminal |
| 298 | < Or short: > |
| 299 | :vert ter |
Bram Moolenaar | dd693ce | 2017-08-10 23:15:19 +0200 | [diff] [blame] | 300 | |
Bram Moolenaar | 25cdd9c | 2018-03-10 20:28:12 +0100 | [diff] [blame] | 301 | When the buffer associated with the terminal is forcibly unloaded or wiped out |
| 302 | the job is killed, similar to calling `job_stop(job, "kill")` . |
| 303 | Closing the window normally results in |E947|. When a kill method was set |
| 304 | with "++kill={how}" or |term_setkill()| then closing the window will use that |
| 305 | way to kill or interrupt the job. For example: > |
| 306 | :term ++kill=term tail -f /tmp/log |
Bram Moolenaar | b6e0ec6 | 2017-07-23 22:12:20 +0200 | [diff] [blame] | 307 | |
Bram Moolenaar | e561a7e | 2017-08-29 22:44:59 +0200 | [diff] [blame] | 308 | So long as the job is running the window behaves like it contains a modified |
Bram Moolenaar | ef68e4f | 2017-09-02 16:28:36 +0200 | [diff] [blame] | 309 | buffer. Trying to close the window with `CTRL-W :quit` fails. When using |
Yee Cheng Chin | 4282633 | 2022-10-10 11:46:16 +0100 | [diff] [blame] | 310 | `CTRL-W :quit!` the job is ended. The text in the window is lost, the buffer |
| 311 | is deleted. With `CTRL-W :bunload!` the buffer remains but will be empty. |
Bram Moolenaar | ef68e4f | 2017-09-02 16:28:36 +0200 | [diff] [blame] | 312 | |
| 313 | Trying to close the window with `CTRL-W :close` also fails. Using |
| 314 | `CTRL-W :close!` will close the window and make the buffer hidden. |
Bram Moolenaar | e561a7e | 2017-08-29 22:44:59 +0200 | [diff] [blame] | 315 | |
| 316 | You can use `CTRL-W :hide` to close the terminal window and make the buffer |
| 317 | hidden, the job keeps running. The `:buffer` command can be used to turn the |
| 318 | current window into a terminal window. If there are unsaved changes this |
Bram Moolenaar | 0b0f099 | 2018-05-22 21:41:30 +0200 | [diff] [blame] | 319 | fails, use ! to force, as usual. |
Bram Moolenaar | 8cad930 | 2017-08-12 14:32:32 +0200 | [diff] [blame] | 320 | |
Bram Moolenaar | 4d14bac | 2019-10-20 21:15:15 +0200 | [diff] [blame] | 321 | *terminal-close* |
Christian Brabandt | 0e17f7e | 2024-03-17 20:14:25 +0100 | [diff] [blame] | 322 | When the terminal job finishes and no [command] was given (e.g. the 'shell' |
| 323 | command was executed), the terminal window will be closed by default (unless |
| 324 | the buffer in next window receiving the space has the 'nobuflisted' option set, |
| 325 | in which case the terminal window would not be closed automatically, but a new |
| 326 | empty buffer would be opened in that window). |
| 327 | |
Bram Moolenaar | 4d14bac | 2019-10-20 21:15:15 +0200 | [diff] [blame] | 328 | When the terminal window is closed, e.g. when the shell exits and "++close" |
| 329 | argument was used, and this is the last normal Vim window, then Vim will exit. |
| 330 | This is like using |:quit| in a normal window. Help and preview windows are |
| 331 | not counted. |
| 332 | |
Bram Moolenaar | 8cad930 | 2017-08-12 14:32:32 +0200 | [diff] [blame] | 333 | To have a background job run without a window, and open the window when it's |
| 334 | done, use options like this: > |
| 335 | :term ++hidden ++open make |
| 336 | Note that the window will open at an unexpected moment, this will interrupt |
| 337 | what you are doing. |
| 338 | |
Bram Moolenaar | 8e539c5 | 2017-08-18 22:57:06 +0200 | [diff] [blame] | 339 | *E947* *E948* |
Bram Moolenaar | 78712a7 | 2017-08-05 14:50:12 +0200 | [diff] [blame] | 340 | So long as the job is running, the buffer is considered modified and Vim |
| 341 | cannot be quit easily, see |abandon|. |
Bram Moolenaar | f55e4c8 | 2017-08-01 20:44:53 +0200 | [diff] [blame] | 342 | |
| 343 | When the job has finished and no changes were made to the buffer: closing the |
| 344 | window will wipe out the buffer. |
| 345 | |
| 346 | Before changes can be made to a terminal buffer, the 'modifiable' option must |
| 347 | be set. This is only possible when the job has finished. At the first change |
| 348 | the buffer will become a normal buffer and the highlighting is removed. |
| 349 | You may want to change the buffer name with |:file| to be able to write, since |
| 350 | the buffer name will still be set to the command. |
| 351 | |
Bram Moolenaar | b6e0ec6 | 2017-07-23 22:12:20 +0200 | [diff] [blame] | 352 | |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 353 | Resizing ~ |
Bram Moolenaar | 7f2e9d7 | 2017-11-11 20:58:53 +0100 | [diff] [blame] | 354 | *terminal-resizing* |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 355 | The size of the terminal can be in one of three modes: |
| 356 | |
Bram Moolenaar | 7dda86f | 2018-04-20 22:36:41 +0200 | [diff] [blame] | 357 | 1. The 'termwinsize' option is empty: The terminal size follows the window |
| 358 | size. The minimal size is 2 screen lines with 10 cells. |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 359 | |
Bram Moolenaar | 7dda86f | 2018-04-20 22:36:41 +0200 | [diff] [blame] | 360 | 2. The 'termwinsize' option is "rows*cols", where "rows" is the minimal number |
| 361 | of screen rows and "cols" is the minimal number of cells. |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 362 | |
Bram Moolenaar | 7dda86f | 2018-04-20 22:36:41 +0200 | [diff] [blame] | 363 | 3. The 'termwinsize' option is "rowsXcols" (where the x is upper or lower |
| 364 | case). The terminal size is fixed to the specified number of screen lines |
| 365 | and cells. If the window is bigger there will be unused empty space. |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 366 | |
| 367 | If the window is smaller than the terminal size, only part of the terminal can |
| 368 | be seen (the lower-left part). |
| 369 | |
| 370 | The |term_getsize()| function can be used to get the current size of the |
| 371 | terminal. |term_setsize()| can be used only when in the first or second mode, |
Bram Moolenaar | 7dda86f | 2018-04-20 22:36:41 +0200 | [diff] [blame] | 372 | not when 'termwinsize' is "rowsXcols". |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 373 | |
Bram Moolenaar | b6e0ec6 | 2017-07-23 22:12:20 +0200 | [diff] [blame] | 374 | |
Bram Moolenaar | dd693ce | 2017-08-10 23:15:19 +0200 | [diff] [blame] | 375 | Terminal-Job and Terminal-Normal mode ~ |
Bram Moolenaar | 8c041b6 | 2018-04-14 18:14:06 +0200 | [diff] [blame] | 376 | *Terminal-mode* *Terminal-Job* |
Bram Moolenaar | 423802d | 2017-07-30 16:52:24 +0200 | [diff] [blame] | 377 | When the job is running the contents of the terminal is under control of the |
Bram Moolenaar | dd693ce | 2017-08-10 23:15:19 +0200 | [diff] [blame] | 378 | job. That includes the cursor position. Typed keys are sent to the job. |
| 379 | The terminal contents can change at any time. This is called Terminal-Job |
| 380 | mode. |
Bram Moolenaar | 423802d | 2017-07-30 16:52:24 +0200 | [diff] [blame] | 381 | |
Bram Moolenaar | 7dda86f | 2018-04-20 22:36:41 +0200 | [diff] [blame] | 382 | Use CTRL-W N (or 'termwinkey' N) to switch to Terminal-Normal mode. Now the |
Bram Moolenaar | dd693ce | 2017-08-10 23:15:19 +0200 | [diff] [blame] | 383 | contents of the terminal window is under control of Vim, the job output is |
| 384 | suspended. CTRL-\ CTRL-N does the same. |
Bram Moolenaar | 69fbc9e | 2017-09-14 20:37:57 +0200 | [diff] [blame] | 385 | |
Bram Moolenaar | 1b9645d | 2017-09-17 23:03:31 +0200 | [diff] [blame] | 386 | Terminal-Job mode is where |:tmap| mappings are applied. Keys sent by |
Bram Moolenaar | 69fbc9e | 2017-09-14 20:37:57 +0200 | [diff] [blame] | 387 | |term_sendkeys()| are not subject to tmap, but keys from |feedkeys()| are. |
| 388 | |
Bram Moolenaar | 8c041b6 | 2018-04-14 18:14:06 +0200 | [diff] [blame] | 389 | It is not possible to enter Insert mode from Terminal-Job mode. |
| 390 | |
| 391 | *Terminal-Normal* *E946* |
Bram Moolenaar | dd693ce | 2017-08-10 23:15:19 +0200 | [diff] [blame] | 392 | In Terminal-Normal mode you can move the cursor around with the usual Vim |
| 393 | commands, Visually mark text, yank text, etc. But you cannot change the |
| 394 | contents of the buffer. The commands that would start insert mode, such as |
| 395 | 'i' and 'a', return to Terminal-Job mode. The window will be updated to show |
Bram Moolenaar | 1b9645d | 2017-09-17 23:03:31 +0200 | [diff] [blame] | 396 | the contents of the terminal. |:startinsert| is ineffective. |
Bram Moolenaar | 423802d | 2017-07-30 16:52:24 +0200 | [diff] [blame] | 397 | |
Bram Moolenaar | dd693ce | 2017-08-10 23:15:19 +0200 | [diff] [blame] | 398 | In Terminal-Normal mode the statusline and window title show "(Terminal)". If |
| 399 | the job ends while in Terminal-Normal mode this changes to |
| 400 | "(Terminal-finished)". |
Bram Moolenaar | 423802d | 2017-07-30 16:52:24 +0200 | [diff] [blame] | 401 | |
Bram Moolenaar | 8c041b6 | 2018-04-14 18:14:06 +0200 | [diff] [blame] | 402 | When the job outputs lines in the terminal, such that the contents scrolls off |
| 403 | the top, those lines are remembered and can be seen in Terminal-Normal mode. |
Bram Moolenaar | 7dda86f | 2018-04-20 22:36:41 +0200 | [diff] [blame] | 404 | The number of lines is limited by the 'termwinscroll' option. When going over |
Bram Moolenaar | 7db25fe | 2018-05-13 00:02:36 +0200 | [diff] [blame] | 405 | this limit, the first 10% of the scrolled lines are deleted and are lost. |
Bram Moolenaar | 8e539c5 | 2017-08-18 22:57:06 +0200 | [diff] [blame] | 406 | |
Bram Moolenaar | 423802d | 2017-07-30 16:52:24 +0200 | [diff] [blame] | 407 | |
Bram Moolenaar | c572da5 | 2017-08-27 16:52:01 +0200 | [diff] [blame] | 408 | Cursor style ~ |
Bram Moolenaar | 7f2e9d7 | 2017-11-11 20:58:53 +0100 | [diff] [blame] | 409 | *terminal-cursor-style* |
Bram Moolenaar | c572da5 | 2017-08-27 16:52:01 +0200 | [diff] [blame] | 410 | By default the cursor in the terminal window uses a not blinking block. The |
| 411 | normal xterm escape sequences can be used to change the blinking state and the |
| 412 | shape. Once focus leaves the terminal window Vim will restore the original |
| 413 | cursor. |
| 414 | |
| 415 | An exception is when xterm is started with the "-bc" argument, or another way |
| 416 | that causes the cursor to blink. This actually means that the blinking flag |
| 417 | is inverted. Since Vim cannot detect this, the terminal window cursor |
| 418 | blinking will also be inverted. |
| 419 | |
| 420 | |
Bram Moolenaar | b5b7562 | 2018-03-09 22:22:21 +0100 | [diff] [blame] | 421 | Session ~ |
| 422 | *terminal-session* |
| 423 | A terminal window will be restored when using a session file, if possible and |
| 424 | wanted. |
| 425 | |
| 426 | If "terminal" was removed from 'sessionoptions' then no terminal windows will |
| 427 | be restored. |
| 428 | |
| 429 | If the job in the terminal was finished the window will not be restored. |
| 430 | |
| 431 | If the terminal can be restored, the command that was used to open it will be |
| 432 | used again. To change this use the |term_setrestore()| function. This can |
| 433 | also be used to not restore a specific terminal by setting the command to |
| 434 | "NONE". |
| 435 | |
| 436 | |
Bram Moolenaar | 7f2e9d7 | 2017-11-11 20:58:53 +0100 | [diff] [blame] | 437 | Special keys ~ |
| 438 | *terminal-special-keys* |
| 439 | Since the terminal emulator simulates an xterm, only escape sequences that |
| 440 | both Vim and xterm recognize will be available in the terminal window. If you |
| 441 | want to pass on other escape sequences to the job running in the terminal you |
| 442 | need to set up forwarding. Example: > |
| 443 | tmap <expr> <Esc>]b SendToTerm("\<Esc>]b") |
Bram Moolenaar | 60e73f2 | 2017-11-12 18:02:06 +0100 | [diff] [blame] | 444 | func SendToTerm(what) |
| 445 | call term_sendkeys('', a:what) |
| 446 | return '' |
| 447 | endfunc |
Bram Moolenaar | b6e0ec6 | 2017-07-23 22:12:20 +0200 | [diff] [blame] | 448 | |
Bram Moolenaar | 7f2e9d7 | 2017-11-11 20:58:53 +0100 | [diff] [blame] | 449 | |
| 450 | Unix ~ |
| 451 | *terminal-unix* |
Bram Moolenaar | b6e0ec6 | 2017-07-23 22:12:20 +0200 | [diff] [blame] | 452 | On Unix a pty is used to make it possible to run all kinds of commands. You |
| 453 | can even run Vim in the terminal! That's used for debugging, see below. |
| 454 | |
Bram Moolenaar | f55e4c8 | 2017-08-01 20:44:53 +0200 | [diff] [blame] | 455 | Environment variables are used to pass information to the running job: |
Bram Moolenaar | 9a993e3 | 2018-04-05 22:15:22 +0200 | [diff] [blame] | 456 | TERM the name of the terminal, from the 'term' option or |
| 457 | $TERM in the GUI; falls back to "xterm" if it does not |
| 458 | start with "xterm" |
Bram Moolenaar | f55e4c8 | 2017-08-01 20:44:53 +0200 | [diff] [blame] | 459 | ROWS number of rows in the terminal initially |
| 460 | LINES same as ROWS |
| 461 | COLUMNS number of columns in the terminal initially |
| 462 | COLORS number of colors, 't_Co' (256*256*256 in the GUI) |
| 463 | VIM_SERVERNAME v:servername |
Bram Moolenaar | d7a137f | 2018-06-12 18:05:24 +0200 | [diff] [blame] | 464 | VIM_TERMINAL v:version |
Bram Moolenaar | f55e4c8 | 2017-08-01 20:44:53 +0200 | [diff] [blame] | 465 | |
Bram Moolenaar | b6e0ec6 | 2017-07-23 22:12:20 +0200 | [diff] [blame] | 466 | |
| 467 | MS-Windows ~ |
Bram Moolenaar | 7f2e9d7 | 2017-11-11 20:58:53 +0100 | [diff] [blame] | 468 | *terminal-ms-windows* |
Bram Moolenaar | 8a77306 | 2017-07-24 22:29:21 +0200 | [diff] [blame] | 469 | On MS-Windows winpty is used to make it possible to run all kind of commands. |
| 470 | Obviously, they must be commands that run in a terminal, not open their own |
| 471 | window. |
| 472 | |
| 473 | You need the following two files from winpty: |
| 474 | |
| 475 | winpty.dll |
| 476 | winpty-agent.exe |
| 477 | |
| 478 | You can download them from the following page: |
| 479 | |
| 480 | https://github.com/rprichard/winpty |
| 481 | |
Bram Moolenaar | 8e539c5 | 2017-08-18 22:57:06 +0200 | [diff] [blame] | 482 | Just put the files somewhere in your PATH. You can set the 'winptydll' option |
| 483 | to point to the right file, if needed. If you have both the 32-bit and 64-bit |
| 484 | version, rename to winpty32.dll and winpty64.dll to match the way Vim was |
| 485 | build. |
Bram Moolenaar | 5acd987 | 2019-02-16 13:35:13 +0100 | [diff] [blame] | 486 | *ConPTY* *E982* |
Bram Moolenaar | aa5df7e | 2019-02-03 14:53:10 +0100 | [diff] [blame] | 487 | On more recent versions of MS-Windows 10 (beginning with the "October 2018 |
| 488 | Update"), winpty is no longer required. On those versions, |:terminal| will use |
| 489 | Windows' built-in support for hosting terminal applications, "ConPTY". When |
| 490 | ConPTY is in use, there may be rendering artifacts regarding ambiguous-width |
Bram Moolenaar | 5acd987 | 2019-02-16 13:35:13 +0100 | [diff] [blame] | 491 | characters. If you encounter any such issues, install "winpty". Until the |
| 492 | ConPTY problems have been fixed "winpty" will be preferred. |
Bram Moolenaar | b6e0ec6 | 2017-07-23 22:12:20 +0200 | [diff] [blame] | 493 | |
Bram Moolenaar | 52dbb5e | 2017-11-21 18:11:27 +0100 | [diff] [blame] | 494 | Environment variables are used to pass information to the running job: |
| 495 | VIM_SERVERNAME v:servername |
| 496 | |
Aliaksei Budavei | 5eaacef | 2025-01-11 17:10:06 +0100 | [diff] [blame] | 497 | *git-vimdumps* |
| 498 | There exists a git-difftool extension called `git-vimdumps` that can be used |
| 499 | to conveniently inspect screendump files and diff them. Please see in the Vim |
| 500 | Repository the file `src/testdir/commondumps.vim` on how to create and use |
| 501 | this git extension. |
| 502 | |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 503 | ============================================================================== |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 504 | 2. Terminal functions *terminal-function-details* |
| 505 | |
| 506 | *term_dumpdiff()* |
| 507 | term_dumpdiff({filename}, {filename} [, {options}]) |
| 508 | Open a new window displaying the difference between the two |
| 509 | files. The files must have been created with |
| 510 | |term_dumpwrite()|. |
| 511 | Returns the buffer number or zero when the diff fails. |
| 512 | Also see |terminal-diff|. |
| 513 | NOTE: this does not work with double-width characters yet. |
| 514 | |
| 515 | The top part of the buffer contains the contents of the first |
| 516 | file, the bottom part of the buffer contains the contents of |
| 517 | the second file. The middle part shows the differences. |
| 518 | The parts are separated by a line of equals. |
| 519 | |
| 520 | If the {options} argument is present, it must be a Dict with |
| 521 | these possible members: |
| 522 | "term_name" name to use for the buffer name, instead |
| 523 | of the first file name. |
| 524 | "term_rows" vertical size to use for the terminal, |
Bram Moolenaar | 1c6737b | 2020-09-07 22:18:52 +0200 | [diff] [blame] | 525 | instead of using 'termwinsize', but |
| 526 | respecting the minimal size |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 527 | "term_cols" horizontal size to use for the terminal, |
Bram Moolenaar | 1c6737b | 2020-09-07 22:18:52 +0200 | [diff] [blame] | 528 | instead of using 'termwinsize', but |
| 529 | respecting the minimal size |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 530 | "vertical" split the window vertically |
| 531 | "curwin" use the current window, do not split the |
| 532 | window; fails if the current buffer |
| 533 | cannot be |abandon|ed |
| 534 | "bufnr" do not create a new buffer, use the |
| 535 | existing buffer "bufnr". This buffer |
| 536 | must have been previously created with |
| 537 | term_dumpdiff() or term_dumpload() and |
| 538 | visible in a window. |
| 539 | "norestore" do not add the terminal window to a |
| 540 | session file |
| 541 | |
| 542 | Each character in the middle part indicates a difference. If |
| 543 | there are multiple differences only the first in this list is |
| 544 | used: |
| 545 | X different character |
| 546 | w different width |
| 547 | f different foreground color |
| 548 | b different background color |
| 549 | a different attribute |
| 550 | + missing position in first file |
| 551 | - missing position in second file |
Bram Moolenaar | 4466ad6 | 2020-11-21 13:16:30 +0100 | [diff] [blame] | 552 | > cursor position in first file, not in second |
Bram Moolenaar | 23515b4 | 2020-11-29 14:36:24 +0100 | [diff] [blame] | 553 | < cursor position in second file, not in first |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 554 | |
| 555 | Using the "s" key the top and bottom parts are swapped. This |
| 556 | makes it easy to spot a difference. |
| 557 | |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 558 | Can also be used as a |method|: > |
| 559 | GetFilename()->term_dumpdiff(otherfile) |
| 560 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 561 | Return type: |Number| |
| 562 | |
| 563 | |
| 564 | term_dumpload({filename} [, {options}]) *term_dumpload()* |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 565 | Open a new window displaying the contents of {filename} |
| 566 | The file must have been created with |term_dumpwrite()|. |
| 567 | Returns the buffer number or zero when it fails. |
| 568 | Also see |terminal-diff|. |
| 569 | |
| 570 | For {options} see |term_dumpdiff()|. |
| 571 | |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 572 | Can also be used as a |method|: > |
Bram Moolenaar | 2e693a8 | 2019-10-16 22:35:02 +0200 | [diff] [blame] | 573 | GetFilename()->term_dumpload() |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 574 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 575 | Return type: |Number| |
| 576 | |
| 577 | |
| 578 | term_dumpwrite({buf}, {filename} [, {options}]) *term_dumpwrite()* |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 579 | Dump the contents of the terminal screen of {buf} in the file |
| 580 | {filename}. This uses a format that can be used with |
| 581 | |term_dumpload()| and |term_dumpdiff()|. |
| 582 | If the job in the terminal already finished an error is given: |
| 583 | *E958* |
| 584 | If {filename} already exists an error is given: *E953* |
| 585 | Also see |terminal-diff|. |
| 586 | |
| 587 | {options} is a dictionary with these optional entries: |
| 588 | "rows" maximum number of rows to dump |
| 589 | "columns" maximum number of columns to dump |
| 590 | |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 591 | Can also be used as a |method|, the base is used for the file |
| 592 | name: > |
Bram Moolenaar | 2e693a8 | 2019-10-16 22:35:02 +0200 | [diff] [blame] | 593 | GetFilename()->term_dumpwrite(bufnr) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 594 | < |
| 595 | Return type: |Number| |
| 596 | |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 597 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 598 | term_getaltscreen({buf}) *term_getaltscreen()* |
| 599 | Returns 1 if the terminal of {buf} is using the alternate |
| 600 | screen. |
| 601 | {buf} is used as with |term_getsize()|. |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 602 | |
| 603 | Can also be used as a |method|: > |
| 604 | GetBufnr()->term_getaltscreen() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 605 | < |
| 606 | Return type: |Number| |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 607 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 608 | |
| 609 | term_getansicolors({buf}) *term_getansicolors()* |
| 610 | Get the ANSI color palette in use by terminal {buf}. |
| 611 | Returns a List of length 16 where each element is a String |
| 612 | representing a color in hexadecimal "#rrggbb" format. |
| 613 | Also see |term_setansicolors()| and |g:terminal_ansi_colors|. |
| 614 | If neither was used returns the default colors. |
| 615 | |
| 616 | {buf} is used as with |term_getsize()|. If the buffer does not |
| 617 | exist or is not a terminal window, an empty list is returned. |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 618 | |
| 619 | Can also be used as a |method|: > |
| 620 | GetBufnr()->term_getansicolors() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 621 | < |
| 622 | Return type: list<string> or list<any> |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 623 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 624 | {only available when compiled with GUI enabled and/or the |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 625 | |+termguicolors| feature} |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 626 | |
| 627 | term_getattr({attr}, {what}) *term_getattr()* |
| 628 | Given {attr}, a value returned by term_scrape() in the "attr" |
| 629 | item, return whether {what} is on. {what} can be one of: |
| 630 | bold |
| 631 | italic |
| 632 | underline |
| 633 | strike |
| 634 | reverse |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 635 | |
| 636 | Can also be used as a |method|: > |
| 637 | GetAttr()->term_getattr() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 638 | < |
| 639 | Return type: |Number| |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 640 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 641 | |
| 642 | term_getcursor({buf}) *term_getcursor()* |
| 643 | Get the cursor position of terminal {buf}. Returns a list with |
| 644 | two numbers and a dictionary: [row, col, dict]. |
| 645 | |
| 646 | "row" and "col" are one based, the first screen cell is row |
| 647 | 1, column 1. This is the cursor position of the terminal |
| 648 | itself, not of the Vim window. |
| 649 | |
| 650 | "dict" can have these members: |
| 651 | "visible" one when the cursor is visible, zero when it |
| 652 | is hidden. |
| 653 | "blink" one when the cursor is blinking, zero when it |
| 654 | is not blinking. |
| 655 | "shape" 1 for a block cursor, 2 for underline and 3 |
| 656 | for a vertical bar. |
| 657 | "color" color of the cursor, e.g. "green" |
| 658 | |
| 659 | {buf} must be the buffer number of a terminal window. If the |
| 660 | buffer does not exist or is not a terminal window, an empty |
| 661 | list is returned. |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 662 | |
| 663 | Can also be used as a |method|: > |
| 664 | GetBufnr()->term_getcursor() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 665 | < |
| 666 | Return type: list<any> |
| 667 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 668 | |
| 669 | term_getjob({buf}) *term_getjob()* |
| 670 | Get the Job associated with terminal window {buf}. |
| 671 | {buf} is used as with |term_getsize()|. |
Ernie Rael | a78eb25 | 2024-06-13 17:24:54 +0200 | [diff] [blame] | 672 | Returns |v:null| when there is no job. In Vim9 script, return |
h-east | 84ac212 | 2024-06-17 18:12:30 +0200 | [diff] [blame] | 673 | |null_job| when there is no job. |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 674 | |
| 675 | Can also be used as a |method|: > |
| 676 | GetBufnr()->term_getjob() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 677 | < |
| 678 | Return type: |job| |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 679 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 680 | |
| 681 | term_getline({buf}, {row}) *term_getline()* |
| 682 | Get a line of text from the terminal window of {buf}. |
| 683 | {buf} is used as with |term_getsize()|. |
| 684 | |
| 685 | The first line has {row} one. When {row} is "." the cursor |
| 686 | line is used. When {row} is invalid an empty string is |
| 687 | returned. |
| 688 | |
| 689 | To get attributes of each character use |term_scrape()|. |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 690 | |
| 691 | Can also be used as a |method|: > |
| 692 | GetBufnr()->term_getline(row) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 693 | < |
| 694 | Return type: |String| |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 695 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 696 | |
| 697 | term_getscrolled({buf}) *term_getscrolled()* |
| 698 | Return the number of lines that scrolled to above the top of |
| 699 | terminal {buf}. This is the offset between the row number |
| 700 | used for |term_getline()| and |getline()|, so that: > |
| 701 | term_getline(buf, N) |
| 702 | < is equal to: > |
| 703 | getline(N + term_getscrolled(buf)) |
| 704 | < (if that line exists). |
| 705 | |
| 706 | {buf} is used as with |term_getsize()|. |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 707 | |
| 708 | Can also be used as a |method|: > |
| 709 | GetBufnr()->term_getscrolled() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 710 | < |
| 711 | Return type: |Number| |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 712 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 713 | |
| 714 | term_getsize({buf}) *term_getsize()* |
| 715 | Get the size of terminal {buf}. Returns a list with two |
| 716 | numbers: [rows, cols]. This is the size of the terminal, not |
| 717 | the window containing the terminal. |
| 718 | |
| 719 | {buf} must be the buffer number of a terminal window. Use an |
| 720 | empty string for the current buffer. If the buffer does not |
| 721 | exist or is not a terminal window, an empty list is returned. |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 722 | |
| 723 | Can also be used as a |method|: > |
| 724 | GetBufnr()->term_getsize() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 725 | < |
| 726 | Return type: list<number> or list<any> |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 727 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 728 | |
| 729 | term_getstatus({buf}) *term_getstatus()* |
Bram Moolenaar | 2963456 | 2020-01-09 21:46:04 +0100 | [diff] [blame] | 730 | Get the status of terminal {buf}. This returns a String with |
Bram Moolenaar | cbaff5e | 2022-04-08 17:45:08 +0100 | [diff] [blame] | 731 | a comma-separated list of these items: |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 732 | running job is running |
| 733 | finished job has finished |
| 734 | normal in Terminal-Normal mode |
| 735 | One of "running" or "finished" is always present. |
| 736 | |
| 737 | {buf} must be the buffer number of a terminal window. If the |
| 738 | buffer does not exist or is not a terminal window, an empty |
| 739 | string is returned. |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 740 | |
| 741 | Can also be used as a |method|: > |
| 742 | GetBufnr()->term_getstatus() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 743 | < |
| 744 | Return type: |String| |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 745 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 746 | |
| 747 | term_gettitle({buf}) *term_gettitle()* |
| 748 | Get the title of terminal {buf}. This is the title that the |
| 749 | job in the terminal has set. |
| 750 | |
| 751 | {buf} must be the buffer number of a terminal window. If the |
| 752 | buffer does not exist or is not a terminal window, an empty |
| 753 | string is returned. |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 754 | |
| 755 | Can also be used as a |method|: > |
| 756 | GetBufnr()->term_gettitle() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 757 | < |
| 758 | Return type: |String| |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 759 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 760 | |
| 761 | term_gettty({buf} [, {input}]) *term_gettty()* |
| 762 | Get the name of the controlling terminal associated with |
| 763 | terminal window {buf}. {buf} is used as with |term_getsize()|. |
| 764 | |
| 765 | When {input} is omitted or 0, return the name for writing |
| 766 | (stdout). When {input} is 1 return the name for reading |
| 767 | (stdin). On UNIX, both return same name. |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 768 | |
| 769 | Can also be used as a |method|: > |
| 770 | GetBufnr()->term_gettty() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 771 | < |
| 772 | Return type: |String| |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 773 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 774 | |
| 775 | term_list() *term_list()* |
| 776 | Return a list with the buffer numbers of all buffers for |
| 777 | terminal windows. |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 778 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 779 | Return type: list<number> or list<any> |
| 780 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 781 | |
| 782 | term_scrape({buf}, {row}) *term_scrape()* |
| 783 | Get the contents of {row} of terminal screen of {buf}. |
| 784 | For {buf} see |term_getsize()|. |
| 785 | |
| 786 | The first line has {row} one. When {row} is "." the cursor |
| 787 | line is used. When {row} is invalid an empty string is |
| 788 | returned. |
| 789 | |
| 790 | Return a List containing a Dict for each screen cell: |
| 791 | "chars" character(s) at the cell |
| 792 | "fg" foreground color as #rrggbb |
| 793 | "bg" background color as #rrggbb |
| 794 | "attr" attributes of the cell, use |term_getattr()| |
| 795 | to get the individual flags |
| 796 | "width" cell width: 1 or 2 |
Bram Moolenaar | 942db23 | 2021-02-13 18:14:48 +0100 | [diff] [blame] | 797 | For a double-width cell there is one item, thus the list can |
| 798 | be shorter than the width of the terminal. |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 799 | |
| 800 | Can also be used as a |method|: > |
| 801 | GetBufnr()->term_scrape(row) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 802 | < |
| 803 | Return type: list<dict<any>> or list<any> |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 804 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 805 | |
| 806 | term_sendkeys({buf}, {keys}) *term_sendkeys()* |
| 807 | Send keystrokes {keys} to terminal {buf}. |
| 808 | {buf} is used as with |term_getsize()|. |
| 809 | |
| 810 | {keys} are translated as key sequences. For example, "\<c-x>" |
| 811 | means the character CTRL-X. |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 812 | |
| 813 | Can also be used as a |method|: > |
| 814 | GetBufnr()->term_sendkeys(keys) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 815 | < |
| 816 | Return type: |Number| |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 817 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 818 | |
| 819 | term_setansicolors({buf}, {colors}) *term_setansicolors()* |
| 820 | Set the ANSI color palette used by terminal {buf}. |
| 821 | {colors} must be a List of 16 valid color names or hexadecimal |
| 822 | color codes, like those accepted by |highlight-guifg|. |
| 823 | Also see |term_getansicolors()| and |g:terminal_ansi_colors|. |
| 824 | |
| 825 | The colors normally are: |
| 826 | 0 black |
| 827 | 1 dark red |
| 828 | 2 dark green |
| 829 | 3 brown |
| 830 | 4 dark blue |
| 831 | 5 dark magenta |
| 832 | 6 dark cyan |
| 833 | 7 light grey |
| 834 | 8 dark grey |
| 835 | 9 red |
| 836 | 10 green |
| 837 | 11 yellow |
| 838 | 12 blue |
| 839 | 13 magenta |
| 840 | 14 cyan |
| 841 | 15 white |
| 842 | |
| 843 | These colors are used in the GUI and in the terminal when |
| 844 | 'termguicolors' is set. When not using GUI colors (GUI mode |
| 845 | or 'termguicolors'), the terminal window always uses the 16 |
| 846 | ANSI colors of the underlying terminal. |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 847 | |
| 848 | Can also be used as a |method|: > |
| 849 | GetBufnr()->term_setansicolors(colors) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 850 | < |
| 851 | Return type: |Number| |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 852 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 853 | {only available with GUI enabled and/or the |+termguicolors| |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 854 | feature} |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 855 | |
Bram Moolenaar | 89a9c15 | 2021-08-29 21:55:35 +0200 | [diff] [blame] | 856 | |
| 857 | term_setapi({buf}, {expr}) *term_setapi()* |
| 858 | Set the function name prefix to be used for the |terminal-api| |
| 859 | function in terminal {buf}. For example: > |
| 860 | :call term_setapi(buf, "Myapi_") |
| 861 | :call term_setapi(buf, "") |
| 862 | < |
| 863 | The default is "Tapi_". When {expr} is an empty string then |
| 864 | no |terminal-api| function can be used for {buf}. |
| 865 | |
| 866 | When used as a method the base is used for {buf}: > |
| 867 | GetBufnr()->term_setapi({expr}) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 868 | < |
| 869 | Return type: |Number| |
Bram Moolenaar | 89a9c15 | 2021-08-29 21:55:35 +0200 | [diff] [blame] | 870 | |
| 871 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 872 | term_setkill({buf}, {how}) *term_setkill()* |
| 873 | When exiting Vim or trying to close the terminal window in |
| 874 | another way, {how} defines whether the job in the terminal can |
| 875 | be stopped. |
| 876 | When {how} is empty (the default), the job will not be |
| 877 | stopped, trying to exit will result in |E947|. |
| 878 | Otherwise, {how} specifies what signal to send to the job. |
| 879 | See |job_stop()| for the values. |
| 880 | |
| 881 | After sending the signal Vim will wait for up to a second to |
| 882 | check that the job actually stopped. |
| 883 | |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 884 | Can also be used as a |method|: > |
| 885 | GetBufnr()->term_setkill(how) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 886 | < |
| 887 | Return type: |Number| |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 888 | |
| 889 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 890 | term_setrestore({buf}, {command}) *term_setrestore()* |
| 891 | Set the command to write in a session file to restore the job |
| 892 | in this terminal. The line written in the session file is: > |
| 893 | terminal ++curwin ++cols=%d ++rows=%d {command} |
| 894 | < Make sure to escape the command properly. |
| 895 | |
| 896 | Use an empty {command} to run 'shell'. |
| 897 | Use "NONE" to not restore this window. |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 898 | |
| 899 | Can also be used as a |method|: > |
| 900 | GetBufnr()->term_setrestore(command) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 901 | < |
| 902 | Return type: |Number| |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 903 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 904 | |
| 905 | term_setsize({buf}, {rows}, {cols}) *term_setsize()* *E955* |
| 906 | Set the size of terminal {buf}. The size of the window |
| 907 | containing the terminal will also be adjusted, if possible. |
| 908 | If {rows} or {cols} is zero or negative, that dimension is not |
| 909 | changed. |
| 910 | |
| 911 | {buf} must be the buffer number of a terminal window. Use an |
| 912 | empty string for the current buffer. If the buffer does not |
| 913 | exist or is not a terminal window, an error is given. |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 914 | |
| 915 | Can also be used as a |method|: > |
| 916 | GetBufnr()->term_setsize(rows, cols) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 917 | < |
| 918 | Return type: |Number| |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 919 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 920 | |
| 921 | term_start({cmd} [, {options}]) *term_start()* |
| 922 | Open a terminal window and run {cmd} in it. |
| 923 | |
| 924 | {cmd} can be a string or a List, like with |job_start()|. The |
| 925 | string "NONE" can be used to open a terminal window without |
| 926 | starting a job, the pty of the terminal can be used by a |
| 927 | command like gdb. |
| 928 | |
| 929 | Returns the buffer number of the terminal window. If {cmd} |
| 930 | cannot be executed the window does open and shows an error |
| 931 | message. |
| 932 | If opening the window fails zero is returned. |
| 933 | |
| 934 | {options} are similar to what is used for |job_start()|, see |
| 935 | |job-options|. However, not all options can be used. These |
| 936 | are supported: |
| 937 | all timeout options |
| 938 | "stoponexit", "cwd", "env" |
| 939 | "callback", "out_cb", "err_cb", "exit_cb", "close_cb" |
| 940 | "in_io", "in_top", "in_bot", "in_name", "in_buf" |
| 941 | "out_io", "out_name", "out_buf", "out_modifiable", "out_msg" |
| 942 | "err_io", "err_name", "err_buf", "err_modifiable", "err_msg" |
| 943 | However, at least one of stdin, stdout or stderr must be |
| 944 | connected to the terminal. When I/O is connected to the |
| 945 | terminal then the callback function for that part is not used. |
| 946 | |
| 947 | There are extra options: |
| 948 | "term_name" name to use for the buffer name, instead |
| 949 | of the command name. |
| 950 | "term_rows" vertical size to use for the terminal, |
Bram Moolenaar | 5300be6 | 2021-11-13 10:27:40 +0000 | [diff] [blame] | 951 | instead of using 'termwinsize'; valid |
| 952 | range is from zero to 1000 |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 953 | "term_cols" horizontal size to use for the terminal, |
| 954 | instead of using 'termwinsize' |
| 955 | "vertical" split the window vertically; note that |
| 956 | other window position can be defined with |
| 957 | command modifiers, such as |:belowright|. |
| 958 | "curwin" use the current window, do not split the |
| 959 | window; fails if the current buffer |
| 960 | cannot be |abandon|ed |
| 961 | "hidden" do not open a window |
| 962 | "norestore" do not add the terminal window to a |
| 963 | session file |
| 964 | "term_kill" what to do when trying to close the |
| 965 | terminal window, see |term_setkill()| |
| 966 | "term_finish" What to do when the job is finished: |
| 967 | "close": close any windows |
| 968 | "open": open window if needed |
| 969 | Note that "open" can be interruptive. |
| 970 | See |term++close| and |term++open|. |
| 971 | "term_opencmd" command to use for opening the window when |
| 972 | "open" is used for "term_finish"; must |
| 973 | have "%d" where the buffer number goes, |
| 974 | e.g. "10split|buffer %d"; when not |
| 975 | specified "botright sbuf %d" is used |
Bram Moolenaar | 83d4790 | 2020-03-26 20:34:00 +0100 | [diff] [blame] | 976 | "term_highlight" highlight group to use instead of |
| 977 | "Terminal" |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 978 | "eof_chars" Text to send after all buffer lines were |
| 979 | written to the terminal. When not set |
| 980 | CTRL-D is used on MS-Windows. For Python |
| 981 | use CTRL-Z or "exit()". For a shell use |
| 982 | "exit". A CR is always added. |
| 983 | "ansi_colors" A list of 16 color names or hex codes |
| 984 | defining the ANSI palette used in GUI |
| 985 | color modes. See |g:terminal_ansi_colors|. |
| 986 | "tty_type" (MS-Windows only): Specify which pty to |
| 987 | use. See 'termwintype' for the values. |
Bram Moolenaar | d2842ea | 2019-09-26 23:08:54 +0200 | [diff] [blame] | 988 | "term_api" function name prefix for the |
| 989 | |terminal-api| function. See |
| 990 | |term_setapi()|. |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 991 | |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 992 | Can also be used as a |method|: > |
| 993 | GetCommand()->term_start() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 994 | < |
| 995 | Return type: |Number| |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 996 | |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 997 | |
| 998 | term_wait({buf} [, {time}]) *term_wait()* |
| 999 | Wait for pending updates of {buf} to be handled. |
| 1000 | {buf} is used as with |term_getsize()|. |
| 1001 | {time} is how long to wait for updates to arrive in msec. If |
Yee Cheng Chin | e70587d | 2025-02-13 20:55:45 +0100 | [diff] [blame] | 1002 | not set then 10 msec will be used. Queued messages will also |
| 1003 | be processed similar to |:sleep|. |
Bram Moolenaar | 7ee80f7 | 2019-09-08 20:55:06 +0200 | [diff] [blame] | 1004 | |
| 1005 | Can also be used as a |method|: > |
| 1006 | GetBufnr()->term_wait() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1007 | < |
| 1008 | Return type: |Number| |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 1009 | |
| 1010 | ============================================================================== |
| 1011 | 3. Terminal communication *terminal-communication* |
Bram Moolenaar | 8fbaeb1 | 2018-03-25 18:20:17 +0200 | [diff] [blame] | 1012 | |
| 1013 | There are several ways to communicate with the job running in a terminal: |
| 1014 | - Use |term_sendkeys()| to send text and escape sequences from Vim to the job. |
| 1015 | - Use the JSON API to send encoded commands from the job to Vim. |
| 1016 | - Use the |client-server| mechanism. This works on machines with an X server |
| 1017 | and on MS-Windows. |
| 1018 | |
| 1019 | |
| 1020 | Vim to job: term_sendkeys() ~ |
| 1021 | *terminal-to-job* |
| 1022 | This allows for remote controlling the job running in the terminal. It is a |
| 1023 | one-way mechanism. The job can update the display to signal back to Vim. |
| 1024 | For example, if a shell is running in a terminal, you can do: > |
| 1025 | call term_sendkeys(buf, "ls *.java\<CR>") |
| 1026 | |
| 1027 | This requires for the job to be in the right state where it will do the right |
| 1028 | thing when receiving the keys. For the above example, the shell must be |
| 1029 | waiting for a command to be typed. |
| 1030 | |
| 1031 | For a job that was written for the purpose, you can use the JSON API escape |
| 1032 | sequence in the other direction. E.g.: > |
| 1033 | call term_sendkeys(buf, "\<Esc>]51;["response"]\x07") |
| 1034 | |
| 1035 | |
| 1036 | Job to Vim: JSON API ~ |
| 1037 | *terminal-api* |
| 1038 | The job can send JSON to Vim, using a special escape sequence. The JSON |
| 1039 | encodes a command that Vim understands. Example of such a message: > |
| 1040 | <Esc>]51;["drop", "README.md"]<07> |
| 1041 | |
| 1042 | The body is always a list, making it easy to find the end: ]<07>. |
| 1043 | The <Esc>]51;msg<07> sequence is reserved by xterm for "Emacs shell", which is |
| 1044 | similar to what we are doing here. |
| 1045 | |
| 1046 | Currently supported commands: |
| 1047 | |
| 1048 | call {funcname} {argument} |
| 1049 | |
Bram Moolenaar | 2a77d21 | 2018-03-26 21:38:52 +0200 | [diff] [blame] | 1050 | Call a user defined function with {argument}. |
| 1051 | The function is called with two arguments: the buffer number |
Bram Moolenaar | 664f3cf | 2019-12-07 16:03:51 +0100 | [diff] [blame] | 1052 | of the terminal and {argument}, the decoded JSON argument. |
Bram Moolenaar | d2842ea | 2019-09-26 23:08:54 +0200 | [diff] [blame] | 1053 | By default, the function name must start with "Tapi_" to avoid |
Bram Moolenaar | 2a77d21 | 2018-03-26 21:38:52 +0200 | [diff] [blame] | 1054 | accidentally calling a function not meant to be used for the |
Bram Moolenaar | d2842ea | 2019-09-26 23:08:54 +0200 | [diff] [blame] | 1055 | terminal API. This can be changed with |term_setapi()|. |
Bram Moolenaar | 2a77d21 | 2018-03-26 21:38:52 +0200 | [diff] [blame] | 1056 | The user function should sanity check the argument. |
Bram Moolenaar | 8fbaeb1 | 2018-03-25 18:20:17 +0200 | [diff] [blame] | 1057 | The function can use |term_sendkeys()| to send back a reply. |
| 1058 | Example in JSON: > |
Bram Moolenaar | 2a77d21 | 2018-03-26 21:38:52 +0200 | [diff] [blame] | 1059 | ["call", "Tapi_Impression", ["play", 14]] |
Bram Moolenaar | 8fbaeb1 | 2018-03-25 18:20:17 +0200 | [diff] [blame] | 1060 | < Calls a function defined like this: > |
Bram Moolenaar | 2a77d21 | 2018-03-26 21:38:52 +0200 | [diff] [blame] | 1061 | function Tapi_Impression(bufnum, arglist) |
Bram Moolenaar | 8fbaeb1 | 2018-03-25 18:20:17 +0200 | [diff] [blame] | 1062 | if len(a:arglist) == 2 |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 1063 | echomsg "impression " .. a:arglist[0] |
| 1064 | echomsg "count " .. a:arglist[1] |
Bram Moolenaar | 8fbaeb1 | 2018-03-25 18:20:17 +0200 | [diff] [blame] | 1065 | endif |
| 1066 | endfunc |
Bram Moolenaar | 2a77d21 | 2018-03-26 21:38:52 +0200 | [diff] [blame] | 1067 | < Output from `:echo` may be erased by a redraw, use `:echomsg` |
| 1068 | to be able to see it with `:messages`. |
| 1069 | |
Bram Moolenaar | 333b80a | 2018-04-04 22:57:29 +0200 | [diff] [blame] | 1070 | drop {filename} [options] |
Bram Moolenaar | 8fbaeb1 | 2018-03-25 18:20:17 +0200 | [diff] [blame] | 1071 | |
| 1072 | Let Vim open a file, like the `:drop` command. If {filename} |
| 1073 | is already open in a window, switch to that window. Otherwise |
| 1074 | open a new window to edit {filename}. |
Bram Moolenaar | 85eee13 | 2018-05-06 17:57:30 +0200 | [diff] [blame] | 1075 | Note that both the job and Vim may change the current |
| 1076 | directory, thus it's best to use the full path. |
Bram Moolenaar | 333b80a | 2018-04-04 22:57:29 +0200 | [diff] [blame] | 1077 | |
| 1078 | [options] is only used when opening a new window. If present, |
Bram Moolenaar | d1caa94 | 2020-04-10 22:10:56 +0200 | [diff] [blame] | 1079 | it must be a Dict. Similarly to |++opt|, these entries are |
Bram Moolenaar | 68e6560 | 2019-05-26 21:33:31 +0200 | [diff] [blame] | 1080 | recognized: |
Bram Moolenaar | 333b80a | 2018-04-04 22:57:29 +0200 | [diff] [blame] | 1081 | "ff" file format: "dos", "mac" or "unix" |
| 1082 | "fileformat" idem |
| 1083 | "enc" overrides 'fileencoding' |
| 1084 | "encoding" idem |
| 1085 | "bin" sets 'binary' |
| 1086 | "binary" idem |
| 1087 | "nobin" resets 'binary' |
| 1088 | "nobinary" idem |
| 1089 | "bad" specifies behavior for bad characters, see |
| 1090 | |++bad| |
| 1091 | |
Bram Moolenaar | 8fbaeb1 | 2018-03-25 18:20:17 +0200 | [diff] [blame] | 1092 | Example in JSON: > |
| 1093 | ["drop", "path/file.txt", {"ff": "dos"}] |
| 1094 | |
Christian Brabandt | 14e8208 | 2025-02-22 13:35:15 +0100 | [diff] [blame] | 1095 | You can use |echoraw()| to make Vim send this escape sequence: > |
| 1096 | call echoraw("\<ESC>]51;[\"call\", \"Tapi_TryThis\", [\"hello\", 123]]\x07") |
| 1097 | call echoraw("\<Esc>]51;[\"drop\", \"README.md\"]\x07") |
| 1098 | Note: JSON requires double quotes around string values, hence those have to be |
| 1099 | escaped. |
Bram Moolenaar | 8fbaeb1 | 2018-03-25 18:20:17 +0200 | [diff] [blame] | 1100 | |
| 1101 | Rationale: Why not allow for any command or expression? Because that might |
| 1102 | create a security problem. |
Bram Moolenaar | 48c3f4e | 2022-08-08 15:42:38 +0100 | [diff] [blame] | 1103 | *terminal-autoshelldir* |
| 1104 | This can be used to pass the current directory from a shell to Vim. |
| 1105 | Put this in your .vimrc: > |
Bram Moolenaar | fd99945 | 2022-08-24 18:30:14 +0100 | [diff] [blame] | 1106 | def g:Tapi_lcd(_, path: string) |
| 1107 | if isdirectory(path) |
zeertzjq | d086b8f | 2024-02-25 15:42:52 +0800 | [diff] [blame] | 1108 | execute 'silent lcd ' .. fnameescape(path) |
| 1109 | endif |
Bram Moolenaar | 48c3f4e | 2022-08-08 15:42:38 +0100 | [diff] [blame] | 1110 | enddef |
| 1111 | < |
| 1112 | And, in a bash init file: > |
zeertzjq | d086b8f | 2024-02-25 15:42:52 +0800 | [diff] [blame] | 1113 | if [[ -n "$VIM_TERMINAL" ]]; then |
| 1114 | PROMPT_COMMAND='_vim_sync_PWD' |
| 1115 | function _vim_sync_PWD() { |
| 1116 | printf '\033]51;["call", "Tapi_lcd", "%q"]\007' "$PWD" |
| 1117 | } |
| 1118 | fi |
Bram Moolenaar | 48c3f4e | 2022-08-08 15:42:38 +0100 | [diff] [blame] | 1119 | < |
| 1120 | Or, for zsh: > |
| 1121 | if [[ -n "$VIM_TERMINAL" ]]; then |
| 1122 | autoload -Uz add-zsh-hook |
| 1123 | add-zsh-hook -Uz chpwd _vim_sync_PWD |
| 1124 | function _vim_sync_PWD() { |
| 1125 | printf '\033]51;["call", "Tapi_lcd", "%q"]\007' "$PWD" |
| 1126 | } |
| 1127 | fi |
| 1128 | < |
| 1129 | Or, for fish: > |
| 1130 | if test -n "$VIM_TERMINAL" |
| 1131 | function _vim_sync_PWD --on-variable=PWD |
| 1132 | printf '\033]51;["call", "Tapi_lcd", "%s"]\007' "$PWD" |
| 1133 | end |
| 1134 | end |
Bram Moolenaar | 8fbaeb1 | 2018-03-25 18:20:17 +0200 | [diff] [blame] | 1135 | |
| 1136 | |
| 1137 | Using the client-server feature ~ |
| 1138 | *terminal-client-server* |
| 1139 | This only works when v:servername is not empty. If needed you can set it, |
| 1140 | before opening the terminal, with: > |
| 1141 | call remote_startserver('vim-server') |
| 1142 | |
| 1143 | $VIM_SERVERNAME is set in the terminal to pass on the server name. |
| 1144 | |
| 1145 | In the job you can then do something like: > |
| 1146 | vim --servername $VIM_SERVERNAME --remote +123 some_file.c |
| 1147 | This will open the file "some_file.c" and put the cursor on line 123. |
| 1148 | |
| 1149 | ============================================================================== |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 1150 | 4. Remote testing *terminal-testing* |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 1151 | |
| 1152 | Most Vim tests execute a script inside Vim. For some tests this does not |
| 1153 | work, running the test interferes with the code being tested. To avoid this |
| 1154 | Vim is executed in a terminal window. The test sends keystrokes to it and |
| 1155 | inspects the resulting screen state. |
| 1156 | |
| 1157 | Functions ~ |
| 1158 | |
Bram Moolenaar | 6dc819b | 2018-07-03 16:42:19 +0200 | [diff] [blame] | 1159 | |term_sendkeys()| send keystrokes to a terminal (not subject to tmap) |
| 1160 | |term_wait()| wait for screen to be updated |
| 1161 | |term_scrape()| inspect terminal screen |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 1162 | |
| 1163 | |
| 1164 | ============================================================================== |
Bram Moolenaar | 6bf2c62 | 2019-07-04 17:12:09 +0200 | [diff] [blame] | 1165 | 5. Diffing screen dumps *terminal-diff* |
Bram Moolenaar | da65058 | 2018-02-20 15:51:40 +0100 | [diff] [blame] | 1166 | |
| 1167 | In some cases it can be bothersome to test that Vim displays the right |
| 1168 | characters on the screen. E.g. with syntax highlighting. To make this |
| 1169 | simpler it is possible to take a screen dump of a terminal and compare it to |
| 1170 | an expected screen dump. |
| 1171 | |
| 1172 | Vim uses the window size, text, color and other attributes as displayed. The |
| 1173 | Vim screen size, font and other properties do not matter. Therefore this |
Bram Moolenaar | 98ef233 | 2018-03-18 14:44:37 +0100 | [diff] [blame] | 1174 | mechanism is portable across systems. A conventional screenshot would reflect |
Bram Moolenaar | da65058 | 2018-02-20 15:51:40 +0100 | [diff] [blame] | 1175 | all differences, including font size and family. |
| 1176 | |
| 1177 | |
| 1178 | Writing a screen dump test for Vim ~ |
| 1179 | *terminal-dumptest* |
| 1180 | For an example see the Test_syntax_c() function in |
| 1181 | src/testdir/test_syntax.vim. The main parts are: |
| 1182 | - Write a file you want to test with. This is useful for testing syntax |
Bram Moolenaar | 560979e | 2020-02-04 22:53:05 +0100 | [diff] [blame] | 1183 | highlighting. You can also start Vim with an empty buffer. |
Bram Moolenaar | da65058 | 2018-02-20 15:51:40 +0100 | [diff] [blame] | 1184 | - Run Vim in a terminal with a specific size. The default is 20 lines of 75 |
| 1185 | characters. This makes sure the dump is always this size. The function |
| 1186 | RunVimInTerminal() takes care of this. Pass it the arguments for the Vim |
| 1187 | command. |
Bram Moolenaar | 6dc819b | 2018-07-03 16:42:19 +0200 | [diff] [blame] | 1188 | - Send any commands to Vim using |term_sendkeys()|. For example: > |
Bram Moolenaar | da65058 | 2018-02-20 15:51:40 +0100 | [diff] [blame] | 1189 | call term_sendkeys(buf, ":echo &lines &columns\<CR>") |
| 1190 | - Check that the screen is now in the expected state, using |
| 1191 | VerifyScreenDump(). This expects the reference screen dump to be in the |
| 1192 | src/testdir/dumps/ directory. Pass the name without ".dump". It is |
| 1193 | recommended to use the name of the test function and a sequence number, so |
| 1194 | that we know what test is using the file. |
| 1195 | - Repeat sending commands and checking the state. |
| 1196 | - Finally stop Vim by calling StopVimInTerminal(). |
| 1197 | |
| 1198 | The first time you do this you won't have a screen dump yet. Create an empty |
| 1199 | file for now, e.g.: > |
| 1200 | touch src/testdir/dumps/Test_function_name_01.dump |
| 1201 | |
| 1202 | The test will then fail, giving you the command to compare the reference dump |
| 1203 | and the failed dump, e.g.: > |
Bram Moolenaar | 0c0734d | 2019-11-26 21:44:46 +0100 | [diff] [blame] | 1204 | call term_dumpdiff("failed/Test_func.dump", "dumps/Test_func.dump") |
Bram Moolenaar | da65058 | 2018-02-20 15:51:40 +0100 | [diff] [blame] | 1205 | |
| 1206 | Use this command in Vim, with the current directory set to src/testdir. |
| 1207 | Once you are satisfied with the test, move the failed dump in place of the |
| 1208 | reference: > |
Bram Moolenaar | 0c0734d | 2019-11-26 21:44:46 +0100 | [diff] [blame] | 1209 | :!mv failed/Test_func.dump dumps/Test_func.dump |
Bram Moolenaar | da65058 | 2018-02-20 15:51:40 +0100 | [diff] [blame] | 1210 | |
| 1211 | |
| 1212 | Creating a screen dump ~ |
| 1213 | *terminal-screendump* |
Bram Moolenaar | da65058 | 2018-02-20 15:51:40 +0100 | [diff] [blame] | 1214 | To create the screen dump, run Vim (or any other program) in a terminal and |
Bram Moolenaar | 6dc819b | 2018-07-03 16:42:19 +0200 | [diff] [blame] | 1215 | make it show the desired state. Then use the |term_dumpwrite()| function to |
Bram Moolenaar | da65058 | 2018-02-20 15:51:40 +0100 | [diff] [blame] | 1216 | create a screen dump file. For example: > |
| 1217 | :call term_dumpwrite(77, "mysyntax.dump") |
| 1218 | |
| 1219 | Here "77" is the buffer number of the terminal. Use `:ls!` to see it. |
| 1220 | |
Bram Moolenaar | 6dc819b | 2018-07-03 16:42:19 +0200 | [diff] [blame] | 1221 | You can view the screen dump with |term_dumpload()|: > |
Bram Moolenaar | da65058 | 2018-02-20 15:51:40 +0100 | [diff] [blame] | 1222 | :call term_dumpload("mysyntax.dump") |
| 1223 | |
| 1224 | To verify that Vim still shows exactly the same screen, run Vim again with |
| 1225 | exactly the same way to show the desired state. Then create a screen dump |
| 1226 | again, using a different file name: > |
| 1227 | :call term_dumpwrite(88, "test.dump") |
| 1228 | |
Bram Moolenaar | 6dc819b | 2018-07-03 16:42:19 +0200 | [diff] [blame] | 1229 | To assert that the files are exactly the same use |assert_equalfile()|: > |
Bram Moolenaar | da65058 | 2018-02-20 15:51:40 +0100 | [diff] [blame] | 1230 | call assert_equalfile("mysyntax.dump", "test.dump") |
| 1231 | |
| 1232 | If there are differences then v:errors will contain the error message. |
| 1233 | |
| 1234 | |
| 1235 | Comparing screen dumps ~ |
| 1236 | *terminal-diffscreendump* |
Bram Moolenaar | 6dc819b | 2018-07-03 16:42:19 +0200 | [diff] [blame] | 1237 | |assert_equalfile()| does not make it easy to see what is different. |
| 1238 | To spot the problem use |term_dumpdiff()|: > |
Bram Moolenaar | da65058 | 2018-02-20 15:51:40 +0100 | [diff] [blame] | 1239 | call term_dumpdiff("mysyntax.dump", "test.dump") |
| 1240 | |
| 1241 | This will open a window consisting of three parts: |
| 1242 | 1. The contents of the first dump |
| 1243 | 2. The difference between the first and second dump |
| 1244 | 3. The contents of the second dump |
| 1245 | |
| 1246 | You can usually see what differs in the second part. Use the 'ruler' to |
Bram Moolenaar | 93a1df2 | 2018-09-10 11:51:50 +0200 | [diff] [blame] | 1247 | relate it to the position in the first or second dump. Letters indicate the |
| 1248 | kind of difference: |
| 1249 | X different character |
| 1250 | > cursor in first but not in second |
| 1251 | < cursor in second but not in first |
| 1252 | w character width differs (single vs double width) |
| 1253 | f foreground color differs |
| 1254 | b background color differs |
| 1255 | a attribute differs (bold, underline, reverse, etc.) |
| 1256 | ? character missing in both |
| 1257 | + character missing in first |
| 1258 | - character missing in second |
Bram Moolenaar | da65058 | 2018-02-20 15:51:40 +0100 | [diff] [blame] | 1259 | |
Bram Moolenaar | 98ef233 | 2018-03-18 14:44:37 +0100 | [diff] [blame] | 1260 | Alternatively, press "s" to swap the first and second dump. Do this several |
Bram Moolenaar | da65058 | 2018-02-20 15:51:40 +0100 | [diff] [blame] | 1261 | times so that you can spot the difference in the context of the text. |
| 1262 | |
| 1263 | ============================================================================== |
Christian Brabandt | 9598a63 | 2025-01-11 10:14:24 +0100 | [diff] [blame] | 1264 | 6. Debugging *terminal-debug* *terminal-debugger* *package-termdebug* |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 1265 | |
| 1266 | The Terminal debugging plugin can be used to debug a program with gdb and view |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 1267 | the source code in a Vim window. Since this is completely contained inside |
| 1268 | Vim this also works remotely over an ssh connection. |
| 1269 | |
Bram Moolenaar | b3307b5 | 2018-06-17 21:34:11 +0200 | [diff] [blame] | 1270 | When the |+terminal| feature is missing, the plugin will use the "prompt" |
| 1271 | buffer type, if possible. The running program will then use a newly opened |
| 1272 | terminal window. See |termdebug-prompt| below for details. |
| 1273 | |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 1274 | |
| 1275 | Starting ~ |
Bram Moolenaar | 7f2e9d7 | 2017-11-11 20:58:53 +0100 | [diff] [blame] | 1276 | *termdebug-starting* |
Bram Moolenaar | c572da5 | 2017-08-27 16:52:01 +0200 | [diff] [blame] | 1277 | Load the plugin with this command: > |
| 1278 | packadd termdebug |
h-east | 52e7cc2 | 2024-07-28 17:03:29 +0200 | [diff] [blame] | 1279 | When loading the plugin from the |.vimrc| file, add the "!" attribute: > |
Christian Brabandt | 27c5598 | 2024-07-14 10:41:08 +0200 | [diff] [blame] | 1280 | packadd! termdebug |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 1281 | < *:Termdebug* |
Bram Moolenaar | d473c8c | 2018-08-11 18:00:22 +0200 | [diff] [blame] | 1282 | To start debugging use `:Termdebug` or `:TermdebugCommand` followed by the |
Bram Moolenaar | 32c67ba | 2018-04-16 16:21:49 +0200 | [diff] [blame] | 1283 | command name, for example: > |
Bram Moolenaar | 24a98a0 | 2017-09-27 22:23:55 +0200 | [diff] [blame] | 1284 | :Termdebug vim |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 1285 | |
Bram Moolenaar | c572da5 | 2017-08-27 16:52:01 +0200 | [diff] [blame] | 1286 | This opens two windows: |
Bram Moolenaar | f0b03c4 | 2017-12-17 17:17:07 +0100 | [diff] [blame] | 1287 | |
Bram Moolenaar | 45d5f26 | 2017-09-10 19:14:31 +0200 | [diff] [blame] | 1288 | gdb window A terminal window in which "gdb vim" is executed. Here you |
| 1289 | can directly interact with gdb. The buffer name is "!gdb". |
Bram Moolenaar | f0b03c4 | 2017-12-17 17:17:07 +0100 | [diff] [blame] | 1290 | |
Bram Moolenaar | 45d5f26 | 2017-09-10 19:14:31 +0200 | [diff] [blame] | 1291 | program window A terminal window for the executed program. When "run" is |
| 1292 | used in gdb the program I/O will happen in this window, so |
| 1293 | that it does not interfere with controlling gdb. The buffer |
Bram Moolenaar | 6f4754b | 2022-01-23 12:07:04 +0000 | [diff] [blame] | 1294 | name is "debugged program". |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 1295 | |
| 1296 | The current window is used to show the source code. When gdb pauses the |
| 1297 | source file location will be displayed, if possible. A sign is used to |
Bram Moolenaar | 664f3cf | 2019-12-07 16:03:51 +0100 | [diff] [blame] | 1298 | highlight the current position, using highlight group debugPC. |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 1299 | |
| 1300 | If the buffer in the current window is modified, another window will be opened |
Bram Moolenaar | 32c67ba | 2018-04-16 16:21:49 +0200 | [diff] [blame] | 1301 | to display the current gdb position. You can use `:Winbar` to add a window |
| 1302 | toolbar there. |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 1303 | |
| 1304 | Focus the terminal of the executed program to interact with it. This works |
| 1305 | the same as any command running in a terminal window. |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 1306 | |
Bram Moolenaar | 45d5f26 | 2017-09-10 19:14:31 +0200 | [diff] [blame] | 1307 | When the debugger ends, typically by typing "quit" in the gdb window, the two |
| 1308 | opened windows are closed. |
Bram Moolenaar | c572da5 | 2017-08-27 16:52:01 +0200 | [diff] [blame] | 1309 | |
Bram Moolenaar | b3623a3 | 2018-04-14 18:59:50 +0200 | [diff] [blame] | 1310 | Only one debugger can be active at a time. |
Ubaldo Tiberi | f7f8f0b | 2024-06-20 22:17:34 +0200 | [diff] [blame] | 1311 | |
| 1312 | *termdebug-timeout* |
| 1313 | Depending on how gdb is launched, termdebug startup time may vary. |
| 1314 | To avoid termdebug to get stuck if the startup process of gdb takes too long, |
| 1315 | a configurable timeout is included. Such time out is configurable in terms of |
| 1316 | multiple of 10ms: > |
| 1317 | let g:termdebug_config['timeout'] = 500 # 500 * 10ms = 5 seconds. |
| 1318 | |
| 1319 | The default timeout is 3000 ms. |
Bram Moolenaar | 32c67ba | 2018-04-16 16:21:49 +0200 | [diff] [blame] | 1320 | *:TermdebugCommand* |
| 1321 | If you want to give specific commands to the command being debugged, you can |
| 1322 | use the `:TermdebugCommand` command followed by the command name and |
| 1323 | additional parameters. > |
| 1324 | :TermdebugCommand vim --clean -c ':set nu' |
Bram Moolenaar | b3623a3 | 2018-04-14 18:59:50 +0200 | [diff] [blame] | 1325 | |
Bram Moolenaar | 32c67ba | 2018-04-16 16:21:49 +0200 | [diff] [blame] | 1326 | Both the `:Termdebug` and `:TermdebugCommand` support an optional "!" bang |
| 1327 | argument to start the command right away, without pausing at the gdb window |
| 1328 | (and cursor will be in the debugged window). For example: > |
| 1329 | :TermdebugCommand! vim --clean |
| 1330 | |
| 1331 | To attach gdb to an already running executable or use a core file, pass extra |
Bram Moolenaar | b3623a3 | 2018-04-14 18:59:50 +0200 | [diff] [blame] | 1332 | arguments. E.g.: > |
| 1333 | :Termdebug vim core |
| 1334 | :Termdebug vim 98343 |
| 1335 | |
Bram Moolenaar | 32c67ba | 2018-04-16 16:21:49 +0200 | [diff] [blame] | 1336 | If no argument is given, you'll end up in a gdb window, in which you need to |
| 1337 | specify which command to run using e.g. the gdb `file` command. |
| 1338 | |
Bram Moolenaar | c572da5 | 2017-08-27 16:52:01 +0200 | [diff] [blame] | 1339 | |
Bram Moolenaar | 24a98a0 | 2017-09-27 22:23:55 +0200 | [diff] [blame] | 1340 | Example session ~ |
Bram Moolenaar | 7f2e9d7 | 2017-11-11 20:58:53 +0100 | [diff] [blame] | 1341 | *termdebug-example* |
Bram Moolenaar | 24a98a0 | 2017-09-27 22:23:55 +0200 | [diff] [blame] | 1342 | Start in the Vim "src" directory and build Vim: > |
| 1343 | % make |
Bram Moolenaar | 1ff14ba | 2019-11-02 14:09:23 +0100 | [diff] [blame] | 1344 | Make sure that debug symbols are present, usually that means that $CFLAGS |
| 1345 | includes "-g". |
| 1346 | |
Bram Moolenaar | 24a98a0 | 2017-09-27 22:23:55 +0200 | [diff] [blame] | 1347 | Start Vim: > |
| 1348 | % ./vim |
Bram Moolenaar | 1ff14ba | 2019-11-02 14:09:23 +0100 | [diff] [blame] | 1349 | |
Bram Moolenaar | 24a98a0 | 2017-09-27 22:23:55 +0200 | [diff] [blame] | 1350 | Load the termdebug plugin and start debugging Vim: > |
| 1351 | :packadd termdebug |
| 1352 | :Termdebug vim |
| 1353 | You should now have three windows: |
| 1354 | source - where you started, has a window toolbar with buttons |
| 1355 | gdb - you can type gdb commands here |
| 1356 | program - the executed program will use this window |
Bram Moolenaar | 71137fe | 2018-03-03 20:47:21 +0100 | [diff] [blame] | 1357 | |
Bram Moolenaar | 24a98a0 | 2017-09-27 22:23:55 +0200 | [diff] [blame] | 1358 | You can use CTRL-W CTRL-W or the mouse to move focus between windows. |
| 1359 | Put focus on the gdb window and type: > |
| 1360 | break ex_help |
| 1361 | run |
| 1362 | Vim will start running in the program window. Put focus there and type: > |
| 1363 | :help gui |
Bram Moolenaar | 664f3cf | 2019-12-07 16:03:51 +0100 | [diff] [blame] | 1364 | Gdb will run into the ex_help breakpoint. The source window now shows the |
Bram Moolenaar | de1a831 | 2018-06-19 16:59:54 +0200 | [diff] [blame] | 1365 | ex_cmds.c file. A red "1 " marker will appear in the signcolumn where the |
| 1366 | breakpoint was set. The line where the debugger stopped is highlighted. You |
| 1367 | can now step through the program. Let's use the mouse: click on the "Next" |
| 1368 | button in the window toolbar. You will see the highlighting move as the |
| 1369 | debugger executes a line of source code. |
Bram Moolenaar | 24a98a0 | 2017-09-27 22:23:55 +0200 | [diff] [blame] | 1370 | |
| 1371 | Click "Next" a few times until the for loop is highlighted. Put the cursor on |
| 1372 | the end of "eap->arg", then click "Eval" in the toolbar. You will see this |
| 1373 | displayed: |
| 1374 | "eap->arg": 0x555555e68855 "gui" ~ |
| 1375 | This way you can inspect the value of local variables. You can also focus the |
| 1376 | gdb window and use a "print" command, e.g.: > |
| 1377 | print *eap |
Bram Moolenaar | 71137fe | 2018-03-03 20:47:21 +0100 | [diff] [blame] | 1378 | If mouse pointer movements are working, Vim will also show a balloon when the |
| 1379 | mouse rests on text that can be evaluated by gdb. |
Bram Moolenaar | 24a98a0 | 2017-09-27 22:23:55 +0200 | [diff] [blame] | 1380 | |
| 1381 | Now go back to the source window and put the cursor on the first line after |
| 1382 | the for loop, then type: > |
| 1383 | :Break |
| 1384 | You will see a ">>" marker appear, this indicates the new breakpoint. Now |
| 1385 | click "Cont" in the toolbar and the code until the breakpoint will be |
| 1386 | executed. |
| 1387 | |
| 1388 | You can type more advanced commands in the gdb window. For example, type: > |
| 1389 | watch curbuf |
| 1390 | Now click "Cont" in the toolbar (or type "cont" in the gdb window). Execution |
| 1391 | will now continue until the value of "curbuf" changes, which is in do_ecmd(). |
| 1392 | To remove this watchpoint again type in the gdb window: > |
| 1393 | delete 3 |
| 1394 | |
| 1395 | You can see the stack by typing in the gdb window: > |
| 1396 | where |
| 1397 | Move through the stack frames, e.g. with: > |
| 1398 | frame 3 |
| 1399 | The source window will show the code, at the point where the call was made to |
| 1400 | a deeper level. |
| 1401 | |
| 1402 | |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 1403 | Stepping through code ~ |
Bram Moolenaar | 7f2e9d7 | 2017-11-11 20:58:53 +0100 | [diff] [blame] | 1404 | *termdebug-stepping* |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 1405 | Put focus on the gdb window to type commands there. Some common ones are: |
Bram Moolenaar | 60e73f2 | 2017-11-12 18:02:06 +0100 | [diff] [blame] | 1406 | - CTRL-C interrupt the program |
| 1407 | - next execute the current line and stop at the next line |
| 1408 | - step execute the current line and stop at the next statement, |
| 1409 | entering functions |
Bram Moolenaar | 75ab590 | 2022-04-18 15:36:40 +0100 | [diff] [blame] | 1410 | - until execute until past the current cursor line or past a specified |
| 1411 | position or the current stack frame returns |
Bram Moolenaar | 60e73f2 | 2017-11-12 18:02:06 +0100 | [diff] [blame] | 1412 | - finish execute until leaving the current function |
| 1413 | - where show the stack |
| 1414 | - frame N go to the Nth stack frame |
| 1415 | - continue continue execution |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 1416 | |
Bram Moolenaar | 32c67ba | 2018-04-16 16:21:49 +0200 | [diff] [blame] | 1417 | *:Run* *:Arguments* |
| 1418 | In the window showing the source code these commands can be used to control |
| 1419 | gdb: |
Christian Brabandt | c52a856 | 2024-06-17 05:29:37 +0200 | [diff] [blame] | 1420 | `:Run` [args] run the program with [args] or the previous arguments |
| 1421 | `:Arguments` {args} set arguments for the next `:Run` |
Bram Moolenaar | 60e73f2 | 2017-11-12 18:02:06 +0100 | [diff] [blame] | 1422 | |
Bram Moolenaar | 589edb3 | 2019-09-20 14:38:13 +0200 | [diff] [blame] | 1423 | *:Break* set a breakpoint at the cursor position |
| 1424 | :Break {position} |
Bram Moolenaar | 2e693a8 | 2019-10-16 22:35:02 +0200 | [diff] [blame] | 1425 | set a breakpoint at the specified position |
iam28th | 323dda1 | 2023-12-14 20:30:26 +0100 | [diff] [blame] | 1426 | *:Tbreak* set a temporary breakpoint at the cursor position |
| 1427 | :Tbreak {position} |
| 1428 | set a temporary breakpoint at the specified position |
Bram Moolenaar | 589edb3 | 2019-09-20 14:38:13 +0200 | [diff] [blame] | 1429 | *:Clear* delete the breakpoint at the cursor position |
Bram Moolenaar | 60e73f2 | 2017-11-12 18:02:06 +0100 | [diff] [blame] | 1430 | |
Bram Moolenaar | 32c67ba | 2018-04-16 16:21:49 +0200 | [diff] [blame] | 1431 | *:Step* execute the gdb "step" command |
| 1432 | *:Over* execute the gdb "next" command (`:Next` is a Vim command) |
Bram Moolenaar | 75ab590 | 2022-04-18 15:36:40 +0100 | [diff] [blame] | 1433 | *:Until* execute the gdb "until" command |
Bram Moolenaar | 32c67ba | 2018-04-16 16:21:49 +0200 | [diff] [blame] | 1434 | *:Finish* execute the gdb "finish" command |
| 1435 | *:Continue* execute the gdb "continue" command |
| 1436 | *:Stop* interrupt the program |
Bram Moolenaar | 45d5f26 | 2017-09-10 19:14:31 +0200 | [diff] [blame] | 1437 | |
Bram Moolenaar | f0b03c4 | 2017-12-17 17:17:07 +0100 | [diff] [blame] | 1438 | If 'mouse' is set the plugin adds a window toolbar with these entries: |
Bram Moolenaar | 71137fe | 2018-03-03 20:47:21 +0100 | [diff] [blame] | 1439 | Step `:Step` |
| 1440 | Next `:Over` |
| 1441 | Finish `:Finish` |
| 1442 | Cont `:Continue` |
| 1443 | Stop `:Stop` |
| 1444 | Eval `:Evaluate` |
Bram Moolenaar | f0b03c4 | 2017-12-17 17:17:07 +0100 | [diff] [blame] | 1445 | This way you can use the mouse to perform the most common commands. You need |
| 1446 | to have the 'mouse' option set to enable mouse clicks. |
Bram Moolenaar | d13166e | 2022-11-18 21:49:57 +0000 | [diff] [blame] | 1447 | See |termdebug_winbar| for configuring this toolbar. |
Bram Moolenaar | 32c67ba | 2018-04-16 16:21:49 +0200 | [diff] [blame] | 1448 | *:Winbar* |
Bram Moolenaar | 71137fe | 2018-03-03 20:47:21 +0100 | [diff] [blame] | 1449 | You can add the window toolbar in other windows you open with: > |
| 1450 | :Winbar |
| 1451 | |
Bram Moolenaar | c4b533e | 2018-04-06 22:26:25 +0200 | [diff] [blame] | 1452 | If gdb stops at a source line and there is no window currently showing the |
| 1453 | source code, a new window will be created for the source code. This also |
| 1454 | happens if the buffer in the source code window has been modified and can't be |
| 1455 | abandoned. |
| 1456 | |
Bram Moolenaar | de1a831 | 2018-06-19 16:59:54 +0200 | [diff] [blame] | 1457 | Gdb gives each breakpoint a number. In Vim the number shows up in the sign |
| 1458 | column, with a red background. You can use these gdb commands: |
| 1459 | - info break list breakpoints |
| 1460 | - delete N delete breakpoint N |
| 1461 | You can also use the `:Clear` command if the cursor is in the line with the |
| 1462 | breakpoint, or use the "Clear breakpoint" right-click menu entry. |
| 1463 | |
Bram Moolenaar | 45d5f26 | 2017-09-10 19:14:31 +0200 | [diff] [blame] | 1464 | |
| 1465 | Inspecting variables ~ |
Bram Moolenaar | 32c67ba | 2018-04-16 16:21:49 +0200 | [diff] [blame] | 1466 | *termdebug-variables* *:Evaluate* |
Christian Brabandt | c52a856 | 2024-06-17 05:29:37 +0200 | [diff] [blame] | 1467 | `:Evaluate` evaluate the expression under the cursor |
| 1468 | `K` same (see |termdebug_map_K| to disable) |
| 1469 | `:Evaluate` {expr} evaluate {expr} |
| 1470 | `:'<,'>Evaluate` evaluate the Visually selected text |
Bram Moolenaar | 45d5f26 | 2017-09-10 19:14:31 +0200 | [diff] [blame] | 1471 | |
| 1472 | This is similar to using "print" in the gdb window. |
Bram Moolenaar | 71137fe | 2018-03-03 20:47:21 +0100 | [diff] [blame] | 1473 | You can usually shorten `:Evaluate` to `:Ev`. |
Bram Moolenaar | 45d5f26 | 2017-09-10 19:14:31 +0200 | [diff] [blame] | 1474 | |
| 1475 | |
Sean Dewar | 3d3a915 | 2023-08-23 17:14:49 +0100 | [diff] [blame] | 1476 | Navigating stack frames ~ |
| 1477 | *termdebug-frames* *:Frame* *:Up* *:Down* |
Christian Brabandt | c52a856 | 2024-06-17 05:29:37 +0200 | [diff] [blame] | 1478 | `:Frame` [frame] select frame [frame], which is a frame number, |
Sean Dewar | 3d3a915 | 2023-08-23 17:14:49 +0100 | [diff] [blame] | 1479 | address, or function name (default: current frame) |
Christian Brabandt | c52a856 | 2024-06-17 05:29:37 +0200 | [diff] [blame] | 1480 | `:Up` [count] go up [count] frames (default: 1; the frame that |
Sean Dewar | 3d3a915 | 2023-08-23 17:14:49 +0100 | [diff] [blame] | 1481 | called the current) |
Christian Brabandt | c52a856 | 2024-06-17 05:29:37 +0200 | [diff] [blame] | 1482 | `+` same (see |termdebug_map_plus| to disable) |
| 1483 | `:Down` [count] go down [count] frames (default: 1; the frame called |
Sean Dewar | 3d3a915 | 2023-08-23 17:14:49 +0100 | [diff] [blame] | 1484 | by the current) |
Christian Brabandt | c52a856 | 2024-06-17 05:29:37 +0200 | [diff] [blame] | 1485 | `-` same (see |termdebug_map_minus| to disable) |
Simon Sobisch | 2ae7ffe | 2023-08-22 22:19:14 +0200 | [diff] [blame] | 1486 | |
| 1487 | |
Bram Moolenaar | 45d5f26 | 2017-09-10 19:14:31 +0200 | [diff] [blame] | 1488 | Other commands ~ |
Bram Moolenaar | 7f2e9d7 | 2017-11-11 20:58:53 +0100 | [diff] [blame] | 1489 | *termdebug-commands* |
Bram Moolenaar | 32c67ba | 2018-04-16 16:21:49 +0200 | [diff] [blame] | 1490 | *:Gdb* jump to the gdb window |
| 1491 | *:Program* jump to the window with the running program |
| 1492 | *:Source* jump to the window with the source code, create it if there |
Bram Moolenaar | c4b533e | 2018-04-06 22:26:25 +0200 | [diff] [blame] | 1493 | isn't one |
Bram Moolenaar | 82be484 | 2021-01-11 19:40:15 +0100 | [diff] [blame] | 1494 | *:Asm* jump to the window with the disassembly, create it if there |
| 1495 | isn't one |
laburnumT | 9f29621 | 2023-05-13 16:29:15 +0200 | [diff] [blame] | 1496 | *:Var* jump to the window with the local and argument variables, |
zeertzjq | d086b8f | 2024-02-25 15:42:52 +0800 | [diff] [blame] | 1497 | create it if there isn't one. This window updates whenever the |
| 1498 | program is stopped |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 1499 | |
Bram Moolenaar | 6aa5729 | 2021-08-14 21:25:52 +0200 | [diff] [blame] | 1500 | Events ~ |
| 1501 | *termdebug-events* |
| 1502 | Four autocommands can be used: > |
| 1503 | au User TermdebugStartPre echomsg 'debugging starting' |
| 1504 | au User TermdebugStartPost echomsg 'debugging started' |
| 1505 | au User TermdebugStopPre echomsg 'debugging stopping' |
| 1506 | au User TermdebugStopPost echomsg 'debugging stopped' |
| 1507 | < |
| 1508 | *TermdebugStartPre* |
| 1509 | TermdebugStartPre Before starting debugging. |
| 1510 | Not triggered if the debugger is already |
Bram Moolenaar | c9a431c | 2022-05-23 21:49:41 +0100 | [diff] [blame] | 1511 | running or the debugger command cannot be |
Bram Moolenaar | 6aa5729 | 2021-08-14 21:25:52 +0200 | [diff] [blame] | 1512 | executed. |
| 1513 | *TermdebugStartPost* |
| 1514 | TermdebugStartPost After debugging has initialized. |
| 1515 | If a "!" bang is passed to `:Termdebug` or |
| 1516 | `:TermdebugCommand` the event is triggered |
| 1517 | before running the provided command in gdb. |
| 1518 | *TermdebugStopPre* |
| 1519 | TermdebugStopPre Before debugging ends, when gdb is terminated, |
| 1520 | most likely after issuing a "quit" command in |
| 1521 | the gdb window. |
| 1522 | *TermdebugStopPost* |
| 1523 | TermdebugStopPost After debugging has ended, gdb-related windows |
| 1524 | are closed, debug buffers wiped out and |
| 1525 | the state before the debugging was restored. |
| 1526 | |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 1527 | |
Bram Moolenaar | d13166e | 2022-11-18 21:49:57 +0000 | [diff] [blame] | 1528 | Customizing ~ |
| 1529 | *termdebug-customizing* *g:termdebug_config* |
| 1530 | In the past several global variables were used for configuration. These are |
| 1531 | deprecated and using the g:termdebug_config dictionary is preferred. When |
| 1532 | g:termdebug_config exists the other global variables will NOT be used. |
| 1533 | The recommended way is to start with an empty dictionary: > |
| 1534 | let g:termdebug_config = {} |
| 1535 | |
| 1536 | Then you can add entries to the dictionary as mentioned below. The |
| 1537 | deprecated global variable names are mentioned for completeness. If you are |
| 1538 | switching over to using g:termdebug_config you can find the old variable name |
| 1539 | and take over the value, then delete the deprecated variable. |
| 1540 | |
| 1541 | |
Bram Moolenaar | b3307b5 | 2018-06-17 21:34:11 +0200 | [diff] [blame] | 1542 | Prompt mode ~ |
| 1543 | *termdebug-prompt* |
| 1544 | When the |+terminal| feature is not supported and on MS-Windows, gdb will run |
| 1545 | in a buffer with 'buftype' set to "prompt". This works slightly differently: |
| 1546 | - The gdb window will be in Insert mode while typing commands. Go to Normal |
| 1547 | mode with <Esc>, then you can move around in the buffer, copy/paste, etc. |
| 1548 | Go back to editing the gdb command with any command that starts Insert mode, |
| 1549 | such as `a` or `i`. |
| 1550 | - The program being debugged will run in a separate window. On MS-Windows |
| 1551 | this is a new console window. On Unix, if the |+terminal| feature is |
| 1552 | available a Terminal window will be opened to run the debugged program in. |
| 1553 | |
| 1554 | *termdebug_use_prompt* |
| 1555 | Prompt mode can be used even when the |+terminal| feature is present with: > |
Ubaldo Tiberi | a90b0b4 | 2024-07-20 12:00:44 +0200 | [diff] [blame] | 1556 | let g:termdebug_config['use_prompt'] = v:true |
Bram Moolenaar | d13166e | 2022-11-18 21:49:57 +0000 | [diff] [blame] | 1557 | If there is no g:termdebug_config you can use: > |
Ubaldo Tiberi | a90b0b4 | 2024-07-20 12:00:44 +0200 | [diff] [blame] | 1558 | let g:termdebug_use_prompt = v:true |
Ubaldo Tiberi | e54fd3f | 2024-07-04 17:14:03 +0200 | [diff] [blame] | 1559 | |
Bram Moolenaar | 388a5d4 | 2020-05-26 21:20:45 +0200 | [diff] [blame] | 1560 | < |
Ubaldo Tiberi | e54fd3f | 2024-07-04 17:14:03 +0200 | [diff] [blame] | 1561 | However, the latter form will be deprecated in future releases. |
| 1562 | |
Peter Wolf | 8f1d098 | 2024-10-27 21:51:14 +0100 | [diff] [blame] | 1563 | |
shane.xb.qian | 7fbbd7f | 2023-11-08 21:44:48 +0100 | [diff] [blame] | 1564 | Mappings ~ |
Ubaldo Tiberi | a48637c | 2024-06-18 20:18:20 +0200 | [diff] [blame] | 1565 | The termdebug plugin enables a few default mappings. All those mappings |
| 1566 | are reset to their original values once the termdebug session concludes. |
| 1567 | |
shane.xb.qian | 7fbbd7f | 2023-11-08 21:44:48 +0100 | [diff] [blame] | 1568 | *termdebug_map_K* *termdebug-mappings* |
zeertzjq | 20a94f4 | 2023-11-09 15:21:58 +0800 | [diff] [blame] | 1569 | The K key is normally mapped to |:Evaluate| unless a buffer local (|:map-local|) |
| 1570 | mapping to K already exists. If you do not want this use: > |
Ubaldo Tiberi | a90b0b4 | 2024-07-20 12:00:44 +0200 | [diff] [blame] | 1571 | let g:termdebug_config['map_K'] = v:false |
Bram Moolenaar | d13166e | 2022-11-18 21:49:57 +0000 | [diff] [blame] | 1572 | If there is no g:termdebug_config you can use: > |
Ubaldo Tiberi | a90b0b4 | 2024-07-20 12:00:44 +0200 | [diff] [blame] | 1573 | let g:termdebug_map_K = v:false |
Bram Moolenaar | 82be484 | 2021-01-11 19:40:15 +0100 | [diff] [blame] | 1574 | < |
Ubaldo Tiberi | e54fd3f | 2024-07-04 17:14:03 +0200 | [diff] [blame] | 1575 | However, the latter form will be deprecated in future releases. |
| 1576 | |
Simon Sobisch | 2ae7ffe | 2023-08-22 22:19:14 +0200 | [diff] [blame] | 1577 | *termdebug_map_minus* |
zeertzjq | 20a94f4 | 2023-11-09 15:21:58 +0800 | [diff] [blame] | 1578 | The - key is normally mapped to |:Down| unless a buffer local mapping to the - |
| 1579 | key already exists. If you do not want this use: > |
Ubaldo Tiberi | a90b0b4 | 2024-07-20 12:00:44 +0200 | [diff] [blame] | 1580 | let g:termdebug_config['map_minus'] = v:false |
Simon Sobisch | 2ae7ffe | 2023-08-22 22:19:14 +0200 | [diff] [blame] | 1581 | < |
| 1582 | *termdebug_map_plus* |
zeertzjq | 20a94f4 | 2023-11-09 15:21:58 +0800 | [diff] [blame] | 1583 | The + key is normally mapped to |:Up| unless a buffer local mapping to the + |
| 1584 | key already exists. If you do not want this use: > |
Ubaldo Tiberi | a90b0b4 | 2024-07-20 12:00:44 +0200 | [diff] [blame] | 1585 | let g:termdebug_config['map_plus'] = v:false |
Simon Sobisch | 2ae7ffe | 2023-08-22 22:19:14 +0200 | [diff] [blame] | 1586 | < |
Bram Moolenaar | 82be484 | 2021-01-11 19:40:15 +0100 | [diff] [blame] | 1587 | *termdebug_disasm_window* |
Bram Moolenaar | 10e8ff9 | 2023-06-10 21:40:39 +0100 | [diff] [blame] | 1588 | If you want the Asm window shown by default, set the "disasm_window" flag to |
| 1589 | 1. The "disasm_window_height" entry can be used to set the window height: > |
Ubaldo Tiberi | a90b0b4 | 2024-07-20 12:00:44 +0200 | [diff] [blame] | 1590 | let g:termdebug_config['disasm_window'] = v:true |
Bram Moolenaar | c9a431c | 2022-05-23 21:49:41 +0100 | [diff] [blame] | 1591 | let g:termdebug_config['disasm_window_height'] = 15 |
Bram Moolenaar | d13166e | 2022-11-18 21:49:57 +0000 | [diff] [blame] | 1592 | If there is no g:termdebug_config you can use: > |
Bram Moolenaar | 82be484 | 2021-01-11 19:40:15 +0100 | [diff] [blame] | 1593 | let g:termdebug_disasm_window = 15 |
Ubaldo Tiberi | e54fd3f | 2024-07-04 17:14:03 +0200 | [diff] [blame] | 1594 | |
| 1595 | However, the latter form will be deprecated in future releases. |
| 1596 | |
zeertzjq | 20a94f4 | 2023-11-09 15:21:58 +0800 | [diff] [blame] | 1597 | Any value greater than 1 will set the Asm window height to that value. |
shane.xb.qian | ca48202 | 2023-11-08 21:59:15 +0100 | [diff] [blame] | 1598 | If the current window has enough horizontal space, it will be vertically split |
| 1599 | and the Asm window will be shown side by side with the source code window (and |
| 1600 | the height option won't be used). |
Bram Moolenaar | b3307b5 | 2018-06-17 21:34:11 +0200 | [diff] [blame] | 1601 | |
laburnumT | 9f29621 | 2023-05-13 16:29:15 +0200 | [diff] [blame] | 1602 | *termdebug_variables_window* |
h_east | 5985879 | 2023-10-25 22:47:05 +0900 | [diff] [blame] | 1603 | If you want the Var window shown by default, set the "variables_window" flag |
| 1604 | to 1. The "variables_window_height" entry can be used to set the window |
| 1605 | height: > |
Ubaldo Tiberi | a90b0b4 | 2024-07-20 12:00:44 +0200 | [diff] [blame] | 1606 | let g:termdebug_config['variables_window'] = v:true |
laburnumT | 9f29621 | 2023-05-13 16:29:15 +0200 | [diff] [blame] | 1607 | let g:termdebug_config['variables_window_height'] = 15 |
| 1608 | If there is no g:termdebug_config you can use: > |
| 1609 | let g:termdebug_variables_window = 15 |
Ubaldo Tiberi | e54fd3f | 2024-07-04 17:14:03 +0200 | [diff] [blame] | 1610 | |
| 1611 | However, the latter form will be deprecated in future releases. |
| 1612 | |
laburnumT | 9f29621 | 2023-05-13 16:29:15 +0200 | [diff] [blame] | 1613 | Any value greater than 1 will set the Var window height to that value. |
shane.xb.qian | ca48202 | 2023-11-08 21:59:15 +0100 | [diff] [blame] | 1614 | If the current window has enough horizontal space, it will be vertically split |
| 1615 | and the Var window will be shown side by side with the source code window (and |
| 1616 | the height options won't be used). |
laburnumT | 9f29621 | 2023-05-13 16:29:15 +0200 | [diff] [blame] | 1617 | |
Peter Wolf | 8f1d098 | 2024-10-27 21:51:14 +0100 | [diff] [blame] | 1618 | |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 1619 | Communication ~ |
Bram Moolenaar | 7f2e9d7 | 2017-11-11 20:58:53 +0100 | [diff] [blame] | 1620 | *termdebug-communication* |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 1621 | There is another, hidden, buffer, which is used for Vim to communicate with |
| 1622 | gdb. The buffer name is "gdb communication". Do not delete this buffer, it |
| 1623 | will break the debugger. |
| 1624 | |
Bram Moolenaar | de1a831 | 2018-06-19 16:59:54 +0200 | [diff] [blame] | 1625 | Gdb has some weird behavior, the plugin does its best to work around that. |
| 1626 | For example, after typing "continue" in the gdb window a CTRL-C can be used to |
| 1627 | interrupt the running program. But after using the MI command |
| 1628 | "-exec-continue" pressing CTRL-C does not interrupt. Therefore you will see |
| 1629 | "continue" being used for the `:Continue` command, instead of using the |
| 1630 | communication channel. |
| 1631 | |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 1632 | |
Bram Moolenaar | c9a431c | 2022-05-23 21:49:41 +0100 | [diff] [blame] | 1633 | GDB command ~ |
Bram Moolenaar | 6aa5729 | 2021-08-14 21:25:52 +0200 | [diff] [blame] | 1634 | *g:termdebugger* |
Bram Moolenaar | c9a431c | 2022-05-23 21:49:41 +0100 | [diff] [blame] | 1635 | To change the name of the gdb command, set "debugger" entry in |
| 1636 | g:termdebug_config or the "g:termdebugger" variable before invoking |
| 1637 | `:Termdebug`: > |
| 1638 | let g:termdebug_config['command'] = "mygdb" |
Bram Moolenaar | d13166e | 2022-11-18 21:49:57 +0000 | [diff] [blame] | 1639 | If there is no g:termdebug_config you can use: > |
Bram Moolenaar | 6aa5729 | 2021-08-14 21:25:52 +0200 | [diff] [blame] | 1640 | let g:termdebugger = "mygdb" |
Bram Moolenaar | c9a431c | 2022-05-23 21:49:41 +0100 | [diff] [blame] | 1641 | |
Ubaldo Tiberi | e54fd3f | 2024-07-04 17:14:03 +0200 | [diff] [blame] | 1642 | However, the latter form will be deprecated in future releases. |
| 1643 | |
Bram Moolenaar | fa3b723 | 2021-12-24 13:18:38 +0000 | [diff] [blame] | 1644 | If the command needs an argument use a List: > |
Bram Moolenaar | c9a431c | 2022-05-23 21:49:41 +0100 | [diff] [blame] | 1645 | let g:termdebug_config['command'] = ['rr', 'replay', '--'] |
Bram Moolenaar | d13166e | 2022-11-18 21:49:57 +0000 | [diff] [blame] | 1646 | If there is no g:termdebug_config you can use: > |
Bram Moolenaar | fa3b723 | 2021-12-24 13:18:38 +0000 | [diff] [blame] | 1647 | let g:termdebugger = ['rr', 'replay', '--'] |
Bram Moolenaar | c9a431c | 2022-05-23 21:49:41 +0100 | [diff] [blame] | 1648 | |
| 1649 | Several arguments will be added to make gdb work well for the debugger. |
| 1650 | If you want to modify them, add a function to filter the argument list: > |
| 1651 | let g:termdebug_config['command_filter'] = MyDebugFilter |
| 1652 | |
| 1653 | If you do not want the arguments to be added, but you do need to set the |
| 1654 | "pty", use a function to add the necessary arguments: > |
| 1655 | let g:termdebug_config['command_add_args'] = MyAddArguments |
| 1656 | The function will be called with the list of arguments so far, and a second |
| 1657 | argument that is the name of the pty. |
| 1658 | *gdb-version* |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 1659 | Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI |
Dominique Pellé | 960822a | 2023-09-24 23:07:39 +0200 | [diff] [blame] | 1660 | interface. The "new-ui" command requires gdb version 7.12 or later. If you |
Bram Moolenaar | 98ef233 | 2018-03-18 14:44:37 +0100 | [diff] [blame] | 1661 | get this error: |
Bram Moolenaar | 01164a6 | 2017-11-02 22:58:42 +0100 | [diff] [blame] | 1662 | Undefined command: "new-ui". Try "help".~ |
| 1663 | Then your gdb is too old. |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 1664 | |
Bram Moolenaar | 71137fe | 2018-03-03 20:47:21 +0100 | [diff] [blame] | 1665 | |
Bram Moolenaar | 8a3b805 | 2022-06-26 12:21:15 +0100 | [diff] [blame] | 1666 | Colors ~ |
Bram Moolenaar | d13166e | 2022-11-18 21:49:57 +0000 | [diff] [blame] | 1667 | *hl-debugPC* *hl-debugBreakpoint* |
Bram Moolenaar | e09ba7b | 2017-09-09 22:19:47 +0200 | [diff] [blame] | 1668 | The color of the signs can be adjusted with these highlight groups: |
| 1669 | - debugPC the current position |
| 1670 | - debugBreakpoint a breakpoint |
| 1671 | |
| 1672 | The defaults are, when 'background' is "light": |
| 1673 | hi debugPC term=reverse ctermbg=lightblue guibg=lightblue |
| 1674 | hi debugBreakpoint term=reverse ctermbg=red guibg=red |
| 1675 | |
| 1676 | When 'background' is "dark": |
| 1677 | hi debugPC term=reverse ctermbg=darkblue guibg=darkblue |
| 1678 | hi debugBreakpoint term=reverse ctermbg=red guibg=red |
Bram Moolenaar | c572da5 | 2017-08-27 16:52:01 +0200 | [diff] [blame] | 1679 | |
Bram Moolenaar | 71137fe | 2018-03-03 20:47:21 +0100 | [diff] [blame] | 1680 | |
Bram Moolenaar | 8a3b805 | 2022-06-26 12:21:15 +0100 | [diff] [blame] | 1681 | Shortcuts ~ |
| 1682 | *termdebug_shortcuts* |
Bram Moolenaar | b3307b5 | 2018-06-17 21:34:11 +0200 | [diff] [blame] | 1683 | You can define your own shortcuts (mappings) to control gdb, that can work in |
| 1684 | any window, using the TermDebugSendCommand() function. Example: > |
| 1685 | map ,w :call TermDebugSendCommand('where')<CR> |
| 1686 | The argument is the gdb command. |
| 1687 | |
| 1688 | |
Bram Moolenaar | 8a3b805 | 2022-06-26 12:21:15 +0100 | [diff] [blame] | 1689 | Popup menu ~ |
| 1690 | *termdebug_popup* |
Bram Moolenaar | 71137fe | 2018-03-03 20:47:21 +0100 | [diff] [blame] | 1691 | By default the Termdebug plugin sets 'mousemodel' to "popup_setpos" and adds |
| 1692 | these entries to the popup menu: |
| 1693 | Set breakpoint `:Break` |
| 1694 | Clear breakpoint `:Clear` |
| 1695 | Evaluate `:Evaluate` |
| 1696 | If you don't want this then disable it with: > |
Bram Moolenaar | c9a431c | 2022-05-23 21:49:41 +0100 | [diff] [blame] | 1697 | let g:termdebug_config['popup'] = 0 |
Bram Moolenaar | d13166e | 2022-11-18 21:49:57 +0000 | [diff] [blame] | 1698 | If there is no g:termdebug_config you can use: > |
Bram Moolenaar | 71137fe | 2018-03-03 20:47:21 +0100 | [diff] [blame] | 1699 | let g:termdebug_popup = 0 |
| 1700 | |
Ubaldo Tiberi | e54fd3f | 2024-07-04 17:14:03 +0200 | [diff] [blame] | 1701 | However, the latter form will be deprecated in future releases. |
Bram Moolenaar | 71137fe | 2018-03-03 20:47:21 +0100 | [diff] [blame] | 1702 | |
Peter Wolf | 8f1d098 | 2024-10-27 21:51:14 +0100 | [diff] [blame] | 1703 | |
skywind3000 | e7d9ca2 | 2023-06-28 23:27:28 +0100 | [diff] [blame] | 1704 | Change default signs ~ |
| 1705 | *termdebug_signs* |
Shane-XB-Qian | 2dd613f | 2023-11-12 23:53:39 +0800 | [diff] [blame] | 1706 | Termdebug uses the hex number of the breakpoint ID in the signcolumn to |
Peter Wolf | 8f1d098 | 2024-10-27 21:51:14 +0100 | [diff] [blame] | 1707 | represent breakpoints. If it is greater than "0xFF", then it will be displayed |
Shane-XB-Qian | 2dd613f | 2023-11-12 23:53:39 +0800 | [diff] [blame] | 1708 | as "F+", due to we really only have two screen cells for the sign. |
Ella Moss | 5e7f43b | 2024-11-09 11:32:15 +0100 | [diff] [blame] | 1709 | You may also use decimal breakpoint signs instead, in which case IDs greater |
| 1710 | than 99 will be displayed as "9+". |
skywind3000 | e7d9ca2 | 2023-06-28 23:27:28 +0100 | [diff] [blame] | 1711 | |
Ella Moss | 5e7f43b | 2024-11-09 11:32:15 +0100 | [diff] [blame] | 1712 | If you want to customize the breakpoint signs to show `>>` in the signcolumn: > |
skywind3000 | e7d9ca2 | 2023-06-28 23:27:28 +0100 | [diff] [blame] | 1713 | let g:termdebug_config['sign'] = '>>' |
Dimitry Ishenko | c4bca1d | 2025-07-08 23:13:14 +0200 | [diff] [blame] | 1714 | You can also specify individual signs for the first several breakpoints: > |
| 1715 | let g:termdebug_config['signs'] = ['>1', '>2', '>3', '>4', '>5', '>6', '>7', '>8', '>9'] |
| 1716 | let g:termdebug_config['sign'] = '>>' |
Ella Moss | 5e7f43b | 2024-11-09 11:32:15 +0100 | [diff] [blame] | 1717 | If you would like to use decimal (base 10) breakpoint signs: > |
| 1718 | let g:termdebug_config['sign_decimal'] = 1 |
zeertzjq | 060107c | 2024-11-10 14:08:56 +0100 | [diff] [blame] | 1719 | If the variable g:termdebug_config does not yet exist, you can use: > |
skywind3000 | e7d9ca2 | 2023-06-28 23:27:28 +0100 | [diff] [blame] | 1720 | let g:termdebug_config = {'sign': '>>'} |
Ella Moss | 5e7f43b | 2024-11-09 11:32:15 +0100 | [diff] [blame] | 1721 | Likewise, to enable decimal signs: > |
| 1722 | let g:termdebug_config = {'sign_decimal': 1} |
skywind3000 | e7d9ca2 | 2023-06-28 23:27:28 +0100 | [diff] [blame] | 1723 | |
| 1724 | |
Bram Moolenaar | d13166e | 2022-11-18 21:49:57 +0000 | [diff] [blame] | 1725 | Window toolbar ~ |
| 1726 | *termdebug_winbar* |
| 1727 | By default the Termdebug plugin creates a window toolbar if the mouse is |
| 1728 | enabled (see |:Winbar|). If you don't want this then disable it with: > |
| 1729 | let g:termdebug_config['winbar'] = 0 |
| 1730 | |
| 1731 | |
Bram Moolenaar | 8a3b805 | 2022-06-26 12:21:15 +0100 | [diff] [blame] | 1732 | Vim window width ~ |
| 1733 | *termdebug_wide* |
Bram Moolenaar | 4466ad6 | 2020-11-21 13:16:30 +0100 | [diff] [blame] | 1734 | To change the width of the Vim window when debugging starts and use a vertical |
| 1735 | split: > |
Bram Moolenaar | c9a431c | 2022-05-23 21:49:41 +0100 | [diff] [blame] | 1736 | let g:termdebug_config['wide'] = 163 |
Bram Moolenaar | d13166e | 2022-11-18 21:49:57 +0000 | [diff] [blame] | 1737 | If there is no g:termdebug_config you can use: > |
Bram Moolenaar | 4466ad6 | 2020-11-21 13:16:30 +0100 | [diff] [blame] | 1738 | let g:termdebug_wide = 163 |
Bram Moolenaar | 38baa3e | 2017-09-14 16:10:38 +0200 | [diff] [blame] | 1739 | |
Ubaldo Tiberi | e54fd3f | 2024-07-04 17:14:03 +0200 | [diff] [blame] | 1740 | However, the latter form will be deprecated in future releases. |
| 1741 | |
Bram Moolenaar | 4466ad6 | 2020-11-21 13:16:30 +0100 | [diff] [blame] | 1742 | This will set 'columns' to 163 when `:Termdebug` is used. The value is |
| 1743 | restored when quitting the debugger. |
| 1744 | |
Bram Moolenaar | c9a431c | 2022-05-23 21:49:41 +0100 | [diff] [blame] | 1745 | If the wide value is set and 'columns' is already a greater value, then a |
Bram Moolenaar | 4466ad6 | 2020-11-21 13:16:30 +0100 | [diff] [blame] | 1746 | vertical split will be used without modifying 'columns'. |
| 1747 | |
Bram Moolenaar | c9a431c | 2022-05-23 21:49:41 +0100 | [diff] [blame] | 1748 | Set the wide value to 1 to use a vertical split without ever changing |
Bram Moolenaar | 4466ad6 | 2020-11-21 13:16:30 +0100 | [diff] [blame] | 1749 | 'columns'. This is useful when the terminal can't be resized by Vim. |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 1750 | |
Bram Moolenaar | e4f25e4 | 2017-07-07 11:54:15 +0200 | [diff] [blame] | 1751 | |
Peter Wolf | 8f1d098 | 2024-10-27 21:51:14 +0100 | [diff] [blame] | 1752 | Evaluate in Popup Window at Cursor ~ |
| 1753 | *termdebug_evaluate_in_popup* |
| 1754 | By default |:Evaluate| will simply echo its output. For larger entities this |
| 1755 | might become difficult to read or even truncated. |
| 1756 | Alternatively, the evaluation result may be output into a popup window at the |
| 1757 | current cursor position: > |
| 1758 | let g:termdebug_config['evaluate_in_popup'] = v:true |
| 1759 | This can also be used in a "one-shot" manner: > |
| 1760 | func OnCursorHold() |
| 1761 | let g:termdebug_config['evaluate_in_popup'] = v:true |
| 1762 | :Evaluate |
| 1763 | let g:termdebug_config['evaluate_in_popup'] = v:false |
| 1764 | endfunc |
| 1765 | < |
Ubaldo Tiberi | ae1c8b7 | 2024-11-19 22:32:30 +0100 | [diff] [blame] | 1766 | |
| 1767 | Contributing ~ |
| 1768 | *termdebug_contributing* |
| 1769 | Contributions for termdebug improvements are welcome. |
| 1770 | However, it is fairly common that during the development process you need some |
| 1771 | mechanisms like `echo` statements (or similar) to help you in your job. |
| 1772 | For this reason, you can set: > |
| 1773 | let g:termdebug_config['debug'] = true |
| 1774 | < |
h-east | b534e80 | 2024-12-03 20:37:52 +0100 | [diff] [blame] | 1775 | This sets the `DEBUG` variable to `true`, which can be referenced in the |
| 1776 | source code. An example of its usage follows: > |
Ubaldo Tiberi | ae1c8b7 | 2024-11-19 22:32:30 +0100 | [diff] [blame] | 1777 | if exists('g:termdebug_loaded') |
| 1778 | if DEBUG |
| 1779 | Echoerr('Termdebug already loaded.') |
| 1780 | endif |
| 1781 | finish |
| 1782 | endif |
| 1783 | < |
| 1784 | |
Bram Moolenaar | 91f84f6 | 2018-07-29 15:07:52 +0200 | [diff] [blame] | 1785 | vim:tw=78:ts=8:noet:ft=help:norl: |