vim: runtime/doc/terminal.txt annotate

annotate runtime/doc/terminal.txt @ 12425:29d21591ad6b v8.0.1092

patch 8.0.1092: terminal debugger can't evaluate expressions commit https://github.com/vim/vim/commit/45d5f26d11d9aac2383453d2c1a8582cad1c8a3d Author: Bram Moolenaar <Bram@vim.org> Date: Sun Sep 10 19:14:31 2017 +0200 patch 8.0.1092: terminal debugger can't evaluate expressions Problem: Terminal debugger can't evaluate expressions. Solution: Add :Evaluate and K. Various other improvements.

author	Christian Brabandt <cb@256bit.org>
date	Sun, 10 Sep 2017 19:15:04 +0200
parents	5d4d744151c2
children	85ddf8e00595

rev	line source
12425 29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	1 terminal.txt For Vim version 8.0. Last change: 2017 Sep 10
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
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	10 WARNING: THIS IS ONLY PARTLY IMPLEMENTED, ANYTHING CAN STILL CHANGE
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	11
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	12 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	13 echo has('terminal')
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	14 If the result is "1" you have it.
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	15
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	16
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	17 1. Basic use \|terminal-use\|
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	18 2. Remote testing \|terminal-testing\|
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	19 3. Debugging \|terminal-debug\|
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	20
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	21 {Vi does not have any of these commands}
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	22 {only available when compiled with the \|+terminal\| feature}
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	23
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	24 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	25
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	26 ==============================================================================
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	27 1. Basic use terminal-use
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	28
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	29 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	30 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	31 :term bash
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	32
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	33 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	34 :term make myprogram
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	35
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	36 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	37 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	38
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	39
11814 d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job Christian Brabandt <cb@256bit.org> parents: 11774 diff changeset	40 Typing ~
d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job Christian Brabandt <cb@256bit.org> parents: 11774 diff changeset	41
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	42 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	43 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	44 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	45
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	46 CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.:
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	47 CTRL-W 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	48 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	49 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	50
be40c8a9240d patch 8.0.0813: cannot use a terminal window while the job is running Christian Brabandt <cb@256bit.org> parents: 11814 diff changeset	51 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	52 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	53 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	54 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	55 CTRL-W " {reg} paste register {reg} CTRL-W_quote
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	56 Also works with the = register to insert the result of
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	57 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	58 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	59
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	60 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	61 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	62 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	63 '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	64 '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	65 '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	66 'termkey' . send a CTRL-W 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	67 'termkey' N go to terminal Normal mode, see below
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 '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	69 '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	70 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	71 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	72 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	73 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	74 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	75 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	76
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	77 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	78 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	79 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	80 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	81
11814 d3d0db111d17 patch 8.0.0787: cannot send CTRL-W command to terminal job Christian Brabandt <cb@256bit.org> parents: 11774 diff changeset	82
12160 b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	83 Size and color ~
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	84
11659 49c12c93abf3 Updated runtime files and translations. Christian Brabandt <cb@256bit.org> parents: 11621 diff changeset	85 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	86 (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	87
12160 b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	88 The terminal uses the 'background' option to decide whether the terminal
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	89 window will start with a white or black background. The job running in the
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	90 terminal can change the colors.
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	91
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	92
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	93 Syntax ~
11774 edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	94
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	95 :[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	96 Open a new terminal window.
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	97
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	98 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	99 the input and output to the terminal.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	100 If [command] is not given the 'shell' option is used.
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	101 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	102 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	103
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	104 A new buffer will be created, using [command] or
11914 4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	105 'shell' as the name, prefixed with a "!". If a buffer
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	106 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	107 parentheses. E.g. if "gdb" exists the second terminal
11914 4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	108 buffer will use "!gdb (1)".
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	109
12192 6947d5bcf57f patch 8.0.0976: cannot send lines to a terminal job Christian Brabandt <cb@256bit.org> parents: 12160 diff changeset	110 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	111 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	112 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	113 ++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	114
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	115 Two comma separated numbers are used as "rows,cols".
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	116 E.g. `:24,80gdb` opens a terminal with 24 rows and 80
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	117 columns. However, if the terminal window spans the
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	118 Vim window with, there is no vertical split, the Vim
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	119 window width is used.
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	120 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	121 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	122 ++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	123 automatically when the job terminates.
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	124 ++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	125 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	126 Note that this can be interruptive.
12064 407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	127 ++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	128 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	129 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	130 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	131 ++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	132 no window will be used.
12192 6947d5bcf57f patch 8.0.0976: cannot send lines to a terminal job Christian Brabandt <cb@256bit.org> parents: 12160 diff changeset	133 ++rows={height} Use {height} for the terminal window
6947d5bcf57f patch 8.0.0976: cannot send lines to a terminal job Christian Brabandt <cb@256bit.org> parents: 12160 diff changeset	134 height.
6947d5bcf57f patch 8.0.0976: cannot send lines to a terminal job Christian Brabandt <cb@256bit.org> parents: 12160 diff changeset	135 ++cols={width} Use {width} for the terminal window
6947d5bcf57f patch 8.0.0976: cannot send lines to a terminal job Christian Brabandt <cb@256bit.org> parents: 12160 diff changeset	136 width.
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	137 ++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	138 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	139 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	140 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	141 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	142 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	143 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	144 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	145 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	146
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	147 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	148 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	149
12160 b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	150 When the buffer associated with the terminal is unloaded or wiped out the job
b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	151 is killed, similar to calling `job_stop(job, "kill")`
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	152
12267 e3bde71afff0 patch 8.0.1013: terminal window behaves different from a buffer with changes Christian Brabandt <cb@256bit.org> parents: 12254 diff changeset	153 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	154 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	155 `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	156 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	157 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	158
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	159 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	160 `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	161
e3bde71afff0 patch 8.0.1013: terminal window behaves different from a buffer with changes Christian Brabandt <cb@256bit.org> parents: 12254 diff changeset	162 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	163 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	164 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	165 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	166
407a475c67fd patch 8.0.0912: cannot run a job in a hidden terminal Christian Brabandt <cb@256bit.org> parents: 12031 diff changeset	167 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	168 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	169 :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	170 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	171 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	172
12160 b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	173 E947 E948
11967 12833414cc02 patch 8.0.0864: cannot specify the name of a terminal Christian Brabandt <cb@256bit.org> parents: 11965 diff changeset	174 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	175 cannot be quit easily, see \|abandon\|.
11914 4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	176
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	177 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	178 window will wipe out the buffer.
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	179
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	180 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	181 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	182 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	183 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	184 the buffer name will still be set to the command.
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	185
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	186
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	187 Resizing ~
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	188
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	189 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	190
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	191 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	192 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	193
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	194 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	195 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	196
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	197 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	198 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	199 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	200
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	201 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	202 be seen (the lower-left part).
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	203
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	204 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	205 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	206 not when 'termsize' is "rowsXcols".
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	207
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	208
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	209 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	210 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	211 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	212 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	213 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	214 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	215
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	216 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	217 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	218 suspended. CTRL-\ CTRL-N does the same.
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	219 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	220 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	221 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	222 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	223 'i' and 'a', return to Terminal-Job mode. The window will be updated to show
9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	224 the contents of the terminal.
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	225
12031 9897241c08b5 patch 8.0.0896: cannot close a terminal window when the job ends Christian Brabandt <cb@256bit.org> parents: 11967 diff changeset	226 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	227 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	228 "(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	229
12160 b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	230 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	231
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	232
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	233 Cursor style ~
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	234
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	235 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	236 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	237 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	238 cursor.
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	239
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	240 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	241 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	242 is inverted. Since Vim cannot detect this, the terminal window cursor
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	243 blinking will also be inverted.
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	244
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	245
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	246 Unix ~
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	247
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	248 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	249 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	250
11914 4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	251 Environment variables are used to pass information to the running job:
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	252 TERM name of the terminal, 'term'
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	253 ROWS number of rows in the terminal initially
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	254 LINES same as ROWS
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	255 COLUMNS number of columns in the terminal initially
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	256 COLORS number of colors, 't_Co' (256256256 in the GUI)
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	257 VIM_SERVERNAME v:servername
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	258
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	259 The \|client-server\| feature can be used to communicate with the Vim instance
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	260 where the job was started. This only works when v:servername is not empty.
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	261 If needed you can set it with: >
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	262 call remote_startserver('vim-server')
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	263
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	264 In the job you can then do something like: >
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	265 vim --servername $VIM_SERVERNAME --remote +123 some_file.c
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	266 This will open the file "some_file.c" and put the cursor on line 123.
4f7081eb1e26 Updated runtime files Christian Brabandt <cb@256bit.org> parents: 11866 diff changeset	267
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	268
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	269 MS-Windows ~
21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	270
11774 edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	271 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	272 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	273 window.
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	274
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	275 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	276
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	277 winpty.dll
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	278 winpty-agent.exe
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	279
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	280 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	281
edf1a2a247fa patch 8.0.0769: build problems with terminal on MS-Windows Christian Brabandt <cb@256bit.org> parents: 11763 diff changeset	282 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	283
12160 b80c0172d1a8 patch 8.0.0960: job in terminal does not get CTRL-C Christian Brabandt <cb@256bit.org> parents: 12064 diff changeset	284 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	285 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	286 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	287 build.
11763 21f3930dfe6e Documentation updates. Christian Brabandt <cb@256bit.org> parents: 11659 diff changeset	288
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	289 ==============================================================================
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	290 2. Remote testing terminal-testing
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	291
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	292 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	293 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	294 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	295 inspects the resulting screen state.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	296
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	297 Functions ~
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	298
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	299 term_sendkeys() send keystrokes to a terminal
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	300 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	301 term_scrape() inspect terminal screen
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	302
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	303
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	304 ==============================================================================
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	305 3. Debugging terminal-debug
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	306
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	307 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	308 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	309 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	310
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	311
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	312 Starting ~
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	313
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	314 Load the plugin with this command: >
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	315 packadd termdebug
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	316 < :Termdebug
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	317 To start debugging use `:TermDebug` folowed by the command name, for example: >
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	318 :TermDebug vim
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	319
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	320 This opens two windows:
12425 29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	321 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	322 can directly interact with gdb. The buffer name is "!gdb".
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	323 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	324 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	325 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	326 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	327
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	328 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	329 source file location will be displayed, if possible. A sign is used to
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	330 highlight the current position (using highlight group debugPC).
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	331
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	332 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	333 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	334
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	335 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	336 the same as any command running in a terminal window.
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	337
12425 29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	338 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	339 opened windows are closed.
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	340
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	341
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	342 Stepping through code ~
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	343
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	344 Put focus on the gdb window to type commands there. Some common ones are:
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	345 - CTRL-C interrupt the program
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	346 - next execute the current line and stop at the next line
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	347 - step execute the current line and stop at the next statement, entering
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	348 functions
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	349 - finish execute until leaving the current function
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	350 - where show the stack
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	351 - frame N go to the Nth stack frame
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	352 - continue continue execution
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	353
12425 29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	354 In the window showing the source code some commands can used to control gdb:
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	355 :Break set a breakpoint at the current line; a sign will be displayed
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	356 :Delete delete a breakpoint at the current line
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	357 :Step execute the gdb "step" command
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	358 :Over execute the gdb "next" command (:Next is a Vim command)
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	359 :Finish execute the gdb "finish" command
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	360 :Continue execute the gdb "continue" command
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	361
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	362
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	363 Inspecting variables ~
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	364
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	365 :Evaluate evaluate the expression under the cursor
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	366 K same
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	367 :Evaluate {expr} evaluate {expr}
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	368 :'<,'>Evaluate evaluate the Visually selected text
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	369
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	370 This is similar to using "print" in the gdb window.
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	371
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	372
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	373 Other commands ~
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	374
29d21591ad6b patch 8.0.1092: terminal debugger can't evaluate expressions Christian Brabandt <cb@256bit.org> parents: 12411 diff changeset	375 :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	376 :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	377
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	378
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	379 Communication ~
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	380
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	381 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	382 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	383 will break the debugger.
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	384
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	385
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	386 Customizing ~
8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	387
12411 5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	388 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	389 invoking `:Termdebug`: >
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	390 let termdebugger = "mygdb"
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	391 Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	392 interface.
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	393
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	394 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	395 - debugPC the current position
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	396 - debugBreakpoint a breakpoint
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	397
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	398 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	399 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	400 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	401
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	402 When 'background' is "dark":
5d4d744151c2 patch 8.0.1085: terminal debugger can't set breakpoints Christian Brabandt <cb@256bit.org> parents: 12311 diff changeset	403 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	404 hi debugBreakpoint term=reverse ctermbg=red guibg=red
12254 8d76a56861ec Update runtime files Christian Brabandt <cb@256bit.org> parents: 12192 diff changeset	405
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	406
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	407
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	408 vim:tw=78:ts=8:ft=help:norl:

Mercurial > vim

annotate runtime/doc/terminal.txt @ 12425:29d21591ad6b v8.0.1092