+2018-07-17 Hristian Kirtchev <kirtchev@adacore.com>
+
+ * doc/gnat_ugn/building_executable_programs_with_gnat.rst: Add missing
+ sections on -gnatH and -gnatJ compiler switches.
+ * gnat_ugn.texi: Regenerate.
+
2018-07-17 Hristian Kirtchev <kirtchev@adacore.com>
* alloc.ads: Update the allocation metrics of the ignored Ghost nodes
.. 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):
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``.
.. 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)
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}`
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}`
.. 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`).
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
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
.. 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)
.. 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)
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``.
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
* 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)
@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):
@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}.
@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)
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)
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)
@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
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
@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
@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)
@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)
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}.
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
@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
projects / gcc.git / commitdiff