Re: [PATCH v3 14/14] the "compile" command

[Eli Zaretskii <eliz at gnu dot org>]

> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> Date: Sat, 01 Nov 2014 22:47:33 +0100
> 
> diff --git a/gdb/NEWS b/gdb/NEWS
> index 649c29e..c4a6c6a 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS

This part is OK.

> +@value{GDBN} supports on-demand compilation and code injection into
> +programs running under @value{GDBN}.  GCC 5.0 or higher built with
> +@code{libcc1.so} must be installed for this functionality to be enabled.

libcc1.so should be in @file, not @code.

> +Compile @var{source} with the compiler language set as the current
> +language in @value{GDBN} (@pxref{Languages}).

Does the user need to set the language, or will the language from the
debug info be used, if available?  If the latter, the wording here
needs to be modified, as it currently implies one needs to set the
language "in GDB".

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

Which "this feature" needs to be supported by the compiler?

> +message will be printed.  If @var{source} compiles and links
> +successfully, @value{GDBN} will load the object-code emitted,

Judging by the example, I would suggest to use @var{source-code}
instead of @var{code}.

> +The command allows you to specify source code in two ways.  The simplest

@var{code}, so that the reader realizes you are talking about the
argument mentioned above.

> +Specifying @samp{-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_}.  The @samp{-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

I think an example of using 'raw' is in order; the description above
is not very clear.

> +@samp{#include} lines are better to be placed before the @samp{#pragma}
> +line.

Why? what happens if one doesn't?

>        The use of @samp{-raw} is considered to be expert usage, and care
> +should be taken when using it.

Like what?

This kind of remarks in documentation are "considered harmful": either
explain in detail what you mean, or don't say that at all.  Leaving
mysterious comments about "here be dragons" doesn't help the reader
understand how to use the feature correctly.

> +If the filename/path contains whitespace it must be enclosed in
> +quotes.

Which quotes? single? double?

> +There are a few caveats to keep in mind when using the @code{compile}
> +command.  As the caveats are different per language, the table below
> +highlights specific issues on a per language basis.

This and the following stuff is better put in its own subsection.

> +@code{C}.  Be aware that changes to inferior variables in the
> +@code{compile} command are persistent.  In the following example:
> +
> +@smallexample
> +compile code k = 3;
> +@end smallexample
> +
> +The variable @code{k} is now 3.

You want this line be continuation of the one before the example.  So:

 @noindent
 the variable @code{k} is now 3.

>                                   It will remain that value until
                                            ^^^^^^
"retain", not "remain".

> +something else in the example program changes it, or another
> +@code{compile} command changes it.

So why did you say the changes are persistent?  Persistent might mean
the value will be the same if the program is re-run.

> +Normal scope and access rules apply to source code compiled and injected
> +by the @code{compile} command.  In the example, the variables @code{j}
> +and @code{k} are not accessible; subsequent execution will bring these
> +variables into scope, and later, code written and compiled with the
> +@code{compile} command will be able to access them.  At this point the
> +program is stopped in the @code{main} function so the following example:
> +
> +@smallexample
> +compile code j = 3;
> +@end smallexample
> +
> +would result in a compilation error, and @value{GDBN} would print that
> +error to the console.

I needed to read this twice to understand what you mean.  Suggest to
reword as follows:

  Normal scope and access rules apply to source code compiled and
  injected by the @code{compile} command.  In the example, the variables
  @code{j} and @code{k} are not accessible yet, because the program is
  currently stopped in the @code{main} function, where these variables
  are not in scope.  Therefore, the following command

  @smallexample
  compile code j = 3;
  @end smallexample

  @noindent
  will result in a compilation error message.

  Once the program is continued, execution will bring these variables in
  scope, and they will become accessible; then the code you specify via
  the @code{compile} command will be able to access them.

> +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 @code{ff} no longer

Again, @noindend after the @example, and start "a compiler error" with
a lower-case letter, as this is a continuation of the sentence before
the example.

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

"... is removed when its execution ends" is better.  ("Completion of
the command" is not well-defined.)

>                                                        Caution is advised
> +when assigning variables belonging to the program with variables created
> +in the @code{compile} command.

"assigning to program variables values of variables created by the
code submitted to the @code{compile} command."

> +The @code{k} variable is assigned to the value of @code{ff}.  The variable
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
"The value of the variable @code{ff} is assigned to @code{k}."

> +@code{k} does not require the existence of @code{ff} to maintain the value
> +it has been assigned.  Pointers and other types of references require

"However, pointers ..."

What "other types"?  How about one or two examples?

> +location when the command exists.  A general rule should be followed
> +in that you should either assign @code{NULL} to any assigned pointers,
> +or restore a valid location to the pointer before the command exits.

Why NULL?  Any constant address will do, right?

> +Similar caution must be exercised with any types defined in
> +@code{compile} command.

I would explain what you mean by "defined types" here.  I'm guessing
you mean structs, unions, and typedefs, but let's say this explicitly.

>                             Types defined in the @code{compile} are also
> +deleted when the command exits.

I think types are not deleted, they simply don't exist in compiled
code.  Right?

>                                    Therefore, if you cast a variable to a
> +type defined in the @code{compile} command, care must be taken to ensure
> +that any future need to resolve the type can be achieved.

I don't understand the meaning of this.  Defining a type and casting
to a type are two different things, so what does this text warn about?

> +Variables that have been optimized away by the compiler are not
> +accessible to the @code{compile} command.

"... not accessible to the code submitted to the @code{compile} command"

Thanks.