From e3f2ff72f246cd5ad5c0352ecb2772ba89740aa1 Mon Sep 17 00:00:00 2001 From: Bob Duff Date: Tue, 11 Dec 2018 11:09:24 +0000 Subject: [PATCH] [Ada] Update gnatstub documentation for the Libadalang-based version 2018-12-11 Bob Duff gcc/ada/ * doc/gnat_ugn/gnat_utility_programs.rst: Update gnatstub documentation for the Libadalang-based version. * gnat_ugn.texi: Regenerate. From-SVN: r266981 --- gcc/ada/ChangeLog | 6 + gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst | 293 ++++++++++++------------- gcc/ada/gnat_ugn.texi | 8 +- 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 + + * doc/gnat_ugn/gnat_utility_programs.rst: Update gnatstub + documentation for the Libadalang-based version. + * gnat_ugn.texi: Regenerate. + 2018-12-11 Ed Schonberg * 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 f43bacf..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) -- 2.7.4