g-dirope.ads: Minor reformatting Document that bounds of result of Base_Name match the input...
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 From-SVN: r103891
This commit is contained in:
Robert Dewar
Arnaud Charlet
parent
bbb9131042
commit
c1cd0d9675
@ -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;
|
||||
|
||||
@ -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 should be minimized.
|
||||
* 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 should be minimized.
|
||||
* 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 recompiled. See the
|
||||
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 suppress incorrect warnings about
|
||||
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 all calls to a given subprogram,
|
||||
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 to guard potential references,
|
||||
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 such types.
|
||||
@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 31 bytes (248 bits = 8 * 31).
|
||||
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
|
||||
|
||||
@ -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) characters ^(@code{k} = krunch)^^.
|
||||
@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 compilation
|
||||
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 no @option{-O} appears
|
||||
|
||||
@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 ones that are costly.
|
||||
@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^ appears in the string after @option{-gnaty}
|
||||
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 code.
|
||||
* 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 that @option{-O3} is better than
|
||||
@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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user