2007-10-15 Vincent Celier <celier@adacore.com>

	    Robert Dewar  <dewar@adacore.com>

	* gnat_ugn.texi: Add documentation for switches --version and --help
	for the GNAT tools gnatbind, gnatlink, gnatmake, gnatchop, gnatname,
	gnatxref, gnatfind, gnatls, and gnatclean.
	Document -gnatw.o.
	Mention attribute Excluded_Source_Dirs
	Replace obsolescent attribute Locally_Removed_Files with attribute
	Excluded_Source_Files.
	Improve documentation of -u (gnatbind)
	Document how to do reliable stack checking for the environmental task
	on iVMS.

	* gnat_rm.texi: Rewrite section about No_Implicit_Dynamic_Code.
	Document attribute Excluded_Source_Files and indicate that attribute
	Locally_Removed_Files is obsolescent.



git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@129341 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 133 insertions, 8 deletions

diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi
index 0979412feb1..73862deacfc 100644
--- a/gcc/ada/gnat_ugn.texi
+++ b/gcc/ada/gnat_ugn.texi
@@ -4724,6 +4724,7 @@ switch are
 @option{-gnatwd} (implicit dereferencing),
 @option{-gnatwh} (hiding),
 @option{-gnatwl} (elaboration warnings),
+@option{-gnatw.o} (warn on values set by out parameters ignored)
 and @option{-gnatwt} (tracking of deleted conditional code).
 All other optional warnings are turned on.
 
@@ -5012,6 +5013,25 @@ This switch suppresses warnings on possibly unintended initialization
 effects of defining address clauses that cause one variable to overlap
 another.
 
+@item -gnatw.o
+@emph{Activate warnings on modified but unreferenced out parameters.}
+@cindex @option{-gnatw.o} (@command{gcc})
+This switch activates warnings for variables that are modified by using
+them as actuals for a call to a procedure with an out mode formal, where
+the resulting assigned value is never read.
+The warning is suppressed for volatile
+variables and also for variables that are renamings of other variables
+or for which an address clause is given.
+The default is that these warnings are not given. Note that this warning
+is not included in -gnatwa, it must be activated explicitly.
+
+@item -gnatw.O
+@emph{Disable warnings on modified but unreferenced out parameters.}
+@cindex @option{-gnatw.O} (@command{gcc})
+This switch suppresses warnings for variables that are modified by using
+them as actuals for a call to a procedure with an out mode formal, where
+the resulting assigned value is never read.
+
 @item -gnatwp
 @emph{Activate warnings on ineffective pragma Inlines.}
 @cindex @option{-gnatwp} (@command{gcc})
@@ -7383,6 +7403,15 @@ be presented in subsequent sections.
 @table @option
 @c !sort!
 
+@item --version
+@cindex @option{--version} @command{gnatbind}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatbind}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
 @item -a
 @cindex @option{-a} @command{gnatbind}
 Indicates that, if supported by the platform, the adainit procedure should
@@ -7619,9 +7648,11 @@ scheduling policy to @code{FIFO_Within_Priorities}.
 
 @item ^-u@var{n}^/DYNAMIC_STACK_USAGE=@var{n}^
 @cindex @option{^-u^/DYNAMIC_STACK_USAGE^} (@code{gnatbind})
-Enable dynamic stack usage, with n result stored and displayed at program
-termination. Results that can't be stored are displayed on the fly, at task
-termination. This option is currently not supported on OpenVMS I64 platforms.
+Enable dynamic stack usage, with @var{n} results stored and displayed
+at program termination. A result is generated when a task
+terminates. Results that can't be stored are displayed on the fly, at
+task termination. This option is currently not supported on Itanium
+platforms. (See @ref{Dynamic Stack Usage Analysis} for details.)
 
 @item ^-v^/REPORT_ERRORS=VERBOSE^
 @cindex @option{^-v^/REPORT_ERRORS=VERBOSE^} (@code{gnatbind})
@@ -8297,6 +8328,15 @@ The following switches are available with the @command{gnatlink} utility:
 @table @option
 @c !sort!
 
+@item --version
+@cindex @option{--version} @command{gnatlink}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatlink}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
 @item ^-A^/BIND_FILE=ADA^
 @cindex @option{^-A^/BIND_FILE=ADA^} (@command{gnatlink})
 The binder has generated code in Ada. This is the default.
@@ -8527,6 +8567,16 @@ You may specify any of the following switches to @command{gnatmake}:
 
 @table @option
 @c !sort!
+
+@item --version
+@cindex @option{--version} @command{gnatmake}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatmake}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
 @ifclear vms
 @item --GCC=@var{compiler_name}
 @cindex @option{--GCC=compiler_name} (@command{gnatmake})
@@ -10446,6 +10496,15 @@ no source files written
 @table @option
 @c !sort!
 
+@item --version
+@cindex @option{--version} @command{gnatchop}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatchop}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
 @item ^-c^/COMPILATION^
 @cindex @option{^-c^/COMPILATION^} (@code{gnatchop})
 Causes @code{gnatchop} to operate in compilation mode, in which
@@ -10804,6 +10863,15 @@ You may specify any of the following switches to @code{gnatname}:
 @table @option
 @c !sort!
 
+@item --version
+@cindex @option{--version} @command{gnatname}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatname}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
 @item ^-c^/CONFIG_FILE=^@file{file}
 @cindex @option{^-c^/CONFIG_FILE^} (@code{gnatname})
 Create a configuration pragmas file @file{file} (instead of the default
@@ -11714,20 +11782,20 @@ and no longer requires a body: in this case, it is necessary to indicate that
 the inherited body is not part of the sources of the project, otherwise there
 will be a compilation error when compiling the spec.
 
-For that purpose, the attribute @code{Locally_Removed_Files} is used.
+For that purpose, the attribute @code{Excluded_Source_Files} is used.
 Its value is a string list: a list of file names.
 
 @smallexample @c @projectfile
 project B extends "a" is
    for Source_Files use ("pkg.ads");
    --  New spec of Pkg does not need a completion
-   for Locally_Removed_Files use ("pkg.adb");
+   for Excluded_Source_Files use ("pkg.adb");
 end B;
 @end smallexample
 
-Attribute @code{Locally_Removed_Files} may also be used to check if a source
+Attribute @code{Excluded_Source_Files} may also be used to check if a source
 is still needed: if it is possible to build using @command{gnatmake} when such
-a source is put in attribute @code{Locally_Removed_Files} of a project P, then
+a source is put in attribute @code{Excluded_Source_Files} of a project P, then
 it is possible to remove the source completely from a system that includes
 project P.
 
@@ -12092,7 +12160,9 @@ The following attributes are defined on projects (all are simple attributes):
 @tab string
 @item @code{Exec_Dir}
 @tab string
-@item @code{Locally_Removed_Files}
+@item @code{Excluded_Source_Dirs}
+@tab string list
+@item @code{Excluded_Source_Files}
 @tab string list
 @item @code{Languages}
 @tab string list
@@ -14499,6 +14569,15 @@ the source path. If you specify directories, no result is produced.
 The switches can be :
 @table @option
 @c !sort!
+@item --version
+@cindex @option{--version} @command{gnatxref}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatxref}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
 @item ^-a^/ALL_FILES^
 @cindex @option{^-a^/ALL_FILES^} (@command{gnatxref})
 If this switch is present, @code{gnatfind} and @code{gnatxref} will parse
@@ -14656,6 +14735,14 @@ The following switches are available:
 @table @option
 @c !sort!
 
+@cindex @option{--version} @command{gnatfind}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatfind}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
 @item ^-a^/ALL_FILES^
 @cindex @option{^-a^/ALL_FILES^} (@command{gnatfind})
 If this switch is present, @code{gnatfind} and @code{gnatxref} will parse
@@ -17513,6 +17600,14 @@ version of the same source that has been modified.
 
 @table @option
 @c !sort!
+@cindex @option{--version} @command{gnatls}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatls}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
 @item ^-a^/ALL_UNITS^
 @cindex @option{^-a^/ALL_UNITS^} (@code{gnatls})
 Consider all units, including those of the predefined Ada library.
@@ -17751,6 +17846,14 @@ normal mode is listed, but no file is actually deleted.
 
 @table @option
 @c !sort!
+@cindex @option{--version} @command{gnatclean}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatclean}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
 @item ^-c^/COMPILER_FILES_ONLY^
 @cindex @option{^-c^/COMPILER_FILES_ONLY^} (@code{gnatclean})
 Only attempt to delete the files produced by the compiler, not those produced
@@ -19399,6 +19502,7 @@ For the environment task, the stack size depends on
 system defaults and is unknown to the compiler. Stack checking
 may still work correctly if a fixed
 size stack is allocated, but this cannot be guaranteed.
+@ifclear vms
 To ensure that a clean exception is signalled for stack
 overflow, set the environment variable
 @code{GNAT_STACK_LIMIT} to indicate the maximum
@@ -19417,6 +19521,27 @@ of stack used by the environment task. If it is necessary to
 increase the amount of stack for the environment task, then this
 is an operating systems issue, and must be addressed with the
 appropriate operating systems commands.
+@end ifclear
+@ifset vms
+To have a fixed size stack in the environment task, the stack must be put
+in the P0 address space and its size specified.  Use these switches to
+create a p0 image:
+
+@smallexample
+gnatmake my_progs -largs "-Wl,--opt=STACK=4000,/p0image"
+@end smallexample
+
+@noindent
+The quotes are required to keep case.  The number after @samp{STACK=} is the
+size of the environmental task stack in pagelets (512 bytes).  In this example
+the stack size is about 2 megabytes.
+
+@noindent
+A consequence of the @option{/p0image} qualifier is also to makes RMS buffers
+be placed in P0 space.  Refer to @cite{HP OpenVMS Linker Utility Manual} for
+more details about the @option{/p0image} qualifier and the @option{stack}
+option.
+@end ifset
 
 @node Static Stack Usage Analysis
 @section Static Stack Usage Analysis