Mercurial > vim
annotate runtime/doc/terminal.txt @ 16505:28e3ba82d8c8 v8.1.1256
patch 8.1.1256: cannot navigate through errors relative to the cursor
commit https://github.com/vim/vim/commit/3ff33114d70fc0f7e9c3187c5fec9028f6499cf3
Author: Bram Moolenaar <Bram@vim.org>
Date: Fri May 3 21:56:35 2019 +0200
patch 8.1.1256: cannot navigate through errors relative to the cursor
Problem: Cannot navigate through errors relative to the cursor.
Solution: Add :cabove, :cbelow, :labove and :lbelow. (Yegappan Lakshmanan,
closes #4316)
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Fri, 03 May 2019 22:00:06 +0200 |
parents | dc766e1b0c95 |
children | 0e473e9e70c2 |
rev | line source |
---|---|
16023 | 1 *terminal.txt* For Vim version 8.1. Last change: 2019 Feb 25 |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
2 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
3 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
4 VIM REFERENCE MANUAL by Bram Moolenaar |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
5 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
6 |
13963 | 7 Terminal window support *terminal* *terminal-window* |
11621
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| |
14123 | 22 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
|
23 Special keys |terminal-special-keys| |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
24 Unix |terminal-unix| |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
25 MS-Windows |terminal-ms-windows| |
13535
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
26 2. Terminal communication |terminal-communication| |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
27 Vim to job: term_sendkeys() |terminal-to-job| |
13575
4df23d9bad47
patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents:
13563
diff
changeset
|
28 Job to Vim: JSON API |terminal-api| |
13535
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
29 Using the client-server feature |terminal-client-server| |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
30 3. Remote testing |terminal-testing| |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
31 4. Diffing screen dumps |terminal-diff| |
13304
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
32 Writing a screen dump test for Vim |terminal-dumptest| |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
33 Creating a screen dump |terminal-screendump| |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
34 Comparing screen dumps |terminal-diffscreendump| |
13535
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
35 5. Debugging |terminal-debug| |
13304
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
36 Starting |termdebug-starting| |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
37 Example session |termdebug-example| |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
38 Stepping through code |termdebug-stepping| |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
39 Inspecting variables |termdebug-variables| |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
40 Other commands |termdebug-commands| |
14107
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
41 Prompt mode |termdebug-prompt| |
13304
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
42 Communication |termdebug-communication| |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
43 Customizing |termdebug-customizing| |
11621
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 {Vi does not have any of these commands} |
12254 | 46 {only available when compiled with the |+terminal| feature} |
15878 | 47 The terminal feature requires the |+job| and |+channel| features. |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
48 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
49 ============================================================================== |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
50 1. Basic use *terminal-use* |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
51 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
52 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
|
53 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
|
54 :term bash |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
55 |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
56 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
|
57 :term make myprogram |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
58 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
59 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
|
60 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
|
61 |
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
|
62 |
11814
d3d0db111d17
patch 8.0.0787: cannot send CTRL-W command to terminal job
Christian Brabandt <cb@256bit.org>
parents:
11774
diff
changeset
|
63 Typing ~ |
12457
dfb8254aa735
patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents:
12455
diff
changeset
|
64 *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
|
65 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
|
66 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
|
67 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
|
68 |
16023 | 69 *t_CTRL-W_CTRL-W* *t_CTRL-W_:* |
11866
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
70 CTRL-W 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
|
71 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
|
72 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
|
73 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
|
74 |
16023 | 75 Special in the terminal window: *t_CTRL-W_.* *t_CTRL-W_N* |
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
|
76 CTRL-W . send a CTRL-W to the job in the terminal |
13668
6a84e3d2b810
patch 8.0.1706: cannot sent CTRL- to a terminal window
Christian Brabandt <cb@256bit.org>
parents:
13626
diff
changeset
|
77 CTRL-W CTRL-\ send a CTRL-\ 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
|
78 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
|
79 CTRL-\ CTRL-N go to Terminal-Normal mode, see |Terminal-mode| |
16023 | 80 CTRL-W " {reg} paste register {reg} *t_CTRL-W_quote* |
11914 | 81 Also works with the = register to insert the result of |
82 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
|
83 CTRL-W CTRL-C ends the job, see below |t_CTRL-W_CTRL-C| |
16023 | 84 CTRL-W gt go to next tabpage, same as `gt` *t_CTRL-W_gt* |
85 CTRL-W gT go to previous tabpage, same as `gT` *t_CTRL-W_gT* | |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
86 |
13735 | 87 See option 'termwinkey' for specifying another key instead of CTRL-W that |
88 will work like CTRL-W. However, typing 'termwinkey' twice sends 'termwinkey' | |
89 to the job. For example: | |
90 'termwinkey' CTRL-W move focus to the next window | |
91 'termwinkey' : enter an Ex command | |
92 'termwinkey' 'termwinkey' send 'termwinkey' to the job in the terminal | |
14109
279465096a16
patch 8.1.0072: use of 'termwinkey' is inconsistent
Christian Brabandt <cb@256bit.org>
parents:
14107
diff
changeset
|
93 'termwinkey' . send 'termwinkey' to the job in the terminal |
279465096a16
patch 8.1.0072: use of 'termwinkey' is inconsistent
Christian Brabandt <cb@256bit.org>
parents:
14107
diff
changeset
|
94 'termwinkey' CTRL-\ send a CTRL-\ to the job in the terminal |
13735 | 95 'termwinkey' N go to terminal Normal mode, see below |
16023 | 96 'termwinkey' CTRL-N same as CTRL-W N |t_CTRL-W_N| |
97 'termwinkey' CTRL-C same as CTRL-W CTRL-C |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
|
98 *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
|
99 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
|
100 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
|
101 *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
|
102 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
|
103 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
|
104 |
b80c0172d1a8
patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents:
12064
diff
changeset
|
105 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
|
106 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
|
107 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
|
108 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
|
109 |
12457
dfb8254aa735
patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents:
12455
diff
changeset
|
110 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
|
111 These are defined like any mapping, but apply only when typing keys that are |
13482
9eebe457eb3c
Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents:
13476
diff
changeset
|
112 sent to the job running in the terminal. For example, to make F1 switch |
12559 | 113 to Terminal-Normal mode: > |
13482
9eebe457eb3c
Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents:
13476
diff
changeset
|
114 tnoremap <F1> <C-W>N |
9eebe457eb3c
Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents:
13476
diff
changeset
|
115 You can use Esc, but you need to make sure it won't cause other keys to |
15131 | 116 break (cursor keys start with an Esc, so they may break): > |
12559 | 117 tnoremap <Esc> <C-W>N |
13482
9eebe457eb3c
Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents:
13476
diff
changeset
|
118 set notimeout ttimeout timeoutlen=100 |
9eebe457eb3c
Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents:
13476
diff
changeset
|
119 |
14952
405309f9dd13
patch 8.1.0487: no menus specifically for the terminal window
Bram Moolenaar <Bram@vim.org>
parents:
14695
diff
changeset
|
120 You can also create menus similar to terminal mode mappings, but you have to |
405309f9dd13
patch 8.1.0487: no menus specifically for the terminal window
Bram Moolenaar <Bram@vim.org>
parents:
14695
diff
changeset
|
121 use |:tlmenu| instead of |:tmenu|. |
405309f9dd13
patch 8.1.0487: no menus specifically for the terminal window
Bram Moolenaar <Bram@vim.org>
parents:
14695
diff
changeset
|
122 |
12756
3b26420fc639
Long overdue runtime update.
Christian Brabandt <cb@256bit.org>
parents:
12559
diff
changeset
|
123 < *options-in-terminal* |
12559 | 124 After opening the terminal window and setting 'buftype' to "terminal" the |
14123 | 125 TerminalOpen autocommand event is triggered. This makes it possible to set |
12559 | 126 options specifically for the window and buffer. Example: > |
14123 | 127 au TerminalOpen * if &buftype == 'terminal' | setlocal bufhidden=hide | endif |
128 The <abuf> is set to the terminal buffer, but if there is no window (hidden | |
129 terminal) then setting options will happen in the wrong buffer, therefore the | |
130 check for &buftype in the example. | |
12457
dfb8254aa735
patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents:
12455
diff
changeset
|
131 |
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
|
132 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
|
133 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
|
134 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
|
135 |
11814
d3d0db111d17
patch 8.0.0787: cannot send CTRL-W command to terminal job
Christian Brabandt <cb@256bit.org>
parents:
11774
diff
changeset
|
136 |
12160
b80c0172d1a8
patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents:
12064
diff
changeset
|
137 Size and color ~ |
12826 | 138 *terminal-size-color* |
13735 | 139 See option 'termwinsize' for controlling the size of the terminal window. |
11659
49c12c93abf3
Updated runtime files and translations.
Christian Brabandt <cb@256bit.org>
parents:
11621
diff
changeset
|
140 (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
|
141 |
12455
85ddf8e00595
patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents:
12425
diff
changeset
|
142 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
|
143 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
|
144 |
85ddf8e00595
patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents:
12425
diff
changeset
|
145 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
|
146 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
|
147 |
13100
656ab57d1ddc
update a few runtime files
Christian Brabandt <cb@256bit.org>
parents:
13051
diff
changeset
|
148 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
|
149 example: > |
12455
85ddf8e00595
patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents:
12425
diff
changeset
|
150 hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue |
13626
ab89131d30e0
patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents:
13592
diff
changeset
|
151 < |
ab89131d30e0
patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents:
13592
diff
changeset
|
152 *g:terminal_ansi_colors* |
13735 | 153 In GUI mode or with 'termguicolors', the 16 ANSI colors used by default in new |
13626
ab89131d30e0
patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents:
13592
diff
changeset
|
154 terminal windows may be configured using the variable |
ab89131d30e0
patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents:
13592
diff
changeset
|
155 `g:terminal_ansi_colors`, which should be a list of 16 color names or |
ab89131d30e0
patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents:
13592
diff
changeset
|
156 hexadecimal color codes, similar to those accepted by |highlight-guifg|. When |
ab89131d30e0
patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents:
13592
diff
changeset
|
157 not using GUI colors, the terminal window always uses the 16 ANSI colors of |
ab89131d30e0
patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents:
13592
diff
changeset
|
158 the underlying terminal. |
ab89131d30e0
patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents:
13592
diff
changeset
|
159 The |term_setansicolors()| function can be used to change the colors, and |
ab89131d30e0
patch 8.0.1685: can't set ANSI colors of a terminal window
Christian Brabandt <cb@256bit.org>
parents:
13592
diff
changeset
|
160 |term_getansicolors()| to get the currently used colors. |
12160
b80c0172d1a8
patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents:
12064
diff
changeset
|
161 |
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
|
162 |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
163 Syntax ~ |
11774
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
164 |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
165 :[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
|
166 Open a new terminal window. |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
167 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
168 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
|
169 the input and output to the terminal. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
170 If [command] is not given the 'shell' option is used. |
12254 | 171 if [command] is NONE no job is started, the pty of the |
172 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
|
173 |
13476
d130044d4f1f
patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents:
13438
diff
changeset
|
174 If [command] is missing the default behavior is to |
d130044d4f1f
patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents:
13438
diff
changeset
|
175 close the terminal when the shell exits. This can be |
d130044d4f1f
patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents:
13438
diff
changeset
|
176 changed with the ++noclose argument. |
d130044d4f1f
patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents:
13438
diff
changeset
|
177 If [command] is present the default behavior is to |
d130044d4f1f
patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents:
13438
diff
changeset
|
178 keep the terminal open in Terminal-Normal mode. This |
d130044d4f1f
patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents:
13438
diff
changeset
|
179 can be changed with the ++close argument. |
d130044d4f1f
patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents:
13438
diff
changeset
|
180 |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
181 A new buffer will be created, using [command] or |
11914 | 182 'shell' as the name, prefixed with a "!". If a buffer |
183 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
|
184 parentheses. E.g. if "gdb" exists the second terminal |
11914 | 185 buffer will use "!gdb (1)". |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
186 |
12192
6947d5bcf57f
patch 8.0.0976: cannot send lines to a terminal job
Christian Brabandt <cb@256bit.org>
parents:
12160
diff
changeset
|
187 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
|
188 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
|
189 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
|
190 ++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
|
191 |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
192 *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
|
193 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
|
194 ++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
|
195 automatically when the job terminates. |
13476
d130044d4f1f
patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents:
13438
diff
changeset
|
196 ++noclose The terminal window will NOT close |
d130044d4f1f
patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents:
13438
diff
changeset
|
197 automatically when the job terminates. |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
198 ++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
|
199 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
|
200 Note that this can be interruptive. |
13476
d130044d4f1f
patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents:
13438
diff
changeset
|
201 The last of ++close, ++noclose and ++open |
d130044d4f1f
patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents:
13438
diff
changeset
|
202 matters and rules out earlier arguments. |
d130044d4f1f
patch 8.0.1612: need to close terminal after shell stopped
Christian Brabandt <cb@256bit.org>
parents:
13438
diff
changeset
|
203 |
12064
407a475c67fd
patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents:
12031
diff
changeset
|
204 ++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
|
205 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
|
206 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
|
207 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
|
208 ++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
|
209 no window will be used. |
13437 | 210 ++norestore Do not include this terminal window |
211 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
|
212 ++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
|
213 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
|
214 |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
|
215 ++rows={height} Use {height} for the terminal window |
13125 | 216 height. If the terminal uses the full |
217 Vim height (no window above or below | |
14006 | 218 the terminal window) the command line |
13125 | 219 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
|
220 ++cols={width} Use {width} for the terminal window |
13125 | 221 width. If the terminal uses the full |
222 Vim width (no window left or right of | |
223 the terminal window) this value is | |
224 ignored. | |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
225 ++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
|
226 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
|
227 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
|
228 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
|
229 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
|
230 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
|
231 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
|
232 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
|
233 e.g. "<C-Z>" for CTRL-Z. |
15746
c017195b121b
patch 8.1.0880: MS-Windows: inconsistent selection of winpty/conpty
Bram Moolenaar <Bram@vim.org>
parents:
15729
diff
changeset
|
234 ++type={pty} (MS-Windows only): Use {pty} as the |
c017195b121b
patch 8.1.0880: MS-Windows: inconsistent selection of winpty/conpty
Bram Moolenaar <Bram@vim.org>
parents:
15729
diff
changeset
|
235 virtual console. See 'termwintype' |
c017195b121b
patch 8.1.0880: MS-Windows: inconsistent selection of winpty/conpty
Bram Moolenaar <Bram@vim.org>
parents:
15729
diff
changeset
|
236 for the values. |
c017195b121b
patch 8.1.0880: MS-Windows: inconsistent selection of winpty/conpty
Bram Moolenaar <Bram@vim.org>
parents:
15729
diff
changeset
|
237 |
12064
407a475c67fd
patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents:
12031
diff
changeset
|
238 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
|
239 function. |
14637 | 240 If you want to split the window vertically, use: > |
241 :vertical terminal | |
242 < Or short: > | |
243 :vert ter | |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
244 |
13438
33eea5ce5415
patch 8.0.1593: :qall never exits with an active terminal window
Christian Brabandt <cb@256bit.org>
parents:
13437
diff
changeset
|
245 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
|
246 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
|
247 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
|
248 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
|
249 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
|
250 :term ++kill=term tail -f /tmp/log |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
251 |
12267
e3bde71afff0
patch 8.0.1013: terminal window behaves different from a buffer with changes
Christian Brabandt <cb@256bit.org>
parents:
12254
diff
changeset
|
252 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
|
253 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
|
254 `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
|
255 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
|
256 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
|
257 |
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
|
258 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
|
259 `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
|
260 |
e3bde71afff0
patch 8.0.1013: terminal window behaves different from a buffer with changes
Christian Brabandt <cb@256bit.org>
parents:
12254
diff
changeset
|
261 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
|
262 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
|
263 current window into a terminal window. If there are unsaved changes this |
14006 | 264 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
|
265 |
407a475c67fd
patch 8.0.0912: cannot run a job in a hidden terminal
Christian Brabandt <cb@256bit.org>
parents:
12031
diff
changeset
|
266 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
|
267 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
|
268 :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
|
269 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
|
270 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
|
271 |
12160
b80c0172d1a8
patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents:
12064
diff
changeset
|
272 *E947* *E948* |
11967
12833414cc02
patch 8.0.0864: cannot specify the name of a terminal
Christian Brabandt <cb@256bit.org>
parents:
11965
diff
changeset
|
273 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
|
274 cannot be quit easily, see |abandon|. |
11914 | 275 |
276 When the job has finished and no changes were made to the buffer: closing the | |
277 window will wipe out the buffer. | |
278 | |
279 Before changes can be made to a terminal buffer, the 'modifiable' option must | |
280 be set. This is only possible when the job has finished. At the first change | |
281 the buffer will become a normal buffer and the highlighting is removed. | |
282 You may want to change the buffer name with |:file| to be able to write, since | |
283 the buffer name will still be set to the command. | |
284 | |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
285 |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
286 Resizing ~ |
12826 | 287 *terminal-resizing* |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
288 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
|
289 |
13735 | 290 1. The 'termwinsize' option is empty: The terminal size follows the window |
291 size. The minimal size is 2 screen lines with 10 cells. | |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
292 |
13735 | 293 2. The 'termwinsize' option is "rows*cols", where "rows" is the minimal number |
294 of 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
|
295 |
13735 | 296 3. The 'termwinsize' option is "rowsXcols" (where the x is upper or lower |
297 case). The terminal size is fixed to the specified number of screen lines | |
298 and cells. If the window is bigger there will be unused empty space. | |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
299 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
300 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
|
301 be seen (the lower-left part). |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
302 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
303 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
|
304 terminal. |term_setsize()| can be used only when in the first or second mode, |
13735 | 305 not when 'termwinsize' is "rowsXcols". |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
306 |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
307 |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
308 Terminal-Job and Terminal-Normal mode ~ |
13680
c32e9628dc30
patch 8.0.1712: terminal scrollback is not limited
Christian Brabandt <cb@256bit.org>
parents:
13668
diff
changeset
|
309 *Terminal-mode* *Terminal-Job* |
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
|
310 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
|
311 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
|
312 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
|
313 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
|
314 |
13735 | 315 Use CTRL-W N (or 'termwinkey' N) to switch to Terminal-Normal mode. Now 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
|
316 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
|
317 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
|
318 |
12487
3f16cf18386c
patch 8.0.1123: cannot define a toolbar for a window
Christian Brabandt <cb@256bit.org>
parents:
12457
diff
changeset
|
319 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
|
320 |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
|
321 |
13680
c32e9628dc30
patch 8.0.1712: terminal scrollback is not limited
Christian Brabandt <cb@256bit.org>
parents:
13668
diff
changeset
|
322 It is not possible to enter Insert mode from Terminal-Job mode. |
c32e9628dc30
patch 8.0.1712: terminal scrollback is not limited
Christian Brabandt <cb@256bit.org>
parents:
13668
diff
changeset
|
323 |
c32e9628dc30
patch 8.0.1712: terminal scrollback is not limited
Christian Brabandt <cb@256bit.org>
parents:
13668
diff
changeset
|
324 *Terminal-Normal* *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
|
325 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
|
326 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
|
327 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
|
328 '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
|
329 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
|
330 |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
331 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
|
332 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
|
333 "(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
|
334 |
13680
c32e9628dc30
patch 8.0.1712: terminal scrollback is not limited
Christian Brabandt <cb@256bit.org>
parents:
13668
diff
changeset
|
335 When the job outputs lines in the terminal, such that the contents scrolls off |
c32e9628dc30
patch 8.0.1712: terminal scrollback is not limited
Christian Brabandt <cb@256bit.org>
parents:
13668
diff
changeset
|
336 the top, those lines are remembered and can be seen in Terminal-Normal mode. |
13735 | 337 The number of lines is limited by the 'termwinscroll' option. When going over |
13912 | 338 this limit, the first 10% of the scrolled lines are deleted and are lost. |
12160
b80c0172d1a8
patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents:
12064
diff
changeset
|
339 |
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
|
340 |
12254 | 341 Cursor style ~ |
12826 | 342 *terminal-cursor-style* |
12254 | 343 By default the cursor in the terminal window uses a not blinking block. The |
344 normal xterm escape sequences can be used to change the blinking state and the | |
345 shape. Once focus leaves the terminal window Vim will restore the original | |
346 cursor. | |
347 | |
348 An exception is when xterm is started with the "-bc" argument, or another way | |
349 that causes the cursor to blink. This actually means that the blinking flag | |
350 is inverted. Since Vim cannot detect this, the terminal window cursor | |
351 blinking will also be inverted. | |
352 | |
353 | |
13437 | 354 Session ~ |
355 *terminal-session* | |
356 A terminal window will be restored when using a session file, if possible and | |
357 wanted. | |
358 | |
359 If "terminal" was removed from 'sessionoptions' then no terminal windows will | |
360 be restored. | |
361 | |
362 If the job in the terminal was finished the window will not be restored. | |
363 | |
364 If the terminal can be restored, the command that was used to open it will be | |
365 used again. To change this use the |term_setrestore()| function. This can | |
366 also be used to not restore a specific terminal by setting the command to | |
367 "NONE". | |
368 | |
369 | |
12826 | 370 Special keys ~ |
371 *terminal-special-keys* | |
372 Since the terminal emulator simulates an xterm, only escape sequences that | |
373 both Vim and xterm recognize will be available in the terminal window. If you | |
374 want to pass on other escape sequences to the job running in the terminal you | |
375 need to set up forwarding. Example: > | |
376 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
|
377 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
|
378 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
|
379 return '' |
db9ffed7e1fc
patch 8.0.1293: setting a breakpoint in the terminal debugger sometimes fails
Christian Brabandt <cb@256bit.org>
parents:
12826
diff
changeset
|
380 endfunc |
12826 | 381 |
382 | |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
383 Unix ~ |
12826 | 384 *terminal-unix* |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
385 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
|
386 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
|
387 |
11914 | 388 Environment variables are used to pass information to the running job: |
13585
03224283bafc
patch 8.0.1665: when running a terminal from the GUI 'term' is not useful
Christian Brabandt <cb@256bit.org>
parents:
13575
diff
changeset
|
389 TERM the name of the terminal, from the 'term' option or |
03224283bafc
patch 8.0.1665: when running a terminal from the GUI 'term' is not useful
Christian Brabandt <cb@256bit.org>
parents:
13575
diff
changeset
|
390 $TERM in the GUI; falls back to "xterm" if it does not |
03224283bafc
patch 8.0.1665: when running a terminal from the GUI 'term' is not useful
Christian Brabandt <cb@256bit.org>
parents:
13575
diff
changeset
|
391 start with "xterm" |
11914 | 392 ROWS number of rows in the terminal initially |
393 LINES same as ROWS | |
394 COLUMNS number of columns in the terminal initially | |
395 COLORS number of colors, 't_Co' (256*256*256 in the GUI) | |
396 VIM_SERVERNAME v:servername | |
14063
f39150ec146e
patch 8.1.0049: shell cannot tell running in a terminal window
Christian Brabandt <cb@256bit.org>
parents:
14006
diff
changeset
|
397 VIM_TERMINAL v:version |
11914 | 398 |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
399 |
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
400 MS-Windows ~ |
12826 | 401 *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
|
402 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
|
403 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
|
404 window. |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
405 |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
406 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
|
407 |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
408 winpty.dll |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
409 winpty-agent.exe |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
410 |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
411 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
|
412 |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
413 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
|
414 |
12160
b80c0172d1a8
patch 8.0.0960: job in terminal does not get CTRL-C
Christian Brabandt <cb@256bit.org>
parents:
12064
diff
changeset
|
415 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
|
416 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
|
417 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
|
418 build. |
15844
63e71d195cee
patch 8.1.0929: no error when requesting ConPTY but it's not available
Bram Moolenaar <Bram@vim.org>
parents:
15746
diff
changeset
|
419 *ConPTY* *E982* |
15725
a3e2e7948ee4
patch 8.1.0870: Vim doesn't use the new ConPTY support in Windows 10
Bram Moolenaar <Bram@vim.org>
parents:
15131
diff
changeset
|
420 On more recent versions of MS-Windows 10 (beginning with the "October 2018 |
a3e2e7948ee4
patch 8.1.0870: Vim doesn't use the new ConPTY support in Windows 10
Bram Moolenaar <Bram@vim.org>
parents:
15131
diff
changeset
|
421 Update"), winpty is no longer required. On those versions, |:terminal| will use |
a3e2e7948ee4
patch 8.1.0870: Vim doesn't use the new ConPTY support in Windows 10
Bram Moolenaar <Bram@vim.org>
parents:
15131
diff
changeset
|
422 Windows' built-in support for hosting terminal applications, "ConPTY". When |
a3e2e7948ee4
patch 8.1.0870: Vim doesn't use the new ConPTY support in Windows 10
Bram Moolenaar <Bram@vim.org>
parents:
15131
diff
changeset
|
423 ConPTY is in use, there may be rendering artifacts regarding ambiguous-width |
15844
63e71d195cee
patch 8.1.0929: no error when requesting ConPTY but it's not available
Bram Moolenaar <Bram@vim.org>
parents:
15746
diff
changeset
|
424 characters. If you encounter any such issues, install "winpty". Until the |
63e71d195cee
patch 8.1.0929: no error when requesting ConPTY but it's not available
Bram Moolenaar <Bram@vim.org>
parents:
15746
diff
changeset
|
425 ConPTY problems have been fixed "winpty" will be preferred. |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
426 |
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
|
427 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
|
428 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
|
429 |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
430 ============================================================================== |
13535
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
431 2. Terminal communication *terminal-communication* |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
432 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
433 There are several ways to communicate with the job running in a terminal: |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
434 - Use |term_sendkeys()| to send text and escape sequences from Vim to the job. |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
435 - Use the JSON API to send encoded commands from the job to Vim. |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
436 - Use the |client-server| mechanism. This works on machines with an X server |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
437 and on MS-Windows. |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
438 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
439 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
440 Vim to job: term_sendkeys() ~ |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
441 *terminal-to-job* |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
442 This allows for remote controlling the job running in the terminal. It is a |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
443 one-way mechanism. The job can update the display to signal back to Vim. |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
444 For example, if a shell is running in a terminal, you can do: > |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
445 call term_sendkeys(buf, "ls *.java\<CR>") |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
446 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
447 This requires for the job to be in the right state where it will do the right |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
448 thing when receiving the keys. For the above example, the shell must be |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
449 waiting for a command to be typed. |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
450 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
451 For a job that was written for the purpose, you can use the JSON API escape |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
452 sequence in the other direction. E.g.: > |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
453 call term_sendkeys(buf, "\<Esc>]51;["response"]\x07") |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
454 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
455 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
456 Job to Vim: JSON API ~ |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
457 *terminal-api* |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
458 The job can send JSON to Vim, using a special escape sequence. The JSON |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
459 encodes a command that Vim understands. Example of such a message: > |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
460 <Esc>]51;["drop", "README.md"]<07> |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
461 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
462 The body is always a list, making it easy to find the end: ]<07>. |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
463 The <Esc>]51;msg<07> sequence is reserved by xterm for "Emacs shell", which is |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
464 similar to what we are doing here. |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
465 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
466 Currently supported commands: |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
467 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
468 call {funcname} {argument} |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
469 |
13547
87a9c1be0ae3
patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents:
13535
diff
changeset
|
470 Call a user defined function with {argument}. |
87a9c1be0ae3
patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents:
13535
diff
changeset
|
471 The function is called with two arguments: the buffer number |
87a9c1be0ae3
patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents:
13535
diff
changeset
|
472 of the terminal and {argument}, the decoded JSON argument. |
87a9c1be0ae3
patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents:
13535
diff
changeset
|
473 The function name must start with "Tapi_" to avoid |
87a9c1be0ae3
patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents:
13535
diff
changeset
|
474 accidentally calling a function not meant to be used for the |
14123 | 475 terminal API. |
13547
87a9c1be0ae3
patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents:
13535
diff
changeset
|
476 The user function should sanity check the argument. |
13535
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
477 The function can use |term_sendkeys()| to send back a reply. |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
478 Example in JSON: > |
13547
87a9c1be0ae3
patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents:
13535
diff
changeset
|
479 ["call", "Tapi_Impression", ["play", 14]] |
13535
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
480 < Calls a function defined like this: > |
13547
87a9c1be0ae3
patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents:
13535
diff
changeset
|
481 function Tapi_Impression(bufnum, arglist) |
13535
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
482 if len(a:arglist) == 2 |
13547
87a9c1be0ae3
patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents:
13535
diff
changeset
|
483 echomsg "impression " . a:arglist[0] |
87a9c1be0ae3
patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents:
13535
diff
changeset
|
484 echomsg "count " . a:arglist[1] |
13535
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
485 endif |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
486 endfunc |
13547
87a9c1be0ae3
patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents:
13535
diff
changeset
|
487 < Output from `:echo` may be erased by a redraw, use `:echomsg` |
87a9c1be0ae3
patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents:
13535
diff
changeset
|
488 to be able to see it with `:messages`. |
87a9c1be0ae3
patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents:
13535
diff
changeset
|
489 |
13575
4df23d9bad47
patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents:
13563
diff
changeset
|
490 drop {filename} [options] |
13535
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
491 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
492 Let Vim open a file, like the `:drop` command. If {filename} |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
493 is already open in a window, switch to that window. Otherwise |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
494 open a new window to edit {filename}. |
13857 | 495 Note that both the job and Vim may change the current |
496 directory, thus it's best to use the full path. | |
13575
4df23d9bad47
patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents:
13563
diff
changeset
|
497 |
4df23d9bad47
patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents:
13563
diff
changeset
|
498 [options] is only used when opening a new window. If present, |
4df23d9bad47
patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents:
13563
diff
changeset
|
499 it must be a Dict. Similarly to |++opt|, These entries are recognized: |
4df23d9bad47
patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents:
13563
diff
changeset
|
500 "ff" file format: "dos", "mac" or "unix" |
4df23d9bad47
patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents:
13563
diff
changeset
|
501 "fileformat" idem |
4df23d9bad47
patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents:
13563
diff
changeset
|
502 "enc" overrides 'fileencoding' |
4df23d9bad47
patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents:
13563
diff
changeset
|
503 "encoding" idem |
4df23d9bad47
patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents:
13563
diff
changeset
|
504 "bin" sets 'binary' |
4df23d9bad47
patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents:
13563
diff
changeset
|
505 "binary" idem |
4df23d9bad47
patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents:
13563
diff
changeset
|
506 "nobin" resets 'binary' |
4df23d9bad47
patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents:
13563
diff
changeset
|
507 "nobinary" idem |
4df23d9bad47
patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents:
13563
diff
changeset
|
508 "bad" specifies behavior for bad characters, see |
4df23d9bad47
patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents:
13563
diff
changeset
|
509 |++bad| |
4df23d9bad47
patch 8.0.1660: the terminal API "drop" command doesn't support options
Christian Brabandt <cb@256bit.org>
parents:
13563
diff
changeset
|
510 |
13535
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
511 Example in JSON: > |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
512 ["drop", "path/file.txt", {"ff": "dos"}] |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
513 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
514 A trick to have Vim send this escape sequence: > |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
515 exe "set t_ts=\<Esc>]51; t_fs=\x07" |
13547
87a9c1be0ae3
patch 8.0.1647: terminal API may call any user function
Christian Brabandt <cb@256bit.org>
parents:
13535
diff
changeset
|
516 let &titlestring = '["call","Tapi_TryThis",["hello",123]]' |
13535
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
517 redraw |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
518 set t_ts& t_fs& |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
519 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
520 Rationale: Why not allow for any command or expression? Because that might |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
521 create a security problem. |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
522 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
523 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
524 Using the client-server feature ~ |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
525 *terminal-client-server* |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
526 This only works when v:servername is not empty. If needed you can set it, |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
527 before opening the terminal, with: > |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
528 call remote_startserver('vim-server') |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
529 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
530 $VIM_SERVERNAME is set in the terminal to pass on the server name. |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
531 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
532 In the job you can then do something like: > |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
533 vim --servername $VIM_SERVERNAME --remote +123 some_file.c |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
534 This will open the file "some_file.c" and put the cursor on line 123. |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
535 |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
536 ============================================================================== |
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
537 3. Remote testing *terminal-testing* |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
538 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
539 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
|
540 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
|
541 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
|
542 inspects the resulting screen state. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
543 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
544 Functions ~ |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
545 |
14249
4543777545a3
Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents:
14126
diff
changeset
|
546 |term_sendkeys()| send keystrokes to a terminal (not subject to tmap) |
4543777545a3
Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents:
14126
diff
changeset
|
547 |term_wait()| wait for screen to be updated |
4543777545a3
Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents:
14126
diff
changeset
|
548 |term_scrape()| inspect terminal screen |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
549 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
550 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
551 ============================================================================== |
13535
e9ffb5b35266
patch 8.0.1641: job in terminal can't communicate with Vim
Christian Brabandt <cb@256bit.org>
parents:
13482
diff
changeset
|
552 4. Diffing screen dumps *terminal-diff* |
13304
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
553 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
554 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
|
555 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
|
556 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
|
557 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
|
558 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
559 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
|
560 Vim screen size, font and other properties do not matter. Therefore this |
13482
9eebe457eb3c
Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents:
13476
diff
changeset
|
561 mechanism is portable across systems. A conventional screenshot would reflect |
13304
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
562 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
|
563 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
564 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
565 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
|
566 *terminal-dumptest* |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
567 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
|
568 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
|
569 - 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
|
570 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
|
571 - 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
|
572 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
|
573 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
|
574 command. |
14249
4543777545a3
Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents:
14126
diff
changeset
|
575 - Send any commands to Vim using |term_sendkeys()|. For example: > |
13304
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
576 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
|
577 - 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
|
578 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
|
579 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
|
580 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
|
581 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
|
582 - 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
|
583 - 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
|
584 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
585 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
|
586 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
|
587 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
|
588 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
589 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
|
590 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
|
591 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
|
592 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
593 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
|
594 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
|
595 reference: > |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
596 :!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
|
597 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
598 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
599 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
|
600 *terminal-screendump* |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
601 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
602 To create the screen dump, run Vim (or any other program) in a terminal and |
14249
4543777545a3
Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents:
14126
diff
changeset
|
603 make it show the desired state. Then use the |term_dumpwrite()| function to |
13304
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
604 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
|
605 :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
|
606 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
607 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
|
608 |
14249
4543777545a3
Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents:
14126
diff
changeset
|
609 You can view the screen dump with |term_dumpload()|: > |
13304
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
610 :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
|
611 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
612 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
|
613 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
|
614 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
|
615 :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
|
616 |
14249
4543777545a3
Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents:
14126
diff
changeset
|
617 To assert that the files are exactly the same use |assert_equalfile()|: > |
13304
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
618 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
|
619 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
620 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
|
621 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
622 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
623 Comparing screen dumps ~ |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
624 *terminal-diffscreendump* |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
625 |
14249
4543777545a3
Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents:
14126
diff
changeset
|
626 |assert_equalfile()| does not make it easy to see what is different. |
4543777545a3
Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents:
14126
diff
changeset
|
627 To spot the problem use |term_dumpdiff()|: > |
13304
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
628 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
|
629 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
630 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
|
631 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
|
632 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
|
633 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
|
634 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
635 You can usually see what differs in the second part. Use the 'ruler' to |
14695 | 636 relate it to the position in the first or second dump. Letters indicate the |
637 kind of difference: | |
638 X different character | |
639 > cursor in first but not in second | |
640 < cursor in second but not in first | |
641 w character width differs (single vs double width) | |
642 f foreground color differs | |
643 b background color differs | |
644 a attribute differs (bold, underline, reverse, etc.) | |
645 ? character missing in both | |
646 + character missing in first | |
647 - character missing in second | |
13304
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
648 |
13482
9eebe457eb3c
Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents:
13476
diff
changeset
|
649 Alternatively, press "s" to swap the first and second dump. Do this several |
13304
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
650 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
|
651 |
013c44d9dc09
patch 8.0.1526: no test using a screen dump yet
Christian Brabandt <cb@256bit.org>
parents:
13125
diff
changeset
|
652 ============================================================================== |
13963 | 653 5. Debugging *terminal-debug* *terminal-debugger* |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
654 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
655 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
|
656 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
|
657 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
|
658 |
14107
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
659 When the |+terminal| feature is missing, the plugin will use the "prompt" |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
660 buffer type, if possible. The running program will then use a newly opened |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
661 terminal window. See |termdebug-prompt| below for details. |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
662 |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
663 |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
664 Starting ~ |
12826 | 665 *termdebug-starting* |
12254 | 666 Load the plugin with this command: > |
667 packadd termdebug | |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
668 < *:Termdebug* |
14519 | 669 To start debugging use `:Termdebug` or `:TermdebugCommand` followed by the |
13706
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
670 command name, for example: > |
12559 | 671 :Termdebug vim |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
672 |
12254 | 673 This opens two windows: |
13051 | 674 |
12425
29d21591ad6b
patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents:
12411
diff
changeset
|
675 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
|
676 can directly interact with gdb. The buffer name is "!gdb". |
13051 | 677 |
12425
29d21591ad6b
patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents:
12411
diff
changeset
|
678 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
|
679 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
|
680 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
|
681 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
|
682 |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
683 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
|
684 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
|
685 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
|
686 |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
687 If the buffer in the current window is modified, another window will be opened |
13706
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
688 to display the current gdb position. You can use `:Winbar` to add a window |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
689 toolbar there. |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
690 |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
691 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
|
692 the same as any command running in a terminal window. |
12254 | 693 |
12425
29d21591ad6b
patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents:
12411
diff
changeset
|
694 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
|
695 opened windows are closed. |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
696 |
13682
fc660a6ef37d
patch 8.0.1713: terminal debugger doesn't handle arguments
Christian Brabandt <cb@256bit.org>
parents:
13680
diff
changeset
|
697 Only one debugger can be active at a time. |
13706
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
698 *:TermdebugCommand* |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
699 If you want to give specific commands to the command being debugged, you can |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
700 use the `:TermdebugCommand` command followed by the command name and |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
701 additional parameters. > |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
702 :TermdebugCommand vim --clean -c ':set nu' |
13682
fc660a6ef37d
patch 8.0.1713: terminal debugger doesn't handle arguments
Christian Brabandt <cb@256bit.org>
parents:
13680
diff
changeset
|
703 |
13706
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
704 Both the `:Termdebug` and `:TermdebugCommand` support an optional "!" bang |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
705 argument to start the command right away, without pausing at the gdb window |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
706 (and cursor will be in the debugged window). For example: > |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
707 :TermdebugCommand! vim --clean |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
708 |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
709 To attach gdb to an already running executable or use a core file, pass extra |
13682
fc660a6ef37d
patch 8.0.1713: terminal debugger doesn't handle arguments
Christian Brabandt <cb@256bit.org>
parents:
13680
diff
changeset
|
710 arguments. E.g.: > |
fc660a6ef37d
patch 8.0.1713: terminal debugger doesn't handle arguments
Christian Brabandt <cb@256bit.org>
parents:
13680
diff
changeset
|
711 :Termdebug vim core |
fc660a6ef37d
patch 8.0.1713: terminal debugger doesn't handle arguments
Christian Brabandt <cb@256bit.org>
parents:
13680
diff
changeset
|
712 :Termdebug vim 98343 |
fc660a6ef37d
patch 8.0.1713: terminal debugger doesn't handle arguments
Christian Brabandt <cb@256bit.org>
parents:
13680
diff
changeset
|
713 |
13706
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
714 If no argument is given, you'll end up in a gdb window, in which you need to |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
715 specify which command to run using e.g. the gdb `file` command. |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
716 |
12254 | 717 |
12559 | 718 Example session ~ |
12826 | 719 *termdebug-example* |
12559 | 720 Start in the Vim "src" directory and build Vim: > |
721 % make | |
722 Start Vim: > | |
723 % ./vim | |
724 Load the termdebug plugin and start debugging Vim: > | |
725 :packadd termdebug | |
726 :Termdebug vim | |
727 You should now have three windows: | |
728 source - where you started, has a window toolbar with buttons | |
729 gdb - you can type gdb commands here | |
730 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
|
731 |
12559 | 732 You can use CTRL-W CTRL-W or the mouse to move focus between windows. |
733 Put focus on the gdb window and type: > | |
734 break ex_help | |
735 run | |
736 Vim will start running in the program window. Put focus there and type: > | |
737 :help gui | |
738 Gdb will run into the ex_help breakpoint. The source window now shows the | |
14126
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
739 ex_cmds.c file. A red "1 " marker will appear in the signcolumn where the |
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
740 breakpoint was set. The line where the debugger stopped is highlighted. You |
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
741 can now step through the program. Let's use the mouse: click on the "Next" |
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
742 button in the window toolbar. You will see the highlighting move as the |
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
743 debugger executes a line of source code. |
12559 | 744 |
745 Click "Next" a few times until the for loop is highlighted. Put the cursor on | |
746 the end of "eap->arg", then click "Eval" in the toolbar. You will see this | |
747 displayed: | |
748 "eap->arg": 0x555555e68855 "gui" ~ | |
749 This way you can inspect the value of local variables. You can also focus the | |
750 gdb window and use a "print" command, e.g.: > | |
751 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
|
752 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
|
753 mouse rests on text that can be evaluated by gdb. |
12559 | 754 |
755 Now go back to the source window and put the cursor on the first line after | |
756 the for loop, then type: > | |
757 :Break | |
758 You will see a ">>" marker appear, this indicates the new breakpoint. Now | |
759 click "Cont" in the toolbar and the code until the breakpoint will be | |
760 executed. | |
761 | |
762 You can type more advanced commands in the gdb window. For example, type: > | |
763 watch curbuf | |
764 Now click "Cont" in the toolbar (or type "cont" in the gdb window). Execution | |
765 will now continue until the value of "curbuf" changes, which is in do_ecmd(). | |
766 To remove this watchpoint again type in the gdb window: > | |
767 delete 3 | |
768 | |
769 You can see the stack by typing in the gdb window: > | |
770 where | |
771 Move through the stack frames, e.g. with: > | |
772 frame 3 | |
773 The source window will show the code, at the point where the call was made to | |
774 a deeper level. | |
775 | |
776 | |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
777 Stepping through code ~ |
12826 | 778 *termdebug-stepping* |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
779 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
|
780 - 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
|
781 - 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
|
782 - 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
|
783 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
|
784 - 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
|
785 - 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
|
786 - 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
|
787 - continue continue execution |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
788 |
13706
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
789 *:Run* *:Arguments* |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
790 In the window showing the source code these commands can be used to control |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
791 gdb: |
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
|
792 `: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
|
793 `: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
|
794 |
13706
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
795 *:Break* set a breakpoint at the current line; a sign will be displayed |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
796 *: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
|
797 |
13706
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
798 *:Step* execute the gdb "step" command |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
799 *:Over* execute the gdb "next" command (`:Next` is a Vim command) |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
800 *:Finish* execute the gdb "finish" command |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
801 *:Continue* execute the gdb "continue" command |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
802 *: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
|
803 |
13051 | 804 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
|
805 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
|
806 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
|
807 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
|
808 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
|
809 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
|
810 Eval `:Evaluate` |
13051 | 811 This way you can use the mouse to perform the most common commands. You need |
812 to have the 'mouse' option set to enable mouse clicks. | |
13706
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
813 *:Winbar* |
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
|
814 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
|
815 :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
|
816 |
13592
a64485061f75
patch 8.0.1668: terminal debugger: can't re-open source code window
Christian Brabandt <cb@256bit.org>
parents:
13589
diff
changeset
|
817 If gdb stops at a source line and there is no window currently showing the |
a64485061f75
patch 8.0.1668: terminal debugger: can't re-open source code window
Christian Brabandt <cb@256bit.org>
parents:
13589
diff
changeset
|
818 source code, a new window will be created for the source code. This also |
a64485061f75
patch 8.0.1668: terminal debugger: can't re-open source code window
Christian Brabandt <cb@256bit.org>
parents:
13589
diff
changeset
|
819 happens if the buffer in the source code window has been modified and can't be |
a64485061f75
patch 8.0.1668: terminal debugger: can't re-open source code window
Christian Brabandt <cb@256bit.org>
parents:
13589
diff
changeset
|
820 abandoned. |
a64485061f75
patch 8.0.1668: terminal debugger: can't re-open source code window
Christian Brabandt <cb@256bit.org>
parents:
13589
diff
changeset
|
821 |
14126
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
822 Gdb gives each breakpoint a number. In Vim the number shows up in the sign |
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
823 column, with a red background. You can use these gdb commands: |
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
824 - info break list breakpoints |
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
825 - delete N delete breakpoint N |
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
826 You can also use the `:Clear` command if the cursor is in the line with the |
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
827 breakpoint, or use the "Clear breakpoint" right-click menu entry. |
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
828 |
12425
29d21591ad6b
patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents:
12411
diff
changeset
|
829 |
29d21591ad6b
patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents:
12411
diff
changeset
|
830 Inspecting variables ~ |
13706
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
831 *termdebug-variables* *:Evaluate* |
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
|
832 `: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
|
833 `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
|
834 `: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
|
835 `:'<,'>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
|
836 |
29d21591ad6b
patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents:
12411
diff
changeset
|
837 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
|
838 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
|
839 |
29d21591ad6b
patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents:
12411
diff
changeset
|
840 |
29d21591ad6b
patch 8.0.1092: terminal debugger can't evaluate expressions
Christian Brabandt <cb@256bit.org>
parents:
12411
diff
changeset
|
841 Other commands ~ |
12826 | 842 *termdebug-commands* |
13706
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
843 *:Gdb* jump to the gdb window |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
844 *:Program* jump to the window with the running program |
bfd9249f72e0
patch 8.0.1725: terminal debugger doesn't handle command arguments
Christian Brabandt <cb@256bit.org>
parents:
13682
diff
changeset
|
845 *:Source* jump to the window with the source code, create it if there |
13592
a64485061f75
patch 8.0.1668: terminal debugger: can't re-open source code window
Christian Brabandt <cb@256bit.org>
parents:
13589
diff
changeset
|
846 isn't one |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
847 |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
848 |
14107
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
849 Prompt mode ~ |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
850 *termdebug-prompt* |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
851 When the |+terminal| feature is not supported and on MS-Windows, gdb will run |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
852 in a buffer with 'buftype' set to "prompt". This works slightly differently: |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
853 - The gdb window will be in Insert mode while typing commands. Go to Normal |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
854 mode with <Esc>, then you can move around in the buffer, copy/paste, etc. |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
855 Go back to editing the gdb command with any command that starts Insert mode, |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
856 such as `a` or `i`. |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
857 - The program being debugged will run in a separate window. On MS-Windows |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
858 this is a new console window. On Unix, if the |+terminal| feature is |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
859 available a Terminal window will be opened to run the debugged program in. |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
860 |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
861 *termdebug_use_prompt* |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
862 Prompt mode can be used even when the |+terminal| feature is present with: > |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
863 let g:termdebug_use_prompt = 1 |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
864 |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
865 |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
866 Communication ~ |
12826 | 867 *termdebug-communication* |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
868 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
|
869 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
|
870 will break the debugger. |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
871 |
14126
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
872 Gdb has some weird behavior, the plugin does its best to work around that. |
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
873 For example, after typing "continue" in the gdb window a CTRL-C can be used to |
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
874 interrupt the running program. But after using the MI command |
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
875 "-exec-continue" pressing CTRL-C does not interrupt. Therefore you will see |
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
876 "continue" being used for the `:Continue` command, instead of using the |
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
877 communication channel. |
1ce45478cbf1
patch 8.1.0080: can't see the breakpoint number in the terminal debugger
Christian Brabandt <cb@256bit.org>
parents:
14123
diff
changeset
|
878 |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
879 |
12254 | 880 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
|
881 |
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
|
882 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
|
883 |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
884 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
|
885 invoking `:Termdebug`: > |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
886 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
|
887 < *gdb-version* |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
888 Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI |
13482
9eebe457eb3c
Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents:
13476
diff
changeset
|
889 interface. The "new-ui" command requires gdb version 7.12 or later. if you |
9eebe457eb3c
Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents:
13476
diff
changeset
|
890 get this error: |
12756
3b26420fc639
Long overdue runtime update.
Christian Brabandt <cb@256bit.org>
parents:
12559
diff
changeset
|
891 Undefined command: "new-ui". Try "help".~ |
3b26420fc639
Long overdue runtime update.
Christian Brabandt <cb@256bit.org>
parents:
12559
diff
changeset
|
892 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
|
893 |
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
|
894 |
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
|
895 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
|
896 |
12411
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
897 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
|
898 - debugPC the current position |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
899 - debugBreakpoint a breakpoint |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
900 |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
901 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
|
902 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
|
903 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
|
904 |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
905 When 'background' is "dark": |
5d4d744151c2
patch 8.0.1085: terminal debugger can't set breakpoints
Christian Brabandt <cb@256bit.org>
parents:
12311
diff
changeset
|
906 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
|
907 hi debugBreakpoint term=reverse ctermbg=red guibg=red |
12254 | 908 |
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
|
909 |
14107
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
910 Shorcuts *termdebug_shortcuts* |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
911 |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
912 You can define your own shortcuts (mappings) to control gdb, that can work in |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
913 any window, using the TermDebugSendCommand() function. Example: > |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
914 map ,w :call TermDebugSendCommand('where')<CR> |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
915 The argument is the gdb command. |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
916 |
274c9f1fbfd2
patch 8.1.0071: terminal debugger only works with the terminal feature
Christian Brabandt <cb@256bit.org>
parents:
14063
diff
changeset
|
917 |
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
|
918 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
|
919 |
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
|
920 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
|
921 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
|
922 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
|
923 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
|
924 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
|
925 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
|
926 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
|
927 |
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
|
928 |
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
|
929 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
|
930 |
12455
85ddf8e00595
patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents:
12425
diff
changeset
|
931 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
|
932 vertical split: > |
85ddf8e00595
patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents:
12425
diff
changeset
|
933 let g:termdebug_wide = 163 |
14249
4543777545a3
Updated runtime and language files.
Christian Brabandt <cb@256bit.org>
parents:
14126
diff
changeset
|
934 This will set &columns to 163 when `:Termdebug` is used. The value is restored |
12455
85ddf8e00595
patch 8.0.1107: terminal debugger jumps to non-existing file
Christian Brabandt <cb@256bit.org>
parents:
12425
diff
changeset
|
935 when quitting the debugger. |
14123 | 936 If g:termdebug_wide is set and &columns is already larger than |
12559 | 937 g:termdebug_wide then a vertical split will be used without changing &columns. |
938 Set it to 1 to get a vertical split without every changing &columns (useful | |
939 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
|
940 |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
941 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
942 |
14421 | 943 vim:tw=78:ts=8:noet:ft=help:norl: |