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

comparison gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst @ 131:84e7813d76e9

gcc-8.2

author	mir3636
date	Thu, 25 Oct 2018 07:37:49 +0900
parents	04ced10e8804
children	1830386684a0

comparison

equal deleted inserted replaced

-:04ced10e8804
+:84e7813d76e9
 * :ref:`The_Cross-Referencing_Tools_gnatxref_and_gnatfind`
 * :ref:`The_Ada_to_HTML_Converter_gnathtml`
 * :ref:`The_Ada-to-XML_Converter_gnat2xml`
 * :ref:`The_Coding_Standard_Verifier_gnatcheck`
 * :ref:`The_GNAT_Metrics_Tool_gnatmetric`
-* :ref:`The_GNAT_Pretty-Printer_gnatpp`
+* :ref:`The_GNAT_Pretty_Printer_gnatpp`
 * :ref:`The_Body_Stub_Generator_gnatstub`
 * :ref:`The_Unit_Test_Generator_gnattest`
+* :ref:`The_Backtrace_Symbolizer_gnatsymbolize`
 It also describes how several of these tools can be used in conjunction
 with project files: :ref:`Using_Project_Files_with_GNAT_Tools`
 .. only:: FSF
 .. index:: --ext (gnatxref)
 :switch:`--ext={extension}`
 Specify an alternate ali file extension. The default is ``ali`` and other
 extensions (e.g. ``gli`` for C/C++ sources) may be specified via this switch.
-Note that if this switch overrides the default, which means that only the
+Note that if this switch overrides the default, only the new extension will
-new extension will be considered.
+be considered.
 .. index:: --RTS (gnatxref)
 :switch:`--RTS={rts-path}`
 .. index:: --ext (gnatfind)
 :switch:`--ext={extension}`
 Specify an alternate ali file extension. The default is ``ali`` and other
-extensions (e.g. ``gli`` for C/C++ sources when using :switch:`-fdump-xref`)
+extensions may be specified via this switch. Note that if this switch
-may be specified via this switch. Note that if this switch overrides the
+overrides the default, only the new extension will be considered.
-default, which means that only the new extension will be considered.
 .. index:: --RTS (gnatfind)
 :switch:`--RTS={rts-path}`
 Take as arguments the files listed in text file ``file``.
 Text file ``file`` may contain empty lines that are ignored.
 Each nonempty line should contain the name of an existing file.
 Several such switches may be specified simultaneously.
+:switch:`--ignore={filename}`
+Do not process the sources listed in a specified file. This option cannot
+be used in incremental mode.
 :switch:`-q`
 Quiet
 :switch:`-v`
 Verbose
 ``gnat2xml`` generates XML files that will validate against
 :file:`ada-schema.xsd`.
-``xml2gnat`` is a back-translator that translates the XML back
+``xml2gnat`` is a back-translator that translates the XML back into
-into Ada source code. The Ada generated by ``xml2gnat`` has
+Ada source code. This is primarily for the purpose of testing
-identical semantics to the original Ada code passed to
+``gnat2xml``, rather than for users. The Ada generated by ``xml2gnat``
-``gnat2xml``. It is not textually identical, however --- for
+has identical semantics to the original Ada code passed to
-example, no attempt is made to preserve the original indentation.
+``gnat2xml``. It is not textually identical, however --- for example,
+no attempt is made to preserve the original indentation.
+The ``xml2gnat`` command line contains a list of the same Ada files
+passed to gnat2xml (not the names of xml files). The xml files are
+assumed to be in an 'xml' subdirectory of the directory in which the
+Ada source files are. So for example, if the Ada source file is
+some/dir/mumble.adb, then the xml file is found in
+some/dir/xml/mumble.adb.xml. You should use the :switch:`--output-dir`
+switch of ``gnat2xml`` to tell it to generate the output in the xml
+subdirectory, so ``xml2gnat`` can find it.
+Output goes into subdirectories "generated_ada" and "self_rep" of the
+output directory, which is the current directory by default, but can
+be overridden with --output-dir=dir on the command line.
 .. _Structure_of_the_XML:
 Structure of the XML
 --------------------
 .. index:: -P (gnatmetric)
 :switch:`-P {file}`
 Indicates the name of the project file that describes the set of sources
 to be processed. The exact set of argument sources depends on other options
-specified, see below.
+specified, see below. An aggregate project is allowed as the file parameter
+only if it has exactly one non-aggregate project being aggregated.
 .. index:: -U (gnatmetric)
 :switch:`-U`
 Text file ``file`` may contain empty lines that are ignored.
 Each nonempty line should contain the name of an existing file.
 Several such switches may be specified simultaneously.
+.. index:: --ignore (gnatmetric)
+:switch:`--ignore={filename}`
+Do not process the sources listed in a specified file.
 .. index:: -j (gnatmetric)
 :switch:`-j{n}`
 Use ``n`` processes to carry out the tree creations (internal representations
 of the argument sources). On a multiprocessor machine this speeds up processing
 all the immediate units of the argument project.
 .. only:: PRO or GPL
-.. _The_GNAT_Pretty-Printer_gnatpp:
+.. _The_GNAT_Pretty_Printer_gnatpp:
-The GNAT Pretty-Printer ``gnatpp``
+The GNAT Pretty Printer ``gnatpp``
 ==================================
 .. index:: ! gnatpp
-.. index:: Pretty-Printer
+.. index:: pretty printer
-The ``gnatpp`` tool is an ASIS-based utility
+This documentation is for the new libadalang-based version
-for source reformatting / pretty-printing.
+of ``gnatpp``, which replaces the ASIS-based version.
-It takes an Ada source file as input and generates a reformatted
-version as output.
+The ``gnatpp`` tool is a utility for source reformatting / pretty
-You can specify various style directives via switches; e.g.,
+printing.  It takes an Ada source file as input and generates a
-identifier case conventions, rules of indentation, and comment layout.
+reformatted version as output.  You can specify various style
+directives via switches; e.g., identifier case conventions, rules of
+indentation, and comment layout.
 ``gnatpp`` is a project-aware tool
 (see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
 the project-related switches).  The project file package that can specify
 ``gnatpp`` switches is named ``Pretty_Printer``.
-To produce a reformatted file, ``gnatpp`` invokes the Ada
+``gnatpp`` cannot process sources that contain preprocessing
-compiler and generates and uses the ASIS tree for the input source;
+directives.
-thus the input must be legal Ada code, and the tool should have all the
-information needed to compile the input source. To provide this information,
-you may specify as a tool parameter the project file the input source belongs to.
-Another possibility is to specify the source search
-path and needed configuration files in ``-cargs`` section of ``gnatpp``
-call, see the description of the ``gnatpp`` switches below.
-``gnatpp`` cannot process sources that contain preprocessing directives.
 The ``gnatpp`` command has the form
 ::
-$ gnatpp [ switches ] filename [ -cargs gcc_switches ]
+$ gnatpp [ switches ] filename
 where
 * ``switches`` is an optional sequence of switches defining such properties as
 the formatting rules, the source search path, and the destination for the
 output source file
-* ``filename`` is the name (including the extension) of the source file to
+* ``filename`` is the name of the source file to reformat; wildcards
-reformat; wildcards or several file names on the same gnatpp command are
+or several file names on the same gnatpp command are allowed. The
-allowed. The file name may contain path information; it does not have to
+file name may contain path information; it does not have to follow
-follow the GNAT file naming rules
+the GNAT file naming rules
-* ``gcc_switches`` is a list of switches for
-``gcc``. They will be passed on to all compiler invocations made by
-``gnatpp`` to generate the ASIS trees. Here you can provide
-``-I`` switches to form the source search path,
-use the ``-gnatec`` switch to set the configuration file, etc.
 .. _Switches_for_gnatpp:
 Switches for ``gnatpp``
 * ``:=`` in initializations in declarations,
 * ``:=`` in assignment statements,
 * ``=>`` in associations, and
 * ``at`` keywords in the component clauses in record representation clauses.
+In addition, ``in`` and ``out`` in parameter specifications are lined up.
-.. index:: -A0 (gnatpp)
-.. index:: -A1 (gnatpp)
+.. index:: --no-alignment (gnatpp)
+.. index:: --alignment (gnatpp)
+.. index:: --no-align-modes (gnatpp)
-:switch:`-A0`
+:switch:`--no-alignment`
 Set alignment to OFF
-:switch:`-A1`
+:switch:`--alignment`
 Set alignment to ON
+:switch:`--no-align-modes`
+Do not line up ``in`` and ``out`` in parameter specifications.
 .. _Casing_Control:
 Casing Control
 Three types of casing are supported: lower case, upper case, and mixed case.
 'Mixed case' means that the first letter, and also each letter immediately
 following an underscore, are converted to their uppercase forms;
 all the other letters are converted to their lowercase forms.
-.. index:: -a (gnatpp)
+(Note: the casing switches are not yet fully supported in the
+libadalang-based version of gnatpp.)
-:switch:`-aL`
+.. index:: --name-case-as-declared (gnatpp)
+:switch:`--name-case-as-declared`
+Name casing for defining occurrences are as they appear in the source file
+(this is the default)
+.. index:: --name-upper-case (gnatpp)
+:switch:`--name-upper-case`
+Names are in upper case
+.. index:: --name-lower-case (gnatpp)
+:switch:`--name-lower-case`
+Names are in lower case
+.. index:: --name-mixed-case (gnatpp)
+:switch:`--name-mixed-case`
+Names are in mixed case
+.. index:: --attribute-lower-case (gnatpp)
+:switch:`--attribute-lower-case`
 Attribute designators are lower case
+.. index:: --attribute-upper-case (gnatpp)
-:switch:`-aU`
+:switch:`--attribute-upper-case`
 Attribute designators are upper case
+.. index:: --attribute-mixed-case (gnatpp)
-:switch:`-aM`
+:switch:`--attribute-mixed-case`
 Attribute designators are mixed case (this is the default)
-.. index:: -k (gnatpp)
+.. index:: --keyword-lower-case (gnatpp)
+:switch:`--keyword-lower-case`
-:switch:`-kL`
 Keywords (technically, these are known in Ada as *reserved words*) are
 lower case (this is the default)
+.. index:: --keyword-upper-case (gnatpp)
-:switch:`-kU`
+:switch:`--keyword-upper-case`
 Keywords are upper case
-.. index:: -n (gnatpp)
+.. index:: --enum-case-as-declared (gnatpp)
+:switch:`--enum-case-as-declared`
-:switch:`-nD`
-Name casing for defining occurrences are as they appear in the source file
-(this is the default)
-:switch:`-nU`
-Names are in upper case
-:switch:`-nL`
-Names are in lower case
-:switch:`-nM`
-Names are in mixed case
-.. index:: -ne (gnatpp)
-:switch:`-neD`
 Enumeration literal casing for defining occurrences are as they appear in the
 source file. Overrides -n casing setting.
+.. index:: --enum-upper-case (gnatpp)
-:switch:`-neU`
+:switch:`--enum-upper-case`
 Enumeration literals are in upper case.  Overrides -n casing
 setting.
+.. index:: --enum-lower-case (gnatpp)
-:switch:`-neL`
+:switch:`--enum-lower-case`
 Enumeration literals are in lower case. Overrides -n casing
 setting.
+.. index:: --enum-mixed-case (gnatpp)
-:switch:`-neM`
+:switch:`--enum-mixed-case`
 Enumeration literals are in mixed case. Overrides -n casing
 setting.
-.. index:: -nt (gnatpp)
+.. index:: --type-case-as-declared (gnatpp)
+:switch:`--type-case-as-declared`
-:switch:`-ntD`
 Names introduced by type and subtype declarations are always
 cased as they appear in the declaration in the source file.
 Overrides -n casing setting.
+.. index:: --type-upper-case (gnatpp)
-:switch:`-ntU`
+:switch:`--type-upper-case`
 Names introduced by type and subtype declarations are always in
 upper case. Overrides -n casing setting.
+.. index:: --type-lower-case (gnatpp)
-:switch:`-ntL`
+:switch:`--type-lower-case`
 Names introduced by type and subtype declarations are always in
 lower case. Overrides -n casing setting.
+.. index:: --type-mixed-case (gnatpp)
-:switch:`-ntM`
+:switch:`--type-mixed-case`
 Names introduced by type and subtype declarations are always in
 mixed case. Overrides -n casing setting.
+.. index:: --number-upper-case (gnatpp)
-:switch:`-nnU`
+:switch:`--number-upper-case`
 Names introduced by number declarations are always in
 upper case. Overrides -n casing setting.
+.. index:: --number-lower-case (gnatpp)
-:switch:`-nnL`
+:switch:`--number-lower-case`
 Names introduced by number declarations are always in
 lower case. Overrides -n casing setting.
+.. index:: --number-mixed-case (gnatpp)
-:switch:`-nnM`
+:switch:`--number-mixed-case`
 Names introduced by number declarations are always in
 mixed case. Overrides -n casing setting.
-.. index:: -p (gnatpp)
+.. index:: --pragma-lower-case (gnatpp)
+:switch:`--pragma-lower-case`
-:switch:`-pL`
 Pragma names are lower case
+.. index:: --pragma-upper-case (gnatpp)
-:switch:`-pU`
+:switch:`--pragma-upper-case`
 Pragma names are upper case
+.. index:: --pragma-mixed-case (gnatpp)
-:switch:`-pM`
+:switch:`--pragma-mixed-case`
 Pragma names are mixed case (this is the default)
-.. index:: -D (gnatpp)
+.. index:: --syntax-only (gnatpp)
-:switch:`-D{file}`
+:switch:`--syntax-only`
+Disable the semantic analysis (name resolution) done by libadalang.
+This means gnatpp will not be able to support any of the
+"as-declared" switches.
+.. index:: --dictionary (gnatpp)
+:switch:`--dictionary={file}`
 Use ``file`` as a *dictionary file* that defines
 the casing for a set of specified names,
 thereby overriding the effect on these names by
 any explicit or implicit
 -n switch.
 To supply more than one dictionary file,
-use several ``-D`` switches.
+use several ``--dictionary`` switches.
 ``gnatpp`` implicitly uses a *default dictionary file*
 to define the casing for the Ada predefined names and
 the names declared in the GNAT libraries.
-.. index:: -D- (gnatpp)
+.. index:: --dictionary=- (gnatpp)
-:switch:`-D-`
+:switch:`--dictionary=-`
 Do not use the default dictionary file;
 instead, use the casing
 defined by a ``-n`` switch and any explicit
 dictionary file(s)
 The structure of a dictionary file, and details on the conventions
 used in the default dictionary file, are defined in :ref:`Name_Casing`.
-The :switch:`-D-` and
+The :switch:`--dictionary=-` and
-:switch:`-D{file}` switches are mutually
+:switch:`--dictionary={file}` switches are mutually
 compatible.
 This group of ``gnatpp`` switches controls the layout of comments and
 complex syntactic constructs.  See :ref:`Formatting_Comments` for details
 on their effect.
 .. index:: -c (gnatpp)
-:switch:`-c0`
+:switch:`--comments-unchanged`
 All comments remain unchanged.
-:switch:`-c1`
+:switch:`--comments-gnat-indentation`
 GNAT-style comment line indentation.
 This is the default.
-:switch:`-c3`
+:switch:`--comments-gnat-beginning`
 GNAT-style comment beginning.
-:switch:`-c4`
+:switch:`--comments-fill`
 Fill comment blocks.
-:switch:`-c5`
+:switch:`--comments-special`
 Keep unchanged special form comments.
 This is the default.
 .. index:: --comments-only (gnatpp)
 :switch:`--use-on-new-line`
 Start each USE clause in a context clause from a separate line.
 .. index:: --insert-blank-lines (gnatpp)
 :switch:`--insert-blank-lines`
 Insert blank lines where appropriate (between bodies and other large
 :switch:`--preserve-blank-lines`
 Preserve blank lines in the input. By default, gnatpp will squeeze
 multiple blank lines down to one.
+.. index:: --preserve-line-breaks (gnatpp)
-The ``-c`` switches are compatible with one another, except that
-the ``-c0`` switch disables all other comment formatting
+:switch:`--preserve-line-breaks`
-switches.
+Preserve line breaks in the input, to the extent possible.
+The ``--comments`` switches are compatible with one another, except
+that the ``--comments-unchanged`` switch disables all other comment
+formatting switches.
 .. _General_Text_Layout_Control:
 General Text Layout Control
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 These switches allow control over line length and indentation.
-.. index:: -M (gnatpp)
+.. index:: --max-line-length (gnatpp)
-:switch:`-M{nnn}`
+:switch:`--max-line-length={nnn}`
 Maximum line length, ``nnn`` from 32...256, the default value is 79
-.. index:: -i (gnatpp)
+.. index:: --indentation (gnatpp)
-:switch:`-i{nnn}`
+:switch:`--indentation={nnn}`
 Indentation level, ``nnn`` from 1...9, the default value is 3
-.. index:: -cl (gnatpp)
+.. index:: --indent-continuation (gnatpp)
-:switch:`-cl{nnn}`
+:switch:`--indent-continuation={nnn}`
 Indentation level for continuation lines (relative to the line being
 continued), ``nnn`` from 1...9.
 The default
 value is one less than the (normal) indentation level, unless the
 indentation is set to 1 (in which case the default value for continuation
 Same as ``--decimal-grouping``, but for based literals. For
 example, with ``--based-grouping=4``, ``16#0001FFFE#`` will be
 changed to ``16#0001_FFFE#``.
+.. index:: --split-line-before-record (gnatpp)
+:switch:`--split-line-before-record`
+Split the line just before ``record`` in a record type declaration.
+.. index:: --indent-named-statements (gnatpp)
+:switch:`--indent-named-statements`
+Named block and loop statements are indented with respect to
+the name.
 .. index:: --split-line-before-op (gnatpp)
 :switch:`--split-line-before-op`
 If it is necessary to split a line at a binary operator, by default
 the line is split after the operator. With this option, it is split
 :switch:`--RM-style-spacing`
 Do not insert an extra blank before various occurrences of
 '(' and ':'. This also turns off alignment.
-.. index:: -ff (gnatpp)
+.. index:: --ff-after-pragma-page (gnatpp)
-:switch:`-ff`
+:switch:`--ff-after-pragma-page`
 Insert a Form Feed character after a pragma Page.
 .. index:: --call_threshold (gnatpp)
 If the number of parameter specifications is greater than ``nnn``
 (or equal to ``nnn`` in case of a function), start each specification from
 a new line. If ``nnn`` is 0, and :switch:`--no-separate-is` was not specified, then
 the ``is`` is placed on a separate line. This feature is disabled by default.
+.. index:: --vertical-enum-types (gnatpp)
+:switch:`--vertical-enum-types`
+Format enumeration type declarations "vertically", e.g. each
+enumeration literal goes on a separate line.
+.. index:: --vertical-array-types (gnatpp)
+:switch:`--vertical-array-types`
+Format array type declarations "vertically", e.g. for
+multidimensional arrays, each index_subtype_definition or
+discrete_subtype_definition goes on a separate line.
+.. index:: --vertical-named-aggregates (gnatpp)
+:switch:`--vertical-named-aggregates`
+Format aggregates "vertically" if named notation is used for all
+component_associations, e.g. each component_association
+goes on a separate line.
+.. index:: --vertical-case-alternatives (gnatpp)
+:switch:`--vertical-case-alternatives`
+Format case statements, case expressions, and variant parts with
+additional line breaks.
 .. _Setting_the_Source_Search_Path:
 Setting the Source Search Path
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 .. _Output_File_Control-gnatpp:
 Output File Control
 ^^^^^^^^^^^^^^^^^^^
-By default the output is sent to a file whose name is obtained by appending
+By default the output overwrites the input file.
-the :file:`.pp` suffix to the name of the input file.
-If the file with this name already exists, it is overwritten.
-Thus if the input file is :file:`my_ada_proc.adb` then
-``gnatpp`` will produce :file:`my_ada_proc.adb.pp`
-as output file.
 The output may be redirected by the following switches:
+.. index:: --replace (gnatpp)
+:switch:`--replace`
+This is the default.
+Replace the input source file with the reformatted output without
+creating any backup copy of the input source.
 .. index:: --output-dir (gnatpp)
 :switch:`--output-dir={dir}`
-Generate output file in directory :file:`dir` with the same name as the input
+Generate output file in directory :file:`dir` with the same name as
-file. If :file:`dir` is the same as the directory containing the input file,
+the input file. If :file:`dir` is the same as the directory
-the input file is not processed; use ``-rnb``
+containing the input file, the input file is not processed; use
-if you want to update the input file in place.
+``--replace`` if you want to update the input file in
+place.
-.. index:: -pipe (gnatpp)
+.. index:: --pipe (gnatpp)
-:switch:`-pipe`
+:switch:`--pipe`
 Send the output to ``Standard_Output``
-.. index:: -o (gnatpp)
+.. index:: --output (gnatpp)
-:switch:`-o {output_file}`
+:switch:`--output={output_file}`
 Write the output into ``output_file``.
 If ``output_file`` already exists, ``gnatpp`` terminates without
 reading or processing the input file.
-.. index:: -of (gnatpp)
+.. index:: --output-force (gnatpp)
-:switch:`-of {output_file}`
+:switch:`--output-force={output_file}`
 Write the output into ``output_file``, overwriting the existing file
 (if one is present).
-.. index:: -r (gnatpp)
+.. index:: --replace-backup (gnatpp)
-:switch:`-r`
+:switch:`--replace-backup`
 Replace the input source file with the reformatted output, and copy the
 original input source into the file whose name is obtained by appending the
 :file:`.npp` suffix to the name of the input file.
 If a file with this name already exists, ``gnatpp`` terminates without
 reading or processing the input file.
-.. index:: -rf (gnatpp)
+.. index:: --replace-force-backup (gnatpp)
-:switch:`-rf`
+:switch:`--replace-force-backup`
-Like ``-r`` except that if the file with the specified name
+Like ``--replace-backup`` except that if the file with the specified name
 already exists, it is overwritten.
-.. index:: -rnb (gnatpp)
-:switch:`-rnb`
-Replace the input source file with the reformatted output without
-creating any backup copy of the input source.
 .. index:: --eol (gnatpp)
 :switch:`--eol={xxx}`
-Specifies the line-ending style of the reformatted output file. The ``xxx``
+Specifies the line-ending style of the reformatted output file. The
-string specified with the switch may be:
+``xxx`` string specified with the switch may be:
 * *dos* - MS DOS style, lines end with CR LF characters*
 * *crlf*  - the same as *dos*
 * *unix* - UNIX style, lines end with LF character*
 * *lf* -  the same as *unix*
-.. index:: -W (gnatpp)
+.. index:: --wide-character-encoding (gnatpp)
-:switch:`-W{e}`
+:switch:`--wide-character-encoding={e}`
-Specify the wide character encoding method for the input and output files.
+Specify the wide character encoding method for the input and output
-``e`` is one of the following:
+files. ``e`` is one of the following:
-* *h* - Hex encoding
-* *u* - Upper half encoding
-* *s* - Shift/JIS encoding
-* *e* - EUC encoding
 * *8* - UTF-8 encoding
 * *b* - Brackets encoding (default value)
-Options ``-o`` and ``-of`` are allowed only if the call to gnatpp
+Options ``--output-file`` and ``--output-force`` are allowed only if
-contains only one file to reformat.
+the call to gnatpp contains only one file to reformat.
-Option ``--eol`` and ``-W`` cannot be used together
+Option ``--eol`` and ``--wide-character-encoding`` cannot be used together
-with the ``-pipe`` option.
+with the ``--pipe`` option.
 .. _Other_gnatpp_Switches:
 Other ``gnatpp`` Switches
 .. index:: -U  (gnatpp)
 :switch:`-U`
 If a project file is specified and no argument source is explicitly
-specified (either directly or by means of ``-files`` option), process
+specified (either directly or by means of ``--files`` option), process
 all the units of the closure of the argument project. Otherwise this option
 has no effect.
 :switch:`-U {main_unit}`
 If a project file is specified and no argument source is explicitly
-specified (either directly or by means of ``-files`` option), process
+specified (either directly or by means of ``--files`` option), process
 the closure of units rooted at ``main_unit``. Otherwise this option
 has no effect.
 .. index:: -X  (gnatpp)
 processed if they have been modified, or if files they depend on have
 been modified. This is similar to the way gnatmake/gprbuild only
 compiles files that need to be recompiled. A project file is required
 in this mode, and the gnat driver (as in *gnat pretty*) is not
 supported.
+(Note: this switch is not yet supported in the libadalang-based
+version of gnatpp.)
 .. index:: --pp-off  (gnatpp)
 :switch:`--pp-off={xxx}`
 :switch:`--pp-on={xxx}`
 Use :switch:`--xxx` as the command to turn pretty printing back on, instead
 of the default ``--!pp on``.
-.. index:: -files (gnatpp)
+.. index:: --files (gnatpp)
-:switch:`-files {filename}`
+:switch:`--files={filename}`
 Take as arguments the files listed in text file ``file``.
 Text file ``file`` may contain empty lines that are ignored.
 Each nonempty line should contain the name of an existing file.
 Several such switches may be specified simultaneously.
-.. index:: -j (gnatpp)
+.. index:: --ignore (gnatpp)
-:switch:`-j{n}`
+:switch:`--ignore={filename}`
-Without ``--incremental``, use *n* processes to carry out the
+Do not process the sources listed in a specified file. This option cannot
-tree creations (internal representations of the argument sources). On
+be used in incremental mode.
-a multiprocessor machine this speeds up processing of big sets of
-argument sources. If *n* is 0, then the maximum number of parallel
+.. index:: --jobs (gnatpp)
-tree creations is the number of core processors on the platform. This
-option cannot be used together with the :switch:`-r`,
+:switch:`--jobs={n}`
-:switch:`-rf` or
+With ``--incremental``, use *n* ``gnatpp`` processes to perform
-:switch:`-rnb` options.
+pretty printing in parallel. If *n* is 0, then the maximum number
+processes is the number of core processors on the platform.
-With ``--incremental``, use *n* ``gnatpp`` processes to
-perform pretty-printing in parallel. *n* = 0 means the same as
-above. In this case, the :switch:`-r`,
+.. index:: --verbose (gnatpp)
-:switch:`-rf` and
-:switch:`-rnb` options are allowed.
+:switch:`--verbose`
-.. index:: -t (gnatpp)
-:switch:`-t`
-Print out execution time.
-.. index:: -v (gnatpp)
-:switch:`-v`
 Verbose mode
-.. index:: -q (gnatpp)
+.. index:: --quiet (gnatpp)
-:switch:`-q`
+:switch:`--quiet`
 Quiet mode
 If a project file is specified and no argument source is explicitly
-specified (either directly or by means of ``-files`` option), and no
+specified (either directly or by means of ``--files`` option), and no
 ``-U`` is specified, then the set of processed sources is
 all the immediate units of the argument project.
+.. index:: --gnat83 (gnatpp)
+:switch:`--gnat83`
+Ada 83 mode
+.. index:: --gnat95 (gnatpp)
+:switch:`--gnat95`
+Ada 95 mode
+.. index:: --gnat2005 (gnatpp)
+:switch:`--gnat2005`
+Ada 2005 mode
+.. index:: --gnat2012 (gnatpp)
+:switch:`--gnat2012`
+Ada 2012 mode
 .. _Formatting_Rules:
 Formatting Rules
 * an *end-of-line comment*, which follows some other Ada code on
 the same line.
 A whole-line comment is indented according to the surrounding code,
-with some exceptions.
+with some exceptions.  Comments that start in column 1 are kept
-Comments that start in column 1 are kept there.
+there.  If possible, comments are not moved so far to the right that
-If possible, comments are not moved so far to the right that the maximum
+the maximum line length is exceeded.  The ``--comments-unchanged``
-line length is exceeded.
+option turns off comment formatting.  Special-form comments such as
-The ``-c0`` option
+SPARK-style ``--#...`` are left alone.
-turns off comment formatting.
-Special-form comments such as SPARK-style ``--#...`` are left alone.
 For an end-of-line comment, ``gnatpp`` tries to leave the same
 number of spaces between the end of the preceding Ada code and the
 beginning of the comment as appear in the original source.
-The ``-c3`` switch
+The ``--comments-gnat-beginning`` switch (GNAT style comment
-(GNAT style comment beginning) has the following
+beginning) has the following effect:
-effect:
 * For each whole-line comment that does not end with two hyphens,
-``gnatpp`` inserts spaces if necessary after the starting two hyphens
+``gnatpp`` inserts spaces if necessary after the starting two
-to ensure that there are at least two spaces between these hyphens and the
+hyphens to ensure that there are at least two spaces between
-first non-blank character of the comment.
+these hyphens and the first non-blank character of the comment.
-The ``-c4`` switch specifies that
+The ``--comments-fill`` switch specifies that whole-line comments
-whole-line comments that form a paragraph will be filled in typical
+that form a paragraph will be filled in typical word processor style
-word processor style (that is, moving words between lines to make the
+(that is, moving words between lines to make the lines other than the
-lines other than the last similar in length ).
+last similar in length ).
-The ``--comments-only`` switch specifies that only the comments
+The ``--comments-only`` switch specifies that only the comments are
-are formatted; the rest of the program text is left alone. The
+formatted; the rest of the program text is left alone. The comments
-comments are formatted according to the -c3 and -c4 switches; other
+are formatted according to the ``--comments-gnat-beginning`` and
-formatting switches are ignored. For example,
+``--comments-fill`` switches; other formatting switches are ignored. For
-``--comments-only -c4`` means to fill comment paragraphs, and do nothing else.
+example, ``--comments-only --comments-fill`` means to fill comment
-Likewise,
+paragraphs, and do nothing else.  Likewise, ``--comments-only
-``--comments-only -c3`` ensures comments start with at least two
+--comments-gnat-beginning`` ensures comments start with at least two
-spaces after ``--``, and ``--comments-only -c3 -c4`` does
+spaces after ``--``, and ``--comments-only --comments-gnat-beginning
-both. If ``--comments-only`` is given without ``-c3`` or
+--comments-fill`` does both. If ``--comments-only`` is given without
-``-c4``, then gnatpp doesn't format anything.
+``--comments-gnat-beginning`` or ``--comments-fill``, then gnatpp
+doesn't format anything.
 .. _Name_Casing:
 Name Casing
 ^^^^^^^^^^^
 ``gnatpp`` always converts the usage occurrence of a (simple) name to
 the same casing as the corresponding defining identifier.
-You control the casing for defining occurrences via the
+You control the casing for defining occurrences via the ``--name...``
-``-n`` switch.
+switches.  With ``--name-case-as-declared``, which is the default,
-With ``-nD`` ('as declared', which is the default),
+defining occurrences appear exactly as in the source file where they
-defining occurrences appear exactly as in the source file
+are declared.  The other values for this switch --
-where they are declared.
+``--name-upper-case``, ``--name-lower-case``, ``--name-mixed-case``
-The other values for this switch --
+-- result in upper, lower, or mixed case, respectively.  If
-``-nU``,
+``gnatpp`` changes the casing of a defining occurrence, it
-``-nL``,
+analogously changes the casing of all the usage occurrences of this
-``-nM`` --
+name.
-result in
-upper, lower, or mixed case, respectively.
+If the defining occurrence of a name is not in the source compilation
-If ``gnatpp`` changes the casing of a defining
+unit currently being processed by ``gnatpp``, the casing of each
-occurrence, it analogously changes the casing of all the
+reference to this name is changed according to the switch (subject to
-usage occurrences of this name.
+the dictionary file mechanism described below).  Thus ``gnatpp`` acts
+as though the switch had affected the casing for the defining
-If the defining occurrence of a name is not in the source compilation unit
+occurrence of the name.
-currently being processed by ``gnatpp``, the casing of each reference to
-this name is changed according to the value of the ``-n``
-switch (subject to the dictionary file mechanism described below).
-Thus ``gnatpp`` acts as though the ``-n`` switch
-had affected the
-casing for the defining occurrence of the name.
 The options
-:switch:`-a{x}`,
+:switch:`--attribute...`,
-:switch:`-k{x}`,
+:switch:`--keyword...`,
-:switch:`-ne{x}`,
+:switch:`--enum...`,
-:switch:`-nt{x}`,
+:switch:`--type...`,
-:switch:`-nn{x}`, and
+:switch:`--number...`, and
-:switch:`-p{x}`
+:switch:`--pragma...`
 allow finer-grained control over casing for
 attributes, keywords, enumeration literals,
 types, named numbers and pragmas, respectively.
-:switch:`-nt{x}` covers subtypes and
+:switch:`--type...` cover subtypes as well.
-task and protected bodies as well.
 Some names may need to be spelled with casing conventions that are not
 covered by the upper-, lower-, and mixed-case transformations.
 You can arrange correct casing by placing such names in a
 *dictionary file*,
-and then supplying a ``-D`` switch.
+and then supplying a ``--dictionary`` switch.
 The casing of names from dictionary files overrides
-any ``-n`` switch.
+any ``--name...`` switch.
 To handle the casing of Ada predefined names and the names from GNAT libraries,
 ``gnatpp`` assumes a default dictionary file.
 The name of each predefined entity is spelled with the same casing as is used
 for the entity in the :title:`Ada Reference Manual` (usually mixed case).
 The name of each entity in the GNAT libraries is spelled with the same casing
 as is used in the declaration of that entity.
-The ``-D-`` switch suppresses the use of
+The ``--dictionary=-`` switch suppresses the use of
 the default dictionary file. Instead, the casing for predefined and
 GNAT-defined names will be established by the
 ``-n`` switch or explicit dictionary files. For
 example, by default the names ``Ada.Text_IO`` and
 ``GNAT.OS_Lib`` will appear as just shown, even in the presence of
-a ``-nU`` switch.  To ensure that even
+a ``--name-upper-case`` switch.  To ensure that even
 such names are rendered in uppercase, additionally supply the
--D- switch (or else place these names
+--dictionary=- switch (or else place these names
 in upper case in a dictionary file).
 A dictionary file is a plain text file; each line in this file can be
 either a blank line (containing only space characters), an Ada comment
 line, or the specification of exactly one *casing schema*.
 The casing schema string can be followed by white space and/or an Ada-style
 comment; any amount of white space is allowed before the string.
 If a dictionary file is passed as
-the value of a :switch:`-D{file}` switch
+the value of a :switch:`--dictionary={file}` switch
 then for every
 simple name and every identifier, ``gnatpp`` checks if the dictionary
 defines the casing for the name or for some of its parts (the term 'subword'
 is used below to denote the part of a name which is delimited by '_' or by
 the beginning or end of the word and which does not contain any '_' inside):
 If ``gnatpp`` is called with the following switches:
 ::
-$ gnatpp -nM -D dict1 -D dict2 test.adb
+$ gnatpp --name-mixed-case --dictionary=dict1 --dictionary=dict2 test.adb
 then we will get the following name casing in the ``gnatpp`` output:
 .. code-block:: ada
 Name1_Var         : Float;
 begin
 Name2_NAME3_Name4 := Name4_NAME3_Name2 > NAME1;
 end Test;
+Legacy Switches
+^^^^^^^^^^^^^^^
+Some switches have a short form, mostly for legacy reasons,
+as shown below.
+.. index:: -n (gnatpp)
+:switch:`-nD`
+:switch:`--name-case-as-declared`
+:switch:`-nU`
+:switch:`--name-upper-case`
+:switch:`-nL`
+:switch:`--name-lower-case`
+:switch:`-nM`
+:switch:`--name-mixed-case`
+.. index:: -a (gnatpp)
+:switch:`-aL`
+:switch:`--attribute-lower-case`
+:switch:`-aU`
+:switch:`--attribute-upper-case`
+:switch:`-aM`
+:switch:`--attribute-mixed-case`
+.. index:: -k (gnatpp)
+:switch:`-kL`
+:switch:`--keyword-lower-case`
+:switch:`-kU`
+:switch:`--keyword-upper-case`
+.. index:: -ne (gnatpp)
+:switch:`-neD`
+:switch:`--enum-case-as-declared`
+:switch:`-neU`
+:switch:`--enum-upper-case`
+:switch:`-neL`
+:switch:`--enum-lower-case`
+:switch:`-neM`
+:switch:`--enum-mixed-case`
+.. index:: -nt (gnatpp)
+:switch:`-ntD`
+:switch:`--type-case-as-declared`
+:switch:`-ntU`
+:switch:`--type-upper-case`
+:switch:`-ntL`
+:switch:`--type-lower-case`
+:switch:`-ntM`
+:switch:`--type-mixed-case`
+:switch:`-nnU`
+:switch:`--number-upper-case`
+:switch:`-nnL`
+:switch:`--number-lower-case`
+:switch:`-nnM`
+:switch:`--number-mixed-case`
+.. index:: -p (gnatpp)
+:switch:`-pL`
+:switch:`--pragma-lower-case`
+:switch:`-pU`
+:switch:`--pragma-upper-case`
+:switch:`-pM`
+:switch:`--pragma-mixed-case`
+.. index:: -D (gnatpp)
+:switch:`-D{file}`
+:switch:`--dictionary={file}`
+.. index:: -D- (gnatpp)
+:switch:`-D-`
+:switch:`--dictionary=-`
+.. index:: -c (gnatpp)
+:switch:`-c0`
+:switch:`--comments-unchanged`
+:switch:`-c1`
+:switch:`--comments-gnat-indentation`
+:switch:`-c3`
+:switch:`--comments-gnat-beginning`
+:switch:`-c4`
+:switch:`--comments-fill`
+:switch:`-c5`
+:switch:`--comments-special`
+.. index:: -M (gnatpp)
+:switch:`-M{nnn}`
+:switch:`--max-line-length={nnn}`
+.. index:: -i (gnatpp)
+:switch:`-i{nnn}`
+:switch:`--indentation={nnn}`
+.. index:: -cl (gnatpp)
+:switch:`-cl{nnn}`
+:switch:`--indent-continuation={nnn}`
+.. index:: -ff (gnatpp)
+:switch:`-ff`
+:switch:`--ff-after-pragma-page`
+.. index:: -pipe (gnatpp)
+:switch:`-pipe`
+:switch:`--pipe`
+.. index:: -o (gnatpp)
+:switch:`-o {output-file}`
+:switch:`--output={output-file}`
+.. index:: -of (gnatpp)
+:switch:`-of {output-file}`
+:switch:`--output-force={output-file}`
+.. index:: -r (gnatpp)
+:switch:`-rnb`
+:switch:`--replace`
+:switch:`-r`
+:switch:`--replace-backup`
+.. index:: -rf (gnatpp)
+:switch:`-rf`
+:switch:`--replace-force-backup`
+.. index:: -rnb (gnatpp)
+.. index:: --eol (gnatpp)
+.. index:: -W (gnatpp)
+:switch:`-W{e}`
+:switch:`--wide-character-encoding={e}`
+.. index:: -files (gnatpp)
+:switch:`-files {filename}`
+:switch:`--files={filename}`
+.. index:: -j (gnatpp)
+:switch:`-j{n}`
+:switch:`--jobs={n}`
+.. index:: -v (gnatpp)
+:switch:`-v`
+:switch:`--verbose`
+.. index:: -q (gnatpp)
+:switch:`-q`
+:switch:`--quiet`
 .. only:: PRO or GPL
 .. _The_Body_Stub_Generator_gnatstub:
 * *filename*
 is the name of the source file that contains a library unit declaration
 for which a body must be created or a library unit body for which subunits
 must be created for the body stubs declared in this body.
 The file name may contain the path information.
-If the name does not follow GNAT file naming conventions and a set
+If the name does not follow GNAT file naming conventions and the set
-of seitches does not contain a project file that defines naming
+of switches does not contain a project file that defines naming
 conventions, the name of the body file must
 be provided
 explicitly as the value of the :switch:`-o{body-name}` option.
 If the file name follows the GNAT file naming
 conventions and the name of the body file is not provided,
 .. index:: -P (gnatstub)
 :switch:`-P {file}`
 Indicates the name of the project file that describes the set of sources
-to be processed.
+to be processed. An aggregate project is allowed as the file parameter only
+if it has exactly one non-aggregate project being aggregated.
 .. index:: -X (gnatstub)
 :switch:`-X{name}={value}`
 .. index:: --subunits (gnatstub)
 :switch:`--subunits`
 Generate subunits for body stubs. If this switch is specified,
-``gnatstub`` expects a library unit body as an agrument file,
+``gnatstub`` expects a library unit body as an argument file,
 otherwise a library unit declaration is expected. If a body stub
 already has a corresponding subunit, ``gnatstub`` does not
 generate anything for it.
 .. index:: --no-exception (gnatstub)
 :switch:`--no-exception`
-Avoid raising PROGRAM_ERROR in the generated bodies of program unit stubs.
+Avoid raising Program_Error in the generated bodies of program unit stubs,
-This is not always possible for function stubs.
+except in the case of functions, where we have no value to return.
 .. index:: --no-local-header (gnatstub)
 :switch:`--no-local-header`
 Take as arguments the files listed in text file ``file``.
 Text file ``file`` may contain empty lines that are ignored.
 Each nonempty line should contain the name of an existing file.
 Several such switches may be specified simultaneously.
+.. index:: --ignore (gnattest)
+:switch:`--ignore={filename}`
+Do not process the sources listed in a specified file.
 .. index:: --RTS (gnattest)
 :switch:`--RTS={rts-path}`
 Specifies the default location of the runtime library. Same meaning as the
 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`). For restricted
 :switch:`--queues={n}`, :switch:`-j{n}`
 Runs ``n`` tests in parallel (default is 1).
+.. index:: --copy-environment (gnattest)
+:switch:`--copy-environment={dir}`
+Contents of ``dir`` directory will be copied to temporary directories
+created by gnattest in which individual test drivers are spawned.
 .. _Project_Attributes_for_gnattest:
 Project Attributes for ``gnattest``
 -----------------------------------
 This attribute cannot be used together with ``Tests_Root`` or ``Tests_Dir``.
 * ``Tests_Dir``
 is used to select the same output mode as with the ``--tests-dir`` option.
 This attribute cannot be used together with ``Subdir`` or ``Tests_Root``.
+* ``Stubs_Dir``
+is used to select the same output mode as with the ``--stubs-dir`` option.
 * ``Harness_Dir``
 is used to specify the directory in which to place harness packages and project
 file for the test driver, otherwise specified by ``--harness-dir``.
 adjustments might be necessary to make the test harness compilable;
 * use of some constructs, such as elaboration-control pragmas, Type_Invariant
 aspects, and complex variable initializations that use Subprogram'Access,
 may result in elaboration circularities in the generated harness.
+.. only:: PRO or GPL
+.. _The_Backtrace_Symbolizer_gnatsymbolize:
+Translating Code Addresses into Source Locations with ``gnatsymbolize``
+=======================================================================
+.. index:: ! gnatsymbolize
+``gnatsymbolize`` is a program which translates addresses into
+their corresponding filename, line number, and function names.
+Running ``gnatsymbolize``
+-------------------------
+::
+$ gnatsymbolize [ switches ] filename [ addresses ]
+For instance, consider the following Ada program:
+.. code-block:: ada
+package Pck is
+Global_Val : Integer := 0;
+procedure Call_Me_First;
+end Pck;
+with GNAT.IO; use GNAT.IO;
+with GNAT.Traceback; use GNAT.Traceback;
+with GNAT.Debug_Utilities;
+package body Pck is
+procedure Call_Me_Third is
+TB : Tracebacks_Array (1 .. 5);
+TB_len : Natural;
+begin
+Global_Val := Global_Val + 1;
+Call_Chain (TB, TB_Len);
+for K in 1 .. TB_Len loop
+Put_Line (GNAT.Debug_Utilities.Image_C (TB (K)));
+end loop;
+end Call_Me_Third;
+procedure Call_Me_Second is
+begin
+Call_Me_Third;
+end Call_Me_Second;
+procedure Call_Me_First is
+begin
+Call_Me_Second;
+end Call_Me_First;
+end Pck;
+with Pck; use Pck;
+procedure Foo is
+begin
+Global_Val := 123;
+Call_Me_First;
+end Foo;
+This program, when built and run, prints a list of addresses which
+correspond to the traceback when inside function ``Call_Me_Third``.
+For instance, on x86_64 GNU/Linux:
+::
+$ gnatmake -g -q foo.adb
+$ ./foo
+0x0000000000402561
+0x00000000004025EF
+0x00000000004025FB
+0x0000000000402611
+0x00000000004024C7
+``gnatsymbolize`` can be used to translate those addresses into
+code locations as follow:
+::
+$ gnatsymbolize foo 0x0000000000402561 0x00000000004025EF \
+0x00000000004025FB 0x0000000000402611 0x00000000004024C7
+Pck.Call_Me_Third at pck.adb:12
+Pck.Call_Me_Second at pck.adb:20
+Pck.Call_Me_First at pck.adb:25
+Foo at foo.adb:6
+Main at b~foo.adb:184
+Switches for ``gnatsymbolize``
+------------------------------
+``gnatsymbolize`` recognizes the following switches:
+.. index:: --help (gnatsymbolize)
+:switch:`--help`
+Display the program's usage, and then exit, disregarding all other
+options.
+:switch:`--cache`
+Read the symbolic information from the executable and cache them
+in memory in order to accelerate the translation of each address
+into a symbolic location.
+Depending on the size of the executable and the number of addresses
+to translate, this may not always make ``gnatsymbolize`` faster
+overall.
+:switch:`--dump`
+If :switch:`--cache` is used, dump the contents of the cache on
+Standard Output. Has no effect otherwise.
+:switch:`--count={N}`
+If specified, compute the symbolic traceback ``N`` times in a row.
+This option is mostly useful for measuring the performance of
+``gnatsymbolize``, particularly in the case where the cache is
+being used.
+Requirements for Correct Operation
+----------------------------------
+The translation is performed by reading the DWARF debugging
+information produced by the compiler for each unit. All units
+for which the translation is to be done must therefore be compiled
+such that DWARF debugging information is produced. In most cases,
+this is done by simply compiling with ``-g``.
+This program provides a functionality similar to ``addr2line``.
+It has fewer options to tailor its output, but has been designed
+to require fewer of the DWARF sections to be present in the
+executable. In particular, the following sections can be
+stripped from the executable without impact to ``gnatsymbolize``'s
+functionality:
+* ``.debug_str``
+* ``.debug_ranges``
 .. only:: PRO or GPL
 .. _Using_Project_Files_with_GNAT_Tools:
 Using Project Files with GNAT Tools

Mercurial > hg > CbC > CbC_gcc

comparison gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst @ 131:84e7813d76e9