[binutils-gdb] [DOC] Document support for running interpreters on separate UIs

[Pedro Alves <palves at sourceware dot org>]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=86f78169c82095eced3a4d1b30f8e002ec841d79

commit 86f78169c82095eced3a4d1b30f8e002ec841d79
Author: Pedro Alves <palves@redhat.com>
Date:   Tue Jun 21 01:11:55 2016 +0100

    [DOC] Document support for running interpreters on separate UIs
    
    gdb/ChangeLog:
    2016-06-21  Pedro Alves  <palves@redhat.com>
    
    	* NEWS: Mention support for running interpreters on separate
    	UIs and the new new-ui command.
    
    gdb/doc/ChangeLog:
    2016-06-21  Pedro Alves  <palves@redhat.com>
    
    	* gdb.texinfo (Interpreters): Update intepreter-exec section,
    	document new-ui and explain use case.

Diff:
---
 gdb/ChangeLog       |  5 +++++
 gdb/NEWS            | 18 +++++++++++++++++
 gdb/doc/ChangeLog   |  5 +++++
 gdb/doc/gdb.texinfo | 56 +++++++++++++++++++++++++++++++++++++++++++----------
 4 files changed, 74 insertions(+), 10 deletions(-)

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index 45e41f1..99b8059 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,5 +1,10 @@
 2016-06-21  Pedro Alves  <palves@redhat.com>
 
+	* NEWS: Mention support for running interpreters on separate
+	UIs and the new new-ui command.
+
+2016-06-21  Pedro Alves  <palves@redhat.com>
+
 	* interps.c (set_top_level_interpreter): New function, factored
 	out from captured_main.
 	(interpreter_completer): Make extern.
diff --git a/gdb/NEWS b/gdb/NEWS
index 340a751..3823f20 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -46,6 +46,20 @@
   language.  See https://www.rust-lang.org/ for more information about
   Rust.
 
+* Support for running interpreters on specified input/output devices
+
+  GDB now supports a new mechanism that allows frontends to provide
+  fully featured GDB console views, as a better alternative to
+  building such views on top of the "-interpreter-exec console"
+  command.  See the new "new-ui" command below.  With that command,
+  frontends can now start GDB in the traditional command-line mode
+  running in an embedded terminal emulator widget, and create a
+  separate MI interpreter running on a specified i/o device.  In this
+  way, GDB handles line editing, history, tab completion, etc. in the
+  console all by itself, and the GUI uses the separate MI interpreter
+  for its own control and synchronization, invisible to the command
+  line.
+
 * New commands
 
 skip -file file
@@ -62,6 +76,10 @@ maint info line-table REGEXP
 maint selftest
   Run any GDB unit tests that were compiled in.
 
+new-ui INTERP TTY
+  Start a new user interface instance running INTERP as interpreter,
+  using the TTY file for input/output.
+
 * Support for tracepoints and fast tracepoints on s390-linux and s390x-linux
   was added in GDBserver, including JIT compiling fast tracepoint's
   conditional expression bytecode into native code.
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 1af71e5..3186ff2 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,8 @@
+2016-06-21  Pedro Alves  <palves@redhat.com>
+
+	* gdb.texinfo (Interpreters): Update intepreter-exec section,
+	document new-ui and explain use case.
+
 2016-06-17  Yan-Ting Lin  <currygt52@gmail.com>
 
 	* gdb.texinfo (Standard Target Features): Document NDS32 features.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 795a70b..a068622 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -24911,18 +24911,11 @@ The @sc{gdb/mi} interface included in @value{GDBN} 5.1, 5.2, and 5.3.
 @end table
 
 @cindex invoke another interpreter
-The interpreter being used by @value{GDBN} may not be dynamically
-switched at runtime.  Although possible, this could lead to a very
-precarious situation.  Consider an IDE using @sc{gdb/mi}.  If a user
-enters the command "interpreter-set console" in a console view,
-@value{GDBN} would switch to using the console interpreter, rendering
-the IDE inoperable!
 
 @kindex interpreter-exec
-Although you may only choose a single interpreter at startup, you may execute
-commands in any interpreter from the current interpreter using the appropriate
-command.  If you are running the console interpreter, simply use the
-@code{interpreter-exec} command:
+You may execute commands in any interpreter from the current
+interpreter using the appropriate command.  If you are running the
+console interpreter, simply use the @code{interpreter-exec} command:
 
 @smallexample
 interpreter-exec mi "-data-list-register-names"
@@ -24931,6 +24924,49 @@ interpreter-exec mi "-data-list-register-names"
 @sc{gdb/mi} has a similar command, although it is only available in versions of
 @value{GDBN} which support @sc{gdb/mi} version 2 (or greater).
 
+Note that @code{interpreter-exec} only changes the interpreter for the
+duration of the specified command.  It does not change the interpreter
+permanently.
+
+@cindex start a new independent interpreter
+
+Although you may only choose a single interpreter at startup, it is
+possible to run an independent interpreter on a specified input/output
+device (usually a tty).
+
+For example, consider a debugger GUI or IDE that wants to provide a
+@value{GDBN} console view.  It may do so by embedding a terminal
+emulator widget in its GUI, starting @value{GDBN} in the traditional
+command-line mode with stdin/stdout/stderr redirected to that
+terminal, and then creating an MI interpreter running on a specified
+input/output device.  The console interpreter created by @value{GDBN}
+at startup handles commands the user types in the terminal widget,
+while the GUI controls and synchronizes state with @value{GDBN} using
+the separate MI interpreter.
+
+To start a new secondary @dfn{user interface} running MI, use the
+@code{new-ui} command:
+
+@kindex new-ui
+@cindex new user interface
+@smallexample
+new-ui @var{interpreter} @var{tty}
+@end smallexample
+
+The @var{interpreter} parameter specifies the interpreter to run.
+This accepts the same values as the @code{interpreter-exec} command.
+For example, @samp{console}, @samp{mi}, @samp{mi2}, etc.  The
+@var{tty} parameter specifies the name of the bidirectional file the
+interpreter uses for input/output, usually the name of a
+pseudoterminal slave on Unix systems.  For example:
+
+@smallexample
+(@value{GDBP}) new-ui mi /dev/pts/9
+@end smallexample
+
+@noindent
+runs an MI interpreter on @file{/dev/pts/9}.
+
 @node TUI
 @chapter @value{GDBN} Text User Interface
 @cindex TUI