diff --git a/doc/terminal.jax b/doc/terminal.jax new file mode 100644 index 000000000..cee044a3b --- /dev/null +++ b/doc/terminal.jax @@ -0,0 +1,430 @@ +*terminal.txt* For Vim バージョン 8.0. Last change: 2017 Sep 14 + + + VIMリファレンスマニュアル by Bram Moolenaar + + +端末ウィンドウサポート *terminal* + + +WARNING: THIS IS ONLY PARTLY IMPLEMENTED, ANYTHING CAN STILL CHANGE + +端末機能はオプションなので、あなたのVimが対応しているかは次のコマンドを使って +確認できます: > + echo has('terminal') +結果が "1" ならば対応しています。 + + +1. 基本的な使い方 |terminal-use| +2. リモートテスト |terminal-testing| +3. デバッグ |terminal-debug| + +{Vi にはこれらのコマンドはありません} +{only: |+terminal| の機能は、コンパイル時に有効にされていなければ使えません} + +端末機能を使うには |+multi_byte|, |+job| そして |+channel| 機能が必要です。 + +============================================================================== +1. 基本的な使い方 *terminal-use* + +これは Vim のウィンドウ内で端末エミュレーターを実行する機能です。端末エミュ +レーターに接続すると1つのジョブが開始されます。例としてシェルを実行するならば +以下のようになります: > + :term bash + +またビルドコマンドを実行するにはこうなります: > + :term make myprogram + +ジョブはVimとは非同期的に動作し、他のウィンドウで編集中であってもジョブからの +出力は随時端末ウィンドウに反映されます。 + + +キー入力 ~ + *terminal-typing* +端末ウィンドウにキーボードのフォーカスがある時には、入力したキーはジョブに送ら +れます。これには可能ならば pty を使用します。端末ウィンドウ外をクリックすれ +ば、キーボードフォーカスを外に動かせます。 + +ウィンドウや他の CTRL-W コマンドを操作するために CTRL-W を使えます。例えば: + CTRL-W CTRL-W 次のウィンドウにフォーカスを移動する + CTRL-W : Exコマンドに入る +他のコマンドについては |CTRL-W| 参照してください。 + + +端末ウィンドウでの特別な操作: *CTRL-W_.* *CTRL-W_N* + CTRL-W . 端末内のジョブに CTRL-W を送る + CTRL-W N Terminal-Normal モードに移行, |Terminal-mode| を参照 + CTRL-\ CTRL-N Terminal-Normal モードに移行, |Terminal-mode| を参照 + CTRL-W " {reg} レジスタ {reg} の内容を貼り付け *CTRL-W_quote* + 式の評価結果を挿入するためのレジスタ = も機能する。 + CTRL-W CTRL-C ジョブを停止する, 下記の |t_CTRL-W_CTRL-C| を参照 + +CTRL-W の代わりに別のキーを使うにはオプション 'termkey' を参照してください。し +かし 'termkey' を2回タイプすると 'termkey' が job へ送信されます。例: + 'termkey' CTRL-W 次のウィンドウにフォーカスを移動する + 'termkey' : Exコマンドに入る + 'termkey' 'termkey' 端末内のジョブに 'termkey' を送信する + 'termkey' . 端末内のジョブに CTRL-W を送信する + 'termkey' N Terminal-Normal モードへ移行、以下を参照 + 'termkey' CTRL-N CTRL-W N と同じ + 'termkey' CTRL-C |t_CTRL-W_CTRL-C| と同じ + *t_CTRL-\_CTRL-N* +他のモードと同じように、ノーマルモードへ移行するための特別なキーの組み合わせで +ある CTRL-\ CTRL-N が利用できます。 + *t_CTRL-W_CTRL-C* +ジョブを強制停止するのに CTRL-W CTRL-C を使えます。MS-Windowsでは CTRL-BREAK +でも同様にジョブを停止できます。 + +CTRL-C を入力した場合、その効果は pty がどのように構成されているかに従います。 +シンプルなコマンドにおいては SIGINT がジョブに送られ、結果的にジョブが停止する +でしょう。中には SIGINT を無視するコマンドもあるでしょうし、また (Vim がそうし +ているように) CTRL-C をプログラム自身で取り扱うものもあるでしょう。 + +入力したキーを別のものに読み返させるには端末モードマッピング、詳細は |:tmap|を +使用してください。これはどのようなマッピングでも定義できますが、端末内で実行さ +れているジョブに送信されるキー入力にのみ作用します。 + + +サイズと色 ~ + +端末ウィンドウのサイズを制御するにはオプション 'termsize' を参照してください。 +(TODO: 端末がウィンドウよりも大きい場合にはスクロールすることを記述する) + +端末内のジョブは端末の色を変更できます。デフォルトの前景色及び背景色はVimの +Normal ハイライトグループにより決定されます。 + +カラー端末を開始する際に、背景に白と黒どちらの系統の色を使用するかは、オプショ +ン 'background' を用いて決定します。 + +異なる色を使う場合には Terminal ハイライトグループを利用できます: > + hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue + + +文法 ~ + +:[range]ter[minal] [options] [command] *:ter* *:terminal* + 新しい端末ウィンドウを開きます。 + + [command] が指定された場合、それをジョブとして実行し、 + 端末の入出力を接続します。 + [command] が指定されなかった場合、オプション 'shell' + を使用します。 + [command] が NONE の場合ジョブは開始されず、端末の pty + は gdb のようなコマンドによって利用できます。 + + 新しいバッファが作られ、 [command] もしくは 'shell' に + "!" が前置された名前が与えられます。すでに同じ名前の + バッファが存在する場合には、カッコに囲まれた番号が付与 + されます。例えば "gdb" が存在して2つ目の端末には "!gdb + (1)" という名前が使われます。 + + [range] が与えられた場合は、指定された範囲の行がジョブ + の入力として使われます。その際の端末ウィンドウではキー + 入力ができなくなります。MS-Windows においては以下の + ++eof オプションも参照してください。 + + コンマで分けられた2つの数字は "行数,桁数" のように利用 + されます。例えば `:24,80gdb` は 24 行かつ 80 桁の端末 + を開きます。しかし端末ウィンドウが Vim のウィンドウを + またがる場合には、垂直分割は起こさずに Vim のウィンド + ウの幅を利用します。 + *term++close* *term++open* + サポートされる [options] は以下の通り: + ++close ジョブが終了した際には自動的に端末ウィ + ンドウを閉じる。 + ++open ジョブが終了した際にウィンドウが表示さ + れていない場合に、ウィンドウを表示す + る。割り込み的に発生しうることに留意。 + ++curwin 現在のウィンドウで端末を開き、現在の + ウィンドウを分割しない。現在のバッファ + を放棄( |abandon| )できない場合は失敗 + する。 + ++hidden 端末を隠しバッファとして開く。ウィンド + ウは使用されない。 + ++rows={height} 端末ウィンドウの高さとして {height} を + 使う + ++cols={width} 端末ウィンドウの幅として {width} を使 + う + ++eof={text} [range] を使った場合: 最後の行を送信し + たあとに指定したテキストが送られる。空 + 白を含むことはできない。 CR が 1 つ付 + け加えられる。MS-Windows ではデフォル + トでは CTRL-D が送られる。 + 例: シェルには "++eof=exit" を、Python + には "++eof=exit()" を指定する。特殊 + コードが `:map` と同様に利用できる。 + 例: "" は CTRL-Z を示す。 + + + より詳細なオプションを使いたいならば |term_start()| 関 + 数を使ってください。 + +端末に関連付けられたバッファがアンロードもしくは削除された場合には、 +`job_stop(job, "kill")` を呼んだのと同じようにそのジョブが殺されます。 + +ジョブが実行され続けるとウィンドウはそのバッファが変更されたかのように振る舞い +ます。 `CTRL-W :quit` でウィンドウを閉じようとしても失敗します。 `CTRL-W :quit!` +を使うとジョブは終了します。ウィンドウのテキストは失われます。バッファは依然存 +在しますが、 `:buffer` でウィンドウに割り当てても空のバッファが表示されます。 + +`CTRL-W :close` で閉じようとしてもまた失敗します。 `CTRL-W :close!` はウィンド +ウを閉じ、バッファを隠し状態にします。 + +`CTRL-W :hide` を使うとジョブを実行したまま、端末ウィンドウを閉じバッファを隠 +し状態にできます。`:buffer` コマンドで現在のウィンドウを端末ウィンドウにするこ +とができます。未保存の変更があった場合にはこれは失敗しますが、通常と同じように +! で強制できます。 + +バックグラウンドジョブをウィンドウ無しで実行し、終了したらウィンドウに表示する +には、次のようにオプションを指定します: > + :term ++hidden ++open make +ウィンドウが予期せぬタイミングで開かれ、あなたが行っている操作に割り込む可能性 +があることに留意してください。 + + *E947* *E948* +ジョブが実行され続けると、バッファが変更されたとみなされ Vim を簡単には終了で +きなくなります。 |abandon| を参照してください。 + +ジョブが終了しバッファになんの変更も及ぼさなかった場合、そのウィンドウを閉じる +とバッファは削除されます。 + +端末バッファを変更するにはオプション 'modifiable' をセットする必要があります。 +これはジョブが終了した後にのみ行なえます。バッファを最初に変更した瞬間に普通の +バッファになりハイライトは削除されます。バッファを保存可能にするために |:file| +でバッファの名前を、コマンド名から変更することもできます。 + + +サイズ変更 ~ + +端末のサイズは3つのモードのいずれか1つで決まります: + +1. オプション 'termsize' が空の場合: 端末サイズはウィンドウのサイズに従う。最 + 小で2行、10桁。 + +2. オプション 'termsize' が "rows*cols" の場合、 "rows" を最小行数、 "cols" を + 最小桁数とする。 + +3. オプション 'termsize' が "rowsXcols" ("X" は大文字小文字を問わない) の場合: + 端末サイズは指定された行数と桁数で固定される。もしもウィンドウがそれよりも + 大きい場合には、使用されない空の領域ができる。 + +ウィンドウサイズが端末サイズよりも小さい場合、端末の一部の領域(左下に相当する +部分)のみが描画されます。 + +端末の現在のサイズを取得するのに関数 |term_getsize()| が使えます。 +|term_setsize()| は 1 か 2 のモードの時にだけ、すなわち 'termsize' が +"rowsXcols" 形式ではない時に使えます。 + + +Terminal-Job と Terminal-Normal モード ~ + *Terminal-mode* +ジョブが実行中には端末の内容はジョブの制御下にあります。それにはカーソルの位置 +も含まれます。入力したキーはジョブに送られます。端末の内容はいつでも更新されえ +ます。これを Terminal-Job モードと呼びます。 + +CTRL-W N (もしくは 'termkey' N) を入力すると Terminal-Normal モードに遷移しま +す。このモードでは端末ウィンドウのコンテンツはVimの制御下に置かれ、ジョブの出 +力は一時保留されます。 CTRL-\ CTRL-N でも同じようになります。 + +|tmap| のマッピングは Terminal-Job モードにおいて作用します。 +|term_sendkeys()| で送ったキーには tmap は適用されませんが、 +|feedkeys()| で送ったキーには適用されます。 + + *E946* +Terminal-Normal モードでは、Vimの普通のコマンドでカーソルを自由に動かせます。 +視覚的にテキストをマークしたり、テキストをヤンクしたり思いのままです。しかし +バッファの内容を変更することはできません。 'i' や 'a' など挿入モードを開始する +コマンドを使うと Terminal-Job モードに戻ります。結果としてウィンドウは端末のコ +ンテンツを反映させるために更新されます。 + +Terminal-Normal モードではステータスラインとウィンドウタイトルには +"(Terminal)" と表示されます。 Terminal-Normal モード中にジョブが終了してしまっ +た場合にはそれが "(Terminal-finished)" に変わります。 + +Terminal-Job モードから挿入モードに移る方法はありません。 + + +カーソルスタイル ~ + +デフォルトでは端末ウィンドウのカーソルには点滅しないブロックが使われます。カー +ソルの点滅状態や形を変更するのに、普通の xterm のエスケープシーケンスが使われ +ます。端末ウィンドウからフォーカスが外れる際に Vim は元々のカーソルを復元しま +す。 + +xterm を "-bc" 引数で起動した場合、または他の方法でカーソルの点滅を発生させた +場合、が1つの例外となります。それらにより点滅フラグが逆転したことが問題の引き +金となります。なぜなら Vim はその逆転を検出できず、端末ウィンドウのカーソルの +点滅も逆転します。 + + +Unix ~ + +UNIX ではすべての種類のコマンドを実行可能とするために pty を用いています。端末 +内で Vim ですら実行できるのです! これは以下のようにデバッグに利用できます。 + +実行中のジョブに情報を伝えるのに以下の環境変数が利用できます: + TERM 端末の名前 'term' + ROWS 端末の初期行数 + LINES ROWS と同じ + COLUMNS 端末の初期桁数 + COLORS 色数 't_Co' (GUIでは 256*256*256) + VIM_SERVERNAME v:servername + +ジョブを開始した Vim インスタンスと通信するのに |client-server| 機能を使えま +す。この方法は v:servername が空ではないときのみ機能します。必要ならば次のよう +にしてそれを設定できます: > + call remote_startserver('vim-server') + +ジョブの中で以下の様なことができます: > + vim --servername $VIM_SERVERNAME --remote +123 some_file.c +これは "some_file.c" の 123 行目を開かせます。 + + +MS-Windows ~ + +MS-Windows ではすべての種類のコマンドを実行可能とするために winpty を用いてい +ます。あたりまえのことですが、ここで実行するコマンドは端末の中で動くもので、独 +自のウィンドウを開くものであってはいけません。 + +winpty 内の以下の2つのファイルが必要です: + + winpty.dll + winpty-agent.exe + +これらは以下のページからダウンロードできます: + + https://github.com/rprichard/winpty + +ファイルを環境変数 PATH のいずれかに置くだけです。必要ならばオプション +'winptydll' でファイルの場所を指定できます。もしも32ビット版と64ビット版を同じ +ディレクトリに置きたいのであれば、Vimのビルドに合わせてそれぞれを winpty32.dll +もしくは winpty64.dll という名前に変更してください。 + +============================================================================== +2. リモートテスト *terminal-testing* + +VimのほとんどのテストはVimのなかでスクリプトを実行しています。テスト対象のコー +ドと干渉してしまうような、幾つかのテストではこれは機能しません。これを避けるた +めに端末ウィンドウ内でさらにVimを実行しています。そのテストではキーストローク +を端末に送信し、その結果として端末画面の状態が変わるのを検査します。 + +関数 ~ + +term_sendkeys() 端末にキーストロークを送信する (tmap の影響を受けない) +term_wait() 端末画面が更新されるのを待つ +term_scrape() 端末画面の内容を検査する + + +============================================================================== +3. デバッグ *terminal-debug* + +Vim のウィンドウでソースコードを表示しながらプログラムを gdb でデバッグするの +に、端末デバッグプラグインが利用できます。これは Vim の中だけで完結するので、 +SSH 接続が1つあればリモートで機能します。 + + +はじめに ~ + +以下のコマンドでプラグインを読み込みます: > + packadd termdebug +< *:Termdebug* +デバッグを開始するには `:TermDebug` に続けてコマンド名を入力します。例: > + :TermDebug vim + +これにより2つのウィンドウが開きます: +gdb のウィンドウ + "gdb vim" を実行した端末ウィンドウ。ここでは直接 gdb とやりと + りできる。バッファ名は "!gdb" +プログラムのウィンドウ + 実行したプログラムの端末ウィンドウ。 gdb 内で "run" をしてプロ + グラムの I/O が発生するとこのウィンドウに反映される。その内容 + は gdb の制御下にない。バッファ名は "gdb program" + +現在のウィンドウはソースコードを表示するのに使われます。gdb が一時停止した際 +に、可能ならばその場所が表示されます。現在の位置を示すためにサインが利用されま +す (ハイライトグループ debugPC を使う)。 + +現在のウィンドウの内容が変更されると、現在の gdb の位置を表示するために別の +ウィンドウが開きます。 + +実行中のプログラムを操作するにはその端末にフォーカスを合わせます。以降の操作は +普通の端末ウィンドウと同様です。 + +デバッガが終了すると、通常は gdb のウィンドウで "quit" とタイプすることで終了 +しますが、2つのウィンドウは閉じます。 + + +コードをステップ実行する ~ + +gdb ウィンドウにフォーカスを移しコマンドを入力します。一般的なものは以下: +- CTRL-C プログラムを中断する +- next 現在の行を実行し、次の行(の手前)で停止する +- step 現在の行を実行し、次の文(の手前)で停止する。関数の内側に入る +- finish 現在の関数を抜けるまで実行する +- where スタックを表示する +- frame N N 番目のスタックフレームに移動する +- continue 実行を再開する + +ソースコードを表示しているウィンドウでは gdb を制御するのに幾つかのコマンドが +使えます: + :Break 現在の行にブレークポイントを設定する。サインが表示される + :Delete 現在の行のブレークポイントを削除する + :Step gdb の "step" コマンドを実行する + :Over gdb の "next" コマンドを実行する + (:Next だと Vim のコマンドとかぶるので) + :Finish gdb の "finish" コマンドを実行する + :Continue gdb の "continue" コマンドを実行する + + +変数を検査する ~ + + :Evaluate カーソルの下の式を評価する + K 上に同じ + :Evaluate {expr} {expr} を評価する + :'<,'>Evaluate ビジュアル選択したテキストを評価する + +これは gdb ウィンドウで "print" コマンドを使ったのに相当します。 + + +その他のコマンド ~ + + :Gdb gdb ウィンドウに移動する + :Program デバッグ中のプログラムウィンドウに移動する + + +通信 ~ + +Vim が gdb と通信するために他に隠されたバッファを利用します。バッファ名は "gdb +communicate" です。このバッファは消さないでください。消してしまうとデバッガが +動作しなくなってしまうでしょう。 + + +カスタマイズ ~ + +gdb コマンド以外のデバッガを使うには、 `:Termdebug` を実行する前に +"termdebugger" 変数を変更してください: > + let termdebugger = "mygdb" +gdb と完全互換のあるデバッガのみが使えます。Vim は gdb の操作に GDB/MI イン +ターフェイスを利用しています。 + +サインの色は以下のハイライトグループで調整できます: +- debugPC 現在の位置 +- debugBreakpoint ブレークポイント + +'background' オプションが "light" の時のデフォルトは以下のとおりです: + hi debugPC term=reverse ctermbg=lightblue guibg=lightblue + hi debugBreakpoint term=reverse ctermbg=red guibg=red + +'background' オプションが "dark" の時は以下のとおりです: + hi debugPC term=reverse ctermbg=darkblue guibg=darkblue + hi debugBreakpoint term=reverse ctermbg=red guibg=red + +デバッグを開始した際に Vim のウィンドウ幅を変更し、垂直分割を利用するには次の +ように設定します: > + let g:termdebug_wide = 163 +これは :Termdebug を実行した際に &columns を 163 に設定します。元の値はデバッ +ガが終了する際に復元されます。 + + + + vim:tw=78:ts=8:ft=help:norl: diff --git a/en/terminal.txt b/en/terminal.txt new file mode 100644 index 000000000..aad8e4a5f --- /dev/null +++ b/en/terminal.txt @@ -0,0 +1,427 @@ +*terminal.txt* For Vim version 8.0. Last change: 2017 Sep 14 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Terminal window support *terminal* + + +WARNING: THIS IS ONLY PARTLY IMPLEMENTED, ANYTHING CAN STILL CHANGE + +The terminal feature is optional, use this to check if your Vim has it: > + echo has('terminal') +If the result is "1" you have it. + + +1. Basic use |terminal-use| +2. Remote testing |terminal-testing| +3. Debugging |terminal-debug| + +{Vi does not have any of these commands} +{only available when compiled with the |+terminal| feature} + +The terminal feature requires the |+multi_byte|, |+job| and |+channel| features. + +============================================================================== +1. Basic use *terminal-use* + +This feature is for running a terminal emulator in a Vim window. A job can be +started connected to the terminal emulator. For example, to run a shell: > + :term bash + +Or to run build command: > + :term make myprogram + +The job runs asynchronously from Vim, the window will be updated to show +output from the job, also while editing in another window. + + +Typing ~ + *terminal-typing* +When the keyboard focus is in the terminal window, typed keys will be sent to +the job. This uses a pty when possible. You can click outside of the +terminal window to move keyboard focus elsewhere. + +CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.: + CTRL-W CTRL-W move focus to the next window + CTRL-W : enter an Ex command +See |CTRL-W| for more commands. + +Special in the terminal window: *CTRL-W_.* *CTRL-W_N* + CTRL-W . send a CTRL-W to the job in the terminal + CTRL-W N go to Terminal-Normal mode, see |Terminal-mode| + CTRL-\ CTRL-N go to Terminal-Normal mode, see |Terminal-mode| + CTRL-W " {reg} paste register {reg} *CTRL-W_quote* + Also works with the = register to insert the result of + evaluating an expression. + CTRL-W CTRL-C ends the job, see below |t_CTRL-W_CTRL-C| + +See option 'termkey' for specifying another key instead of CTRL-W that +will work like CTRL-W. However, typing 'termkey' twice sends 'termkey' to +the job. For example: + 'termkey' CTRL-W move focus to the next window + 'termkey' : enter an Ex command + 'termkey' 'termkey' send 'termkey' to the job in the terminal + 'termkey' . send a CTRL-W to the job in the terminal + 'termkey' N go to terminal Normal mode, see below + 'termkey' CTRL-N same as CTRL-W N + 'termkey' CTRL-C same as |t_CTRL-W_CTRL-C| + *t_CTRL-\_CTRL-N* +The special key combination CTRL-\ CTRL-N can be used to switch to Normal +mode, just like this works in any other mode. + *t_CTRL-W_CTRL-C* +CTRL-W CTRL-C can be typed to forcefully end the job. On MS-Windows a +CTRL-BREAK will also kill the job. + +If you type CTRL-C the effect depends on what the pty has been configured to +do. For simple commands this causes a SIGINT to be sent to the job, which +would end it. Other commands may ignore the SIGINT or handle the CTRL-C +themselves (like Vim does). + +To change the keys you type use terminal mode mappings, see |:tmap|. +These are defined like any mapping, but apply only when typing keys that are +sent to the job running in the terminal. + + +Size and color ~ + +See option 'termsize' for controlling the size of the terminal window. +(TODO: scrolling when the terminal is larger than the window) + +The job running in the terminal can change the colors. The default foreground +and background colors are taken from Vim, the Normal highlight group. + +For a color terminal the 'background' option is used to decide whether the +terminal window will start with a white or black background. + +To use a different color the Terminal highlight group can be used: > + hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue + + +Syntax ~ + +:[range]ter[minal] [options] [command] *:ter* *:terminal* + Open a new terminal window. + + If [command] is provided run it as a job and connect + the input and output to the terminal. + If [command] is not given the 'shell' option is used. + if [command] is NONE no job is started, the pty of the + terminal can be used by a command like gdb. + + A new buffer will be created, using [command] or + 'shell' as the name, prefixed with a "!". If a buffer + by this name already exists a number is added in + parentheses. E.g. if "gdb" exists the second terminal + buffer will use "!gdb (1)". + + If [range] is given the specified lines are used as + input for the job. It will not be possible to type + keys in the terminal window. For MS-Windows see the + ++eof argument below. + + Two comma separated numbers are used as "rows,cols". + E.g. `:24,80gdb` opens a terminal with 24 rows and 80 + columns. However, if the terminal window spans the + Vim window with, there is no vertical split, the Vim + window width is used. + *term++close* *term++open* + Supported [options] are: + ++close The terminal window will close + automatically when the job terminates. + ++open When the job terminates and no window + shows it, a window will be opened. + Note that this can be interruptive. + ++curwin Open the terminal in the current + window, do not split the current + window. Fails if the current buffer + cannot be |abandon|ed. + ++hidden Open the terminal in a hidden buffer, + no window will be used. + ++rows={height} Use {height} for the terminal window + height. + ++cols={width} Use {width} for the terminal window + width. + ++eof={text} when using [range]: text to send after + the last line was written. Cannot + contain white space. A CR is + appended. For MS-Windows the default + is to send CTRL-D. + E.g. for a shell use "++eof=exit" and + for Python "++eof=exit()". Special + codes can be used like with `:map`, + e.g. "" for CTRL-Z. + + If you want to use more options use the |term_start()| + function. + +When the buffer associated with the terminal is unloaded or wiped out the job +is killed, similar to calling `job_stop(job, "kill")` + +So long as the job is running the window behaves like it contains a modified +buffer. Trying to close the window with `CTRL-W :quit` fails. When using +`CTRL-W :quit!` the job is ended. The text in the window is lost. The buffer +still exists, but getting it in a window with `:buffer` will show an empty +buffer. + +Trying to close the window with `CTRL-W :close` also fails. Using +`CTRL-W :close!` will close the window and make the buffer hidden. + +You can use `CTRL-W :hide` to close the terminal window and make the buffer +hidden, the job keeps running. The `:buffer` command can be used to turn the +current window into a terminal window. If there are unsaved changes this +fails, use ! to force, as usual. + +To have a background job run without a window, and open the window when it's +done, use options like this: > + :term ++hidden ++open make +Note that the window will open at an unexpected moment, this will interrupt +what you are doing. + + *E947* *E948* +So long as the job is running, the buffer is considered modified and Vim +cannot be quit easily, see |abandon|. + +When the job has finished and no changes were made to the buffer: closing the +window will wipe out the buffer. + +Before changes can be made to a terminal buffer, the 'modifiable' option must +be set. This is only possible when the job has finished. At the first change +the buffer will become a normal buffer and the highlighting is removed. +You may want to change the buffer name with |:file| to be able to write, since +the buffer name will still be set to the command. + + +Resizing ~ + +The size of the terminal can be in one of three modes: + +1. The 'termsize' option is empty: The terminal size follows the window size. + The minimal size is 2 screen lines with 10 cells. + +2. The 'termsize' option is "rows*cols", where "rows" is the minimal number of + screen rows and "cols" is the minimal number of cells. + +3. The 'termsize' option is "rowsXcols" (where the x is upper or lower case). + The terminal size is fixed to the specified number of screen lines and + cells. If the window is bigger there will be unused empty space. + +If the window is smaller than the terminal size, only part of the terminal can +be seen (the lower-left part). + +The |term_getsize()| function can be used to get the current size of the +terminal. |term_setsize()| can be used only when in the first or second mode, +not when 'termsize' is "rowsXcols". + + +Terminal-Job and Terminal-Normal mode ~ + *Terminal-mode* +When the job is running the contents of the terminal is under control of the +job. That includes the cursor position. Typed keys are sent to the job. +The terminal contents can change at any time. This is called Terminal-Job +mode. + +Use CTRL-W N (or 'termkey' N) to switch to Terminal-Normal mode. Now the +contents of the terminal window is under control of Vim, the job output is +suspended. CTRL-\ CTRL-N does the same. + +Terminal-Job mode is where |tmap| mappings are applied. Keys sent by +|term_sendkeys()| are not subject to tmap, but keys from |feedkeys()| are. + + *E946* +In Terminal-Normal mode you can move the cursor around with the usual Vim +commands, Visually mark text, yank text, etc. But you cannot change the +contents of the buffer. The commands that would start insert mode, such as +'i' and 'a', return to Terminal-Job mode. The window will be updated to show +the contents of the terminal. + +In Terminal-Normal mode the statusline and window title show "(Terminal)". If +the job ends while in Terminal-Normal mode this changes to +"(Terminal-finished)". + +It is not possible to enter Insert mode from Terminal-Job mode. + + +Cursor style ~ + +By default the cursor in the terminal window uses a not blinking block. The +normal xterm escape sequences can be used to change the blinking state and the +shape. Once focus leaves the terminal window Vim will restore the original +cursor. + +An exception is when xterm is started with the "-bc" argument, or another way +that causes the cursor to blink. This actually means that the blinking flag +is inverted. Since Vim cannot detect this, the terminal window cursor +blinking will also be inverted. + + +Unix ~ + +On Unix a pty is used to make it possible to run all kinds of commands. You +can even run Vim in the terminal! That's used for debugging, see below. + +Environment variables are used to pass information to the running job: + TERM name of the terminal, 'term' + ROWS number of rows in the terminal initially + LINES same as ROWS + COLUMNS number of columns in the terminal initially + COLORS number of colors, 't_Co' (256*256*256 in the GUI) + VIM_SERVERNAME v:servername + +The |client-server| feature can be used to communicate with the Vim instance +where the job was started. This only works when v:servername is not empty. +If needed you can set it with: > + call remote_startserver('vim-server') + +In the job you can then do something like: > + vim --servername $VIM_SERVERNAME --remote +123 some_file.c +This will open the file "some_file.c" and put the cursor on line 123. + + +MS-Windows ~ + +On MS-Windows winpty is used to make it possible to run all kind of commands. +Obviously, they must be commands that run in a terminal, not open their own +window. + +You need the following two files from winpty: + + winpty.dll + winpty-agent.exe + +You can download them from the following page: + + https://github.com/rprichard/winpty + +Just put the files somewhere in your PATH. You can set the 'winptydll' option +to point to the right file, if needed. If you have both the 32-bit and 64-bit +version, rename to winpty32.dll and winpty64.dll to match the way Vim was +build. + +============================================================================== +2. Remote testing *terminal-testing* + +Most Vim tests execute a script inside Vim. For some tests this does not +work, running the test interferes with the code being tested. To avoid this +Vim is executed in a terminal window. The test sends keystrokes to it and +inspects the resulting screen state. + +Functions ~ + +term_sendkeys() send keystrokes to a terminal (not subject to tmap) +term_wait() wait for screen to be updated +term_scrape() inspect terminal screen + + +============================================================================== +3. Debugging *terminal-debug* + +The Terminal debugging plugin can be used to debug a program with gdb and view +the source code in a Vim window. Since this is completely contained inside +Vim this also works remotely over an ssh connection. + + +Starting ~ + +Load the plugin with this command: > + packadd termdebug +< *:Termdebug* +To start debugging use `:TermDebug` folowed by the command name, for example: > + :TermDebug vim + +This opens two windows: +gdb window A terminal window in which "gdb vim" is executed. Here you + can directly interact with gdb. The buffer name is "!gdb". +program window A terminal window for the executed program. When "run" is + used in gdb the program I/O will happen in this window, so + that it does not interfere with controlling gdb. The buffer + name is "gdb program". + +The current window is used to show the source code. When gdb pauses the +source file location will be displayed, if possible. A sign is used to +highlight the current position (using highlight group debugPC). + +If the buffer in the current window is modified, another window will be opened +to display the current gdb position. + +Focus the terminal of the executed program to interact with it. This works +the same as any command running in a terminal window. + +When the debugger ends, typically by typing "quit" in the gdb window, the two +opened windows are closed. + + +Stepping through code ~ + +Put focus on the gdb window to type commands there. Some common ones are: +- CTRL-C interrupt the program +- next execute the current line and stop at the next line +- step execute the current line and stop at the next statement, entering + functions +- finish execute until leaving the current function +- where show the stack +- frame N go to the Nth stack frame +- continue continue execution + +In the window showing the source code some commands can used to control gdb: + :Break set a breakpoint at the current line; a sign will be displayed + :Delete delete a breakpoint at the current line + :Step execute the gdb "step" command + :Over execute the gdb "next" command (:Next is a Vim command) + :Finish execute the gdb "finish" command + :Continue execute the gdb "continue" command + + +Inspecting variables ~ + + :Evaluate evaluate the expression under the cursor + K same + :Evaluate {expr} evaluate {expr} + :'<,'>Evaluate evaluate the Visually selected text + +This is similar to using "print" in the gdb window. + + +Other commands ~ + + :Gdb jump to the gdb window + :Program jump to the window with the running program + + +Communication ~ + +There is another, hidden, buffer, which is used for Vim to communicate with +gdb. The buffer name is "gdb communication". Do not delete this buffer, it +will break the debugger. + + +Customizing ~ + +To change the name of the gdb command, set the "termdebugger" variable before +invoking `:Termdebug`: > + let termdebugger = "mygdb" +Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI +interface. + +The color of the signs can be adjusted with these highlight groups: +- debugPC the current position +- debugBreakpoint a breakpoint + +The defaults are, when 'background' is "light": + hi debugPC term=reverse ctermbg=lightblue guibg=lightblue + hi debugBreakpoint term=reverse ctermbg=red guibg=red + +When 'background' is "dark": + hi debugPC term=reverse ctermbg=darkblue guibg=darkblue + hi debugBreakpoint term=reverse ctermbg=red guibg=red + +To change the width of the Vim window when debugging starts, and use a +vertical split: > + let g:termdebug_wide = 163 +This will set &columns to 163 when :Termdebug is used. The value is restored +when quitting the debugger. + + + + vim:tw=78:ts=8:ft=help:norl: