Re: (Doc ping [for news and manual]) -- [PATCH 14/14] the "compile" command

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Mon, 16 Jun 2014 10:54:58 +0100
> From: Phil Muldoon <pmuldoon@redhat.com>
> CC: Tom Tromey <tromey@redhat.com>, "eliz@gnu.org" <eliz@gnu.org>
> 
> On 16/05/14 16:26, Tom Tromey wrote:

Sorry, I guess I missed the fact that this large patch included docs.

> diff --git a/gdb/NEWS b/gdb/NEWS
> index d0c44ea..6829f5b 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -3,6 +3,16 @@
>  
>  *** Changes since GDB 7.7
>  
> +* GDB now supports the compilation and injection of source code into
> +  the inferior.  GDB will use a feature-capable compiler to compile
> +  the source code to object code, and if successful, inject and
> +  execute that code within the current context of the inferior.
> +  Currently the "C" language is supported.  The commands used to

C without quotes, please.

> +compile code [-r|-raw] [--] [source code]
> +  Compile and inject into the inferior the executable object code
> +  produced by compiling the provided source code.  This resulting
> +  object code will be executed within the current context of the
> +  inferior, allowing access to variables, types and other elements
> +  that are currently within scope.  The -raw option will prevent GDB
> +  automatically wrapping the source code into a callable scope (this
> +  will have to be provided in the source code, and is considered
> +  expert level usage).  The "--" option indicates that all text to the
> +  right of the "--" is to be considered as source code, and will not
> +  be considered for option parsing.
> +
> +compile file [-r|-raw] filename
> +  Compile and inject into the inferior the executable object code
> +  produced by compiling the source code stored in the filename
> +  provided.  This resulting object code will be executed within the
> +  current context of the inferior, allowing access to variables, types
> +  and other elements that are currently within scope.  The -raw option
> +  will prevent GDB automatically wrapping the source code into a
> +  callable scope (this will have to be provided in the source code,
> +  and is considered expert level usage).

This is too voluminous for NEWS.  Just leave the 1st sentence of each
paragraphs, it's enough.

> +* Compiling and Injecting Code:: Compiling and injecting code in GDB
                                                                      ^^^
@value{GDBN}

> +@node Compiling and Injecting Code
> +@section Compiling and injecting code in GDB

Likewise.

> +@cindex injecting code
> +@cindex writing into executables
> +@cindex compiling code
> +
> +@value{GDBN} supports on-demand compilation and code injection into
> +programs running under GDB.  A suitable compiler must be installed for

Likewise.

> +Compile @var{source} using the language set in @value{GDBN}
> +(@pxref{Languages}), as the compilation language type.
                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
I don't understand what was meant by the highlighted part.  What is
"compilation language type"?

>                                                         If compilation
> +and injection is not supported with the current language specified in
> +@value{GDBN}, or the compiler does not support this feature

I think it would be good to say here which compiler(s) in what
version(s) started supporting this feature.

> +compiles and links successfully, @value{GDBN} will load the object-code
> +emitted, and execute it within the context of the currently selected
> +inferior.

When you say "and execute it", you don't mean right away, yes?
Because that's what the text conveys.  Will the execution commence
immediately, or only when the program counter gets to this code?

> +@code{_gdb_expr_}.  @samp{-@var{raw}} code does not automatically access

Please insert "The" before @samp here, so that the sentence doesn't
start with a lower-case letter.

> +@item compile file @var{filename}
> +@itemx compile file -@var{raw} @var{filename}
> +Load source code from the file specified by @var{filename}, and compile
> +it using the language set in @value{GDBN} (@pxref{Languages}), as the
> +compilation language type.  If compilation and injection is not
> +supported with the current language specified in @value{GDBN}, or the
> +compiler does not support this feature, an error message will be printed
> +and the command will exit.  If the source-code contained within
> +@var{filename} compiles and links successfully, @value{GDBN} will load
> +the object-code emitted, and execute it within the context of the
> +currently selected inferior.

This repeats almost verbatim what you already said when describing the
previous command.  I suggest something like

 @item compile file @var{filename}
 @itemx compile file -@var{raw} @var{filename}
 Like @code{compile code}, but take the source code from @var{filename}.

> +@smallexample
> +compile file /home/user/example.c
> +@end smallexample

Does this support file names with whitespace characters?  If so, does
one need to use quotes in such cases?

> +Specifying @samp{-@var{raw}}, prohibits @value{GDBN} from wrapping the
> +provided @var{source} in a callable scope.  In this case, you must
> +specify the entry point of the code by defining a function named
> +@code{_gdb_expr_}.  @samp{-@var{raw}} code does not automatically access
> +variables of the inferior, for their import you must use
> +the @samp{#pragma} line first:
> +
> +@smallexample
> +#pragma GCC user_expression
> +@end smallexample
> +
> +@samp{#include} lines are better to be placed before the @samp{#pragma}
> +line.  The use of @var{raw} is considered to be expert usage, and care
> +should be taken when using it.
> +@end table

Likewise: this is repetition.  If you accept my proposal above, you
will be able to delete this part altogether.

> +There are a few caveats to keep in mind when using the compile command.
                                                          ^^^^^^^
@code{compile}

> +@table @code
> +@item C code examples and caveats

@code is not appropriate here, as the items are not program symbols,
just text; use @asis instead.

> +When the language in @value{GDBN} is set to @samp{C}, the compiler will
> +attempt to compile the source code with a @samp{C} compiler.  The source

This begs the question: how will GDB know which compiler to invoke and
by what name?

> +Currently, as @value{GDBN} has stopped the program in the @samp{main}
> +function, the @samp{compile} command would have access to the variable
> +@var{k}.  You could invoke the @samp{compile} command and type some
> +source code to set the value of @var{k}.  You can also read it, or do

Here and elsewhere, you use @var where you should use @code.  All the
symbols in the examples' program source should have @code markup,
because they are literal symbols, not placeholders for other symbols.

> +You can create variables and types with the @samp{compile} command as
> +part of your source code.  Variables and types that are created as part
> +of the @samp{compile} command are not persistent, and only exist as
> +long as the injected object code exists.  This example is valid:
> +
> +@smallexample
> +compile code int ff = 5; printf ("ff is %d\n", ff);
> +@end smallexample
> +
> +However, if you were to type the following into @value{GDBN} after that
> +command has completed:
> +
> +@smallexample
> +compile code printf ("ff is %d\n'', ff);
> +@end smallexample
> +
> +A compiler error would be raised as the variable @var{ff} no longer
> +exists.

This text hints, for the first time, that the compiled code is thrown
away once it finishes execution.

>           Object code generated and injected by the @samp{compile}
> +command is removed on completion of the command.

This sentence, which tells that explicitly, should have been much
earlier, since this is a very important issue, that shouldn't be
buried in the examples.

> +exists.  A general rule should be followed in that you should either
> +assign NULL to any assigned pointers, or restore a valid location to the

@code{NULL} (it is a symbol).

> +Similar caution must be exercised with any types defined in
> +@samp{compile} command.  Types defined in the @samp{compile} are also
> +deleted when the command exits.  Therefore, if you cast a variable to a
> +type defined in the @samp{compile} command, care must be taken to ensure
> +that any future need to resolve the type can be achieved.

This also should be described with the commands, not in the examples.

> +Variables that have been optimized away by the compiler are not
> +accessible to the @samp{compile} command.  Access to those variables
> +will generate a compiler error which @value{GDBN} will print to the console.
> +@end table

Can the compile command access registers?

Thanks.