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

Pedro Alves
2016-06-17T17:24:10Z

On 05/26/2016 12:11 PM, Pedro Alves wrote:
> On 05/06/2016 02:04 PM, Eli Zaretskii wrote:
>>> From: Pedro Alves <palves@redhat.com>
>>> Date: Fri, 6 May 2016 13:35:00 +0100
>>>
>>> +Although you may only choose a single interpreter at startup, it is
>>> +possible to run an independent interpreter on a separate channel.
>>
>> "Channel"? What's that? Can we find a better word?
>>
>> No other comments to the doc part. Thanks.
>
> Thanks Eli. Here's an attempt at clarifying things, using
> the same terminology already used in other related commands.

Hi Eli. I'm not sure whether the "no other comments" remark
meant pre-approval, or whether this slipped through
the cracks. FAOD, is the below OK?

Thanks,
Pedro Alves

>
> From b58b402641e5cb5d0cbdf3bc2a815ada244be4c5 Mon Sep 17 00:00:00 2001
> From: Pedro Alves <palves@redhat.com>
> Date: Thu, 5 May 2016 13:06:03 +0100
> Subject: [PATCH 30/34] [DOC] Document support for running interpreters on
> separate UIs
>
> gdb/ChangeLog:
> yyyy-mm-dd Pedro Alves <palves@redhat.com>
>
> * NEWS: Mention support for running interpreters on separate
> UIs 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 | 56 +++++++++++++++++++++++++++++++++++++++++++----------
> gdb/NEWS | 18 +++++++++++++++++
> 2 files changed, 64 insertions(+), 10 deletions(-)
>
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index f74c41c..a302d6e 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,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
> diff --git a/gdb/NEWS b/gdb/NEWS
> index 7bf1e1a..c6ed63d 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -27,6 +27,20 @@
> Bounds: [lower = 0x7fffffffc390, upper = 0x7fffffffc3a3]
> 0x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68
>
> +* 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
> @@ -40,6 +54,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.
>