[Ada] Documentation updates
Arnaud Charlet
charlet@adacore.com
Mon Sep 5 08:46:00 GMT 2005
Tested on i686-linux, committed on HEAD
Update documentation, e.g. document that bounds of result of Base_Name match
the input index positions.
2005-09-01 Robert Dewar <dewar@adacore.com>
Arnaud Charlet <charlet@adacore.com>
* g-dirope.ads: Minor reformatting
Document that bounds of result of Base_Name match the input index
positions.
Add documentation on environment variable syntax for Expand_Path
* gnat_ugn.texi: Update documentation to include mention of -m switches
Document new treatment of wide characters in max line length
style check.
Remove -gnatL/-gnatZ switches, no longer used.
Add note on pragmas Assertion_Policy and Debug_Policy in discussion
of -gnata switch.
* gnat_rm.texi: Add doc for two argument form of pragma
Float_Representation.
Add documentation for pragma No_Strict_Aliasing
Add note that explicit component clause overrides pragma Pack.
Add documentation of pragma Debug_Policy
-------------- next part --------------
Index: g-dirope.ads
===================================================================
RCS file: /cvs/gcc/gcc/gcc/ada/g-dirope.ads,v
retrieving revision 1.9
diff -u -p -r1.9 g-dirope.ads
--- g-dirope.ads 1 Jul 2005 01:24:14 -0000 1.9
+++ g-dirope.ads 5 Sep 2005 07:32:00 -0000
@@ -6,7 +6,7 @@
-- --
-- S p e c --
-- --
--- Copyright (C) 1998-2004 Ada Core Technologies, Inc. --
+-- Copyright (C) 1998-2005 Ada Core Technologies, Inc. --
-- --
-- GNAT is free software; you can redistribute it and/or modify it under --
-- terms of the GNU General Public License as published by the Free Soft- --
@@ -94,7 +94,7 @@ package GNAT.Directory_Operations is
-- Dir_Name. Raises Directory_Error if Dir_Name cannot be removed.
function Get_Current_Dir return Dir_Name_Str;
- -- Returns the current working directory for the execution environment.
+ -- Returns the current working directory for the execution environment
procedure Get_Current_Dir (Dir : out Dir_Name_Str; Last : out Natural);
-- Returns the current working directory for the execution environment
@@ -137,6 +137,10 @@ package GNAT.Directory_Operations is
-- The comparison of Suffix is case-insensitive on systems such as Windows
-- and VMS where the file search is case-insensitive (e.g. on such systems,
-- Base_Name ("/Users/AdaCore/BB12.patch", ".Patch") returns "BB12").
+ --
+ -- Note that the index bounds of the result match the corresponding indexes
+ -- in the Path string (you cannot assume that the lower bound of the
+ -- returned string is one).
function File_Extension (Path : Path_Name) return String;
-- Return the file extension. This is defined as the string after the
@@ -150,16 +154,7 @@ package GNAT.Directory_Operations is
-- path information. This is equivalent to Base_Name with default Extension
-- value.
- type Path_Style is
- (UNIX,
- -- Use '/' as the directory separator. The default on Unix systems
- -- and on OpenVMS.
-
- DOS,
- -- Use '\' as the directory separator. The default on Windows.
-
- System_Default);
-
+ type Path_Style is (UNIX, DOS, System_Default);
function Format_Pathname
(Path : Path_Name;
Style : Path_Style := System_Default) return Path_Name;
@@ -168,26 +163,20 @@ package GNAT.Directory_Operations is
-- function will help to provide a consistent naming scheme running for
-- different environments. If style is set to System_Default the routine
-- will use the default directory separator on the running environment.
+ --
+ -- The Style argument indicates the syntax to be used for path names:
+ --
+ -- UNIX
+ -- Use '/' as the directory separator. The default on Unix systems
+ -- and on OpenVMS.
+ --
+ -- DOS
+ -- Use '\' as the directory separator. The default on Windows.
+ --
+ -- System_Default
+ -- Use the default style for the current system
- type Environment_Style is
- (UNIX,
- -- Environment variables and OpenVMS logical names use $ as prefix and
- -- can use curly brackets as in ${HOME}/mydir. If there is no closing
- -- curly bracket for an opening one then translation is done, so for
- -- example ${VAR/toto is returned as ${VAR/toto.
-
- DOS,
- -- Environment variables uses % as prefix and suffix
- -- (e.g. %HOME%/mydir). The name DOS refer to "DOS-like" environment.
- -- This includes al Windows systems.
-
- Both,
- -- Recognize both forms described above.
-
- System_Default);
- -- Uses either UNIX on Unix and OpenVMS systems, or DOS on Windows and
- -- OS/2 depending on the running environment.
-
+ type Environment_Style is (UNIX, DOS, Both, System_Default);
function Expand_Path
(Path : Path_Name;
Mode : Environment_Style := System_Default) return Path_Name;
@@ -198,6 +187,29 @@ package GNAT.Directory_Operations is
-- variable does not exists the variable will be replaced by the empty
-- string. Two dollar or percent signs are replaced by a single
-- dollar/percent sign. Note that a variable must start with a letter.
+ --
+ -- The Mode argument indicates the recognized syntax for environment
+ -- variables as follows:
+ --
+ -- UNIX
+ -- Environment variables and OpenVMS logical names use $ as prefix and
+ -- can use curly brackets as in ${HOME}/mydir. If there is no closing
+ -- curly bracket for an opening one then no translation is done, so for
+ -- example ${VAR/toto is returned as ${VAR/toto. The use of {} brackets
+ -- is required if the environment variable name contains other than
+ -- alphanumeric characters.
+ --
+ -- DOS
+ -- Environment variables uses % as prefix and suffix (e.g. %HOME%/dir).
+ -- The name DOS refer to "DOS-like" environment. This includes all
+ -- Windows systems.
+ --
+ -- Both
+ -- Recognize both forms described above.
+ --
+ -- System_Default
+ -- Uses either UNIX on Unix and OpenVMS systems, or DOS on Windows and
+ -- OS/2 depending on the running environment.
---------------
-- Iterators --
@@ -215,7 +227,7 @@ package GNAT.Directory_Operations is
-- Raises Directory_Error if Dir has not be opened (Dir = Null_Dir).
function Is_Open (Dir : Dir_Type) return Boolean;
- -- Returns True if Dir is open, or False otherwise.
+ -- Returns True if Dir is open, or False otherwise
procedure Read
(Dir : in out Dir_Type;
@@ -251,6 +263,6 @@ private
Dir_Seps : constant Ada.Strings.Maps.Character_Set :=
Ada.Strings.Maps.To_Set ("/\");
- -- UNIX and DOS style directory separators.
+ -- UNIX and DOS style directory separators
end GNAT.Directory_Operations;
Index: gnat_ugn.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/ada/gnat_ugn.texi,v
retrieving revision 1.35
diff -u -p -r1.35 gnat_ugn.texi
--- gnat_ugn.texi 7 Jul 2005 09:47:42 -0000 1.35
+++ gnat_ugn.texi 5 Sep 2005 07:32:03 -0000
@@ -331,6 +331,7 @@ Performance Considerations
* Optimization Levels::
* Debugging Optimized Code::
* Inlining of Subprograms::
+* Other Optimization Switches::
* Optimization and Strict Aliasing::
@ifset vms
* Coverage Analysis::
@@ -3752,7 +3753,8 @@ Allow full Ada 2005 features.
@item -gnata
@cindex @option{-gnata} (@command{gcc})
Assertions enabled. @code{Pragma Assert} and @code{pragma Debug} to be
-activated.
+activated. Note that these pragmas can also be controlled using the
+configuration pragmas @code{Assertion_Policy} and @code{Debug_Policy}.
@item -gnatA
@cindex @option{-gnatA} (@command{gcc})
@@ -3865,11 +3867,6 @@ Limit file names to @var{n} (1-999) char
@cindex @option{-gnatl} (@command{gcc})
Output full source listing with embedded error messages.
-@item -gnatL
-@cindex @option{-gnatL} (@command{gcc})
-This switch is deprecated. You can use @option{--RTS=sjlj} instead to enable
-@code{setjmp/longjmp} exception mechanism.
-
@item -gnatm=@var{n}
@cindex @option{-gnatm} (@command{gcc})
Limit number of detected error or warning messages to @var{n}
@@ -3996,10 +3993,6 @@ Distribution stub generation and compila
to be generated and compiled).
@end ifset
-@item -gnatZ
-This switch is deprecated. When zero cost exception handling is not the
-default and this is supported, you can use @option{--RTS=zcx} instead.
-
@item ^-I^/SEARCH=^@var{dir}
@cindex @option{^-I^/SEARCH^} (@command{gcc})
@cindex RTL
@@ -4054,16 +4047,13 @@ No optimization, the default setting if
@item n = 1
Normal optimization, the default if you specify @option{-O} without
-an operand.
+an operand. A good compromise between code quality and compilation
+time.
@item n = 2
-Extensive optimization
+Extensive optimization, may improve execution time, possibly at the cost of
+substantially increased compilation time.
-@item n = 3
-Extensive optimization with automatic inlining of subprograms not
-specified by pragma @code{Inline}. This applies only to
-inlining within a unit. For details on control of inlining
-see @ref{Subprogram Inlining Control}.
@end table
@end ifclear
@@ -4094,11 +4084,6 @@ Perform some optimizations, but omit one
@item DEVELOPMENT
Same as @code{SOME}.
-@item INLINING
-Full optimization, and also attempt automatic inlining of small
-subprograms within a unit even when pragma @code{Inline}
-is not specified (@pxref{Inlining of Subprograms}).
-
@item UNROLL_LOOPS
Try to unroll loops. This keyword may be specified together with
any keyword above other than @code{NONE}. Loop unrolling
@@ -5537,10 +5522,10 @@ If the ^letter m^word LINE_LENGTH^ appea
then the length of source lines must not exceed 79 characters, including
any trailing blanks. The value of 79 allows convenient display on an
80 character wide device or window, allowing for possible special
-treatment of 80 character lines. Note that this count is of raw
+treatment of 80 character lines. Note that this count is of
characters in the source text. This means that a tab character counts
-as one character in this count and a wide character sequence counts as
-several characters (however many are needed in the encoding).
+as one character in this count but a wide character sequence counts as
+a single character (however many bytes are needed in the encoding).
@item ^Mnnn^MAX_LENGTH=nnn^
@emph{Set maximum line length.}
@@ -8911,7 +8896,9 @@ some guidelines on debugging optimized c
* Optimization Levels::
* Debugging Optimized Code::
* Inlining of Subprograms::
+* Other Optimization Switches::
* Optimization and Strict Aliasing::
+
@ifset vms
* Coverage Analysis::
@end ifset
@@ -9019,8 +9006,16 @@ No optimization (the default);
generates unoptimized code but has
the fastest compilation time.
+Note that many other compilers do fairly extensive optimization
+even if "no optimization" is specified. When using gcc, it is
+very unusual to use ^-O0^/OPTIMIZE=NONE^ for production if
+execution time is of any concern, since ^-O0^/OPTIMIZE=NONE^
+really does mean no optimization at all. This difference between
+gcc and other compilers should be kept in mind when doing
+performance comparisons.
+
@item ^-O1^/OPTIMIZE=SOME^
-Medium level optimization;
+Moderate optimization;
optimizes reasonably well but does not
degrade compilation time significantly.
@@ -9309,6 +9304,20 @@ that you should not automatically assume
@option{-O2}, and indeed you should use @option{-O3} only if tests show that
it actually improves performance.
+@node Other Optimization Switches
+@subsection Other Optimization Switches
+@cindex Optimization Switches
+
+Since @code{GNAT} uses the @code{gcc} back end, all the specialized
+@code{gcc} optimization switches are potentially usable. These switches
+have not been extensively tested with GNAT but can generally be expected
+to work. Examples of switches in this category are
+@option{-funroll-loops} and
+the various target-specific @option{-m} options (in particular, it has been
+observed that @option{-march=pentium4} can significantly improve performance
+on appropriate machines. For full details of these switches, see the
+@code{gcc} manual.
+
@node Optimization and Strict Aliasing
@subsection Optimization and Strict Aliasing
@cindex Aliasing
Index: gnat_rm.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/ada/gnat_rm.texi,v
retrieving revision 1.38
diff -u -p -r1.38 gnat_rm.texi
--- gnat_rm.texi 4 Jul 2005 13:31:43 -0000 1.38
+++ gnat_rm.texi 5 Sep 2005 07:32:04 -0000
@@ -118,6 +118,7 @@ Implementation Defined Pragmas
* Pragma CPP_Virtual::
* Pragma CPP_Vtable::
* Pragma Debug::
+* Pragma Debug_Policy::
* Pragma Detect_Blocking::
* Pragma Elaboration_Checks::
* Pragma Eliminate::
@@ -156,6 +157,7 @@ Implementation Defined Pragmas
* Pragma Machine_Attribute::
* Pragma Main_Storage::
* Pragma No_Return::
+* Pragma No_Strict_Aliasing ::
* Pragma Normalize_Scalars::
* Pragma Obsolescent::
* Pragma Passive::
@@ -649,6 +651,7 @@ consideration, the use of these pragmas
* Pragma CPP_Virtual::
* Pragma CPP_Vtable::
* Pragma Debug::
+* Pragma Debug_Policy::
* Pragma Detect_Blocking::
* Pragma Elaboration_Checks::
* Pragma Eliminate::
@@ -687,6 +690,7 @@ consideration, the use of these pragmas
* Pragma Machine_Attribute::
* Pragma Main_Storage::
* Pragma No_Return::
+* Pragma No_Strict_Aliasing::
* Pragma Normalize_Scalars::
* Pragma Obsolescent::
* Pragma Passive::
@@ -1362,12 +1366,45 @@ PROCEDURE_CALL_WITHOUT_SEMICOLON ::=
The argument has the syntactic form of an expression, meeting the
syntactic requirements for pragmas.
-If assertions are not enabled on the command line, this pragma has no
-effect. If asserts are enabled, the semantics of the pragma is exactly
+If debug pragmas are not enabled, this pragma has no
+effect. If debug pragmas are enabled, the semantics of the pragma is exactly
equivalent to the procedure call statement corresponding to the argument
with a terminating semicolon. Pragmas are permitted in sequences of
declarations, so you can use pragma @code{Debug} to intersperse calls to
-debug procedures in the middle of declarations.
+debug procedures in the middle of declarations. Debug pragmas can be
+enabled either by use of the command line switch @code{-gnata} or by use
+of the configuration pragma @code{Debug_Policy}.
+
+
+@node Pragma Debug_Policy
+@unnumberedsec Pragma Debug_Policy
+@findex Debug_Policy
+@noindent
+Syntax:
+
+@smallexample @c ada
+pragma Debug_Policy (CHECK | IGNORE);
+@end smallexample
+
+@noindent
+If the argument is @code{CHECK}, then pragma @code{DEBUG} is enabled.
+If the argument is @code{IGNORE}, then pragma @code{DEBUG} is ignored.
+This pragma overrides the effect of the @code{-gnata} switch on the
+command line.
+
+If debug pragmas are not enabled, this pragma has no
+effect. If debug pragmas are enabled, the semantics of the pragma is exactly
+equivalent to the procedure call statement corresponding to the argument
+with a terminating semicolon. Pragmas are permitted in sequences of
+declarations, so you can use pragma @code{Debug} to intersperse calls to
+debug procedures in the middle of declarations. Debug pragmas can be
+enabled either by use of the command line switch @code{-gnata} or by use
+of the configuration pragma @code{Debug_Policy}.
+
+
+
+
+
@node Pragma Detect_Blocking
@unnumberedsec Pragma Detect_Blocking
@@ -1981,13 +2018,13 @@ execution, hence the name.
Syntax:
@smallexample @c ada
-pragma Float_Representation (FLOAT_REP);
+pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]);
FLOAT_REP ::= VAX_Float | IEEE_Float
@end smallexample
@noindent
-This pragma
+In the one argument form, this pragma is a configuration pragma which
allows control over the internal representation chosen for the predefined
floating point types declared in the packages @code{Standard} and
@code{System}. On all systems other than OpenVMS, the argument must
@@ -1998,6 +2035,24 @@ the standard runtime libraries be recomp
description of the @code{GNAT LIBRARY} command in the OpenVMS version
of the GNAT Users Guide for details on the use of this command.
+The two argument form specifies the representation to be used for
+the specified floating-poin type. On all systems other than OpenVMS,
+the argument must
+be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the
+argument may be @code{VAX_Float} to specify the use of the VAX float
+format, as follows:
+
+@itemize @bullet
+@item
+For digits values up to 6, F float format will be used.
+@item
+For digits values from 7 to 9, G float format will be used.
+@item
+For digits values from 10 to 15, F float format will be used.
+@item
+Digits values above 15 are not allowed.
+@end itemize
+
@node Pragma Ident
@unnumberedsec Pragma Ident
@findex Ident
@@ -2670,7 +2725,7 @@ package p is
new_name_for_i : Integer;
pragma Linker_Alias (new_name_for_i, "i");
-end p;
+end p;
@end smallexample
@node Pragma Linker_Constructor
@@ -2865,6 +2920,26 @@ Another use of this pragma is to suppres
missing returns in functions, where the last statement of a function
statement sequence is a call to such a procedure.
+@node Pragma No_Strict_Aliasing
+@unnumberedsec Pragma No_Strict_Aliasing
+@findex No_Strict_Aliasing
+@noindent
+Syntax:
+
+@smallexample @c ada
+ppragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)];
+@end smallexample
+
+@noindent
+@var{type_LOCAL_NAME} must refer to an access type
+declaration in the current declarative part. The effect is to inhibit
+strict aliasing optimization for the given type. The form with no
+arguments is a configuration pragma which applies to all access types
+declared in units to which the pragma applies. For a detailed
+description of the strict aliasing optimization, and the situations
+in which it must be suppressed, see section "Optimization and Strict Aliasing"
+in the @value{EDITION} User's Guide.
+
@node Pragma Normalize_Scalars
@unnumberedsec Pragma Normalize_Scalars
@findex Normalize_Scalars
@@ -4033,7 +4108,7 @@ Note that if a warning is desired for al
regardless of whether they occur in the same unit as the subprogram
declaration, then this pragma should not be used (calls from another
unit would not be flagged); pragma Obsolescent can be used instead
-for this purpose (@xref{Pragma Obsolescent}).
+for this purpose, see @xref{Pragma Obsolescent}.
@node Pragma Unreserve_All_Interrupts
@unnumberedsec Pragma Unreserve_All_Interrupts
@@ -4245,7 +4320,7 @@ Address of such an entity, for example t
as shown in the example below.
Some file formats do not support weak symbols so not all target machines
-support this pragma.
+support this pragma.
@smallexample @c ada
-- Example of the use of pragma Weak_External
@@ -9167,7 +9242,7 @@ Only @code{Size} may be specified for su
@cindex Component_Size Clause
@noindent
-Normally, the value specified in a component clause must be consistent
+Normally, the value specified in a component size clause must be consistent
with the subtype of the array component with regard to size and alignment.
In other words, the value specified must be at least equal to the size
of this subtype, and must be a multiple of the alignment value.
@@ -9189,6 +9264,10 @@ then the resulting array has a length of
Of course access to the components of such an array is considerably
less efficient than if the natural component size of 32 is used.
+Note that there is no point in giving both a component size clause
+and a pragma Pack for the same array type. if such duplicate
+clauses are given, the pragma Pack will be ignored.
+
@node Bit_Order Clauses
@section Bit_Order Clauses
@cindex Bit_Order Clause
More information about the Gcc-patches
mailing list