Mercurial > vim
annotate runtime/doc/terminal.txt @ 13438:33eea5ce5415 v8.0.1593
patch 8.0.1593: :qall never exits with an active terminal window
commit https://github.com/vim/vim/commit/25cdd9c33b21ddbd31321c075873bb225450d2d2
Author: Bram Moolenaar <Bram@vim.org>
Date: Sat Mar 10 20:28:12 2018 +0100
patch 8.0.1593: :qall never exits with an active terminal window
Problem: :qall never exits with an active terminal window.
Solution: Add a way to kill a job in a terminal window.
author | Christian Brabandt <cb@256bit.org> |
---|---|
date | Sat, 10 Mar 2018 20:30:04 +0100 |
parents | 02b3f719eacb |
children | d130044d4f1f |
rev | line source |
---|---|
13438
33eea5ce5415
patch 8.0.1593: :qall never exits with an active terminal window
Christian Brabandt <cb@256bit.org>
parents:
13437
diff
changeset
|
1 *terminal.txt* For Vim version 8.0. Last change: 2018 Mar 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 |
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 | 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| |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
26 2. Remote testing |terminal-testing| |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
27 3. Diffing screen dumps |terminal-diff| |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
28 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
|
29 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
|
30 Comparing screen dumps |terminal-diffscreendump| |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
31 4. Debugging |terminal-debug| |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
32 Starting |termdebug-starting| |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
33 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
|
34 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
|
35 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
|
36 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
|
37 Communication |termdebug-communication| |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
38 Customizing |termdebug-customizing| |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
39 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
40 {Vi does not have any of these commands} |
12254 | 41 {only available when compiled with the |+terminal| feature} |
42 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
|
43 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
44 ============================================================================== |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
45 1. Basic use *terminal-use* |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
46 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
47 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
|
48 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
|
49 :term bash |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
50 |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
51 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
|
52 :term make myprogram |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
53 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
54 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
|
55 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
|
56 |
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
|
57 |
11814
d3d0db111d17
patch 8.0.0787: cannot send CTRL-W command to terminal job
Christian Brabandt <cb@256bit.org>
parents:
11774
diff
changeset
|
58 Typing ~ |
12457
dfb8254aa735
patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents:
12455
diff
changeset
|
59 *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
|
60 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
|
61 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
|
62 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
|
63 |
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
|
64 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
|
65 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
|
66 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
|
67 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
|
68 |
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
69 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
|
70 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
|
71 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
|
72 CTRL-\ CTRL-N go to Terminal-Normal mode, see |Terminal-mode| |
11914 | 73 CTRL-W " {reg} paste register {reg} *CTRL-W_quote* |
74 Also works with the = register to insert the result of | |
75 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
|
76 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
|
77 |
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
|
78 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
|
79 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
|
80 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
|
81 '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
|
82 '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
|
83 '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
|
84 '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
|
85 '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
|
86 '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
|
87 '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
|
88 *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
|
89 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
|
90 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
|
91 *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
|
92 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
|
93 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
|
94 |
b80c0172d1a8
patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents:
12064
diff
changeset
|
95 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
|
96 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
|
97 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
|
98 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
|
99 |
12457
dfb8254aa735
patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents:
12455
diff
changeset
|
100 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
|
101 These are defined like any mapping, but apply only when typing keys that are |
12559 | 102 sent to the job running in the terminal. For example, to make Escape switch |
103 to Terminal-Normal mode: > | |
104 tnoremap <Esc> <C-W>N | |
12756
3b26420fc639
Long overdue runtime update.
Christian Brabandt <cb@256bit.org>
parents:
12559
diff
changeset
|
105 < *options-in-terminal* |
12559 | 106 After opening the terminal window and setting 'buftype' to "terminal" the |
107 BufWinEnter autocommand event is triggered. This makes it possible to set | |
108 options specifically for the window and buffer. Example: > | |
109 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
|
110 |
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
|
111 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
|
112 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
|
113 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
|
114 |
11814
d3d0db111d17
patch 8.0.0787: cannot send CTRL-W command to terminal job
Christian Brabandt <cb@256bit.org>
parents:
11774
diff
changeset
|
115 |
12160
b80c0172d1a8
patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents:
12064
diff
changeset
|
116 Size and color ~ |
12826 | 117 *terminal-size-color* |
11659
49c12c93abf3
Updated runtime files and translations.
Christian Brabandt <cb@256bit.org>
parents:
11621
diff
changeset
|
118 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
|
119 (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
|
120 |
12455
85ddf8e00595
patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents:
12425
diff
changeset
|
121 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
|
122 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
|
123 |
85ddf8e00595
patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents:
12425
diff
changeset
|
124 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
|
125 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
|
126 |
13100
656ab57d1ddc
update a few runtime files
Christian Brabandt <cb@256bit.org>
parents:
13051
diff
changeset
|
127 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
|
128 example: > |
12455
85ddf8e00595
patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents:
12425
diff
changeset
|
129 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
|
130 |
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
|
131 |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
132 Syntax ~ |
11774
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
133 |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
134 :[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
|
135 Open a new terminal window. |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
136 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
137 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
|
138 the input and output to the terminal. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
139 If [command] is not given the 'shell' option is used. |
12254 | 140 if [command] is NONE no job is started, the pty of the |
141 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
|
142 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
143 A new buffer will be created, using [command] or |
11914 | 144 'shell' as the name, prefixed with a "!". If a buffer |
145 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
|
146 parentheses. E.g. if "gdb" exists the second terminal |
11914 | 147 buffer will use "!gdb (1)". |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
148 |
12192
6947d5bcf57f
patch 8.0.0976: cannot send lines to a terminal job
Christian Brabandt <cb@256bit.org>
parents:
12160
diff
changeset
|
149 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
|
150 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
|
151 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
|
152 ++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
|
153 |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
154 *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
|
155 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
|
156 ++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
|
157 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
|
158 ++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
|
159 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
|
160 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
|
161 ++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
|
162 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
|
163 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
|
164 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
|
165 ++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
|
166 no window will be used. |
13437 | 167 ++norestore Do not include this terminal window |
168 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
|
169 ++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
|
170 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
|
171 |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
|
172 ++rows={height} Use {height} for the terminal window |
13125 | 173 height. If the terminal uses the full |
174 Vim height (no window above or below | |
175 th terminal window) the command line | |
176 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
|
177 ++cols={width} Use {width} for the terminal window |
13125 | 178 width. If the terminal uses the full |
179 Vim width (no window left or right of | |
180 the terminal window) this value is | |
181 ignored. | |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
182 ++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
|
183 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
|
184 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
|
185 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
|
186 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
|
187 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
|
188 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
|
189 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
|
190 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
|
191 |
407a475c67fd
patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents:
12031
diff
changeset
|
192 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
|
193 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
|
194 |
13438
33eea5ce5415
patch 8.0.1593: :qall never exits with an active terminal window
Christian Brabandt <cb@256bit.org>
parents:
13437
diff
changeset
|
195 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
|
196 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
|
197 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
|
198 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
|
199 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
|
200 :term ++kill=term tail -f /tmp/log |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
201 |
12267
e3bde71afff0
patch 8.0.1013: terminal window behaves different from a buffer with changes
Christian Brabandt <cb@256bit.org>
parents:
12254
diff
changeset
|
202 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
|
203 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
|
204 `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
|
205 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
|
206 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
|
207 |
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 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
|
209 `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
|
210 |
e3bde71afff0
patch 8.0.1013: terminal window behaves different from a buffer with changes
Christian Brabandt <cb@256bit.org>
parents:
12254
diff
changeset
|
211 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
|
212 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
|
213 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
|
214 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
|
215 |
407a475c67fd
patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents:
12031
diff
changeset
|
216 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
|
217 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
|
218 :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
|
219 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
|
220 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
|
221 |
12160
b80c0172d1a8
patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents:
12064
diff
changeset
|
222 *E947* *E948* |
11967
12833414cc02
patch 8.0.0864: cannot specify the name of a terminal
Christian Brabandt <cb@256bit.org>
parents:
11965
diff
changeset
|
223 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
|
224 cannot be quit easily, see |abandon|. |
11914 | 225 |
226 When the job has finished and no changes were made to the buffer: closing the | |
227 window will wipe out the buffer. | |
228 | |
229 Before changes can be made to a terminal buffer, the 'modifiable' option must | |
230 be set. This is only possible when the job has finished. At the first change | |
231 the buffer will become a normal buffer and the highlighting is removed. | |
232 You may want to change the buffer name with |:file| to be able to write, since | |
233 the buffer name will still be set to the command. | |
234 | |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
235 |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
236 Resizing ~ |
12826 | 237 *terminal-resizing* |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
238 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
|
239 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
240 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
|
241 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
|
242 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
243 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
|
244 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
|
245 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
246 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
|
247 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
|
248 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
|
249 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
250 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
|
251 be seen (the lower-left part). |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
252 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
253 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
|
254 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
|
255 not when 'termsize' is "rowsXcols". |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
256 |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
257 |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
258 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
|
259 *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
|
260 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
|
261 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
|
262 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
|
263 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
|
264 |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
265 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
|
266 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
|
267 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
|
268 |
12487
3f16cf18386c
patch 8.0.1123: cannot define a toolbar for a window
Christian Brabandt <cb@256bit.org>
parents:
12457
diff
changeset
|
269 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
|
270 |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
|
271 |
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
|
272 *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
|
273 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
|
274 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
|
275 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
|
276 '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
|
277 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
|
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 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
|
280 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
|
281 "(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
|
282 |
12160
b80c0172d1a8
patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents:
12064
diff
changeset
|
283 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
|
284 |
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 |
12254 | 286 Cursor style ~ |
12826 | 287 *terminal-cursor-style* |
12254 | 288 By default the cursor in the terminal window uses a not blinking block. The |
289 normal xterm escape sequences can be used to change the blinking state and the | |
290 shape. Once focus leaves the terminal window Vim will restore the original | |
291 cursor. | |
292 | |
293 An exception is when xterm is started with the "-bc" argument, or another way | |
294 that causes the cursor to blink. This actually means that the blinking flag | |
295 is inverted. Since Vim cannot detect this, the terminal window cursor | |
296 blinking will also be inverted. | |
297 | |
298 | |
13437 | 299 Session ~ |
300 *terminal-session* | |
301 A terminal window will be restored when using a session file, if possible and | |
302 wanted. | |
303 | |
304 If "terminal" was removed from 'sessionoptions' then no terminal windows will | |
305 be restored. | |
306 | |
307 If the job in the terminal was finished the window will not be restored. | |
308 | |
309 If the terminal can be restored, the command that was used to open it will be | |
310 used again. To change this use the |term_setrestore()| function. This can | |
311 also be used to not restore a specific terminal by setting the command to | |
312 "NONE". | |
313 | |
314 | |
12826 | 315 Special keys ~ |
316 *terminal-special-keys* | |
317 Since the terminal emulator simulates an xterm, only escape sequences that | |
318 both Vim and xterm recognize will be available in the terminal window. If you | |
319 want to pass on other escape sequences to the job running in the terminal you | |
320 need to set up forwarding. Example: > | |
321 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
|
322 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
|
323 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
|
324 return '' |
db9ffed7e1fc
patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails
Christian Brabandt <cb@256bit.org>
parents:
12826
diff
changeset
|
325 endfunc |
12826 | 326 |
327 | |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
328 Unix ~ |
12826 | 329 *terminal-unix* |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
330 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
|
331 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
|
332 |
11914 | 333 Environment variables are used to pass information to the running job: |
334 TERM name of the terminal, 'term' | |
335 ROWS number of rows in the terminal initially | |
336 LINES same as ROWS | |
337 COLUMNS number of columns in the terminal initially | |
338 COLORS number of colors, 't_Co' (256*256*256 in the GUI) | |
339 VIM_SERVERNAME v:servername | |
340 | |
341 The |client-server| feature can be used to communicate with the Vim instance | |
342 where the job was started. This only works when v:servername is not empty. | |
343 If needed you can set it with: > | |
344 call remote_startserver('vim-server') | |
345 | |
346 In the job you can then do something like: > | |
347 vim --servername $VIM_SERVERNAME --remote +123 some_file.c | |
348 This will open the file "some_file.c" and put the cursor on line 123. | |
349 | |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
350 |
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
351 MS-Windows ~ |
12826 | 352 *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
|
353 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
|
354 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
|
355 window. |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
356 |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
357 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
|
358 |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
359 winpty.dll |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
360 winpty-agent.exe |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
361 |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
362 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
|
363 |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
364 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
|
365 |
12160
b80c0172d1a8
patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents:
12064
diff
changeset
|
366 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
|
367 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
|
368 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
|
369 build. |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
370 |
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
|
371 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
|
372 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
|
373 |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
374 ============================================================================== |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
375 2. Remote testing *terminal-testing* |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
376 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
377 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
|
378 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
|
379 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
|
380 inspects the resulting screen state. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
381 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
382 Functions ~ |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
383 |
12457
dfb8254aa735
patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents:
12455
diff
changeset
|
384 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
|
385 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
|
386 term_scrape() inspect terminal screen |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
387 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
388 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
389 ============================================================================== |
13304
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
390 3. Diffing screen dumps *terminal-diff* |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
391 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
392 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
|
393 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
|
394 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
|
395 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
|
396 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
397 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
|
398 Vim screen size, font and other properties do not matter. Therefore this |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
399 mechanism is portable across systems. A convential screenshot would reflect |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
400 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
|
401 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
402 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
403 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
|
404 *terminal-dumptest* |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
405 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
|
406 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
|
407 - 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
|
408 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
|
409 - 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
|
410 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
|
411 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
|
412 command. |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
413 - 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
|
414 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
|
415 - 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
|
416 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
|
417 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
|
418 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
|
419 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
|
420 - 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
|
421 - 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
|
422 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
423 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
|
424 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
|
425 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
|
426 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
427 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
|
428 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
|
429 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
|
430 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
431 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
|
432 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
|
433 reference: > |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
434 :!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
|
435 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
436 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
437 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
|
438 *terminal-screendump* |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
439 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
440 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
|
441 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
|
442 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
|
443 :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
|
444 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
445 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
|
446 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
447 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
|
448 :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
|
449 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
450 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
|
451 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
|
452 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
|
453 :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
|
454 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
455 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
|
456 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
|
457 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
458 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
|
459 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
460 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
461 Comparing screen dumps ~ |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
462 *terminal-diffscreendump* |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
463 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
464 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
|
465 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
|
466 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
|
467 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
468 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
|
469 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
|
470 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
|
471 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
|
472 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
473 You can usually see what differs in the second part. Use the 'ruler' to |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
474 relate it to the postion in the first or second dump. |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
475 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
476 Alternatively, press "s" to swap the first and second dump. Do this everal |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
477 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
|
478 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
479 ============================================================================== |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
480 4. Debugging *terminal-debug* |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
481 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
482 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
|
483 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
|
484 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
|
485 |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
486 |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
487 Starting ~ |
12826 | 488 *termdebug-starting* |
12254 | 489 Load the plugin with this command: > |
490 packadd termdebug | |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
491 < *:Termdebug* |
13051 | 492 To start debugging use `:Termdebug` followed by the command name, for example: > |
12559 | 493 :Termdebug vim |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
494 |
12254 | 495 This opens two windows: |
13051 | 496 |
12425
29d21591ad6b
patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents:
12411
diff
changeset
|
497 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
|
498 can directly interact with gdb. The buffer name is "!gdb". |
13051 | 499 |
12425
29d21591ad6b
patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents:
12411
diff
changeset
|
500 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
|
501 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
|
502 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
|
503 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
|
504 |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
505 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
|
506 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
|
507 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
|
508 |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
509 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
|
510 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
|
511 |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
512 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
|
513 the same as any command running in a terminal window. |
12254 | 514 |
12425
29d21591ad6b
patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents:
12411
diff
changeset
|
515 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
|
516 opened windows are closed. |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
517 |
12254 | 518 |
12559 | 519 Example session ~ |
12826 | 520 *termdebug-example* |
12559 | 521 Start in the Vim "src" directory and build Vim: > |
522 % make | |
523 Start Vim: > | |
524 % ./vim | |
525 Load the termdebug plugin and start debugging Vim: > | |
526 :packadd termdebug | |
527 :Termdebug vim | |
528 You should now have three windows: | |
529 source - where you started, has a window toolbar with buttons | |
530 gdb - you can type gdb commands here | |
531 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
|
532 |
12559 | 533 You can use CTRL-W CTRL-W or the mouse to move focus between windows. |
534 Put focus on the gdb window and type: > | |
535 break ex_help | |
536 run | |
537 Vim will start running in the program window. Put focus there and type: > | |
538 :help gui | |
539 Gdb will run into the ex_help breakpoint. The source window now shows the | |
540 ex_cmds.c file. A ">>" marker will appear where the breakpoint was set. The | |
541 line where the debugger stopped is highlighted. You can now step through the | |
542 program. Let's use the mouse: click on the "Next" button in the window | |
543 toolbar. You will see the highlighting move as the debugger executes a line | |
544 of source code. | |
545 | |
546 Click "Next" a few times until the for loop is highlighted. Put the cursor on | |
547 the end of "eap->arg", then click "Eval" in the toolbar. You will see this | |
548 displayed: | |
549 "eap->arg": 0x555555e68855 "gui" ~ | |
550 This way you can inspect the value of local variables. You can also focus the | |
551 gdb window and use a "print" command, e.g.: > | |
552 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
|
553 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
|
554 mouse rests on text that can be evaluated by gdb. |
12559 | 555 |
556 Now go back to the source window and put the cursor on the first line after | |
557 the for loop, then type: > | |
558 :Break | |
559 You will see a ">>" marker appear, this indicates the new breakpoint. Now | |
560 click "Cont" in the toolbar and the code until the breakpoint will be | |
561 executed. | |
562 | |
563 You can type more advanced commands in the gdb window. For example, type: > | |
564 watch curbuf | |
565 Now click "Cont" in the toolbar (or type "cont" in the gdb window). Execution | |
566 will now continue until the value of "curbuf" changes, which is in do_ecmd(). | |
567 To remove this watchpoint again type in the gdb window: > | |
568 delete 3 | |
569 | |
570 You can see the stack by typing in the gdb window: > | |
571 where | |
572 Move through the stack frames, e.g. with: > | |
573 frame 3 | |
574 The source window will show the code, at the point where the call was made to | |
575 a deeper level. | |
576 | |
577 | |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
578 Stepping through code ~ |
12826 | 579 *termdebug-stepping* |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
580 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
|
581 - 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
|
582 - 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
|
583 - 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
|
584 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
|
585 - 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
|
586 - 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
|
587 - 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
|
588 - continue continue execution |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
589 |
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
|
590 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
|
591 `: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
|
592 `: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
|
593 |
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
|
594 `: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
|
595 `: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
|
596 |
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
|
597 `: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
|
598 `: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
|
599 `: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
|
600 `: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
|
601 `: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
|
602 |
13051 | 603 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
|
604 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
|
605 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
|
606 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
|
607 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
|
608 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
|
609 Eval `:Evaluate` |
13051 | 610 This way you can use the mouse to perform the most common commands. You need |
611 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
|
612 |
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
|
613 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
|
614 :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
|
615 |
12425
29d21591ad6b
patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents:
12411
diff
changeset
|
616 |
29d21591ad6b
patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents:
12411
diff
changeset
|
617 Inspecting variables ~ |
12826 | 618 *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
|
619 `: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
|
620 `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
|
621 `: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
|
622 `:'<,'>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
|
623 |
29d21591ad6b
patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents:
12411
diff
changeset
|
624 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
|
625 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
|
626 |
29d21591ad6b
patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents:
12411
diff
changeset
|
627 |
29d21591ad6b
patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents:
12411
diff
changeset
|
628 Other commands ~ |
12826 | 629 *termdebug-commands* |
12425
29d21591ad6b
patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents:
12411
diff
changeset
|
630 :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
|
631 :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
|
632 |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
633 |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
634 Communication ~ |
12826 | 635 *termdebug-communication* |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
636 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
|
637 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
|
638 will break the debugger. |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
639 |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
640 |
12254 | 641 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
|
642 |
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
|
643 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
|
644 |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
645 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
|
646 invoking `:Termdebug`: > |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
647 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
|
648 < *gdb-version* |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
649 Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI |
12756
3b26420fc639
Long overdue runtime update.
Christian Brabandt <cb@256bit.org>
parents:
12559
diff
changeset
|
650 interface. This probably requires gdb version 7.12. if you get this error: |
3b26420fc639
Long overdue runtime update.
Christian Brabandt <cb@256bit.org>
parents:
12559
diff
changeset
|
651 Undefined command: "new-ui". Try "help".~ |
3b26420fc639
Long overdue runtime update.
Christian Brabandt <cb@256bit.org>
parents:
12559
diff
changeset
|
652 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
|
653 |
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
|
654 |
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
|
655 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
|
656 |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
657 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
|
658 - debugPC the current position |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
659 - debugBreakpoint a breakpoint |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
660 |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
661 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
|
662 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
|
663 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
|
664 |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
665 When 'background' is "dark": |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
666 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
|
667 hi debugBreakpoint term=reverse ctermbg=red guibg=red |
12254 | 668 |
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
|
669 |
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
|
670 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
|
671 |
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
|
672 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
|
673 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
|
674 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
|
675 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
|
676 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
|
677 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
|
678 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
|
679 |
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
|
680 |
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
|
681 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
|
682 |
12455
85ddf8e00595
patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents:
12425
diff
changeset
|
683 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
|
684 vertical split: > |
85ddf8e00595
patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents:
12425
diff
changeset
|
685 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
|
686 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
|
687 when quitting the debugger. |
12559 | 688 If g:termdebug_wide is set and &Columns is already larger than |
689 g:termdebug_wide then a vertical split will be used without changing &columns. | |
690 Set it to 1 to get a vertical split without every changing &columns (useful | |
691 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
|
692 |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
693 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
694 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
695 vim:tw=78:ts=8:ft=help:norl: |