2005-06-10 Robert Dewar <dewar@adacore.com>

	    Eric Botcazou  <ebotcazou@adacore.com>
	    Ben Brosgol  <brosgol@adacore.com>
	    Cyrille Comar  <comar@adacore.com>
	    Sergey Rybin  <rybin@adacore.com>
	    Pascal Obry  <obry@adacore.com>

	* gnat_rm.texi: Add documentation for pragma Persistent_BSS
	Document second argument (Ada_05) of pragma Obsolescent
	Add note that call to subprogram marked with pragma Obsolescent
	is now considered to be a violation of program Restrictions
	(No_Obsolescent_Features).
	(Implementation Defined Pragmas) <Machine_Attribute>: Make it clear
	that only machine-dependent attributes are supported.

	* gnat_ugn.texi:
	Commented out menu lines and empty section for gnatclean examples
	Document -gnatwy/Y
	Fix some over long lines
	Clarify and enhance documentation of ADA_PROJECT_PATH.
	Rework section 2.11.2(3) about linking with a non-GNU compiler.
	Mention new switch -fcallgraph-info.
	Mention new switch -fstack-usage.
	For gnatpp, replace '-notab' with '-N' and add this option to Index
	Corrected VMS example.
	VMS keyword for style check -gnatyd is DOS_LINE_ENDINGS, no NOCRLF
	Minor reformatting
	Add documentation for -gnatyu switch (unnecessary blank lines)
	Document new switch -U for GNAT PRETTY and GNAT METRIC
	Add note about Stdcall being handled as C convention on non Windows OS.
	Remove some junk typo in description of gnatbind -S switch
	Remove reference to Extensions_Allowed pragma
	Document the new order of the directories to be searched (source and
	object directories of project files before directories in ADA_*_PATH
	environment variables.

        * g-trasym.ads: Document that IRIX is supported


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

1 files changed, 135 insertions, 57 deletions

diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi
index e27ed3de73c..23b49ac93f0 100644
--- a/gcc/ada/gnat_ugn.texi
+++ b/gcc/ada/gnat_ugn.texi
@@ -433,7 +433,7 @@ Cleaning Up Using gnatclean
 
 * Running gnatclean::
 * Switches for gnatclean::
-* Examples of gnatclean Usage::
+@c * Examples of gnatclean Usage::
 
 @ifclear vms
 
@@ -1094,13 +1094,8 @@ $ gnatmake hello.adb
 The result is an executable program called @file{hello}, which can be
 run by entering:
 
-@c The following should be removed (BMB 2001-01-23)
-@c @smallexample
-@c $ ^./hello^$ RUN HELLO^
-@c @end smallexample
-
 @smallexample
-$ hello
+$ ^hello^RUN HELLO^
 @end smallexample
 
 @noindent
@@ -3054,7 +3049,9 @@ implemented as a single machine instruction.
 @item Stdcall
 This is relevant only to NT/Win95 implementations of GNAT,
 and specifies that the Stdcall calling sequence will be used, as defined
-by the NT API.
+by the NT API. Nevertheless, to ease building cross-platform bindings this
+convention will be handled as a C calling convention on non Windows
+platforms.
 
 @findex DLL
 @cindex Convention DLL
@@ -3202,8 +3199,11 @@ $ gnatlink -v -v ada_unit file1.o file2.o --LINK=./my_script
 @item
 Using a non-GNU C++ compiler: The commands previously described can be
 used to insure that the C++ linker is used. Nonetheless, you need to add
-the path to libgcc explicitly, since some libraries needed by GNAT are
-located in this directory:
+a few more parameters to the link command line, depending on the exception
+mechanism used.
+
+If the @code{setjmp/longjmp} exception mechanism is used, only the paths
+to the libgcc libraries are required:
 
 @smallexample
 $ cat ./my_script
@@ -3214,6 +3214,24 @@ $ gnatlink ada_unit file1.o file2.o --LINK=./my_script
 
 Where CC is the name of the non-GNU C++ compiler.
 
+If the @code{zero cost} exception mechanism is used, and the platform
+supports automatic registration of exception tables (e.g. Solaris or IRIX),
+paths to more objects are required:
+
+@smallexample
+$ cat ./my_script
+#!/bin/sh
+CC `gcc -print-file-name=crtbegin.o` $* \
+`gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a` \
+`gcc -print-file-name=crtend.o`
+$ gnatlink ada_unit file1.o file2.o --LINK=./my_script
+@end smallexample
+
+If the @code{zero cost} exception mechanism is used, and the platform
+doesn't support automatic registration of exception tables (e.g. HP-UX,
+Tru64 or AIX), the simple approach described above will not work and
+a pre-linking phase using GNAT will be necessary.
+
 @end enumerate
 
 @node A Simple Example
@@ -3699,6 +3717,19 @@ of objects of different types. See
 Activates stack checking.
 See @ref{Stack Overflow Checking} for details of the use of this option.
 
+@item -fstack-usage
+@cindex @option{-fstack-usage} (@command{gcc})
+Makes the compiler output stack usage information for the program, on a
+per-function basis.  The description of the format is to be found in
+the GCC documentation.
+
+@item -fcallgraph-info
+@cindex @option{-fcallgraph-info} (@command{gcc})
+Makes the compiler output callgraph information for the program, on a
+per-file basis.  The information is generated in the VCG format.  It can
+be decorated with additional, per-node information if other debugging
+options are enabled (only works with -fstack-usage as of this writing).
+
 @item ^-g^/DEBUG^
 @cindex @option{^-g^/DEBUG^} (@command{gcc})
 Generate debugging information. This information is stored in the object
@@ -4911,6 +4942,25 @@ such warnings are generated.
 This switch suppresses warnings for access to variables which
 may not be properly initialized.
 
+@item -gnatwy
+@emph{Activate warnings for Ada 2005 compatibility issues.}
+@cindex @option{-gnatwy} (@command{gcc})
+@cindex Ada 2005 compatibility issues warnings
+For the most part Ada 2005 is upwards compatible with Ada 95,
+but there are some exceptions (for example the fact that
+@code{interface} is now a reserved word in Ada 2005. This
+switch activates several warnings to help in identifying
+and correcting such incompatibilities. The default is that
+these warnings are generated. Note that at one point Ada 2005
+was called Ada 0Y, hence the choice of character.
+
+@item -gnatwY
+@emph{Disab le warnings for Ada 2005 compatibility issues.}
+@cindex @option{-gnatwY} (@command{gcc})
+@cindex Ada 2005 compatibility issues warnings
+This switch suppresses several warnings intended to help in identifying
+incompatibilities between Ada 95 and Ada 2005.
+
 @item -gnatwx
 @emph{Activate warnings on Export/Import pragmas.}
 @cindex @option{-gnatwx} (@command{gcc})
@@ -5363,9 +5413,10 @@ example:
 
 @item ^d^DOS_LINE_ENDINGS^
 @emph{Check no DOS line terminators present.}
-If the ^letter d^word NOCRLF^ appears in the string after @option{-gnaty}
-then all lines must be terminated by a single ASCII.LF character (in
-particular the DOS line terminator sequence CR/LF is not allowed).
+If the ^letter d^word DOS_LINE_ENDINGS^ appears in the string after
+@option{-gnaty} then all lines must be terminated by a single ASCII.LF
+character (in particular the DOS line terminator sequence CR/LF is not
+allowed).
 
 @item ^e^END^
 @emph{Check end/exit labels.}
@@ -5588,6 +5639,12 @@ A unary plus or minus may not be followed by a space.
 A vertical bar must be surrounded by spaces.
 @end itemize
 
+@item ^u^UNNECESSARY_BLANK_LINES^
+@emph{Check unnecessary blank lines.}
+Check for unnecessary blank lines. A blank line is considered
+unnecessary if it appears at the end of the file, or if more than
+one blank line occurs in sequence.
+
 @item ^x^XTRA_PARENS^
 @emph{Check extra parentheses.}
 Check for the use of an unnecessary extra level of parentheses (C-style)
@@ -5617,14 +5674,16 @@ The switch
 @ifclear vms
 @option{-gnaty} on its own (that is not
 followed by any letters or digits),
-is equivalent to @code{gnaty3abcefhiklmprst}, that is all checking
-options enabled with the exception of -gnatyo,
+is equivalent to @code{gnaty3abcefhiklmnprst}, that is all checking
+options enabled with the exception of @option{-gnatyo},
+@option{-gnatyd}, @option{-gnatyu}, and @option{-gnatyx}.
 @end ifclear
 @ifset vms
 /STYLE_CHECKS=ALL_BUILTIN enables all checking options with
-the exception of ORDERED_SUBPROGRAMS,
+the exception of ORDERED_SUBPROGRAMS, UNNECESSARY_BLANK_LINES,
+XTRA_PARENS, and DOS_LINE_ENDINGS. In addition
 @end ifset
-with an indentation level of 3. This is the standard
+an indentation level of 3 is set. This is similar to the standard
 checking option that is used for the GNAT sources.
 
 The switch
@@ -6716,6 +6775,16 @@ Each directory named by an @option{^-I^/SOURCE_SEARCH^} switch given on the
 @command{gcc} command line, in the order given.
 
 @item
+@findex ADA_PRJ_INCLUDE_FILE
+Each of the directories listed in the text file whose name is given
+by the @code{ADA_PRJ_INCLUDE_FILE} ^environment variable^logical name^.
+
+@noindent
+@code{ADA_PRJ_INCLUDE_FILE} is normally set by gnatmake or by the ^gnat^GNAT^
+driver when project files are used. It should not normally be set
+by other means.
+
+@item
 @findex ADA_INCLUDE_PATH
 Each of the directories listed in the value of the
 @code{ADA_INCLUDE_PATH} ^environment variable^logical name^.
@@ -6747,16 +6816,6 @@ packages by default, ADA_INCLUDE_PATH must be redefined.
 @end ifset
 
 @item
-@findex ADA_PRJ_INCLUDE_FILE
-Each of the directories listed in the text file whose name is given
-by the @code{ADA_PRJ_INCLUDE_FILE} ^environment variable^logical name^.
-
-@noindent
-@code{ADA_PRJ_INCLUDE_FILE} is normally set by gnatmake or by the ^gnat^GNAT^
-driver when project files are used. It should not normally be set
-by other means.
-
-@item
 The content of the @file{ada_source_path} file which is part of the GNAT
 installation tree and is used to store standard libraries such as the
 GNAT Run Time Library (RTL) source files.
@@ -7169,7 +7228,6 @@ The @var{xxx} ^string specified with the switch^option^ may be either
 @itemize @bullet
 @item ``@option{^in^INVALID^}'' requesting an invalid value where possible
 @item ``@option{^lo^LOW^}'' for the lowest possible value
-possible, and the low
 @item ``@option{^hi^HIGH^}'' for the highest possible value
 @item ``@option{xx}'' for a value consisting of repeated bytes with the
 value 16#xx# (i.e. xx is a string of two hexadecimal digits).
@@ -7632,6 +7690,16 @@ switches on the @code{gnatbind}
 command line, in the order given.
 
 @item
+@findex ADA_PRJ_OBJECTS_FILE
+Each of the directories listed in the text file whose name is given
+by the @code{ADA_PRJ_OBJECTS_FILE} ^environment variable^logical name^.
+
+@noindent
+@code{ADA_PRJ_OBJECTS_FILE} is normally set by gnatmake or by the ^gnat^GNAT^
+driver when project files are used. It should not normally be set
+by other means.
+
+@item
 @findex ADA_OBJECTS_PATH
 Each of the directories listed in the value of the
 @code{ADA_OBJECTS_PATH} ^environment variable^logical name^.
@@ -7664,16 +7732,6 @@ packages by default, ADA_OBJECTS_PATH must be redefined.
 @end ifset
 
 @item
-@findex ADA_PRJ_OBJECTS_FILE
-Each of the directories listed in the text file whose name is given
-by the @code{ADA_PRJ_OBJECTS_FILE} ^environment variable^logical name^.
-
-@noindent
-@code{ADA_PRJ_OBJECTS_FILE} is normally set by gnatmake or by the ^gnat^GNAT^
-driver when project files are used. It should not normally be set
-by other means.
-
-@item
 The content of the @file{ada_object_path} file which is part of the GNAT
 installation tree and is used to store standard libraries such as the
 GNAT Run Time Library (RTL) unless the switch @option{-nostdlib} is
@@ -10060,7 +10118,6 @@ recognized by @code{GNAT}:
    Elaboration_Checks
    Eliminate
    Extend_System
-   Extensions_Allowed
    External_Name_Casing
    Float_Representation
    Initialize_Scalars
@@ -10959,6 +11016,7 @@ is equivalent to the @command{gnatmake} invocation using the project file
 
 @node Importing Other Projects
 @subsection Importing Other Projects
+@cindex @code{ADA_PROJECT_PATH}
 
 @noindent
 A compilation unit in a source file in one project may depend on compilation
@@ -11993,6 +12051,7 @@ define a package @code{Naming} (@pxref{Naming Schemes}).
 
 @node  Importing Projects
 @section Importing Projects
+@cindex @code{ADA_PROJECT_PATH}
 
 @noindent
 An immediate source of a project P may depend on source files that
@@ -12016,19 +12075,24 @@ use literal strings instead of names, and the @code{with} clause identifies
 project files rather than packages.
 
 Each literal string is the file name or path name (absolute or relative) of a
-project file. If a string is simply a file name, with no path, then its
-location is determined by the @emph{project path}:
+project file. If a string corresponds to a file name, with no path or a
+relative path, then its location is determined by the @emph{project path}. The
+latter can be queried using @code{gnatls -v}. It contains:
 
 @itemize @bullet
 @item
-If the ^environment variable^logical name^ @env{ADA_PROJECT_PATH} exists,
-then the project path includes all the directories in this
-^environment variable^logical name^, plus the directory of the project file.
+In first position, the directory containing the current project file.
+@item
+In last position, the default project directory. This default project directory
+is part of the GNAT installation and is the standard place to install project
+files giving access to standard support libraries.
+@ifclear vms
+@ref{Installing a library}
+@end ifclear
 
 @item
-If the ^environment variable^logical name^ @env{ADA_PROJECT_PATH} does not
-exist, then the project path contains only one directory, namely the one where
-the project file is located.
+In between, all the directories referenced in the
+^environment variable^logical name^ @env{ADA_PROJECT_PATH} if it exists.
 @end itemize
 
 @noindent
@@ -12039,9 +12103,10 @@ If a relative pathname is used, as in
 @end smallexample
 
 @noindent
-then the path is relative to the directory where the importing project file is
-located. Any symbolic link will be fully resolved in the directory
-of the importing project file before the imported project file is examined.
+then the full path for the project is constructed by concatenating this
+relative path to those in the project path, in order, until a matching file is
+found. Any symbolic link will be fully resolved in the directory of the
+importing project file before the imported project file is examined.
 
 If the @code{with}'ed project file name does not have an extension,
 the default is @file{^.gpr^.GPR^}. If a file with this extension is not found,
@@ -13380,6 +13445,17 @@ with all the immediate sources of the specified project file and with
 of the project.
 
 @noindent
+In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with
+a project file, no source is specified on the command line and
+switch ^-U^/ALL_PROJECTS^ is specified on the command line, then
+the underlying tool (^gnatpp^gnatpp^ or
+^gnatmetric^gnatmetric^) is invoked for all sources of all projects,
+not only for the immediate sources of the main project.
+@ifclear vms
+(-U stands for Universal or Union of the project files of the project tree)
+@end ifclear
+
+@noindent
 For each of the following commands, there is optionally a corresponding
 package in the main project.
 
@@ -14810,7 +14886,8 @@ Compact layout
 @item ^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^
 Uncompact layout
 
-@item ^-notab^/NOTABS^
+@cindex @option{^-N^/NOTABS^} (@command{gnatpp})
+@item ^-N^/NOTABS^
 All the VT characters are removed from the comment text. All the HT characters
 are expanded with the sequences of space characters to get to the next tab
 stops.
@@ -15553,8 +15630,8 @@ upon units in files located outside the current directory, you have to provide
 the source search path when invoking @command{gnatmetric}.
 If it depends semantically upon units that are contained
 in files with names that do not follow the GNAT file naming rules, you have to
-provide the configuration file describing the corresponding naming scheme; see
-the description of the @command{gnatmetric} switches below.
+provide the configuration file describing the corresponding naming scheme (see
+the description of the @command{gnatmetric} switches below.)
 Alternatively, you may use a project file and invoke @command{gnatmetric}
 through the @command{gnat} driver.
 
@@ -16856,7 +16933,7 @@ generated files and executable files.
 @menu
 * Running gnatclean::
 * Switches for gnatclean::
-* Examples of gnatclean Usage::
+@c * Examples of gnatclean Usage::
 @end menu
 
 @node Running gnatclean
@@ -16970,8 +17047,8 @@ where @code{gnatclean} was invoked.
 
 @end table
 
-@node Examples of gnatclean Usage
-@section Examples of @code{gnatclean} Usage
+@c @node Examples of gnatclean Usage
+@c @section Examples of @code{gnatclean} Usage
 
 @ifclear vms
 @node GNAT and Libraries
@@ -17160,6 +17237,7 @@ the directive @option{-lxxx} at link time.
 
 @node Installing a library
 @subsection Installing a library
+@cindex @code{ADA_PROJECT_PATH}
 
 @noindent
 If you use project files, library installation is part of the library build
@@ -17199,7 +17277,7 @@ responsibility of the library provider to install the necessary sources, ALI
 files and libraries in the directories mentioned in the project file. For
 convenience, the user's library project file should be installed in a location
 that will be searched automatically by the GNAT
-builder. These are the directories referenced in the @code{ADA_LIBRARY_PATH}
+builder. These are the directories referenced in the @code{ADA_PROJECT_PATH}
 environment variable (@pxref{Importing Projects}), and also the default GNAT
 library location that can be queried with @command{gnatls -v} and is usually of
 the form $gnat_install_root/lib/gnat.