Mercurial > vim
annotate runtime/doc/terminal.txt @ 11621:b8299e742f41 v8.0.0693
patch 8.0.0693: no terminal emulator support
commit https://github.com/vim/vim/commit/e4f25e4a8db2c8a8a71a4ba2a68540b3ab341e42
Author: Bram Moolenaar <Bram@vim.org>
Date: Fri Jul 7 11:54:15 2017 +0200
patch 8.0.0693: no terminal emulator support
Problem: No terminal emulator support. Cannot properly run commands in the
GUI. Cannot run a job interactively with an ssh connection.
Solution: Very early implementation of the :terminal command. Includes
libvterm converted to ANSI C. Many parts still missing.
author | Christian Brabandt <cb@256bit.org> |
---|---|
date | Fri, 07 Jul 2017 12:00:04 +0200 |
parents | |
children | 49c12c93abf3 |
rev | line source |
---|---|
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
1 *terminal.txt* For Vim version 8.0. Last change: 2017 Jul 04 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
2 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
3 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
4 VIM REFERENCE MANUAL by Bram Moolenaar |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
5 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
6 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
7 Terminal window support *terminal* |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
8 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
9 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
10 WARNING: THIS IS ONLY PARTLY IMPLEMENTED, ANYTHING CAN STILL CHANGE |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
11 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
12 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
13 1. Basic use |terminal-use| |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
14 2. Remote testing |terminal-testing| |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
15 3. Debugging |terminal-debug| |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
16 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
17 {Vi does not have any of these commands} |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
18 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
19 ============================================================================== |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
20 1. Basic use *terminal-use* |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
21 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
22 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
|
23 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
|
24 :term bash |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
25 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
26 Or to run a debugger: > |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
27 :term gdb vim |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
28 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
29 The job runs asynchronously from Vim, the window will be updated to show |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
30 output from the job, also while editing in any other window. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
31 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
32 When the keyboard focus is in the terminal window, typed keys will be send to |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
33 the job. This uses a pty when possible. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
34 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
35 Navigate between windows with CTRL-W commands (and mouse). |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
36 E.g. CTRL-W CTRL-W moves focus to the next window. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
37 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
38 Option 'termkey' |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
39 Specify key for Vim command in terminal window. local to window. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
40 Default is CTRL-W. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
41 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
42 Option 'termsize' |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
43 Specify terminal size. Local to window. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
44 When empty the terminal gets the size from the window. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
45 When set (e.g., "24x80") the terminal size is fixed. If the window is smaller |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
46 only the top-left part is displayed. (TODO: scrolling?) |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
47 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
48 Syntax ~ |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
49 *:ter* *:terminal* |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
50 :terminal[!] [command] Open a new terminal window. |
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 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
|
53 the input and output to the terminal. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
54 If [command] is not given the 'shell' option is used. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
55 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
56 A new buffer will be created, using [command] or |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
57 'shell' as the name. If a buffer by this name already |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
58 exists a number is added in parenthesis. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
59 E.g. if "gdb" exists the second terminal buffer will |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
60 use "gdb (1)". |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
61 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
62 The window can be closed, in which case the buffer |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
63 becomes hidden. The command will not be stopped. The |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
64 `:buffer` command can be used to turn the current |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
65 window into a terminal window, using the existing |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
66 buffer. If there are unsaved changes this fails, use |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
67 ! to force, as usual. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
68 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
69 Resizing ~ |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
70 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
71 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
|
72 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
73 1. The 'termsize' option is empty: The terminal size follows the window size. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
74 The minimal size is 2 screen lines with 10 cells. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
75 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
76 2. The 'termsize' option is "rows*cols", where "rows" is the minimal number of |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
77 screen rows and "cols" is the minial number of cells. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
78 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
79 3. The 'termsize' option is "rowsXcols" (where the x is upper or lower case). |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
80 The terminal size is fixed to the specified number of screen lines and |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
81 cells. If the window is bigger there will be unused empty space. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
82 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
83 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
|
84 be seen (the lower-left part). |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
85 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
86 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
|
87 terminal. |term_setsize()| can be used only when in the first or second mode, |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
88 not when 'termsize' is "rowsXcols". |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
89 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
90 ============================================================================== |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
91 2. Remote testing *terminal-testing* |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
92 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
93 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
|
94 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
|
95 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
|
96 inspects the resulting screen state. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
97 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
98 Functions ~ |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
99 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
100 term_sendkeys() send keystrokes to a terminal |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
101 term_wait() wait for screen to be updated |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
102 term_scrape() inspect terminal screen |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
103 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
104 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
105 ============================================================================== |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
106 3. Debugging *terminal-debug* |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
107 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
108 The Terminal debugging plugin can be used to debug a program with gdb and view |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
109 the source code in a Vim window. For example: > |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
110 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
111 :TermDebug vim |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
112 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
113 This opens three windows: |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
114 - A terminal window in which "gdb vim" is executed. Here you can directly |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
115 interact with gdb. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
116 - A terminal window for the executed program. When "run" is used in gdb the |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
117 program I/O will happen in this window, so that it does not interfere with |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
118 controlling gdb. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
119 - A normal Vim window used to show the source code. When gdb jumps to a |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
120 source file location this window will display the code, if possible. Values |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
121 of variables can be inspected, breakpoints set and cleared, etc. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
122 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
123 This uses two terminal windows. To open the gdb window: > |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
124 :term gdb [arguments] |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
125 To open the terminal to run the tested program |term_open()| is used. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
126 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
127 TODO |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
128 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
129 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
130 vim:tw=78:ts=8:ft=help:norl: |