Skip to content

R
riscv-gcc-1
Commit e3f2ff72 by Bob Duff Committed by Pierre-Marie de Rodat
Options

[Ada] Update gnatstub documentation for the Libadalang-based version 

2018-12-11  Bob Duff  <duff@adacore.com>

gcc/ada/

	* doc/gnat_ugn/gnat_utility_programs.rst: Update gnatstub
	documentation for the Libadalang-based version.
	* gnat_ugn.texi: Regenerate.

From-SVN: r266981
parent 5f531fef
Showing with 156 additions and 151 deletions
gcc/ada/ChangeLog
2018-12-11 Bob Duff <duff@adacore.com>
* doc/gnat_ugn/gnat_utility_programs.rst: Update gnatstub
documentation for the Libadalang-based version.
* gnat_ugn.texi: Regenerate.
2018-12-11 Ed Schonberg <schonberg@adacore.com> 2018-12-11 Ed Schonberg <schonberg@adacore.com>
* sem_ch13.adb (Push_Type, Pop_Type): New procedures, used for * sem_ch13.adb (Push_Type, Pop_Type): New procedures, used for
......
gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
...@@ -87,7 +87,7 @@ Switches for ``gnatclean`` ...@@ -87,7 +87,7 @@ Switches for ``gnatclean``
.. index:: --version (gnatclean) .. index:: --version (gnatclean)
:switch:`--version` :switch:`--version`
Display Copyright and version, then exit disregarding all other options. Display copyright and version, then exit disregarding all other options.
.. index:: --help (gnatclean) .. index:: --help (gnatclean)
...@@ -289,7 +289,7 @@ Switches for ``gnatls`` ...@@ -289,7 +289,7 @@ Switches for ``gnatls``
.. index:: --version (gnatls) .. index:: --version (gnatls)
:switch:`--version` :switch:`--version`
Display Copyright and version, then exit disregarding all other options. Display copyright and version, then exit disregarding all other options.
.. index:: --help (gnatls) .. index:: --help (gnatls)
...@@ -535,7 +535,7 @@ The following switches are available for ``gnatxref``: ...@@ -535,7 +535,7 @@ The following switches are available for ``gnatxref``:
.. index:: --version (gnatxref) .. index:: --version (gnatxref)
:switch:`--version` :switch:`--version`
Display Copyright and version, then exit disregarding all other options. Display copyright and version, then exit disregarding all other options.
.. index:: --help (gnatxref) .. index:: --help (gnatxref)
...@@ -724,7 +724,7 @@ The following switches are available: ...@@ -724,7 +724,7 @@ The following switches are available:
.. index:: --version (gnatfind) .. index:: --version (gnatfind)
:switch:`--version` :switch:`--version`
Display Copyright and version, then exit disregarding all other options. Display copyright and version, then exit disregarding all other options.
.. index:: --help (gnatfind) .. index:: --help (gnatfind)
...@@ -1357,7 +1357,7 @@ Alternatively, you may run the script using the following command line: ...@@ -1357,7 +1357,7 @@ Alternatively, you may run the script using the following command line:
:switch:`-X{name}={value}` :switch:`-X{name}={value}`
Indicates that external variable ``name`` in Indicates that external variable ``name`` in
the argument project has the value ``value``. Has no effect if no the argument project has the value ``value``. Has no effect if no
project is specified as tool argument. project is specified.
:switch:`--RTS={rts-path}` :switch:`--RTS={rts-path}`
Specifies the default location of the runtime Specifies the default location of the runtime
...@@ -2696,7 +2696,7 @@ Alternatively, you may run the script using the following command line: ...@@ -2696,7 +2696,7 @@ Alternatively, you may run the script using the following command line:
.. index:: --version (gnatmetric) .. index:: --version (gnatmetric)
:switch:`--version` :switch:`--version`
Display Copyright and version, then exit disregarding all other options. Display copyright and version, then exit disregarding all other options.
.. index:: --help (gnatmetric) .. index:: --help (gnatmetric)
...@@ -2734,8 +2734,7 @@ Alternatively, you may run the script using the following command line: ...@@ -2734,8 +2734,7 @@ Alternatively, you may run the script using the following command line:
:switch:`-X{name}={value}` :switch:`-X{name}={value}`
Indicates that external variable ``name`` in the argument project Indicates that external variable ``name`` in the argument project
has the value ``value``. Has no effect if no project is specified as has the value ``value``. Has no effect if no project is specified.
tool argument.
.. index:: --RTS (gnatmetric) .. index:: --RTS (gnatmetric)
...@@ -3494,8 +3493,7 @@ Alternatively, you may run the script using the following command line: ...@@ -3494,8 +3493,7 @@ Alternatively, you may run the script using the following command line:
:switch:`-X{name}={value}` :switch:`-X{name}={value}`
Indicates that external variable ``name`` in the argument project Indicates that external variable ``name`` in the argument project
has the value ``value``. Has no effect if no project is specified as has the value ``value``. Has no effect if no project is specified.
tool argument.
.. index:: --RTS (gnatpp) .. index:: --RTS (gnatpp)
...@@ -4079,7 +4077,7 @@ Alternatively, you may run the script using the following command line: ...@@ -4079,7 +4077,7 @@ Alternatively, you may run the script using the following command line:
``gnatstub`` creates empty but compilable bodies ``gnatstub`` creates empty but compilable bodies
for library unit declarations, and empty but compilable for library unit declarations, and empty but compilable
subunit for body stubs. subunits for body stubs.
``gnatstub`` is a project-aware tool. ``gnatstub`` is a project-aware tool.
(See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of (See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
...@@ -4090,24 +4088,10 @@ Alternatively, you may run the script using the following command line: ...@@ -4090,24 +4088,10 @@ Alternatively, you may run the script using the following command line:
``gnatstub`` switches is named ``gnatstub``. ``gnatstub`` switches is named ``gnatstub``.
To create a body or a subunit, ``gnatstub`` invokes the Ada
compiler and generates and uses the ASIS tree for the input source;
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 ``gnatstub``
call, see the description of the ``gnatstub`` switches below.
If the ``gnatstub`` argument source contains preprocessing directives
then the needed options should be provided to run preprocessor as a part of
the ``gnatstub`` call, and the generated body stub will correspond to
the preprocessed source.
By default, all the program unit bodies generated by ``gnatstub`` By default, all the program unit bodies generated by ``gnatstub``
raise the predefined ``Program_Error`` exception, which will catch raise ``Program_Error``, which will catch accidental calls of
accidental calls of generated stubs. This behavior can be changed with generated stubs. This behavior can be changed with option
option ``--no-exception`` (see below). ``--no-exception`` (see below).
.. _Running_gnatstub: .. _Running_gnatstub:
...@@ -4118,7 +4102,7 @@ Alternatively, you may run the script using the following command line: ...@@ -4118,7 +4102,7 @@ Alternatively, you may run the script using the following command line:
:: ::
$ gnatstub [ switches ] filename [ -cargs gcc_switches ] $ gnatstub [ switches ] {filename}
where where
...@@ -4126,12 +4110,12 @@ Alternatively, you may run the script using the following command line: ...@@ -4126,12 +4110,12 @@ Alternatively, you may run the script using the following command line:
is the name of the source file that contains a library unit declaration 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 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. must be created for the body stubs declared in this body.
The file name may contain the path information. The file name may contain path information.
If the name does not follow GNAT file naming conventions and the set If the name does not follow GNAT file naming conventions and the set
of switches 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 conventions, the name of the body file must
be provided be provided
explicitly as the value of the :switch:`-o{body-name}` option. explicitly as the value of the :switch:`--output={body-name}` option.
If the file name follows the GNAT file naming If the file name follows the GNAT file naming
conventions and the name of the body file is not provided, conventions and the name of the body file is not provided,
``gnatstub`` ``gnatstub``
...@@ -4140,14 +4124,6 @@ Alternatively, you may run the script using the following command line: ...@@ -4140,14 +4124,6 @@ Alternatively, you may run the script using the following command line:
or creates the name file to generate using the standard GNAT or creates the name file to generate using the standard GNAT
naming conventions. naming conventions.
* *gcc_switches* is a list of switches for *gcc*.
They will be passed on to all compiler invocations made by
``gnatstub`` 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,
use the ``-gnat05`` switch if sources should be compiled in
Ada 2005 mode etc.
* *switches* * *switches*
is an optional sequence of switches as described in the next section is an optional sequence of switches as described in the next section
...@@ -4160,7 +4136,7 @@ Alternatively, you may run the script using the following command line: ...@@ -4160,7 +4136,7 @@ Alternatively, you may run the script using the following command line:
.. index:: --version (gnatstub) .. index:: --version (gnatstub)
:switch:`--version` :switch:`--version`
Display Copyright and version, then exit disregarding all other options. Display copyright and version, then exit disregarding all other options.
.. index:: --help (gnatstub) .. index:: --help (gnatstub)
...@@ -4181,8 +4157,7 @@ Alternatively, you may run the script using the following command line: ...@@ -4181,8 +4157,7 @@ Alternatively, you may run the script using the following command line:
:switch:`-X{name}={value}` :switch:`-X{name}={value}`
Indicates that external variable ``name`` in the argument project Indicates that external variable ``name`` in the argument project
has the value ``value``. Has no effect if no project is specified as has the value ``value``. Has no effect if no project is specified.
tool argument.
.. index:: --RTS (gnatstub) .. index:: --RTS (gnatstub)
...@@ -4196,32 +4171,32 @@ Alternatively, you may run the script using the following command line: ...@@ -4196,32 +4171,32 @@ Alternatively, you may run the script using the following command line:
:switch:`--subunits` :switch:`--subunits`
Generate subunits for body stubs. If this switch is specified, Generate subunits for body stubs. If this switch is specified,
``gnatstub`` expects a library unit body as an argument file, ``gnatstub`` expects a library unit body as an argument file;
otherwise a library unit declaration is expected. If a body stub otherwise a library unit declaration is expected. If a body stub
already has a corresponding subunit, ``gnatstub`` does not already has a corresponding subunit, ``gnatstub`` does not
generate anything for it. generate anything for it.
.. index:: -f (gnatstub) .. index:: --force (gnatstub)
:switch:`-f` :switch:`--force`
If the destination directory already contains a file with the name of the If the destination directory already contains a file with the name of the
body file body file
for the argument spec file, replace it with the generated body stub. for the argument spec file, replace it with the generated body stub.
This switch cannot be used together with ``--subunits``. This switch cannot be used together with ``--subunits``.
.. index:: -hs (gnatstub) .. index:: --comment-header-spec (gnatstub)
:switch:`-hs` :switch:`--comment-header-spec`
Put the comment header (i.e., all the comments preceding the Put the comment header (i.e., all the comments preceding the
compilation unit) from the source of the library unit declaration compilation unit) from the source of the library unit declaration
into the body stub. into the body stub.
.. index:: -hg (gnatstub) .. index:: --comment-header-sample (gnatstub)
:switch:`-hg` :switch:`--comment-header-sample`
Put a sample comment header into the body stub. Put a sample comment header into the body stub.
...@@ -4231,156 +4206,180 @@ Alternatively, you may run the script using the following command line: ...@@ -4231,156 +4206,180 @@ Alternatively, you may run the script using the following command line:
Use the content of the file as the comment header for a generated body stub. Use the content of the file as the comment header for a generated body stub.
.. index:: -IDIR (gnatstub) .. index:: --max-line-length (gnatstub)
.. index:: -I- (gnatstub)
:switch:`-I{DIR}`, :switch:`-I-` :switch:`--max-line-length={n}`
These switches have the same meaning as in calls to (``n`` is a non-negative integer). Set the maximum line length for
``gcc``. the output files. The default is 79. The maximum value that can be
They define the source search path in the call to specified is 32767.
``gcc`` issued
by ``gnatstub`` to compile an argument source file.
.. index:: -gnatec (gnatstub) .. index:: --indentation (gnatstub)
:switch:`-gnatec{PATH}` :switch:`--indentation={n}`
This switch has the same meaning as in calls to ``gcc``. (``n`` is an integer from 1 to 9). Set the indentation level in
It defines the additional configuration file to be passed to the call to the generated files to ``n``.
``gcc`` issued The default indentation is 3.
by ``gnatstub`` to compile an argument source file.
.. index:: -gnatyM (gnatstub) .. index:: --alphabetical-order (gnatstub)
:switch:`-gnatyM{n}` :switch:`--alphabetical-order`
(``n`` is a non-negative integer). Set the maximum line length that is Order local bodies alphabetically. (By default local bodies are ordered
allowed in a source file. The default is 79. The maximum value that can be in the same way as the corresponding local specs in the argument
specified is 32767. Note that in the special case of configuration spec file.)
pragma files, the maximum is always 32767 regardless of whether or
not this switch appears.
.. index:: -gnaty (gnatstub) .. index:: --no-exception (gnatstub)
:switch:`-gnaty{n}` :switch:`--no-exception`
(``n`` is a non-negative integer from 1 to 9). Set the indentation level in Avoid raising Program_Error in the generated bodies of program unit stubs,
the generated body sample to ``n``. except in the case of functions, where we have no value to return.
The default indentation is 3.
.. index:: -gnatyo (gnatstub) .. index:: --no-local-header (gnatstub)
:switch:`-gnatyo` :switch:`--no-local-header`
Order local bodies alphabetically. (By default local bodies are ordered Do not place local comment header with unit name before body stub for a
in the same way as the corresponding local specs in the argument spec file.) unit.
.. index:: -i (gnatstub) .. index:: --files (gnatstub)
:switch:`-i{n}` :switch:`--files={filename}`
Same as :switch:`-gnaty{n}`` 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.
.. index:: -k (gnatstub) .. index:: --output (gnatstub)
:switch:`-k` :switch:`--output={body-name}`
Do not remove the tree file (i.e., the snapshot of the compiler internal Body file name. This should be set if the argument file name does
structures used by ``gnatstub``) after creating the body stub. not follow the default GNAT file naming conventions, and the naming
conventions are not specified by a project file. If this switch and
``-P`` are both omitted, the name for the body will be obtained
according to the default GNAT file naming conventions.
.. index:: -l (gnatstub) .. index:: --output-dir (gnatstub)
:switch:`-l{n}` :switch:`--output-dir={dir-name}`
Same as ``-gnatyM`n``` The directory in which to place the output files.
If this switch is not set, the generated library unit body is
placed in the current directory, and generated sununits
in the directory where the argument body is located.
.. index:: --no-exception (gnatstub) .. index:: --wide-character-encoding (gnatstub)
:switch:`--no-exception` :switch:`--wide-character-encoding={e}`
Avoid raising Program_Error in the generated bodies of program unit stubs, Specify the wide character encoding method for the input and output
except in the case of functions, where we have no value to return. files. ``e`` is one of the following:
* *8* - UTF-8 encoding
.. index:: --no-local-header (gnatstub) * *b* - Brackets encoding (default value)
:switch:`--no-local-header`
Do not place local comment header with unit name before body stub for a
unit.
.. index:: --gnat83 (gnatstub)
.. index:: -o (gnatstub) :switch:`--gnat83`
Ada 83 mode
:switch:`-o {body-name}`
Body file name. This should be set if the argument file name does not
follow
the GNAT file naming
conventions. If this switch is omitted the default name for the body will be
obtained
from the argument file name according to the GNAT file naming conventions.
.. index:: --gnat95 (gnatstub)
.. index:: --dir (gnatstub) :switch:`--gnat95`
Ada 95 mode
:switch:`--dir={dir-name}`
The path to the directory to place the generated files into.
If this switch is not set, the generated library unit body is
placed in the current directory, and generated sununits -
in the directory where the argument body is located.
.. index:: --gnat2005 (gnatstub)
.. index:: -W (gnatstub) :switch:`--gnat2005`
Ada 2005 mode
:switch:`-W{e}`
Specify the wide character encoding method for the output body file.
``e`` is one of the following:
==== ================================== .. index:: --gnat2012 (gnatstub)
*h* Hex encoding
*u* Upper half encoding :switch:`--gnat2012`
*s* Shift/JIS encoding Ada 2012 mode
*e* EUC encoding
*8* UTF-8 encoding
*b* Brackets encoding (default value)
==== ==================================
.. index:: --quiet (gnatstub)
.. index:: -q (gnatstub) .. index:: -q (gnatstub)
:switch:`-q` :switch:`--quiet` / :switch:`-q`
Quiet mode: do not generate a confirmation when a body is Quiet mode.
successfully created, and do not generate a message when a body is not
required for an
argument unit.
.. index:: -r (gnatstub) .. index:: --verbose (gnatstub)
.. index:: -v (gnatstub)
:switch:`-r` :switch:`--verbose` / :switch:`-v`
Reuse the tree file (if it exists) instead of creating it. Instead of Verbose mode.
creating the tree file for the library unit declaration, ``gnatstub``
tries to find it in the current directory and use it for creating
a body. If the tree file is not found, no body is created. This option
also implies ``-k``, whether or not
the latter is set explicitly.
Legacy Switches
^^^^^^^^^^^^^^^
.. index:: -t (gnatstub) Some switches have a short form, mostly for legacy reasons,
as shown below.
:switch:`-t` .. index:: -M (gnatstub)
Overwrite the existing tree file. If the current directory already
contains the file which, according to the GNAT file naming rules should
be considered as a tree file for the argument source file,
``gnatstub``
will refuse to create the tree file needed to create a sample body
unless this option is set.
:switch:`-gnatyM{nnn}`
:switch:`--max-line-length={nnn}`
.. index:: -v (gnatstub) .. index:: -i (gnatstub)
:switch:`-v` :switch:`-i{nnn}`
Verbose mode: generate version information. :switch:`--indentation={nnn}`
.. index:: -gnaty (gnatstub)
:switch:`-gnaty{nnn}`
:switch:`--indentation={nnn}`
.. index:: -f (gnatstub)
:switch:`-f`
:switch:`--force`
.. index:: -gnatyo (gnatstub)
:switch:`-gnatyo`
:switch:`--alphabetical-order`
.. index:: -hg (gnatstub)
:switch:`-hg`
:switch:`--comment-header-sample`
.. index:: -hs (gnatstub)
:switch:`-hs`
:switch:`--comment-header-spec`
.. index:: -o (gnatstub)
:switch:`-o {output-file}`
:switch:`--output={output-file}`
.. index:: -dir (gnatstub)
:switch:`-dir {dir-name}`
:switch:`--output-dir={dir-name}`
.. index:: -W (gnatstub)
:switch:`-W{e}`
:switch:`--wide-character-encoding={e}`
.. index:: -files (gnatstub)
:switch:`-files {filename}`
:switch:`--files={filename}`
.. only:: PRO or GPL .. only:: PRO or GPL
......
gcc/ada/gnat_ugn.texi
...@@ -17384,7 +17384,7 @@ normal mode is listed, but no file is actually deleted. ...@@ -17384,7 +17384,7 @@ normal mode is listed, but no file is actually deleted.
@item @code{--version} @item @code{--version}
Display Copyright and version, then exit disregarding all other options. Display copyright and version, then exit disregarding all other options.
@end table @end table
@geindex --help (gnatclean) @geindex --help (gnatclean)
...@@ -17687,7 +17687,7 @@ version of the same source that has been modified. ...@@ -17687,7 +17687,7 @@ version of the same source that has been modified.
@item @code{--version} @item @code{--version}
Display Copyright and version, then exit disregarding all other options. Display copyright and version, then exit disregarding all other options.
@end table @end table
@geindex --help (gnatls) @geindex --help (gnatls)
...@@ -18020,7 +18020,7 @@ The following switches are available for @code{gnatxref}: ...@@ -18020,7 +18020,7 @@ The following switches are available for @code{gnatxref}:
@item @code{--version} @item @code{--version}
Display Copyright and version, then exit disregarding all other options. Display copyright and version, then exit disregarding all other options.
@end table @end table
@geindex --help (gnatxref) @geindex --help (gnatxref)
...@@ -18278,7 +18278,7 @@ The following switches are available: ...@@ -18278,7 +18278,7 @@ The following switches are available:
@item @code{--version} @item @code{--version}
Display Copyright and version, then exit disregarding all other options. Display copyright and version, then exit disregarding all other options.
@end table @end table
@geindex --help (gnatfind) @geindex --help (gnatfind)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment