[Ada] Document the -fgnat-encodings switch

2018-12-11  Pierre-Marie de Rodat  <derodat@adacore.com>

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

+2018-12-11  Pierre-Marie de Rodat  <derodat@adacore.com>
+
+	* doc/gnat_ugn/building_executable_programs_with_gnat.rst:
+	Document the -fgnat-encodings switch.
+	* gnat_ugn.texi: Regenerate.
+
 2018-12-11  Justin Squirek  <squirek@adacore.com>
 
 	* sem_ch10.adb (Analyze_Subunit): Modify conditional to fully

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

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