[29/29] Document new Python and Guile constants
Checks
Context |
Check |
Description |
linaro-tcwg-bot/tcwg_gdb_build--master-aarch64 |
success
|
Testing passed
|
linaro-tcwg-bot/tcwg_gdb_build--master-arm |
success
|
Testing passed
|
linaro-tcwg-bot/tcwg_gdb_check--master-aarch64 |
success
|
Testing passed
|
linaro-tcwg-bot/tcwg_gdb_check--master-arm |
success
|
Testing passed
|
Commit Message
This documents the new Python and Guile constants introduced earlier
in this series.
---
gdb/NEWS | 12 ++++++++++++
gdb/doc/guile.texi | 13 +++++++++++++
gdb/doc/python.texi | 30 +++++++++++++++++++++++++++---
3 files changed, 52 insertions(+), 3 deletions(-)
Comments
> From: Tom Tromey <tom@tromey.com>
> Date: Mon, 20 Nov 2023 20:54:00 -0700
>
> This documents the new Python and Guile constants introduced earlier
> in this series.
Thanks.
> diff --git a/gdb/NEWS b/gdb/NEWS
> index 1073e38dfc6..93fee9a8044 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -57,6 +57,18 @@ show remote thread-options-packet
> sub-classed to create handlers for objfiles with missing debug
> information.
>
> + ** New constants gdb.SYMBOL_TYPE_DOMAIN, gdb.SYMBOL_FUNCTION_DOMAIN,
> + and gdb.SEARCH_*_DOMAIN corresponding to all the existing symbol
> + domains. Symbol lookup can now search in multiple domains at
> + once, and can also narrowly search for just a type or function.
> +
> +* Guile API
> +
> + ** New constants SYMBOL_TYPE_DOMAIN, SYMBOL_FUNCTION_DOMAIN, and
> + SEARCH_*_DOMAIN corresponding to all the existing symbol domains.
> + Symbol lookup can now search in multiple domains at once, and can
> + also narrowly search for just a type or function.
> +
> * New remote packets
This part is OK.
> +@item SYMBOL_TYPE_DOMAIN
> +This domain contains types. In a C-like language, types using a tag
> +will not appear here; in other languages, all types are in this
> +domain.
I suggest an example here to explain what is a "type using a tag"; it
was not clear to me, FWIW.
> +When searching for a symbol, the desired domain constant can be passed
> +verbatim to the lookup function. For more complex searches, there is
> +a corresponding set of constants using a @samp{SEARCH_} prefix. These
> +may be or'd together to form a search constant.
Not sure this is clear enough without a couple of examples, either.
Specifically, it is not clear which "constants" are being alluded to
here, and how to construct these constants.
> +@vindex SYMBOL_TYPE_DOMAIN
> +@item gdb.SYMBOL_TYPE_DOMAIN
> +This domain contains types. In a C-like language, types using a tag
> +will not appear here; in other languages, all types are in this
> +domain.
>
> @vindex SYMBOL_STRUCT_DOMAIN
> @item gdb.SYMBOL_STRUCT_DOMAIN
> -This domain holds struct, union and enum type names.
> +This domain holds struct, union and enum tag names. This domain is
> +only used for C-like languages.
Same comment about "types using a tag" here.
> +When searching for a symbol, the desired domain constant can be passed
> +verbatim to the lookup function. For example:
> +@smallexample
> +symbol = gdb.lookup_symbol ("name", domain=gdb.SYMBOL_VAR_DOMAIN)
> +@end smallexample
> +
> +For more complex searches, there is a corresponding set of constants
> +using a @samp{SEARCH_} prefix. These may be or'd together to form a
> +search constant, e.g.:
> +@smallexample
> +symbol = gdb.lookup_symbol ("name",
> + domain=gdb.SEARCH_VAR_DOMAIN | gdb.SEARCH_TYPE_DOMAIN)
> +@end smallexample
This is better than what we have in guile.texi, due to the example,
but it reveals that indeed just saying "set of constants using
'SEARCH_' prefix" is not enough, because you don't say that the
'SYMBOL_' prefix should be removed.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:
>> From: Tom Tromey <tom@tromey.com>
>> Date: Mon, 20 Nov 2023 20:54:00 -0700
>>
>> This documents the new Python and Guile constants introduced earlier
>> in this series.
Eli> Thanks.
...
Eli> I suggest an example here to explain what is a "type using a tag"; it
Eli> was not clear to me, FWIW.
...
I missed this review before sending v2.
I've updated the doc patch. The new version is appended, let me know
what you think.
Tom
commit 439edc10f654d10e49b3235562aafeb941c03302
Author: Tom Tromey <tom@tromey.com>
Date: Sat Nov 18 10:00:12 2023 -0700
Document new Python and Guile constants
This documents the new Python and Guile constants introduced earlier
in this series.
diff --git a/gdb/NEWS b/gdb/NEWS
index bab300e36b8..2638b3e0d9c 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -108,6 +108,11 @@ show remote thread-options-packet
object, these will be stored in the object's new
InferiorThread.__dict__ attribute.
+ ** New constants gdb.SYMBOL_TYPE_DOMAIN, gdb.SYMBOL_FUNCTION_DOMAIN,
+ and gdb.SEARCH_*_DOMAIN corresponding to all the existing symbol
+ domains. Symbol lookup can now search in multiple domains at
+ once, and can also narrowly search for just a type or function.
+
* Debugger Adapter Protocol changes
** GDB now emits the "process" event.
@@ -121,6 +126,13 @@ show remote thread-options-packet
** The "set debug dap-log-file" command is now documented. This
command was available in GDB 14 but not documented.
+* Guile API
+
+ ** New constants SYMBOL_TYPE_DOMAIN, SYMBOL_FUNCTION_DOMAIN, and
+ SEARCH_*_DOMAIN corresponding to all the existing symbol domains.
+ Symbol lookup can now search in multiple domains at once, and can
+ also narrowly search for just a type or function.
+
* New remote packets
New stop reason: clone
diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi
index 271b672fdc6..7326186941d 100644
--- a/gdb/doc/guile.texi
+++ b/gdb/doc/guile.texi
@@ -2802,8 +2802,24 @@ in the symbol information or in @value{GDBN}'s handling of symbols.
This domain contains variables, function names, typedef names and enum
type values.
+@item SYMBOL_FUNCTION_DOMAIN
+This domain contains functions.
+
+@item SYMBOL_TYPE_DOMAIN
+This domain contains types. In a C-like language, types using a tag
+(the name appearing after a @code{struct}, @code{union}, or
+@code{enum} keyword) will not appear here; in other languages, all
+types are in this domain.
+
@item SYMBOL_STRUCT_DOMAIN
-This domain holds struct, union and enum type names.
+This domain holds struct, union and enum tag names. This domain is
+only used for C-like languages. For example, in this code:
+@smallexample
+struct type_one @{ int x; @};
+typedef struct type_one type_two;
+@end smallexample
+Here @code{type_one} will be in @code{SYMBOL_STRUCT_DOMAIN}, but
+@code{type_two} will be in @code{SYMBOL_TYPE_DOMAIN}.
@item SYMBOL_LABEL_DOMAIN
This domain contains names of labels (for gotos).
@@ -2822,6 +2838,15 @@ This domain contains all types.
The available address class categories in @code{<gdb:symbol>} are represented
as constants in the @code{gdb} module:
+When searching for a symbol, the desired domain constant can be passed
+verbatim to the lookup function.
+
+For more complex searches, there is a corresponding set of constants,
+each named after one of the preceding constants, but with the
+@samp{SEARCH} prefix replacing the @samp{SYMBOL} prefix; for example,
+@code{SEARCH_LABEL_DOMAIN}. These may be or'd together to form a
+search constant.
+
@vtable @code
@item SYMBOL_LOC_UNDEF
If this is returned by address class, it indicates an error either in
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 71431878dd3..ece9038844c 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -6214,12 +6214,29 @@ in the symbol information or in @value{GDBN}'s handling of symbols.
@vindex SYMBOL_VAR_DOMAIN
@item gdb.SYMBOL_VAR_DOMAIN
-This domain contains variables, function names, typedef names and enum
-type values.
+This domain contains variables.
+
+@vindex SYMBOL_FUNCTION_DOMAIN
+@item gdb.SYMBOL_FUNCTION_DOMAIN
+This domain contains functions.
+
+@vindex SYMBOL_TYPE_DOMAIN
+@item gdb.SYMBOL_TYPE_DOMAIN
+This domain contains types. In a C-like language, types using a tag
+(the name appearing after a @code{struct}, @code{union}, or
+@code{enum} keyword) will not appear here; in other languages, all
+types are in this domain.
@vindex SYMBOL_STRUCT_DOMAIN
@item gdb.SYMBOL_STRUCT_DOMAIN
-This domain holds struct, union and enum type names.
+This domain holds struct, union and enum tag names. This domain is
+only used for C-like languages. For example, in this code:
+@smallexample
+struct type_one @{ int x; @};
+typedef struct type_one type_two;
+@end smallexample
+Here @code{type_one} will be in @code{SYMBOL_STRUCT_DOMAIN}, but
+@code{type_two} will be in @code{SYMBOL_TYPE_DOMAIN}.
@vindex SYMBOL_LABEL_DOMAIN
@item gdb.SYMBOL_LABEL_DOMAIN
@@ -6234,6 +6251,22 @@ This domain contains names of Fortran module types.
This domain contains names of Fortran common blocks.
@end vtable
+When searching for a symbol, the desired domain constant can be passed
+verbatim to the lookup function. For example:
+@smallexample
+symbol = gdb.lookup_symbol ("name", domain=gdb.SYMBOL_VAR_DOMAIN)
+@end smallexample
+
+For more complex searches, there is a corresponding set of constants,
+each named after one of the preceding constants, but with the
+@samp{SEARCH} prefix replacing the @samp{SYMBOL} prefix; for example,
+@code{SEARCH_LABEL_DOMAIN}. These may be or'd together to form a
+search constant, e.g.:
+@smallexample
+symbol = gdb.lookup_symbol ("name",
+ domain=gdb.SEARCH_VAR_DOMAIN | gdb.SEARCH_TYPE_DOMAIN)
+@end smallexample
+
The available address class categories in @code{gdb.Symbol} are represented
as constants in the @code{gdb} module:
> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>, gdb-patches@sourceware.org
> Date: Mon, 22 Jan 2024 17:34:48 -0700
>
> >>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:
>
> >> From: Tom Tromey <tom@tromey.com>
> >> Date: Mon, 20 Nov 2023 20:54:00 -0700
> >>
> >> This documents the new Python and Guile constants introduced earlier
> >> in this series.
>
> Eli> Thanks.
>
> ...
>
> Eli> I suggest an example here to explain what is a "type using a tag"; it
> Eli> was not clear to me, FWIW.
>
> ...
>
> I missed this review before sending v2.
> I've updated the doc patch. The new version is appended, let me know
> what you think.
This is fine, thanks.
Approved-By: Eli Zaretskii <eliz@gnu.org>
@@ -57,6 +57,18 @@ show remote thread-options-packet
sub-classed to create handlers for objfiles with missing debug
information.
+ ** New constants gdb.SYMBOL_TYPE_DOMAIN, gdb.SYMBOL_FUNCTION_DOMAIN,
+ and gdb.SEARCH_*_DOMAIN corresponding to all the existing symbol
+ domains. Symbol lookup can now search in multiple domains at
+ once, and can also narrowly search for just a type or function.
+
+* Guile API
+
+ ** New constants SYMBOL_TYPE_DOMAIN, SYMBOL_FUNCTION_DOMAIN, and
+ SEARCH_*_DOMAIN corresponding to all the existing symbol domains.
+ Symbol lookup can now search in multiple domains at once, and can
+ also narrowly search for just a type or function.
+
* New remote packets
New stop reason: clone
@@ -2802,6 +2802,14 @@ in the symbol information or in @value{GDBN}'s handling of symbols.
This domain contains variables, function names, typedef names and enum
type values.
+@item SYMBOL_FUNCTION_DOMAIN
+This domain contains functions.
+
+@item SYMBOL_TYPE_DOMAIN
+This domain contains types. In a C-like language, types using a tag
+will not appear here; in other languages, all types are in this
+domain.
+
@item SYMBOL_STRUCT_DOMAIN
This domain holds struct, union and enum type names.
@@ -2822,6 +2830,11 @@ This domain contains all types.
The available address class categories in @code{<gdb:symbol>} are represented
as constants in the @code{gdb} module:
+When searching for a symbol, the desired domain constant can be passed
+verbatim to the lookup function. For more complex searches, there is
+a corresponding set of constants using a @samp{SEARCH_} prefix. These
+may be or'd together to form a search constant.
+
@vtable @code
@item SYMBOL_LOC_UNDEF
If this is returned by address class, it indicates an error either in
@@ -6088,12 +6088,22 @@ in the symbol information or in @value{GDBN}'s handling of symbols.
@vindex SYMBOL_VAR_DOMAIN
@item gdb.SYMBOL_VAR_DOMAIN
-This domain contains variables, function names, typedef names and enum
-type values.
+This domain contains variables.
+
+@vindex SYMBOL_FUNCTION_DOMAIN
+@item gdb.SYMBOL_FUNCTION_DOMAIN
+This domain contains functions.
+
+@vindex SYMBOL_TYPE_DOMAIN
+@item gdb.SYMBOL_TYPE_DOMAIN
+This domain contains types. In a C-like language, types using a tag
+will not appear here; in other languages, all types are in this
+domain.
@vindex SYMBOL_STRUCT_DOMAIN
@item gdb.SYMBOL_STRUCT_DOMAIN
-This domain holds struct, union and enum type names.
+This domain holds struct, union and enum tag names. This domain is
+only used for C-like languages.
@vindex SYMBOL_LABEL_DOMAIN
@item gdb.SYMBOL_LABEL_DOMAIN
@@ -6108,6 +6118,20 @@ This domain contains names of Fortran module types.
This domain contains names of Fortran common blocks.
@end vtable
+When searching for a symbol, the desired domain constant can be passed
+verbatim to the lookup function. For example:
+@smallexample
+symbol = gdb.lookup_symbol ("name", domain=gdb.SYMBOL_VAR_DOMAIN)
+@end smallexample
+
+For more complex searches, there is a corresponding set of constants
+using a @samp{SEARCH_} prefix. These may be or'd together to form a
+search constant, e.g.:
+@smallexample
+symbol = gdb.lookup_symbol ("name",
+ domain=gdb.SEARCH_VAR_DOMAIN | gdb.SEARCH_TYPE_DOMAIN)
+@end smallexample
+
The available address class categories in @code{gdb.Symbol} are represented
as constants in the @code{gdb} module: