Home Explore Blog CI



neovim

4th chunk of `runtime/doc/terminal.txt`
1a3d7e27f9f18b254be97be3777948217de0229be9fd061e0000000100000fa8
 window title or tab title of a graphical terminal emulator. Terminal
  programs can set this by emitting an escape sequence.
- |'channel'|  Terminal PTY |job-id|.  Can be used with |chansend()| to send
  input to the terminal.
- The |TermClose| event gives the terminal job exit code in the |v:event|
  "status" field. For example, this autocommand outputs the terminal's exit
  code to |:messages|: >vim
    autocmd TermClose * echom 'Terminal exited with status '..v:event.status

Use |jobwait()| to check if the terminal job has finished: >vim
    let running = jobwait([&channel], 0)[0] == -1
<
==============================================================================
:Termdebug plugin	*terminal-debug* *terminal-debugger* *package-termdebug*

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 ~
							*termdebug-starting*
Load the plugin with this command: >vim
	packadd termdebug
When loading the plugin from the |vimrc| file, add the "!" attribute: >vim
	packadd! termdebug
<							*:Termdebug*
To start debugging use `:Termdebug` or `:TermdebugCommand` followed by the
command name, for example: >vim
	:Termdebug vim

This opens two windows:

gdb window	A terminal window in which "gdb vim" is executed.  Here you
		can directly interact with 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 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.

Only one debugger can be active at a time.
							*:TermdebugCommand*
If you want to give specific commands to the command being debugged, you can
use the `:TermdebugCommand` command followed by the command name and
additional parameters. >vim
	:TermdebugCommand vim --clean -c ':set nu'

Both the `:Termdebug` and `:TermdebugCommand` support an optional "!" bang
argument to start the command right away, without pausing at the gdb window
(and cursor will be in the debugged window).  For example: >vim
	:TermdebugCommand! vim --clean

To attach gdb to an already running executable or use a core file, pass extra
arguments.  E.g.: >vim
	:Termdebug vim core
	:Termdebug vim 98343

If no argument is given, you'll end up in a gdb window, in which you need to
specify which command to run using e.g. the gdb `file` command.


Example session ~
							*termdebug-example*
Start in the Vim "src" directory and build Vim: >
	% make
Start Vim: >
	% ./vim
Load the termdebug plugin and start debugging Vim: >vim
	:packadd termdebug
	:Termdebug vim
You should now have three windows:
    source  - where you started
    gdb	    - you can type gdb commands here
    program - the executed program will use this window

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
	: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
breakpoint was set.  The line where the debugger stopped is highlighted.  You
can now step through the program.  You will see the highlighting move as the
debugger executes a line of source code.

Run ":Next" a few times until the for loop is highlighted.  Put the cursor on
the end of "eap->arg", then call ":Eval".

Title: Nvim's Termdebug Plugin: Debugging with GDB Inside Vim
Summary
This section describes the `:Termdebug` plugin, which allows debugging programs with gdb directly within Nvim, even remotely. It covers loading the plugin using `packadd termdebug`, starting debugging with `:Termdebug` or `:TermdebugCommand`, and explains the purpose of the gdb window, program window, and source code window. It also describes how to interact with the debugger, including setting breakpoints and stepping through code. The section concludes with an example session that demonstrates how to use the plugin to debug Vim itself.