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>
* 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``
.. index:: --version (gnatclean)
: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)
......@@ -289,7 +289,7 @@ Switches for ``gnatls``
.. index:: --version (gnatls)
: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)
......@@ -535,7 +535,7 @@ The following switches are available for ``gnatxref``:
.. index:: --version (gnatxref)
: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)
......@@ -724,7 +724,7 @@ The following switches are available:
.. index:: --version (gnatfind)
: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)
......@@ -1357,7 +1357,7 @@ Alternatively, you may run the script using the following command line:
:switch:`-X{name}={value}`
Indicates that external variable ``name`` in
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}`
Specifies the default location of the runtime
......@@ -2696,7 +2696,7 @@ Alternatively, you may run the script using the following command line:
.. index:: --version (gnatmetric)
: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)
......@@ -2734,8 +2734,7 @@ Alternatively, you may run the script using the following command line:
:switch:`-X{name}={value}`
Indicates that external variable ``name`` in the argument project
has the value ``value``. Has no effect if no project is specified as
tool argument.
has the value ``value``. Has no effect if no project is specified.
.. index:: --RTS (gnatmetric)
......@@ -3494,8 +3493,7 @@ Alternatively, you may run the script using the following command line:
:switch:`-X{name}={value}`
Indicates that external variable ``name`` in the argument project
has the value ``value``. Has no effect if no project is specified as
tool argument.
has the value ``value``. Has no effect if no project is specified.
.. index:: --RTS (gnatpp)
......@@ -4079,7 +4077,7 @@ Alternatively, you may run the script using the following command line:
``gnatstub`` creates empty but compilable bodies
for library unit declarations, and empty but compilable
subunit for body stubs.
subunits for body stubs.
``gnatstub`` is a project-aware tool.
(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:
``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``
raise the predefined ``Program_Error`` exception, which will catch
accidental calls of generated stubs. This behavior can be changed with
option ``--no-exception`` (see below).
raise ``Program_Error``, which will catch accidental calls of
generated stubs. This behavior can be changed with option
``--no-exception`` (see below).
.. _Running_gnatstub:
......@@ -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
......@@ -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
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.
The file name may contain path information.
If the name does not follow GNAT file naming conventions and the set
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.
explicitly as the value of the :switch:`--output={body-name}` option.
If the file name follows the GNAT file naming
conventions and the name of the body file is not provided,
``gnatstub``
......@@ -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
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*
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:
.. index:: --version (gnatstub)
: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)
......@@ -4181,8 +4157,7 @@ Alternatively, you may run the script using the following command line:
:switch:`-X{name}={value}`
Indicates that external variable ``name`` in the argument project
has the value ``value``. Has no effect if no project is specified as
tool argument.
has the value ``value``. Has no effect if no project is specified.
.. index:: --RTS (gnatstub)
......@@ -4196,32 +4171,32 @@ Alternatively, you may run the script using the following command line:
:switch:`--subunits`
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
already has a corresponding subunit, ``gnatstub`` does not
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
body file
for the argument spec file, replace it with the generated body stub.
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
compilation unit) from the source of the library unit declaration
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.
......@@ -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.
.. index:: -IDIR (gnatstub)
.. index:: -I- (gnatstub)
.. index:: --max-line-length (gnatstub)
:switch:`-I{DIR}`, :switch:`-I-`
These switches have the same meaning as in calls to
``gcc``.
They define the source search path in the call to
``gcc`` issued
by ``gnatstub`` to compile an argument source file.
:switch:`--max-line-length={n}`
(``n`` is a non-negative integer). Set the maximum line length for
the output files. The default is 79. The maximum value that can be
specified is 32767.
.. index:: -gnatec (gnatstub)
.. index:: --indentation (gnatstub)
:switch:`-gnatec{PATH}`
This switch has the same meaning as in calls to ``gcc``.
It defines the additional configuration file to be passed to the call to
``gcc`` issued
by ``gnatstub`` to compile an argument source file.
:switch:`--indentation={n}`
(``n`` is an integer from 1 to 9). Set the indentation level in
the generated files to ``n``.
The default indentation is 3.
.. index:: -gnatyM (gnatstub)
.. index:: --alphabetical-order (gnatstub)
:switch:`-gnatyM{n}`
(``n`` is a non-negative integer). Set the maximum line length that is
allowed in a source file. The default is 79. The maximum value that can be
specified is 32767. Note that in the special case of configuration
pragma files, the maximum is always 32767 regardless of whether or
not this switch appears.
:switch:`--alphabetical-order`
Order local bodies alphabetically. (By default local bodies are ordered
in the same way as the corresponding local specs in the argument
spec file.)
.. index:: -gnaty (gnatstub)
.. index:: --no-exception (gnatstub)
:switch:`-gnaty{n}`
(``n`` is a non-negative integer from 1 to 9). Set the indentation level in
the generated body sample to ``n``.
The default indentation is 3.
:switch:`--no-exception`
Avoid raising Program_Error in the generated bodies of program unit stubs,
except in the case of functions, where we have no value to return.
.. index:: -gnatyo (gnatstub)
.. index:: --no-local-header (gnatstub)
:switch:`-gnatyo`
Order local bodies alphabetically. (By default local bodies are ordered
in the same way as the corresponding local specs in the argument spec file.)
:switch:`--no-local-header`
Do not place local comment header with unit name before body stub for a
unit.
.. index:: -i (gnatstub)
.. index:: --files (gnatstub)
:switch:`-i{n}`
Same as :switch:`-gnaty{n}``
: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.
.. index:: -k (gnatstub)
.. index:: --output (gnatstub)
:switch:`-k`
Do not remove the tree file (i.e., the snapshot of the compiler internal
structures used by ``gnatstub``) after creating the body stub.
:switch:`--output={body-name}`
Body file name. This should be set if the argument file name does
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}`
Same as ``-gnatyM`n```
:switch:`--output-dir={dir-name}`
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`
Avoid raising Program_Error in the generated bodies of program unit stubs,
except in the case of functions, where we have no value to return.
:switch:`--wide-character-encoding={e}`
Specify the wide character encoding method for the input and output
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:
==== ==================================
*h* Hex encoding
*u* Upper half encoding
*s* Shift/JIS encoding
*e* EUC encoding
*8* UTF-8 encoding
*b* Brackets encoding (default value)
==== ==================================
.. index:: --gnat2012 (gnatstub)
:switch:`--gnat2012`
Ada 2012 mode
.. index:: --quiet (gnatstub)
.. index:: -q (gnatstub)
:switch:`-q`
Quiet mode: do not generate a confirmation when a body is
successfully created, and do not generate a message when a body is not
required for an
argument unit.
:switch:`--quiet` / :switch:`-q`
Quiet mode.
.. index:: -r (gnatstub)
.. index:: --verbose (gnatstub)
.. index:: -v (gnatstub)
:switch:`-r`
Reuse the tree file (if it exists) instead of creating it. Instead of
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.
:switch:`--verbose` / :switch:`-v`
Verbose mode.
Legacy Switches
^^^^^^^^^^^^^^^
.. index:: -t (gnatstub)
Some switches have a short form, mostly for legacy reasons,
as shown below.
:switch:`-t`
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.
.. index:: -M (gnatstub)
:switch:`-gnatyM{nnn}`
:switch:`--max-line-length={nnn}`
.. index:: -v (gnatstub)
.. index:: -i (gnatstub)
:switch:`-v`
Verbose mode: generate version information.
:switch:`-i{nnn}`
: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
......
gcc/ada/gnat_ugn.texi
......@@ -17384,7 +17384,7 @@ normal mode is listed, but no file is actually deleted.
@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
@geindex --help (gnatclean)
......@@ -17687,7 +17687,7 @@ version of the same source that has been modified.
@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
@geindex --help (gnatls)
......@@ -18020,7 +18020,7 @@ The following switches are available for @code{gnatxref}:
@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
@geindex --help (gnatxref)
......@@ -18278,7 +18278,7 @@ The following switches are available:
@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
@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