From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 13751 invoked by alias); 16 Jun 2014 15:25:17 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 13741 invoked by uid 89); 16 Jun 2014 15:25:16 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.8 required=5.0 tests=AWL,BAYES_20,RCVD_IN_DNSWL_NONE,SPF_SOFTFAIL autolearn=no version=3.3.2 X-HELO: mtaout22.012.net.il Received: from mtaout22.012.net.il (HELO mtaout22.012.net.il) (80.179.55.172) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Mon, 16 Jun 2014 15:25:14 +0000 Received: from conversion-daemon.a-mtaout22.012.net.il by a-mtaout22.012.net.il (HyperSendmail v2007.08) id <0N7900I00P83CE00@a-mtaout22.012.net.il> for gdb-patches@sourceware.org; Mon, 16 Jun 2014 18:25:11 +0300 (IDT) Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout22.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0N7900IRSPHT2T60@a-mtaout22.012.net.il>; Mon, 16 Jun 2014 18:25:05 +0300 (IDT) Date: Mon, 16 Jun 2014 15:25:00 -0000 From: Eli Zaretskii Subject: Re: (Doc ping [for news and manual]) -- [PATCH 14/14] the "compile" command In-reply-to: <539EBEF2.5010703@redhat.com> To: Phil Muldoon Cc: gdb-patches@sourceware.org, tromey@redhat.com Reply-to: Eli Zaretskii Message-id: <83ha3kvpv5.fsf@gnu.org> References: <1400253995-12333-1-git-send-email-tromey@redhat.com> <1400253995-12333-15-git-send-email-tromey@redhat.com> <539EBEF2.5010703@redhat.com> X-IsSubscribed: yes X-SW-Source: 2014-06/txt/msg00557.txt.bz2 > Date: Mon, 16 Jun 2014 10:54:58 +0100 > From: Phil Muldoon > CC: Tom Tromey , "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.