From aed4f0d8efe5ee7e8ec7a38879369ca3762bdf95 Mon Sep 17 00:00:00 2001 From: h-east Date: Sat, 18 Oct 2025 19:19:31 +0900 Subject: [PATCH 1/3] Update terminal.{txt,jax} --- dict.yml | 3 + doc/terminal.jax | 174 ++++++++++++++++++++++++++++++++--------- en/terminal.txt | 198 +++++++++++++++++++++++++++++++++++------------ 3 files changed, 290 insertions(+), 85 deletions(-) diff --git a/dict.yml b/dict.yml index 6f385d30e..ec49b8000 100644 --- a/dict.yml +++ b/dict.yml @@ -299,6 +299,9 @@ Vim9 script: - オペレーター - 演算コマンド +フィルタ: + - フィルター + フォントセット: - フォント・セット diff --git a/doc/terminal.jax b/doc/terminal.jax index 69d5804ce..f8e49cfac 100644 --- a/doc/terminal.jax +++ b/doc/terminal.jax @@ -1,4 +1,4 @@ -*terminal.txt* For Vim バージョン 9.1. Last change: 2025 Sep 15 +*terminal.txt* For Vim バージョン 9.1. Last change: 2025 Oct 14 VIMリファレンスマニュアル by Bram Moolenaar @@ -13,39 +13,40 @@ 結果が "1" の場合、対応している。 -1. 基本的な使い方 |terminal-use| - キー入力 |terminal-typing| - サイズと色 |terminal-size-color| - 文法 |:terminal| - サイズ変更 |terminal-resizing| - 端末モード |Terminal-mode| - カーソルスタイル |terminal-cursor-style| - セッション |terminal-session| - 特別なキー |terminal-special-keys| - Unix |terminal-unix| - MS-Windows |terminal-ms-windows| +1. 基本的な使い方 |terminal-use| + キー入力 |terminal-typing| + サイズと色 |terminal-size-color| + 文法 |:terminal| + サイズ変更 |terminal-resizing| + 端末モード |Terminal-mode| + カーソルスタイル |terminal-cursor-style| + セッション |terminal-session| + 特別なキー |terminal-special-keys| + Unix |terminal-unix| + MS-Windows |terminal-ms-windows| 2. 端末関数 |terminal-function-details| 3. 端末通信 |terminal-communication| - Vim からジョブへ: term_sendkeys() |terminal-to-job| - ジョブから Vim へ: JSON API |terminal-api| - クライアントサーバー機能を使う |terminal-client-server| -4. リモートテスト |terminal-testing| -5. 画面ダンプの差分 |terminal-diff| - Vimの画面ダンプテストを書く |terminal-dumptest| - 画面ダンプを作成する |terminal-screendump| - 画面ダンプを比較する |terminal-diffscreendump| -6. デバッグ |terminal-debug| - はじめに |termdebug-starting| - セッション例 |termdebug-example| - コードをステップ実行する |termdebug-stepping| - 変数を検査する |termdebug-variables| - スタックフレームの移動 |termdebug-frames| - その他のコマンド |termdebug-commands| - イベント |termdebug-events| - プロンプトモード |termdebug-prompt| - マッピング |termdebug-mappings| - 通信 |termdebug-communication| - カスタマイズ |termdebug-customizing| + Vim からジョブへ: term_sendkeys() |terminal-to-job| + ジョブから Vim へ: JSON API |terminal-api| + クライアントサーバー機能を使う |terminal-client-server| +4. リモートテスト |terminal-testing| +5. 画面ダンプの差分 |terminal-diff| + Vimの画面ダンプテストを書く |terminal-dumptest| + 画面ダンプを作成する |terminal-screendump| + 画面ダンプを比較する |terminal-diffscreendump| +6. デバッグ |terminal-debug| + はじめに |termdebug-starting| + セッション例 |termdebug-example| + コードをステップ実行する |termdebug-stepping| + 変数を検査する |termdebug-variables| + スタックフレームの移動 |termdebug-frames| + その他のコマンド |termdebug-commands| + イベント |termdebug-events| + プロンプトモード |termdebug-prompt| + マッピング |termdebug-mappings| + 通信 |termdebug-communication| + リモートデバッグ |termdebug-remote| + カスタマイズ |termdebug-customizing| {Vimが |+terminal| 機能付きでコンパイルされたときのみ有効} 端末機能を使うには |+job| と |+channel| 機能が必要である。 @@ -1609,11 +1610,102 @@ gdb は奇妙な動作をしているが、プラグインはその問題を回 `:Continue` コマンドに "continue" が使用されていることが分かる。 +リモートデバッグ ~ + *termdebug-remote* +リモートデバッグにおける主な問題の 1 つは、デバッグ対象のソースファイルへのア +クセスである。プラグインは、システムと Vim のネットワーク機能を使用してこの問題 +を回避できる。 + *termdebug-remote-example* +|termdebug-example| は、`gdb` デバッガーを実行して `ssh` 経由でアクセス可能な +リモート Linux マシン上の Vim をデバッグすることで再現できる。 + +- ローカルの例の説明に従って Vim をビルドする。 + +リモートマシンで "socat" が使用できない場合、'terminal' モードは正常に動作しな +い。|termdebug_use_prompt| にフォールバックする: > + :let g:termdebug_config = {} + :let g:termdebug_config['use_prompt'] = v:true + +- リモート `gdb` インスタンスを実行するためのコマンドラインを指定する: > + :let g:termdebug_config['command'] = ['ssh', 'hostname', 'gdb'] +< この例では `ssh` の説明は範囲外だが、`$HOME/.ssh/config` ファイルにユーザー、 + キー、その他のオプションを指定することによって、コマンドラインを大幅に簡素化 + できることに注目して欲しい。 + +- リモートパスを |netrw| パスに変換するためのヒントを提供する: > + :let g:termdebug_config['substitute_path'] = { '/': 'scp://hostname//' } + +- termdebug プラグインをロードし、Vim のデバッグを開始する: > + :packadd termdebug + :Termdebug vim + +これで、ローカルの例と同じ 3 つのウィンドウが表示され、同じ手順を実行できる。 +唯一の違いは、ソースウィンドウにローカルバッファではなくnetrwバッファが表示さ +れることである。 + + *termdebug-substitute-path* +`g:termdebug_config['substitute_path']` エントリを使用して、gdb の +`substitute-path` コマンドと同じ戦略でリモートファイルをローカルファイルにマッ +ピングする。例: +- ssh 経由でリモートファイルにアクセスするには、|netrw| を使用する: > + let g:termdebug_config['command'] = ['ssh', 'hostname', 'gdb'] + let g:termdebug_config['substitute_path'] = { '/': 'scp://hostname//' } +< Note: キーはリモートマシンのルートパスを指定し、値はローカルマシンのルートパ +スを指定する。 +- Windows の `UNC` パスを使用して `WSL2` ソースにアクセスする: > + let g:termdebug_config['command'] = ['wsl', 'gdb'] + let g:termdebug_config['substitute_path'] = { + \ '/': '\\wsl.localhost\Ubuntu-22.04\', + \ '/mnt/c/': 'C:/' } +< Note: 複数のマッピングが必要である。各ドライブユニットに 1 つ、Linux ファイ +ルシステムに 1 つ (`wslpath` 経由で照会)。 + +このモードでは、すべての `ssh` または `wsl` コマンドが検出され、同様のコマンド +を使用してリモート `tty` 端末セッションで `socat` を起動し、それを `gdb` に接 +続する。 +`socat` が使用できない場合は、フォールバックとして通常のリモート端末が使用され +る。 +次のセッションでは、このデフォルトの動作をオーバーライドする方法を説明する。 + + *termdebug-remote-window* +別のリモート端末クライアントを使用するには、`:Termdebug` を呼び出す前に、 +`g:termdebug_config` 変数の "remote_window" エントリを設定する。例: +- "prompt" モードを使用して Docker コンテナ内でデバッグする: > + let g:termdebug_config['use_prompt'] = v:true + let g:termdebug_config['command'] = ['docker', 'run', '-i', + \ '--rm', '--name', 'container-name', 'image-name', 'gdb'] + let g:termdebug_config['remote_window'] = + \ ['docker', 'exec', '-ti', 'container-name' + \ ,'socat', '-dd', '-', 'PTY,raw,echo=0'] + +- "terminal buffer" を使用して Docker コンテナ内でデバッグする。 + コンテナは既に実行されているはずである。これは、前述の `terminal mode` の場 + 合とは異なり、"program" および "communication" pty が gdb pty の前に作成され + るためである: > + $ docker run -ti --rm --name container-name immage-name + +< 次に、デバッガーを起動する: > + let g:termdebug_config['use_prompt'] = v:false " default + let g:termdebug_config['command'] = + \ ['docker', 'exec', '-ti', 'container-name', 'gdb'] + let g:termdebug_config['remote_window'] = + \ ['docker', 'exec', '-ti', 'container-name' + \ ,'socat', '-dd', '-', 'PTY,raw,echo=0'] + +Note: プロンプトバッファが `tty` 接続を処理できないため、"command" は +|termdebug-prompt| モードで `-t` を使用できない。 +"remote_window" コマンドでは `-t` を使用する必要がある。そうしなければ、gdb が +接続するための `pty slave device` が不足する。 +Note: "socat" は、リモートマシンの "terminal" モードで使用可能である必要がある。 +Note: docker コンテナソースは、`volumes` とマッピングを組み合わせてアクセスで +きる (|termdebug-substitute-path| を参照)。 + GDBコマンド ~ *g:termdebugger* gdb コマンド以外のデバッガを使うには、`:Termdebug` を実行する前に g:termdebug_config の "debugger" エントリか "g:termdebugger" 変数を変更する: > let g:termdebug_config['command'] = "mygdb" + g:termdebug_config がない場合は、以下を使用できる: > let g:termdebugger = "mygdb" @@ -1621,6 +1713,7 @@ g:termdebug_config がない場合は、以下を使用できる: > コマンドに引数が必要な場合はリストを使用する: > let g:termdebug_config['command'] = ['rr', 'replay', '--'] + g:termdebug_config がない場合は、以下を使用できる: > let g:termdebugger = ['rr', 'replay', '--'] @@ -1628,6 +1721,13 @@ gdb がデバッガで適切に動作するように、いくつかの引数が したい場合は、引数リストをフィルタリングする関数を追加する: > let g:termdebug_config['command_filter'] = MyDebugFilter +"command_filter" シナリオは、ssh 経由のリモートデバッグにおけるエスケープの問 +題を解決する。便宜上、引数内の空白をエスケープするためのデフォルトフィルタが用 +意されている。このフィルタは ssh 用に自動的に設定されるが、以下のような他のユー +スケースにも使用できる: > + let g:termdebug_config['command_filter'] = + / function('g:Termdebug_escape_whitespace') + 引数を追加したくないが、"pty" を設定する必要がある場合は、関数を使用して必要な 引数を追加する: > let g:termdebug_config['command_add_args'] = MyAddArguments @@ -1682,15 +1782,15 @@ g:termdebug_config がない場合は、以下を使用できる: > デフォルトの目印の変更 ~ *termdebug_signs* Termdebug は、signcolumn のブレークポイント ID の 16 進数を使用してブレークポ -イントを表す。"0xFF" より大きい場合は、実際には記号用の画面セルが 2 つしかない -ため、"F+" と表示される。 -代わりに 10 進数のブレークポイントの目印を使用することもできる。その場合、99 -より大きい ID は "9+" と表示される。 +イントを表す。"0xFF" より大きい場合、目印に使用できる画面セルは 2 つしかないた +め、"F+" と表示される。代わりに 10 進数のブレークポイントの目印を使用すること +もできる。その場合、99 より大きい ID は "9+" と表示される。 ブレークポイントの目印をカスタマイズして、signcolumn に `>>` を表示するには: > let g:termdebug_config['sign'] = '>>' 最初のいくつかのブレークポイントに個別の記号を指定することもできる: > - let g:termdebug_config['signs'] = ['>1', '>2', '>3', '>4', '>5', '>6', '>7', '>8', '>9'] + let g:termdebug_config['signs'] = ['>1', '>2', '>3', '>4', '>5', + \ '>6', '>7', '>8', '>9'] let g:termdebug_config['sign'] = '>>' 10 進数 (基数 10) のブレークポイントの目印を使用するには: > let g:termdebug_config['sign_decimal'] = 1 diff --git a/en/terminal.txt b/en/terminal.txt index b667832f0..f7fe33016 100644 --- a/en/terminal.txt +++ b/en/terminal.txt @@ -1,4 +1,4 @@ -*terminal.txt* For Vim version 9.1. Last change: 2025 Sep 15 +*terminal.txt* For Vim version 9.1. Last change: 2025 Oct 14 VIM REFERENCE MANUAL by Bram Moolenaar @@ -44,6 +44,7 @@ If the result is "1" you have it. Prompt mode |termdebug-prompt| Mappings |termdebug-mappings| Communication |termdebug-communication| + Remote Debugging |termdebug-remote| Customizing |termdebug-customizing| {only available when compiled with the |+terminal| feature} @@ -53,7 +54,7 @@ The terminal feature requires the |+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: > +started connected to the terminal emulator. For example, to run a shell: > :term bash Or to run build command: > @@ -70,7 +71,8 @@ the job. This uses a pty when possible. You can click outside of the terminal window to move keyboard focus elsewhere. *t_CTRL-W_CTRL-W* *t_CTRL-W_:* -CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.: +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. @@ -270,12 +272,12 @@ Command syntax ~ the terminal window) the command line height will be reduced as needed. ++cols={width} Use {width} for the terminal window - width. If the terminal uses the full + width. If the terminal uses the full Vim width (no window left or right of the terminal window) this value is ignored. ++eof={text} When using [range]: text to send after - the last line was written. Cannot + the last line was written. Cannot contain white space. A CR is appended. For MS-Windows the default is to send CTRL-D. @@ -321,13 +323,13 @@ fails, use ! to force, as usual. *terminal-close* When the terminal job finishes and no [command] was given (e.g. the 'shell' command was executed), the terminal window will be closed by default (unless -the buffer in next window receiving the space has the 'nobuflisted' option set, -in which case the terminal window would not be closed automatically, but a new -empty buffer would be opened in that window). +the buffer in next window receiving the space has the 'nobuflisted' option +set, in which case the terminal window would not be closed automatically, but +a new empty buffer would be opened in that window). When the terminal window is closed, e.g. when the shell exits and "++close" argument was used, and this is the last normal Vim window, then Vim will exit. -This is like using |:quit| in a normal window. Help and preview windows are +This is like using |:quit| in a normal window. Help and preview windows are not counted. To have a background job run without a window, and open the window when it's @@ -383,7 +385,7 @@ Use CTRL-W N (or 'termwinkey' 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 +Terminal-Job mode is where |:tmap| mappings are applied. Keys sent by |term_sendkeys()| are not subject to tmap, but keys from |feedkeys()| are. It is not possible to enter Insert mode from Terminal-Job mode. @@ -393,7 +395,7 @@ 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. |:startinsert| is ineffective. +the contents of the terminal. |:startinsert| is ineffective. In Terminal-Normal mode the statusline and window title show "(Terminal)". If the job ends while in Terminal-Normal mode this changes to @@ -401,7 +403,7 @@ the job ends while in Terminal-Normal mode this changes to When the job outputs lines in the terminal, such that the contents scrolls off the top, those lines are remembered and can be seen in Terminal-Normal mode. -The number of lines is limited by the 'termwinscroll' option. When going over +The number of lines is limited by the 'termwinscroll' option. When going over this limit, the first 10% of the scrolled lines are deleted and are lost. @@ -485,10 +487,10 @@ version, rename to winpty32.dll and winpty64.dll to match the way Vim was build. *ConPTY* *E982* On more recent versions of MS-Windows 10 (beginning with the "October 2018 -Update"), winpty is no longer required. On those versions, |:terminal| will use +Update"), winpty is no longer required. On those versions, |:terminal| will use Windows' built-in support for hosting terminal applications, "ConPTY". When ConPTY is in use, there may be rendering artifacts regarding ambiguous-width -characters. If you encounter any such issues, install "winpty". Until the +characters. If you encounter any such issues, install "winpty". Until the ConPTY problems have been fixed "winpty" will be preferred. Environment variables are used to pass information to the running job: @@ -539,7 +541,7 @@ term_dumpdiff({filename}, {filename} [, {options}]) "norestore" do not add the terminal window to a session file - Each character in the middle part indicates a difference. If + Each character in the middle part indicates a difference. If there are multiple differences only the first in this list is used: X different character @@ -640,8 +642,8 @@ term_getattr({attr}, {what}) *term_getattr()* term_getcursor({buf}) *term_getcursor()* - Get the cursor position of terminal {buf}. Returns a list with - two numbers and a dictionary: [row, col, dict]. + Get the cursor position of terminal {buf}. Returns a list + with two numbers and a dictionary: [row, col, dict]. "row" and "col" are one based, the first screen cell is row 1, column 1. This is the cursor position of the terminal @@ -656,7 +658,7 @@ term_getcursor({buf}) *term_getcursor()* for a vertical bar. "color" color of the cursor, e.g. "green" - {buf} must be the buffer number of a terminal window. If the + {buf} must be the buffer number of a terminal window. If the buffer does not exist or is not a terminal window, an empty list is returned. @@ -669,7 +671,7 @@ term_getcursor({buf}) *term_getcursor()* term_getjob({buf}) *term_getjob()* Get the Job associated with terminal window {buf}. {buf} is used as with |term_getsize()|. - Returns |v:null| when there is no job. In Vim9 script, return + Returns |v:null| when there is no job. In Vim9 script, return |null_job| when there is no job. Can also be used as a |method|: > @@ -712,7 +714,7 @@ term_getscrolled({buf}) *term_getscrolled()* term_getsize({buf}) *term_getsize()* - Get the size of terminal {buf}. Returns a list with two + Get the size of terminal {buf}. Returns a list with two numbers: [rows, cols]. This is the size of the terminal, not the window containing the terminal. @@ -727,14 +729,14 @@ term_getsize({buf}) *term_getsize()* term_getstatus({buf}) *term_getstatus()* - Get the status of terminal {buf}. This returns a String with + Get the status of terminal {buf}. This returns a String with a comma-separated list of these items: running job is running finished job has finished normal in Terminal-Normal mode One of "running" or "finished" is always present. - {buf} must be the buffer number of a terminal window. If the + {buf} must be the buffer number of a terminal window. If the buffer does not exist or is not a terminal window, an empty string is returned. @@ -745,10 +747,10 @@ term_getstatus({buf}) *term_getstatus()* term_gettitle({buf}) *term_gettitle()* - Get the title of terminal {buf}. This is the title that the + Get the title of terminal {buf}. This is the title that the job in the terminal has set. - {buf} must be the buffer number of a terminal window. If the + {buf} must be the buffer number of a terminal window. If the buffer does not exist or is not a terminal window, an empty string is returned. @@ -763,8 +765,8 @@ term_gettty({buf} [, {input}]) *term_gettty()* terminal window {buf}. {buf} is used as with |term_getsize()|. When {input} is omitted or 0, return the name for writing - (stdout). When {input} is 1 return the name for reading - (stdin). On UNIX, both return same name. + (stdout). When {input} is 1 return the name for reading + (stdin). On UNIX, both return same name. Can also be used as a |method|: > GetBufnr()->term_gettty() @@ -807,7 +809,7 @@ term_sendkeys({buf}, {keys}) *term_sendkeys()* Send keystrokes {keys} to terminal {buf}. {buf} is used as with |term_getsize()|. - {keys} are translated as key sequences. For example, "\" + {keys} are translated as key sequences. For example, "\" means the character CTRL-X. Can also be used as a |method|: > @@ -903,7 +905,7 @@ term_setrestore({buf}, {command}) *term_setrestore()* term_setsize({buf}, {rows}, {cols}) *term_setsize()* *E955* - Set the size of terminal {buf}. The size of the window + Set the size of terminal {buf}. The size of the window containing the terminal will also be adjusted, if possible. If {rows} or {cols} is zero or negative, that dimension is not changed. @@ -921,7 +923,7 @@ term_setsize({buf}, {rows}, {cols}) *term_setsize()* *E955* term_start({cmd} [, {options}]) *term_start()* Open a terminal window and run {cmd} in it. - {cmd} can be a string or a List, like with |job_start()|. The + {cmd} can be a string or a List, like with |job_start()|. The string "NONE" can be used to open a terminal window without starting a job, the pty of the terminal can be used by a command like gdb. @@ -968,17 +970,17 @@ term_start({cmd} [, {options}]) *term_start()* "open": open window if needed Note that "open" can be interruptive. See |term++close| and |term++open|. - "term_opencmd" command to use for opening the window when - "open" is used for "term_finish"; must - have "%d" where the buffer number goes, - e.g. "10split|buffer %d"; when not + "term_opencmd" command to use for opening the window + when "open" is used for "term_finish"; + must have "%d" where the buffer number + goes, e.g. "10split|buffer %d"; when not specified "botright sbuf %d" is used "term_highlight" highlight group to use instead of "Terminal" "eof_chars" Text to send after all buffer lines were written to the terminal. When not set - CTRL-D is used on MS-Windows. For Python - use CTRL-Z or "exit()". For a shell use + CTRL-D is used on MS-Windows. For Python + use CTRL-Z or "exit()". For a shell use "exit". A CR is always added. "ansi_colors" A list of 16 color names or hex codes defining the ANSI palette used in GUI @@ -1013,7 +1015,7 @@ term_wait({buf} [, {time}]) *term_wait()* There are several ways to communicate with the job running in a terminal: - Use |term_sendkeys()| to send text and escape sequences from Vim to the job. - Use the JSON API to send encoded commands from the job to Vim. -- Use the |client-server| mechanism. This works on machines with an X server +- Use the |client-server| mechanism. This works on machines with an X server and on MS-Windows. @@ -1179,7 +1181,7 @@ Writing a screen dump test for Vim ~ *terminal-dumptest* For an example see the Test_syntax_c() function in src/testdir/test_syntax.vim. The main parts are: -- Write a file you want to test with. This is useful for testing syntax +- Write a file you want to test with. This is useful for testing syntax highlighting. You can also start Vim with an empty buffer. - Run Vim in a terminal with a specific size. The default is 20 lines of 75 characters. This makes sure the dump is always this size. The function @@ -1257,7 +1259,7 @@ kind of difference: + character missing in first - character missing in second -Alternatively, press "s" to swap the first and second dump. Do this several +Alternatively, press "s" to swap the first and second dump. Do this several times so that you can spot the difference in the context of the text. ============================================================================== @@ -1312,7 +1314,7 @@ Only one debugger can be active at a time. *termdebug-timeout* Depending on how gdb is launched, termdebug startup time may vary. To avoid termdebug to get stuck if the startup process of gdb takes too long, -a configurable timeout is included. Such time out is configurable in terms of +a configurable timeout is included. Such time out is configurable in terms of multiple of 10ms: > let g:termdebug_config['timeout'] = 500 # 500 * 10ms = 5 seconds. @@ -1359,7 +1361,7 @@ You can use CTRL-W CTRL-W or the mouse to move focus between windows. Put focus on the gdb window and type: > break ex_help run -Vim will start running in the program window. Put focus there and type: > +Vim will start running in the program window. Put focus there and type: > :help gui Gdb will run into the ex_help breakpoint. The source window now shows the ex_cmds.c file. A red "1 " marker will appear in the signcolumn where the @@ -1387,7 +1389,7 @@ executed. You can type more advanced commands in the gdb window. For example, type: > watch curbuf -Now click "Cont" in the toolbar (or type "cont" in the gdb window). Execution +Now click "Cont" in the toolbar (or type "cont" in the gdb window). Execution will now continue until the value of "curbuf" changes, which is in do_ecmd(). To remove this watchpoint again type in the gdb window: > delete 3 @@ -1499,7 +1501,7 @@ Other commands ~ *:Asm* jump to the window with the disassembly, create it if there isn't one *:Var* jump to the window with the local and argument variables, - create it if there isn't one. This window updates whenever the + create it if there isn't one. This window updates whenever the program is stopped Events ~ @@ -1635,12 +1637,103 @@ interrupt the running program. But after using the MI command communication channel. +Remote debugging ~ + *termdebug-remote* +One of the main issues of remote debugging is the access to the debuggee's +source files. The plugin can profit from system and vim's networking +capabilities to workaround this. + *termdebug-remote-example* +The |termdebug-example| can be replicated by running the `gdb` debugger to +debug Vim on a remote Linux machine accessible via `ssh`. + +- Build Vim as explained in the local example. + +- If "socat" is not available in the remote machine 'terminal' mode will not + work properly. Fall back to |termdebug_use_prompt|: > + :let g:termdebug_config = {} + :let g:termdebug_config['use_prompt'] = v:true + +- Specify the command line to run the remote `gdb` instance: > + :let g:termdebug_config['command'] = ['ssh', 'hostname', 'gdb'] +< Explaining `ssh` is beyond the scope of this example, but notice the + command line can be greatly simplified by specifying the user, keys and + other options into the `$HOME/.ssh/config` file. + +- Provide a hint for translating remote paths into |netrw| paths: > + :let g:termdebug_config['substitute_path'] = { '/': 'scp://hostname//' } + +- Load the termdebug plugin and start debugging Vim: > + :packadd termdebug + :Termdebug vim + +You now have the same three windows of the local example and can follow the +very same steps. The only difference is that the source windows displays a +netrw buffer instead of a local one. + + *termdebug-substitute-path* +Use the `g:termdebug_config['substitute_path']` entry to map remote to local +files using the same strategy that gdb's `substitute-path` command uses. +For example: +- Use |netrw| to access files remoting via ssh: > + let g:termdebug_config['command'] = ['ssh', 'hostname', 'gdb'] + let g:termdebug_config['substitute_path'] = { '/': 'scp://hostname//' } +< Note: that the key specifies the remote machine root path and the value + the local one. +- Use Windows' `UNC` paths to access `WSL2` sources: > + let g:termdebug_config['command'] = ['wsl', 'gdb'] + let g:termdebug_config['substitute_path'] = { + \ '/': '\\wsl.localhost\Ubuntu-22.04\', + \ '/mnt/c/': 'C:/' } +< Note: that several mappings are required: one for each drive unit + and one for the linux filesystem (queried via `wslpath`). + +In this mode any `ssh` or `wsl` command would be detected and a similar +command would be used to launch `socat` in a remote `tty` terminal session +and connect it to `gdb`. +If `socat` is not available a plain remote terminal would be used as +fallback. +The next session shows how to override this default behaviour. + + *termdebug-remote-window* +In order to use another remote terminal client, set "remote_window" entry +in `g:termdebug_config` variable before invoking `:Termdebug`. For example: +- Debugging inside a docker container using "prompt" mode: > + let g:termdebug_config['use_prompt'] = v:true + let g:termdebug_config['command'] = ['docker', 'run', '-i', + \ '--rm', '--name', 'container-name', 'image-name', 'gdb'] + let g:termdebug_config['remote_window'] = + \ ['docker', 'exec', '-ti', 'container-name' + \ ,'socat', '-dd', '-', 'PTY,raw,echo=0'] + +- Debugging inside a docker container using a "terminal buffer". + The container should be already running because unlike the previous + case for `terminal mode` "program" and "communication" ptys are created + before the gdb one: > + $ docker run -ti --rm --name container-name immage-name + +< Then, launch the debugger: > + let g:termdebug_config['use_prompt'] = v:false " default + let g:termdebug_config['command'] = + \ ['docker', 'exec', '-ti', 'container-name', 'gdb'] + let g:termdebug_config['remote_window'] = + \ ['docker', 'exec', '-ti', 'container-name' + \ ,'socat', '-dd', '-', 'PTY,raw,echo=0'] + +Note: "command" cannot use `-t` on |termdebug-prompt| mode because prompt +buffers cannot handle `tty` connections. +The "remote_window" command must use `-t` because otherwise it will lack +a `pty slave device` for gdb to connect. +Note: "socat" must be available in the remote machine on "terminal" mode. +Note: docker container sources can be accessible combining `volumes` +with mappings (see |termdebug-substitute-path|). + GDB command ~ *g:termdebugger* To change the name of the gdb command, set "debugger" entry in g:termdebug_config or the "g:termdebugger" variable before invoking `:Termdebug`: > let g:termdebug_config['command'] = "mygdb" + If there is no g:termdebug_config you can use: > let g:termdebugger = "mygdb" @@ -1648,6 +1741,7 @@ However, the latter form will be deprecated in future releases. If the command needs an argument use a List: > let g:termdebug_config['command'] = ['rr', 'replay', '--'] + If there is no g:termdebug_config you can use: > let g:termdebugger = ['rr', 'replay', '--'] @@ -1655,6 +1749,13 @@ Several arguments will be added to make gdb work well for the debugger. If you want to modify them, add a function to filter the argument list: > let g:termdebug_config['command_filter'] = MyDebugFilter +A "command_filter" scenario is solving escaping issues on remote debugging +over "ssh". For convenience a default filter is provided for escaping +whitespaces inside the arguments. It is automatically configured for "ssh", +but can be employed in other use cases like this: > + let g:termdebug_config['command_filter'] = + / function('g:Termdebug_escape_whitespace') + If you do not want the arguments to be added, but you do need to set the "pty", use a function to add the necessary arguments: > let g:termdebug_config['command_add_args'] = MyAddArguments @@ -1709,15 +1810,16 @@ However, the latter form will be deprecated in future releases. Change default signs ~ *termdebug_signs* Termdebug uses the hex number of the breakpoint ID in the signcolumn to -represent breakpoints. If it is greater than "0xFF", then it will be displayed -as "F+", due to we really only have two screen cells for the sign. -You may also use decimal breakpoint signs instead, in which case IDs greater -than 99 will be displayed as "9+". +represent breakpoints. If it is greater than "0xFF", then it will be +displayed as "F+", because there are only two screen cells available for the +sign. You may also use decimal breakpoint signs instead, in which case IDs +greater than 99 will be displayed as "9+". If you want to customize the breakpoint signs to show `>>` in the signcolumn: > let g:termdebug_config['sign'] = '>>' You can also specify individual signs for the first several breakpoints: > - let g:termdebug_config['signs'] = ['>1', '>2', '>3', '>4', '>5', '>6', '>7', '>8', '>9'] + let g:termdebug_config['signs'] = ['>1', '>2', '>3', '>4', '>5', + \ '>6', '>7', '>8', '>9'] let g:termdebug_config['sign'] = '>>' If you would like to use decimal (base 10) breakpoint signs: > let g:termdebug_config['sign_decimal'] = 1 @@ -1756,7 +1858,7 @@ Set the wide value to 1 to use a vertical split without ever changing Evaluate in Popup Window at Cursor ~ *termdebug_evaluate_in_popup* -By default |:Evaluate| will simply echo its output. For larger entities this +By default |:Evaluate| will simply echo its output. For larger entities this might become difficult to read or even truncated. Alternatively, the evaluation result may be output into a popup window at the current cursor position: > From 1e6f4e13ab3004ff433e6cb67fa09c646c594783 Mon Sep 17 00:00:00 2001 From: h_east Date: Sun, 26 Oct 2025 19:37:21 +0900 Subject: [PATCH 2/3] Update doc/terminal.jax Co-authored-by: Tsuyoshi CHO --- doc/terminal.jax | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/terminal.jax b/doc/terminal.jax index f8e49cfac..e43d9aa0a 100644 --- a/doc/terminal.jax +++ b/doc/terminal.jax @@ -1612,9 +1612,9 @@ gdb は奇妙な動作をしているが、プラグインはその問題を回 リモートデバッグ ~ *termdebug-remote* -リモートデバッグにおける主な問題の 1 つは、デバッグ対象のソースファイルへのア -クセスである。プラグインは、システムと Vim のネットワーク機能を使用してこの問題 -を回避できる。 +リモートデバッグにおける主な問題の 1 つは、デバッグ対象のソースファイルへのアク +セスである。プラグインは、システムと Vim のネットワーク機能を使用してこの問題を +回避できる。 *termdebug-remote-example* |termdebug-example| は、`gdb` デバッガーを実行して `ssh` 経由でアクセス可能な リモート Linux マシン上の Vim をデバッグすることで再現できる。 From 6bffe448c5b4ff508f9cf33d9fd6a4ac7af1bf95 Mon Sep 17 00:00:00 2001 From: h_east Date: Sun, 26 Oct 2025 19:39:43 +0900 Subject: [PATCH 3/3] Update doc/terminal.jax Co-authored-by: Tsuyoshi CHO --- doc/terminal.jax | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/terminal.jax b/doc/terminal.jax index e43d9aa0a..a494b8f3a 100644 --- a/doc/terminal.jax +++ b/doc/terminal.jax @@ -1640,8 +1640,8 @@ gdb は奇妙な動作をしているが、プラグインはその問題を回 :Termdebug vim これで、ローカルの例と同じ 3 つのウィンドウが表示され、同じ手順を実行できる。 -唯一の違いは、ソースウィンドウにローカルバッファではなくnetrwバッファが表示さ -れることである。 +唯一の違いは、ソースウィンドウにローカルバッファではなく netrw バッファが表示 +されることである。 *termdebug-substitute-path* `g:termdebug_config['substitute_path']` エントリを使用して、gdb の