[Ada] Add elaboration-related switches to GNAT UGN

Message ID 20180717082233.GA1245@adacore.com
State New
Headers show
Series
  • [Ada] Add elaboration-related switches to GNAT UGN
Related show

Commit Message

Pierre-Marie de Rodat July 17, 2018, 8:22 a.m.
This patch adds compiler switches -gnatH and -gnatJ to section "Alphabetical
list of all switches" of the GNAT User Guide for Native.

Tested on x86_64-pc-linux-gnu, committed on trunk

2018-07-17  Hristian Kirtchev  <kirtchev@adacore.com>

gcc/ada/

	* doc/gnat_ugn/building_executable_programs_with_gnat.rst: Add missing
	sections on -gnatH and -gnatJ compiler switches.
	* gnat_ugn.texi: Regenerate.

Patch

--- gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
+++ gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
@@ -720,9 +720,9 @@  is passed to ``gcc`` (e.g., :switch:`-O`, :switch:`-gnato,` etc.)
 .. index:: --RTS  (gnatmake)
 
 :switch:`--RTS={rts-path}`
-  Specifies the default location of the runtime library. GNAT looks for the
-  runtime
-  in the following directories, and stops as soon as a valid runtime is found
+  Specifies the default location of the run-time library. GNAT looks for the
+  run-time
+  in the following directories, and stops as soon as a valid run-time is found
   (:file:`adainclude` or :file:`ada_source_path`, and :file:`adalib` or
   :file:`ada_object_path` present):
 
@@ -1505,7 +1505,7 @@  Alphabetical List of All Switches
 
 
   In the example above, the first call to ``Detect_Aliasing`` fails with a
-  ``Program_Error`` at runtime because the actuals for ``Val_1`` and
+  ``Program_Error`` at run time because the actuals for ``Val_1`` and
   ``Val_2`` denote the same object. The second call executes without raising
   an exception because ``Self(Obj)`` produces an anonymous object which does
   not share the memory location of ``Obj``.
@@ -1817,14 +1817,12 @@  Alphabetical List of All Switches
 .. index:: -gnatg  (gcc)
 
 :switch:`-gnatg`
-  Internal GNAT implementation mode. This should not be used for
-  applications programs, it is intended only for use by the compiler
-  and its run-time library. For documentation, see the GNAT sources.
-  Note that :switch:`-gnatg` implies
-  :switch:`-gnatw.ge` and
-  :switch:`-gnatyg`
-  so that all standard warnings and all standard style options are turned on.
-  All warnings and style messages are treated as errors.
+  Internal GNAT implementation mode. This should not be used for applications
+  programs, it is intended only for use by the compiler and its run-time
+  library. For documentation, see the GNAT sources. Note that :switch:`-gnatg`
+  implies :switch:`-gnatw.ge` and :switch:`-gnatyg` so that all standard
+  warnings and all standard style options are turned on. All warnings and style
+  messages are treated as errors.
 
 
 .. index:: -gnatG[nn]  (gcc)
@@ -1839,6 +1837,13 @@  Alphabetical List of All Switches
   Output usage information. The output is written to :file:`stdout`.
 
 
+.. index:: -gnatH  (gcc)
+
+:switch:`-gnatH`
+  Legacy elaboration-checking mode enabled. When this switch is in effect, the
+  pre-18.x access-before-elaboration model becomes the de facto model.
+
+
 .. index:: -gnati  (gcc)
 
 :switch:`-gnati{c}`
@@ -1874,6 +1879,27 @@  Alphabetical List of All Switches
   Reformat error messages to fit on ``nn`` character lines
 
 
+.. index:: -gnatJ  (gcc)
+
+:switch:`-gnatJ`
+  Permissive elaboration-checking mode enabled. When this switch is in effect,
+  the post-18.x access-before-elaboration model ignores potential issues with:
+
+  - Accept statements
+  - Activations of tasks defined in instances
+  - Assertion pragmas
+  - Calls from within an instance to its enclosing context
+  - Calls through generic formal parameters
+  - Calls to subprograms defined in instances
+  - Entry calls
+  - Indirect calls using 'Access
+  - Requeue statements
+  - Select statements
+  - Synchronous task suspension
+
+  and does not emit compile-time diagnostics or run-time checks.
+
+
 .. index:: -gnatk  (gcc)
 
 :switch:`-gnatk={n}`
@@ -2195,7 +2221,7 @@  Alphabetical List of All Switches
 .. index:: --RTS  (gcc)
 
 :switch:`--RTS={rts-path}`
-  Specifies the default location of the runtime library. Same meaning as the
+  Specifies the default location of the run-time library. Same meaning as the
   equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
 
 
@@ -5062,7 +5088,7 @@  switches refine this default behavior.
   that a certain check will necessarily fail, it will generate code to
   do an unconditional 'raise', even if checks are suppressed. The
   compiler warns in this case. Another case in which checks may not be
-  eliminated is when they are embedded in certain run time routines such
+  eliminated is when they are embedded in certain run-time routines such
   as math library routines.
 
   Of course, run-time checks are omitted whenever the compiler can prove
@@ -5858,7 +5884,7 @@  Debugging Control
 Exception Handling Control
 --------------------------
 
-GNAT uses two methods for handling exceptions at run-time. The
+GNAT uses two methods for handling exceptions at run time. The
 ``setjmp/longjmp`` method saves the context when entering
 a frame with an exception handler. Then when an exception is
 raised, the context can be restored immediately, without the
@@ -6367,7 +6393,7 @@  be presented in subsequent sections.
   .. index:: --RTS  (gnatbind)
 
 :switch:`--RTS={rts-path}`
-  Specifies the default location of the runtime library. Same meaning as the
+  Specifies the default location of the run-time library. Same meaning as the
   equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
 
   .. index:: -o   (gnatbind)
@@ -6470,13 +6496,13 @@  be presented in subsequent sections.
 .. index:: -static  (gnatbind)
 
 :switch:`-static`
-  Link against a static GNAT run time.
+  Link against a static GNAT run-time.
 
 
   .. index:: -shared  (gnatbind)
 
 :switch:`-shared`
-  Link against a shared GNAT run time when available.
+  Link against a shared GNAT run-time when available.
 
 
   .. index:: -t  (gnatbind)
@@ -6495,7 +6521,7 @@  be presented in subsequent sections.
   nonzero value will activate round-robin scheduling.
 
   A value of zero is treated specially. It turns off time
-  slicing, and in addition, indicates to the tasking run time that the
+  slicing, and in addition, indicates to the tasking run-time that the
   semantics should match as closely as possible the Annex D
   requirements of the Ada RM, and in particular sets the default
   scheduling policy to ``FIFO_Within_Priorities``.
@@ -6939,7 +6965,7 @@  The output is an Ada unit in source form that can be compiled with GNAT.
 This compilation occurs automatically as part of the ``gnatlink``
 processing.
 
-Currently the GNAT run time requires a FPU using 80 bits mode
+Currently the GNAT run-time requires a FPU using 80 bits mode
 precision. Under targets where this is not the default it is required to
 call GNAT.Float_Control.Reset before using floating point numbers (this
 include float computation, float input and output) in the Ada code. A
@@ -7040,7 +7066,7 @@  directories searched are:
 
 * The content of the :file:`ada_object_path` file which is part of the GNAT
   installation tree and is used to store standard libraries such as the
-  GNAT Run Time Library (RTL) unless the switch :switch:`-nostdlib` is
+  GNAT Run-Time Library (RTL) unless the switch :switch:`-nostdlib` is
   specified. See :ref:`Installing_a_library`
 
 .. index:: -I  (gnatbind)

--- gcc/ada/gnat_ugn.texi
+++ gcc/ada/gnat_ugn.texi
@@ -8157,9 +8157,9 @@  Do not look for library files in the system default directory.
 
 @item @code{--RTS=@emph{rts-path}}
 
-Specifies the default location of the runtime library. GNAT looks for the
-runtime
-in the following directories, and stops as soon as a valid runtime is found
+Specifies the default location of the run-time library. GNAT looks for the
+run-time
+in the following directories, and stops as soon as a valid run-time is found
 (@code{adainclude} or @code{ada_source_path}, and @code{adalib} or
 @code{ada_object_path} present):
 
@@ -9170,7 +9170,7 @@  Detect_Aliasing (Obj, Self (Obj));
 @end example
 
 In the example above, the first call to @code{Detect_Aliasing} fails with a
-@code{Program_Error} at runtime because the actuals for @code{Val_1} and
+@code{Program_Error} at run time because the actuals for @code{Val_1} and
 @code{Val_2} denote the same object. The second call executes without raising
 an exception because @code{Self(Obj)} produces an anonymous object which does
 not share the memory location of @code{Obj}.
@@ -9577,14 +9577,12 @@  Externals names are folded to all uppercase.
 
 @item @code{-gnatg}
 
-Internal GNAT implementation mode. This should not be used for
-applications programs, it is intended only for use by the compiler
-and its run-time library. For documentation, see the GNAT sources.
-Note that @code{-gnatg} implies
-@code{-gnatw.ge} and
-@code{-gnatyg}
-so that all standard warnings and all standard style options are turned on.
-All warnings and style messages are treated as errors.
+Internal GNAT implementation mode. This should not be used for applications
+programs, it is intended only for use by the compiler and its run-time
+library. For documentation, see the GNAT sources. Note that @code{-gnatg}
+implies @code{-gnatw.ge} and @code{-gnatyg} so that all standard
+warnings and all standard style options are turned on. All warnings and style
+messages are treated as errors.
 @end table
 
 @geindex -gnatG[nn] (gcc)
@@ -9607,6 +9605,17 @@  List generated expanded code in source form.
 Output usage information. The output is written to @code{stdout}.
 @end table
 
+@geindex -gnatH (gcc)
+
+
+@table @asis
+
+@item @code{-gnatH}
+
+Legacy elaboration-checking mode enabled. When this switch is in effect, the
+pre-18.x access-before-elaboration model becomes the de facto model.
+@end table
+
 @geindex -gnati (gcc)
 
 
@@ -9654,6 +9663,56 @@  from the tree and ignored. This means that the tool will not see them.
 Reformat error messages to fit on @code{nn} character lines
 @end table
 
+@geindex -gnatJ (gcc)
+
+
+@table @asis
+
+@item @code{-gnatJ}
+
+Permissive elaboration-checking mode enabled. When this switch is in effect,
+the post-18.x access-before-elaboration model ignores potential issues with:
+
+
+@itemize -
+
+@item 
+Accept statements
+
+@item 
+Activations of tasks defined in instances
+
+@item 
+Assertion pragmas
+
+@item 
+Calls from within an instance to its enclosing context
+
+@item 
+Calls through generic formal parameters
+
+@item 
+Calls to subprograms defined in instances
+
+@item 
+Entry calls
+
+@item 
+Indirect calls using 'Access
+
+@item 
+Requeue statements
+
+@item 
+Select statements
+
+@item 
+Synchronous task suspension
+@end itemize
+
+and does not emit compile-time diagnostics or run-time checks.
+@end table
+
 @geindex -gnatk (gcc)
 
 
@@ -10195,7 +10254,7 @@  exit status.
 
 @item @code{--RTS=@emph{rts-path}}
 
-Specifies the default location of the runtime library. Same meaning as the
+Specifies the default location of the run-time library. Same meaning as the
 equivalent @code{gnatmake} flag (@ref{dc,,Switches for gnatmake}).
 @end table
 
@@ -13981,7 +14040,7 @@  if checks are suppressed. In particular, if the compiler can prove
 that a certain check will necessarily fail, it will generate code to
 do an unconditional 'raise', even if checks are suppressed. The
 compiler warns in this case. Another case in which checks may not be
-eliminated is when they are embedded in certain run time routines such
+eliminated is when they are embedded in certain run-time routines such
 as math library routines.
 
 Of course, run-time checks are omitted whenever the compiler can prove
@@ -15089,7 +15148,7 @@  speed up compilation, but means that these tools cannot be used.
 @subsection Exception Handling Control
 
 
-GNAT uses two methods for handling exceptions at run-time. The
+GNAT uses two methods for handling exceptions at run time. The
 @code{setjmp/longjmp} method saves the context when entering
 a frame with an exception handler. Then when an exception is
 raised, the context can be restored immediately, without the
@@ -15706,7 +15765,7 @@  Do not look for library files in the system default directory.
 
 @item @code{--RTS=@emph{rts-path}}
 
-Specifies the default location of the runtime library. Same meaning as the
+Specifies the default location of the run-time library. Same meaning as the
 equivalent @code{gnatmake} flag (@ref{dc,,Switches for gnatmake}).
 
 @geindex -o (gnatbind)
@@ -15823,13 +15882,13 @@  then the default is @code{in} (invalid values).
 
 @item @code{-static}
 
-Link against a static GNAT run time.
+Link against a static GNAT run-time.
 
 @geindex -shared (gnatbind)
 
 @item @code{-shared}
 
-Link against a shared GNAT run time when available.
+Link against a shared GNAT run-time when available.
 
 @geindex -t (gnatbind)
 
@@ -15848,7 +15907,7 @@  does support some general notion of round-robin scheduling, then any
 nonzero value will activate round-robin scheduling.
 
 A value of zero is treated specially. It turns off time
-slicing, and in addition, indicates to the tasking run time that the
+slicing, and in addition, indicates to the tasking run-time that the
 semantics should match as closely as possible the Annex D
 requirements of the Ada RM, and in particular sets the default
 scheduling policy to @code{FIFO_Within_Priorities}.
@@ -16366,7 +16425,7 @@  The output is an Ada unit in source form that can be compiled with GNAT.
 This compilation occurs automatically as part of the @code{gnatlink}
 processing.
 
-Currently the GNAT run time requires a FPU using 80 bits mode
+Currently the GNAT run-time requires a FPU using 80 bits mode
 precision. Under targets where this is not the default it is required to
 call GNAT.Float_Control.Reset before using floating point numbers (this
 include float computation, float input and output) in the Ada code. A
@@ -16491,7 +16550,7 @@  of GNAT).
 @item 
 The content of the @code{ada_object_path} file which is part of the GNAT
 installation tree and is used to store standard libraries such as the
-GNAT Run Time Library (RTL) unless the switch @code{-nostdlib} is
+GNAT Run-Time Library (RTL) unless the switch @code{-nostdlib} is
 specified. See @ref{87,,Installing a library}
 @end itemize