gnat_ugn.texi: Add documentation for switches --version and --help for the GNAT tools gnatbind...

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.

From-SVN: r129341

gcc/ada/gnat_rm.texi

@@ -7780,11 +7780,13 @@ of composite objects and the Max/Min attributes.
 @findex No_Implicit_Dynamic_Code
 This restriction prevents the compiler from building ``trampolines''.
 This is a structure that is built on the stack and contains dynamic
-code to be executed at run time. A trampoline is needed to indirectly
-address a nested subprogram (that is a subprogram that is not at the
-library level). The restriction prevents the use of any of the
-attributes @code{Address}, @code{Access} or @code{Unrestricted_Access}
-being applied to a subprogram that is not at the library level.
+code to be executed at run time. On some targets, a trampoline is
+built for the following features: @code{Access},
+@code{Unrestricted_Access}, or @code{Address} of a nested subprogram;
+nested task bodies; primitive operations of nested tagged types.
+Trampolines do not work on machines that prevent execution of stack
+data. For example, on windows systems, enabling DEP (data execution
+protection) will cause trampolines to raise an exception.
 
 @item No_Implicit_Loops
 @findex No_Implicit_Loops
@@ -15044,6 +15046,15 @@ If not specified, executables are placed in the object directory.
 Expression must be a list of path names. The attribute
 defines the directories in which the source files for the project are to be
 found. If not specified, source files are found in the project directory.
+If a string in the list ends with "/**", then the directory that precedes
+"/**" and all of its subdirectories (recursively) are included in the list
+of source directories.
+
+@item  Excluded_Source_Dirs
+Expression must be a list of strings. Each entry designates a directory that
+is not to be included in the list of source directories of the project.
+This is normally used when there are strings ending with "/**" in the value
+of attribute Source_Dirs.
 
 @item  Source_Files
 Expression must be a list of file names. The attribute
@@ -15052,6 +15063,16 @@ as sources for the project. File names are path_names that contain no directory
 information. If the project has no sources the attribute must be declared
 explicitly with an empty list.
 
+@item  Excluded_Source_Files (Locally_Removed_Files)
+Expression must be a list of strings that are legal file names.
+Each file name must designate a source that would normally be a source file
+in the source directories of the project or, if the project file is an
+extending project file, inherited by the current project file. It cannot
+designate an immediate source that is not inherited. Each of the source files
+in the list are not considered to be sources of the project file: they are not
+inherited. Attribute Locally_Removed_Files is obsolescent, attribute
+Excluded_Source_Files is preferred.
+
 @item  Source_List_File
 Expression must a single path name. The attribute
 defines a text file that contains a list of source file names to be used
@@ -15186,13 +15207,6 @@ language of the main program.
 Expression must be a string list. Each string designates
 a programming language that is known to GNAT. The strings are case-insensitive.
 
-@item  Locally_Removed_Files
-This attribute is legal only in a project file that extends another.
-Expression must be a list of strings that are legal file names.
-Each file name must designate a source that would normally be inherited
-by the current project file. It cannot designate an immediate source that is
-not inherited. Each of the source files in the list are not considered to
-be sources of the project file: they are not inherited.
 @end table
 
 @node Attribute References

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