aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBob Duff <duff@adacore.com>2018-12-11 11:09:24 +0000
committerPierre-Marie de Rodat <pmderodat@gcc.gnu.org>2018-12-11 11:09:24 +0000
commite3f2ff72f246cd5ad5c0352ecb2772ba89740aa1 (patch)
treec4393a0a54b794b1bcc958160880f1be300e2cbd
parent5f531feff7ed6651354ed5b1cbd2a83cf204d170 (diff)
downloadgcc-e3f2ff72f246cd5ad5c0352ecb2772ba89740aa1.zip
gcc-e3f2ff72f246cd5ad5c0352ecb2772ba89740aa1.tar.gz
gcc-e3f2ff72f246cd5ad5c0352ecb2772ba89740aa1.tar.bz2
[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
-rw-r--r--gcc/ada/ChangeLog6
-rw-r--r--gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst293
-rw-r--r--gcc/ada/gnat_ugn.texi8
3 files changed, 156 insertions, 151 deletions
diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog
index 861b09d..ebcdc6e 100644
--- a/gcc/ada/ChangeLog
+++ b/gcc/ada/ChangeLog
@@ -1,3 +1,9 @@
+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
diff --git a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
index f43bacfd..98ff342 100644
--- a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
+++ b/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
diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi
index 9e2138e..dc216df 100644
--- a/gcc/ada/gnat_ugn.texi
+++ b/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)