The argument is called static_members, not static_fields.
gdb/doc/ChangeLog:
2020-11-29 Hannes Domani <ssbssa@yahoo.de>
PR python/26974
* python.texi: Fix docu for static members argument.
This commit unifies all of the Python register lookup code (used by
Frame.read_register, PendingFrame.read_register, and
gdb.UnwindInfo.add_saved_register), and adds support for using a
gdb.RegisterDescriptor for register lookup.
Currently the register unwind code (PendingFrame and UnwindInfo) allow
registers to be looked up either by name, or by GDB's internal
number. I suspect the number was added for performance reasons, when
unwinding we don't want to repeatedly map from name to number for
every unwind. However, this kind-of sucks, it means Python scripts
could include GDB's internal register numbers, and if we ever change
this numbering in the future users scripts will break in unexpected
ways.
Meanwhile, the Frame.read_register method only supports accessing
registers using a string, the register name.
This commit unifies all of the register to register-number lookup code
in our Python bindings, and adds a third choice into the mix, the use
of gdb.RegisterDescriptor.
The register descriptors can be looked up by name, but once looked up,
they contain GDB's register number, and so provide all of the
performance benefits of using a register number directly. However, as
they are looked up by name we are no longer tightly binding the Python
API to GDB's internal numbering scheme.
As we may already have scripts in the wild that are using the register
numbers directly I have kept support for this in the API, but I have
listed this method last in the manual, and I have tried to stress that
this is NOT a good method to use and that users should use either a
string or register descriptor approach.
After this commit all existing Python code should function as before,
but users now have new options for how to identify registers.
gdb/ChangeLog:
* python/py-frame.c: Remove 'user-regs.h' include.
(frapy_read_register): Rewrite to make use of
gdbpy_parse_register_id.
* python/py-registers.c (gdbpy_parse_register_id): New function,
moved here from python/py-unwind.c. Updated the return type, and
also accepts register descriptor objects.
* python/py-unwind.c: Remove 'user-regs.h' include.
(pyuw_parse_register_id): Moved to python/py-registers.c.
(unwind_infopy_add_saved_register): Update to use
gdbpy_parse_register_id.
(pending_framepy_read_register): Likewise.
* python/python-internal.h (gdbpy_parse_register_id): Declare.
gdb/testsuite/ChangeLog:
* gdb.python/py-unwind.py: Update to make use of a register
descriptor.
gdb/doc/ChangeLog:
* python.texi (Unwinding Frames in Python): Update descriptions
for PendingFrame.read_register and
gdb.UnwindInfo.add_saved_register.
(Frames In Python): Update description of Frame.read_register.
Adds a new method 'find' to the gdb.RegisterDescriptorIterator class,
this allows gdb.RegisterDescriptor objects to be looked up directly by
register name rather than having to iterate over all registers.
This will be of use for a later commit.
I've documented the new function in the manual, but I don't think a
NEWS entry is required here, as, since the last release, the whole
register descriptor mechanism is new, and is already mentioned in the
NEWS file.
gdb/ChangeLog:
* python/py-registers.c: Add 'user-regs.h' include.
(register_descriptor_iter_find): New function.
(register_descriptor_iterator_object_methods): New static global
methods array.
(register_descriptor_iterator_object_type): Add pointer to methods
array.
gdb/testsuite/ChangeLog:
* gdb.python/py-arch-reg-names.exp: Add additional tests.
gdb/doc/ChangeLog:
* python.texi (Registers In Python): Document new find function.
Add a new method gdb.Architecture.register_groups which returns a new
object of type gdb.RegisterGroupsIterator. This new iterator then
returns objects of type gdb.RegisterGroup.
Each gdb.RegisterGroup object just wraps a single reggroup pointer,
and (currently) has just one read-only property 'name' that is a
string, the name of the register group.
As with the previous commit (adding gdb.RegisterDescriptor) I made
gdb.RegisterGroup an object rather than just a string in case we want
to add additional properties in the future.
gdb/ChangeLog:
* NEWS: Mention additions to Python API.
* python/py-arch.c (archpy_register_groups): New function.
(arch_object_methods): Add 'register_groups' method.
* python/py-registers.c (reggroup_iterator_object): New struct.
(reggroup_object): New struct.
(gdbpy_new_reggroup): New function.
(gdbpy_reggroup_to_string): New function.
(gdbpy_reggroup_name): New function.
(gdbpy_reggroup_iter): New function.
(gdbpy_reggroup_iter_next): New function.
(gdbpy_new_reggroup_iterator): New function
(gdbpy_initialize_registers): Register new types.
(reggroup_iterator_object_type): Define new Python type.
(gdbpy_reggroup_getset): New static global.
(reggroup_object_type): Define new Python type.
* python/python-internal.h
gdb/testsuite/ChangeLog:
* gdb.python/py-arch-reg-groups.exp: New file.
gdb/doc/ChangeLog:
* gdb.texi (Registers): Add @anchor for 'info registers
<reggroup>' command.
* python.texi (Architectures In Python): Document new
register_groups method.
(Registers In Python): Document two new object types related to
register groups.
This commit adds a new method gdb.Architecture.registers that returns
an object of the new type gdb.RegisterDescriptorIterator. This
iterator returns objects of the new type gdb.RegisterDescriptor.
A RegisterDescriptor is not a way to read the value of a register,
this is already covered by Frame.read_register, a RegisterDescriptor
is simply a way to discover from Python, which registers are
available for a given architecture.
I did consider just returning a string, the name of each register,
instead of a RegisterDescriptor, however, I'm aware that it we don't
want to break the existing Python API in any way, so if I return just
a string now, but in the future we want more information about a
register then we would have to add a second API to get that
information. By going straight to a descriptor object now, it is easy
to add additional properties in the future should we wish to.
Right now the only property of a register that a user can access is
the name of the register.
In future we might want to be able to ask the register about is
register groups, or its type.
gdb/ChangeLog:
* Makefile.in (SUBDIR_PYTHON_SRCS): Add py-registers.c
* python/py-arch.c (archpy_registers): New function.
(arch_object_methods): Add 'registers' method.
* python/py-registers.c: New file.
* python/python-internal.h
(gdbpy_new_register_descriptor_iterator): Declare.
(gdbpy_initialize_registers): Declare.
* python/python.c (do_start_initialization): Call
gdbpy_initialize_registers.
* NEWS: Mention additions to the Python API.
gdb/testsuite/ChangeLog:
* gdb.python/py-arch-reg-names.exp: New file.
gdb/doc/ChangeLog:
* python.texi (Python API): Add new section the menu.
(Frames In Python): Add new @anchor.
(Architectures In Python): Document new registers method.
(Registers In Python): New section.
It could be useful to determine the architecture of a frame being
unwound during the frame unwind process, that is, before we have a
gdb.Frame, but when we only have a gdb.PendingFrame.
The PendingFrame already has a pointer to the gdbarch internally, this
commit just exposes an 'architecture' method to Python, and has this
return a gdb.Architecture object (list gdb.Frame.architecture does).
gdb/ChangeLog:
* NEWS: Mention new Python API method.
* python/py-unwind.c (pending_framepy_architecture): New function.
(pending_frame_object_methods): Add architecture method.
gdb/testsuite/ChangeLog:
* gdb.python/py-unwind.py (TestUnwinder::__call__): Add test for
gdb.PendingFrame.architecture method.
gdb/doc/ChangeLog:
* python.texi (Unwinding Frames in Python): Document
PendingFrame.architecture method.
Now that Python code can create TUI windows, it seemed appropriate to
allow Python commands to appear in the "TUI" help class. This patch
adds this capability.
gdb/ChangeLog
2020-04-28 Tom Tromey <tom@tromey.com>
* NEWS: Update.
* python/py-cmd.c (gdbpy_initialize_commands): Add COMMAND_TUI.
(cmdpy_init): Allow class_tui.
gdb/doc/ChangeLog
2020-04-28 Tom Tromey <tom@tromey.com>
* python.texi (Commands In Python): Document gdb.COMMAND_TUI.
This expands the Python dynamic type documentation, as suggested by
Christian.
gdb/doc/ChangeLog
2020-04-27 Tom Tromey <tromey@adacore.com>
* python.texi (Types In Python): Mention missing fields. Add
dynamic type example.
This changes the gdb Python API to add support for dynamic types. In
particular, this adds an attribute to gdb.Type, and updates some
attributes to reflect dynamic sizes and field offsets.
There's still no way to get the dynamic type from one of its concrete
instances. This could perhaps be added if needed.
gdb/ChangeLog
2020-04-24 Tom Tromey <tromey@adacore.com>
PR python/23662:
* python/py-type.c (convert_field): Handle
FIELD_LOC_KIND_DWARF_BLOCK.
(typy_get_sizeof): Handle TYPE_HAS_DYNAMIC_LENGTH.
(typy_get_dynamic): Nw function.
(type_object_getset): Add "dynamic".
* NEWS: Add entry.
gdb/doc/ChangeLog
2020-04-24 Tom Tromey <tromey@adacore.com>
PR python/23662:
* python.texi (Types In Python): Document new features.
gdb/testsuite/ChangeLog
2020-04-24 Tom Tromey <tromey@adacore.com>
PR python/23662:
* gdb.ada/variant.exp: Add Python checks.
* gdb.rust/simple.exp: Add dynamic type checks.
Building gdb-9.1 on a system that has an older version of makeinfo
(4.8) shows the following warnings:
-----------------
make[4]: Entering directory '/home/tester/gdb-9.1/build/gdb/doc'
makeinfo --split-size=5000000 --split-size=5000000 -I
../../../gdb/doc/../../readline/readline/doc -I ../../../gdb/doc/../mi
-I ../../../gdb/doc \
-o gdb.info ../../../gdb/doc/gdb.texinfo
../../../gdb/doc/gdb.texinfo:21867: warning: unlikely character [ in @var.
../../../gdb/doc/gdb.texinfo:21867: warning: unlikely character ] in @var.
../../../gdb/doc/gdb.texinfo:21868: warning: unlikely character [ in @var.
../../../gdb/doc/gdb.texinfo:21868: warning: unlikely character ] in @var.
../../../gdb/doc/gdb.texinfo:21869: warning: unlikely character [ in @var.
../../../gdb/doc/gdb.texinfo:21869: warning: unlikely character ] in @var.
../../../gdb/doc/gdb.texinfo:21872: warning: unlikely character [ in @var.
../../../gdb/doc/gdb.texinfo:21872: warning: unlikely character ] in @var.
../../../gdb/doc/gdb.texinfo:21874: warning: unlikely character [ in @var.
../../../gdb/doc/gdb.texinfo:21874: warning: unlikely character ] in @var.
../../../gdb/doc/gdb.texinfo:21876: warning: unlikely character [ in @var.
../../../gdb/doc/gdb.texinfo:21876: warning: unlikely character ] in @var.
../../../gdb/doc/gdb.texinfo:21879: warning: unlikely character [ in @var.
../../../gdb/doc/gdb.texinfo:21879: warning: unlikely character ] in @var.
../../../gdb/doc/gdb.texinfo:21931: warning: unlikely character [ in @var.
../../../gdb/doc/gdb.texinfo:21931: warning: unlikely character ] in @var.
../../../gdb/doc/gdb.texinfo:21933: warning: unlikely character [ in @var.
../../../gdb/doc/gdb.texinfo:21933: warning: unlikely character ] in @var.
../../../gdb/doc/gdb.texinfo:21936: warning: unlikely character [ in @var.
../../../gdb/doc/gdb.texinfo:21936: warning: unlikely character ] in @var.
../../../gdb/doc/gdb.texinfo:21939: warning: unlikely character [ in @var.
../../../gdb/doc/gdb.texinfo:21939: warning: unlikely character ] in @var.
../../../gdb/doc//python.texi:3297: warning: `.' or `,' must follow
@xref, not `A'.
make[4]: Leaving directory '/home/tester/gdb-9.1/build/gdb/doc'
-----------------
These are thrown by expressions like `@var{[host]}`, intended to
produce `[HOST]`.
In that context this should instead be changed to `[@var{host}]`, which
has the same effect but without the warnings.
As for the warning in `python.texi`, there's period missing at the end
of one `@xref{}` clause. Added.
gdb/doc/ChangeLog:
2020-04-15 Artur Shepilko <nomadbyte@gmail.com>
* gdb.texinfo: Transform @var{[host]} to [@var{host}]; this
clears makeinfo warnings.
* python.texi: Add a missing period trailing an @xref{} clause;
this clears a makeinfo warning.
Since commit 3453e7e409 'Clean up "Reading symbols" output' we no longer print
"done." after the "Reading symbols from" message:
...
$ gdb -q a.out
Reading symbols from a.out...
(gdb)
...
Update docs accordingly.
Build on x86_64-linux.
gdb/doc/ChangeLog:
2020-03-04 Tom de Vries <tdevries@suse.de>
* gdb.texinfo: Remove trailing "done." in "Reading symbols from" lines.
* python.texi: Same.
This patch adds support for writing new TUI windows in Python.
2020-02-22 Tom Tromey <tom@tromey.com>
* NEWS: Add entry for gdb.register_window_type.
* tui/tui-layout.h (window_factory): New typedef.
(tui_register_window): Declare.
* tui/tui-layout.c (saved_tui_windows): New global.
(tui_apply_current_layout): Use it.
(tui_register_window): New function.
* python/python.c (do_start_initialization): Call
gdbpy_initialize_tui.
(python_GdbMethods): Add "register_window_type" function.
* python/python-internal.h (gdbpy_register_tui_window)
(gdbpy_initialize_tui): Declare.
* python/py-tui.c: New file.
* Makefile.in (SUBDIR_PYTHON_SRCS): Add py-tui.c.
gdb/doc/ChangeLog
2020-02-22 Tom Tromey <tom@tromey.com>
* python.texi (Python API): Add menu item.
(TUI Windows In Python): New node.
gdb/testsuite/ChangeLog
2020-02-22 Tom Tromey <tom@tromey.com>
* gdb.python/tui-window.exp: New file.
* gdb.python/tui-window.py: New file.
Change-Id: I85fbfb923a1840450a00a7dce113a05d7f048baa
This commit documents the new multi-target features in both NEWS and
user manual.
gdb/ChangeLog:
2020-01-10 Pedro Alves <palves@redhat.com>
* NEWS: Mention multi-target debugging, "info connections", and
"add-inferior -no-connection".
gdb/doc/ChangeLog:
2020-01-10 Pedro Alves <palves@redhat.com>
* gdb.texinfo (Starting): Say "current inferior not connected"
instead of "GDB not connected".
(Inferiors and Programs): Rename node to ...
(Inferiors Connections and Programs): ... this. Update all
references. Talk about multiple target connections. Update "info
inferiors" info to mention the connections column. Describe "info
connections". Document "add-inferior -no-connection".
* guile.texi, python.texi: Update cross references.
In this commit:
commit 086baaf134
Date: Tue Oct 15 16:18:26 2019 +0100
gdb/python: Introduce gdb.lookup_static_symbols
A duplicate description of gdb.lookup_global_symbol was accidentally
added. This commit corrects this mistake and removes the duplicate.
gdb/doc/ChangeLog:
* python.texi (Symbols In Python): Remove duplicate description of
gdb.lookup_global_symbol.
Change-Id: I4457b42cf05bde39e5c0ff39f168af919cad1255
I noticed that an example in the gdb.prompt documentation used the
wrong kind of quotes -- because it is code, it should use a plain
ASCII quotation mark. I also slightly shortened the sample text here,
so it would more clearly fit on a single line.
gdb/doc/ChangeLog
2019-12-10 Tom Tromey <tom@tromey.com>
* python.texi (gdb.prompt): Use correct quotes in example.
Shorten sample text.
Change-Id: I4153928c0d88001244ad410f3943c952a6ebfeb1
If gdb.lookup_static_symbol is going to return a single symbol then it
makes sense (I think) for it to return a context sensitive choice of
symbol, that is the global static symbol that would be visible to the
program at that point.
However, if the user of the python API wants to instead get a
consistent set of global static symbols, no matter where they stop,
then they have to instead consider all global static symbols with a
given name - there could be many. That is what this new API function
offers, it returns a list (possibly empty) of all global static
symbols matching a given name (and optionally a given symbol domain).
gdb/ChangeLog:
* python/py-symbol.c (gdbpy_lookup_static_symbols): New
function.
* python/python-internal.h (gdbpy_lookup_static_symbols):
Declare new function.
* python/python.c (python_GdbMethods): Add
gdb.lookup_static_symbols method.
* NEWS: Mention gdb.lookup_static_symbols.
gdb/testsuite/ChangeLog:
* gdb.python/py-symbol.exp: Add test for
gdb.lookup_static_symbols.
gdb/doc/ChangeLog:
* python.texi (Symbols In Python): Add documentation for
gdb.lookup_static_symbols.
Change-Id: I1153b0ae5bcbc43b3dcf139043c7a48bf791e1a3
When using gdb.lookup_static_symbol I think that GDB should find
static symbols (global symbol with static linkage) from the current
object file ahead of static symbols from other object files.
This means that if we have two source files f1.c and f2.c, and both
files contains 'static int foo;', then when we are stopped in f1.c a
call to 'gdb.lookup_static_symbol ("foo")' will find f1.c::foo, and if
we are stopped in f2.c we would find 'f2.c::foo'.
Given that gdb.lookup_static_symbol always returns a single symbol,
but there can be multiple static symbols with the same name GDB is
always making a choice about which symbols to return. I think that it
makes sense for the choice GDB makes in this case to match what a user
would get on the command line if they asked to 'print foo'.
gdb/testsuite/ChangeLog:
* gdb.python/py-symbol.c: Declare and call function from new
py-symbol-2.c file.
* gdb.python/py-symbol.exp: Compile both source files, and add new
tests for gdb.lookup_static_symbol.
* gdb.python/py-symbol-2.c: New file.
gdb/doc/ChangeLog:
* python.texi (Symbols In Python): Extend documentation for
gdb.lookup_static_symbol.
gdb/ChangeLog:
* python/py-symbol.c (gdbpy_lookup_static_symbol): Lookup in
static block of current object file first. Also fix typo in
header comment.
Change-Id: Ie55dbeb8806f35577b46015deecde27a0ca2ab64
It's not immediately obvious how to get the list of threads,
so add a note about that in the "Threads in Python" section.
gdb/doc/ChangeLog:
2019-10-23 Christian Biesinger <cbiesinger@google.com>
* python.texi (Threads In Python): Add a note for how to get the
list of threads.
Change-Id: I0fef8a7aff161fc347c09052319048c907a6e8c3
Currently we support iteration on blocks; this patch extends that to make
subscript access work as well.
gdb/ChangeLog:
2019-08-05 Christian Biesinger <cbiesinger@google.com>
* NEWS: Mention dictionary access on blocks.
* python/py-block.c (blpy_getitem): New function.
(block_object_as_mapping): New struct.
(block_object_type): Use new struct for tp_as_mapping field.
gdb/doc/ChangeLog:
2019-08-05 Christian Biesinger <cbiesinger@google.com>
* python.texi (Blocks In Python): Document dictionary access on blocks.
gdb/testsuite/ChangeLog:
2019-08-05 Christian Biesinger <cbiesinger@google.com>
* gdb.python/py-block.exp: Test dictionary access on blocks.
Similar to lookup_global_symbol, except that it checks the
STATIC_SCOPE.
gdb/ChangeLog:
2019-07-30 Christian Biesinger <cbiesinger@google.com>
PR/24474: Add a function to lookup static variables.
* NEWS: Mention this new function.
* python/py-symbol.c (gdbpy_lookup_static_symbol): New function.
* python/python-internal.h (gdbpy_lookup_static_symbol): New function.
* python/python.c (python_GdbMethods): Add new function.
gdb/doc/ChangeLog:
2019-07-30 Christian Biesinger <cbiesinger@google.com>
* python.texi (Symbols In Python): Document new function
gdb.lookup_static_symbol.
gdb/testsuite/ChangeLog:
2019-07-30 Christian Biesinger <cbiesinger@google.com>
* gdb.python/py-symbol.c: Add a static variable and one in an anonymous
namespace.
* gdb.python/py-symbol.exp: Test gdb.lookup_static_symbol.
This is essentially the inverse of Symbol.objfile. This allows
handling different symbols with the same name (but from different
objfiles) and can also be faster if the objfile is known.
gdb/ChangeLog:
2019-07-29 Christian Biesinger <cbiesinger@google.com>
* NEWS: Mention new functions Objfile.lookup_{global,static}_symbol.
* python/py-objfile.c (objfpy_lookup_global_symbol): New function.
(objfpy_lookup_static_symbol): New function.
(objfile_object_methods): Add new functions.
gdb/doc/ChangeLog:
2019-07-29 Christian Biesinger <cbiesinger@google.com>
* python.texi (Objfiles In Python): Document new functions
Objfile.lookup_{global,static}_symbol.
gdb/testsuite/ChangeLog:
2019-07-29 Christian Biesinger <cbiesinger@google.com>
* gdb.python/py-objfile.c: Add global and static vars.
* gdb.python/py-objfile.exp: Test new functions Objfile.
lookup_global_symbol and lookup_static_symbol.
The example in the documentation for the "python" command shows GDB
outputting instructions for how to terminate a sequence of python
commands entered from the command line. The documentation shows that
the following two lines are being output, though this does not occur
when actually using the "python" command from GDB:
Type python script
End with a line saying just "end".
While display of this text might be helpful, GDB has several other
commands which also use the "end" terminator that offer no such text.
Examples include the "if" and "while" commands. For example,
(gdb) if 1==1
>print "a"
>end
$1 = "a"
This seems similar to doing:
(gdb) python
>print 23
>end
23
If we decide that we want the "python" command to print such a message,
we should also adjust the behavior for other GDB commands which also use
"end" to terminate a command list. I.e, if this decision is made, the
"if" and "while" commands ought to also print similar messages.
So, for the moment anyway, this commit adjusts the documentation of the
python command to match its implementation.
This patch was taken from a larger body of work originating from the
Archer project. I haven't been able to determine its original author,
though I did find a commit log from Jan Kratochvil (in the Archer
repository) which suggests that the change had originally been made to
gdb.texinfo, but got inadvertently dropped when the python related
documentation was split out to python.texi.
gdb/doc/ChangeLog:
* python.texi (python command): Revise example to match
command behavior.
This allows users of the Python API to find the objfile where a type
was defined.
gdb/ChangeLog:
gdb/ChangeLog
2019-06-04 Christian Biesinger <cbiesinger@google.com>
Add objfile property to gdb.Type.
* gdb/NEWS: Mention Python API addition.
* gdb/python/py-type.c (typy_get_objfile): New method.
gdb/doc/ChangeLog
2019-06-04 Christian Biesinger <cbiesinger@google.com>
* gdb/doc/python.texi: Document new gdb.Type.objfile property.
gdb/testsuite/ChangeLog
2019-06-04 Christian Biesinger <cbiesinger@google.com>
* gdb/testsuite/gdb.python/py-type.exp: Test for new
gdb.Type.objfile property.
I found out recently that some users didn't know that the Python
pretty-printers "children" method should compute its result lazily.
This has been a good idea since the earliest days, but wasn't
mentioned in the docs. This patch adds some text to this effect.
gdb/doc/ChangeLog
2019-05-10 Tom Tromey <tromey@adacore.com>
* python.texi (Pretty Printing API): Mention lazy computation for
"children".
Introduce a new print setting max-depth which can be set with 'set
print max-depth DEPTH'. The default value of DEPTH is 20, but this
can also be set to unlimited.
When GDB is printing a value containing nested structures GDB will
stop descending at depth DEPTH. Here is a small example:
typedef struct s1 { int a; } s1;
typedef struct s2 { s1 b; } s2;
typedef struct s3 { s2 c; } s3;
typedef struct s4 { s3 d; } s4;
s4 var = { { { { 3 } } } };
The following table shows how various depth settings affect printing
of 'var':
| Depth Setting | Result of 'p var' |
|---------------+--------------------------------|
| Unlimited | $1 = {d = {c = {b = {a = 3}}}} |
| 4 | $1 = {d = {c = {b = {a = 3}}}} |
| 3 | $1 = {d = {c = {b = {...}}}} |
| 2 | $1 = {d = {c = {...}}} |
| 1 | $1 = {d = {...}} |
| 0 | $1 = {...} |
Only structures, unions, and arrays are replaced in this way, scalars
and strings are not replaced.
The replacement is counted from the level at which you print, not from
the top level of the structure. So, consider the above example and
this GDB session:
(gdb) set print max-depth 2
(gdb) p var
$1 = {d = {c = {...}}}
(gdb) p var.d
$2 = {c = {b = {...}}}
(gdb) p var.d.c
$3 = {b = {a = 3}}
Setting the max-depth to 2 doesn't prevent the user from exploring
deeper into 'var' by asking for specific sub-fields to be printed.
The motivation behind this feature is to try and give the user more
control over how much is printed when examining large, complex data
structures.
The default max-depth of 20 means that there is a change in GDB's
default behaviour. Someone printing a data structure with 20 levels
of nesting will now see '{...}' instead of their data, they would need
to adjust the max depth, or call print again naming a specific field
in order to dig deeper into their data structure. If this is
considered a problem then we could increase the default, or even make
the default unlimited.
This commit relies on the previous commit, which added a new field to
the language structure, this new field was a string that contained the
pattern that should be used when a structure/union/array is replaced
in the output, this allows languages to use a syntax that is more
appropriate, mostly this will be selecting the correct types of
bracket '(...)' or '{...}', both of which are currently in use.
This commit should have no impact on MI output, expressions are
printed through the MI using -var-create and then -var-list-children.
As each use of -var-list-children only ever displays a single level of
an expression then the max-depth setting will have no impact.
This commit also adds the max-depth mechanism to the scripting
language pretty printers following basically the same rules as for the
built in value printing.
One quirk is that when printing a value using the display hint 'map',
if the keys of the map are structs then GDB will hide the keys one
depth level after it hides the values, this ensures that GDB produces
output like this:
$1 = map_object = {[{key1}] = {...}, [{key2}] = {...}}
Instead of this less helpful output:
$1 = map_object = {[{...}] = {...}, [{...}] = {...}}
This is covered by the new tests in gdb.python/py-nested-maps.exp.
gdb/ChangeLog:
* cp-valprint.c (cp_print_value_fields): Allow an additional level
of depth when printing anonymous structs or unions.
* guile/scm-pretty-print.c (gdbscm_apply_val_pretty_printer):
Don't print either the top-level value, or the children if the
max-depth is exceeded.
(ppscm_print_children): When printing the key of a map, allow one
extra level of depth.
* python/py-prettyprint.c (gdbpy_apply_val_pretty_printer): Don't
print either the top-level value, or the children if the max-depth
is exceeded.
(print_children): When printing the key of a map, allow one extra
level of depth.
* python/py-value.c (valpy_format_string): Add max_depth keyword.
* valprint.c: (PRINT_MAX_DEPTH_DEFAULT): Define.
(user_print_options): Initialise max_depth field.
(val_print_scalar_or_string_type_p): New function.
(val_print): Check to see if the max depth has been reached.
(val_print_check_max_depth): Define new function.
(show_print_max_depth): New function.
(_initialize_valprint): Add 'print max-depth' option.
* valprint.h (struct value_print_options) <max_depth>: New field.
(val_print_check_max_depth): Declare new function.
* NEWS: Document new feature.
gdb/doc/ChangeLog:
* gdb.texinfo (Print Settings): Document 'print max-depth'.
* guile.texi (Guile Pretty Printing API): Document that 'print
max-depth' can effect the display of a values children.
* python.texi (Pretty Printing API): Likewise.
(Values From Inferior): Document max_depth keyword.
gdb/testsuite/ChangeLog:
* gdb.base/max-depth.c: New file.
* gdb.base/max-depth.exp: New file.
* gdb.python/py-nested-maps.c: New file.
* gdb.python/py-nested-maps.exp: New file.
* gdb.python/py-nested-maps.py: New file.
* gdb.python/py-format-string.exp (test_max_depth): New proc.
(test_all_common): Call test_max_depth.
* gdb.fortran/max-depth.exp: New file.
* gdb.fortran/max-depth.f90: New file.
* gdb.go/max-depth.exp: New file.
* gdb.go/max-depth.go: New file.
* gdb.modula2/max-depth.exp: New file.
* gdb.modula2/max-depth.c: New file.
* lib/gdb.exp (get_print_expr_at_depths): New proc.
This renaming was done to stay consistent with the naming of the new
gdb.InferiorThread.handle method. I had initially named it "thread_handle"
but Tom Tromey suggested just "handle".
The old name (thread_from_thread_handle) still works, but is marked as
deprecated in comments in the code as well as in the documentation.
I have some code which uses these functions. I very much like the
brevity of the new names.
gdb/doc/ChangeLog:
* python.texi (Inferiors In Python): Rename
Inferior.thread_from_thread_handle to Inferior.thread_from_handle.
Add note about the former being deprecated.
gdb/ChangeLog:
* python/py-inferior.c (infpy_thread_from_thread_handle):
Adjust comments to reflect renaming of thread_from_thread_handle
to thread_from_handle. Adjust keywords. Fix type error message.
(inferior_object_methods): Add thread_from_handle. Retain
thread_from_thread_handle, but mark it as deprecated.
testsuite/ChangeLog:
* gdb.python/py-thrhandle.exp: Adjust tests to call
thread_from_handle instead of thread_from_thread_handle.
The str () function, called on a gdb.Value instance, produces a string
representation similar to what can be achieved with the print command,
but it doesn't allow to specify additional formatting settings, for
instance disabling pretty printers.
This patch introduces a new format_string () method to gdb.Value which
allows specifying more formatting options, thus giving access to more
features provided by the internal C function common_val_print ().
gdb/ChangeLog:
2019-04-01 Marco Barisione <mbarisione@undo.io>
Add gdb.Value.format_string ().
* python/py-value.c (copy_py_bool_obj):
(valpy_format_string): Add gdb.Value.format_string ().
* NEWS: Document the addition of gdb.Value.format_string ().
gdb/doc/ChangeLog:
2019-04-01 Marco Barisione <mbarisione@undo.io>
* python.texi (Values From Inferior): Document
gdb.Value.format_string ().
gdb/testsuite/ChangeLog:
2019-04-01 Marco Barisione <mbarisione@undo.io>
Test gdb.Value.format_string ().
* gdb.python/py-format-string.exp: New test.
* gdb.python/py-format-string.c: New file.
* gdb.python/py-format-string.py: New file.
The documentation say that the display_hint method must return a
string to serve as a display hint, and then goes on to list some
acceptable strings.
However, if we don't supply the display_hint method then we get a
default display style behaviour and there's currently no way (in the
python api) to force this default behaviour.
The guile api allows #f to be used in order to force the default
display style behaviour, and this is documented.
Currently, using None in the python api also forces the default
display behaviour.
This commit extends the documentation to make returning None from the
display_hint method an official mechanism by which the user can get
the default display style.
I've extended one of the existing tests to cover this case.
gdb/doc/ChangeLog:
* python.texi (Pretty Printing API): Document use of None for the
display_hint.
gdb/testsuite/ChangeLog:
* gdb.python/py-prettyprint.c (struct container) <is_map_p>: New
field.
(make_container): Initialise new field.
* gdb.python/py-prettyprint.exp: Add new tests.
* gdb.python/py-prettyprint.py (class ContainerPrinter)
<display_hint>: New method.
While referencing the manual, I noticed that gdb.pretty_printers
wasn't documented using @defvar. This made it more difficult to find
in the info pages. This patch adds the @defvar and also an
introductory paragraph in that node.
gdb/doc/ChangeLog
2019-03-20 Tom Tromey <tromey@adacore.com>
* python.texi (Selecting Pretty-Printers): Use @defvar for
gdb.pretty_printers.
The synopsis of the two-parameters form of the gdb.Value constructor is
currently shown as
Value.__init__ (val, [, type ])
in the documentation.
First, there is an extra comma, which I think we can remove in any
case.
Then, since the type parameter is not optional, I would not put in
between square brackets. Those usually indicate that something is
optional.
With this patch, it appears as:
Value.__init__ (val, type)
gdb/doc/ChangeLog:
* python.texi (Values From Inferior): Change synopsys of the
second form of Value.__init__.
gdb/ChangeLog:
* NEWS: Mention two argument form of gdb.Value constructor.
gdb/doc/ChangeLog:
* python.texi (Values From Inferior): Document second form
of Value.__init__.
This commit applies all changes made after running the gdb/copyright.py
script.
Note that one file was flagged by the script, due to an invalid
copyright header
(gdb/unittests/basic_string_view/element_access/char/empty.cc).
As the file was copied from GCC's libstdc++-v3 testsuite, this commit
leaves this file untouched for the time being; a patch to fix the header
was sent to gcc-patches first.
gdb/ChangeLog:
Update copyright year range in all GDB files.
This fixes he @pxref in Inferior.architecture to point to the "Frames
In Python" node, as originally intended; somewhat reverting an earlier
build fix. The initial patch had typod the "In".
Tested by "make info".
gdb/doc/ChangeLog
2018-10-09 Tom Tromey <tom@tromey.com>
* python.texi (Inferiors In Python): Link to "Frames In Python",
not "Unwinding Frames in Python".
I've written a couple of gdb unwinders in Python, and while doing so,
I wanted to find the architecture of the inferior. (In an unwinder in
particular, one can't use the frame's architecture, because there is
no frame.)
This patch adds Inferior.architecture to allow this. Normally I think
I would have chosen an attribute and not a method here, but seeing
that Frame.architecture is a method, I chose a method as well, for
consistency.
gdb/ChangeLog
2018-10-06 Tom Tromey <tom@tromey.com>
PR python/19399:
* python/py-inferior.c: Add "architecture" entry.
(infpy_architecture): New function.
gdb/doc/ChangeLog
2018-10-06 Tom Tromey <tom@tromey.com>
PR python/19399:
* python.texi (Inferiors In Python): Document
Inferior.Architecture.
gdb/testsuite/ChangeLog
2018-10-06 Tom Tromey <tom@tromey.com>
PR python/19399:
* gdb.python/py-inferior.exp: Add architecture test.
In the distant past, there was no distinction between domain_enum and
search_domain. At that point, there were two sets of enumerators in a
single enum -- which is why these were eventually split. This
confusion leaked out to the Python API as well, as noted in
PR python/21765.
This patch deprecates the constants that aren't useful to the Python
API. They are left in place for now, but removed from the
documentation. Also, their values are changed so that, if used, they
might work. Finally, missing domains and location constants are
added.
gdb/ChangeLog
2018-10-06 Tom Tromey <tom@tromey.com>
PR python/21765:
* python/py-symbol.c (gdbpy_initialize_symbols): Redefine
SYMBOL_VARIABLES_DOMAIN, SYMBOL_FUNCTIONS_DOMAIN,
SYMBOL_TYPES_DOMAIN. Define SYMBOL_MODULE_DOMAIN,
SYMBOL_COMMON_BLOCK_DOMAIN, SYMBOL_LOC_COMMON_BLOCK.
gdb/doc/ChangeLog
2018-10-06 Tom Tromey <tom@tromey.com>
PR python/21765:
* python.texi (Symbols In Python): Document the module and
common-block domains. Remove documentation for incorrect
domains.
A convention in the Python layer is that raising a gdb.GdbError will
not print the Python stack -- instead the exception is treated as any
other gdb exception.
PR python/18852 asks that this treatment be extended the the
get_set_value method of gdb.Parameter. This makes sense, because it
lets Python-created parameters act like gdb parameters.
2018-09-23 Tom Tromey <tom@tromey.com>
PR python/18852:
* python/py-param.c (get_set_value): Use gdbpy_handle_exception.
gdb/doc/ChangeLog
2018-09-23 Tom Tromey <tom@tromey.com>
PR python/18852:
* python.texi (Parameters In Python): Document exception behavior
of get_set_string.
gdb/testsuite/ChangeLog
2018-09-23 Tom Tromey <tom@tromey.com>
PR python/18852:
* gdb.python/py-parameter.exp: Add test for parameter that throws
on "set".
There are a number of global functions in the gdb Python module which
really should be methods on Progspace. This patch adds new methods to
Progspace and then redefines these globals in terms of these new
methods.
This version has been rebased on the related changes that Simon
recently put in.
Built and regtested on x86-64 Fedora 28.
gdb/ChangeLog
2018-09-16 Tom Tromey <tom@tromey.com>
* python/lib/gdb/__init__.py (current_progspace, objfiles)
(solib_name, block_for_pc, find_pc_line): New functions.
(execute_unwinders): Update.
* python/py-block.c (gdbpy_block_for_pc): Remove.
* python/py-inferior.c (infpy_get_progspace): New function.
(inferior_object_getset) <progspace>: Add.
* python/py-progspace.c (pspy_objfiles): Rewrite.
(pspy_solib_name, pspy_block_for_pc)
(pspy_find_pc_line, pspy_is_valid): New functions.
(progspace_object_methods): Add entries for solib_name,
block_for_pc, find_pc_line, is_valid.
* python/python-internal.h (gdbpy_block_for_pc)
(build_objfiles_list): Don't declare.
* python/python.c: Don't include solib.h.
(gdbpy_solib_name, gdbpy_find_pc_line)
(gdbpy_get_current_progspace, build_objfiles_list)
(gdbpy_objfiles): Remove.
(GdbMethods) <current_progspace, objfiles, block_for_pc,
solib_name, find_pc_line>: Remove entries.
gdb/doc/ChangeLog
2018-09-16 Tom Tromey <tom@tromey.com>
* python.texi (Basic Python): Update docs for find_pc_line,
solib_name.
(Progspaces In Python): Update docs for current_progspace.
Document block_for_pc, find_pc_line, is_valid, nsolib_name.
Move method documentation before example.
The code implementing gdb.objfiles() returns a list of objfiles for the
current program space (the program space of the selected inferior). The
documentation for the gdb.objfiles() Python method, however, states:
Return a sequence of all the objfiles current known to GDB.
That sounds wrong to me. I tried to phrase to be more precise.
gdb/doc/ChangeLog:
* python.texi (Objfiles In Python): Update gdb.objfiles() doc.
This patch adds an objfiles method to the Progspace object, which
returns a sequence of the objfiles associated to that program space. I
chose a method rather than a property for symmetry with gdb.objfiles().
gdb/ChangeLog:
* python/py-progspace.c (PSPY_REQUIRE_VALID): New macro.
(pspy_get_objfiles): New function.
(progspace_object_methods): New.
(pspace_object_type): Add tp_methods callback.
* python/python-internal.h (build_objfiles_list): New
declaration.
* python/python.c (build_objfiles_list): New function.
(gdbpy_objfiles): Implement using build_objfiles_list.
* NEWS: Mention the Progspace.objfiles method.
gdb/doc/ChangeLog:
* python.texi (Program Spaces In Python): Document the
Progspace.objfiles method.
(Objfiles In Python): Mention that gdb.objfiles() is identical
to gdb.selected_inferior().progspace.objfiles().
gdb/testsuite/ChangeLog:
* gdb.python/py-progspace.exp: Test the Progspace.objfiles
method.
This patch adds a progspace property to the gdb.Inferior type, which
allows getting the gdb.Progspace object associated to that inferior.
In conjunction with the following patch, this will allow scripts iterate
on objfiles associated with a particular inferior.
gdb/ChangeLog:
* python/py-inferior.c (infpy_get_progspace): New function.
(inferior_object_getset): Add progspace property.
* NEWS: Mention the new property.
gdb/doc/ChangeLog:
* python.texi (Inferiors In Python): Document
Inferior.progspace.
(Program Spaces In Python): Document that
gdb.current_progspace() is the same as
gdb.selected_inferior().progspace.
gdb/testsuite/ChangeLog:
* gdb.python/py-inferior.exp: Add tests for Inferior.progspace
and a few other Inferior properties when the Inferior is no
longer valid.
Printing a GDB Python object is notoriously not helpful:
>>> print(gdb.selected_inferior())
<gdb.Inferior object at 0x7fea59aed198>
>>> print(gdb.objfiles())
[<gdb.Objfile object at 0x7fea59b57c90>]
This makes printing debug traces more difficult than it should be. This
patch provides some repr() implementation for these two types (more to
come if people agree with the idea, but I want to test the water first).
Here's the same example as above, but with this patch:
>>> print(gdb.selected_inferior())
<gdb.Inferior num=1>
>>> print(gdb.objfiles())
[<gdb.Objfile filename=/home/emaisin/build/binutils-gdb-gcc-git/gdb/test>]
I implemented repr rather than str, because when printing a list (or
another container I suppose), Python calls the repr method of the
elements. This is useful when printing a list of inferiors or objfiles.
The print(gdb.objfiles()) above would not have worked if I had
implemented str.
I found this post useful to understand the difference between repr and
str:
https://stackoverflow.com/questions/1436703/difference-between-str-and-repr
gdb/ChangeLog:
* python/py-inferior.c (infpy_repr): New.
(inferior_object_type): Register infpy_repr.
* python/py-objfile.c (objfpy_repr): New.
(objfile_object_type): Register objfpy_repr.
gdb/testsuite/ChangeLog:
* gdb.python/py-inferior.exp: Test repr() of gdb.Inferior.
* gdb.python/py-objfile.exp: Test repr() of gdb.Objfile.
* gdb.python/py-symtab.exp: Update test printing an objfile.
gdb/doc/ChangeLog:
* python.texi (Basic Python): Mention the string representation
of GDB Python objects.
This removes the remaining trailing periods from the Python section
titles. I thought these looked weird and I don't this is generally
done in the gdb documentation.
gdb/doc/ChangeLog
2018-09-10 Tom Tromey <tom@tromey.com>
* python.texi (Frames In Python, Blocks In Python)
(Symbols In Python, Symbol Tables In Python)
(Lazy Strings In Python): Remove periods from section titles.
I thought the start of the Pretty Printing API node read a bit
strangely. This patch swaps the first two sentences, which seems
better.
gdb/doc/ChangeLog
2018-09-10 Tom Tromey <tom@tromey.com>
* python.texi (Pretty Printing API): Swap sentence order.
PR python/16461 asks that the Python dynamic_type documentation
mention virtual tables; this patch implements that request.
gdb/doc/ChangeLog
2018-09-10 Tom Tromey <tom@tromey.com>
PR python/16461:
* python.texi (Values From Inferior): Mention use of virtual
table.
I noticed that the decode_line documentation did not have parens
around the argument:
-- Function: gdb.decode_line [expression]
This patch fixes this oversight.
gdb/doc/ChangeLog
2018-09-10 Tom Tromey <tom@tromey.com>
* python.texi (Basic Python): Parenthesize argument to
decode_line.
