runtime/termdebug.vim #8364

* commit 36257d0f97b396467bef7a5937befd894fb23e31
Author: Kwon-Young Choi <kwon-young.choi@hotmail.fr>
Date:   Sat May 5 16:57:45 2018 +0200

    Port of the termdebug.vim plugin to neovim terminal feature.
    For neovim compatibility,
    The vim specific calls were replaced with neovim specific calls:
      term_start -> term_open
      term_sendkeys -> jobsend
      term_getline -> getbufline
      job_info && term_getjob -> using linux command ps to get the tty

    fix1: forgot to port EndDebug callback to neovim

    fix2: use nvim_get_chan_info to get pty of job
          remove the use of communication buffer by using jobstart instead
          of termopen

    fix3: get gdbbuf using nvim_get_chan_info

* cleaned up if has('nvim') to remove vim support.
added neovim floating window support for expression evaluation

* improvred documentation, cleaned up vim menu code, fixed bug when
floating window feature is not available

1 files changed, 253 insertions, 0 deletions

diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt
index cfaec12520..fe5506fc4c 100644
--- a/runtime/doc/nvim_terminal_emulator.txt
+++ b/runtime/doc/nvim_terminal_emulator.txt
@@ -131,4 +131,257 @@ a local 'statusline'. Example: >
     :autocmd TermOpen * setlocal statusline=%{b:term_title}
 <
 ==============================================================================
+5. Debugging				*terminal-debug* *terminal-debugger*
+
+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: >
+	packadd termdebug
+<							*:Termdebug*
+To start debugging use `:Termdebug` or `:TermdebugCommand` followed 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.
+
+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. >
+	: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: >
+	:TermdebugCommand! vim --clean
+
+To attach gdb to an already running executable or use a core file, pass extra
+arguments.  E.g.: >
+	: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: >
+	: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: >
+	: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".  You will see this displayed:
+	"eap->arg": 0x555555e68855 "gui" ~
+This way you can inspect the value of local variables.  You can also focus the
+gdb window and use a "print" command, e.g.: >
+	print *eap
+If mouse pointer movements are working, Vim will also show a balloon when the
+mouse rests on text that can be evaluated by gdb.
+You can also use the "K" mapping that will either use neovim floating windows
+if available to show the results or print below the status bar.
+
+Now go back to the source window and put the cursor on the first line after
+the for loop, then type: >
+	:Break
+You will see a "1" marker appear, this indicates the new breakpoint.  Now
+run ":Cont" command and the code until the breakpoint will be executed.
+
+You can type more advanced commands in the gdb window.  For example, type: >
+	watch curbuf
+Now run ":Cont" (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
+
+You can see the stack by typing in the gdb window: >
+	where
+Move through the stack frames, e.g. with: >
+	frame 3
+The source window will show the code, at the point where the call was made to
+a deeper level.
+
+
+Stepping through code ~
+							*termdebug-stepping*
+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
+
+						*:Run* *:Arguments*
+In the window showing the source code these commands can be used to control
+gdb:
+ `:Run` [args]	    run the program with [args] or the previous arguments
+ `:Arguments` {args}  set arguments for the next `:Run`
+
+ *:Break*	set a breakpoint at the current line; a sign will be displayed
+ *:Clear*	delete the 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
+ *:Stop*	interrupt the program
+
+If gdb stops at a source line and there is no window currently showing the
+source code, a new window will be created for the source code.  This also
+happens if the buffer in the source code window has been modified and can't be
+abandoned.
+
+Gdb gives each breakpoint a number.  In Vim the number shows up in the sign
+column, with a red background.  You can use these gdb commands:
+- info break	list breakpoints
+- delete N	delete breakpoint N
+You can also use the `:Clear` command if the cursor is in the line with the
+breakpoint, or use the "Clear breakpoint" right-click menu entry.
+
+
+Inspecting variables ~
+					*termdebug-variables* *:Evaluate*
+ `: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.
+You can usually shorten `:Evaluate` to `:Ev`.
+
+
+Other commands ~
+							*termdebug-commands*
+ *:Gdb*	     jump to the gdb window
+ *:Program*    jump to the window with the running program
+ *:Source*     jump to the window with the source code, create it if there
+	     isn't one
+
+
+Communication ~
+						*termdebug-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.
+
+Gdb has some weird behavior, the plugin does its best to work around that.
+For example, after typing "continue" in the gdb window a CTRL-C can be used to
+interrupt the running program.  But after using the MI command
+"-exec-continue"  pressing CTRL-C does not interrupt.  Therefore you will see
+"continue" being used for the `:Continue` command, instead of using the
+communication channel.
+
+
+Customizing ~
+
+GDB command						 *termdebug-customizing*
+
+To change the name of the gdb command, set the "termdebugger" variable before
+invoking `:Termdebug`: >
+	let termdebugger = "mygdb"
+
+To use neovim floating windows for previewing variable evaluation, set the
+`g:termdebug_useFloatingHover` variable like this: >
+	let g:termdebug_useFloatingHover = 1
+
+If you are a mouse person, you can also define a mapping using your right
+click to one of the terminal command like evaluate the variable under the
+cursor: >
+      	nnoremap <RightMouse> :Evaluate<CR>
+or set/unset a breakpoint: >
+	nnoremap <RightMouse> :Break<CR>
+
+<							*gdb-version*
+Only debuggers fully compatible with gdb will work.  Vim uses the GDB/MI
+interface.  The "new-ui" command  requires gdb version 7.12 or later.  if you
+get this error:
+	Undefined command: "new-ui". Try "help".~
+Then your gdb is too old.
+
+
+Colors						*hl-debugPC* *hl-debugBreakpoint*
+
+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
+
+
+Shorcuts						*termdebug_shortcuts*
+
+You can define your own shortcuts (mappings) to control gdb, that can work in
+any window, using the TermDebugSendCommand() function.  Example: >
+	map ,w :call TermDebugSendCommand('where')<CR>
+The argument is the gdb command.
+
+
+Vim window width						*termdebug_wide*
+
+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.
+If g:termdebug_wide is set and &columns is already larger than
+g:termdebug_wide then a vertical split will be used without changing &columns.
+Set it to 1 to get a vertical split without every changing &columns (useful
+for when the terminal can't be resized by Vim).
+
+
+
  vim:tw=78:ts=8:noet:ft=help:norl: