From 0453ca3d7288b11830065c9ed05ee3a75dc974da Mon Sep 17 00:00:00 2001 From: Robert Dewar Date: Thu, 16 Jun 2005 10:57:18 +0200 Subject: [PATCH] gnat_rm.texi: Add documentation for pragma Persistent_BSS Document second argument (Ada_05)... 2005-06-10 Robert Dewar Eric Botcazou Ben Brosgol Cyrille Comar Sergey Rybin Pascal Obry * 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) : 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 From-SVN: r101071 --- gcc/ada/g-trasym.ads | 6 +- gcc/ada/gnat_rm.texi | 149 ++++++++++++++++++++------------ gcc/ada/gnat_ugn.texi | 192 +++++++++++++++++++++++++++++------------- 3 files changed, 234 insertions(+), 113 deletions(-) diff --git a/gcc/ada/g-trasym.ads b/gcc/ada/g-trasym.ads index dc7b6dbe7c3..4268acfa392 100644 --- a/gcc/ada/g-trasym.ads +++ b/gcc/ada/g-trasym.ads @@ -6,7 +6,7 @@ -- -- -- S p e c -- -- -- --- Copyright (C) 1999-2004 Ada Core Technologies, Inc. -- +-- Copyright (C) 1999-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- -- @@ -33,8 +33,8 @@ -- Run-time symbolic traceback support --- Note: this is only available on selected targets. Currently it is --- supported on Sparc/Solaris, GNU/Linux, Windows NT, HP-UX, VMS and Tru64. +-- Note: this is only available on selected targets. Current targets are: +-- Sparc/Solaris, GNU/Linux, SGI/IRIX, Windows NT, HP-UX, VMS, Tru64. -- The routines provided in this package assume that your application has -- been compiled with debugging information turned on, since this information diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi index a985edc42d8..c6d50b3f396 100644 --- a/gcc/ada/gnat_rm.texi +++ b/gcc/ada/gnat_rm.texi @@ -157,6 +157,7 @@ Implementation Defined Pragmas * Pragma Normalize_Scalars:: * Pragma Obsolescent:: * Pragma Passive:: +* Pragma Persistent_BSS:: * Pragma Polling:: * Pragma Profile (Ravenscar):: * Pragma Profile (Restricted):: @@ -685,6 +686,7 @@ consideration, the use of these pragmas should be minimized. * Pragma Normalize_Scalars:: * Pragma Obsolescent:: * Pragma Passive:: +* Pragma Persistent_BSS:: * Pragma Polling:: * Pragma Profile (Ravenscar):: * Pragma Profile (Restricted):: @@ -978,7 +980,7 @@ Syntax: @smallexample @c ada pragma Common_Object ( - [Internal =>] LOCAL_NAME, + [Internal =>] local_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Size =>] EXTERNAL_SYMBOL] ); @@ -991,7 +993,7 @@ EXTERNAL_SYMBOL ::= This pragma enables the shared use of variables stored in overlaid linker areas corresponding to the use of @code{COMMON} in Fortran. The single -object @var{local_name} is assigned to the area designated by +object @var{local_NAME} is assigned to the area designated by the @var{External} argument. You may define a record to correspond to a series of fields. The @var{size} argument @@ -1036,7 +1038,7 @@ Syntax: @smallexample @c ada pragma Complex_Representation - ([Entity =>] LOCAL_NAME); + ([Entity =>] local_NAME); @end smallexample @noindent @@ -1060,7 +1062,7 @@ Syntax: @smallexample @c ada pragma Component_Alignment ( [Form =>] ALIGNMENT_CHOICE - [, [Name =>] type_LOCAL_NAME]); + [, [Name =>] type_local_NAME]); ALIGNMENT_CHOICE ::= Component_Size @@ -1107,7 +1109,7 @@ alignment). @end table @noindent -If the @code{Name} parameter is present, @var{type_local_name} must +If the @code{Name} parameter is present, @var{type_local_NAME} must refer to a local record or array type, and the specified alignment choice applies to the specified type. The use of @code{Component_Alignment} together with a pragma @code{Pack} causes the @@ -1171,7 +1173,7 @@ would be used system-wide. Syntax: @smallexample @c ada -pragma CPP_Class ([Entity =>] LOCAL_NAME); +pragma CPP_Class ([Entity =>] local_NAME); @end smallexample @noindent @@ -1202,7 +1204,7 @@ See @ref{Interfacing to C++} for related information. Syntax: @smallexample @c ada -pragma CPP_Constructor ([Entity =>] LOCAL_NAME); +pragma CPP_Constructor ([Entity =>] local_NAME); @end smallexample @noindent @@ -1533,7 +1535,7 @@ Syntax: @smallexample @c ada pragma Export_Exception ( - [Internal =>] LOCAL_NAME, + [Internal =>] local_NAME, [, [External =>] EXTERNAL_SYMBOL,] [, [Form =>] Ada | VMS] [, [Code =>] static_integer_EXPRESSION]); @@ -1562,7 +1564,7 @@ Syntax: @smallexample @c ada pragma Export_Function ( - [Internal =>] LOCAL_NAME, + [Internal =>] local_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Parameter_Types =>] PARAMETER_TYPES] [, [Result_Type =>] result_SUBTYPE_MARK] @@ -1638,7 +1640,7 @@ Syntax: @smallexample @c ada pragma Export_Object - [Internal =>] LOCAL_NAME, + [Internal =>] local_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Size =>] EXTERNAL_SYMBOL] @@ -1663,7 +1665,7 @@ Syntax: @smallexample @c ada pragma Export_Procedure ( - [Internal =>] LOCAL_NAME + [Internal =>] local_NAME [, [External =>] EXTERNAL_SYMBOL] [, [Parameter_Types =>] PARAMETER_TYPES] [, [Mechanism =>] MECHANISM]); @@ -1743,7 +1745,7 @@ Syntax: @smallexample @c ada pragma Export_Valued_Procedure ( - [Internal =>] LOCAL_NAME + [Internal =>] local_NAME [, [External =>] EXTERNAL_SYMBOL] [, [Parameter_Types =>] PARAMETER_TYPES] [, [Mechanism =>] MECHANISM]); @@ -1775,7 +1777,7 @@ MECHANISM_NAME ::= @noindent This pragma is identical to @code{Export_Procedure} except that the -first parameter of @var{local_name}, which must be present, must be of +first parameter of @var{local_NAME}, which must be present, must be of mode @code{OUT}, and externally the subprogram is treated as a function with this parameter as the result of the function. GNAT provides for this capability to allow the use of @code{OUT} and @code{IN OUT} @@ -1957,7 +1959,7 @@ to enforce the upper casing of all external symbols. Syntax: @smallexample @c ada -pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); +pragma Finalize_Storage_Only (first_subtype_local_NAME); @end smallexample @noindent @@ -2024,7 +2026,7 @@ Syntax: @smallexample @c ada pragma Import_Exception ( - [Internal =>] LOCAL_NAME, + [Internal =>] local_NAME, [, [External =>] EXTERNAL_SYMBOL,] [, [Form =>] Ada | VMS] [, [Code =>] static_integer_EXPRESSION]); @@ -2051,7 +2053,7 @@ Syntax: @smallexample @c ada pragma Import_Function ( - [Internal =>] LOCAL_NAME, + [Internal =>] local_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Parameter_Types =>] PARAMETER_TYPES] [, [Result_Type =>] SUBTYPE_MARK] @@ -2133,7 +2135,7 @@ Syntax: @smallexample @c ada pragma Import_Object - [Internal =>] LOCAL_NAME, + [Internal =>] local_NAME, [, [External =>] EXTERNAL_SYMBOL], [, [Size =>] EXTERNAL_SYMBOL]); @@ -2159,7 +2161,7 @@ Syntax: @smallexample @c ada pragma Import_Procedure ( - [Internal =>] LOCAL_NAME, + [Internal =>] local_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Parameter_Types =>] PARAMETER_TYPES] [, [Mechanism =>] MECHANISM] @@ -2205,7 +2207,7 @@ Syntax: @smallexample @c ada pragma Import_Valued_Procedure ( - [Internal =>] LOCAL_NAME, + [Internal =>] local_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Parameter_Types =>] PARAMETER_TYPES] [, [Mechanism =>] MECHANISM] @@ -2240,7 +2242,7 @@ CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca @noindent This pragma is identical to @code{Import_Procedure} except that the -first parameter of @var{local_name}, which must be present, must be of +first parameter of @var{local_NAME}, which must be present, must be of mode @code{OUT}, and externally the subprogram is treated as a function with this parameter as the result of the function. The purpose of this capability is to allow the use of @code{OUT} and @code{IN OUT} @@ -2356,7 +2358,7 @@ Syntax: @smallexample @c ada pragma Interface ( [Convention =>] convention_identifier, - [Entity =>] local_name + [Entity =>] local_NAME [, [External_Name =>] static_string_expression], [, [Link_Name =>] static_string_expression]); @end smallexample @@ -2377,7 +2379,7 @@ Syntax: @smallexample @c ada pragma Interface_Name ( - [Entity =>] LOCAL_NAME + [Entity =>] local_NAME [, [External_Name =>] static_string_EXPRESSION] [, [Link_Name =>] static_string_EXPRESSION]); @end smallexample @@ -2395,7 +2397,7 @@ least one of @var{External_Name} or @var{Link_Name}. Syntax: @smallexample @c ada -pragma Interrupt_Handler (procedure_LOCAL_NAME); +pragma Interrupt_Handler (procedure_local_NAME); @end smallexample @noindent @@ -2491,11 +2493,11 @@ and in the case of the signal used to implement the @code{abort} statement. Syntax: @smallexample @c ada -pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); +pragma Keep_Names ([On =>] enumeration_first_subtype_local_NAME); @end smallexample @noindent -The @var{LOCAL_NAME} argument +The @var{local_NAME} argument must refer to an enumeration first subtype in the current declarative part. The effect is to retain the enumeration literal names for use by @code{Image} and @code{Value} even if a global @@ -2634,7 +2636,7 @@ Syntax: @smallexample @c ada pragma Linker_Alias ( - [Entity =>] LOCAL_NAME + [Entity =>] local_NAME [Alias =>] static_string_EXPRESSION); @end smallexample @@ -2650,7 +2652,7 @@ Syntax: @smallexample @c ada pragma Linker_Section ( - [Entity =>] LOCAL_NAME + [Entity =>] local_NAME [Section =>] static_string_EXPRESSION); @end smallexample @@ -2691,19 +2693,18 @@ Syntax: @smallexample @c ada pragma Machine_Attribute ( [Attribute_Name =>] string_EXPRESSION, - [Entity =>] LOCAL_NAME); + [Entity =>] local_NAME); @end smallexample @noindent -Machine dependent attributes can be specified for types and/or -declarations. Currently only subprogram entities are supported. This -pragma is semantically equivalent to +Machine-dependent attributes can be specified for types and/or +declarations. This pragma is semantically equivalent to @code{__attribute__((@var{string_expression}))} in GNU C, where @code{@var{string_expression}} is -recognized by the GNU C macros @code{VALID_MACHINE_TYPE_ATTRIBUTE} and -@code{VALID_MACHINE_DECL_ATTRIBUTE} which are defined in the -configuration header file @file{tm.h} for each machine. See the GCC -manual for further information. +recognized by the target macro @code{TARGET_ATTRIBUTE_TABLE} which is +defined for each machine. See the GCC manual for further information. +It is not possible to specify attributes defined by other languages, +only attributes defined by the machine the code is intended to run on. @node Pragma Main_Storage @unnumberedsec Pragma Main_Storage @@ -2734,7 +2735,7 @@ also has no effect in DEC Ada 83 for OpenVMS Alpha Systems. Syntax: @smallexample @c ada -pragma No_Return (procedure_LOCAL_NAME); +pragma No_Return (procedure_local_NAME); @end smallexample @noindent @@ -2833,7 +2834,7 @@ will always generate an invalid value if one exists. Syntax: @smallexample @c ada -pragma Obsolescent [(static_string_EXPRESSION)]; +pragma Obsolescent [(static_string_EXPRESSION [,Ada_05])]; @end smallexample @noindent @@ -2849,6 +2850,17 @@ subprogram is obsolescent if the appropriate warning option in the compiler is activated. If a parameter is present, then a second warning message is given containing this text. +In addition, a call to such a program is considered a violation of +pragma Restrictions (No_Obsolescent_Features). + +If the optional second parameter is present (which must be exactly +the identifier Ada_05, no other argument is allowed), then the +indication of obsolescence applies only when compiling in Ada 2005 +mode. This is primarily intended for dealing with the situations +in the predefined library where subprograms have become defined +as obsolescent in Ada 2005 (e.g. in Ada.Characters.Handling), but +may be used anywhere. + @node Pragma Passive @unnumberedsec Pragma Passive @findex Passive @@ -2870,6 +2882,37 @@ desired. If the argument @code{No} is present, the task must not be optimized. GNAT does not attempt to optimize any tasks in this manner (since protected objects are available in place of passive tasks). +@node Pragma Persistent_BSS +@unnumberedsec Pragma Persistent_BSS +@findex Persistent_BSS +@noindent +Syntax: + +@smallexample @c ada +pragma Persistent_BSS [local_NAME] +@end smallexample + +@noindent +This pragma allows selected objects to be placed in the @code{.persistent_bss} +section. On some targets the linker and loader provide for special +treatment of this section, allowing a program to be reloaded without +affecting the contents of this data (hence the name persistent). + +There are two forms of usage. If an argument is given, it must be the +local name of a library level object, with no explicit initialization +and whose type is potentially persistent. If no argument is given, then +the pragma is a configuration pragma, and applies to all library level +objects with no explicit initialization of potentially persistent types. + +A potentially persistent type is a scalar type, or a non-tagged, +non-discriminated record, all of whose components have no explicit +initialization and are themselves of a potentially persistent type, +or an array, all of whose constraints are static, and whose component +type is potentially persistent. + +If this pragma is used on a target where this feature is not supported, +then the pragma will be ignored. See also @code{pragma Linker_Section}. + @node Pragma Polling @unnumberedsec Pragma Polling @findex Polling @@ -3098,7 +3141,7 @@ limited set of tasking functionality permitted by this set of restrictions. Syntax: @smallexample @c ada -pragma Propagate_Exceptions (subprogram_LOCAL_NAME); +pragma Propagate_Exceptions (subprogram_local_NAME); @end smallexample @noindent @@ -3138,7 +3181,7 @@ Syntax: @smallexample @c ada pragma Psect_Object ( - [Internal =>] LOCAL_NAME, + [Internal =>] local_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Size =>] EXTERNAL_SYMBOL]); @@ -3157,7 +3200,7 @@ This pragma is identical in effect to pragma @code{Common_Object}. Syntax: @smallexample @c ada -pragma Pure_Function ([Entity =>] function_LOCAL_NAME); +pragma Pure_Function ([Entity =>] function_local_NAME); @end smallexample @noindent @@ -3331,7 +3374,7 @@ Syntax: @smallexample @c ada pragma Stream_Convert ( - [Entity =>] type_LOCAL_NAME, + [Entity =>] type_local_NAME, [Read =>] function_NAME, [Write =>] function_NAME); @end smallexample @@ -3405,7 +3448,7 @@ Syntax: @smallexample @c ada pragma Style_Checks (string_LITERAL | ALL_CHECKS | - On | Off [, LOCAL_NAME]); + On | Off [, local_NAME]); @end smallexample @noindent @@ -3626,7 +3669,7 @@ Syntax: @smallexample @c ada pragma Task_Storage ( - [Task_Type =>] LOCAL_NAME, + [Task_Type =>] local_NAME, [Top_Guard =>] static_integer_EXPRESSION); @end smallexample @@ -3645,7 +3688,7 @@ Syntax: @smallexample @c ada pragma Thread_Body ( - [Entity =>] LOCAL_NAME, + [Entity =>] local_NAME, [[Secondary_Stack_Size =>] static_integer_EXPRESSION)]; @end smallexample @@ -3730,7 +3773,7 @@ following the normal rules for procedure calls in Ada. Syntax: @smallexample @c ada -pragma Unchecked_Union (first_subtype_LOCAL_NAME); +pragma Unchecked_Union (first_subtype_local_NAME); @end smallexample @noindent @@ -3845,7 +3888,7 @@ compilations of units where universal addressing of the data is desired. Syntax: @smallexample @c ada -pragma Unreferenced (local_Name @{, local_Name@}); +pragma Unreferenced (local_NAME @{, local_NAME@}); @end smallexample @noindent @@ -3863,7 +3906,7 @@ and that this is deliberate. It can also be useful in the case of objects declared only for their initialization or finalization side effects. -If @code{local_Name} identifies more than one matching homonym in the +If @code{local_NAME} identifies more than one matching homonym in the current scope, then the entity most recently declared is the one to which the pragma applies. @@ -4033,7 +4076,7 @@ Dec Ada 83. Syntax: @smallexample @c ada -pragma Warnings (On | Off [, LOCAL_NAME]); +pragma Warnings (On | Off [, local_NAME]); @end smallexample @noindent @@ -4046,7 +4089,7 @@ setting of the command line switches. The form with a single argument is a configuration pragma. -If the @var{local_name} parameter is present, warnings are suppressed for +If the @var{local_NAME} parameter is present, warnings are suppressed for the specified entity. This suppression is effective from the point where it occurs till the end of the extended scope of the variable (similar to the scope of @code{Suppress}). @@ -4058,7 +4101,7 @@ the scope of @code{Suppress}). Syntax: @smallexample @c ada -pragma Weak_External ([Entity =>] LOCAL_NAME); +pragma Weak_External ([Entity =>] local_NAME); @end smallexample @noindent @@ -13103,13 +13146,13 @@ inter-operability between Ada tagged types and C class definitions. See @ref{Implementation Defined Pragmas}, for more details. @table @code -@item pragma CPP_Class ([Entity =>] @var{local_name}) +@item pragma CPP_Class ([Entity =>] @var{local_NAME}) The argument denotes an entity in the current declarative region that is declared as a tagged or untagged record type. It indicates that the type corresponds to an externally declared C++ class type, and is to be laid out the same way that C++ would lay out the type. -@item pragma CPP_Constructor ([Entity =>] @var{local_name}) +@item pragma CPP_Constructor ([Entity =>] @var{local_NAME}) This pragma identifies an imported function (imported in the usual way with pragma @code{Import}) as corresponding to a C++ constructor. @@ -14603,7 +14646,7 @@ of the @command{gnatls} utility to be used to retrieve information about the predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}. @item VCS_Kind -This is a simple attribute. Is value is a string used to specify the +This is a simple attribute. Its value is a string used to specify the Version Control System (VCS) to be used for this project, e.g CVS, RCS ClearCase or Perforce. 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 @@ -6715,6 +6774,16 @@ The directory containing the source file of the main unit being compiled 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 @@ -6746,16 +6815,6 @@ instead of the Ada95 packages. Thus, in order to get the Ada 95 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 @@ -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). @@ -7631,6 +7689,16 @@ All directories specified by @option{^-I^/SEARCH^} 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 @@ -7663,16 +7731,6 @@ instead of the Ada95 packages. Thus, in order to get the Ada 95 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 @@ -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, @@ -13379,6 +13444,17 @@ with all the immediate sources of the specified project file and with @option{^-d^/DIRECTORY^} with the parameter pointing to the object directory 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. -- 2.30.2