[PATCH v3 30/34] [DOC] Document support for running interpreters on separate UI channels

Pedro Alves
2016-05-06T12:42:54Z

gdb/ChangeLog:
yyyy-mm-dd Pedro Alves <palves@redhat.com>

* NEWS: Mention support for running interpreters on separate
channels and the new new-ui command.

gdb/doc/ChangeLog:
yyyy-mm-dd Pedro Alves <palves@redhat.com>

* gdb.texinfo (Interpreters): Update intepreter-exec section,
document new-ui and explain use case.
---
gdb/doc/gdb.texinfo | 55 +++++++++++++++++++++++++++++++++++++++++++----------
gdb/NEWS | 16 ++++++++++++++++
2 files changed, 61 insertions(+), 10 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index f74c41c..c89486d 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -24805,18 +24805,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"
@@ -24825,6 +24818,48 @@ 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 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 separate channel.
+
+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
+window widget in its GUI, starting @value{GDBN} with the default
+console interpreter running on that terminal, and then opening a
+secondary communication channel running the MI interpreter. 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
+channel.
+
+To start a new secondary @dfn{user interface} channel 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
diff --git a/gdb/NEWS b/gdb/NEWS
index 7bf1e1a..c280300 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -27,6 +27,18 @@
Bounds: [lower = 0x7fffffffc390, upper = 0x7fffffffc3a3]
0x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68

+* Support for running interpreters on separate channels
+
+ 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 console mode running on an embedded
+ terminal widget, and open a separate MI channel for the usual MI
+ control and synchronization invisible to the user. In this way, GDB
+ handles line editing, history, tab completion, etc. in the console
+ all by itself.
+
* New commands

skip -file file
@@ -40,6 +52,10 @@ skip -rfunction regular-expression
maint info line-table REGEXP
Display the contents of GDB's internal line table data struture.

+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.
--
2.5.5