vim: runtime/doc/terminal.txt annotate

annotate runtime/doc/terminal.txt @ 13535:e9ffb5b35266 v8.0.1641

patch 8.0.1641: job in terminal can't communicate with Vim commit https://github.com/vim/vim/commit/8fbaeb195d9298c3a2a80300b5f96f1adddd2f59 Author: Bram Moolenaar <Bram@vim.org> Date: Sun Mar 25 18:20:17 2018 +0200 patch 8.0.1641: job in terminal can't communicate with Vim Problem: Job in terminal can't communicate with Vim. Solution: Add the terminal API.

author	Christian Brabandt <cb@256bit.org>
date	Sun, 25 Mar 2018 18:30:07 +0200
parents	9eebe457eb3c
children	87a9c1be0ae3

rev	line source
13535 e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	1 terminal.txt For Vim version 8.0. Last change: 2018 Mar 25
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	2
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	3
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	4 VIM REFERENCE MANUAL by Bram Moolenaar
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	5
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	6
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	7 Terminal window support terminal
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	8
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	9
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	10 The terminal feature is optional, use this to check if your Vim has it: >
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	11 echo has('terminal')
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	12 If the result is "1" you have it.
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	13
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	14
13304 013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	15 1. Basic use \|terminal-use\|
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	16 Typing \|terminal-typing\|
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	17 Size and color \|terminal-size-color\|
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	18 Syntax \|:terminal\|
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	19 Resizing \|terminal-resizing\|
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	20 Terminal Modes \|Terminal-mode\|
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	21 Cursor style \|terminal-cursor-style\|
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	22 Special keys \|terminal-special-keys\|
13437 02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	23 Session \|terminal-session\|
13304 013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	24 Unix \|terminal-unix\|
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	25 MS-Windows \|terminal-ms-windows\|
13535 e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	26 2. Terminal communication \|terminal-communication\|
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	27 Vim to job: term_sendkeys() \|terminal-to-job\|
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	28 Job to Vim: JSON API \|terminal-api\|
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	29 Using the client-server feature \|terminal-client-server\|
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	30 3. Remote testing \|terminal-testing\|
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	31 4. Diffing screen dumps \|terminal-diff\|
13304 013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	32 Writing a screen dump test for Vim \|terminal-dumptest\|
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	33 Creating a screen dump \|terminal-screendump\|
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	34 Comparing screen dumps \|terminal-diffscreendump\|
13535 e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	35 5. Debugging \|terminal-debug\|
13304 013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	36 Starting \|termdebug-starting\|
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	37 Example session \|termdebug-example\|
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	38 Stepping through code \|termdebug-stepping\|
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	39 Inspecting variables \|termdebug-variables\|
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	40 Other commands \|termdebug-commands\|
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	41 Communication \|termdebug-communication\|
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	42 Customizing \|termdebug-customizing\|
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	43
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	44 {Vi does not have any of these commands}
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	45 {only available when compiled with the \|+terminal\| feature}
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	46 The terminal feature requires the \|+multi_byte\|, \|+job\| and \|+channel\| features.
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	47
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	48 ==============================================================================
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	49 1. Basic use terminal-use
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	50
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	51 This feature is for running a terminal emulator in a Vim window. A job can be
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	52 started connected to the terminal emulator. For example, to run a shell: >
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	53 :term bash
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	54
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	55 Or to run build command: >
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	56 :term make myprogram
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	57
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	58 The job runs asynchronously from Vim, the window will be updated to show
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	59 output from the job, also while editing in another window.
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	60
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	61
11814 d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job Christian Brabandt <cb@256bit.org> parents: 11774 diff changeset	62 Typing ~
12457 dfb8254aa735 patch 8.0.1108: cannot specify mappings for the terminal window Christian Brabandt <cb@256bit.org> parents: 12455 diff changeset	63 terminal-typing
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	64 When the keyboard focus is in the terminal window, typed keys will be sent to
11814 d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job Christian Brabandt <cb@256bit.org> parents: 11774 diff changeset	65 the job. This uses a pty when possible. You can click outside of the
d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job Christian Brabandt <cb@256bit.org> parents: 11774 diff changeset	66 terminal window to move keyboard focus elsewhere.
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	67
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	68 CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.:
12833 db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails Christian Brabandt <cb@256bit.org> parents: 12826 diff changeset	69 CTRL-W CTRL-W move focus to the next window
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	70 CTRL-W : enter an Ex command
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	71 See \|CTRL-W\| for more commands.
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	72
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	73 Special in the terminal window: CTRL-W_. CTRL-W_N
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	74 CTRL-W . send a CTRL-W to the job in the terminal
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	75 CTRL-W N go to Terminal-Normal mode, see \|Terminal-mode\|
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	76 CTRL-\ CTRL-N go to Terminal-Normal mode, see \|Terminal-mode\|
11914 4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	77 CTRL-W " {reg} paste register {reg} CTRL-W_quote
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	78 Also works with the = register to insert the result of
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	79 evaluating an expression.
12160 b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	80 CTRL-W CTRL-C ends the job, see below \|t_CTRL-W_CTRL-C\|
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	81
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	82 See option 'termkey' for specifying another key instead of CTRL-W that
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	83 will work like CTRL-W. However, typing 'termkey' twice sends 'termkey' to
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	84 the job. For example:
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	85 'termkey' CTRL-W move focus to the next window
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	86 'termkey' : enter an Ex command
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	87 'termkey' 'termkey' send 'termkey' to the job in the terminal
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	88 'termkey' . send a CTRL-W to the job in the terminal
12833 db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails Christian Brabandt <cb@256bit.org> parents: 12826 diff changeset	89 'termkey' N go to terminal Normal mode, see below
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	90 'termkey' CTRL-N same as CTRL-W N
12160 b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	91 'termkey' CTRL-C same as \|t_CTRL-W_CTRL-C\|
11965 a932d3da41c8 patch 8.0.0863: a remote command does not work in the terminal window Christian Brabandt <cb@256bit.org> parents: 11914 diff changeset	92 t_CTRL-\_CTRL-N
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	93 The special key combination CTRL-\ CTRL-N can be used to switch to Normal
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	94 mode, just like this works in any other mode.
12160 b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	95 t_CTRL-W_CTRL-C
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	96 CTRL-W CTRL-C can be typed to forcefully end the job. On MS-Windows a
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	97 CTRL-BREAK will also kill the job.
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	98
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	99 If you type CTRL-C the effect depends on what the pty has been configured to
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	100 do. For simple commands this causes a SIGINT to be sent to the job, which
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	101 would end it. Other commands may ignore the SIGINT or handle the CTRL-C
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	102 themselves (like Vim does).
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	103
12457 dfb8254aa735 patch 8.0.1108: cannot specify mappings for the terminal window Christian Brabandt <cb@256bit.org> parents: 12455 diff changeset	104 To change the keys you type use terminal mode mappings, see \|:tmap\|.
dfb8254aa735 patch 8.0.1108: cannot specify mappings for the terminal window Christian Brabandt <cb@256bit.org> parents: 12455 diff changeset	105 These are defined like any mapping, but apply only when typing keys that are
13482 9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8. Christian Brabandt <cb@256bit.org> parents: 13476 diff changeset	106 sent to the job running in the terminal. For example, to make F1 switch
12559 34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	107 to Terminal-Normal mode: >
13482 9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8. Christian Brabandt <cb@256bit.org> parents: 13476 diff changeset	108 tnoremap <F1> <C-W>N
9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8. Christian Brabandt <cb@256bit.org> parents: 13476 diff changeset	109 You can use Esc, but you need to make sure it won't cause other keys to
9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8. Christian Brabandt <cb@256bit.org> parents: 13476 diff changeset	110 break: >
12559 34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	111 tnoremap <Esc> <C-W>N
13482 9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8. Christian Brabandt <cb@256bit.org> parents: 13476 diff changeset	112 set notimeout ttimeout timeoutlen=100
9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8. Christian Brabandt <cb@256bit.org> parents: 13476 diff changeset	113
12756 3b26420fc639 Long overdue runtime update. Christian Brabandt <cb@256bit.org> parents: 12559 diff changeset	114 < options-in-terminal
12559 34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	115 After opening the terminal window and setting 'buftype' to "terminal" the
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	116 BufWinEnter autocommand event is triggered. This makes it possible to set
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	117 options specifically for the window and buffer. Example: >
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	118 au BufWinEnter * if &buftype == 'terminal' \| setlocal bufhidden=hide \| endif
12457 dfb8254aa735 patch 8.0.1108: cannot specify mappings for the terminal window Christian Brabandt <cb@256bit.org> parents: 12455 diff changeset	119
12907 32531a3eab1f patch 8.0.1330: MS-Windows: job in terminal can't get back to Vim Christian Brabandt <cb@256bit.org> parents: 12833 diff changeset	120 Mouse events (click and drag) are passed to the terminal. Mouse move events
32531a3eab1f patch 8.0.1330: MS-Windows: job in terminal can't get back to Vim Christian Brabandt <cb@256bit.org> parents: 12833 diff changeset	121 are only passed when Vim itself is receiving them. For a terminal that is
32531a3eab1f patch 8.0.1330: MS-Windows: job in terminal can't get back to Vim Christian Brabandt <cb@256bit.org> parents: 12833 diff changeset	122 when 'balloonevalterm' is enabled.
32531a3eab1f patch 8.0.1330: MS-Windows: job in terminal can't get back to Vim Christian Brabandt <cb@256bit.org> parents: 12833 diff changeset	123
11814 d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job Christian Brabandt <cb@256bit.org> parents: 11774 diff changeset	124
12160 b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	125 Size and color ~
12826 f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	126 terminal-size-color
11659 49c12c93abf3 Updated runtime files and translations. Christian Brabandt <cb@256bit.org> parents: 11621 diff changeset	127 See option 'termsize' for controlling the size of the terminal window.
49c12c93abf3 Updated runtime files and translations. Christian Brabandt <cb@256bit.org> parents: 11621 diff changeset	128 (TODO: scrolling when the terminal is larger than the window)
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	129
12455 85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file Christian Brabandt <cb@256bit.org> parents: 12425 diff changeset	130 The job running in the terminal can change the colors. The default foreground
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file Christian Brabandt <cb@256bit.org> parents: 12425 diff changeset	131 and background colors are taken from Vim, the Normal highlight group.
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file Christian Brabandt <cb@256bit.org> parents: 12425 diff changeset	132
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file Christian Brabandt <cb@256bit.org> parents: 12425 diff changeset	133 For a color terminal the 'background' option is used to decide whether the
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file Christian Brabandt <cb@256bit.org> parents: 12425 diff changeset	134 terminal window will start with a white or black background.
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file Christian Brabandt <cb@256bit.org> parents: 12425 diff changeset	135
13100 656ab57d1ddc update a few runtime files Christian Brabandt <cb@256bit.org> parents: 13051 diff changeset	136 To use a different color the Terminal highlight group can be used, for
656ab57d1ddc update a few runtime files Christian Brabandt <cb@256bit.org> parents: 13051 diff changeset	137 example: >
12455 85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file Christian Brabandt <cb@256bit.org> parents: 12425 diff changeset	138 hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue
12160 b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	139
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	140
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	141 Syntax ~
11774 edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	142
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	143 :[range]ter[minal] [options] [command] :ter :terminal
11774 edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	144 Open a new terminal window.
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	145
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	146 If [command] is provided run it as a job and connect
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	147 the input and output to the terminal.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	148 If [command] is not given the 'shell' option is used.
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	149 if [command] is NONE no job is started, the pty of the
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	150 terminal can be used by a command like gdb.
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	151
13476 d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped Christian Brabandt <cb@256bit.org> parents: 13438 diff changeset	152 If [command] is missing the default behavior is to
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped Christian Brabandt <cb@256bit.org> parents: 13438 diff changeset	153 close the terminal when the shell exits. This can be
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped Christian Brabandt <cb@256bit.org> parents: 13438 diff changeset	154 changed with the ++noclose argument.
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped Christian Brabandt <cb@256bit.org> parents: 13438 diff changeset	155 If [command] is present the default behavior is to
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped Christian Brabandt <cb@256bit.org> parents: 13438 diff changeset	156 keep the terminal open in Terminal-Normal mode. This
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped Christian Brabandt <cb@256bit.org> parents: 13438 diff changeset	157 can be changed with the ++close argument.
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped Christian Brabandt <cb@256bit.org> parents: 13438 diff changeset	158
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	159 A new buffer will be created, using [command] or
11914 4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	160 'shell' as the name, prefixed with a "!". If a buffer
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	161 by this name already exists a number is added in
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	162 parentheses. E.g. if "gdb" exists the second terminal
11914 4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	163 buffer will use "!gdb (1)".
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	164
12192 6947d5bcf57f patch 8.0.0976: cannot send lines to a terminal job Christian Brabandt <cb@256bit.org> parents: 12160 diff changeset	165 If [range] is given the specified lines are used as
6947d5bcf57f patch 8.0.0976: cannot send lines to a terminal job Christian Brabandt <cb@256bit.org> parents: 12160 diff changeset	166 input for the job. It will not be possible to type
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	167 keys in the terminal window. For MS-Windows see the
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	168 ++eof argument below.
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	169
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	170 term++close term++open
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	171 Supported [options] are:
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	172 ++close The terminal window will close
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	173 automatically when the job terminates.
13476 d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped Christian Brabandt <cb@256bit.org> parents: 13438 diff changeset	174 ++noclose The terminal window will NOT close
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped Christian Brabandt <cb@256bit.org> parents: 13438 diff changeset	175 automatically when the job terminates.
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	176 ++open When the job terminates and no window
12064 407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	177 shows it, a window will be opened.
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	178 Note that this can be interruptive.
13476 d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped Christian Brabandt <cb@256bit.org> parents: 13438 diff changeset	179 The last of ++close, ++noclose and ++open
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped Christian Brabandt <cb@256bit.org> parents: 13438 diff changeset	180 matters and rules out earlier arguments.
d130044d4f1f patch 8.0.1612: need to close terminal after shell stopped Christian Brabandt <cb@256bit.org> parents: 13438 diff changeset	181
12064 407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	182 ++curwin Open the terminal in the current
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	183 window, do not split the current
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	184 window. Fails if the current buffer
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	185 cannot be \|abandon\|ed.
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	186 ++hidden Open the terminal in a hidden buffer,
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	187 no window will be used.
13437 02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	188 ++norestore Do not include this terminal window
02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	189 in a session file.
13438 33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window Christian Brabandt <cb@256bit.org> parents: 13437 diff changeset	190 ++kill={how} When trying to close the terminal
33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window Christian Brabandt <cb@256bit.org> parents: 13437 diff changeset	191 window kill the job with {how}. See
33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window Christian Brabandt <cb@256bit.org> parents: 13437 diff changeset	192 \|term_setkill()\| for the values.
12192 6947d5bcf57f patch 8.0.0976: cannot send lines to a terminal job Christian Brabandt <cb@256bit.org> parents: 12160 diff changeset	193 ++rows={height} Use {height} for the terminal window
13125 371ceeebbdaa Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13100 diff changeset	194 height. If the terminal uses the full
371ceeebbdaa Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13100 diff changeset	195 Vim height (no window above or below
371ceeebbdaa Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13100 diff changeset	196 th terminal window) the command line
371ceeebbdaa Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13100 diff changeset	197 height will be reduced as needed.
12192 6947d5bcf57f patch 8.0.0976: cannot send lines to a terminal job Christian Brabandt <cb@256bit.org> parents: 12160 diff changeset	198 ++cols={width} Use {width} for the terminal window
13125 371ceeebbdaa Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13100 diff changeset	199 width. If the terminal uses the full
371ceeebbdaa Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13100 diff changeset	200 Vim width (no window left or right of
371ceeebbdaa Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13100 diff changeset	201 the terminal window) this value is
371ceeebbdaa Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13100 diff changeset	202 ignored.
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	203 ++eof={text} when using [range]: text to send after
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	204 the last line was written. Cannot
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	205 contain white space. A CR is
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	206 appended. For MS-Windows the default
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	207 is to send CTRL-D.
12311 66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows Christian Brabandt <cb@256bit.org> parents: 12267 diff changeset	208 E.g. for a shell use "++eof=exit" and
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows Christian Brabandt <cb@256bit.org> parents: 12267 diff changeset	209 for Python "++eof=exit()". Special
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows Christian Brabandt <cb@256bit.org> parents: 12267 diff changeset	210 codes can be used like with `:map`,
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows Christian Brabandt <cb@256bit.org> parents: 12267 diff changeset	211 e.g. "<C-Z>" for CTRL-Z.
12064 407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	212
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	213 If you want to use more options use the \|term_start()\|
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	214 function.
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	215
13438 33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window Christian Brabandt <cb@256bit.org> parents: 13437 diff changeset	216 When the buffer associated with the terminal is forcibly unloaded or wiped out
33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window Christian Brabandt <cb@256bit.org> parents: 13437 diff changeset	217 the job is killed, similar to calling `job_stop(job, "kill")` .
33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window Christian Brabandt <cb@256bit.org> parents: 13437 diff changeset	218 Closing the window normally results in \|E947\|. When a kill method was set
33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window Christian Brabandt <cb@256bit.org> parents: 13437 diff changeset	219 with "++kill={how}" or \|term_setkill()\| then closing the window will use that
33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window Christian Brabandt <cb@256bit.org> parents: 13437 diff changeset	220 way to kill or interrupt the job. For example: >
33eea5ce5415 patch 8.0.1593: :qall never exits with an active terminal window Christian Brabandt <cb@256bit.org> parents: 13437 diff changeset	221 :term ++kill=term tail -f /tmp/log
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	222
12267 e3bde71afff0 patch 8.0.1013: terminal window behaves different from a buffer with changes Christian Brabandt <cb@256bit.org> parents: 12254 diff changeset	223 So long as the job is running the window behaves like it contains a modified
12311 66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows Christian Brabandt <cb@256bit.org> parents: 12267 diff changeset	224 buffer. Trying to close the window with `CTRL-W :quit` fails. When using
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows Christian Brabandt <cb@256bit.org> parents: 12267 diff changeset	225 `CTRL-W :quit!` the job is ended. The text in the window is lost. The buffer
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows Christian Brabandt <cb@256bit.org> parents: 12267 diff changeset	226 still exists, but getting it in a window with `:buffer` will show an empty
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows Christian Brabandt <cb@256bit.org> parents: 12267 diff changeset	227 buffer.
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows Christian Brabandt <cb@256bit.org> parents: 12267 diff changeset	228
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows Christian Brabandt <cb@256bit.org> parents: 12267 diff changeset	229 Trying to close the window with `CTRL-W :close` also fails. Using
66fa8eabbd6e patch 8.0.1035: sending buffer lines to terminal doesn't work on MS-Windows Christian Brabandt <cb@256bit.org> parents: 12267 diff changeset	230 `CTRL-W :close!` will close the window and make the buffer hidden.
12267 e3bde71afff0 patch 8.0.1013: terminal window behaves different from a buffer with changes Christian Brabandt <cb@256bit.org> parents: 12254 diff changeset	231
e3bde71afff0 patch 8.0.1013: terminal window behaves different from a buffer with changes Christian Brabandt <cb@256bit.org> parents: 12254 diff changeset	232 You can use `CTRL-W :hide` to close the terminal window and make the buffer
e3bde71afff0 patch 8.0.1013: terminal window behaves different from a buffer with changes Christian Brabandt <cb@256bit.org> parents: 12254 diff changeset	233 hidden, the job keeps running. The `:buffer` command can be used to turn the
e3bde71afff0 patch 8.0.1013: terminal window behaves different from a buffer with changes Christian Brabandt <cb@256bit.org> parents: 12254 diff changeset	234 current window into a terminal window. If there are unsaved changes this
e3bde71afff0 patch 8.0.1013: terminal window behaves different from a buffer with changes Christian Brabandt <cb@256bit.org> parents: 12254 diff changeset	235 fails, use ! to force, as usual.
12064 407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	236
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	237 To have a background job run without a window, and open the window when it's
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	238 done, use options like this: >
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	239 :term ++hidden ++open make
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	240 Note that the window will open at an unexpected moment, this will interrupt
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	241 what you are doing.
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	242
12160 b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	243 E947 E948
11967 12833414cc02 patch 8.0.0864: cannot specify the name of a terminal Christian Brabandt <cb@256bit.org> parents: 11965 diff changeset	244 So long as the job is running, the buffer is considered modified and Vim
12833414cc02 patch 8.0.0864: cannot specify the name of a terminal Christian Brabandt <cb@256bit.org> parents: 11965 diff changeset	245 cannot be quit easily, see \|abandon\|.
11914 4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	246
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	247 When the job has finished and no changes were made to the buffer: closing the
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	248 window will wipe out the buffer.
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	249
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	250 Before changes can be made to a terminal buffer, the 'modifiable' option must
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	251 be set. This is only possible when the job has finished. At the first change
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	252 the buffer will become a normal buffer and the highlighting is removed.
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	253 You may want to change the buffer name with \|:file\| to be able to write, since
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	254 the buffer name will still be set to the command.
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	255
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	256
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	257 Resizing ~
12826 f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	258 terminal-resizing
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	259 The size of the terminal can be in one of three modes:
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	260
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	261 1. The 'termsize' option is empty: The terminal size follows the window size.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	262 The minimal size is 2 screen lines with 10 cells.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	263
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	264 2. The 'termsize' option is "rows*cols", where "rows" is the minimal number of
11774 edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	265 screen rows and "cols" is the minimal number of cells.
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	266
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	267 3. The 'termsize' option is "rowsXcols" (where the x is upper or lower case).
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	268 The terminal size is fixed to the specified number of screen lines and
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	269 cells. If the window is bigger there will be unused empty space.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	270
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	271 If the window is smaller than the terminal size, only part of the terminal can
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	272 be seen (the lower-left part).
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	273
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	274 The \|term_getsize()\| function can be used to get the current size of the
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	275 terminal. \|term_setsize()\| can be used only when in the first or second mode,
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	276 not when 'termsize' is "rowsXcols".
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	277
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	278
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	279 Terminal-Job and Terminal-Normal mode ~
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	280 Terminal-mode
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	281 When the job is running the contents of the terminal is under control of the
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	282 job. That includes the cursor position. Typed keys are sent to the job.
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	283 The terminal contents can change at any time. This is called Terminal-Job
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	284 mode.
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	285
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	286 Use CTRL-W N (or 'termkey' N) to switch to Terminal-Normal mode. Now the
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	287 contents of the terminal window is under control of Vim, the job output is
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	288 suspended. CTRL-\ CTRL-N does the same.
12457 dfb8254aa735 patch 8.0.1108: cannot specify mappings for the terminal window Christian Brabandt <cb@256bit.org> parents: 12455 diff changeset	289
12487 3f16cf18386c patch 8.0.1123: cannot define a toolbar for a window Christian Brabandt <cb@256bit.org> parents: 12457 diff changeset	290 Terminal-Job mode is where \|:tmap\| mappings are applied. Keys sent by
12457 dfb8254aa735 patch 8.0.1108: cannot specify mappings for the terminal window Christian Brabandt <cb@256bit.org> parents: 12455 diff changeset	291 \|term_sendkeys()\| are not subject to tmap, but keys from \|feedkeys()\| are.
dfb8254aa735 patch 8.0.1108: cannot specify mappings for the terminal window Christian Brabandt <cb@256bit.org> parents: 12455 diff changeset	292
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	293 E946
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	294 In Terminal-Normal mode you can move the cursor around with the usual Vim
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	295 commands, Visually mark text, yank text, etc. But you cannot change the
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	296 contents of the buffer. The commands that would start insert mode, such as
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	297 'i' and 'a', return to Terminal-Job mode. The window will be updated to show
12487 3f16cf18386c patch 8.0.1123: cannot define a toolbar for a window Christian Brabandt <cb@256bit.org> parents: 12457 diff changeset	298 the contents of the terminal. \|:startinsert\| is ineffective.
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	299
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	300 In Terminal-Normal mode the statusline and window title show "(Terminal)". If
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	301 the job ends while in Terminal-Normal mode this changes to
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	302 "(Terminal-finished)".
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	303
12160 b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	304 It is not possible to enter Insert mode from Terminal-Job mode.
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	305
11866 be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	306
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	307 Cursor style ~
12826 f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	308 terminal-cursor-style
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	309 By default the cursor in the terminal window uses a not blinking block. The
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	310 normal xterm escape sequences can be used to change the blinking state and the
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	311 shape. Once focus leaves the terminal window Vim will restore the original
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	312 cursor.
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	313
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	314 An exception is when xterm is started with the "-bc" argument, or another way
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	315 that causes the cursor to blink. This actually means that the blinking flag
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	316 is inverted. Since Vim cannot detect this, the terminal window cursor
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	317 blinking will also be inverted.
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	318
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	319
13437 02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	320 Session ~
02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	321 terminal-session
02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	322 A terminal window will be restored when using a session file, if possible and
02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	323 wanted.
02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	324
02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	325 If "terminal" was removed from 'sessionoptions' then no terminal windows will
02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	326 be restored.
02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	327
02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	328 If the job in the terminal was finished the window will not be restored.
02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	329
02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	330 If the terminal can be restored, the command that was used to open it will be
02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	331 used again. To change this use the \|term_setrestore()\| function. This can
02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	332 also be used to not restore a specific terminal by setting the command to
02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	333 "NONE".
02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	334
02b3f719eacb Update runtime files. Christian Brabandt <cb@256bit.org> parents: 13377 diff changeset	335
12826 f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	336 Special keys ~
f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	337 terminal-special-keys
f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	338 Since the terminal emulator simulates an xterm, only escape sequences that
f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	339 both Vim and xterm recognize will be available in the terminal window. If you
f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	340 want to pass on other escape sequences to the job running in the terminal you
f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	341 need to set up forwarding. Example: >
f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	342 tmap <expr> <Esc>]b SendToTerm("\<Esc>]b")
12833 db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails Christian Brabandt <cb@256bit.org> parents: 12826 diff changeset	343 func SendToTerm(what)
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails Christian Brabandt <cb@256bit.org> parents: 12826 diff changeset	344 call term_sendkeys('', a:what)
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails Christian Brabandt <cb@256bit.org> parents: 12826 diff changeset	345 return ''
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails Christian Brabandt <cb@256bit.org> parents: 12826 diff changeset	346 endfunc
12826 f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	347
f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	348
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	349 Unix ~
12826 f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	350 terminal-unix
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	351 On Unix a pty is used to make it possible to run all kinds of commands. You
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	352 can even run Vim in the terminal! That's used for debugging, see below.
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	353
11914 4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	354 Environment variables are used to pass information to the running job:
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	355 TERM name of the terminal, 'term'
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	356 ROWS number of rows in the terminal initially
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	357 LINES same as ROWS
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	358 COLUMNS number of columns in the terminal initially
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	359 COLORS number of colors, 't_Co' (256256256 in the GUI)
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	360 VIM_SERVERNAME v:servername
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	361
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	362
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	363 MS-Windows ~
12826 f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	364 terminal-ms-windows
11774 edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	365 On MS-Windows winpty is used to make it possible to run all kind of commands.
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	366 Obviously, they must be commands that run in a terminal, not open their own
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	367 window.
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	368
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	369 You need the following two files from winpty:
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	370
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	371 winpty.dll
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	372 winpty-agent.exe
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	373
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	374 You can download them from the following page:
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	375
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	376 https://github.com/rprichard/winpty
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	377
12160 b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	378 Just put the files somewhere in your PATH. You can set the 'winptydll' option
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	379 to point to the right file, if needed. If you have both the 32-bit and 64-bit
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	380 version, rename to winpty32.dll and winpty64.dll to match the way Vim was
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	381 build.
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	382
12907 32531a3eab1f patch 8.0.1330: MS-Windows: job in terminal can't get back to Vim Christian Brabandt <cb@256bit.org> parents: 12833 diff changeset	383 Environment variables are used to pass information to the running job:
32531a3eab1f patch 8.0.1330: MS-Windows: job in terminal can't get back to Vim Christian Brabandt <cb@256bit.org> parents: 12833 diff changeset	384 VIM_SERVERNAME v:servername
32531a3eab1f patch 8.0.1330: MS-Windows: job in terminal can't get back to Vim Christian Brabandt <cb@256bit.org> parents: 12833 diff changeset	385
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	386 ==============================================================================
13535 e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	387 2. Terminal communication terminal-communication
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	388
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	389 There are several ways to communicate with the job running in a terminal:
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	390 - Use \|term_sendkeys()\| to send text and escape sequences from Vim to the job.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	391 - Use the JSON API to send encoded commands from the job to Vim.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	392 - Use the \|client-server\| mechanism. This works on machines with an X server
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	393 and on MS-Windows.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	394
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	395
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	396 Vim to job: term_sendkeys() ~
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	397 terminal-to-job
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	398 This allows for remote controlling the job running in the terminal. It is a
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	399 one-way mechanism. The job can update the display to signal back to Vim.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	400 For example, if a shell is running in a terminal, you can do: >
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	401 call term_sendkeys(buf, "ls *.java\<CR>")
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	402
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	403 This requires for the job to be in the right state where it will do the right
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	404 thing when receiving the keys. For the above example, the shell must be
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	405 waiting for a command to be typed.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	406
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	407 For a job that was written for the purpose, you can use the JSON API escape
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	408 sequence in the other direction. E.g.: >
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	409 call term_sendkeys(buf, "\<Esc>]51;["response"]\x07")
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	410
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	411
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	412 Job to Vim: JSON API ~
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	413 terminal-api
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	414 The job can send JSON to Vim, using a special escape sequence. The JSON
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	415 encodes a command that Vim understands. Example of such a message: >
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	416 <Esc>]51;["drop", "README.md"]<07>
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	417
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	418 The body is always a list, making it easy to find the end: ]<07>.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	419 The <Esc>]51;msg<07> sequence is reserved by xterm for "Emacs shell", which is
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	420 similar to what we are doing here.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	421
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	422 Currently supported commands:
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	423
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	424 call {funcname} {argument}
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	425
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	426 Call a user defined function with [argument]. The function is
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	427 called with the buffer number of the terminal and the decoded
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	428 argument. The user function must sanity check the argument.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	429 The function can use \|term_sendkeys()\| to send back a reply.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	430 Example in JSON: >
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	431 ["call", "Impression", ["play", 14]]
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	432 < Calls a function defined like this: >
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	433 function Impression(bufnum, arglist)
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	434 if len(a:arglist) == 2
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	435 echo "impression " . a:arglist[0]
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	436 echo "count " . a:arglist[1]
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	437 endif
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	438 endfunc
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	439 <
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	440 drop {filename}
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	441
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	442 Let Vim open a file, like the `:drop` command. If {filename}
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	443 is already open in a window, switch to that window. Otherwise
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	444 open a new window to edit {filename}.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	445 Example in JSON: >
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	446 ["drop", "path/file.txt", {"ff": "dos"}]
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	447
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	448 A trick to have Vim send this escape sequence: >
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	449 exe "set t_ts=\<Esc>]51; t_fs=\x07"
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	450 let &titlestring = '["call","TryThis",["hello",123]]'
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	451 redraw
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	452 set t_ts& t_fs&
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	453
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	454 Rationale: Why not allow for any command or expression? Because that might
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	455 create a security problem.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	456
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	457
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	458 Using the client-server feature ~
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	459 terminal-client-server
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	460 This only works when v:servername is not empty. If needed you can set it,
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	461 before opening the terminal, with: >
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	462 call remote_startserver('vim-server')
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	463
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	464 $VIM_SERVERNAME is set in the terminal to pass on the server name.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	465
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	466 In the job you can then do something like: >
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	467 vim --servername $VIM_SERVERNAME --remote +123 some_file.c
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	468 This will open the file "some_file.c" and put the cursor on line 123.
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	469
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	470 ==============================================================================
e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	471 3. Remote testing terminal-testing
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	472
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	473 Most Vim tests execute a script inside Vim. For some tests this does not
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	474 work, running the test interferes with the code being tested. To avoid this
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	475 Vim is executed in a terminal window. The test sends keystrokes to it and
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	476 inspects the resulting screen state.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	477
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	478 Functions ~
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	479
12457 dfb8254aa735 patch 8.0.1108: cannot specify mappings for the terminal window Christian Brabandt <cb@256bit.org> parents: 12455 diff changeset	480 term_sendkeys() send keystrokes to a terminal (not subject to tmap)
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	481 term_wait() wait for screen to be updated
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	482 term_scrape() inspect terminal screen
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	483
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	484
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	485 ==============================================================================
13535 e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	486 4. Diffing screen dumps terminal-diff
13304 013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	487
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	488 In some cases it can be bothersome to test that Vim displays the right
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	489 characters on the screen. E.g. with syntax highlighting. To make this
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	490 simpler it is possible to take a screen dump of a terminal and compare it to
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	491 an expected screen dump.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	492
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	493 Vim uses the window size, text, color and other attributes as displayed. The
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	494 Vim screen size, font and other properties do not matter. Therefore this
13482 9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8. Christian Brabandt <cb@256bit.org> parents: 13476 diff changeset	495 mechanism is portable across systems. A conventional screenshot would reflect
13304 013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	496 all differences, including font size and family.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	497
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	498
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	499 Writing a screen dump test for Vim ~
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	500 terminal-dumptest
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	501 For an example see the Test_syntax_c() function in
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	502 src/testdir/test_syntax.vim. The main parts are:
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	503 - Write a file you want to test with. This is useful for testing syntax
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	504 highlighting. You can also start Vim with en empty buffer.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	505 - Run Vim in a terminal with a specific size. The default is 20 lines of 75
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	506 characters. This makes sure the dump is always this size. The function
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	507 RunVimInTerminal() takes care of this. Pass it the arguments for the Vim
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	508 command.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	509 - Send any commands to Vim using term_sendkeys(). For example: >
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	510 call term_sendkeys(buf, ":echo &lines &columns\<CR>")
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	511 - Check that the screen is now in the expected state, using
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	512 VerifyScreenDump(). This expects the reference screen dump to be in the
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	513 src/testdir/dumps/ directory. Pass the name without ".dump". It is
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	514 recommended to use the name of the test function and a sequence number, so
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	515 that we know what test is using the file.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	516 - Repeat sending commands and checking the state.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	517 - Finally stop Vim by calling StopVimInTerminal().
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	518
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	519 The first time you do this you won't have a screen dump yet. Create an empty
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	520 file for now, e.g.: >
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	521 touch src/testdir/dumps/Test_function_name_01.dump
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	522
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	523 The test will then fail, giving you the command to compare the reference dump
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	524 and the failed dump, e.g.: >
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	525 call term_dumpdiff("Test_func.dump.failed", "dumps/Test_func.dump")
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	526
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	527 Use this command in Vim, with the current directory set to src/testdir.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	528 Once you are satisfied with the test, move the failed dump in place of the
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	529 reference: >
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	530 :!mv Test_func.dump.failed dumps/Test_func.dump
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	531
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	532
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	533 Creating a screen dump ~
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	534 terminal-screendump
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	535
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	536 To create the screen dump, run Vim (or any other program) in a terminal and
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	537 make it show the desired state. Then use the term_dumpwrite() function to
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	538 create a screen dump file. For example: >
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	539 :call term_dumpwrite(77, "mysyntax.dump")
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	540
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	541 Here "77" is the buffer number of the terminal. Use `:ls!` to see it.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	542
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	543 You can view the screen dump with term_dumpload(): >
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	544 :call term_dumpload("mysyntax.dump")
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	545
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	546 To verify that Vim still shows exactly the same screen, run Vim again with
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	547 exactly the same way to show the desired state. Then create a screen dump
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	548 again, using a different file name: >
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	549 :call term_dumpwrite(88, "test.dump")
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	550
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	551 To assert that the files are exactly the same use assert_equalfile(): >
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	552 call assert_equalfile("mysyntax.dump", "test.dump")
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	553
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	554 If there are differences then v:errors will contain the error message.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	555
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	556
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	557 Comparing screen dumps ~
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	558 terminal-diffscreendump
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	559
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	560 assert_equalfile() does not make it easy to see what is different.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	561 To spot the problem use term_dumpdiff(): >
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	562 call term_dumpdiff("mysyntax.dump", "test.dump")
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	563
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	564 This will open a window consisting of three parts:
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	565 1. The contents of the first dump
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	566 2. The difference between the first and second dump
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	567 3. The contents of the second dump
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	568
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	569 You can usually see what differs in the second part. Use the 'ruler' to
13482 9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8. Christian Brabandt <cb@256bit.org> parents: 13476 diff changeset	570 relate it to the position in the first or second dump.
13304 013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	571
13482 9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8. Christian Brabandt <cb@256bit.org> parents: 13476 diff changeset	572 Alternatively, press "s" to swap the first and second dump. Do this several
13304 013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	573 times so that you can spot the difference in the context of the text.
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	574
013c44d9dc09 patch 8.0.1526: no test using a screen dump yet Christian Brabandt <cb@256bit.org> parents: 13125 diff changeset	575 ==============================================================================
13535 e9ffb5b35266 patch 8.0.1641: job in terminal can't communicate with Vim Christian Brabandt <cb@256bit.org> parents: 13482 diff changeset	576 5. Debugging terminal-debug
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	577
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	578 The Terminal debugging plugin can be used to debug a program with gdb and view
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	579 the source code in a Vim window. Since this is completely contained inside
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	580 Vim this also works remotely over an ssh connection.
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	581
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	582
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	583 Starting ~
12826 f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	584 termdebug-starting
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	585 Load the plugin with this command: >
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	586 packadd termdebug
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	587 < :Termdebug
13051 a6d3e2081544 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12907 diff changeset	588 To start debugging use `:Termdebug` followed by the command name, for example: >
12559 34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	589 :Termdebug vim
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	590
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	591 This opens two windows:
13051 a6d3e2081544 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12907 diff changeset	592
12425 29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	593 gdb window A terminal window in which "gdb vim" is executed. Here you
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	594 can directly interact with gdb. The buffer name is "!gdb".
13051 a6d3e2081544 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12907 diff changeset	595
12425 29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	596 program window A terminal window for the executed program. When "run" is
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	597 used in gdb the program I/O will happen in this window, so
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	598 that it does not interfere with controlling gdb. The buffer
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	599 name is "gdb program".
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	600
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	601 The current window is used to show the source code. When gdb pauses the
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	602 source file location will be displayed, if possible. A sign is used to
13377 1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	603 highlight the current position, using highlight group debugPC.
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	604
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	605 If the buffer in the current window is modified, another window will be opened
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	606 to display the current gdb position.
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	607
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	608 Focus the terminal of the executed program to interact with it. This works
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	609 the same as any command running in a terminal window.
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	610
12425 29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	611 When the debugger ends, typically by typing "quit" in the gdb window, the two
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	612 opened windows are closed.
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	613
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	614
12559 34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	615 Example session ~
12826 f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	616 termdebug-example
12559 34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	617 Start in the Vim "src" directory and build Vim: >
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	618 % make
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	619 Start Vim: >
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	620 % ./vim
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	621 Load the termdebug plugin and start debugging Vim: >
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	622 :packadd termdebug
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	623 :Termdebug vim
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	624 You should now have three windows:
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	625 source - where you started, has a window toolbar with buttons
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	626 gdb - you can type gdb commands here
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	627 program - the executed program will use this window
13377 1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	628
12559 34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	629 You can use CTRL-W CTRL-W or the mouse to move focus between windows.
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	630 Put focus on the gdb window and type: >
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	631 break ex_help
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	632 run
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	633 Vim will start running in the program window. Put focus there and type: >
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	634 :help gui
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	635 Gdb will run into the ex_help breakpoint. The source window now shows the
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	636 ex_cmds.c file. A ">>" marker will appear where the breakpoint was set. The
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	637 line where the debugger stopped is highlighted. You can now step through the
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	638 program. Let's use the mouse: click on the "Next" button in the window
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	639 toolbar. You will see the highlighting move as the debugger executes a line
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	640 of source code.
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	641
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	642 Click "Next" a few times until the for loop is highlighted. Put the cursor on
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	643 the end of "eap->arg", then click "Eval" in the toolbar. You will see this
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	644 displayed:
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	645 "eap->arg": 0x555555e68855 "gui" ~
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	646 This way you can inspect the value of local variables. You can also focus the
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	647 gdb window and use a "print" command, e.g.: >
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	648 print *eap
13377 1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	649 If mouse pointer movements are working, Vim will also show a balloon when the
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	650 mouse rests on text that can be evaluated by gdb.
12559 34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	651
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	652 Now go back to the source window and put the cursor on the first line after
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	653 the for loop, then type: >
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	654 :Break
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	655 You will see a ">>" marker appear, this indicates the new breakpoint. Now
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	656 click "Cont" in the toolbar and the code until the breakpoint will be
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	657 executed.
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	658
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	659 You can type more advanced commands in the gdb window. For example, type: >
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	660 watch curbuf
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	661 Now click "Cont" in the toolbar (or type "cont" in the gdb window). Execution
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	662 will now continue until the value of "curbuf" changes, which is in do_ecmd().
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	663 To remove this watchpoint again type in the gdb window: >
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	664 delete 3
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	665
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	666 You can see the stack by typing in the gdb window: >
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	667 where
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	668 Move through the stack frames, e.g. with: >
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	669 frame 3
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	670 The source window will show the code, at the point where the call was made to
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	671 a deeper level.
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	672
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	673
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	674 Stepping through code ~
12826 f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	675 termdebug-stepping
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	676 Put focus on the gdb window to type commands there. Some common ones are:
12833 db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails Christian Brabandt <cb@256bit.org> parents: 12826 diff changeset	677 - CTRL-C interrupt the program
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails Christian Brabandt <cb@256bit.org> parents: 12826 diff changeset	678 - next execute the current line and stop at the next line
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails Christian Brabandt <cb@256bit.org> parents: 12826 diff changeset	679 - step execute the current line and stop at the next statement,
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails Christian Brabandt <cb@256bit.org> parents: 12826 diff changeset	680 entering functions
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails Christian Brabandt <cb@256bit.org> parents: 12826 diff changeset	681 - finish execute until leaving the current function
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails Christian Brabandt <cb@256bit.org> parents: 12826 diff changeset	682 - where show the stack
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails Christian Brabandt <cb@256bit.org> parents: 12826 diff changeset	683 - frame N go to the Nth stack frame
db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails Christian Brabandt <cb@256bit.org> parents: 12826 diff changeset	684 - continue continue execution
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	685
13377 1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	686 In the window showing the source code these commands can be used to control gdb:
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	687 `:Run` [args] run the program with [args] or the previous arguments
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	688 `:Arguments` {args} set arguments for the next `:Run`
12833 db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails Christian Brabandt <cb@256bit.org> parents: 12826 diff changeset	689
13377 1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	690 `:Break` set a breakpoint at the current line; a sign will be displayed
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	691 `:Clear` delete the breakpoint at the current line
12833 db9ffed7e1fc patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails Christian Brabandt <cb@256bit.org> parents: 12826 diff changeset	692
13377 1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	693 `:Step` execute the gdb "step" command
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	694 `:Over` execute the gdb "next" command (`:Next` is a Vim command)
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	695 `:Finish` execute the gdb "finish" command
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	696 `:Continue` execute the gdb "continue" command
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	697 `:Stop` interrupt the program
12425 29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	698
13051 a6d3e2081544 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12907 diff changeset	699 If 'mouse' is set the plugin adds a window toolbar with these entries:
13377 1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	700 Step `:Step`
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	701 Next `:Over`
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	702 Finish `:Finish`
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	703 Cont `:Continue`
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	704 Stop `:Stop`
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	705 Eval `:Evaluate`
13051 a6d3e2081544 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12907 diff changeset	706 This way you can use the mouse to perform the most common commands. You need
a6d3e2081544 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12907 diff changeset	707 to have the 'mouse' option set to enable mouse clicks.
12487 3f16cf18386c patch 8.0.1123: cannot define a toolbar for a window Christian Brabandt <cb@256bit.org> parents: 12457 diff changeset	708
13377 1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	709 You can add the window toolbar in other windows you open with: >
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	710 :Winbar
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	711
12425 29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	712
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	713 Inspecting variables ~
12826 f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	714 termdebug-variables
13377 1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	715 `:Evaluate` evaluate the expression under the cursor
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	716 `K` same
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	717 `:Evaluate` {expr} evaluate {expr}
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	718 `:'<,'>Evaluate` evaluate the Visually selected text
12425 29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	719
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	720 This is similar to using "print" in the gdb window.
13377 1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	721 You can usually shorten `:Evaluate` to `:Ev`.
12425 29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	722
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	723
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	724 Other commands ~
12826 f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	725 termdebug-commands
12425 29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	726 :Gdb jump to the gdb window
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	727 :Program jump to the window with the running program
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	728
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	729
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	730 Communication ~
12826 f690da1b3c04 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 12756 diff changeset	731 termdebug-communication
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	732 There is another, hidden, buffer, which is used for Vim to communicate with
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	733 gdb. The buffer name is "gdb communication". Do not delete this buffer, it
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	734 will break the debugger.
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	735
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	736
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	737 Customizing ~
13377 1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	738
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	739 GDB command termdebug-customizing
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	740
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	741 To change the name of the gdb command, set the "termdebugger" variable before
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	742 invoking `:Termdebug`: >
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	743 let termdebugger = "mygdb"
13377 1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	744 < gdb-version
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	745 Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI
13482 9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8. Christian Brabandt <cb@256bit.org> parents: 13476 diff changeset	746 interface. The "new-ui" command requires gdb version 7.12 or later. if you
9eebe457eb3c Update runtime files. Convert a couple of help files to utf-8. Christian Brabandt <cb@256bit.org> parents: 13476 diff changeset	747 get this error:
12756 3b26420fc639 Long overdue runtime update. Christian Brabandt <cb@256bit.org> parents: 12559 diff changeset	748 Undefined command: "new-ui". Try "help".~
3b26420fc639 Long overdue runtime update. Christian Brabandt <cb@256bit.org> parents: 12559 diff changeset	749 Then your gdb is too old.
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	750
13377 1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	751
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	752 Colors hl-debugPC hl-debugBreakpoint
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	753
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	754 The color of the signs can be adjusted with these highlight groups:
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	755 - debugPC the current position
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	756 - debugBreakpoint a breakpoint
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	757
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	758 The defaults are, when 'background' is "light":
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	759 hi debugPC term=reverse ctermbg=lightblue guibg=lightblue
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	760 hi debugBreakpoint term=reverse ctermbg=red guibg=red
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	761
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	762 When 'background' is "dark":
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	763 hi debugPC term=reverse ctermbg=darkblue guibg=darkblue
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	764 hi debugBreakpoint term=reverse ctermbg=red guibg=red
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	765
13377 1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	766
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	767 Popup menu termdebug_popup
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	768
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	769 By default the Termdebug plugin sets 'mousemodel' to "popup_setpos" and adds
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	770 these entries to the popup menu:
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	771 Set breakpoint `:Break`
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	772 Clear breakpoint `:Clear`
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	773 Evaluate `:Evaluate`
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	774 If you don't want this then disable it with: >
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	775 let g:termdebug_popup = 0
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	776
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	777
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	778 Vim window width termdebug_wide
1ffba37fd222 patch 8.0.1562: the terminal debugger can't set a breakpoint with the mouse Christian Brabandt <cb@256bit.org> parents: 13304 diff changeset	779
12455 85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file Christian Brabandt <cb@256bit.org> parents: 12425 diff changeset	780 To change the width of the Vim window when debugging starts, and use a
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file Christian Brabandt <cb@256bit.org> parents: 12425 diff changeset	781 vertical split: >
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file Christian Brabandt <cb@256bit.org> parents: 12425 diff changeset	782 let g:termdebug_wide = 163
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file Christian Brabandt <cb@256bit.org> parents: 12425 diff changeset	783 This will set &columns to 163 when :Termdebug is used. The value is restored
85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file Christian Brabandt <cb@256bit.org> parents: 12425 diff changeset	784 when quitting the debugger.
12559 34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	785 If g:termdebug_wide is set and &Columns is already larger than
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	786 g:termdebug_wide then a vertical split will be used without changing &columns.
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	787 Set it to 1 to get a vertical split without every changing &columns (useful
34c8ec888122 Update runtime files Christian Brabandt <cb@256bit.org> parents: 12487 diff changeset	788 for when the terminal can't be resized by Vim).
12455 85ddf8e00595 patch 8.0.1107: terminal debugger jumps to non-existing file Christian Brabandt <cb@256bit.org> parents: 12425 diff changeset	789
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	790
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	791
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	792 vim:tw=78:ts=8:ft=help:norl:

Mercurial > vim

annotate runtime/doc/terminal.txt @ 13535:e9ffb5b35266 v8.0.1641