You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Debug Native Executables with a Python Helper Script
8
+
9
+
Additionally to the [GDB debugging](debug-native-executables-with-gdb.md), you can debug a `native-image` process using a Python helper script, _gdb-debughelpers.py_.
10
+
The [GDB Python API](https://sourceware.org/gdb/current/onlinedocs/gdb/Python.html) is used to provide a reasonably good experience for debugging native executables or shared libraries.
11
+
It requires GDB with Python support.
12
+
The debugging extension is tested against GDB 13.2 and supports the new debuginfo generation introduced in GraalVM for JDK 17 and later.
13
+
14
+
> Note: The _gdb-debughelpers.py_ file does not work with versions older than version 13.2 of `gdb` or versions older than GraalVM for JDK 17.
15
+
16
+
The Python script _gdb-debughelpers.py_ can be found in the _<GRAALVM\_HOME>/lib/svm/debug_ directory.
17
+
If debuginfo generation is enabled (see [Build a Native Executable with Debug Information](debug-native-executables-with-gdb.md#build-a-native-executable-with-debug-information)), the script is copied to the build directory.
18
+
The `native-image` tool adds the debugging section `.debug_gdb_scripts` to the debug info file, which causes GDB to automatically load _gdb-debughelpers.py_ from the current working directory.
19
+
20
+
For [security reasons](https://sourceware.org/gdb/current/onlinedocs/gdb/Auto_002dloading-safe-path.html)
21
+
the first time GDB encounters a native executable or shared library that requests a specific Python file to be loaded it will print a warning:
22
+
23
+
> warning: File "<CWD>/gdb-debughelpers.py" auto-loading has been declined by your `auto-load safe-path' set to "$debugdir:$datadir/auto-load".
Both enable GDB to auto-load _gdb-debughelpers.py_ from the current working directory.
44
+
45
+
Auto-loading is the recommended way to provide the script to GDB.
46
+
However, it is possible to manually load the script from GDB explicitly with:
47
+
48
+
(gdb) source gdb-debughelpers.py
49
+
50
+
## Pretty Printing Support
51
+
52
+
Loading _gdb-debughelpers.py_ registers a new pretty printer to GDB, which adds an extra level of convenience for debugging native executables or shared libraries.
53
+
This pretty printer handles the printing of Java Objects, Arrays, Strings, and Enums for debugging native executables or shared libraries.
54
+
If the Java application uses `@CStruct` and `@CPointer` annotations to access C data structures, the pretty printer will also try to print them as if they were Java data structures.
55
+
If the C data structures cannot be printed by the pretty printer, printing is performed by GDB.
56
+
57
+
The pretty printer also prints of the primitive value of a boxed primitive (instead of a Java Object).
58
+
59
+
Whenever printing is done via the `p` alias of the `print` command the pretty printer intercepts that call to perform type casts to the respective runtime types of Java Objects.
60
+
This also applies for auto-completion when using the `p` alias.
61
+
This means that if the static type is different to the runtime type, the `print` command uses the static type, which leaves the user to discover the runtime type and typecast it.
62
+
Additionally, the `p` alias understands Java field and array access and function calls for Java Objects.
63
+
64
+
#### Limitations
65
+
66
+
The `print` command still uses its default implementation, as there is no way to overwrite it, while still keeping the capability of the default `print` command.
67
+
Overriding would cause printing non-Java Objects to not work properly.
68
+
Therefore, only the `p` alias for the `print` command is overwritten by the pretty printer, such that the user can still make use of the default GDB `print` command.
69
+
70
+
### Options to Control the Pretty Printer Behavior
71
+
72
+
In addition to the enhanced `p` alias, _gdb-debughelpers.py_ introduces some GDB parameters to customize the behavior of the pretty printer.
73
+
Parameters in GDB can be controlled with `set <param> <value>` and `show <param>` commands, and thus integrate with GDB's customization options.
74
+
75
+
*#### svm-print on/off
76
+
77
+
Use this command to enable/disable the pretty printer.
78
+
This also resets the `print` command alias `p` to its default behavior.
79
+
Alternatively pretty printing can be suppressed with the
80
+
[`raw` printing option of GDB's `print` command](https://sourceware.org/gdb/current/onlinedocs/gdb/Output-Formats.html):
81
+
82
+
(gdb) show svm-print
83
+
The current value of 'svm-print' is "on".
84
+
85
+
(gdb) print str
86
+
$1 = "string"
87
+
88
+
(gdb) print/r str
89
+
$2 = (java.lang.String *) 0x7ffff689d2d0
90
+
91
+
(gdb) set svm-print off
92
+
1 printer disabled
93
+
1 of 2 printers enabled
94
+
95
+
(gdb) print str
96
+
$3 = (java.lang.String *) 0x7ffff689d2d0
97
+
98
+
*#### svm-print-string-limit <int>
99
+
100
+
Customizes the maximum length for pretty printing a Java String.
101
+
The default value is `200`.
102
+
Set to `-1` or `unlimited` for unlimited printing of a Java String.
103
+
This does not change the limit for a C String, which can be controlled with GDB's `set print characters` command.
104
+
105
+
*#### svm-print-element-limit <int>
106
+
107
+
Customizes the maximum number of elements for pretty printing a Java Array, ArrayList, and HashMap.
108
+
The default value is `10`.
109
+
Set to `-1` or `unlimited` to print an unlimited number of elements.
110
+
This does not change the limit for a C array, which can be controlled with GDB's `set print elements` command.
111
+
However, GDB's parameter `print elements` is the upper bound for `svm-print-element-limit`.
112
+
113
+
*#### svm-print-field-limit <int>
114
+
115
+
Customizes the maximum number of elements for pretty printing fields of a Java Object.
116
+
The default value is `50`.
117
+
Set to `-1` or `unlimited` to print an unlimited number of fields.
118
+
GDB's parameter `print elements` is the upper bound for `svm-print-field-limit`.
119
+
120
+
*#### svm-print-depth-limit <int>
121
+
122
+
Customizes the maximum depth of recursive pretty printing.
123
+
The default value is `1`.
124
+
The children of direct children are printed (a sane default to make contents of boxed values visible).
125
+
Set to `-1` or `unlimited` to print unlimited depth.
126
+
GDB's parameter `print max-depth` is the upper bound for `svm-print-depth-limit`.
127
+
128
+
*#### svm-use-hlrep on/off
129
+
130
+
Enables/disables pretty printing for higher level representations.
131
+
It provides a more data-oriented view on some Java data structures with a known internal structure such as Lists or Maps.
132
+
Currently supports ArrayList and HashMap.
133
+
134
+
*#### svm-infer-generics <int>
135
+
136
+
Customizes the number of elements taken into account to infer the generic type of higher level representations.
137
+
The default value is `10`.
138
+
Set to `0` to not infer generic types and `-1` or `unlimited` to infer the generic type of all elements.
139
+
140
+
*#### svm-print-address absolute/on/off
141
+
142
+
Enables/disables printing of addresses in addition to regular pretty printing.
143
+
When `absolute` mode is used even compressed references are shown as absolute addresses.
144
+
Printing addresses is disabled by default.
145
+
146
+
*#### svm-print-static-fields on/off
147
+
148
+
Enables/disables printing of static fields for a Java Object.
149
+
Printing static fields is disabled by default.
150
+
151
+
*#### svm-complete-static-variables on/off
152
+
153
+
Enables/disables auto-completion of static field members for the enhanced `p` alias.
154
+
Auto-completion of static fields is enabled by default.
155
+
156
+
*#### svm-selfref-check on/off
157
+
158
+
Enables/disables self-reference checks for data structures.
159
+
The pretty printer detects a self-referential data structure and prevents further expansion to avoid endless recursion.
160
+
Self-reference checks are enabled by default.
161
+
For testing, this feature can be temporary disabled (usually you wouldn't want to do this).
162
+
163
+
### Related Documentation
164
+
165
+
*[Debug Info Feature](../DebugInfo.md)
166
+
*[Debug Native Executables with GDB](debug-native-executables-with-gdb.md)
Copy file name to clipboardExpand all lines: substratevm/CHANGELOG.md
+3Lines changed: 3 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,6 +2,9 @@
2
2
3
3
This changelog summarizes major changes to GraalVM Native Image.
4
4
5
+
## GraalVM for JDK 24 (Internal Version 24.2.0)
6
+
* (GR-48384) Added a GDB Python script (`gdb-debughelpers.py`) to improve the Native Image debugging experience.
7
+
5
8
## GraalVM for JDK 23 (Internal Version 24.1.0)
6
9
* (GR-51520) The old class initialization strategy, which was deprecated in GraalVM for JDK 22, is removed. The option `StrictImageHeap` no longer has any effect.
7
10
* (GR-51106) Fields that are accessed via a `VarHandle` or `MethodHandle` are no longer marked as "unsafe accessed" when the `VarHandle`/`MethodHandle` can be fully intrinsified.
parser.add_argument(all_args[0], metavar='<output-path>', nargs=1, help='Path of the generated image', default=[join(svmbuild_dir(), "gdbdebughelperstest")])
1651
+
parser.add_argument(all_args[1], action='store_true', help='Only build and test the native image with isolates')
1652
+
parser.add_argument(all_args[2], action='store_true', help='Only build the native image')
1653
+
parser.add_argument(all_args[3], action='store_true', help='Only run the tests')
0 commit comments