From 15bdffc4963b842cf104a0075921965a3cee272b Mon Sep 17 00:00:00 2001 From: Pierre-Marie de Rodat Date: Tue, 11 Dec 2018 11:09:13 +0000 Subject: [PATCH] [Ada] Document the -fgnat-encodings switch 2018-12-11 Pierre-Marie de Rodat gcc/ada/ * doc/gnat_ugn/building_executable_programs_with_gnat.rst: Document the -fgnat-encodings switch. * gnat_ugn.texi: Regenerate. From-SVN: r266979 --- gcc/ada/ChangeLog | 6 ++ ...building_executable_programs_with_gnat.rst | 37 +++++++++++++ gcc/ada/gnat_ugn.texi | 55 ++++++++++++++++++- 3 files changed, 97 insertions(+), 1 deletion(-) diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog index b190949b958..5ff08a54194 100644 --- a/gcc/ada/ChangeLog +++ b/gcc/ada/ChangeLog @@ -1,3 +1,9 @@ +2018-12-11 Pierre-Marie de Rodat + + * doc/gnat_ugn/building_executable_programs_with_gnat.rst: + Document the -fgnat-encodings switch. + * gnat_ugn.texi: Regenerate. + 2018-12-11 Justin Squirek * sem_ch10.adb (Analyze_Subunit): Modify conditional to fully 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 1b69bdd457a..b5363dada97 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 @@ -1243,6 +1243,13 @@ Alphabetical List of All Switches :file:`scos.adb`. +.. index:: -fgnat-encodings (gcc) + +:switch:`-fgnat-encodings=[all|gdb|minimal]` + This switch controls the balance between GNAT encodings and standard DWARF + emitted in the debug information. + + .. index:: -flto (gcc) :switch:`-flto[={n}]` @@ -5915,6 +5922,36 @@ Debugging Control suppresses this information. This saves some space and may slightly speed up compilation, but means that these tools cannot be used. + +.. index:: -fgnat-encodings (gcc) + +:switch:`-fgnat-encodings=[all|gdb|minimal]` + This switch controls the balance between GNAT encodings and standard DWARF + emitted in the debug information. + + Historically, old debug formats like stabs were not powerful enough to + express some Ada types (for instance, variant records or fixed-point types). + To work around this, GNAT introduced proprietary encodings that embed the + missing information ("GNAT encodings"). + + Recent versions of the DWARF debug information format are now able to + correctly describe most of these Ada constructs ("standard DWARF"). As + third-party tools started to use this format, GNAT has been enhanced to + generate it. However, most tools (including GDB) are still relying on GNAT + encodings. + + To support all tools, GNAT needs to be versatile about the balance between + generation of GNAT encodings and standard DWARF. This is what + :switch:`-fgnat-encodings` is about. + + * ``=all``: Emit all GNAT encodings, and then emit as much standard DWARF as + possible so it does not conflict with GNAT encodings. + * ``=gdb``: Emit as much standard DWARF as possible as long as the current + GDB handles it. Emit GNAT encodings for the rest. + * ``=minimal``: Emit as much standard DWARF as possible and emit GNAT + encodings for the rest. + + .. _Exception_Handling_Control: Exception Handling Control diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi index d28d53dc7fa..9e2138e9cf7 100644 --- a/gcc/ada/gnat_ugn.texi +++ b/gcc/ada/gnat_ugn.texi @@ -21,7 +21,7 @@ @copying @quotation -GNAT User's Guide for Native Platforms , Nov 09, 2018 +GNAT User's Guide for Native Platforms , Dec 05, 2018 AdaCore @@ -8809,6 +8809,17 @@ in the compiler sources for details in files @code{scos.ads} and @code{scos.adb}. @end table +@geindex -fgnat-encodings (gcc) + + +@table @asis + +@item @code{-fgnat-encodings=[all|gdb|minimal]} + +This switch controls the balance between GNAT encodings and standard DWARF +emitted in the debug information. +@end table + @geindex -flto (gcc) @@ -15174,6 +15185,48 @@ suppresses this information. This saves some space and may slightly speed up compilation, but means that these tools cannot be used. @end table +@geindex -fgnat-encodings (gcc) + + +@table @asis + +@item @code{-fgnat-encodings=[all|gdb|minimal]} + +This switch controls the balance between GNAT encodings and standard DWARF +emitted in the debug information. + +Historically, old debug formats like stabs were not powerful enough to +express some Ada types (for instance, variant records or fixed-point types). +To work around this, GNAT introduced proprietary encodings that embed the +missing information ("GNAT encodings"). + +Recent versions of the DWARF debug information format are now able to +correctly describe most of these Ada constructs ("standard DWARF"). As +third-party tools started to use this format, GNAT has been enhanced to +generate it. However, most tools (including GDB) are still relying on GNAT +encodings. + +To support all tools, GNAT needs to be versatile about the balance between +generation of GNAT encodings and standard DWARF. This is what +@code{-fgnat-encodings} is about. + + +@itemize * + +@item +@code{=all}: Emit all GNAT encodings, and then emit as much standard DWARF as +possible so it does not conflict with GNAT encodings. + +@item +@code{=gdb}: Emit as much standard DWARF as possible as long as the current +GDB handles it. Emit GNAT encodings for the rest. + +@item +@code{=minimal}: Emit as much standard DWARF as possible and emit GNAT +encodings for the rest. +@end itemize +@end table + @node Exception Handling Control,Units to Sources Mapping Files,Debugging Control,Compiler Switches @anchor{gnat_ugn/building_executable_programs_with_gnat id28}@anchor{114}@anchor{gnat_ugn/building_executable_programs_with_gnat exception-handling-control}@anchor{115} @subsection Exception Handling Control -- 2.30.2