CbC/CbC_gcc: gcc/ada/doc/gnat_ugn/building_executable_programs_with

comparison gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst @ 145:1830386684a0

gcc-9.2.0

author	anatofuz
date	Thu, 13 Feb 2020 11:34:05 +0900
parents	84e7813d76e9
children

comparison

equal deleted inserted replaced

-:84e7813d76e9
+:1830386684a0
 :switch:`-fdump-scos`
 Generates SCO (Source Coverage Obligation) information in the ALI file.
 This information is used by advanced coverage tools. See unit :file:`SCOs`
 in the compiler sources for details in files :file:`scos.ads` and
 :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}]`
 ``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_Scalar_Alignment`` is the alignment for a scalar whose size is two
+``Double_Float_Alignment``, if not zero, is the maximum alignment that the
-machine words. It should be the same as the alignment for C ``long_long`` on
+compiler can choose by default for a 64-bit floating-point type or object.
-most targets.
+``Double_Scalar_Alignment``, if not zero, is the maximum alignment that the
-``Maximum_Alignment`` is the maximum alignment that the compiler might choose
+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.`
 .. 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)
 :switch:`-gnatf`
 .. index:: -gnatH  (gcc)
 :switch:`-gnatH`
-Legacy elaboration-checking mode enabled. When this switch is in effect, the
+Legacy elaboration-checking mode enabled. When this switch is in effect,
-pre-18.x access-before-elaboration model becomes the de facto model.
+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}`
 - Indirect calls using 'Access
 - Requeue statements
 - Select statements
 - Synchronous task suspension
-and does not emit compile-time diagnostics or run-time checks.
+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}`
 Treat pragma Restrictions as Restriction_Warnings.
 .. 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
 are not compatible.
 e.adb:3:04: Incorrect spelling of keyword "function"
 e.adb:4:20: ";" should be "is"
 The first integer after the file name is the line number in the file,
 and the second integer is the column number within the line.
-``GPS`` can parse the error messages
+``GNAT Studio`` can parse the error messages
 and point to the referenced character.
 The following switches provide control over the error message
 format:
 .. index:: -gnatwa  (gcc)
 :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:`-gnatwo` (address clause overlay)
 * :switch:`-gnatw.o` (values set by out parameters ignored)
 * :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)
 This switch suppresses warnings for assertions where the compiler can tell at
 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`
 *Activate warnings on bad fixed values.*
 representation clause is present and has component clauses for the
 majority, but not all, of the components. A warning is given for each
 component for which no component clause is present.
-.. index:: -gnatwC  (gcc)
+.. index:: -gnatw.C  (gcc)
 :switch:`-gnatw.C`
 *Suppress warnings on missing component clauses.*
 This switch suppresses warnings for record components that are
 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 unknown condition in Compile_Time_Warning.*
+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`
 function call, which is equivalent to a constant declaration (as
 opposed to renaming the function itself).  The default is that these
 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`
 .. index:: Size/Alignment warnings
 :switch:`-gnatw.z`
 *Activate warnings for size not a multiple of alignment.*
-This switch activates warnings for cases of record types with
+This switch activates warnings for cases of array and record types
-specified ``Size`` and ``Alignment`` attributes where the
+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.
 .. index:: Size/Alignment warnings
 :switch:`-gnatw.Z`
 *Suppress warnings for size not a multiple of alignment.*
-This switch suppresses warnings for cases of record types with
+This switch suppresses warnings for cases of array and record types
-specified ``Size`` and ``Alignment`` attributes where the
+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.
+size that is greater than the specified size. The warning can also
-The warning can also be
+be suppressed by giving an explicit ``Object_Size`` value.
-suppressed by giving an explicit ``Object_Size`` value.
 .. index:: -Wunused (gcc)
 :switch:`-Wunused`
 All lines must be terminated by a single ASCII.LF
 character (in particular the DOS line terminator sequence CR/LF is not
 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`
 *Check end/exit labels.*
 :switch:`-gnatyg`
 *GNAT style mode.*
 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.
 .. index:: -gnatyh (gcc)
 style check option. That is, it cancels the effect of a previous -,
 if any.
 .. end of switch description (leave this comment to ease automatic parsing for
-.. GPS
+.. GNAT Studio
 In the above rules, appearing in column one is always permitted, that is,
 counts as meeting either a requirement for a required preceding space,
 or as meeting a requirement for no preceding space.
 $ gcc -c -gnats x.adb
 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.
 You may use other switches in conjunction with :switch:`-gnats`. In
 particular, :switch:`-gnatl` and :switch:`-gnatv` are useful to control the
 restriction warnings rather than restrictions.
 .. 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
 latter case occurs for objects of a type for which a ``Linker_Section``
 is set).
 at run time for records are included. These symbolic expressions have
 a mostly obvious format with #n being used to represent the value of 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.
 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 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
+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
 Ada syntax, for example ``at 0 range 0 .. -1``.
 Normally the compiler generates full cross-referencing information in
 the :file:`ALI` file. This information is used by a number of tools,
 including ``gnatfind`` and ``gnatxref``. The :switch:`-gnatx` switch
 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
 --------------------------
 .. 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)
 :switch:`-F`
 Force the checks of elaboration flags. ``gnatbind`` does not normally
 :switch:`-h`
 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
 :switch:`-H64`
 Use 64-bit allocations for ``__gnat_malloc`` (and thus for access types).
 For further details see :ref:`Dynamic_Allocation_Control`.
 .. index:: -M  (gnatbind)
 :switch:`-M{xyz}`
 Rename generated main program from main to xyz. This option is
 supported on cross environments only.
 .. index:: -m  (gnatbind)
 :switch:`-m{n}`
 Limit number of detected errors or warnings to ``n``, where ``n`` is
 continues in this case. If the number of errors reaches this
 limit, then a message is output and the bind is abandoned.
 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:
+* Starting the program's execution in the debugger will cause it to
+stop at the start of the ``main`` function instead of the main subprogram.
+This can be worked around by manually inserting a breakpoint on that
+subprogram and resuming the program's execution until reaching that breakpoint.
+* Programs using GNAT.Compiler_Version will not link.
 .. index:: -n  (gnatbind)
 :switch:`-n`
 No main program.
 Elaboration Control
 ^^^^^^^^^^^^^^^^^^^
 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)
 :switch:`-f{elab-order}`
 Blank lines and Ada-style comments are ignored. Unit names that do not exist
 in the program are ignored. Units in the GNAT predefined library are also
 ignored.
 .. index:: -p  (gnatbind)
 :switch:`-p`
-Normally the binder attempts to choose an elaboration order that is
+Pessimistic elaboration order
-likely to minimize the likelihood of an elaboration order error resulting
-in raising a ``Program_Error`` exception. This switch reverses the
+This switch is only applicable to the pre-20.x legacy elaboration models.
-action of the binder, and requests that it deliberately choose an order
+The post-20.x elaboration model uses a more informed approach of ordering
-that is likely to maximize the likelihood of an elaboration error.
+the units.
-This is useful in ensuring portability and avoiding dependence on
-accidental fortuitous elaboration ordering.
+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
-Normally it only makes sense to use the :switch:`-p`
+``Program_Error`` exception. This switch reverses the action of the binder,
-switch if dynamic
+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
+These implicit pragmas are still respected by the binder in :switch:`-p`
-:switch:`-p` mode, so a
+mode, so a safe elaboration order is assured.
-safe elaboration order is assured.
+Note that :switch:`-p` is not intended for production use; it is more for
-Note that :switch:`-p` is not intended for
+debugging/experimental use.
-production use; it is more for debugging/experimental use.
 .. _Output_Control:
 Output Control
 ^^^^^^^^^^^^^^

Mercurial > hg > CbC > CbC_gcc

comparison gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst @ 145:1830386684a0