From 84e80d556415c4c82081647e70e899506a7db9ba Mon Sep 17 00:00:00 2001 From: Steve Baird Date: Wed, 9 Nov 2022 15:53:49 -0800 Subject: [PATCH] ada: Improve documentation for -gnatw.h warnings The -gnatw.h option enables warnings about "gaps" in record layout specifications. In the case of a "partial" layout specification, where the locations of some components are left unspecified, the resulting warnings may be incomplete or incorrect. Document this implementation limitation. gcc/ada/ * doc/gnat_ugn/building_executable_programs_with_gnat.rst: Improve the description of how the -gnatw.h switch interacts with "partial" record layout specifications (i.e., specifications where the locations of some components are left unspecified). * gnat_ugn.texi: Regenerate. --- .../building_executable_programs_with_gnat.rst | 9 +++++++-- gcc/ada/gnat_ugn.texi | 11 ++++++++--- 2 files changed, 15 insertions(+), 5 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 87fb1087e421..fe0b567c2b95 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 @@ -3221,8 +3221,13 @@ of the pragma in the :title:`GNAT_Reference_manual`). This switch activates warnings on component clauses in record representation clauses that leave holes (gaps) in the record layout. - If this warning option is active, then record representation clauses - should specify a contiguous layout, adding unused fill fields if needed. + If a record representation clause does not specify a location for + every component of the record type, then the warnings generated (or not + generated) are unspecified. For example, there may be gaps for which + either no warning is generated or a warning is generated that + incorrectly describes the location of the gap. This undesirable situation + can sometimes be avoided by adding (and specifying the location for) unused + fill fields. .. index:: -gnatw.H (gcc) diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi index 2f43b4f71c8f..12eb494d40de 100644 --- a/gcc/ada/gnat_ugn.texi +++ b/gcc/ada/gnat_ugn.texi @@ -19,7 +19,7 @@ @copying @quotation -GNAT User's Guide for Native Platforms , Nov 14, 2022 +GNAT User's Guide for Native Platforms , Nov 18, 2022 AdaCore @@ -11305,8 +11305,13 @@ This switch suppresses warnings on hiding declarations. This switch activates warnings on component clauses in record representation clauses that leave holes (gaps) in the record layout. -If this warning option is active, then record representation clauses -should specify a contiguous layout, adding unused fill fields if needed. +If a record representation clause does not specify a location for +every component of the record type, then the warnings generated (or not +generated) are unspecified. For example, there may be gaps for which +either no warning is generated or a warning is generated that +incorrectly describes the location of the gap. This undesirable situation +can sometimes be avoided by adding (and specifying the location for) unused +fill fields. @end table @geindex -gnatw.H (gcc) -- 2.47.2