From: Tom Tromey <[email protected]>
This updates the gnat-llvm debugging documentation to reflect the
current status.
gcc/ada/ChangeLog:
* doc/gnat_ugn/building_executable_programs_with_gnat.rst
(GNATLLVM): Update debugging documentation.
* gnat_ugn.texi: Regenerate.
Tested on x86_64-pc-linux-gnu (before the recent bootstrap breakage), committed
on master.
---
...building_executable_programs_with_gnat.rst | 24 ++++++++++++-------
gcc/ada/gnat_ugn.texi | 24 ++++++++++++-------
2 files changed, 30 insertions(+), 18 deletions(-)
diff --git a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
index cee7c51cfce..b339d2579dd 100644
--- a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
+++ b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
@@ -8004,15 +8004,21 @@ passed between C and Ada as simple as practical.
GNAT LLVM currently provides limited support for debugging data. It
provides full line number information for declarations and statements,
but not sufficient debugging data to display all Ada data
-structures. GNAT LLVM outputs complete debugging data only for types
-with a direct equivalent in C, namely records without discriminants
-and constrained arrays whose dimensions are known at compile time. You
-will not be able to use ``gdb`` print commands to look at objects not
-of those types or to display components of those types. You can use
-low-level ``gdb`` commands that display memory to view such data
-provided you know how they're laid out. Debugging information may
-also be limited for bitfields (fields whose size and position
-aren't on byte boundaries)
+structures. GNAT LLVM outputs complete debugging data only for a
+subset of types: scalar types; records whose field offsets are known
+at compile time, including discriminated records fitting this
+description; and arrays. Records that have a field whose size or
+offset is only known at run time do not yet have correct debugging
+data. You will not be able to use ``gdb`` print commands to look at
+objects not of those types or to display components of those
+types. You can use low-level ``gdb`` commands that display memory to
+view such data provided you know how they're laid out.
+
+In some situations, a name in the source may not be available.
+Renamings are not currently emitted into the debugging data. When
+debugging a nested function, variables from enclosing scopes will not
+be available. You will have to examine those variables in their
+hosting frame.
In addition, debugging information may be confusing if you have
``out`` parameters to subprograms. If you have a procedure with only
diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi
index 201f013e77f..9edf1aa47f2 100644
--- a/gcc/ada/gnat_ugn.texi
+++ b/gcc/ada/gnat_ugn.texi
@@ -17570,15 +17570,21 @@ passed between C and Ada as simple as practical.
GNAT LLVM currently provides limited support for debugging data. It
provides full line number information for declarations and statements,
but not sufficient debugging data to display all Ada data
-structures. GNAT LLVM outputs complete debugging data only for types
-with a direct equivalent in C, namely records without discriminants
-and constrained arrays whose dimensions are known at compile time. You
-will not be able to use @code{gdb} print commands to look at objects not
-of those types or to display components of those types. You can use
-low-level @code{gdb} commands that display memory to view such data
-provided you know how they’re laid out. Debugging information may
-also be limited for bitfields (fields whose size and position
-aren’t on byte boundaries)
+structures. GNAT LLVM outputs complete debugging data only for a
+subset of types: scalar types; records whose field offsets are known
+at compile time, including discriminated records fitting this
+description; and arrays. Records that have a field whose size or
+offset is only known at run time do not yet have correct debugging
+data. You will not be able to use @code{gdb} print commands to look at
+objects not of those types or to display components of those
+types. You can use low-level @code{gdb} commands that display memory to
+view such data provided you know how they’re laid out.
+
+In some situations, a name in the source may not be available.
+Renamings are not currently emitted into the debugging data. When
+debugging a nested function, variables from enclosing scopes will not
+be available. You will have to examine those variables in their
+hosting frame.
In addition, debugging information may be confusing if you have
@code{out} parameters to subprograms. If you have a procedure with only
--
2.51.0
