.. 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):
: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}]`
of the program, instead of a fragmentary view with the usual approach.
This can also speed up the compilation of big programs and reduce the
size of the executable, compared with a traditional per-unit compilation
- with inlining across modules enabled by the :switch:`-gnatn` switch.
+ with inlining across units enabled by the :switch:`-gnatn` switch.
The drawback of this approach is that it may require more memory and that
the debugging information generated by -g with it might be hardly usable.
The switch, as well as the accompanying :switch:`-Ox` switches, must be
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``.
Maximum_Alignment : Pos; -- Maximum permitted alignment
Max_Unaligned_Field : Pos; -- Maximum size for unaligned bit field
Pointer_Size : Pos; -- System.Address'Size
- Short_Enums : Nat; -- Short foreign convention enums?
+ Short_Enums : Nat; -- Foreign enums use short size?
Short_Size : Pos; -- Standard.Short_Integer'Size
Strict_Alignment : Nat; -- Strict alignment?
System_Allocator_Alignment : Nat; -- Alignment for malloc calls
Wchar_T_Size : Pos; -- Interfaces.C.wchar_t'Size
Words_BE : Nat; -- Words stored big-endian?
+ ``Bits_Per_Unit`` is the number of bits in a storage unit, the equivalent of
+ GCC macro ``BITS_PER_UNIT`` documented as follows: `Define this macro to be
+ the number of bits in an addressable storage unit (byte); normally 8.`
+
+ ``Bits_Per_Word`` is the number of bits in a machine word, the equivalent of
+ GCC macro ``BITS_PER_WORD`` documented as follows: `Number of bits in a word;
+ normally 32.`
+
+ ``Double_Float_Alignment``, if not zero, is the maximum alignment that the
+ compiler can choose by default for a 64-bit floating-point type or object.
+
+ ``Double_Scalar_Alignment``, if not zero, is the maximum alignment that the
+ compiler can choose by default for a 64-bit or larger scalar type or object.
+
+ ``Maximum_Alignment`` is the maximum alignment that the compiler can choose
+ by default for a type or object, which is also the maximum alignment that can
+ be specified in GNAT. It is computed for GCC backends as ``BIGGEST_ALIGNMENT
+ / BITS_PER_UNIT`` where GCC macro ``BIGGEST_ALIGNMENT`` is documented as
+ follows: `Biggest alignment that any data type can require on this machine,
+ in bits.`
+
+ ``Max_Unaligned_Field`` is the maximum size for unaligned bit field, which is
+ 64 for the majority of GCC targets (but can be different on some targets like
+ AAMP).
+
+ ``Strict_Alignment`` is the equivalent of GCC macro ``STRICT_ALIGNMENT``
+ documented as follows: `Define this macro to be the value 1 if instructions
+ will fail to work if given data not on the nominal alignment. If instructions
+ will merely go slower in that case, define this macro as 0.`
+
+ ``System_Allocator_Alignment`` is the guaranteed alignment of data returned
+ by calls to ``malloc``.
+
The format of the input file is as follows. First come the values of
the variables defined above, with one line per value:
.. index:: -gnatE (gcc)
:switch:`-gnatE`
- Full dynamic elaboration checks.
+ Dynamic elaboration checking mode enabled. For further details see
+ :ref:`Elaboration_Order_Handling_in_GNAT`.
.. index:: -gnatf (gcc)
.. 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.
+ For further details see :ref:`Elaboration_Order_Handling_in_GNAT`.
+
+
.. 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. For further
+ details see :ref:`Elaboration_Order_Handling_in_GNAT`.
+
+
.. index:: -gnatk (gcc)
:switch:`-gnatk={n}`
.. index:: -gnatn (gcc)
:switch:`-gnatn[12]`
- Activate inlining across modules for subprograms for which pragma ``Inline``
+ Activate inlining across units for subprograms for which pragma ``Inline``
is specified. This inlining is performed by the GCC back-end. An optional
- digit sets the inlining level: 1 for moderate inlining across modules
- or 2 for full inlining across modules. If no inlining level is specified,
+ digit sets the inlining level: 1 for moderate inlining across units
+ or 2 for full inlining across units. If no inlining level is specified,
the compiler will pick it based on the optimization level.
.. index:: -gnatR (gcc)
-:switch:`-gnatR[0|1|2|3][e][j][m][s]`
+:switch:`-gnatR[0|1|2|3|4][e][j][m][s]`
Output representation information for declared types, objects and
subprograms. Note that this switch is not allowed if a previous
:switch:`-gnatD` switch has been given, since these two 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`).
:switch:`-gnatwa`
*Activate most optional warnings.*
- This switch activates most optional warning messages. See the remaining list
+ This switch activates most optional warning messages. See the remaining list
in this section for details on optional warning messages that can be
individually controlled. The warnings that are not turned on by this
switch are:
* :switch:`-gnatw.q` (questionable layout of record types)
+ * :switch:`-gnatw_r` (out-of-order record representation clauses)
+
* :switch:`-gnatw.s` (overridden size clause)
* :switch:`-gnatwt` (tracking of deleted conditional code)
compile time that the assertion will fail.
+.. index:: -gnatw_a
+
+:switch:`-gnatw_a`
+ *Activate warnings on anonymous allocators.*
+
+ .. index:: Anonymous allocators
+
+ This switch activates warnings for allocators of anonymous access types,
+ which can involve run-time accessibility checks and lead to unexpected
+ accessibility violations. For more details on the rules involved, see
+ RM 3.10.2 (14).
+
+
+.. index:: -gnatw_A
+
+:switch:`-gnatw_A`
+ *Supress warnings on anonymous allocators.*
+
+ .. index:: Anonymous allocators
+
+ This switch suppresses warnings for anonymous access type allocators.
+
+
.. index:: -gnatwb (gcc)
:switch:`-gnatwb`
component for which no component clause is present.
-.. index:: -gnatwC (gcc)
+.. index:: -gnatw.C (gcc)
:switch:`-gnatw.C`
*Suppress warnings on missing component clauses.*
missing a component clause in the situation described above.
+.. index:: -gnatw_c (gcc)
+
+:switch:`-gnatw_c`
+ *Activate warnings on unknown condition in Compile_Time_Warning.*
+
+ .. index:: Compile_Time_Warning
+ .. index:: Compile_Time_Error
+
+ This switch activates warnings on a pragma Compile_Time_Warning
+ or Compile_Time_Error whose condition has a value that is not
+ known at compile time.
+ The default is that such warnings are generated.
+
+
+.. index:: -gnatw_C (gcc)
+
+:switch:`-gnatw_C`
+ *Suppress warnings on missing component clauses.*
+
+ This switch supresses warnings on a pragma Compile_Time_Warning
+ or Compile_Time_Error whose condition has a value that is not
+ known at compile time.
+
+
.. index:: -gnatwd (gcc)
:switch:`-gnatwd`
warnings are given.
-.. index:: -gnatwT (gcc)
+.. index:: -gnatw.R (gcc)
:switch:`-gnatw.R`
*Suppress warnings for object renaming function.*
This switch suppresses warnings for object renaming function.
+.. index:: -gnatw_r (gcc)
+
+:switch:`-gnatw_r`
+ *Activate warnings for out-of-order record representation clauses.*
+
+ This switch activates warnings for record representation clauses,
+ if the order of component declarations, component clauses,
+ and bit-level layout do not all agree.
+ The default is that these warnings are not given.
+
+
+.. index:: -gnatw_R (gcc)
+
+:switch:`-gnatw_R`
+ *Suppress warnings for out-of-order record representation clauses.*
+
+
.. index:: -gnatws (gcc)
:switch:`-gnatws`
:switch:`-gnatw.z`
*Activate warnings for size not a multiple of alignment.*
- This switch activates warnings for cases of record types with
- specified ``Size`` and ``Alignment`` attributes where the
+ This switch activates warnings for cases of array and record types
+ with specified ``Size`` and ``Alignment`` attributes where the
size is not a multiple of the alignment, resulting in an object
size that is greater than the specified size. The default
is that such warnings are generated.
:switch:`-gnatw.Z`
*Suppress warnings for size not a multiple of alignment.*
- This switch suppresses warnings for cases of record types with
- specified ``Size`` and ``Alignment`` attributes where the
+ This switch suppresses warnings for cases of array and record types
+ with specified ``Size`` and ``Alignment`` attributes where the
size is not a multiple of the alignment, resulting in an object
- size that is greater than the specified size.
- The warning can also be
- suppressed by giving an explicit ``Object_Size`` value.
+ size that is greater than the specified size. The warning can also
+ be suppressed by giving an explicit ``Object_Size`` value.
.. index:: -Wunused (gcc)
allowed).
+.. index:: -gnatyD (gcc)
+
+:switch:`-gnatyD`
+ *Check declared identifiers in mixed case.*
+
+ Declared identifiers must be in mixed case, as in
+ This_Is_An_Identifier. Use -gnatyr in addition to ensure
+ that references match declarations.
+
+
.. index:: -gnatye (gcc)
:switch:`-gnatye`
The set of style check switches is set to match that used by the GNAT sources.
This may be useful when developing code that is eventually intended to be
- incorporated into GNAT. Currently this is equivalent to :switch:`-gnatwydISux`)
+ incorporated into GNAT. Currently this is equivalent to :switch:`-gnatyydISux`)
but additional style switches may be added to this set in the future without
advance notice.
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
compiles file :file:`x.adb` in syntax-check-only mode. You can check a
series of files in a single command
- , and can use wild cards to specify such a group of files.
+ , and can use wildcards to specify such a group of files.
Note that you must specify the :switch:`-c` (compile
only) flag in addition to the :switch:`-gnats` flag.
The ``n`` here is intended to suggest the first syllable of the word 'inline'.
GNAT recognizes and processes ``Inline`` pragmas. However, for inlining to
actually occur, optimization must be enabled and, by default, inlining of
- subprograms across modules is not performed. If you want to additionally
- enable inlining of subprograms specified by pragma ``Inline`` across modules,
+ subprograms across units is not performed. If you want to additionally
+ enable inlining of subprograms specified by pragma ``Inline`` across units,
you must also specify this switch.
- In the absence of this switch, GNAT does not attempt inlining across modules
+ In the absence of this switch, GNAT does not attempt inlining across units
and does not access the bodies of subprograms for which ``pragma Inline`` is
specified if they are not in the current unit.
You can optionally specify the inlining level: 1 for moderate inlining across
- modules, which is a good compromise between compilation times and performances
- at run time, or 2 for full inlining across modules, which may bring about
+ units, which is a good compromise between compilation times and performances
+ at run time, or 2 for full inlining across units, which may bring about
longer compilation times. If no inlining level is specified, the compiler will
pick it based on the optimization level: 1 for :switch:`-O1`, :switch:`-O2` or
:switch:`-Os` and 2 for :switch:`-O3`.
.. index:: -gnatR (gcc)
-:switch:`-gnatR[0|1|2|3][e][j][m][s]`
+:switch:`-gnatR[0|1|2|3|4][e][j][m][s]`
This switch controls output from the compiler of a listing showing
representation information for declared types, objects and subprograms.
For :switch:`-gnatR0`, no information is output (equivalent to omitting
the :switch:`-gnatR` switch). For :switch:`-gnatR1` (which is the default,
so :switch:`-gnatR` with no parameter has the same effect), size and
alignment information is listed for declared array and record types.
+
For :switch:`-gnatR2`, size and alignment information is listed for all
declared types and objects. The ``Linker_Section`` is also listed for any
entity for which the ``Linker_Section`` is set explicitly or implicitly (the
n'th discriminant. See source files :file:`repinfo.ads/adb` in the
GNAT sources for full details on the format of :switch:`-gnatR3` output.
+ For :switch:`-gnatR4`, information for relevant compiler-generated types
+ is also listed, i.e. when they are structurally part of other declared
+ types and objects.
+
If the switch is followed by an ``e`` (e.g. :switch:`-gnatR2e`), then
extended representation information for record sub-components of records
- are included.
+ is included.
If the switch is followed by an ``m`` (e.g. :switch:`-gnatRm`), then
subprogram conventions and parameter passing mechanisms for all the
subprograms are included.
- If the switch is followed by an ``s`` (e.g., :switch:`-gnatR3s`), then
- the output is to a file with the name :file:`file.rep` where file is
- the name of the corresponding source file.
+ If the switch is followed by a ``j`` (e.g., :switch:`-gnatRj`), then
+ the output is in the JSON data interchange format specified by the
+ ECMA-404 standard. The semantic description of this JSON output is
+ available in the specification of the Repinfo unit present in the
+ compiler sources.
- If the switch is followed by a ``j`` (e.g., :switch:`-gnatR3j`), then
- the output is to a file with the name :file:`file.json` where file is
- the name of the corresponding source file, and it uses the JSON data
- interchange format specified by the ECMA-404 standard. The semantic
- description of this JSON output is available in the specification of
- the Repinfo unit present in the compiler sources.
+ If the switch is followed by an ``s`` (e.g., :switch:`-gnatR3s`), then
+ the output is to a file with the name :file:`file.rep` where ``file`` is
+ the name of the corresponding source file, except if ``j`` is also
+ specified, in which case the file name is :file:`file.json`.
Note that it is possible for record components to have zero size. In
this case, the component clause uses an obvious extension of permitted
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
--------------------------
-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:: -f (gnatbind)
:switch:`-f{elab-order}`
- Force elaboration order.
+ Force elaboration order. For further details see :ref:`Elaboration_Control`
+ and :ref:`Elaboration_Order_Handling_in_GNAT`.
+
.. index:: -F (gnatbind)
Output usage (help) information.
- .. index:: -H32 (gnatbind)
+.. index:: -H (gnatbind)
+
+:switch:`-H`
+ Legacy elaboration order model enabled. For further details see
+ :ref:`Elaboration_Order_Handling_in_GNAT`.
+
+
+.. index:: -H32 (gnatbind)
:switch:`-H32`
Use 32-bit allocations for ``__gnat_malloc`` (and thus for access types).
For further details see :ref:`Dynamic_Allocation_Control`.
- .. index:: -H64 (gnatbind)
- .. index:: __gnat_malloc
+.. index:: -H64 (gnatbind)
+.. index:: __gnat_malloc
:switch:`-H64`
Use 64-bit allocations for ``__gnat_malloc`` (and thus for access types).
Rename generated main program from main to xyz. This option is
supported on cross environments only.
-
.. index:: -m (gnatbind)
:switch:`-m{n}`
A value of zero means that no limit is enforced. The equal
sign is optional.
+ .. index:: -minimal (gnatbind)
+
+:switch:`-minimal`
+ Generate a binder file suitable for space-constrained applications. When
+ active, binder-generated objects not required for program operation are no
+ longer generated. **Warning:** this option comes with the following
+ limitations:
+
+ * Debugging will not work;
+ * Programs using GNAT.Compiler_Version will not link.
.. index:: -n (gnatbind)
.. 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``.
^^^^^^^^^^^^^^^^^^^
The following switches provide additional control over the elaboration
-order. For full details see :ref:`Elaboration_Order_Handling_in_GNAT`.
+order. For further details see :ref:`Elaboration_Order_Handling_in_GNAT`.
.. index:: -f (gnatbind)
ignored.
- .. index:: -p (gnatbind)
+.. index:: -p (gnatbind)
:switch:`-p`
- Normally the binder attempts to choose an elaboration order that is
- likely to minimize the likelihood of an elaboration order error resulting
- in raising a ``Program_Error`` exception. This switch reverses the
- action of the binder, and requests that it deliberately choose an order
- that is likely to maximize the likelihood of an elaboration error.
- This is useful in ensuring portability and avoiding dependence on
- accidental fortuitous elaboration ordering.
-
- Normally it only makes sense to use the :switch:`-p`
- switch if dynamic
+ Pessimistic elaboration order
+
+ This switch is only applicable to the pre-20.x legacy elaboration models.
+ The post-20.x elaboration model uses a more informed approach of ordering
+ the units.
+
+ Normally the binder attempts to choose an elaboration order that is likely to
+ minimize the likelihood of an elaboration order error resulting in raising a
+ ``Program_Error`` exception. This switch reverses the action of the binder,
+ and requests that it deliberately choose an order that is likely to maximize
+ the likelihood of an elaboration error. This is useful in ensuring
+ portability and avoiding dependence on accidental fortuitous elaboration
+ ordering.
+
+ Normally it only makes sense to use the :switch:`-p` switch if dynamic
elaboration checking is used (:switch:`-gnatE` switch used for compilation).
This is because in the default static elaboration mode, all necessary
``Elaborate`` and ``Elaborate_All`` pragmas are implicitly inserted.
- These implicit pragmas are still respected by the binder in
- :switch:`-p` mode, so a
- safe elaboration order is assured.
+ These implicit pragmas are still respected by the binder in :switch:`-p`
+ mode, so a safe elaboration order is assured.
- Note that :switch:`-p` is not intended for
- production use; it is more for debugging/experimental use.
+ Note that :switch:`-p` is not intended for production use; it is more for
+ debugging/experimental use.
.. _Output_Control:
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)
projects / thirdparty / gcc.git / blobdiff