diff options
| author | bstarynk <bstarynk@138bc75d-0d04-0410-961f-82ee72b054a4> | 2010-09-19 18:19:39 +0000 |
|---|---|---|
| committer | bstarynk <bstarynk@138bc75d-0d04-0410-961f-82ee72b054a4> | 2010-09-19 18:19:39 +0000 |
| commit | e56043cd2c207982e812ce6fcecb7353dea58363 (patch) | |
| tree | 01a6f37ad5a9ae6b18bdc20f052b04e19b4255c0 /gcc/ada/gnat_ugn.texi | |
| parent | 2e02a1a4548f2ee1ea519c88e68b20621ad16fcc (diff) | |
| download | gcc-e56043cd2c207982e812ce6fcecb7353dea58363.tar.gz | |
2010-09-19 Basile Starynkevitch <basile@starynkevitch.net>
MELT branch merged with trunk rev 164348, with some improvements
in gcc/melt-runtime.[ch]
2010-09-19 Basile Starynkevitch <basile@starynkevitch.net>
[[merged with trunk rev.164348, so improved MELT runtime!]]
* gcc/melt-runtime.h: improved comments.
(melt_debug_garbcoll, melt_debuggc_eprintf): Moved from melt-runtime.c.
(melt_obmag_string): New declaration.
(struct meltobject_st, struct meltclosure_st, struct
meltroutine_st, struct meltmixbigint_st, struct meltstring_st):
using GTY variable_size and @@MELTGTY@@ comment.
(melt_mark_special): added debug print.
* gcc/melt-runtime.c: Improved comments.
Include bversion.h, realmpfr.h, gimple-pretty-print.h.
(ggc_force_collect) Declared external.
(melt_forward_counter): Added.
(melt_obmag_string): New function.
(melt_alptr_1, melt_alptr_2, melt_break_alptr_1_at)
(melt_break_alptr_2_at, melt_break_alptr_1,melt_break_alptr_1)
(melt_allocate_young_gc_zone, melt_free_young_gc_zone): New.
(delete_special, meltgc_make_special): Improved debug printf and
use melt_break_alptr_1...
(ggc_alloc_*) macros defined for backport to GCC 4.5
(melt_forwarded_copy): Don't clear the new destination zone in old
GGC heap.
(meltgc_add_out_raw_len): Use ggc_alloc_atomic.
(meltgc_raw_new_mappointers, meltgc_raw_put_mappointers)
(meltgc_raw_remove_mappointers): Corrected length argument to
ggc_alloc_cleared_vec_entrypointermelt_st.
(melt_really_initialize): Call melt_allocate_young_gc_zone.
(melt_initialize): Set flag_plugin_added.
(melt_val2passflag): TODO_verify_loops only in GCC 4.5
git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/branches/melt-branch@164424 138bc75d-0d04-0410-961f-82ee72b054a4
Diffstat (limited to 'gcc/ada/gnat_ugn.texi')
| -rw-r--r-- | gcc/ada/gnat_ugn.texi | 6694 |
1 files changed, 779 insertions, 5915 deletions
diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi index ab52d637c95..80086022476 100644 --- a/gcc/ada/gnat_ugn.texi +++ b/gcc/ada/gnat_ugn.texi @@ -7,7 +7,7 @@ @c o @c G N A T _ U G N o @c o -@c GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o +@c Copyright (C) 1992-2010, AdaCore o @c o @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo @@ -18,7 +18,7 @@ Copyright @copyright{} 1995-2009 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or +under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts and with no Back-Cover Texts. A copy of the license is included in the section entitled @@ -107,6 +107,13 @@ Texts. A copy of the license is included in the section entitled @macro ovar{varname} @r{[}@var{\varname\}@r{]}@c @end macro +@c Status as of November 2009: +@c Unfortunately texi2pdf and texi2html treat the trailing "@c" +@c differently, and faulty output is produced by one or the other +@c depending on whether the "@c" is present or absent. +@c As a result, the @ovar macro is not used, and all invocations +@c of the @ovar macro have been expanded inline. + @settitle @value{EDITION} User's Guide @value{PLATFORM} @dircategory GNU Ada tools @@ -169,14 +176,12 @@ AdaCore@* * Configuration Pragmas:: * Handling Arbitrary File Naming Conventions Using gnatname:: * GNAT Project Manager:: +* Tools Supporting Project Files:: * The Cross-Referencing Tools gnatxref and gnatfind:: * The GNAT Pretty-Printer gnatpp:: * The GNAT Metric Tool gnatmetric:: * File Name Krunching Using gnatkr:: * Preprocessing Using gnatprep:: -@ifset vms -* The GNAT Run-Time Library Builder gnatlbr:: -@end ifset * The GNAT Library Browser gnatls:: * Cleaning Up Using gnatclean:: @ifclear vms @@ -340,6 +345,7 @@ Performance Considerations Reducing Size of Ada Executables with gnatelim * About gnatelim:: * Running gnatelim:: +* Processing Precompiled Libraries:: * Correcting the List of Eliminate Pragmas:: * Making Your Executables Smaller:: * Summary of the gnatelim Usage Cycle:: @@ -368,26 +374,6 @@ Handling Arbitrary File Naming Conventions Using gnatname * Switches for gnatname:: * Examples of gnatname Usage:: -GNAT Project Manager - -* Introduction:: -* Examples of Project Files:: -* Project File Syntax:: -* Objects and Sources in Project Files:: -* Importing Projects:: -* Project Extension:: -* Project Hierarchy Extension:: -* External References in Project Files:: -* Packages in Project Files:: -* Variables from Imported Projects:: -* Naming Schemes:: -* Library Projects:: -* Stand-alone Library Projects:: -* Switches Related to Project Files:: -* Tools Supporting Project Files:: -* An Extended Example:: -* Project File Complete Syntax:: - The Cross-Referencing Tools gnatxref and gnatfind * Switches for gnatxref:: @@ -420,14 +406,6 @@ Preprocessing Using gnatprep * Form of Definitions File:: * Form of Input Text for gnatprep:: -@ifset vms -The GNAT Run-Time Library Builder gnatlbr - -* Running gnatlbr:: -* Switches for gnatlbr:: -* Examples of gnatlbr Usage:: -@end ifset - The GNAT Library Browser gnatls * Running gnatls:: @@ -523,6 +501,7 @@ Running and Debugging Ada Programs * Ada Exceptions:: * Ada Tasks:: * Debugging Generic Units:: +* Remote Debugging using gdbserver:: * GNAT Abnormal Termination or Failure to Terminate:: * Naming Conventions for GNAT Source Files:: * Getting Internal Debugging Information:: @@ -597,6 +576,8 @@ Platform-Specific Information for the Run-Time Libraries * Linux-Specific Considerations:: * AIX-Specific Considerations:: * Irix-Specific Considerations:: +* RTX-Specific Considerations:: +* HP-UX-Specific Considerations:: Example of Binder Output File @@ -800,13 +781,6 @@ preprocessor utility that allows a single source file to be used to generate multiple or parameterized source files by means of macro substitution. -@ifset vms -@item -@ref{The GNAT Run-Time Library Builder gnatlbr}, describes @command{gnatlbr}, -a tool for rebuilding the GNAT run time with user-supplied -configuration pragmas. -@end ifset - @item @ref{The GNAT Library Browser gnatls}, describes @code{gnatls}, a utility that displays information about compiled units, including dependences @@ -1804,8 +1778,8 @@ of the compiler (@pxref{Character Set Control}). @noindent The basic character set is Latin-1. This character set is defined by ISO standard 8859, part 1. The lower half (character codes @code{16#00#} -@dots{} @code{16#7F#)} is identical to standard ASCII coding, but the upper half -is used to represent additional characters. These include extended letters +@dots{} @code{16#7F#)} is identical to standard ASCII coding, but the upper +half is used to represent additional characters. These include extended letters used by European languages, such as French accents, the vowels with umlauts used in German, and the extra letter A-ring used in Swedish. @@ -3849,7 +3823,8 @@ compiled. @cindex cannot generate code If you attempt to compile any of these files, you will get one of the -following error messages (where @var{fff} is the name of the file you compiled): +following error messages (where @var{fff} is the name of the file you +compiled): @smallexample cannot generate code for file @var{fff} (package spec) @@ -3873,7 +3848,9 @@ without generating code, then use the @option{-gnatc} switch. The basic command for compiling a file containing an Ada unit is @smallexample -$ gcc -c @ovar{switches} @file{file name} +@c $ gcc -c @ovar{switches} @file{file name} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gcc -c @r{[}@var{switches}@r{]} @file{file name} @end smallexample @noindent @@ -4003,7 +3980,7 @@ effect if this switch is present. @item -fno-inline-functions @cindex @option{-fno-inline-functions} (@command{gcc}) -Suppresses automatic inlining of simple subprograms, which is enabled +Suppresses automatic inlining of subprograms, which is enabled if @option{-O3} is used. @item -fno-inline-small-functions @@ -4066,6 +4043,17 @@ Enforce Ada 95 restrictions. @cindex @option{-gnat05} (@command{gcc}) Allow full Ada 2005 features. +@item -gnat2005 +@cindex @option{-gnat2005} (@command{gcc}) +Allow full Ada 2005 features (same as @option{-gnat05} + +@item -gnat12 +@cindex @option{-gnat12} (@command{gcc}) + +@item -gnat2012 +@cindex @option{-gnat2012} (@command{gcc}) +Allow full Ada 2012 features (same as @option{-gnat12} + @item -gnata @cindex @option{-gnata} (@command{gcc}) Assertions enabled. @code{Pragma Assert} and @code{pragma Debug} to be @@ -4188,7 +4176,7 @@ Note that @option{^-gnatg^/GNAT_INTERNAL^} implies @option{^-gnatwae^/WARNINGS=ALL,ERRORS^} and @option{^-gnatyg^/STYLE_CHECKS=GNAT^} so that all standard warnings and all standard style options are turned on. -All warnings and style error messages are treated as errors. +All warnings and style messages are treated as errors. @ifclear vms @item -gnatG=nn @@ -4282,7 +4270,12 @@ controlled by this switch (division by zero checking is on by default). @item -gnatp @cindex @option{-gnatp} (@command{gcc}) -Suppress all checks. See @ref{Run-Time Checks} for details. +Suppress all checks. See @ref{Run-Time Checks} for details. This switch +has no effect if cancelled by a subsequent @option{-gnat-p} switch. + +@item -gnat-p +@cindex @option{-gnat-p} (@command{gcc}) +Cancel effect of previous @option{-gnatp} switch. @item -gnatP @cindex @option{-gnatP} (@command{gcc}) @@ -4360,6 +4353,10 @@ Wide character encoding method @cindex @option{-gnatx} (@command{gcc}) Suppress generation of cross-reference information. +@item -gnatX +@cindex @option{-gnatX} (@command{gcc}) +Enable GNAT implementation extensions and latest Ada version. + @item ^-gnaty^/STYLE_CHECKS=(option,option@dots{})^ @cindex @option{^-gnaty^/STYLE_CHECKS^} (@command{gcc}) Enable built-in style checks (@pxref{Style Checking}). @@ -4419,7 +4416,9 @@ Inhibit the search of the default location for the GNAT Run Time Library (RTL) ALI files. @ifclear vms -@item -O@ovar{n} +@c @item -O@ovar{n} +@c Expanding @ovar macro inline (explanation in macro def comments) +@item -O@r{[}@var{n}@r{]} @cindex @option{-O} (@command{gcc}) @var{n} controls the optimization level. @@ -4577,6 +4576,9 @@ The switches @option{-gnatzc} and @option{-gnatzr} may not be combined with any other switches, and only one of them may appear in the command line. +@item +The switch @option{-gnat-p} may not be combined with any other switch. + @ifclear vms @item Once a ``y'' appears in the string (that is a use of the @option{-gnaty} @@ -5054,6 +5056,7 @@ individually controlled. The warnings that are not turned on by this switch are @option{-gnatwd} (implicit dereferencing), @option{-gnatwh} (hiding), +@option{-gnatw.h} (holes (gaps) in record layouts) @option{-gnatwl} (elaboration warnings), @option{-gnatw.o} (warn on values set by out parameters ignored) and @option{-gnatwt} (tracking of deleted conditional code). @@ -5190,12 +5193,14 @@ This switch suppresses warnings for implicit dereferences in indexed components, slices, and selected components. @item -gnatwe -@emph{Treat warnings as errors.} +@emph{Treat warnings and style checks as errors.} @cindex @option{-gnatwe} (@command{gcc}) @cindex Warnings, treat as error -This switch causes warning messages to be treated as errors. +This switch causes warning messages and style check messages to be +treated as errors. The warning string still appears, but the warning messages are counted -as errors, and prevent the generation of an object file. +as errors, and prevent the generation of an object file. Note that this +is the only -gnatw switch that affects the handling of style check messages. @item -gnatw.e @emph{Activate every optional warning} @@ -5254,6 +5259,22 @@ Note that @option{-gnatwa} does not affect the setting of this warning option. @cindex @option{-gnatwH} (@command{gcc}) This switch suppresses warnings on hiding declarations. +@item -gnatw.h +@emph{Activate warnings on holes/gaps in records.} +@cindex @option{-gnatw.h} (@command{gcc}) +@cindex Record Representation (gaps) +This switch activates warnings on component clauses in record +representation clauses that leave holes (gaps) in the record layout. +If this warning option is active, then record representation clauses +should specify a contiguous layout, adding unused fill fields if needed. +Note that @option{-gnatwa} does not affect the setting of this warning option. + +@item -gnatw.H +@emph{Suppress warnings on holes/gaps in records.} +@cindex @option{-gnatw.H} (@command{gcc}) +This switch suppresses warnings on component clauses in record +representation clauses that leave holes (haps) in the record layout. + @item -gnatwi @emph{Activate warnings on implementation units.} @cindex @option{-gnatwi} (@command{gcc}) @@ -5558,7 +5579,27 @@ This switch completely suppresses the output of all warning messages from the GNAT front end. Note that it does not suppress warnings from the @command{gcc} back end. To suppress these back end warnings as well, use the switch @option{-w} -in addition to @option{-gnatws}. +in addition to @option{-gnatws}. Also this switch has no effect on the +handling of style check messages. + +@item -gnatw.s +@emph{Activate warnings on overridden size clauses.} +@cindex @option{-gnatw.s} (@command{gcc}) +@cindex Record Representation (component sizes) +This switch activates warnings on component clauses in record +representation clauses where the length given overrides that +specified by an explicit size clause for the component type. A +warning is similarly given in the array case if a specified +component size overrides an explicit size clause for the array +component type. +Note that @option{-gnatwa} does not affect the setting of this warning option. + +@item -gnatw.S +@emph{Suppress warnings on overriddebn size clauses.} +@cindex @option{-gnatw.S} (@command{gcc}) +This switch suppresses warnings on component clauses in record +representation clauses that override size clauses, and similar +warnings when an array component size overrides a size clause. @item -gnatwt @emph{Activate warnings for tracking of deleted conditional code.} @@ -5605,6 +5646,24 @@ This switch suppresses warnings for unused entities and packages. It also turns off warnings on unreferenced formals (and thus includes the effect of @option{-gnatwF}). +@item -gnatw.u +@emph{Activate warnings on unordered enumeration types.} +@cindex @option{-gnatw.u} (@command{gcc}) +This switch causes enumeration types to be considered as conceptually +unordered, unless an explicit pragma @code{Ordered} is given for the type. +The effect is to generate warnings in clients that use explicit comparisons +or subranges, since these constructs both treat objects of the type as +ordered. (A @emph{client} is defined as a unit that is other than the unit in +which the type is declared, or its body or subunits.) Please refer to +the description of pragma @code{Ordered} in the +@cite{@value{EDITION} Reference Manual} for further details. + +@item -gnatw.U +@emph{Deactivate warnings on unordered enumeration types.} +@cindex @option{-gnatw.U} (@command{gcc}) +This switch causes all enumeration types to be considered as ordered, so +that no warnings are given for comparisons or subranges for any type. + @item -gnatwv @emph{Activate warnings on unassigned variables.} @cindex @option{-gnatwv} (@command{gcc}) @@ -6117,8 +6176,21 @@ causes the compiler to enforce specified style rules. A limited set of style rules has been used in writing the GNAT sources themselves. This switch allows user programs to activate all or some of these checks. If the source program fails a -specified style check, an appropriate warning message is given, preceded by -the character sequence ``(style)''. +specified style check, an appropriate message is given, preceded by +the character sequence ``(style)''. This message does not prevent +successful compilation (unless the @option{-gnatwe} switch is used). + +Note that this is by no means intended to be a general facility for +checking arbitrary coding standards. It is simply an embedding of the +style rules we have chosen for the GNAT sources. If you are starting +a project which does not have established style standards, you may +find it useful to adopt the entire set of GNAT coding standards, or +some subset of them. If you already have an established set of coding +standards, then it may be that selected style checking options do +indeed correspond to choices you have made, but for general checking +of an existing set of coding rules, you should look to the gnatcheck +tool, which is designed for that purpose. + @ifset vms @code{(option,option,@dots{})} is a sequence of keywords @end ifset @@ -6183,8 +6255,8 @@ Comments that follow other tokens on a line must have at least one blank following the ``@code{--}'' at the start of the comment. @item -Full line comments must have two blanks following the ``@code{--}'' that -starts the comment, with the following exceptions. +Full line comments must have at least two blanks following the +``@code{--}'' that starts the comment, with the following exceptions. @item A line consisting only of the ``@code{--}'' characters, possibly preceded @@ -6608,6 +6680,16 @@ year). The compiler will generate code based on the assumption that the condition being checked is true, which can result in disaster if that assumption is wrong. +The @option{-gnatp} switch has no effect if a subsequent +@option{-gnat-p} switch appears. + +@item -gnat-p +@cindex @option{-gnat-p} (@command{gcc}) +@cindex Suppressing checks +@cindex Checks, suppressing +@findex Suppress +This switch cancels the effect of a previous @option{gnatp} switch. + @item -gnato @cindex @option{-gnato} (@command{gcc}) @cindex Overflow checks @@ -6881,27 +6963,60 @@ uses of the new Ada 2005 features will cause error messages or warnings. This switch also can be used to cancel the effect of a previous -@option{-gnat83} or @option{-gnat05} switch earlier in the command line. +@option{-gnat83}, @option{-gnat05/2005}, or @option{-gnat12/2012} +switch earlier in the command line. -@item -gnat05 (Ada 2005 mode) +@item -gnat05 or -gnat2005 (Ada 2005 mode) @cindex @option{-gnat05} (@command{gcc}) +@cindex @option{-gnat2005} (@command{gcc}) @cindex Ada 2005 mode @noindent This switch directs the compiler to implement the Ada 2005 version of the -language. +language, as documented in the official Ada standards document. Since Ada 2005 is almost completely upwards compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs may generally be compiled using this switch (see the description of the @option{-gnat83} and @option{-gnat95} switches for further information). +Note that even though Ada 2005 is the current official version of the +language, GNAT still compiles in Ada 95 mode by default, so if you are +using Ada 2005 features in your program, you must use this switch (or +the equivalent Ada_05 or Ada_2005 configuration pragmas). + +@item -gnat12 or -gnat2012 (Ada 2012 mode) +@cindex @option{-gnat12} (@command{gcc}) +@cindex @option{-gnat2012} (@command{gcc}) +@cindex Ada 2012 mode + +@noindent +This switch directs the compiler to implement the Ada 2012 version of the +language. +Since Ada 2012 is almost completely upwards +compatible with Ada 2005 (and thus also with Ada 83, and Ada 95), +Ada 83 and Ada 95 programs +may generally be compiled using this switch (see the description of the +@option{-gnat83}, @option{-gnat95}, and @option{-gnat05/2005} switches +for further information). + For information about the approved ``Ada Issues'' that have been incorporated -into Ada 2005, see @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs}. -Included with GNAT releases is a file @file{features-ada0y} that describes -the set of implemented Ada 2005 features. -@end table +into Ada 2012, see @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs}. +Included with GNAT releases is a file @file{features-ada12} that describes +the set of implemented Ada 2012 features. + +@item -gnatX (Enable GNAT Extensions) +@cindex @option{-gnatX} (@command{gcc}) +@cindex Ada language extensions +@cindex GNAT extensions + +@noindent +This switch directs the compiler to implement the latest version of the +language (currently Ada 2012) and also to enable certain GNAT implementation +extensions that are not part of any Ada standard. For a full list of these +extensions, see the GNAT reference manual. +@end table @node Character Set Control @subsection Character Set Control @@ -7187,7 +7302,9 @@ Shows the storage pool associated with a @code{free} statement. Used to list an equivalent declaration for an internally generated type that is referenced elsewhere in the listing. -@item freeze @var{type-name} @ovar{actions} +@c @item freeze @var{type-name} @ovar{actions} +@c Expanding @ovar macro inline (explanation in macro def comments) +@item freeze @var{type-name} @r{[}@var{actions}@r{]} Shows the point at which @var{type-name} is frozen, with possible associated actions to be performed at the freeze point. @@ -7886,12 +8003,14 @@ to be read by the @command{gnatlink} utility used to link the Ada application. The form of the @code{gnatbind} command is @smallexample -$ gnatbind @ovar{switches} @var{mainprog}@r{[}.ali@r{]} @ovar{switches} +@c $ gnatbind @ovar{switches} @var{mainprog}@r{[}.ali@r{]} @ovar{switches} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatbind @r{[}@var{switches}@r{]} @var{mainprog}@r{[}.ali@r{]} @r{[}@var{switches}@r{]} @end smallexample @noindent where @file{@var{mainprog}.adb} is the Ada file containing the main program -unit body. If no switches are specified, @code{gnatbind} constructs an Ada +unit body. @code{gnatbind} constructs an Ada package in two files whose names are @file{b~@var{mainprog}.ads}, and @file{b~@var{mainprog}.adb}. For example, if given the @@ -7962,14 +8081,6 @@ the generated main program. It can also be debugged just like any other Ada code provided the @option{^-g^/DEBUG^} switch is used for @command{gnatbind} and @command{gnatlink}. -However for some purposes it may be convenient to generate the main -program in C rather than Ada. This may for example be helpful when you -are generating a mixed language program with the main program in C. The -GNAT compiler itself is an example. -The use of the @option{^-C^/BIND_FILE=C^} switch -for both @code{gnatbind} and @command{gnatlink} will cause the program to -be generated in C (and compiled using the gnu C compiler). - @node Switches for gnatbind @section Switches for @command{gnatbind} @@ -7982,6 +8093,7 @@ be presented in subsequent sections. * Binder Error Message Control:: * Elaboration Control:: * Output Control:: +* Dynamic Allocation Control:: * Binding with Non-Ada Main Programs:: * Binding Programs with No Main Subprogram:: @end menu @@ -8013,9 +8125,9 @@ Specify directory to be searched for ALI files. @cindex @option{^-aI^/SOURCE_SEARCH^} (@command{gnatbind}) Specify directory to be searched for source file. -@item ^-A^/BIND_FILE=ADA^ -@cindex @option{^-A^/BIND_FILE=ADA^} (@command{gnatbind}) -Generate binder program in Ada (default) +@item ^-A^/ALI_LIST^@r{[=}@var{filename}@r{]} +@cindex @option{^-A^/ALI_LIST^} (@command{gnatbind}) +Output ALI list (to standard output or to the named file). @item ^-b^/REPORT_ERRORS=BRIEF^ @cindex @option{^-b^/REPORT_ERRORS=BRIEF^} (@command{gnatbind}) @@ -8025,10 +8137,6 @@ Generate brief messages to @file{stderr} even if verbose mode set. @cindex @option{^-c^/NOOUTPUT^} (@command{gnatbind}) Check only, no generation of binder output file. -@item ^-C^/BIND_FILE=C^ -@cindex @option{^-C^/BIND_FILE=C^} (@command{gnatbind}) -Generate binder program in C - @item ^-d^/DEFAULT_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]} @cindex @option{^-d^/DEFAULT_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]}} (@command{gnatbind}) This switch can be used to change the default task stack size value @@ -8071,7 +8179,6 @@ Output complete list of elaboration-order dependencies. @item ^-E^/STORE_TRACEBACKS^ @cindex @option{^-E^/STORE_TRACEBACKS^} (@command{gnatbind}) Store tracebacks in exception occurrences when the target supports it. -This is the default with the zero cost exception mechanism. @ignore @c The following may get moved to an appendix This option is currently supported on the following targets: @@ -8098,6 +8205,17 @@ flag checks are generated. @cindex @option{^-h^/HELP^} (@command{gnatbind}) Output usage (help) information +@item ^-H32^/32_MALLOC^ +@cindex @option{^-H32^/32_MALLOC^} (@command{gnatbind}) +Use 32-bit allocations for @code{__gnat_malloc} (and thus for access types). +For further details see @ref{Dynamic Allocation Control}. + +@item ^-H64^/64_MALLOC^ +@cindex @option{^-H32^/32_MALLOC^} (@command{gnatbind}) +Use 64-bit allocations for @code{__gnat_malloc} (and thus for access types). +@cindex @code{__gnat_malloc} +For further details see @ref{Dynamic Allocation Control}. + @item ^-I^/SEARCH^ @cindex @option{^-I^/SEARCH^} (@command{gnatbind}) Specify directory to be searched for source and ALI files. @@ -8173,9 +8291,9 @@ Name the output file @var{file} (default is @file{b~@var{xxx}.adb}). Note that if this option is used, then linking must be done manually, gnatlink cannot be used. -@item ^-O^/OBJECT_LIST^ +@item ^-O^/OBJECT_LIST^@r{[=}@var{filename}@r{]} @cindex @option{^-O^/OBJECT_LIST^} (@command{gnatbind}) -Output object list. +Output object list (to standard output or to the named file). @item ^-p^/PESSIMISTIC_ELABORATION^ @cindex @option{^-p^/PESSIMISTIC_ELABORATION^} (@command{gnatbind}) @@ -8474,24 +8592,11 @@ generated by the binder. @table @option @c !sort! -@item ^-A^/BIND_FILE=ADA^ -@cindex @option{^-A^/BIND_FILE=ADA^} (@code{gnatbind}) -Generate binder program in Ada (default). The binder program is named -@file{b~@var{mainprog}.adb} by default. This can be changed with -@option{^-o^/OUTPUT^} @code{gnatbind} option. - @item ^-c^/NOOUTPUT^ @cindex @option{^-c^/NOOUTPUT^} (@code{gnatbind}) Check only. Do not generate the binder output file. In this mode the binder performs all error checks but does not generate an output file. -@item ^-C^/BIND_FILE=C^ -@cindex @option{^-C^/BIND_FILE=C^} (@code{gnatbind}) -Generate binder program in C. The binder program is named -@file{b_@var{mainprog}.c}. -This can be changed with @option{^-o^/OUTPUT^} @code{gnatbind} -option. - @item ^-e^/ELABORATION_DEPENDENCIES^ @cindex @option{^-e^/ELABORATION_DEPENDENCIES^} (@code{gnatbind}) Output complete list of elaboration-order dependencies, showing the @@ -8526,8 +8631,7 @@ directory names for the run-time units depend on the system configuration. @cindex @option{^-o^/OUTPUT^} (@code{gnatbind}) Set name of output file to @var{file} instead of the normal @file{b~@var{mainprog}.adb} default. Note that @var{file} denote the Ada -binder generated body filename. In C mode you would normally give -@var{file} an extension of @file{.c} because it will be a C source program. +binder generated body filename. Note that if this option is used, then linking must be done manually. It is not possible to use gnatlink in this case, since it cannot locate the binder file. @@ -8540,6 +8644,35 @@ be used to improve code generation in some cases. @end table +@node Dynamic Allocation Control +@subsection Dynamic Allocation Control + +@noindent +The heap control switches -- @option{-H32} and @option{-H64} -- +determine whether dynamic allocation uses 32-bit or 64-bit memory. +They only affect compiler-generated allocations via @code{__gnat_malloc}; +explicit calls to @code{malloc} and related functions from the C +run-time library are unaffected. + +@table @option +@item -H32 +Allocate memory on 32-bit heap + +@item -H64 +Allocate memory on 64-bit heap. This is the default +unless explicitly overridden by a @code{'Size} clause on the access type. +@end table + +@ifset vms +@noindent +See also @ref{Access types and 32/64-bit allocation}. +@end ifset +@ifclear vms +@noindent +These switches are only effective on VMS platforms. +@end ifclear + + @node Binding with Non-Ada Main Programs @subsection Binding with Non-Ada Main Programs @@ -8601,9 +8734,7 @@ more quite separate groups of Ada units. The binder takes the name of its output file from the last specified ALI file, unless overridden by the use of the @option{^-o file^/OUTPUT=file^}. @cindex @option{^-o^/OUTPUT^} (@command{gnatbind}) -The output is an Ada unit in source form that can -be compiled with GNAT unless the -C switch is used in which case the -output is a C source file, which must be compiled using the C compiler. +The output is an Ada unit in source form that can be compiled with GNAT. This compilation occurs automatically as part of the @command{gnatlink} processing. @@ -8800,39 +8931,8 @@ The main program @code{Hello} (source program in @file{hello.adb}) is bound using the standard switch settings. The generated main program is @file{mainprog.adb} with the associated spec in @file{mainprog.ads}. Note that you must specify the body here not the -spec, in the case where the output is in Ada. Note that if this option -is used, then linking must be done manually, since gnatlink will not -be able to find the generated file. - -@ifclear vms -@item gnatbind main -C -o mainprog.c -x -@end ifclear -@ifset vms -@item gnatbind MAIN.ALI /BIND_FILE=C /OUTPUT=Mainprog.C /READ_SOURCES=NONE -@end ifset -The main program @code{Main} (source program in -@file{main.adb}) is bound, excluding source files from the -consistency checking, generating -the file @file{mainprog.c}. - -@ifclear vms -@item gnatbind -x main_program -C -o mainprog.c -This command is exactly the same as the previous example. Switches may -appear anywhere in the command line, and single letter switches may be -combined into a single switch. -@end ifclear - -@ifclear vms -@item gnatbind -n math dbase -C -o ada-control.c -@end ifclear -@ifset vms -@item gnatbind /NOMAIN math dbase /BIND_FILE=C /OUTPUT=ada-control.c -@end ifset -The main program is in a language other than Ada, but calls to -subprograms in packages @code{Math} and @code{Dbase} appear. This call -to @code{gnatbind} generates the file @file{ada-control.c} containing -the @code{adainit} and @code{adafinal} routines to be called before and -after accessing the Ada units. +spec. Note that if this option is used, then linking must be done manually, +since gnatlink will not be able to find the generated file. @end table @c ------------------------------------ @@ -8865,8 +8965,12 @@ driver (see @ref{The GNAT Driver and Project Files}). The form of the @command{gnatlink} command is @smallexample -$ gnatlink @ovar{switches} @var{mainprog}@r{[}.ali@r{]} - @ovar{non-Ada objects} @ovar{linker options} +@c $ gnatlink @ovar{switches} @var{mainprog}@r{[}.ali@r{]} +@c @ovar{non-Ada objects} @ovar{linker options} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatlink @r{[}@var{switches}@r{]} @var{mainprog}@r{[}.ali@r{]} + @r{[}@var{non-Ada objects}@r{]} @r{[}@var{linker options}@r{]} + @end smallexample @noindent @@ -8947,17 +9051,6 @@ Display Copyright and version, then exit disregarding all other options. If @option{--version} was not used, display usage, then exit disregarding all other options. -@item ^-A^/BIND_FILE=ADA^ -@cindex @option{^-A^/BIND_FILE=ADA^} (@command{gnatlink}) -The binder has generated code in Ada. This is the default. - -@item ^-C^/BIND_FILE=C^ -@cindex @option{^-C^/BIND_FILE=C^} (@command{gnatlink}) -If instead of generating a file in Ada, the binder has generated one in -C, then the linker needs to know about it. Use this switch to signal -to @command{gnatlink} that the binder has generated C code rather than -Ada code. - @item ^-f^/FORCE_OBJECT_FILE_LIST^ @cindex Command line length @cindex @option{^-f^/FORCE_OBJECT_FILE_LIST^} (@command{gnatlink}) @@ -9144,8 +9237,11 @@ dependencies, they will always be tracked exactly correctly by The usual form of the @command{gnatmake} command is @smallexample -$ gnatmake @ovar{switches} @var{file_name} - @ovar{file_names} @ovar{mode_switches} +@c $ gnatmake @ovar{switches} @var{file_name} +@c @ovar{file_names} @ovar{mode_switches} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatmake @r{[}@var{switches}@r{]} @var{file_name} + @r{[}@var{file_names}@r{]} @r{[}@var{mode_switches}@r{]} @end smallexample @noindent @@ -9233,6 +9329,30 @@ itself must not include any embedded spaces. @end ifclear +@item ^--subdirs^/SUBDIRS^=subdir +Actual object directory of each project file is the subdirectory subdir of the +object directory specified or defaulted in the project file. + +@item ^--single-compile-per-obj-dir^/SINGLE_COMPILE_PER_OBJ_DIR^ +Disallow simultaneous compilations in the same object directory when +project files are used. + +@item ^--unchecked-shared-lib-imports^/UNCHECKED_SHARED_LIB_IMPORTS^ +By default, shared library projects are not allowed to import static library +projects. When this switch is used on the command line, this restriction is +relaxed. + +@ifclear vms +@item --create-map-file +When linking an executable, create a map file. The name of the map file +has the same name as the executable with extension ".map". + +@item --create-map-file=mapfile +When linking an executable, create a map file. The name of the map file is +"mapfile". + +@end ifclear + @item ^-a^/ALL_FILES^ @cindex @option{^-a^/ALL_FILES^} (@command{gnatmake}) Consider all files in the make process, even the GNAT internal system @@ -10088,12 +10208,12 @@ generates highly optimized code and has the slowest compilation time. @item ^-O3^/OPTIMIZE=INLINING^ -Full optimization as in @option{-O2}, -and also attempts automatic inlining of small -subprograms within a unit (@pxref{Inlining of Subprograms}). +Full optimization as in @option{-O2}; +also uses more aggressive automatic inlining of subprograms within a unit +(@pxref{Inlining of Subprograms}) and attemps to vectorize loops. @item ^-Os^/OPTIMIZE=SPACE^ -Optimize space usage of resulting program. +Optimize space usage (code and data) of resulting program. @end table @noindent @@ -10122,7 +10242,7 @@ levels. Note regarding the use of @option{-O3}: The use of this optimization level is generally discouraged with GNAT, since it often results in larger -executables which run more slowly. See further discussion of this point +executables which may run more slowly. See further discussion of this point in @ref{Inlining of Subprograms}. @node Debugging Optimized Code @@ -10272,9 +10392,10 @@ subprograms. @item @cindex pragma Inline @findex Inline -Either @code{pragma Inline} applies to the subprogram, or it is local -to the unit and called once from within it, or it is small and automatic -inlining (optimization level @option{-O3}) is specified. +Either @code{pragma Inline} applies to the subprogram, or it is local to +the unit and called once from within it, or it is small and optimization +level @option{-O2} is specified, or automatic inlining (optimization level +@option{-O3}) is specified. @end itemize @noindent @@ -10358,7 +10479,11 @@ this switch is used to suppress the resulting inlining actions. @cindex @option{-fno-inline-functions} (@command{gcc}) Note: The @option{-fno-inline-functions} switch can be used to prevent -automatic inlining of small subprograms if @option{-O3} is used. +automatic inlining of subprograms if @option{-O3} is used. + +@cindex @option{-fno-inline-small-functions} (@command{gcc}) +Note: The @option{-fno-inline-small-functions} switch can be used to prevent +automatic inlining of small subprograms if @option{-O2} is used. @cindex @option{-fno-inline-functions-called-once} (@command{gcc}) Note: The @option{-fno-inline-functions-called-once} switch @@ -10670,6 +10795,7 @@ program. @menu * About gnatelim:: * Running gnatelim:: +* Processing Precompiled Libraries:: * Correcting the List of Eliminate Pragmas:: * Making Your Executables Smaller:: * Summary of the gnatelim Usage Cycle:: @@ -10693,20 +10819,24 @@ because the compiler will not generate the code for 'eliminated' subprograms. @xref{Pragma Eliminate,,, gnat_rm, GNAT Reference Manual}, for more information about this pragma. -@code{gnatelim} needs as its input data the name of the main subprogram -and a bind file for a main subprogram. +@code{gnatelim} needs as its input data the name of the main subprogram. -To create a bind file for @code{gnatelim}, run @code{gnatbind} for -the main subprogram. @code{gnatelim} can work with both Ada and C -bind files; when both are present, it uses the Ada bind file. -The following commands will build the program and create the bind file: +If a set of source files is specified as @code{gnatelim} arguments, it +treats these files as a complete set of sources making up a program to +analyse, and analyses only these sources. + +After a full successful build of the main subprogram @code{gnatelim} can be +called without specifying sources to analyse, in this case it computes +the source closure of the main unit from the @file{ALI} files. + +The following command will create the set of @file{ALI} files needed for +@code{gnatelim}: @smallexample $ gnatmake ^-c Main_Prog^/ACTIONS=COMPILE MAIN_PROG^ -$ gnatbind main_prog @end smallexample -Note that @code{gnatelim} needs neither object nor ALI files. +Note that @code{gnatelim} does not need object files. @node Running gnatelim @subsection Running @code{gnatelim} @@ -10715,23 +10845,66 @@ Note that @code{gnatelim} needs neither object nor ALI files. @code{gnatelim} has the following command-line interface: @smallexample -$ gnatelim @ovar{options} name +$ gnatelim [@var{switches}] ^-main^?MAIN^=@var{main_unit_name} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]} @end smallexample @noindent -@code{name} should be a name of a source file that contains the main subprogram -of a program (partition). +@var{main_unit_name} should be a name of a source file that contains the main +subprogram of a program (partition). + +Each @var{filename} is the name (including the extension) of a source +file to process. ``Wildcards'' are allowed, and +the file name may contain path information. + +@samp{@var{gcc_switches}} is a list of switches for +@command{gcc}. They will be passed on to all compiler invocations made by +@command{gnatelim} to generate the ASIS trees. Here you can provide +@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path, +use the @option{-gnatec} switch to set the configuration file, +use the @option{-gnat05} switch if sources should be compiled in +Ada 2005 mode etc. @code{gnatelim} has the following switches: @table @option @c !sort! +@item ^-files^/FILES^=@var{filename} +@cindex @option{^-files^/FILES^} (@code{gnatelim}) +Take the argument source files from the specified file. This file should be an +ordinary text file containing file names separated by spaces or +line breaks. You can use this switch more than once in the same call to +@command{gnatelim}. You also can combine this switch with +an explicit list of files. + +@item ^-log^/LOG^ +@cindex @option{^-log^/LOG^} (@command{gnatelim}) +Duplicate all the output sent to @file{stderr} into a log file. The log file +is named @file{gnatelim.log} and is located in the current directory. + +@item ^-log^/LOGFILE^=@var{filename} +@cindex @option{^-log^/LOGFILE^} (@command{gnatelim}) +Duplicate all the output sent to @file{stderr} into a specified log file. + +@cindex @option{^--no-elim-dispatch^/NO_DISPATCH^} (@command{gnatelim}) +@item ^--no-elim-dispatch^/NO_DISPATCH^ +Do not generate pragmas for dispatching operations. + +@cindex @option{^-o^/OUTPUT^} (@command{gnatelim}) +@item ^-o^/OUTPUT^=@var{report_file} +Put @command{gnatelim} output into a specified file. If this file already exists, +it is overridden. If this switch is not used, @command{gnatelim} outputs its results +into @file{stderr} + @item ^-q^/QUIET^ @cindex @option{^-q^/QUIET^} (@command{gnatelim}) Quiet mode: by default @code{gnatelim} outputs to the standard error stream the number of program units left to be processed. This option turns this trace off. +@cindex @option{^-t^/TIME^} (@command{gnatelim}) +@item ^-t^/TIME^ +Print out execution time. + @item ^-v^/VERBOSE^ @cindex @option{^-v^/VERBOSE^} (@command{gnatelim}) Verbose mode: @code{gnatelim} version information is printed as Ada @@ -10739,67 +10912,24 @@ comments to the standard output stream. Also, in addition to the number of program units left @code{gnatelim} will output the name of the current unit being processed. -@item ^-a^/ALL^ -@cindex @option{^-a^/ALL^} (@command{gnatelim}) -Also look for subprograms from the GNAT run time that can be eliminated. Note -that when @file{gnat.adc} is produced using this switch, the entire program -must be recompiled with switch @option{^-a^/ALL_FILES^} to @command{gnatmake}. - -@item ^-I^/INCLUDE_DIRS=^@var{dir} -@cindex @option{^-I^/INCLUDE_DIRS^} (@command{gnatelim}) -When looking for source files also look in directory @var{dir}. Specifying -@option{^-I-^/INCLUDE_DIRS=-^} instructs @code{gnatelim} not to look for -sources in the current directory. - -@item ^-b^/BIND_FILE=^@var{bind_file} -@cindex @option{^-b^/BIND_FILE^} (@command{gnatelim}) -Specifies @var{bind_file} as the bind file to process. If not set, the name -of the bind file is computed from the full expanded Ada name -of a main subprogram. - -@item ^-C^/CONFIG_FILE=^@var{config_file} -@cindex @option{^-C^/CONFIG_FILE^} (@command{gnatelim}) -Specifies a file @var{config_file} that contains configuration pragmas. The -file must be specified with full path. - -@item ^--GCC^/COMPILER^=@var{compiler_name} -@cindex @option{^-GCC^/COMPILER^} (@command{gnatelim}) -Instructs @code{gnatelim} to use specific @command{gcc} compiler instead of one -available on the path. - -@item ^--GNATMAKE^/GNATMAKE^=@var{gnatmake_name} -@cindex @option{^--GNATMAKE^/GNATMAKE^} (@command{gnatelim}) -Instructs @code{gnatelim} to use specific @command{gnatmake} instead of one -available on the path. +@item ^-wq^/WARNINGS=QUIET^ +@cindex @option{^-wq^/WARNINGS=QUIET^} (@command{gnatelim}) +Quet warning mode - some warnings are suppressed. In particular warnings that +indicate that the analysed set of sources is incomplete to make up a +partition and that some subprogram bodies are missing are not generated. @end table -@noindent -@code{gnatelim} sends its output to the standard output stream, and all the -tracing and debug information is sent to the standard error stream. -In order to produce a proper GNAT configuration file -@file{gnat.adc}, redirection must be used: - -@smallexample -@ifset vms -$ PIPE GNAT ELIM MAIN_PROG.ADB > GNAT.ADC -@end ifset -@ifclear vms -$ gnatelim main_prog.adb > gnat.adc -@end ifclear -@end smallexample +@node Processing Precompiled Libraries +@subsection Processing Precompiled Libraries -@ifclear vms @noindent -or - -@smallexample -$ gnatelim main_prog.adb >> gnat.adc -@end smallexample - -@noindent -in order to append the @code{gnatelim} output to the existing contents of -@file{gnat.adc}. -@end ifclear +If some program uses a precompiled Ada library, it can be processed by +@code{gnatelim} in a usual way. @code{gnatelim} will newer generate an +Eliminate pragma for a subprogram if the body of this subprogram has not +been analysed, this is a typical case for subprograms from precompiled +libraries. Switch @option{^-wq^/WARNINGS=QUIET^} may be used to suppress +warnings about missing source files and non-analyzed subprogram bodies +that can be generated when processing precompiled Ada libraries. @node Correcting the List of Eliminate Pragmas @subsection Correcting the List of Eliminate Pragmas @@ -10810,22 +10940,23 @@ subprograms that are actually called in the program. In this case, the compiler will generate an error message of the form: @smallexample -file.adb:106:07: cannot call eliminated subprogram "My_Prog" +main.adb:4:08: cannot reference subprogram "P" eliminated at elim.out:5 @end smallexample @noindent You will need to manually remove the wrong @code{Eliminate} pragmas from -the @file{gnat.adc} file. You should recompile your program -from scratch after that, because you need a consistent @file{gnat.adc} file -during the entire compilation. +the configuration file indicated in the error message. You should recompile +your program from scratch after that, because you need a consistent +configuration file(s) during the entire compilation. @node Making Your Executables Smaller @subsection Making Your Executables Smaller @noindent In order to get a smaller executable for your program you now have to -recompile the program completely with the new @file{gnat.adc} file -created by @code{gnatelim} in your current directory: +recompile the program completely with the configuration file containing +pragmas Eliminate generated by gnatelim. If these pragmas are placed in +@file{gnat.adc} file located in your current directory, just do: @smallexample $ gnatmake ^-f main_prog^/FORCE_COMPILE MAIN_PROG^ @@ -10839,10 +10970,10 @@ with the set of pragmas @code{Eliminate} that you have obtained with Be aware that the set of @code{Eliminate} pragmas is specific to each program. It is not recommended to merge sets of @code{Eliminate} -pragmas created for different programs in one @file{gnat.adc} file. +pragmas created for different programs in one configuration file. @node Summary of the gnatelim Usage Cycle -@subsection Summary of the gnatelim Usage Cycle +@subsection Summary of the @code{gnatelim} Usage Cycle @noindent Here is a quick summary of the steps to be taken in order to reduce @@ -10852,15 +10983,16 @@ to produce the debugging information, to set search path, etc. @enumerate @item -Produce a bind file +Create a complete set of @file{ALI} files (if the program has not been +built already) @smallexample $ gnatmake ^-c main_prog^/ACTIONS=COMPILE MAIN_PROG^ -$ gnatbind main_prog @end smallexample @item -Generate a list of @code{Eliminate} pragmas +Generate a list of @code{Eliminate} pragmas in default configuration file +@file{gnat.adc} in the current directory @smallexample @ifset vms $ PIPE GNAT ELIM MAIN_PROG > GNAT.ADC @@ -11119,8 +11251,11 @@ in which GNAT processes the ACVC tests. The @code{gnatchop} command has the form: @smallexample +@c $ gnatchop switches @var{file name} @r{[}@var{file name} @dots{}@r{]} +@c @ovar{directory} +@c Expanding @ovar macro inline (explanation in macro def comments) $ gnatchop switches @var{file name} @r{[}@var{file name} @dots{}@r{]} - @ovar{directory} + @r{[}@var{directory}@r{]} @end smallexample @noindent @@ -11376,6 +11511,8 @@ recognized by GNAT: Ada_95 Ada_05 Ada_2005 + Ada_12 + Ada_2012 Assertion_Policy Assume_No_Invalid_Values C_Pass_By_Copy @@ -11419,6 +11556,7 @@ recognized by GNAT: Restrictions Restrictions_Warnings Reviewable + Short_Circuit_And_Or Source_File_Name Source_File_Name_Project Style_Checks @@ -11546,8 +11684,11 @@ set of files. The usual form of the @code{gnatname} command is @smallexample -$ gnatname @ovar{switches} @var{naming_pattern} @ovar{naming_patterns} - @r{[}--and @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}@r{]} +@c $ gnatname @ovar{switches} @var{naming_pattern} @ovar{naming_patterns} +@c @r{[}--and @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}@r{]} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatname @r{[}@var{switches}@r{]} @var{naming_pattern} @r{[}@var{naming_patterns}@r{]} + @r{[}--and @r{[}@var{switches}@r{]} @var{naming_pattern} @r{[}@var{naming_patterns}@r{]}@r{]} @end smallexample @noindent @@ -11563,7 +11704,8 @@ regular files. @noindent One or several Naming Patterns may be given as arguments to @code{gnatname}. -Each Naming Pattern is enclosed between double quotes. +Each Naming Pattern is enclosed between double quotes (or single +quotes on Windows). A Naming Pattern is a regular expression similar to the wildcard patterns used in file names by the Unix shells or the DOS prompt. @@ -11762,3599 +11904,58 @@ are used in this example. @c ***************************************** @c * G N A T P r o j e c t M a n a g e r * @c ***************************************** -@node GNAT Project Manager -@chapter GNAT Project Manager - -@menu -* Introduction:: -* Examples of Project Files:: -* Project File Syntax:: -* Objects and Sources in Project Files:: -* Importing Projects:: -* Project Extension:: -* Project Hierarchy Extension:: -* External References in Project Files:: -* Packages in Project Files:: -* Variables from Imported Projects:: -* Naming Schemes:: -* Library Projects:: -* Stand-alone Library Projects:: -* Switches Related to Project Files:: -* Tools Supporting Project Files:: -* An Extended Example:: -* Project File Complete Syntax:: -@end menu - -@c **************** -@c * Introduction * -@c **************** - -@node Introduction -@section Introduction - -@noindent -This chapter describes GNAT's @emph{Project Manager}, a facility that allows -you to manage complex builds involving a number of source files, directories, -and compilation options for different system configurations. In particular, -project files allow you to specify: -@itemize @bullet -@item -The directory or set of directories containing the source files, and/or the -names of the specific source files themselves -@item -The directory in which the compiler's output -(@file{ALI} files, object files, tree files) is to be placed -@item -The directory in which the executable programs is to be placed -@item -^Switch^Switch^ settings for any of the project-enabled tools -(@command{gnatmake}, compiler, binder, linker, @code{gnatls}, @code{gnatxref}, -@code{gnatfind}); you can apply these settings either globally or to individual -compilation units. -@item -The source files containing the main subprogram(s) to be built -@item -The source programming language(s) (currently Ada and/or C) -@item -Source file naming conventions; you can specify these either globally or for -individual compilation units -@end itemize - -@menu -* Project Files:: -@end menu - -@node Project Files -@subsection Project Files - -@noindent -Project files are written in a syntax close to that of Ada, using familiar -notions such as packages, context clauses, declarations, default values, -assignments, and inheritance. Finally, project files can be built -hierarchically from other project files, simplifying complex system -integration and project reuse. - -A @dfn{project} is a specific set of values for various compilation properties. -The settings for a given project are described by means of -a @dfn{project file}, which is a text file written in an Ada-like syntax. -Property values in project files are either strings or lists of strings. -Properties that are not explicitly set receive default values. A project -file may interrogate the values of @dfn{external variables} (user-defined -command-line switches or environment variables), and it may specify property -settings conditionally, based on the value of such variables. - -In simple cases, a project's source files depend only on other source files -in the same project, or on the predefined libraries. (@emph{Dependence} is -used in -the Ada technical sense; as in one Ada unit @code{with}ing another.) However, -the Project Manager also allows more sophisticated arrangements, -where the source files in one project depend on source files in other -projects: -@itemize @bullet -@item -One project can @emph{import} other projects containing needed source files. -@item -You can organize GNAT projects in a hierarchy: a @emph{child} project -can extend a @emph{parent} project, inheriting the parent's source files and -optionally overriding any of them with alternative versions -@end itemize - -@noindent -More generally, the Project Manager lets you structure large development -efforts into hierarchical subsystems, where build decisions are delegated -to the subsystem level, and thus different compilation environments -(^switch^switch^ settings) used for different subsystems. - -The Project Manager is invoked through the -@option{^-P^/PROJECT_FILE=^@emph{projectfile}} -switch to @command{gnatmake} or to the @command{^gnat^GNAT^} front driver. -@ifclear vms -There may be zero, one or more spaces between @option{-P} and -@option{@emph{projectfile}}. -@end ifclear -If you want to define (on the command line) an external variable that is -queried by the project file, you must use the -@option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch. -The Project Manager parses and interprets the project file, and drives the -invoked tool based on the project settings. - -The Project Manager supports a wide range of development strategies, -for systems of all sizes. Here are some typical practices that are -easily handled: -@itemize @bullet -@item -Using a common set of source files, but generating object files in different -directories via different ^switch^switch^ settings -@item -Using a mostly-shared set of source files, but with different versions of -some unit or units -@end itemize - -@noindent -The destination of an executable can be controlled inside a project file -using the @option{^-o^-o^} -^switch^switch^. -In the absence of such a ^switch^switch^ either inside -the project file or on the command line, any executable files generated by -@command{gnatmake} are placed in the directory @code{Exec_Dir} specified -in the project file. If no @code{Exec_Dir} is specified, they will be placed -in the object directory of the project. - -You can use project files to achieve some of the effects of a source -versioning system (for example, defining separate projects for -the different sets of sources that comprise different releases) but the -Project Manager is independent of any source configuration management tools -that might be used by the developers. - -The next section introduces the main features of GNAT's project facility -through a sequence of examples; subsequent sections will present the syntax -and semantics in more detail. A more formal description of the project -facility appears in @ref{Project File Reference,,, gnat_rm, GNAT -Reference Manual}. - -@c ***************************** -@c * Examples of Project Files * -@c ***************************** - -@node Examples of Project Files -@section Examples of Project Files -@noindent -This section illustrates some of the typical uses of project files and -explains their basic structure and behavior. - -@menu -* Common Sources with Different ^Switches^Switches^ and Directories:: -* Using External Variables:: -* Importing Other Projects:: -* Extending a Project:: -@end menu - -@node Common Sources with Different ^Switches^Switches^ and Directories -@subsection Common Sources with Different ^Switches^Switches^ and Directories - -@menu -* Source Files:: -* Specifying the Object Directory:: -* Specifying the Exec Directory:: -* Project File Packages:: -* Specifying ^Switch^Switch^ Settings:: -* Main Subprograms:: -* Executable File Names:: -* Source File Naming Conventions:: -* Source Language(s):: -@end menu - -@noindent -Suppose that the Ada source files @file{pack.ads}, @file{pack.adb}, and -@file{proc.adb} are in the @file{/common} directory. The file -@file{proc.adb} contains an Ada main subprogram @code{Proc} that @code{with}s -package @code{Pack}. We want to compile these source files under two sets -of ^switches^switches^: -@itemize @bullet -@item -When debugging, we want to pass the @option{-g} switch to @command{gnatmake}, -and the @option{^-gnata^-gnata^}, -@option{^-gnato^-gnato^}, -and @option{^-gnatE^-gnatE^} switches to the -compiler; the compiler's output is to appear in @file{/common/debug} -@item -When preparing a release version, we want to pass the @option{^-O2^O2^} switch -to the compiler; the compiler's output is to appear in @file{/common/release} -@end itemize - -@noindent -The GNAT project files shown below, respectively @file{debug.gpr} and -@file{release.gpr} in the @file{/common} directory, achieve these effects. - -Schematically: -@smallexample -@group -^/common^[COMMON]^ - debug.gpr - release.gpr - pack.ads - pack.adb - proc.adb -@end group -@group -^/common/debug^[COMMON.DEBUG]^ - proc.ali, proc.o - pack.ali, pack.o -@end group -@group -^/common/release^[COMMON.RELEASE]^ - proc.ali, proc.o - pack.ali, pack.o -@end group -@end smallexample -Here are the corresponding project files: - -@smallexample @c projectfile -@group -project Debug is - for Object_Dir use "debug"; - for Main use ("proc"); - - package Builder is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-g^-g^"); - for Executable ("proc.adb") use "proc1"; - end Builder; -@end group - -@group - package Compiler is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("-fstack-check", - "^-gnata^-gnata^", - "^-gnato^-gnato^", - "^-gnatE^-gnatE^"); - end Compiler; -end Debug; -@end group -@end smallexample - -@smallexample @c projectfile -@group -project Release is - for Object_Dir use "release"; - for Exec_Dir use "."; - for Main use ("proc"); - - package Compiler is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-O2^-O2^"); - end Compiler; -end Release; -@end group -@end smallexample - -@noindent -The name of the project defined by @file{debug.gpr} is @code{"Debug"} (case -insensitive), and analogously the project defined by @file{release.gpr} is -@code{"Release"}. For consistency the file should have the same name as the -project, and the project file's extension should be @code{"gpr"}. These -conventions are not required, but a warning is issued if they are not followed. - -If the current directory is @file{^/temp^[TEMP]^}, then the command -@smallexample -gnatmake ^-P/common/debug.gpr^/PROJECT_FILE=[COMMON]DEBUG^ -@end smallexample - -@noindent -generates object and ALI files in @file{^/common/debug^[COMMON.DEBUG]^}, -as well as the @code{^proc1^PROC1.EXE^} executable, -using the ^switch^switch^ settings defined in the project file. - -Likewise, the command -@smallexample -gnatmake ^-P/common/release.gpr^/PROJECT_FILE=[COMMON]RELEASE^ -@end smallexample - -@noindent -generates object and ALI files in @file{^/common/release^[COMMON.RELEASE]^}, -and the @code{^proc^PROC.EXE^} -executable in @file{^/common^[COMMON]^}, -using the ^switch^switch^ settings from the project file. - -@node Source Files -@unnumberedsubsubsec Source Files - -@noindent -If a project file does not explicitly specify a set of source directories or -a set of source files, then by default the project's source files are the -Ada source files in the project file directory. Thus @file{pack.ads}, -@file{pack.adb}, and @file{proc.adb} are the source files for both projects. - -@node Specifying the Object Directory -@unnumberedsubsubsec Specifying the Object Directory - -@noindent -Several project properties are modeled by Ada-style @emph{attributes}; -a property is defined by supplying the equivalent of an Ada attribute -definition clause in the project file. -A project's object directory is another such a property; the corresponding -attribute is @code{Object_Dir}, and its value is also a string expression, -specified either as absolute or relative. In the later case, -it is relative to the project file directory. Thus the compiler's -output is directed to @file{^/common/debug^[COMMON.DEBUG]^} -(for the @code{Debug} project) -and to @file{^/common/release^[COMMON.RELEASE]^} -(for the @code{Release} project). -If @code{Object_Dir} is not specified, then the default is the project file -directory itself. - -@node Specifying the Exec Directory -@unnumberedsubsubsec Specifying the Exec Directory - -@noindent -A project's exec directory is another property; the corresponding -attribute is @code{Exec_Dir}, and its value is also a string expression, -either specified as relative or absolute. If @code{Exec_Dir} is not specified, -then the default is the object directory (which may also be the project file -directory if attribute @code{Object_Dir} is not specified). Thus the executable -is placed in @file{^/common/debug^[COMMON.DEBUG]^} -for the @code{Debug} project (attribute @code{Exec_Dir} not specified) -and in @file{^/common^[COMMON]^} for the @code{Release} project. - -@node Project File Packages -@unnumberedsubsubsec Project File Packages - -@noindent -A GNAT tool that is integrated with the Project Manager is modeled by a -corresponding package in the project file. In the example above, -The @code{Debug} project defines the packages @code{Builder} -(for @command{gnatmake}) and @code{Compiler}; -the @code{Release} project defines only the @code{Compiler} package. - -The Ada-like package syntax is not to be taken literally. Although packages in -project files bear a surface resemblance to packages in Ada source code, the -notation is simply a way to convey a grouping of properties for a named -entity. Indeed, the package names permitted in project files are restricted -to a predefined set, corresponding to the project-aware tools, and the contents -of packages are limited to a small set of constructs. -The packages in the example above contain attribute definitions. - -@node Specifying ^Switch^Switch^ Settings -@unnumberedsubsubsec Specifying ^Switch^Switch^ Settings - -@noindent -^Switch^Switch^ settings for a project-aware tool can be specified through -attributes in the package that corresponds to the tool. -The example above illustrates one of the relevant attributes, -@code{^Default_Switches^Default_Switches^}, which is defined in packages -in both project files. -Unlike simple attributes like @code{Source_Dirs}, -@code{^Default_Switches^Default_Switches^} is -known as an @emph{associative array}. When you define this attribute, you must -supply an ``index'' (a literal string), and the effect of the attribute -definition is to set the value of the array at the specified index. -For the @code{^Default_Switches^Default_Switches^} attribute, -the index is a programming language (in our case, Ada), -and the value specified (after @code{use}) must be a list -of string expressions. - -The attributes permitted in project files are restricted to a predefined set. -Some may appear at project level, others in packages. -For any attribute that is an associative array, the index must always be a -literal string, but the restrictions on this string (e.g., a file name or a -language name) depend on the individual attribute. -Also depending on the attribute, its specified value will need to be either a -string or a string list. - -In the @code{Debug} project, we set the switches for two tools, -@command{gnatmake} and the compiler, and thus we include the two corresponding -packages; each package defines the @code{^Default_Switches^Default_Switches^} -attribute with index @code{"Ada"}. -Note that the package corresponding to -@command{gnatmake} is named @code{Builder}. The @code{Release} project is -similar, but only includes the @code{Compiler} package. - -In project @code{Debug} above, the ^switches^switches^ starting with -@option{-gnat} that are specified in package @code{Compiler} -could have been placed in package @code{Builder}, since @command{gnatmake} -transmits all such ^switches^switches^ to the compiler. - -@node Main Subprograms -@unnumberedsubsubsec Main Subprograms - -@noindent -One of the specifiable properties of a project is a list of files that contain -main subprograms. This property is captured in the @code{Main} attribute, -whose value is a list of strings. If a project defines the @code{Main} -attribute, it is not necessary to identify the main subprogram(s) when -invoking @command{gnatmake} (@pxref{gnatmake and Project Files}). - -@node Executable File Names -@unnumberedsubsubsec Executable File Names - -@noindent -By default, the executable file name corresponding to a main source is -deduced from the main source file name. Through the attributes -@code{Executable} and @code{Executable_Suffix} of package @code{Builder}, -it is possible to change this default. -In project @code{Debug} above, the executable file name -for main source @file{^proc.adb^PROC.ADB^} is -@file{^proc1^PROC1.EXE^}. -Attribute @code{Executable_Suffix}, when specified, may change the suffix -of the executable files, when no attribute @code{Executable} applies: -its value replace the platform-specific executable suffix. -Attributes @code{Executable} and @code{Executable_Suffix} are the only ways to -specify a non-default executable file name when several mains are built at once -in a single @command{gnatmake} command. - -@node Source File Naming Conventions -@unnumberedsubsubsec Source File Naming Conventions - -@noindent -Since the project files above do not specify any source file naming -conventions, the GNAT defaults are used. The mechanism for defining source -file naming conventions -- a package named @code{Naming} -- -is described below (@pxref{Naming Schemes}). - -@node Source Language(s) -@unnumberedsubsubsec Source Language(s) - -@noindent -Since the project files do not specify a @code{Languages} attribute, by -default the GNAT tools assume that the language of the project file is Ada. -More generally, a project can comprise source files -in Ada, C, and/or other languages. - -@node Using External Variables -@subsection Using External Variables - -@noindent -Instead of supplying different project files for debug and release, we can -define a single project file that queries an external variable (set either -on the command line or via an ^environment variable^logical name^) in order to -conditionally define the appropriate settings. Again, assume that the -source files @file{pack.ads}, @file{pack.adb}, and @file{proc.adb} are -located in directory @file{^/common^[COMMON]^}. The following project file, -@file{build.gpr}, queries the external variable named @code{STYLE} and -defines an object directory and ^switch^switch^ settings based on whether -the value is @code{"deb"} (debug) or @code{"rel"} (release), and where -the default is @code{"deb"}. - -@smallexample @c projectfile -@group -project Build is - for Main use ("proc"); - - type Style_Type is ("deb", "rel"); - Style : Style_Type := external ("STYLE", "deb"); - - case Style is - when "deb" => - for Object_Dir use "debug"; - - when "rel" => - for Object_Dir use "release"; - for Exec_Dir use "."; - end case; -@end group - -@group - package Builder is - - case Style is - when "deb" => - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-g^-g^"); - for Executable ("proc") use "proc1"; - when others => - null; - end case; - - end Builder; -@end group - -@group - package Compiler is - - case Style is - when "deb" => - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-gnata^-gnata^", - "^-gnato^-gnato^", - "^-gnatE^-gnatE^"); - - when "rel" => - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-O2^-O2^"); - end case; - - end Compiler; - -end Build; -@end group -@end smallexample - -@noindent -@code{Style_Type} is an example of a @emph{string type}, which is the project -file analog of an Ada enumeration type but whose components are string literals -rather than identifiers. @code{Style} is declared as a variable of this type. - -The form @code{external("STYLE", "deb")} is known as an -@emph{external reference}; its first argument is the name of an -@emph{external variable}, and the second argument is a default value to be -used if the external variable doesn't exist. You can define an external -variable on the command line via the @option{^-X^/EXTERNAL_REFERENCE^} switch, -or you can use ^an environment variable^a logical name^ -as an external variable. - -Each @code{case} construct is expanded by the Project Manager based on the -value of @code{Style}. Thus the command -@ifclear vms -@smallexample -gnatmake -P/common/build.gpr -XSTYLE=deb -@end smallexample -@end ifclear - -@ifset vms -@smallexample -gnatmake /PROJECT_FILE=[COMMON]BUILD.GPR /EXTERNAL_REFERENCE=STYLE=deb -@end smallexample -@end ifset - -@noindent -is equivalent to the @command{gnatmake} invocation using the project file -@file{debug.gpr} in the earlier example. So is the command -@smallexample -gnatmake ^-P/common/build.gpr^/PROJECT_FILE=[COMMON]BUILD.GPR^ -@end smallexample - -@noindent -since @code{"deb"} is the default for @code{STYLE}. - -Analogously, - -@ifclear vms -@smallexample -gnatmake -P/common/build.gpr -XSTYLE=rel -@end smallexample -@end ifclear - -@ifset vms -@smallexample -GNAT MAKE /PROJECT_FILE=[COMMON]BUILD.GPR /EXTERNAL_REFERENCE=STYLE=rel -@end smallexample -@end ifset - -@noindent -is equivalent to the @command{gnatmake} invocation using the project file -@file{release.gpr} in the earlier example. - -@node Importing Other Projects -@subsection Importing Other Projects -@cindex @code{ADA_PROJECT_PATH} -@cindex @code{GPR_PROJECT_PATH} - -@noindent -A compilation unit in a source file in one project may depend on compilation -units in source files in other projects. To compile this unit under -control of a project file, the -dependent project must @emph{import} the projects containing the needed source -files. -This effect is obtained using syntax similar to an Ada @code{with} clause, -but where @code{with}ed entities are strings that denote project files. - -As an example, suppose that the two projects @code{GUI_Proj} and -@code{Comm_Proj} are defined in the project files @file{gui_proj.gpr} and -@file{comm_proj.gpr} in directories @file{^/gui^[GUI]^} -and @file{^/comm^[COMM]^}, respectively. -Suppose that the source files for @code{GUI_Proj} are -@file{gui.ads} and @file{gui.adb}, and that the source files for -@code{Comm_Proj} are @file{comm.ads} and @file{comm.adb}, where each set of -files is located in its respective project file directory. Schematically: - -@smallexample -@group -^/gui^[GUI]^ - gui_proj.gpr - gui.ads - gui.adb -@end group - -@group -^/comm^[COMM]^ - comm_proj.gpr - comm.ads - comm.adb -@end group -@end smallexample - -@noindent -We want to develop an application in directory @file{^/app^[APP]^} that -@code{with} the packages @code{GUI} and @code{Comm}, using the properties of -the corresponding project files (e.g.@: the ^switch^switch^ settings -and object directory). -Skeletal code for a main procedure might be something like the following: - -@smallexample @c ada -@group -with GUI, Comm; -procedure App_Main is - @dots{} -begin - @dots{} -end App_Main; -@end group -@end smallexample - -@noindent -Here is a project file, @file{app_proj.gpr}, that achieves the desired -effect: - -@smallexample @c projectfile -@group -with "/gui/gui_proj", "/comm/comm_proj"; -project App_Proj is - for Main use ("app_main"); -end App_Proj; -@end group -@end smallexample - -@noindent -Building an executable is achieved through the command: -@smallexample -gnatmake ^-P/app/app_proj^/PROJECT_FILE=[APP]APP_PROJ^ -@end smallexample -@noindent -which will generate the @code{^app_main^APP_MAIN.EXE^} executable -in the directory where @file{app_proj.gpr} resides. - -If an imported project file uses the standard extension (@code{^gpr^GPR^}) then -(as illustrated above) the @code{with} clause can omit the extension. - -Our example specified an absolute path for each imported project file. -Alternatively, the directory name of an imported object can be omitted -if either -@itemize @bullet -@item -The imported project file is in the same directory as the importing project -file, or -@item -You have defined one or two ^environment variables^logical names^ -that includes the directory containing -the needed project file. The syntax of @code{GPR_PROJECT_PATH} and -@code{ADA_PROJECT_PATH} is the same as -the syntax of @code{ADA_INCLUDE_PATH} and @code{ADA_OBJECTS_PATH}: a list of -directory names separated by colons (semicolons on Windows). -@end itemize - -@noindent -Thus, if we define @code{ADA_PROJECT_PATH} or @code{GPR_PROJECT_PATH} -to include @file{^/gui^[GUI]^} and -@file{^/comm^[COMM]^}, then our project file @file{app_proj.gpr} can be written -as follows: - -@smallexample @c projectfile -@group -with "gui_proj", "comm_proj"; -project App_Proj is - for Main use ("app_main"); -end App_Proj; -@end group -@end smallexample - -@noindent -Importing other projects can create ambiguities. -For example, the same unit might be present in different imported projects, or -it might be present in both the importing project and in an imported project. -Both of these conditions are errors. Note that in the current version of -the Project Manager, it is illegal to have an ambiguous unit even if the -unit is never referenced by the importing project. This restriction may be -relaxed in a future release. - -@node Extending a Project -@subsection Extending a Project - -@noindent -In large software systems it is common to have multiple -implementations of a common interface; in Ada terms, multiple versions of a -package body for the same spec. For example, one implementation -might be safe for use in tasking programs, while another might only be used -in sequential applications. This can be modeled in GNAT using the concept -of @emph{project extension}. If one project (the ``child'') @emph{extends} -another project (the ``parent'') then by default all source files of the -parent project are inherited by the child, but the child project can -override any of the parent's source files with new versions, and can also -add new files. This facility is the project analog of a type extension in -Object-Oriented Programming. Project hierarchies are permitted (a child -project may be the parent of yet another project), and a project that -inherits one project can also import other projects. - -As an example, suppose that directory @file{^/seq^[SEQ]^} contains the project -file @file{seq_proj.gpr} as well as the source files @file{pack.ads}, -@file{pack.adb}, and @file{proc.adb}: - -@smallexample -@group -^/seq^[SEQ]^ - pack.ads - pack.adb - proc.adb - seq_proj.gpr -@end group -@end smallexample - -@noindent -Note that the project file can simply be empty (that is, no attribute or -package is defined): - -@smallexample @c projectfile -@group -project Seq_Proj is -end Seq_Proj; -@end group -@end smallexample - -@noindent -implying that its source files are all the Ada source files in the project -directory. - -Suppose we want to supply an alternate version of @file{pack.adb}, in -directory @file{^/tasking^[TASKING]^}, but use the existing versions of -@file{pack.ads} and @file{proc.adb}. We can define a project -@code{Tasking_Proj} that inherits @code{Seq_Proj}: - -@smallexample -@group -^/tasking^[TASKING]^ - pack.adb - tasking_proj.gpr -@end group - -@group -project Tasking_Proj extends "/seq/seq_proj" is -end Tasking_Proj; -@end group -@end smallexample - -@noindent -The version of @file{pack.adb} used in a build depends on which project file -is specified. - -Note that we could have obtained the desired behavior using project import -rather than project inheritance; a @code{base} project would contain the -sources for @file{pack.ads} and @file{proc.adb}, a sequential project would -import @code{base} and add @file{pack.adb}, and likewise a tasking project -would import @code{base} and add a different version of @file{pack.adb}. The -choice depends on whether other sources in the original project need to be -overridden. If they do, then project extension is necessary, otherwise, -importing is sufficient. - -@noindent -In a project file that extends another project file, it is possible to -indicate that an inherited source is not part of the sources of the extending -project. This is necessary sometimes when a package spec has been overloaded -and no longer requires a body: in this case, it is necessary to indicate that -the inherited body is not part of the sources of the project, otherwise there -will be a compilation error when compiling the spec. - -For that purpose, the attribute @code{Excluded_Source_Files} is used. -Its value is a string list: a list of file names. It is also possible to use -attribute @code{Excluded_Source_List_File}. Its value is a single string: -the file name of a text file containing a list of file names, one per line. - -@smallexample @c @projectfile -project B extends "a" is - for Source_Files use ("pkg.ads"); - -- New spec of Pkg does not need a completion - for Excluded_Source_Files use ("pkg.adb"); -end B; -@end smallexample - -Attribute @code{Excluded_Source_Files} may also be used to check if a source -is still needed: if it is possible to build using @command{gnatmake} when such -a source is put in attribute @code{Excluded_Source_Files} of a project P, then -it is possible to remove the source completely from a system that includes -project P. - -@c *********************** -@c * Project File Syntax * -@c *********************** - -@node Project File Syntax -@section Project File Syntax - -@menu -* Basic Syntax:: -* Qualified Projects:: -* Packages:: -* Expressions:: -* String Types:: -* Variables:: -* Attributes:: -* Associative Array Attributes:: -* case Constructions:: -@end menu - -@noindent -This section describes the structure of project files. - -A project may be an @emph{independent project}, entirely defined by a single -project file. Any Ada source file in an independent project depends only -on the predefined library and other Ada source files in the same project. - -@noindent -A project may also @dfn{depend on} other projects, in either or both of -the following ways: -@itemize @bullet -@item It may import any number of projects -@item It may extend at most one other project -@end itemize - -@noindent -The dependence relation is a directed acyclic graph (the subgraph reflecting -the ``extends'' relation is a tree). - -A project's @dfn{immediate sources} are the source files directly defined by -that project, either implicitly by residing in the project file's directory, -or explicitly through any of the source-related attributes described below. -More generally, a project @var{proj}'s @dfn{sources} are the immediate sources -of @var{proj} together with the immediate sources (unless overridden) of any -project on which @var{proj} depends (either directly or indirectly). - -@node Basic Syntax -@subsection Basic Syntax - -@noindent -As seen in the earlier examples, project files have an Ada-like syntax. -The minimal project file is: -@smallexample @c projectfile -@group -project Empty is - -end Empty; -@end group -@end smallexample - -@noindent -The identifier @code{Empty} is the name of the project. -This project name must be present after the reserved -word @code{end} at the end of the project file, followed by a semi-colon. - -Any name in a project file, such as the project name or a variable name, -has the same syntax as an Ada identifier. - -The reserved words of project files are the Ada 95 reserved words plus -@code{extends}, @code{external}, and @code{project}. Note that the only Ada -reserved words currently used in project file syntax are: - -@itemize @bullet -@item -@code{all} -@item -@code{at} -@item -@code{case} -@item -@code{end} -@item -@code{for} -@item -@code{is} -@item -@code{limited} -@item -@code{null} -@item -@code{others} -@item -@code{package} -@item -@code{renames} -@item -@code{type} -@item -@code{use} -@item -@code{when} -@item -@code{with} -@end itemize - -@noindent -Comments in project files have the same syntax as in Ada, two consecutive -hyphens through the end of the line. - -@node Qualified Projects -@subsection Qualified Projects - -@noindent -Before the reserved @code{project}, there may be one or two "qualifiers", that -is identifiers or other reserved words, to qualify the project. - -The current list of qualifiers is: - -@itemize @bullet -@item -@code{abstract}: qualify a project with no sources. A qualified abstract -project must either have no declaration of attributes @code{Source_Dirs}, -@code{Source_Files}, @code{Languages} or @code{Source_List_File}, or one of -@code{Source_Dirs}, @code{Source_Files}, or @code{Languages} must be declared -as empty. If it extends another project, the project it extends must also be a -qualified abstract project. - -@item -@code{standard}: a standard project is a non library project with sources. - -@item -@code{aggregate}: for future extension - -@item -@code{aggregate library}: for future extension - -@item -@code{library}: a library project must declare both attributes -@code{Library_Name} and @code{Library_Dir}. - -@item -@code{configuration}: a configuration project cannot be in a project tree. -@end itemize - -@node Packages -@subsection Packages - -@noindent -A project file may contain @emph{packages}. The name of a package must be one -of the identifiers from the following list. A package -with a given name may only appear once in a project file. Package names are -case insensitive. The following package names are legal: - -@itemize @bullet -@item -@code{Naming} -@item -@code{Builder} -@item -@code{Compiler} -@item -@code{Binder} -@item -@code{Linker} -@item -@code{Finder} -@item -@code{Cross_Reference} -@item -@code{Check} -@item -@code{Eliminate} -@item -@code{Pretty_Printer} -@item -@code{Metrics} -@item -@code{gnatls} -@item -@code{gnatstub} -@item -@code{IDE} -@item -@code{Language_Processing} -@end itemize - -@noindent -In its simplest form, a package may be empty: - -@smallexample @c projectfile -@group -project Simple is - package Builder is - end Builder; -end Simple; -@end group -@end smallexample - -@noindent -A package may contain @emph{attribute declarations}, -@emph{variable declarations} and @emph{case constructions}, as will be -described below. - -When there is ambiguity between a project name and a package name, -the name always designates the project. To avoid possible confusion, it is -always a good idea to avoid naming a project with one of the -names allowed for packages or any name that starts with @code{gnat}. - -@node Expressions -@subsection Expressions - -@noindent -An @emph{expression} is either a @emph{string expression} or a -@emph{string list expression}. - -A @emph{string expression} is either a @emph{simple string expression} or a -@emph{compound string expression}. - -A @emph{simple string expression} is one of the following: -@itemize @bullet -@item A literal string; e.g.@: @code{"comm/my_proj.gpr"} -@item A string-valued variable reference (@pxref{Variables}) -@item A string-valued attribute reference (@pxref{Attributes}) -@item An external reference (@pxref{External References in Project Files}) -@end itemize - -@noindent -A @emph{compound string expression} is a concatenation of string expressions, -using the operator @code{"&"} -@smallexample - Path & "/" & File_Name & ".ads" -@end smallexample - -@noindent -A @emph{string list expression} is either a -@emph{simple string list expression} or a -@emph{compound string list expression}. - -A @emph{simple string list expression} is one of the following: -@itemize @bullet -@item A parenthesized list of zero or more string expressions, -separated by commas -@smallexample - File_Names := (File_Name, "gnat.adc", File_Name & ".orig"); - Empty_List := (); -@end smallexample -@item A string list-valued variable reference -@item A string list-valued attribute reference -@end itemize - -@noindent -A @emph{compound string list expression} is the concatenation (using -@code{"&"}) of a simple string list expression and an expression. Note that -each term in a compound string list expression, except the first, may be -either a string expression or a string list expression. - -@smallexample @c projectfile -@group - File_Name_List := () & File_Name; -- One string in this list - Extended_File_Name_List := File_Name_List & (File_Name & ".orig"); - -- Two strings - Big_List := File_Name_List & Extended_File_Name_List; - -- Concatenation of two string lists: three strings - Illegal_List := "gnat.adc" & Extended_File_Name_List; - -- Illegal: must start with a string list -@end group -@end smallexample - -@node String Types -@subsection String Types - -@noindent -A @emph{string type declaration} introduces a discrete set of string literals. -If a string variable is declared to have this type, its value -is restricted to the given set of literals. - -Here is an example of a string type declaration: - -@smallexample @c projectfile - type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS"); -@end smallexample - -@noindent -Variables of a string type are called @emph{typed variables}; all other -variables are called @emph{untyped variables}. Typed variables are -particularly useful in @code{case} constructions, to support conditional -attribute declarations. -(@pxref{case Constructions}). - -The string literals in the list are case sensitive and must all be different. -They may include any graphic characters allowed in Ada, including spaces. - -A string type may only be declared at the project level, not inside a package. - -A string type may be referenced by its name if it has been declared in the same -project file, or by an expanded name whose prefix is the name of the project -in which it is declared. - -@node Variables -@subsection Variables - -@noindent -A variable may be declared at the project file level, or within a package. -Here are some examples of variable declarations: - -@smallexample @c projectfile -@group - This_OS : OS := external ("OS"); -- a typed variable declaration - That_OS := "GNU/Linux"; -- an untyped variable declaration -@end group -@end smallexample - -@noindent -The syntax of a @emph{typed variable declaration} is identical to the Ada -syntax for an object declaration. By contrast, the syntax of an untyped -variable declaration is identical to an Ada assignment statement. In fact, -variable declarations in project files have some of the characteristics of -an assignment, in that successive declarations for the same variable are -allowed. Untyped variable declarations do establish the expected kind of the -variable (string or string list), and successive declarations for it must -respect the initial kind. - -@noindent -A string variable declaration (typed or untyped) declares a variable -whose value is a string. This variable may be used as a string expression. -@smallexample @c projectfile - File_Name := "readme.txt"; - Saved_File_Name := File_Name & ".saved"; -@end smallexample - -@noindent -A string list variable declaration declares a variable whose value is a list -of strings. The list may contain any number (zero or more) of strings. - -@smallexample @c projectfile - Empty_List := (); - List_With_One_Element := ("^-gnaty^-gnaty^"); - List_With_Two_Elements := List_With_One_Element & "^-gnatg^-gnatg^"; - Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada" - "pack2.ada", "util_.ada", "util.ada"); -@end smallexample - -@noindent -The same typed variable may not be declared more than once at project level, -and it may not be declared more than once in any package; it is in effect -a constant. - -The same untyped variable may be declared several times. Declarations are -elaborated in the order in which they appear, so the new value replaces -the old one, and any subsequent reference to the variable uses the new value. -However, as noted above, if a variable has been declared as a string, all -subsequent -declarations must give it a string value. Similarly, if a variable has -been declared as a string list, all subsequent declarations -must give it a string list value. - -A @emph{variable reference} may take several forms: - -@itemize @bullet -@item The simple variable name, for a variable in the current package (if any) -or in the current project -@item An expanded name, whose prefix is a context name. -@end itemize - -@noindent -A @emph{context} may be one of the following: - -@itemize @bullet -@item The name of an existing package in the current project -@item The name of an imported project of the current project -@item The name of an ancestor project (i.e., a project extended by the current -project, either directly or indirectly) -@item An expanded name whose prefix is an imported/parent project name, and -whose selector is a package name in that project. -@end itemize - -@noindent -A variable reference may be used in an expression. - -@node Attributes -@subsection Attributes - -@noindent -A project (and its packages) may have @emph{attributes} that define -the project's properties. Some attributes have values that are strings; -others have values that are string lists. - -There are two categories of attributes: @emph{simple attributes} -and @emph{associative arrays} (@pxref{Associative Array Attributes}). - -Legal project attribute names, and attribute names for each legal package are -listed below. Attributes names are case-insensitive. - -The following attributes are defined on projects (all are simple attributes): - -@multitable @columnfractions .4 .3 -@item @emph{Attribute Name} -@tab @emph{Value} -@item @code{Source_Files} -@tab string list -@item @code{Source_Dirs} -@tab string list -@item @code{Source_List_File} -@tab string -@item @code{Object_Dir} -@tab string -@item @code{Exec_Dir} -@tab string -@item @code{Excluded_Source_Dirs} -@tab string list -@item @code{Excluded_Source_Files} -@tab string list -@item @code{Excluded_Source_List_File} -@tab string -@item @code{Languages} -@tab string list -@item @code{Main} -@tab string list -@item @code{Library_Dir} -@tab string -@item @code{Library_Name} -@tab string -@item @code{Library_Kind} -@tab string -@item @code{Library_Version} -@tab string -@item @code{Library_Interface} -@tab string -@item @code{Library_Auto_Init} -@tab string -@item @code{Library_Options} -@tab string list -@item @code{Library_Src_Dir} -@tab string -@item @code{Library_ALI_Dir} -@tab string -@item @code{Library_GCC} -@tab string -@item @code{Library_Symbol_File} -@tab string -@item @code{Library_Symbol_Policy} -@tab string -@item @code{Library_Reference_Symbol_File} -@tab string -@item @code{Externally_Built} -@tab string -@end multitable - -@noindent -The following attributes are defined for package @code{Naming} -(@pxref{Naming Schemes}): - -@multitable @columnfractions .4 .2 .2 .2 -@item Attribute Name @tab Category @tab Index @tab Value -@item @code{Spec_Suffix} -@tab associative array -@tab language name -@tab string -@item @code{Body_Suffix} -@tab associative array -@tab language name -@tab string -@item @code{Separate_Suffix} -@tab simple attribute -@tab n/a -@tab string -@item @code{Casing} -@tab simple attribute -@tab n/a -@tab string -@item @code{Dot_Replacement} -@tab simple attribute -@tab n/a -@tab string -@item @code{Spec} -@tab associative array -@tab Ada unit name -@tab string -@item @code{Body} -@tab associative array -@tab Ada unit name -@tab string -@item @code{Specification_Exceptions} -@tab associative array -@tab language name -@tab string list -@item @code{Implementation_Exceptions} -@tab associative array -@tab language name -@tab string list -@end multitable - -@noindent -The following attributes are defined for packages @code{Builder}, -@code{Compiler}, @code{Binder}, -@code{Linker}, @code{Cross_Reference}, and @code{Finder} -(@pxref{^Switches^Switches^ and Project Files}). - -@multitable @columnfractions .4 .2 .2 .2 -@item Attribute Name @tab Category @tab Index @tab Value -@item @code{^Default_Switches^Default_Switches^} -@tab associative array -@tab language name -@tab string list -@item @code{^Switches^Switches^} -@tab associative array -@tab file name -@tab string list -@end multitable - -@noindent -In addition, package @code{Compiler} has a single string attribute -@code{Local_Configuration_Pragmas} and package @code{Builder} has a single -string attribute @code{Global_Configuration_Pragmas}. - -@noindent -Each simple attribute has a default value: the empty string (for string-valued -attributes) and the empty list (for string list-valued attributes). - -An attribute declaration defines a new value for an attribute. - -Examples of simple attribute declarations: - -@smallexample @c projectfile - for Object_Dir use "objects"; - for Source_Dirs use ("units", "test/drivers"); -@end smallexample - -@noindent -The syntax of a @dfn{simple attribute declaration} is similar to that of an -attribute definition clause in Ada. - -Attributes references may be appear in expressions. -The general form for such a reference is @code{<entity>'<attribute>}: -Associative array attributes are functions. Associative -array attribute references must have an argument that is a string literal. - -Examples are: - -@smallexample @c projectfile - project'Object_Dir - Naming'Dot_Replacement - Imported_Project'Source_Dirs - Imported_Project.Naming'Casing - Builder'^Default_Switches^Default_Switches^("Ada") -@end smallexample - -@noindent -The prefix of an attribute may be: -@itemize @bullet -@item @code{project} for an attribute of the current project -@item The name of an existing package of the current project -@item The name of an imported project -@item The name of a parent project that is extended by the current project -@item An expanded name whose prefix is imported/parent project name, -and whose selector is a package name -@end itemize - -@noindent -Example: -@smallexample @c projectfile -@group - project Prj is - for Source_Dirs use project'Source_Dirs & "units"; - for Source_Dirs use project'Source_Dirs & "test/drivers" - end Prj; -@end group -@end smallexample - -@noindent -In the first attribute declaration, initially the attribute @code{Source_Dirs} -has the default value: an empty string list. After this declaration, -@code{Source_Dirs} is a string list of one element: @code{"units"}. -After the second attribute declaration @code{Source_Dirs} is a string list of -two elements: @code{"units"} and @code{"test/drivers"}. - -Note: this example is for illustration only. In practice, -the project file would contain only one attribute declaration: - -@smallexample @c projectfile - for Source_Dirs use ("units", "test/drivers"); -@end smallexample - -@node Associative Array Attributes -@subsection Associative Array Attributes - -@noindent -Some attributes are defined as @emph{associative arrays}. An associative -array may be regarded as a function that takes a string as a parameter -and delivers a string or string list value as its result. - -Here are some examples of single associative array attribute associations: - -@smallexample @c projectfile - for Body ("main") use "Main.ada"; - for ^Switches^Switches^ ("main.ada") - use ("^-v^-v^", - "^-gnatv^-gnatv^"); - for ^Switches^Switches^ ("main.ada") - use Builder'^Switches^Switches^ ("main.ada") - & "^-g^-g^"; -@end smallexample - -@noindent -Like untyped variables and simple attributes, associative array attributes -may be declared several times. Each declaration supplies a new value for the -attribute, and replaces the previous setting. - -@noindent -An associative array attribute may be declared as a full associative array -declaration, with the value of the same attribute in an imported or extended -project. - -@smallexample @c projectfile - package Builder is - for Default_Switches use Default.Builder'Default_Switches; - end Builder; -@end smallexample - -@noindent -In this example, @code{Default} must be either a project imported by the -current project, or the project that the current project extends. If the -attribute is in a package (in this case, in package @code{Builder}), the same -package needs to be specified. - -@noindent -A full associative array declaration replaces any other declaration for the -attribute, including other full associative array declaration. Single -associative array associations may be declare after a full associative -declaration, modifying the value for a single association of the attribute. - -@node case Constructions -@subsection @code{case} Constructions - -@noindent -A @code{case} construction is used in a project file to effect conditional -behavior. -Here is a typical example: - -@smallexample @c projectfile -@group -project MyProj is - type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS"); - - OS : OS_Type := external ("OS", "GNU/Linux"); -@end group - -@group - package Compiler is - case OS is - when "GNU/Linux" | "Unix" => - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-gnath^-gnath^"); - when "NT" => - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-gnatP^-gnatP^"); - when others => - end case; - end Compiler; -end MyProj; -@end group -@end smallexample - -@noindent -The syntax of a @code{case} construction is based on the Ada case statement -(although there is no @code{null} construction for empty alternatives). - -The case expression must be a typed string variable. -Each alternative comprises the reserved word @code{when}, either a list of -literal strings separated by the @code{"|"} character or the reserved word -@code{others}, and the @code{"=>"} token. -Each literal string must belong to the string type that is the type of the -case variable. -An @code{others} alternative, if present, must occur last. - -After each @code{=>}, there are zero or more constructions. The only -constructions allowed in a case construction are other case constructions, -attribute declarations and variable declarations. String type declarations and -package declarations are not allowed. Variable declarations are restricted to -variables that have already been declared before the case construction. - -The value of the case variable is often given by an external reference -(@pxref{External References in Project Files}). - -@c **************************************** -@c * Objects and Sources in Project Files * -@c **************************************** - -@node Objects and Sources in Project Files -@section Objects and Sources in Project Files - -@menu -* Object Directory:: -* Exec Directory:: -* Source Directories:: -* Source File Names:: -@end menu - -@noindent -Each project has exactly one object directory and one or more source -directories. The source directories must contain at least one source file, -unless the project file explicitly specifies that no source files are present -(@pxref{Source File Names}). - -@node Object Directory -@subsection Object Directory - -@noindent -The object directory for a project is the directory containing the compiler's -output (such as @file{ALI} files and object files) for the project's immediate -sources. - -The object directory is given by the value of the attribute @code{Object_Dir} -in the project file. - -@smallexample @c projectfile - for Object_Dir use "objects"; -@end smallexample - -@noindent -The attribute @code{Object_Dir} has a string value, the path name of the object -directory. The path name may be absolute or relative to the directory of the -project file. This directory must already exist, and be readable and writable. - -By default, when the attribute @code{Object_Dir} is not given an explicit value -or when its value is the empty string, the object directory is the same as the -directory containing the project file. - -@node Exec Directory -@subsection Exec Directory - -@noindent -The exec directory for a project is the directory containing the executables -for the project's main subprograms. - -The exec directory is given by the value of the attribute @code{Exec_Dir} -in the project file. - -@smallexample @c projectfile - for Exec_Dir use "executables"; -@end smallexample - -@noindent -The attribute @code{Exec_Dir} has a string value, the path name of the exec -directory. The path name may be absolute or relative to the directory of the -project file. This directory must already exist, and be writable. - -By default, when the attribute @code{Exec_Dir} is not given an explicit value -or when its value is the empty string, the exec directory is the same as the -object directory of the project file. - -@node Source Directories -@subsection Source Directories - -@noindent -The source directories of a project are specified by the project file -attribute @code{Source_Dirs}. - -This attribute's value is a string list. If the attribute is not given an -explicit value, then there is only one source directory, the one where the -project file resides. - -A @code{Source_Dirs} attribute that is explicitly defined to be the empty list, -as in - -@smallexample @c projectfile - for Source_Dirs use (); -@end smallexample - -@noindent -indicates that the project contains no source files. - -Otherwise, each string in the string list designates one or more -source directories. - -@smallexample @c projectfile - for Source_Dirs use ("sources", "test/drivers"); -@end smallexample - -@noindent -If a string in the list ends with @code{"/**"}, then the directory whose path -name precedes the two asterisks, as well as all its subdirectories -(recursively), are source directories. - -@smallexample @c projectfile - for Source_Dirs use ("/system/sources/**"); -@end smallexample - -@noindent -Here the directory @code{/system/sources} and all of its subdirectories -(recursively) are source directories. - -To specify that the source directories are the directory of the project file -and all of its subdirectories, you can declare @code{Source_Dirs} as follows: -@smallexample @c projectfile - for Source_Dirs use ("./**"); -@end smallexample - -@noindent -Each of the source directories must exist and be readable. - -@node Source File Names -@subsection Source File Names - -@noindent -In a project that contains source files, their names may be specified by the -attributes @code{Source_Files} (a string list) or @code{Source_List_File} -(a string). Source file names never include any directory information. - -If the attribute @code{Source_Files} is given an explicit value, then each -element of the list is a source file name. - -@smallexample @c projectfile - for Source_Files use ("main.adb"); - for Source_Files use ("main.adb", "pack1.ads", "pack2.adb"); -@end smallexample - -@noindent -If the attribute @code{Source_Files} is not given an explicit value, -but the attribute @code{Source_List_File} is given a string value, -then the source file names are contained in the text file whose path name -(absolute or relative to the directory of the project file) is the -value of the attribute @code{Source_List_File}. - -Each line in the file that is not empty or is not a comment -contains a source file name. - -@smallexample @c projectfile - for Source_List_File use "source_list.txt"; -@end smallexample - -@noindent -By default, if neither the attribute @code{Source_Files} nor the attribute -@code{Source_List_File} is given an explicit value, then each file in the -source directories that conforms to the project's naming scheme -(@pxref{Naming Schemes}) is an immediate source of the project. - -A warning is issued if both attributes @code{Source_Files} and -@code{Source_List_File} are given explicit values. In this case, the attribute -@code{Source_Files} prevails. - -Each source file name must be the name of one existing source file -in one of the source directories. - -A @code{Source_Files} attribute whose value is an empty list -indicates that there are no source files in the project. - -If the order of the source directories is known statically, that is if -@code{"/**"} is not used in the string list @code{Source_Dirs}, then there may -be several files with the same source file name. In this case, only the file -in the first directory is considered as an immediate source of the project -file. If the order of the source directories is not known statically, it is -an error to have several files with the same source file name. - -Projects can be specified to have no Ada source -files: the value of @code{Source_Dirs} or @code{Source_Files} may be an empty -list, or the @code{"Ada"} may be absent from @code{Languages}: - -@smallexample @c projectfile - for Source_Dirs use (); - for Source_Files use (); - for Languages use ("C", "C++"); -@end smallexample - -@noindent -Otherwise, a project must contain at least one immediate source. - -Projects with no source files are useful as template packages -(@pxref{Packages in Project Files}) for other projects; in particular to -define a package @code{Naming} (@pxref{Naming Schemes}). - -@c **************************** -@c * Importing Projects * -@c **************************** - -@node Importing Projects -@section Importing Projects -@cindex @code{ADA_PROJECT_PATH} -@cindex @code{GPR_PROJECT_PATH} - -@noindent -An immediate source of a project P may depend on source files that -are neither immediate sources of P nor in the predefined library. -To get this effect, P must @emph{import} the projects that contain the needed -source files. - -@smallexample @c projectfile -@group - with "project1", "utilities.gpr"; - with "/namings/apex.gpr"; - project Main is - @dots{} -@end group -@end smallexample - -@noindent -As can be seen in this example, the syntax for importing projects is similar -to the syntax for importing compilation units in Ada. However, project files -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 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 -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 -In between, all the directories referenced in the -^environment variables^logical names^ @env{GPR_PROJECT_PATH} -and @env{ADA_PROJECT_PATH} if they exist, and in that order. -@end itemize - -@noindent -If a relative pathname is used, as in - -@smallexample @c projectfile - with "tests/proj"; -@end smallexample - -@noindent -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, -then the file name as specified in the @code{with} clause (no extension) will -be used. In the above example, if a file @code{project1.gpr} is found, then it -will be used; otherwise, if a file @code{^project1^PROJECT1^} exists -then it will be used; if neither file exists, this is an error. - -A warning is issued if the name of the project file does not match the -name of the project; this check is case insensitive. - -Any source file that is an immediate source of the imported project can be -used by the immediate sources of the importing project, transitively. Thus -if @code{A} imports @code{B}, and @code{B} imports @code{C}, the immediate -sources of @code{A} may depend on the immediate sources of @code{C}, even if -@code{A} does not import @code{C} explicitly. However, this is not recommended, -because if and when @code{B} ceases to import @code{C}, some sources in -@code{A} will no longer compile. - -A side effect of this capability is that normally cyclic dependencies are not -permitted: if @code{A} imports @code{B} (directly or indirectly) then @code{B} -is not allowed to import @code{A}. However, there are cases when cyclic -dependencies would be beneficial. For these cases, another form of import -between projects exists, the @code{limited with}: a project @code{A} that -imports a project @code{B} with a straight @code{with} may also be imported, -directly or indirectly, by @code{B} on the condition that imports from @code{B} -to @code{A} include at least one @code{limited with}. - -@smallexample @c 0projectfile -with "../b/b.gpr"; -with "../c/c.gpr"; -project A is -end A; - -limited with "../a/a.gpr"; -project B is -end B; - -with "../d/d.gpr"; -project C is -end C; - -limited with "../a/a.gpr"; -project D is -end D; -@end smallexample - -@noindent -In the above legal example, there are two project cycles: -@itemize @bullet -@item A-> B-> A -@item A -> C -> D -> A -@end itemize - -@noindent -In each of these cycle there is one @code{limited with}: import of @code{A} -from @code{B} and import of @code{A} from @code{D}. - -The difference between straight @code{with} and @code{limited with} is that -the name of a project imported with a @code{limited with} cannot be used in the -project that imports it. In particular, its packages cannot be renamed and -its variables cannot be referred to. - -An exception to the above rules for @code{limited with} is that for the main -project specified to @command{gnatmake} or to the @command{GNAT} driver a -@code{limited with} is equivalent to a straight @code{with}. For example, -in the example above, projects @code{B} and @code{D} could not be main -projects for @command{gnatmake} or to the @command{GNAT} driver, because they -each have a @code{limited with} that is the only one in a cycle of importing -projects. - -@c ********************* -@c * Project Extension * -@c ********************* - -@node Project Extension -@section Project Extension - -@noindent -During development of a large system, it is sometimes necessary to use -modified versions of some of the source files, without changing the original -sources. This can be achieved through the @emph{project extension} facility. - -@smallexample @c projectfile - project Modified_Utilities extends "/baseline/utilities.gpr" is @dots{} -@end smallexample - -@noindent -A project extension declaration introduces an extending project -(the @emph{child}) and a project being extended (the @emph{parent}). - -By default, a child project inherits all the sources of its parent. -However, inherited sources can be overridden: a unit in a parent is hidden -by a unit of the same name in the child. - -Inherited sources are considered to be sources (but not immediate sources) -of the child project; see @ref{Project File Syntax}. - -An inherited source file retains any switches specified in the parent project. - -For example if the project @code{Utilities} contains the spec and the -body of an Ada package @code{Util_IO}, then the project -@code{Modified_Utilities} can contain a new body for package @code{Util_IO}. -The original body of @code{Util_IO} will not be considered in program builds. -However, the package spec will still be found in the project -@code{Utilities}. - -A child project can have only one parent, except when it is qualified as -abstract. But it may import any number of other projects. - -A project is not allowed to import directly or indirectly at the same time a -child project and any of its ancestors. - -@c ******************************* -@c * Project Hierarchy Extension * -@c ******************************* - -@node Project Hierarchy Extension -@section Project Hierarchy Extension - -@noindent -When extending a large system spanning multiple projects, it is often -inconvenient to extend every project in the hierarchy that is impacted by a -small change introduced. In such cases, it is possible to create a virtual -extension of entire hierarchy using @code{extends all} relationship. - -When the project is extended using @code{extends all} inheritance, all projects -that are imported by it, both directly and indirectly, are considered virtually -extended. That is, the Project Manager creates "virtual projects" -that extend every project in the hierarchy; all these virtual projects have -no sources of their own and have as object directory the object directory of -the root of "extending all" project. - -It is possible to explicitly extend one or more projects in the hierarchy -in order to modify the sources. These extending projects must be imported by -the "extending all" project, which will replace the corresponding virtual -projects with the explicit ones. - -When building such a project hierarchy extension, the Project Manager will -ensure that both modified sources and sources in virtual extending projects -that depend on them, are recompiled. - -By means of example, consider the following hierarchy of projects. - -@enumerate -@item -project A, containing package P1 -@item -project B importing A and containing package P2 which depends on P1 -@item -project C importing B and containing package P3 which depends on P2 -@end enumerate - -@noindent -We want to modify packages P1 and P3. - -This project hierarchy will need to be extended as follows: - -@enumerate -@item -Create project A1 that extends A, placing modified P1 there: - -@smallexample @c 0projectfile -project A1 extends "(@dots{})/A" is -end A1; -@end smallexample - -@item -Create project C1 that "extends all" C and imports A1, placing modified -P3 there: - -@smallexample @c 0projectfile -with "(@dots{})/A1"; -project C1 extends all "(@dots{})/C" is -end C1; -@end smallexample -@end enumerate - -When you build project C1, your entire modified project space will be -recompiled, including the virtual project B1 that has been impacted by the -"extending all" inheritance of project C. - -Note that if a Library Project in the hierarchy is virtually extended, -the virtual project that extends the Library Project is not a Library Project. - -@c **************************************** -@c * External References in Project Files * -@c **************************************** - -@node External References in Project Files -@section External References in Project Files - -@noindent -A project file may contain references to external variables; such references -are called @emph{external references}. - -An external variable is either defined as part of the environment (an -environment variable in Unix, for example) or else specified on the command -line via the @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch. -If both, then the command line value is used. - -The value of an external reference is obtained by means of the built-in -function @code{external}, which returns a string value. -This function has two forms: -@itemize @bullet -@item @code{external (external_variable_name)} -@item @code{external (external_variable_name, default_value)} -@end itemize - -@noindent -Each parameter must be a string literal. For example: - -@smallexample @c projectfile - external ("USER") - external ("OS", "GNU/Linux") -@end smallexample - -@noindent -In the form with one parameter, the function returns the value of -the external variable given as parameter. If this name is not present in the -environment, the function returns an empty string. - -In the form with two string parameters, the second argument is -the value returned when the variable given as the first argument is not -present in the environment. In the example above, if @code{"OS"} is not -the name of ^an environment variable^a logical name^ and is not passed on -the command line, then the returned value is @code{"GNU/Linux"}. - -An external reference may be part of a string expression or of a string -list expression, and can therefore appear in a variable declaration or -an attribute declaration. - -@smallexample @c projectfile -@group - type Mode_Type is ("Debug", "Release"); - Mode : Mode_Type := external ("MODE"); - case Mode is - when "Debug" => - @dots{} -@end group -@end smallexample - -@c ***************************** -@c * Packages in Project Files * -@c ***************************** - -@node Packages in Project Files -@section Packages in Project Files - -@noindent -A @emph{package} defines the settings for project-aware tools within a -project. -For each such tool one can declare a package; the names for these -packages are preset (@pxref{Packages}). -A package may contain variable declarations, attribute declarations, and case -constructions. - -@smallexample @c projectfile -@group - project Proj is - package Builder is -- used by gnatmake - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-v^-v^", - "^-g^-g^"); - end Builder; - end Proj; -@end group -@end smallexample - -@noindent -The syntax of package declarations mimics that of package in Ada. - -Most of the packages have an attribute -@code{^Default_Switches^Default_Switches^}. -This attribute is an associative array, and its value is a string list. -The index of the associative array is the name of a programming language (case -insensitive). This attribute indicates the ^switch^switch^ -or ^switches^switches^ to be used -with the corresponding tool. - -Some packages also have another attribute, @code{^Switches^Switches^}, -an associative array whose value is a string list. -The index is the name of a source file. -This attribute indicates the ^switch^switch^ -or ^switches^switches^ to be used by the corresponding -tool when dealing with this specific file. - -Further information on these ^switch^switch^-related attributes is found in -@ref{^Switches^Switches^ and Project Files}. - -A package may be declared as a @emph{renaming} of another package; e.g., from -the project file for an imported project. - -@smallexample @c projectfile -@group - with "/global/apex.gpr"; - project Example is - package Naming renames Apex.Naming; - @dots{} - end Example; -@end group -@end smallexample - -@noindent -Packages that are renamed in other project files often come from project files -that have no sources: they are just used as templates. Any modification in the -template will be reflected automatically in all the project files that rename -a package from the template. - -In addition to the tool-oriented packages, you can also declare a package -named @code{Naming} to establish specialized source file naming conventions -(@pxref{Naming Schemes}). - -@c ************************************ -@c * Variables from Imported Projects * -@c ************************************ - -@node Variables from Imported Projects -@section Variables from Imported Projects - -@noindent -An attribute or variable defined in an imported or parent project can -be used in expressions in the importing / extending project. -Such an attribute or variable is denoted by an expanded name whose prefix -is either the name of the project or the expanded name of a package within -a project. - -@smallexample @c projectfile -@group - with "imported"; - project Main extends "base" is - Var1 := Imported.Var; - Var2 := Base.Var & ".new"; -@end group - -@group - package Builder is - for ^Default_Switches^Default_Switches^ ("Ada") - use Imported.Builder'Ada_^Switches^Switches^ & - "^-gnatg^-gnatg^" & - "^-v^-v^"; - end Builder; -@end group - -@group - package Compiler is - for ^Default_Switches^Default_Switches^ ("Ada") - use Base.Compiler'Ada_^Switches^Switches^; - end Compiler; - end Main; -@end group -@end smallexample - -@noindent -In this example: - -@itemize @bullet -@item -The value of @code{Var1} is a copy of the variable @code{Var} defined -in the project file @file{"imported.gpr"} -@item -the value of @code{Var2} is a copy of the value of variable @code{Var} -defined in the project file @file{base.gpr}, concatenated with @code{".new"} -@item -attribute @code{^Default_Switches^Default_Switches^ ("Ada")} in package -@code{Builder} is a string list that includes in its value a copy of the value -of @code{Ada_^Switches^Switches^} defined in the @code{Builder} package -in project file @file{imported.gpr} plus two new elements: -@option{"^-gnatg^-gnatg^"} -and @option{"^-v^-v^"}; -@item -attribute @code{^Default_Switches^Default_Switches^ ("Ada")} in package -@code{Compiler} is a copy of the variable @code{Ada_^Switches^Switches^} -defined in the @code{Compiler} package in project file @file{base.gpr}, -the project being extended. -@end itemize - -@c ****************** -@c * Naming Schemes * -@c ****************** - -@node Naming Schemes -@section Naming Schemes - -@noindent -Sometimes an Ada software system is ported from a foreign compilation -environment to GNAT, and the file names do not use the default GNAT -conventions. Instead of changing all the file names (which for a variety -of reasons might not be possible), you can define the relevant file -naming scheme in the @code{Naming} package in your project file. - -@noindent -Note that the use of pragmas described in -@ref{Alternative File Naming Schemes} by mean of a configuration -pragmas file is not supported when using project files. You must use -the features described in this paragraph. You can however use specify -other configuration pragmas (@pxref{Specifying Configuration Pragmas}). - -@ifclear vms -For example, the following -package models the Apex file naming rules: - -@smallexample @c projectfile -@group - package Naming is - for Casing use "lowercase"; - for Dot_Replacement use "."; - for Spec_Suffix ("Ada") use ".1.ada"; - for Body_Suffix ("Ada") use ".2.ada"; - end Naming; -@end group -@end smallexample -@end ifclear - -@ifset vms -For example, the following package models the HP Ada file naming rules: - -@smallexample @c projectfile -@group - package Naming is - for Casing use "lowercase"; - for Dot_Replacement use "__"; - for Spec_Suffix ("Ada") use "_.^ada^ada^"; - for Body_Suffix ("Ada") use ".^ada^ada^"; - end Naming; -@end group -@end smallexample - -@noindent -(Note that @code{Casing} is @code{"lowercase"} because GNAT gets the file -names in lower case) -@end ifset - -@noindent -You can define the following attributes in package @code{Naming}: - -@table @code - -@item @code{Casing} -This must be a string with one of the three values @code{"lowercase"}, -@code{"uppercase"} or @code{"mixedcase"}; these strings are case insensitive. - -@noindent -If @code{Casing} is not specified, then the default is @code{"lowercase"}. - -@item @code{Dot_Replacement} -This must be a string whose value satisfies the following conditions: - -@itemize @bullet -@item It must not be empty -@item It cannot start or end with an alphanumeric character -@item It cannot be a single underscore -@item It cannot start with an underscore followed by an alphanumeric -@item It cannot contain a dot @code{'.'} except if the entire string -is @code{"."} -@end itemize - -@noindent -If @code{Dot_Replacement} is not specified, then the default is @code{"-"}. - -@item @code{Spec_Suffix} -This is an associative array (indexed by the programming language name, case -insensitive) whose value is a string that must satisfy the following -conditions: - -@itemize @bullet -@item It must not be empty -@item It must include at least one dot -@end itemize -@noindent -If @code{Spec_Suffix ("Ada")} is not specified, then the default is -@code{"^.ads^.ADS^"}. - -@item @code{Body_Suffix} -This is an associative array (indexed by the programming language name, case -insensitive) whose value is a string that must satisfy the following -conditions: - -@itemize @bullet -@item It must not be empty -@item It must include at least one dot -@item It cannot be the same as @code{Spec_Suffix ("Ada")} -@end itemize -@noindent -If @code{Body_Suffix ("Ada")} and @code{Spec_Suffix ("Ada")} end with the -same string, then a file name that ends with the longest of these two suffixes -will be a body if the longest suffix is @code{Body_Suffix ("Ada")} or a spec -if the longest suffix is @code{Spec_Suffix ("Ada")}. - -If the suffix does not start with a '.', a file with a name exactly equal -to the suffix will also be part of the project (for instance if you define -the suffix as @code{Makefile}, a file called @file{Makefile} will be part -of the project. This is not interesting in general when using projects to -compile. However, it might become useful when a project is also used to -find the list of source files in an editor, like the GNAT Programming System -(GPS). - -If @code{Body_Suffix ("Ada")} is not specified, then the default is -@code{"^.adb^.ADB^"}. - -@item @code{Separate_Suffix} -This must be a string whose value satisfies the same conditions as -@code{Body_Suffix}. The same "longest suffix" rules apply. - -@noindent -If @code{Separate_Suffix ("Ada")} is not specified, then it defaults to same -value as @code{Body_Suffix ("Ada")}. - -@item @code{Spec} -@noindent -You can use the associative array attribute @code{Spec} to define -the source file name for an individual Ada compilation unit's spec. The array -index must be a string literal that identifies the Ada unit (case insensitive). -The value of this attribute must be a string that identifies the file that -contains this unit's spec (case sensitive or insensitive depending on the -operating system). - -@smallexample @c projectfile - for Spec ("MyPack.MyChild") use "mypack.mychild.spec"; -@end smallexample - -When the source file contains several units, you can indicate at what -position the unit occurs in the file, with the following. The first unit -in the file has index 1 - -@smallexample @c projectfile - for Body ("top") use "foo.a" at 1; - for Body ("foo") use "foo.a" at 2; -@end smallexample - -@item @code{Body} - -You can use the associative array attribute @code{Body} to -define the source file name for an individual Ada compilation unit's body -(possibly a subunit). The array index must be a string literal that identifies -the Ada unit (case insensitive). The value of this attribute must be a string -that identifies the file that contains this unit's body or subunit (case -sensitive or insensitive depending on the operating system). - -@smallexample @c projectfile - for Body ("MyPack.MyChild") use "mypack.mychild.body"; -@end smallexample -@end table - -@c ******************** -@c * Library Projects * -@c ******************** - -@node Library Projects -@section Library Projects - -@noindent -@emph{Library projects} are projects whose object code is placed in a library. -(Note that this facility is not yet supported on all platforms). - -@code{gnatmake} or @code{gprbuild} will collect all object files into a -single archive, which might either be a shared or a static library. This -library can later on be linked with multiple executables, potentially -reducing their sizes. - -If your project file specifies languages other than Ada, but you are still -using @code{gnatmake} to compile and link, the latter will not try to -compile your sources other than Ada (you should use @code{gprbuild} if that -is your intent). However, @code{gnatmake} will automatically link all object -files found in the object directory, whether or not they were compiled from -an Ada source file. This specific behavior only applies when multiple -languages are specified. - -To create a library project, you need to define in its project file -two project-level attributes: @code{Library_Name} and @code{Library_Dir}. -Additionally, you may define other library-related attributes such as -@code{Library_Kind}, @code{Library_Version}, @code{Library_Interface}, -@code{Library_Auto_Init}, @code{Library_Options} and @code{Library_GCC}. - -The @code{Library_Name} attribute has a string value. There is no restriction -on the name of a library. It is the responsibility of the developer to -choose a name that will be accepted by the platform. It is recommended to -choose names that could be Ada identifiers; such names are almost guaranteed -to be acceptable on all platforms. - -The @code{Library_Dir} attribute has a string value that designates the path -(absolute or relative) of the directory where the library will reside. -It must designate an existing directory, and this directory must be writable, -different from the project's object directory and from any source directory -in the project tree. - -If both @code{Library_Name} and @code{Library_Dir} are specified and -are legal, then the project file defines a library project. The optional -library-related attributes are checked only for such project files. - -The @code{Library_Kind} attribute has a string value that must be one of the -following (case insensitive): @code{"static"}, @code{"dynamic"} or -@code{"relocatable"} (which is a synonym for @code{"dynamic"}). If this -attribute is not specified, the library is a static library, that is -an archive of object files that can be potentially linked into a -static executable. Otherwise, the library may be dynamic or -relocatable, that is a library that is loaded only at the start of execution. - -If you need to build both a static and a dynamic library, you should use two -different object directories, since in some cases some extra code needs to -be generated for the latter. For such cases, it is recommended to either use -two different project files, or a single one which uses external variables -to indicate what kind of library should be build. - -The @code{Library_ALI_Dir} attribute may be specified to indicate the -directory where the ALI files of the library will be copied. When it is -not specified, the ALI files are copied to the directory specified in -attribute @code{Library_Dir}. The directory specified by @code{Library_ALI_Dir} -must be writable and different from the project's object directory and from -any source directory in the project tree. - -The @code{Library_Version} attribute has a string value whose interpretation -is platform dependent. It has no effect on VMS and Windows. On Unix, it is -used only for dynamic/relocatable libraries as the internal name of the -library (the @code{"soname"}). If the library file name (built from the -@code{Library_Name}) is different from the @code{Library_Version}, then the -library file will be a symbolic link to the actual file whose name will be -@code{Library_Version}. - -Example (on Unix): - -@smallexample @c projectfile -@group -project Plib is - - Version := "1"; - - for Library_Dir use "lib_dir"; - for Library_Name use "dummy"; - for Library_Kind use "relocatable"; - for Library_Version use "libdummy.so." & Version; - -end Plib; -@end group -@end smallexample - -@noindent -Directory @file{lib_dir} will contain the internal library file whose name -will be @file{libdummy.so.1}, and @file{libdummy.so} will be a symbolic link to -@file{libdummy.so.1}. - -When @command{gnatmake} detects that a project file -is a library project file, it will check all immediate sources of the project -and rebuild the library if any of the sources have been recompiled. - -Standard project files can import library project files. In such cases, -the libraries will only be rebuilt if some of its sources are recompiled -because they are in the closure of some other source in an importing project. -Sources of the library project files that are not in such a closure will -not be checked, unless the full library is checked, because one of its sources -needs to be recompiled. - -For instance, assume the project file @code{A} imports the library project file -@code{L}. The immediate sources of A are @file{a1.adb}, @file{a2.ads} and -@file{a2.adb}. The immediate sources of L are @file{l1.ads}, @file{l1.adb}, -@file{l2.ads}, @file{l2.adb}. - -If @file{l1.adb} has been modified, then the library associated with @code{L} -will be rebuilt when compiling all the immediate sources of @code{A} only -if @file{a1.ads}, @file{a2.ads} or @file{a2.adb} includes a statement -@code{"with L1;"}. - -To be sure that all the sources in the library associated with @code{L} are -up to date, and that all the sources of project @code{A} are also up to date, -the following two commands needs to be used: - -@smallexample -gnatmake -Pl.gpr -gnatmake -Pa.gpr -@end smallexample - -When a library is built or rebuilt, an attempt is made first to delete all -files in the library directory. -All @file{ALI} files will also be copied from the object directory to the -library directory. To build executables, @command{gnatmake} will use the -library rather than the individual object files. - -@ifclear vms -It is also possible to create library project files for third-party libraries -that are precompiled and cannot be compiled locally thanks to the -@code{externally_built} attribute. (See @ref{Installing a library}). -@end ifclear - -@c ******************************* -@c * Stand-alone Library Projects * -@c ******************************* - -@node Stand-alone Library Projects -@section Stand-alone Library Projects - -@noindent -A Stand-alone Library is a library that contains the necessary code to -elaborate the Ada units that are included in the library. A Stand-alone -Library is suitable to be used in an executable when the main is not -in Ada. However, Stand-alone Libraries may also be used with an Ada main -subprogram. - -A Stand-alone Library Project is a Library Project where the library is -a Stand-alone Library. - -To be a Stand-alone Library Project, in addition to the two attributes -that make a project a Library Project (@code{Library_Name} and -@code{Library_Dir}, see @ref{Library Projects}), the attribute -@code{Library_Interface} must be defined. - -@smallexample @c projectfile -@group - for Library_Dir use "lib_dir"; - for Library_Name use "dummy"; - for Library_Interface use ("int1", "int1.child"); -@end group -@end smallexample - -Attribute @code{Library_Interface} has a nonempty string list value, -each string in the list designating a unit contained in an immediate source -of the project file. - -When a Stand-alone Library is built, first the binder is invoked to build -a package whose name depends on the library name -(^b~dummy.ads/b^B$DUMMY.ADS/B^ in the example above). -This binder-generated package includes initialization and -finalization procedures whose -names depend on the library name (dummyinit and dummyfinal in the example -above). The object corresponding to this package is included in the library. - -A dynamic or relocatable Stand-alone Library is automatically initialized -if automatic initialization of Stand-alone Libraries is supported on the -platform and if attribute @code{Library_Auto_Init} is not specified or -is specified with the value "true". A static Stand-alone Library is never -automatically initialized. - -Single string attribute @code{Library_Auto_Init} may be specified with only -two possible values: "false" or "true" (case-insensitive). Specifying -"false" for attribute @code{Library_Auto_Init} will prevent automatic -initialization of dynamic or relocatable libraries. - -When a non-automatically initialized Stand-alone Library is used -in an executable, its initialization procedure must be called before -any service of the library is used. -When the main subprogram is in Ada, it may mean that the initialization -procedure has to be called during elaboration of another package. - -For a Stand-Alone Library, only the @file{ALI} files of the Interface Units -(those that are listed in attribute @code{Library_Interface}) are copied to -the Library Directory. As a consequence, only the Interface Units may be -imported from Ada units outside of the library. If other units are imported, -the binding phase will fail. - -When a Stand-Alone Library is bound, the switches that are specified in -the attribute @code{Default_Switches ("Ada")} in package @code{Binder} are -used in the call to @command{gnatbind}. - -The string list attribute @code{Library_Options} may be used to specified -additional switches to the call to @command{gcc} to link the library. - -The attribute @code{Library_Src_Dir}, may be specified for a -Stand-Alone Library. @code{Library_Src_Dir} is a simple attribute that has a -single string value. Its value must be the path (absolute or relative to the -project directory) of an existing directory. This directory cannot be the -object directory or one of the source directories, but it can be the same as -the library directory. The sources of the Interface -Units of the library, necessary to an Ada client of the library, will be -copied to the designated directory, called Interface Copy directory. -These sources includes the specs of the Interface Units, but they may also -include bodies and subunits, when pragmas @code{Inline} or @code{Inline_Always} -are used, or when there is a generic units in the spec. Before the sources -are copied to the Interface Copy directory, an attempt is made to delete all -files in the Interface Copy directory. - -@c ************************************* -@c * Switches Related to Project Files * -@c ************************************* -@node Switches Related to Project Files -@section Switches Related to Project Files - -@noindent -The following switches are used by GNAT tools that support project files: - -@table @option - -@item ^-P^/PROJECT_FILE=^@var{project} -@cindex @option{^-P^/PROJECT_FILE^} (any project-aware tool) -Indicates the name of a project file. This project file will be parsed with -the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}}, -if any, and using the external references indicated -by @option{^-X^/EXTERNAL_REFERENCE^} switches, if any. -@ifclear vms -There may zero, one or more spaces between @option{-P} and @var{project}. -@end ifclear - -@noindent -There must be only one @option{^-P^/PROJECT_FILE^} switch on the command line. -@noindent -Since the Project Manager parses the project file only after all the switches -on the command line are checked, the order of the switches -@option{^-P^/PROJECT_FILE^}, -@option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} -or @option{^-X^/EXTERNAL_REFERENCE^} is not significant. +@c ------ macros for projects.texi +@c These macros are needed when building the gprbuild documentation, but +@c should have no effect in the gnat user's guide -@item ^-X^/EXTERNAL_REFERENCE=^@var{name=value} -@cindex @option{^-X^/EXTERNAL_REFERENCE^} (any project-aware tool) -Indicates that external variable @var{name} has the value @var{value}. -The Project Manager will use this value for occurrences of -@code{external(name)} when parsing the project file. - -@ifclear vms -@noindent -If @var{name} or @var{value} includes a space, then @var{name=value} should be -put between quotes. +@macro CODESAMPLE{TXT} @smallexample - -XOS=NT - -X"user=John Doe" -@end smallexample -@end ifclear - -@noindent -Several @option{^-X^/EXTERNAL_REFERENCE^} switches can be used simultaneously. -If several @option{^-X^/EXTERNAL_REFERENCE^} switches specify the same -@var{name}, only the last one is used. - -@noindent -An external variable specified with a @option{^-X^/EXTERNAL_REFERENCE^} switch -takes precedence over the value of the same name in the environment. - -@item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x} -@cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (any project-aware tool) -Indicates the verbosity of the parsing of GNAT project files. - -@ifclear vms -@option{-vP0} means Default; -@option{-vP1} means Medium; -@option{-vP2} means High. -@end ifclear - -@ifset vms -There are three possible options for this qualifier: DEFAULT, MEDIUM and -HIGH. -@end ifset - -@noindent -The default is ^Default^DEFAULT^: no output for syntactically correct -project files. -@noindent -If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present, -only the last one is used. - -@item ^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir> -@cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool) -Add directory <dir> at the beginning of the project search path, in order, -after the current working directory. - -@ifclear vms -@item -eL -@cindex @option{-eL} (any project-aware tool) -Follow all symbolic links when processing project files. -@end ifclear - -@item ^--subdirs^/SUBDIRS^=<subdir> -@cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean) -This switch is recognized by gnatmake and gnatclean. It indicate that the real -directories (except the source directories) are the subdirectories <subdir> -of the directories specified in the project files. This applies in particular -to object directories, library directories and exec directories. If the -subdirectories do not exist, they are created automatically. - -@end table - -@c ********************************** -@c * Tools Supporting Project Files * -@c ********************************** - -@node Tools Supporting Project Files -@section Tools Supporting Project Files - -@menu -* gnatmake and Project Files:: -* The GNAT Driver and Project Files:: -@end menu - -@node gnatmake and Project Files -@subsection gnatmake and Project Files - -@noindent -This section covers several topics related to @command{gnatmake} and -project files: defining ^switches^switches^ for @command{gnatmake} -and for the tools that it invokes; specifying configuration pragmas; -the use of the @code{Main} attribute; building and rebuilding library project -files. - -@menu -* ^Switches^Switches^ and Project Files:: -* Specifying Configuration Pragmas:: -* Project Files and Main Subprograms:: -* Library Project Files:: -@end menu - -@node ^Switches^Switches^ and Project Files -@subsubsection ^Switches^Switches^ and Project Files - -@ifset vms -It is not currently possible to specify VMS style qualifiers in the project -files; only Unix style ^switches^switches^ may be specified. -@end ifset - -@noindent -For each of the packages @code{Builder}, @code{Compiler}, @code{Binder}, and -@code{Linker}, you can specify a @code{^Default_Switches^Default_Switches^} -attribute, a @code{^Switches^Switches^} attribute, or both; -as their names imply, these ^switch^switch^-related -attributes affect the ^switches^switches^ that are used for each of these GNAT -components when -@command{gnatmake} is invoked. As will be explained below, these -component-specific ^switches^switches^ precede -the ^switches^switches^ provided on the @command{gnatmake} command line. - -The @code{^Default_Switches^Default_Switches^} attribute is an associative -array indexed by language name (case insensitive) whose value is a string list. -For example: - -@smallexample @c projectfile -@group -package Compiler is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-gnaty^-gnaty^", - "^-v^-v^"); -end Compiler; -@end group -@end smallexample - -@noindent -The @code{^Switches^Switches^} attribute is also an associative array, -indexed by a file name (which may or may not be case sensitive, depending -on the operating system) whose value is a string list. For example: - -@smallexample @c projectfile @group -package Builder is - for ^Switches^Switches^ ("main1.adb") - use ("^-O2^-O2^"); - for ^Switches^Switches^ ("main2.adb") - use ("^-g^-g^"); -end Builder; -@end group -@end smallexample - -@noindent -For the @code{Builder} package, the file names must designate source files -for main subprograms. For the @code{Binder} and @code{Linker} packages, the -file names must designate @file{ALI} or source files for main subprograms. -In each case just the file name without an explicit extension is acceptable. - -For each tool used in a program build (@command{gnatmake}, the compiler, the -binder, and the linker), the corresponding package @dfn{contributes} a set of -^switches^switches^ for each file on which the tool is invoked, based on the -^switch^switch^-related attributes defined in the package. -In particular, the ^switches^switches^ -that each of these packages contributes for a given file @var{f} comprise: - -@itemize @bullet -@item -the value of attribute @code{^Switches^Switches^ (@var{f})}, -if it is specified in the package for the given file, -@item -otherwise, the value of @code{^Default_Switches^Default_Switches^ ("Ada")}, -if it is specified in the package. -@end itemize - -@noindent -If neither of these attributes is defined in the package, then the package does -not contribute any ^switches^switches^ for the given file. - -When @command{gnatmake} is invoked on a file, the ^switches^switches^ comprise -two sets, in the following order: those contributed for the file -by the @code{Builder} package; -and the switches passed on the command line. - -When @command{gnatmake} invokes a tool (compiler, binder, linker) on a file, -the ^switches^switches^ passed to the tool comprise three sets, -in the following order: - -@enumerate -@item -the applicable ^switches^switches^ contributed for the file -by the @code{Builder} package in the project file supplied on the command line; - -@item -those contributed for the file by the package (in the relevant project file -- -see below) corresponding to the tool; and - -@item -the applicable switches passed on the command line. -@end enumerate - -@noindent -The term @emph{applicable ^switches^switches^} reflects the fact that -@command{gnatmake} ^switches^switches^ may or may not be passed to individual -tools, depending on the individual ^switch^switch^. - -@command{gnatmake} may invoke the compiler on source files from different -projects. The Project Manager will use the appropriate project file to -determine the @code{Compiler} package for each source file being compiled. -Likewise for the @code{Binder} and @code{Linker} packages. - -As an example, consider the following package in a project file: - -@smallexample @c projectfile -@group -project Proj1 is - package Compiler is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-g^-g^"); - for ^Switches^Switches^ ("a.adb") - use ("^-O1^-O1^"); - for ^Switches^Switches^ ("b.adb") - use ("^-O2^-O2^", - "^-gnaty^-gnaty^"); - end Compiler; -end Proj1; -@end group -@end smallexample - -@noindent -If @command{gnatmake} is invoked with this project file, and it needs to -compile, say, the files @file{a.adb}, @file{b.adb}, and @file{c.adb}, then -@file{a.adb} will be compiled with the ^switch^switch^ -@option{^-O1^-O1^}, -@file{b.adb} with ^switches^switches^ -@option{^-O2^-O2^} -and @option{^-gnaty^-gnaty^}, -and @file{c.adb} with @option{^-g^-g^}. - -The following example illustrates the ordering of the ^switches^switches^ -contributed by different packages: - -@smallexample @c projectfile -@group -project Proj2 is - package Builder is - for ^Switches^Switches^ ("main.adb") - use ("^-g^-g^", - "^-O1^-)1^", - "^-f^-f^"); - end Builder; -@end group - -@group - package Compiler is - for ^Switches^Switches^ ("main.adb") - use ("^-O2^-O2^"); - end Compiler; -end Proj2; -@end group -@end smallexample - -@noindent -If you issue the command: - -@smallexample - gnatmake ^-Pproj2^/PROJECT_FILE=PROJ2^ -O0 main -@end smallexample - -@noindent -then the compiler will be invoked on @file{main.adb} with the following -sequence of ^switches^switches^ - -@smallexample - ^-g -O1 -O2 -O0^-g -O1 -O2 -O0^ -@end smallexample - -with the last @option{^-O^-O^} -^switch^switch^ having precedence over the earlier ones; -several other ^switches^switches^ -(such as @option{^-c^-c^}) are added implicitly. - -The ^switches^switches^ -@option{^-g^-g^} -and @option{^-O1^-O1^} are contributed by package -@code{Builder}, @option{^-O2^-O2^} is contributed -by the package @code{Compiler} -and @option{^-O0^-O0^} comes from the command line. - -The @option{^-g^-g^} -^switch^switch^ will also be passed in the invocation of -@command{Gnatlink.} - -A final example illustrates switch contributions from packages in different -project files: - -@smallexample @c projectfile -@group -project Proj3 is - for Source_Files use ("pack.ads", "pack.adb"); - package Compiler is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-gnata^-gnata^"); - end Compiler; -end Proj3; -@end group - -@group -with "Proj3"; -project Proj4 is - for Source_Files use ("foo_main.adb", "bar_main.adb"); - package Builder is - for ^Switches^Switches^ ("foo_main.adb") - use ("^-s^-s^", - "^-g^-g^"); - end Builder; -end Proj4; -@end group - -@group --- Ada source file: -with Pack; -procedure Foo_Main is - @dots{} -end Foo_Main; -@end group -@end smallexample - -If the command is -@smallexample -gnatmake ^-PProj4^/PROJECT_FILE=PROJ4^ foo_main.adb -cargs -gnato -@end smallexample - -@noindent -then the ^switches^switches^ passed to the compiler for @file{foo_main.adb} are -@option{^-g^-g^} (contributed by the package @code{Proj4.Builder}) and -@option{^-gnato^-gnato^} (passed on the command line). -When the imported package @code{Pack} is compiled, the ^switches^switches^ used -are @option{^-g^-g^} from @code{Proj4.Builder}, -@option{^-gnata^-gnata^} (contributed from package @code{Proj3.Compiler}, -and @option{^-gnato^-gnato^} from the command line. - -@noindent -When using @command{gnatmake} with project files, some ^switches^switches^ or -arguments may be expressed as relative paths. As the working directory where -compilation occurs may change, these relative paths are converted to absolute -paths. For the ^switches^switches^ found in a project file, the relative paths -are relative to the project file directory, for the switches on the command -line, they are relative to the directory where @command{gnatmake} is invoked. -The ^switches^switches^ for which this occurs are: -^-I^-I^, -^-A^-A^, -^-L^-L^, -^-aO^-aO^, -^-aL^-aL^, -^-aI^-aI^, as well as all arguments that are not switches (arguments to -^switch^switch^ -^-o^-o^, object files specified in package @code{Linker} or after --largs on the command line). The exception to this rule is the ^switch^switch^ -^--RTS=^--RTS=^ for which a relative path argument is never converted. - -@node Specifying Configuration Pragmas -@subsubsection Specifying Configuration Pragmas - -When using @command{gnatmake} with project files, if there exists a file -@file{gnat.adc} that contains configuration pragmas, this file will be -ignored. - -Configuration pragmas can be defined by means of the following attributes in -project files: @code{Global_Configuration_Pragmas} in package @code{Builder} -and @code{Local_Configuration_Pragmas} in package @code{Compiler}. - -Both these attributes are single string attributes. Their values is the path -name of a file containing configuration pragmas. If a path name is relative, -then it is relative to the project directory of the project file where the -attribute is defined. - -When compiling a source, the configuration pragmas used are, in order, -those listed in the file designated by attribute -@code{Global_Configuration_Pragmas} in package @code{Builder} of the main -project file, if it is specified, and those listed in the file designated by -attribute @code{Local_Configuration_Pragmas} in package @code{Compiler} of -the project file of the source, if it exists. - -@node Project Files and Main Subprograms -@subsubsection Project Files and Main Subprograms - -@noindent -When using a project file, you can invoke @command{gnatmake} -with one or several main subprograms, by specifying their source files on the -command line. - -@smallexample - gnatmake ^-P^/PROJECT_FILE=^prj main1 main2 main3 -@end smallexample - -@noindent -Each of these needs to be a source file of the same project, except -when the switch ^-u^/UNIQUE^ is used. - -@noindent -When ^-u^/UNIQUE^ is not used, all the mains need to be sources of the -same project, one of the project in the tree rooted at the project specified -on the command line. The package @code{Builder} of this common project, the -"main project" is the one that is considered by @command{gnatmake}. - -@noindent -When ^-u^/UNIQUE^ is used, the specified source files may be in projects -imported directly or indirectly by the project specified on the command line. -Note that if such a source file is not part of the project specified on the -command line, the ^switches^switches^ found in package @code{Builder} of the -project specified on the command line, if any, that are transmitted -to the compiler will still be used, not those found in the project file of -the source file. - -@noindent -When using a project file, you can also invoke @command{gnatmake} without -explicitly specifying any main, and the effect depends on whether you have -defined the @code{Main} attribute. This attribute has a string list value, -where each element in the list is the name of a source file (the file -extension is optional) that contains a unit that can be a main subprogram. - -If the @code{Main} attribute is defined in a project file as a non-empty -string list and the switch @option{^-u^/UNIQUE^} is not used on the command -line, then invoking @command{gnatmake} with this project file but without any -main on the command line is equivalent to invoking @command{gnatmake} with all -the file names in the @code{Main} attribute on the command line. - -Example: -@smallexample @c projectfile -@group - project Prj is - for Main use ("main1", "main2", "main3"); - end Prj; -@end group -@end smallexample - -@noindent -With this project file, @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^"} -is equivalent to -@code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1 main2 main3"}. - -When the project attribute @code{Main} is not specified, or is specified -as an empty string list, or when the switch @option{-u} is used on the command -line, then invoking @command{gnatmake} with no main on the command line will -result in all immediate sources of the project file being checked, and -potentially recompiled. Depending on the presence of the switch @option{-u}, -sources from other project files on which the immediate sources of the main -project file depend are also checked and potentially recompiled. In other -words, the @option{-u} switch is applied to all of the immediate sources of the -main project file. - -When no main is specified on the command line and attribute @code{Main} exists -and includes several mains, or when several mains are specified on the -command line, the default ^switches^switches^ in package @code{Builder} will -be used for all mains, even if there are specific ^switches^switches^ -specified for one or several mains. - -But the ^switches^switches^ from package @code{Binder} or @code{Linker} will be -the specific ^switches^switches^ for each main, if they are specified. - -@node Library Project Files -@subsubsection Library Project Files - -@noindent -When @command{gnatmake} is invoked with a main project file that is a library -project file, it is not allowed to specify one or more mains on the command -line. - -@noindent -When a library project file is specified, switches ^-b^/ACTION=BIND^ and -^-l^/ACTION=LINK^ have special meanings. - -@itemize @bullet -@item ^-b^/ACTION=BIND^ is only allowed for stand-alone libraries. It indicates -to @command{gnatmake} that @command{gnatbind} should be invoked for the -library. - -@item ^-l^/ACTION=LINK^ may be used for all library projects. It indicates -to @command{gnatmake} that the binder generated file should be compiled -(in the case of a stand-alone library) and that the library should be built. - -@end itemize - -@node The GNAT Driver and Project Files -@subsection The GNAT Driver and Project Files - -@noindent -A number of GNAT tools, other than @command{^gnatmake^gnatmake^} -can benefit from project files: -@command{^gnatbind^gnatbind^}, -@command{^gnatcheck^gnatcheck^}), -@command{^gnatclean^gnatclean^}), -@command{^gnatelim^gnatelim^}, -@command{^gnatfind^gnatfind^}, -@command{^gnatlink^gnatlink^}, -@command{^gnatls^gnatls^}, -@command{^gnatmetric^gnatmetric^}, -@command{^gnatpp^gnatpp^}, -@command{^gnatstub^gnatstub^}, -and @command{^gnatxref^gnatxref^}. However, none of these tools can be invoked -directly with a project file switch (@option{^-P^/PROJECT_FILE=^}). -They must be invoked through the @command{gnat} driver. - -The @command{gnat} driver is a wrapper that accepts a number of commands and -calls the corresponding tool. It was designed initially for VMS platforms (to -convert VMS qualifiers to Unix-style switches), but it is now available on all -GNAT platforms. - -On non-VMS platforms, the @command{gnat} driver accepts the following commands -(case insensitive): - -@itemize @bullet -@item -BIND to invoke @command{^gnatbind^gnatbind^} -@item -CHOP to invoke @command{^gnatchop^gnatchop^} -@item -CLEAN to invoke @command{^gnatclean^gnatclean^} -@item -COMP or COMPILE to invoke the compiler -@item -ELIM to invoke @command{^gnatelim^gnatelim^} -@item -FIND to invoke @command{^gnatfind^gnatfind^} -@item -KR or KRUNCH to invoke @command{^gnatkr^gnatkr^} -@item -LINK to invoke @command{^gnatlink^gnatlink^} -@item -LS or LIST to invoke @command{^gnatls^gnatls^} -@item -MAKE to invoke @command{^gnatmake^gnatmake^} -@item -NAME to invoke @command{^gnatname^gnatname^} -@item -PREP or PREPROCESS to invoke @command{^gnatprep^gnatprep^} -@item -PP or PRETTY to invoke @command{^gnatpp^gnatpp^} -@item -METRIC to invoke @command{^gnatmetric^gnatmetric^} -@item -STUB to invoke @command{^gnatstub^gnatstub^} -@item -XREF to invoke @command{^gnatxref^gnatxref^} -@end itemize - -@noindent -(note that the compiler is invoked using the command -@command{^gnatmake -f -u -c^gnatmake -f -u -c^}). - -@noindent -On non-VMS platforms, between @command{gnat} and the command, two -special switches may be used: - -@itemize @bullet -@item -@command{-v} to display the invocation of the tool. -@item -@command{-dn} to prevent the @command{gnat} driver from removing -the temporary files it has created. These temporary files are -configuration files and temporary file list files. -@end itemize - -@noindent -The command may be followed by switches and arguments for the invoked -tool. - -@smallexample - gnat bind -C main.ali - gnat ls -a main - gnat chop foo.txt -@end smallexample - -@noindent -Switches may also be put in text files, one switch per line, and the text -files may be specified with their path name preceded by '@@'. - -@smallexample - gnat bind @@args.txt main.ali -@end smallexample - -@noindent -In addition, for commands BIND, COMP or COMPILE, FIND, ELIM, LS or LIST, LINK, -METRIC, PP or PRETTY, STUB and XREF, the project file related switches -(@option{^-P^/PROJECT_FILE^}, -@option{^-X^/EXTERNAL_REFERENCE^} and -@option{^-vP^/MESSAGES_PROJECT_FILE=^x}) may be used in addition to -the switches of the invoking tool. - -@noindent -When GNAT PP or GNAT PRETTY is used with a project file, but with no source -specified on the command line, it invokes @command{^gnatpp^gnatpp^} with all -the immediate sources of the specified project file. - -@noindent -When GNAT METRIC is used with a project file, but with no source -specified on the command line, it invokes @command{^gnatmetric^gnatmetric^} -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. - -@itemize @bullet -@item -package @code{Binder} for command BIND (invoking @code{^gnatbind^gnatbind^}) - -@item -package @code{Check} for command CHECK (invoking -@code{^gnatcheck^gnatcheck^}) - -@item -package @code{Compiler} for command COMP or COMPILE (invoking the compiler) - -@item -package @code{Cross_Reference} for command XREF (invoking -@code{^gnatxref^gnatxref^}) - -@item -package @code{Eliminate} for command ELIM (invoking -@code{^gnatelim^gnatelim^}) - -@item -package @code{Finder} for command FIND (invoking @code{^gnatfind^gnatfind^}) - -@item -package @code{Gnatls} for command LS or LIST (invoking @code{^gnatls^gnatls^}) - -@item -package @code{Gnatstub} for command STUB -(invoking @code{^gnatstub^gnatstub^}) - -@item -package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^}) - -@item -package @code{Check} for command CHECK -(invoking @code{^gnatcheck^gnatcheck^}) - -@item -package @code{Metrics} for command METRIC -(invoking @code{^gnatmetric^gnatmetric^}) - -@item -package @code{Pretty_Printer} for command PP or PRETTY -(invoking @code{^gnatpp^gnatpp^}) - -@end itemize - -@noindent -Package @code{Gnatls} has a unique attribute @code{^Switches^Switches^}, -a simple variable with a string list value. It contains ^switches^switches^ -for the invocation of @code{^gnatls^gnatls^}. - -@smallexample @c projectfile -@group -project Proj1 is - package gnatls is - for ^Switches^Switches^ - use ("^-a^-a^", - "^-v^-v^"); - end gnatls; -end Proj1; -@end group -@end smallexample - -@noindent -All other packages have two attribute @code{^Switches^Switches^} and -@code{^Default_Switches^Default_Switches^}. - -@noindent -@code{^Switches^Switches^} is an associative array attribute, indexed by the -source file name, that has a string list value: the ^switches^switches^ to be -used when the tool corresponding to the package is invoked for the specific -source file. - -@noindent -@code{^Default_Switches^Default_Switches^} is an associative array attribute, -indexed by the programming language that has a string list value. -@code{^Default_Switches^Default_Switches^ ("Ada")} contains the -^switches^switches^ for the invocation of the tool corresponding -to the package, except if a specific @code{^Switches^Switches^} attribute -is specified for the source file. - -@smallexample @c projectfile -@group -project Proj is - - for Source_Dirs use ("./**"); - - package gnatls is - for ^Switches^Switches^ use - ("^-a^-a^", - "^-v^-v^"); - end gnatls; -@end group -@group - - package Compiler is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-gnatv^-gnatv^", - "^-gnatwa^-gnatwa^"); - end Binder; -@end group -@group - - package Binder is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-C^-C^", - "^-e^-e^"); - end Binder; -@end group -@group - - package Linker is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-C^-C^"); - for ^Switches^Switches^ ("main.adb") - use ("^-C^-C^", - "^-v^-v^", - "^-v^-v^"); - end Linker; -@end group -@group - - package Finder is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-a^-a^", - "^-f^-f^"); - end Finder; -@end group -@group - - package Cross_Reference is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-a^-a^", - "^-f^-f^", - "^-d^-d^", - "^-u^-u^"); - end Cross_Reference; -end Proj; -@end group -@end smallexample - -@noindent -With the above project file, commands such as - -@smallexample - ^gnat comp -Pproj main^GNAT COMP /PROJECT_FILE=PROJ MAIN^ - ^gnat ls -Pproj main^GNAT LIST /PROJECT_FILE=PROJ MAIN^ - ^gnat xref -Pproj main^GNAT XREF /PROJECT_FILE=PROJ MAIN^ - ^gnat bind -Pproj main.ali^GNAT BIND /PROJECT_FILE=PROJ MAIN.ALI^ - ^gnat link -Pproj main.ali^GNAT LINK /PROJECT_FILE=PROJ MAIN.ALI^ -@end smallexample - -@noindent -will set up the environment properly and invoke the tool with the switches -found in the package corresponding to the tool: -@code{^Default_Switches^Default_Switches^ ("Ada")} for all tools, -except @code{^Switches^Switches^ ("main.adb")} -for @code{^gnatlink^gnatlink^}. -It is also possible to invoke some of the tools, -@code{^gnatcheck^gnatcheck^}), -@code{^gnatmetric^gnatmetric^}), -and @code{^gnatpp^gnatpp^}) -on a set of project units thanks to the combination of the switches -@option{-P}, @option{-U} and possibly the main unit when one is interested -in its closure. For instance, -@smallexample -gnat metric -Pproj -@end smallexample -will compute the metrics for all the immediate units of project -@code{proj}. -@smallexample -gnat metric -Pproj -U -@end smallexample -will compute the metrics for all the units of the closure of projects -rooted at @code{proj}. -@smallexample -gnat metric -Pproj -U main_unit -@end smallexample -will compute the metrics for the closure of units rooted at -@code{main_unit}. This last possibility relies implicitly -on @command{gnatbind}'s option @option{-R}. - -@c ********************** -@node An Extended Example -@section An Extended Example - -@noindent -Suppose that we have two programs, @var{prog1} and @var{prog2}, -whose sources are in corresponding directories. We would like -to build them with a single @command{gnatmake} command, and we want to place -their object files into @file{build} subdirectories of the source directories. -Furthermore, we want to have to have two separate subdirectories -in @file{build} -- @file{release} and @file{debug} -- which will contain -the object files compiled with different set of compilation flags. - -In other words, we have the following structure: - -@smallexample -@group - main - |- prog1 - | |- build - | | debug - | | release - |- prog2 - |- build - | debug - | release -@end group -@end smallexample - -@noindent -Here are the project files that we must place in a directory @file{main} -to maintain this structure: - -@enumerate - -@item We create a @code{Common} project with a package @code{Compiler} that -specifies the compilation ^switches^switches^: - -@smallexample -File "common.gpr": -@group -@b{project} Common @b{is} - - @b{for} Source_Dirs @b{use} (); -- No source files -@end group - -@group - @b{type} Build_Type @b{is} ("release", "debug"); - Build : Build_Type := External ("BUILD", "debug"); -@end group -@group - @b{package} Compiler @b{is} - @b{case} Build @b{is} - @b{when} "release" => - @b{for} ^Default_Switches^Default_Switches^ ("Ada") - @b{use} ("^-O2^-O2^"); - @b{when} "debug" => - @b{for} ^Default_Switches^Default_Switches^ ("Ada") - @b{use} ("^-g^-g^"); - @b{end case}; - @b{end} Compiler; - -@b{end} Common; -@end group -@end smallexample - -@item We create separate projects for the two programs: - -@smallexample -@group -File "prog1.gpr": - -@b{with} "common"; -@b{project} Prog1 @b{is} - - @b{for} Source_Dirs @b{use} ("prog1"); - @b{for} Object_Dir @b{use} "prog1/build/" & Common.Build; - - @b{package} Compiler @b{renames} Common.Compiler; - -@b{end} Prog1; -@end group -@end smallexample - -@smallexample -@group -File "prog2.gpr": - -@b{with} "common"; -@b{project} Prog2 @b{is} - - @b{for} Source_Dirs @b{use} ("prog2"); - @b{for} Object_Dir @b{use} "prog2/build/" & Common.Build; - - @b{package} Compiler @b{renames} Common.Compiler; - -@end group -@b{end} Prog2; -@end smallexample - -@item We create a wrapping project @code{Main}: - -@smallexample -@group -File "main.gpr": - -@b{with} "common"; -@b{with} "prog1"; -@b{with} "prog2"; -@b{project} Main @b{is} - - @b{package} Compiler @b{renames} Common.Compiler; - -@b{end} Main; +\TXT\ @end group @end smallexample +@end macro -@item Finally we need to create a dummy procedure that @code{with}s (either -explicitly or implicitly) all the sources of our two programs. +@macro PROJECTFILE{TXT} +@CODESAMPLE{\TXT\} +@end macro -@end enumerate +@c simulates a newline when in a @CODESAMPLE +@macro NL{} +@end macro +@macro TIP{TXT} +@quotation @noindent -Now we can build the programs using the command +\TXT\ +@end quotation +@end macro -@smallexample - gnatmake ^-P^/PROJECT_FILE=^main dummy -@end smallexample +@macro TIPHTML{TXT} +\TXT\ +@end macro +@macro IMPORTANT{TXT} +@quotation @noindent -for the Debug mode, or - -@ifclear vms -@smallexample - gnatmake -Pmain -XBUILD=release -@end smallexample -@end ifclear +\TXT\ +@end quotation -@ifset vms -@smallexample - GNAT MAKE /PROJECT_FILE=main /EXTERNAL_REFERENCE=BUILD=release -@end smallexample -@end ifset +@end macro +@macro NOTE{TXT} +@quotation @noindent -for the Release mode. - -@c ******************************** -@c * Project File Complete Syntax * -@c ******************************** - -@node Project File Complete Syntax -@section Project File Complete Syntax - -@smallexample -project ::= - context_clause project_declaration - -context_clause ::= - @{with_clause@} - -with_clause ::= - @b{with} path_name @{ , path_name @} ; - -path_name ::= - string_literal - -project_declaration ::= - simple_project_declaration | project_extension - -simple_project_declaration ::= - @b{project} <project_>simple_name @b{is} - @{declarative_item@} - @b{end} <project_>simple_name; - -project_extension ::= - @b{project} <project_>simple_name @b{extends} path_name @b{is} - @{declarative_item@} - @b{end} <project_>simple_name; - -declarative_item ::= - package_declaration | - typed_string_declaration | - other_declarative_item - -package_declaration ::= - package_spec | package_renaming - -package_spec ::= - @b{package} package_identifier @b{is} - @{simple_declarative_item@} - @b{end} package_identifier ; - -package_identifier ::= - @code{Naming} | @code{Builder} | @code{Compiler} | @code{Binder} | - @code{Linker} | @code{Finder} | @code{Cross_Reference} | - @code{^gnatls^gnatls^} | @code{IDE} | @code{Pretty_Printer} - -package_renaming ::== - @b{package} package_identifier @b{renames} - <project_>simple_name.package_identifier ; - -typed_string_declaration ::= - @b{type} <typed_string_>_simple_name @b{is} - ( string_literal @{, string_literal@} ); - -other_declarative_item ::= - attribute_declaration | - typed_variable_declaration | - variable_declaration | - case_construction - -attribute_declaration ::= - full_associative_array_declaration | - @b{for} attribute_designator @b{use} expression ; - -full_associative_array_declaration ::= - @b{for} <associative_array_attribute_>simple_name @b{use} - <project_>simple_name [ . <package_>simple_Name ] ' <attribute_>simple_name ; - -attribute_designator ::= - <simple_attribute_>simple_name | - <associative_array_attribute_>simple_name ( string_literal ) - -typed_variable_declaration ::= - <typed_variable_>simple_name : <typed_string_>name := string_expression ; - -variable_declaration ::= - <variable_>simple_name := expression; - -expression ::= - term @{& term@} - -term ::= - literal_string | - string_list | - <variable_>name | - external_value | - attribute_reference - -string_literal ::= - (same as Ada) - -string_list ::= - ( <string_>expression @{ , <string_>expression @} ) - -external_value ::= - @b{external} ( string_literal [, string_literal] ) - -attribute_reference ::= - attribute_prefix ' <simple_attribute_>simple_name [ ( literal_string ) ] - -attribute_prefix ::= - @b{project} | - <project_>simple_name | package_identifier | - <project_>simple_name . package_identifier - -case_construction ::= - @b{case} <typed_variable_>name @b{is} - @{case_item@} - @b{end case} ; - -case_item ::= - @b{when} discrete_choice_list => - @{case_construction | attribute_declaration@} - -discrete_choice_list ::= - string_literal @{| string_literal@} | - @b{others} - -name ::= - simple_name @{. simple_name@} +\TXT\ +@end quotation +@end macro -simple_name ::= - identifier (same as Ada) +@include projects.texi -@end smallexample +@c ***************************************** +@c * Cross-referencing tools +@c ***************************************** @node The Cross-Referencing Tools gnatxref and gnatfind @chapter The Cross-Referencing Tools @code{gnatxref} and @code{gnatfind} @@ -15403,7 +12004,9 @@ use the @code{gnat} driver (see @ref{The GNAT Driver and Project Files}). @noindent The command invocation for @code{gnatxref} is: @smallexample -$ gnatxref @ovar{switches} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]} +@c $ gnatxref @ovar{switches} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatxref @r{[}@var{switches}@r{]} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]} @end smallexample @noindent @@ -15467,6 +12070,13 @@ Do not look for sources in the system default directory. @cindex @option{-nostdlib} (@command{gnatxref}) Do not look for library files in the system default directory. +@item --ext=@var{extension} +@cindex @option{--ext} (@command{gnatxref}) +Specify an alternate ali file extension. The default is @code{ali} and other +extensions (e.g. @code{sli} for SPARK library files) may be specified via this +switch. Note that if this switch overrides the default, which means that only +the new extension will be considered. + @item --RTS=@var{rts-path} @cindex @option{--RTS} (@command{gnatxref}) Specifies the default location of the runtime library. Same meaning as the @@ -15495,7 +12105,7 @@ Equivalent to @samp{-aODIR -aIDIR}. @item -pFILE @cindex @option{-pFILE} (@command{gnatxref}) -Specify a project file to use @xref{Project Files}. +Specify a project file to use @xref{GNAT Project Manager}. If you need to use the @file{.gpr} project files, you should use gnatxref through the GNAT driver (@command{gnat xref -Pproject}). @@ -15535,8 +12145,11 @@ you can say @samp{gnatxref ^-ag^/ALL_FILES/IGNORE_LOCALS^} instead of The command line for @code{gnatfind} is: @smallexample -$ gnatfind @ovar{switches} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]} - @r{[}@var{file1} @var{file2} @dots{}] +@c $ gnatfind @ovar{switches} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]} +@c @r{[}@var{file1} @var{file2} @dots{}] +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatfind @r{[}@var{switches}@r{]} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]} + @r{[}@var{file1} @var{file2} @dots{}@r{]} @end smallexample @noindent @@ -15675,7 +12288,7 @@ Equivalent to @samp{-aODIR -aIDIR}. @item -pFILE @cindex @option{-pFILE} (@command{gnatfind}) -Specify a project file (@pxref{Project Files}) to use. +Specify a project file (@pxref{GNAT Project Manager}) to use. By default, @code{gnatxref} and @code{gnatfind} will try to locate a project file in the current directory. @@ -16122,7 +12735,9 @@ call @command{gnatpp} through the @command{gnat} driver The @command{gnatpp} command has the form @smallexample -$ gnatpp @ovar{switches} @var{filename} +@c $ gnatpp @ovar{switches} @var{filename} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatpp @r{[}@var{switches}@r{]} @var{filename} @r{[}-cargs @var{gcc_switches}@r{]} @end smallexample @noindent @@ -16138,6 +12753,15 @@ output source file reformat; ``wildcards'' or several file names on the same gnatpp command are allowed. The file name may contain path information; it does not have to follow the GNAT file naming rules + +@item +@samp{@var{gcc_switches}} is a list of switches for +@command{gcc}. They will be passed on to all compiler invocations made by +@command{gnatelim} to generate the ASIS trees. Here you can provide +@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path, +use the @option{-gnatec} switch to set the configuration file, +use the @option{-gnat05} switch if sources should be compiled in +Ada 2005 mode etc. @end itemize @menu @@ -16635,12 +13259,12 @@ with @option{^-pipe^/STANDARD_OUTPUT^} option. The additional @command{gnatpp} switches are defined in this subsection. @table @option -@item ^-files @var{filename}^/FILES=@var{output_file}^ +@item ^-files @var{filename}^/FILES=@var{filename}^ @cindex @option{^-files^/FILES^} (@code{gnatpp}) Take the argument source files from the specified file. This file should be an -ordinary textual file containing file names separated by spaces or -line breaks. You can use this switch more then once in the same call to -@command{gnatpp}. You also can combine this switch with explicit list of +ordinary text file containing file names separated by spaces or +line breaks. You can use this switch more than once in the same call to +@command{gnatpp}. You also can combine this switch with an explicit list of files. @item ^-v^/VERBOSE^ @@ -17224,7 +13848,9 @@ through the @command{gnat} driver. The @command{gnatmetric} command has the form @smallexample -$ gnatmetric @ovar{switches} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]} +@c $ gnatmetric @ovar{switches} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatmetric @r{[}@var{switches}@r{]} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]} @end smallexample @noindent @@ -17245,11 +13871,13 @@ Including both a @option{-files} switch and one or more @var{filename} arguments is permitted. @item -@samp{-cargs @var{gcc_switches}} is a list of switches for +@samp{@var{gcc_switches}} is a list of switches for @command{gcc}. They will be passed on to all compiler invocations made by @command{gnatmetric} to generate the ASIS trees. Here you can provide @option{^-I^/INCLUDE_DIRS=^} switches to form the source search path, -and use the @option{-gnatec} switch to set the configuration file. +and use the @option{-gnatec} switch to set the configuration file, +use the @option{-gnat05} switch if sources should be compiled in +Ada 2005 mode etc. @end itemize @menu @@ -17319,7 +13947,7 @@ Do not generate the output in text form (implies @option{^-x^/XML^}) @cindex @option{^-d^/DIRECTORY^} (@command{gnatmetric}) @item ^-d @var{output_dir}^/DIRECTORY=@var{output_dir}^ -Put textual files with detailed metrics into @var{output_dir} +Put text files with detailed metrics into @var{output_dir} @cindex @option{^-o^/SUFFIX_DETAILS^} (@command{gnatmetric}) @item ^-o @var{file_suffix}^/SUFFIX_DETAILS=@var{file_suffix}^ @@ -17896,7 +14524,7 @@ Additional @command{gnatmetric} switches are as follows: @cindex @option{^-files^/FILES^} (@code{gnatmetric}) Take the argument source files from the specified file. This file should be an ordinary text file containing file names separated by spaces or -line breaks. You can use this switch more then once in the same call to +line breaks. You can use this switch more than once in the same call to @command{gnatmetric}. You also can combine this switch with an explicit list of files. @@ -18006,7 +14634,9 @@ The @code{gnatkr} command has the form @ifclear vms @smallexample -$ gnatkr @var{name} @ovar{length} +@c $ gnatkr @var{name} @ovar{length} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatkr @var{name} @r{[}@var{length}@r{]} @end smallexample @end ifclear @@ -18194,7 +14824,9 @@ all characters need to be in the ASCII set (no accented letters). To call @code{gnatprep} use @smallexample -$ gnatprep @ovar{switches} @var{infile} @var{outfile} @ovar{deffile} +@c $ gnatprep @ovar{switches} @var{infile} @var{outfile} @ovar{deffile} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatprep @r{[}@var{switches}@r{]} @var{infile} @var{outfile} @r{[}@var{deffile}@r{]} @end smallexample @noindent @@ -18457,76 +15089,6 @@ Header : String := $XYZ; @noindent and then the substitution will occur as desired. -@ifset vms -@node The GNAT Run-Time Library Builder gnatlbr -@chapter The GNAT Run-Time Library Builder @code{gnatlbr} -@findex gnatlbr -@cindex Library builder - -@noindent -@code{gnatlbr} is a tool for rebuilding the GNAT run time with user -supplied configuration pragmas. - -@menu -* Running gnatlbr:: -* Switches for gnatlbr:: -* Examples of gnatlbr Usage:: -@end menu - -@node Running gnatlbr -@section Running @code{gnatlbr} - -@noindent -The @code{gnatlbr} command has the form - -@smallexample -$ GNAT LIBRARY /@r{[}CREATE@r{|}SET@r{|}DELETE@r{]}=directory @r{[}/CONFIG=file@r{]} -@end smallexample - -@node Switches for gnatlbr -@section Switches for @code{gnatlbr} - -@noindent -@code{gnatlbr} recognizes the following switches: - -@table @option -@c !sort! -@item /CREATE=directory -@cindex @code{/CREATE} (@code{gnatlbr}) -Create the new run-time library in the specified directory. - -@item /SET=directory -@cindex @code{/SET} (@code{gnatlbr}) -Make the library in the specified directory the current run-time library. - -@item /DELETE=directory -@cindex @code{/DELETE} (@code{gnatlbr}) -Delete the run-time library in the specified directory. - -@item /CONFIG=file -@cindex @code{/CONFIG} (@code{gnatlbr}) -With /CREATE: Use the configuration pragmas in the specified file when -building the library. - -With /SET: Use the configuration pragmas in the specified file when -compiling. - -@end table - -@node Examples of gnatlbr Usage -@section Example of @code{gnatlbr} Usage - -@smallexample -Contents of VAXFLOAT.ADC: -pragma Float_Representation (VAX_Float); - -$ GNAT LIBRARY /CREATE=[.VAXFLOAT] /CONFIG=VAXFLOAT.ADC - -GNAT LIBRARY rebuilds the run-time library in directory [.VAXFLOAT] - -@end smallexample -@end ifset - @node The GNAT Library Browser gnatls @chapter The GNAT Library Browser @code{gnatls} @findex gnatls @@ -18878,6 +15440,15 @@ Display Copyright and version, then exit disregarding all other options. If @option{--version} was not used, display usage, then exit disregarding all other options. +@item ^--subdirs^/SUBDIRS^=subdir +Actual object directory of each project file is the subdirectory subdir of the +object directory specified or defauted in the project file. + +@item ^--unchecked-shared-lib-imports^/UNCHECKED_SHARED_LIB_IMPORTS^ +By default, shared library projects are not allowed to import static library +projects. When this switch is used on the command line, this restriction is +relaxed. + @item ^-c^/COMPILER_FILES_ONLY^ @cindex @option{^-c^/COMPILER_FILES_ONLY^} (@code{gnatclean}) Only attempt to delete the files produced by the compiler, not those produced @@ -19155,46 +15726,7 @@ be accessed by the directive @option{-l@var{xxx}} at link time. @noindent If you use project files, library installation is part of the library build -process. Thus no further action is needed in order to make use of the -libraries that are built as part of the general application build. A usable -version of the library is installed in the directory specified by the -@code{Library_Dir} attribute of the library project file. - -You may want to install a library in a context different from where the library -is built. This situation arises with third party suppliers, who may want -to distribute a library in binary form where the user is not expected to be -able to recompile the library. The simplest option in this case is to provide -a project file slightly different from the one used to build the library, by -using the @code{externally_built} attribute. For instance, the project -file used to build the library in the previous section can be changed into the -following one when the library is installed: - -@smallexample @c projectfile -project My_Lib is - for Source_Dirs use ("src1", "src2"); - for Library_Name use "mylib"; - for Library_Dir use "lib"; - for Library_Kind use "dynamic"; - for Externally_Built use "true"; -end My_lib; -@end smallexample - -@noindent -This project file assumes that the directories @file{src1}, -@file{src2}, and @file{lib} exist in -the directory containing the project file. The @code{externally_built} -attribute makes it clear to the GNAT builder that it should not attempt to -recompile any of the units from this library. It allows the library provider to -restrict the source set to the minimum necessary for clients to make use of the -library as described in the first section of this chapter. It is the -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 @env{GPR_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. +process (@pxref{Installing a library with project files}). When project files are not an option, it is also possible, but not recommended, to install the library so that the sources needed to use the library are on the @@ -20170,7 +16702,9 @@ Solaris and Windows NT/2000/XP (x86). The @code{gnatmem} command has the form @smallexample - $ gnatmem @ovar{switches} user_program +@c $ gnatmem @ovar{switches} user_program +@c Expanding @ovar macro inline (explanation in macro def comments) + $ gnatmem @r{[}@var{switches}@r{]} @var{user_program} @end smallexample @noindent @@ -20698,7 +17232,11 @@ driver (see @ref{The GNAT Driver and Project Files}). Invoking @command{gnatcheck} on the command line has the form: @smallexample -$ gnatcheck @ovar{switches} @{@var{filename}@} +@c $ gnatcheck @ovar{switches} @{@var{filename}@} +@c @r{[}^-files^/FILES^=@{@var{arg_list_filename}@}@r{]} +@c @r{[}-cargs @var{gcc_switches}@r{]} -rules @var{rule_options} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatcheck @r{[}@var{switches}@r{]} @{@var{filename}@} @r{[}^-files^/FILES^=@{@var{arg_list_filename}@}@r{]} @r{[}-cargs @var{gcc_switches}@r{]} -rules @var{rule_options} @end smallexample @@ -20724,7 +17262,9 @@ or line breaks. @command{gcc}. They will be passed on to all compiler invocations made by @command{gnatcheck} to generate the ASIS trees. Here you can provide @option{^-I^/INCLUDE_DIRS=^} switches to form the source search path, -and use the @option{-gnatec} switch to set the configuration file. +and use the @option{-gnatec} switch to set the configuration file, +use the @option{-gnat05} switch if sources should be compiled in +Ada 2005 mode etc. @item @var{rule_options} is a list of options for controlling a set of @@ -20846,13 +17386,6 @@ Set name of report file file to @var{report_file} . @end table -@noindent -Note that if any of the options @option{^-s1^/COMPILER_STYLE^}, -@option{^-s2^/BY_RULES^} or -@option{^-s3^/BY_FILES_BY_RULES^} is specified, -then the @command{gnatcheck} report file will only contain sections -explicitly denoted by these options. - @node gnatcheck Rule Options @section @command{gnatcheck} Rule Options @@ -21138,1808 +17671,13 @@ release. @end ignore @noindent -The following subsections document the rules implemented in -@command{gnatcheck}. -The subsection title is the same as the rule identifier, which may be -used as a parameter of the @option{+R} or @option{-R} options. - - -@menu -* Abstract_Type_Declarations:: -* Anonymous_Arrays:: -* Anonymous_Subtypes:: -* Blocks:: -* Boolean_Relational_Operators:: -@ignore -* Ceiling_Violations:: -@end ignore -* Complex_Inlined_Subprograms:: -* Controlled_Type_Declarations:: -* Declarations_In_Blocks:: -* Deep_Inheritance_Hierarchies:: -* Deeply_Nested_Generics:: -* Deeply_Nested_Inlining:: -@ignore -* Deeply_Nested_Local_Inlining:: -@end ignore -* Default_Parameters:: -* Direct_Calls_To_Primitives:: -* Discriminated_Records:: -* Enumeration_Ranges_In_CASE_Statements:: -* Exceptions_As_Control_Flow:: -* Exits_From_Conditional_Loops:: -* EXIT_Statements_With_No_Loop_Name:: -* Expanded_Loop_Exit_Names:: -* Explicit_Full_Discrete_Ranges:: -* Float_Equality_Checks:: -* Forbidden_Attributes:: -* Forbidden_Pragmas:: -* Function_Style_Procedures:: -* Generics_In_Subprograms:: -* GOTO_Statements:: -* Implicit_IN_Mode_Parameters:: -* Implicit_SMALL_For_Fixed_Point_Types:: -* Improperly_Located_Instantiations:: -* Improper_Returns:: -* Library_Level_Subprograms:: -* Local_Packages:: -@ignore -* Improperly_Called_Protected_Entries:: -@end ignore -* Metrics:: -* Misnamed_Controlling_Parameters:: -* Misnamed_Identifiers:: -* Multiple_Entries_In_Protected_Definitions:: -* Name_Clashes:: -* Non_Qualified_Aggregates:: -* Non_Short_Circuit_Operators:: -* Non_SPARK_Attributes:: -* Non_Tagged_Derived_Types:: -* Non_Visible_Exceptions:: -* Numeric_Literals:: -* OTHERS_In_Aggregates:: -* OTHERS_In_CASE_Statements:: -* OTHERS_In_Exception_Handlers:: -* Outer_Loop_Exits:: -* Overloaded_Operators:: -* Overly_Nested_Control_Structures:: -* Parameters_Out_Of_Order:: -* Positional_Actuals_For_Defaulted_Generic_Parameters:: -* Positional_Actuals_For_Defaulted_Parameters:: -* Positional_Components:: -* Positional_Generic_Parameters:: -* Positional_Parameters:: -* Predefined_Numeric_Types:: -* Raising_External_Exceptions:: -* Raising_Predefined_Exceptions:: -* Separate_Numeric_Error_Handlers:: -@ignore -* Recursion:: -* Side_Effect_Functions:: -@end ignore -* Slices:: -* Too_Many_Parents:: -* Unassigned_OUT_Parameters:: -* Uncommented_BEGIN_In_Package_Bodies:: -* Unconditional_Exits:: -* Unconstrained_Array_Returns:: -* Universal_Ranges:: -* Unnamed_Blocks_And_Loops:: -@ignore -* Unused_Subprograms:: -@end ignore -* USE_PACKAGE_Clauses:: -* Visible_Components:: -* Volatile_Objects_Without_Address_Clauses:: -@end menu - - -@node Abstract_Type_Declarations -@subsection @code{Abstract_Type_Declarations} -@cindex @code{Abstract_Type_Declarations} rule (for @command{gnatcheck}) - -@noindent -Flag all declarations of abstract types. For an abstract private -type, both the private and full type declarations are flagged. - -This rule has no parameters. - - -@node Anonymous_Arrays -@subsection @code{Anonymous_Arrays} -@cindex @code{Anonymous_Arrays} rule (for @command{gnatcheck}) - -@noindent -Flag all anonymous array type definitions (by Ada semantics these can only -occur in object declarations). - -This rule has no parameters. - -@node Anonymous_Subtypes -@subsection @code{Anonymous_Subtypes} -@cindex @code{Anonymous_Subtypes} rule (for @command{gnatcheck}) - -@noindent -Flag all uses of anonymous subtypes (except cases when subtype indication -is a part of a record component definition, and this subtype indication -depends on a discriminant). A use of an anonymous subtype is -any instance of a subtype indication with a constraint, other than one -that occurs immediately within a subtype declaration. Any use of a range -other than as a constraint used immediately within a subtype declaration -is considered as an anonymous subtype. - -An effect of this rule is that @code{for} loops such as the following are -flagged (since @code{1..N} is formally a ``range''): - -@smallexample @c ada -for I in 1 .. N loop - @dots{} -end loop; -@end smallexample - -@noindent -Declaring an explicit subtype solves the problem: - -@smallexample @c ada -subtype S is Integer range 1..N; -@dots{} -for I in S loop - @dots{} -end loop; -@end smallexample - -@noindent -This rule has no parameters. - -@node Blocks -@subsection @code{Blocks} -@cindex @code{Blocks} rule (for @command{gnatcheck}) - -@noindent -Flag each block statement. - -This rule has no parameters. - -@node Boolean_Relational_Operators -@subsection @code{Boolean_Relational_Operators} -@cindex @code{Boolean_Relational_Operators} rule (for @command{gnatcheck}) - -@noindent -Flag each call to a predefined relational operator (``<'', ``>'', ``<='', -``>='', ``='' and ``/='') for the predefined Boolean type. -(This rule is useful in enforcing the SPARK language restrictions.) - -Calls to predefined relational operators of any type derived from -@code{Standard.Boolean} are not detected. Calls to user-defined functions -with these designators, and uses of operators that are renamings -of the predefined relational operators for @code{Standard.Boolean}, -are likewise not detected. - -This rule has no parameters. - -@ignore -@node Ceiling_Violations -@subsection @code{Ceiling5_Violations} (under construction, GLOBAL) -@cindex @code{Ceiling_Violations} rule (for @command{gnatcheck}) - -@noindent -Flag invocations of a protected operation by a task whose priority exceeds -the protected object's ceiling. - -As of @value{NOW}, this rule has the following limitations: - -@itemize @bullet - -@item - We consider only pragmas Priority and Interrupt_Priority as means to define - a task/protected operation priority. We do not consider the effect of using - Ada.Dynamic_Priorities.Set_Priority procedure; - -@item - We consider only base task priorities, and no priority inheritance. That is, - we do not make a difference between calls issued during task activation and - execution of the sequence of statements from task body; - -@item - Any situation when the priority of protected operation caller is set by a - dynamic expression (that is, the corresponding Priority or - Interrupt_Priority pragma has a non-static expression as an argument) we - treat as a priority inconsistency (and, therefore, detect this situation). -@end itemize - -@noindent -At the moment the notion of the main subprogram is not implemented in -gnatcheck, so any pragma Priority in a library level subprogram body (in case -if this subprogram can be a main subprogram of a partition) changes the -priority of an environment task. So if we have more then one such pragma in -the set of processed sources, the pragma that is processed last, defines the -priority of an environment task. - -This rule has no parameters. -@end ignore - -@node Controlled_Type_Declarations -@subsection @code{Controlled_Type_Declarations} -@cindex @code{Controlled_Type_Declarations} rule (for @command{gnatcheck}) - -@noindent -Flag all declarations of controlled types. A declaration of a private type -is flagged if its full declaration declares a controlled type. A declaration -of a derived type is flagged if its ancestor type is controlled. Subtype -declarations are not checked. A declaration of a type that itself is not a -descendant of a type declared in @code{Ada.Finalization} but has a controlled -component is not checked. - -This rule has no parameters. - - -@node Complex_Inlined_Subprograms -@subsection @code{Complex_Inlined_Subprograms} -@cindex @code{Complex_Inlined_Subprograms} rule (for @command{gnatcheck}) - -@noindent -Flags a subprogram (or generic subprogram) if -pragma Inline is applied to the subprogram and at least one of the following -conditions is met: - -@itemize @bullet -@item -it contains at least one complex declaration such as a subprogram body, -package, task, protected declaration, or a generic instantiation -(except instantiation of @code{Ada.Unchecked_Conversion}); - -@item -it contains at least one complex statement such as a loop, a case -or a if statement, or a short circuit control form; - -@item -the number of statements exceeds -a value specified by the @option{N} rule parameter; -@end itemize - -@noindent -This rule has the following (mandatory) parameter for the @option{+R} option: - -@table @emph -@item N -Positive integer specifying the maximum allowed total number of statements -in the subprogram body. -@end table - - -@node Declarations_In_Blocks -@subsection @code{Declarations_In_Blocks} -@cindex @code{Declarations_In_Blocks} rule (for @command{gnatcheck}) - -@noindent -Flag all block statements containing local declarations. A @code{declare} -block with an empty @i{declarative_part} or with a @i{declarative part} -containing only pragmas and/or @code{use} clauses is not flagged. - -This rule has no parameters. - - -@node Deep_Inheritance_Hierarchies -@subsection @code{Deep_Inheritance_Hierarchies} -@cindex @code{Deep_Inheritance_Hierarchies} rule (for @command{gnatcheck}) - -@noindent -Flags a tagged derived type declaration or an interface type declaration if -its depth (in its inheritance -hierarchy) exceeds the value specified by the @option{N} rule parameter. - -The inheritance depth of a tagged type or interface type is defined as 0 for -a type with no parent and no progenitor, and otherwise as 1 + max of the -depths of the immediate parent and immediate progenitors. - -This rule does not flag private extension -declarations. In the case of a private extension, the corresponding full -declaration is checked. - -This rule has the following (mandatory) parameter for the @option{+R} option: - -@table @emph -@item N -Integer not less than -1 specifying the maximal allowed depth of any inheritance -hierarchy. If the rule parameter is set to -1, the rule flags all the declarations -of tagged and interface types. -@end table - - -@node Deeply_Nested_Generics -@subsection @code{Deeply_Nested_Generics} -@cindex @code{Deeply_Nested_Generics} rule (for @command{gnatcheck}) - -@noindent -Flags a generic declaration nested in another generic declaration if -the nesting level of the inner generic exceeds -a value specified by the @option{N} rule parameter. -The nesting level is the number of generic declaratons that enclose the given -(generic) declaration. Formal packages are not flagged by this rule. - -This rule has the following (mandatory) parameters for the @option{+R} option: - -@table @emph -@item N -Positive integer specifying the maximal allowed nesting level -for a generic declaration. -@end table - -@node Deeply_Nested_Inlining -@subsection @code{Deeply_Nested_Inlining} -@cindex @code{Deeply_Nested_Inlining} rule (for @command{gnatcheck}) - -@noindent -Flags a subprogram (or generic subprogram) if -pragma Inline has been applied to the subprogram but the subprogram -calls to another inlined subprogram that results in nested inlining -with nesting depth exceeding the value specified by the -@option{N} rule parameter. - -This rule requires the global analysis of all the compilation units that -are @command{gnatcheck} arguments; such analysis may affect the tool's -performance. - -This rule has the following (mandatory) parameter for the @option{+R} option: - -@table @emph -@item N -Positive integer specifying the maximal allowed level of nested inlining. -@end table - - -@ignore -@node Deeply_Nested_Local_Inlining -@subsection @code{Deeply_Nested_Local_Inlining} -@cindex @code{Deeply_Nested_Local_Inlining} rule (for @command{gnatcheck}) - -@noindent -Flags a subprogram body if a pragma @code{Inline} is applied to the -corresponding subprogram (or generic subprogram) and the body contains a call -to another inlined subprogram that results in nested inlining with nesting -depth more then a value specified by the @option{N} rule parameter. -This rule is similar to @code{Deeply_Nested_Inlining} rule, but it -assumes that calls to subprograms in -with'ed units are not inlided, so all the analysis of the depth of inlining is -limited by the compilation unit where the subprogram body is located and the -units it depends semantically upon. Such analysis may be usefull for the case -when neiter @option{-gnatn} nor @option{-gnatN} option is used when building -the executable. - -This rule has the following (mandatory) parameters for the @option{+R} option: - -@table @emph -@item N -Positive integer specifying the maximal allowed level of nested inlining. -@end table - -@end ignore - -@node Default_Parameters -@subsection @code{Default_Parameters} -@cindex @code{Default_Parameters} rule (for @command{gnatcheck}) - -@noindent -Flag all default expressions for subprogram parameters. Parameter -declarations of formal and generic subprograms are also checked. - -This rule has no parameters. - - -@node Direct_Calls_To_Primitives -@subsection @code{Direct_Calls_To_Primitives} -@cindex @code{Direct_Calls_To_Primitives} rule (for @command{gnatcheck}) - -@noindent -Flags any non-dispatching call to a dispatching primitive operation, except -for the common idiom where a primitive subprogram for a tagged type -directly calls the same primitive subprogram of the type's immediate ancestor. - -This rule has no parameters. - - -@node Discriminated_Records -@subsection @code{Discriminated_Records} -@cindex @code{Discriminated_Records} rule (for @command{gnatcheck}) - -@noindent -Flag all declarations of record types with discriminants. Only the -declarations of record and record extension types are checked. Incomplete, -formal, private, derived and private extension type declarations are not -checked. Task and protected type declarations also are not checked. - -This rule has no parameters. - - -@node Enumeration_Ranges_In_CASE_Statements -@subsection @code{Enumeration_Ranges_In_CASE_Statements} -@cindex @code{Enumeration_Ranges_In_CASE_Statements} (for @command{gnatcheck}) - -@noindent -Flag each use of a range of enumeration literals as a choice in a -@code{case} statement. -All forms for specifying a range (explicit ranges -such as @code{A .. B}, subtype marks and @code{'Range} attributes) are flagged. -An enumeration range is -flagged even if contains exactly one enumeration value or no values at all. A -type derived from an enumeration type is considered as an enumeration type. - -This rule helps prevent maintenance problems arising from adding an -enumeration value to a type and having it implicitly handled by an existing -@code{case} statement with an enumeration range that includes the new literal. - -This rule has no parameters. - - -@node Exceptions_As_Control_Flow -@subsection @code{Exceptions_As_Control_Flow} -@cindex @code{Exceptions_As_Control_Flow} (for @command{gnatcheck}) - -@noindent -Flag each place where an exception is explicitly raised and handled in the -same subprogram body. A @code{raise} statement in an exception handler, -package body, task body or entry body is not flagged. - -The rule has no parameters. - -@node Exits_From_Conditional_Loops -@subsection @code{Exits_From_Conditional_Loops} -@cindex @code{Exits_From_Conditional_Loops} (for @command{gnatcheck}) - -@noindent -Flag any exit statement if it transfers the control out of a @code{for} loop -or a @code{while} loop. This includes cases when the @code{exit} statement -applies to a @code{FOR} or @code{while} loop, and cases when it is enclosed -in some @code{for} or @code{while} loop, but transfers the control from some -outer (inconditional) @code{loop} statement. - -The rule has no parameters. - - -@node EXIT_Statements_With_No_Loop_Name -@subsection @code{EXIT_Statements_With_No_Loop_Name} -@cindex @code{EXIT_Statements_With_No_Loop_Name} (for @command{gnatcheck}) - -@noindent -Flag each @code{exit} statement that does not specify the name of the loop -being exited. - -The rule has no parameters. - - -@node Expanded_Loop_Exit_Names -@subsection @code{Expanded_Loop_Exit_Names} -@cindex @code{Expanded_Loop_Exit_Names} rule (for @command{gnatcheck}) - -@noindent -Flag all expanded loop names in @code{exit} statements. - -This rule has no parameters. - -@node Explicit_Full_Discrete_Ranges -@subsection @code{Explicit_Full_Discrete_Ranges} -@cindex @code{Explicit_Full_Discrete_Ranges} rule (for @command{gnatcheck}) - -@noindent -Flag each discrete range that has the form @code{A'First .. A'Last}. - -This rule has no parameters. - -@node Float_Equality_Checks -@subsection @code{Float_Equality_Checks} -@cindex @code{Float_Equality_Checks} rule (for @command{gnatcheck}) - -@noindent -Flag all calls to the predefined equality operations for floating-point types. -Both ``@code{=}'' and ``@code{/=}'' operations are checked. -User-defined equality operations are not flagged, nor are ``@code{=}'' -and ``@code{/=}'' operations for fixed-point types. - -This rule has no parameters. - - -@node Forbidden_Attributes -@subsection @code{Forbidden_Attributes} -@cindex @code{Forbidden_Attributes} rule (for @command{gnatcheck}) - -@noindent -Flag each use of the specified attributes. The attributes to be detected are -named in the rule's parameters. - -This rule has the following parameters: - -@itemize @bullet -@item For the @option{+R} option - -@table @asis -@item @emph{Attribute_Designator} -Adds the specified attribute to the set of attributes to be detected and sets -the detection checks for all the specified attributes ON. -If @emph{Attribute_Designator} -does not denote any attribute defined in the Ada standard -or in -@ref{Implementation Defined Attributes,,, gnat_rm, GNAT Reference -Manual}, it is treated as the name of unknown attribute. - -@item @code{GNAT} -All the GNAT-specific attributes are detected; this sets -the detection checks for all the specified attributes ON. - -@item @code{ALL} -All attributes are detected; this sets the rule ON. -@end table - -@item For the @option{-R} option -@table @asis -@item @emph{Attribute_Designator} -Removes the specified attribute from the set of attributes to be -detected without affecting detection checks for -other attributes. If @emph{Attribute_Designator} does not correspond to any -attribute defined in the Ada standard or in -@ref{Implementation Defined Attributes,,, gnat_rm, GNAT Reference Manual}, -this option is treated as turning OFF detection of all unknown attributes. - -@item GNAT -Turn OFF detection of all GNAT-specific attributes - -@item ALL -Clear the list of the attributes to be detected and -turn the rule OFF. -@end table -@end itemize - -@noindent -Parameters are not case sensitive. If @emph{Attribute_Designator} does not -have the syntax of an Ada identifier and therefore can not be considered as a -(part of an) attribute designator, a diagnostic message is generated and the -corresponding parameter is ignored. (If an attribute allows a static -expression to be a part of the attribute designator, this expression is -ignored by this rule.) - -When more then one parameter is given in the same rule option, the parameters -must be separated by commas. - -If more then one option for this rule is specified for the gnatcheck call, a -new option overrides the previous one(s). - -The @option{+R} option with no parameters turns the rule ON, with the set of -attributes to be detected defined by the previous rule options. -(By default this set is empty, so if the only option specified for the rule is -@option{+RForbidden_Attributes} (with -no parameter), then the rule is enabled, but it does not detect anything). -The @option{-R} option with no parameter turns the rule OFF, but it does not -affect the set of attributes to be detected. - - -@node Forbidden_Pragmas -@subsection @code{Forbidden_Pragmas} -@cindex @code{Forbidden_Pragmas} rule (for @command{gnatcheck}) - -@noindent -Flag each use of the specified pragmas. The pragmas to be detected -are named in the rule's parameters. - -This rule has the following parameters: - -@itemize @bullet -@item For the @option{+R} option - -@table @asis -@item @emph{Pragma_Name} -Adds the specified pragma to the set of pragmas to be -checked and sets the checks for all the specified pragmas -ON. @emph{Pragma_Name} is treated as a name of a pragma. If it -does not correspond to any pragma name defined in the Ada -standard or to the name of a GNAT-specific pragma defined -in @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference -Manual}, it is treated as the name of unknown pragma. - -@item @code{GNAT} -All the GNAT-specific pragmas are detected; this sets -the checks for all the specified pragmas ON. - -@item @code{ALL} -All pragmas are detected; this sets the rule ON. -@end table - -@item For the @option{-R} option -@table @asis -@item @emph{Pragma_Name} -Removes the specified pragma from the set of pragmas to be -checked without affecting checks for -other pragmas. @emph{Pragma_Name} is treated as a name -of a pragma. If it does not correspond to any pragma -defined in the Ada standard or to any name defined in -@ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual}, -this option is treated as turning OFF detection of all unknown pragmas. - -@item GNAT -Turn OFF detection of all GNAT-specific pragmas - -@item ALL -Clear the list of the pragmas to be detected and -turn the rule OFF. -@end table -@end itemize - -@noindent -Parameters are not case sensitive. If @emph{Pragma_Name} does not have -the syntax of an Ada identifier and therefore can not be considered -as a pragma name, a diagnostic message is generated and the corresponding -parameter is ignored. - -When more then one parameter is given in the same rule option, the parameters -must be separated by a comma. - -If more then one option for this rule is specified for the @command{gnatcheck} -call, a new option overrides the previous one(s). - -The @option{+R} option with no parameters turns the rule ON with the set of -pragmas to be detected defined by the previous rule options. -(By default this set is empty, so if the only option specified for the rule is -@option{+RForbidden_Pragmas} (with -no parameter), then the rule is enabled, but it does not detect anything). -The @option{-R} option with no parameter turns the rule OFF, but it does not -affect the set of pragmas to be detected. - - - - -@node Function_Style_Procedures -@subsection @code{Function_Style_Procedures} -@cindex @code{Function_Style_Procedures} rule (for @command{gnatcheck}) - -@noindent -Flag each procedure that can be rewritten as a function. A procedure can be -converted into a function if it has exactly one parameter of mode @code{out} -and no parameters of mode @code{in out}. Procedure declarations, -formal procedure declarations, and generic procedure declarations are always -checked. Procedure -bodies and body stubs are flagged only if they do not have corresponding -separate declarations. Procedure renamings and procedure instantiations are -not flagged. - -If a procedure can be rewritten as a function, but its @code{out} parameter is -of a limited type, it is not flagged. - -Protected procedures are not flagged. Null procedures also are not flagged. - -This rule has no parameters. - - -@node Generics_In_Subprograms -@subsection @code{Generics_In_Subprograms} -@cindex @code{Generics_In_Subprograms} rule (for @command{gnatcheck}) - -@noindent -Flag each declaration of a generic unit in a subprogram. Generic -declarations in the bodies of generic subprograms are also flagged. -A generic unit nested in another generic unit is not flagged. -If a generic unit is -declared in a local package that is declared in a subprogram body, the -generic unit is flagged. - -This rule has no parameters. - - -@node GOTO_Statements -@subsection @code{GOTO_Statements} -@cindex @code{GOTO_Statements} rule (for @command{gnatcheck}) - -@noindent -Flag each occurrence of a @code{goto} statement. - -This rule has no parameters. - - -@node Implicit_IN_Mode_Parameters -@subsection @code{Implicit_IN_Mode_Parameters} -@cindex @code{Implicit_IN_Mode_Parameters} rule (for @command{gnatcheck}) - -@noindent -Flag each occurrence of a formal parameter with an implicit @code{in} mode. -Note that @code{access} parameters, although they technically behave -like @code{in} parameters, are not flagged. - -This rule has no parameters. - - -@node Implicit_SMALL_For_Fixed_Point_Types -@subsection @code{Implicit_SMALL_For_Fixed_Point_Types} -@cindex @code{Implicit_SMALL_For_Fixed_Point_Types} rule (for @command{gnatcheck}) - -@noindent -Flag each fixed point type declaration that lacks an explicit -representation clause to define its @code{'Small} value. -Since @code{'Small} can be defined only for ordinary fixed point types, -decimal fixed point type declarations are not checked. - -This rule has no parameters. - - -@node Improperly_Located_Instantiations -@subsection @code{Improperly_Located_Instantiations} -@cindex @code{Improperly_Located_Instantiations} rule (for @command{gnatcheck}) - -@noindent -Flag all generic instantiations in library-level package specs -(including library generic packages) and in all subprogram bodies. - -Instantiations in task and entry bodies are not flagged. Instantiations in the -bodies of protected subprograms are flagged. - -This rule has no parameters. - - - -@node Improper_Returns -@subsection @code{Improper_Returns} -@cindex @code{Improper_Returns} rule (for @command{gnatcheck}) - -@noindent -Flag each explicit @code{return} statement in procedures, and -multiple @code{return} statements in functions. -Diagnostic messages are generated for all @code{return} statements -in a procedure (thus each procedure must be written so that it -returns implicitly at the end of its statement part), -and for all @code{return} statements in a function after the first one. -This rule supports the stylistic convention that each subprogram -should have no more than one point of normal return. - -This rule has no parameters. - - -@node Library_Level_Subprograms -@subsection @code{Library_Level_Subprograms} -@cindex @code{Library_Level_Subprograms} rule (for @command{gnatcheck}) - -@noindent -Flag all library-level subprograms (including generic subprogram instantiations). - -This rule has no parameters. - - -@node Local_Packages -@subsection @code{Local_Packages} -@cindex @code{Local_Packages} rule (for @command{gnatcheck}) - -@noindent -Flag all local packages declared in package and generic package -specs. -Local packages in bodies are not flagged. - -This rule has no parameters. - -@ignore -@node Improperly_Called_Protected_Entries -@subsection @code{Improperly_Called_Protected_Entries} (under construction, GLOBAL) -@cindex @code{Improperly_Called_Protected_Entries} rule (for @command{gnatcheck}) - -@noindent -Flag each protected entry that can be called from more than one task. - -This rule has no parameters. -@end ignore - -@node Metrics -@subsection @code{Metrics} -@cindex @code{Metrics} rule (for @command{gnatcheck}) - -@noindent -There is a set of checks based on computing a metric value and comparing the -result with the specified upper (or lower, depending on a specific metric) -value specified for a given metric. A construct is flagged if a given metric -is applicable (can be computed) for it and the computed value is greater -then (lover then) the specified upper (lower) bound. - -The name of any metric-based rule consists of the prefix @code{Metrics_} -followed by the name of the corresponding metric (see the table below). -For @option{+R} option, each metric-based rule has a numeric parameter -specifying the bound (integer or real, depending on a metric), @option{-R} -option for metric rules does not have a parameter. - -The following table shows the metric names for that the corresponding -metrics-based checks are supported by gnatcheck, including the -constraint that must be satisfied by the bound that is specified for the check -and what bound - upper (U) or lower (L) - should be specified. - -@multitable {@code{Cyclomatic_Complexity}}{Cyclomatic complexity}{Positive integer} -@ifnothtml -@headitem Check Name @tab Description @tab Bounds Value -@end ifnothtml -@ifhtml -@item @b{Check Name} @tab @b{Description} @tab @b{Bounds Value} -@end ifhtml -@c Above conditional code is workaround to bug in texi2html (Feb 2008) -@item @code{Essential_Complexity} @tab Essential complexity @tab Positive integer (U) -@item @code{Cyclomatic_Complexity} @tab Cyclomatic complexity @tab Positive integer (U) -@item @code{LSLOC} @tab Logical Source Lines of Code @tab Positive integer (U) -@end multitable - -@noindent -The meaning and the computed values for all these metrics are exactly -the same as for the corresponding metrics in @command{gnatmetric}. - -@emph{Example:} the rule -@smallexample -+RMetrics_Cyclomatic_Complexity : 7 -@end smallexample -@noindent -means that all bodies with cyclomatic complexity exceeding 7 will be flagged. - -To turn OFF the check for cyclomatic complexity metric, use the following option: -@smallexample --RMetrics_Cyclomatic_Complexity -@end smallexample - - -@node Misnamed_Controlling_Parameters -@subsection @code{Misnamed_Controlling_Parameters} -@cindex @code{Misnamed_Controlling_Parameters} rule (for @command{gnatcheck}) - -@noindent -Flags a declaration of a dispatching operation, if the first parameter is -not a controlling one and its name is not @code{This} (the check for -parameter name is not case-sensitive). Declarations of dispatching functions -with controlling result and no controlling parameter are never flagged. - -A subprogram body declaration, subprogram renaming declaration or subprogram -body stub is flagged only if it is not a completion of a prior subprogram -declaration. - -This rule has no parameters. - - - -@node Misnamed_Identifiers -@subsection @code{Misnamed_Identifiers} -@cindex @code{Misnamed_Identifiers} rule (for @command{gnatcheck}) - -@noindent -Flag the declaration of each identifier that does not have a suffix -corresponding to the kind of entity being declared. -The following declarations are checked: - -@itemize @bullet -@item -type declarations - -@item -subtype declarations - -@item -constant declarations (but not number declarations) - -@item -package renaming declarations (but not generic package renaming -declarations) -@end itemize - -@noindent -This rule may have parameters. When used without parameters, the rule enforces -the following checks: - -@itemize @bullet -@item -type-defining names end with @code{_T}, unless the type is an access type, -in which case the suffix must be @code{_A} -@item -constant names end with @code{_C} -@item -names defining package renamings end with @code{_R} -@end itemize - -@noindent -Defining identifiers from incomplete type declarations are never flagged. - -For a private type declaration (including private extensions), the defining -identifier from the private type declaration is checked against the type -suffix (even if the corresponding full declaration is an access type -declaration), and the defining identifier from the corresponding full type -declaration is not checked. - -@noindent -For a deferred constant, the defining name in the corresponding full constant -declaration is not checked. - -Defining names of formal types are not checked. - -The rule may have the following parameters: - -@itemize @bullet -@item -For the @option{+R} option: -@table @code -@item Default -Sets the default listed above for all the names to be checked. - -@item Type_Suffix=@emph{string} -Specifies the suffix for a type name. - -@item Access_Suffix=@emph{string} -Specifies the suffix for an access type name. If -this parameter is set, it overrides for access -types the suffix set by the @code{Type_Suffix} parameter. -For access types, @emph{string} may have the following format: -@emph{suffix1(suffix2)}. That means that an access type name -should have the @emph{suffix1} suffix except for the case when -the designated type is also an access type, in this case the -type name should have the @emph{suffix1 & suffix2} suffix. - -@item Class_Access_Suffix=@emph{string} -Specifies the suffix for the name of an access type that points to some class-wide -type. If this parameter is set, it overrides for such access -types the suffix set by the @code{Type_Suffix} or @code{Access_Suffix} -parameter. - -@item Class_Subtype_Suffix=@emph{string} -Specifies the suffix for the name of a subtype that denotes a class-wide type. - -@item Constant_Suffix=@emph{string} -Specifies the suffix for a constant name. - -@item Renaming_Suffix=@emph{string} -Specifies the suffix for a package renaming name. -@end table - -@item -For the @option{-R} option: -@table @code -@item All_Suffixes -Remove all the suffixes specified for the -identifier suffix checks, whether by default or -as specified by other rule parameters. All the -checks for this rule are disabled as a result. - -@item Type_Suffix -Removes the suffix specified for types. This -disables checks for types but does not disable -any other checks for this rule (including the -check for access type names if @code{Access_Suffix} is -set). - -@item Access_Suffix -Removes the suffix specified for access types. -This disables checks for access type names but -does not disable any other checks for this rule. -If @code{Type_Suffix} is set, access type names are -checked as ordinary type names. - -@item Class_Access_Suffix -Removes the suffix specified for access types pointing to class-wide -type. This disables specific checks for names of access types pointing to -class-wide types but does not disable any other checks for this rule. -If @code{Type_Suffix} is set, access type names are -checked as ordinary type names. If @code{Access_Suffix} is set, these -access types are checked as any other access type name. - -@item Class_Subtype_Suffix=@emph{string} -Removes the suffix specified for subtype names. -This disables checks for subtype names but -does not disable any other checks for this rule. - -@item Constant_Suffix -Removes the suffix specified for constants. This -disables checks for constant names but does not -disable any other checks for this rule. - -@item Renaming_Suffix -Removes the suffix specified for package -renamings. This disables checks for package -renamings but does not disable any other checks -for this rule. -@end table -@end itemize - -@noindent -If more than one parameter is used, parameters must be separated by commas. - -If more than one option is specified for the @command{gnatcheck} invocation, -a new option overrides the previous one(s). - -The @option{+RMisnamed_Identifiers} option (with no parameter) enables -checks for all the -name suffixes specified by previous options used for this rule. - -The @option{-RMisnamed_Identifiers} option (with no parameter) disables -all the checks but keeps -all the suffixes specified by previous options used for this rule. - -The @emph{string} value must be a valid suffix for an Ada identifier (after -trimming all the leading and trailing space characters, if any). -Parameters are not case sensitive, except the @emph{string} part. - -If any error is detected in a rule parameter, the parameter is ignored. -In such a case the options that are set for the rule are not -specified. - - - -@node Multiple_Entries_In_Protected_Definitions -@subsection @code{Multiple_Entries_In_Protected_Definitions} -@cindex @code{Multiple_Entries_In_Protected_Definitions} rule (for @command{gnatcheck}) - -@noindent -Flag each protected definition (i.e., each protected object/type declaration) -that defines more than one entry. -Diagnostic messages are generated for all the entry declarations -except the first one. An entry family is counted as one entry. Entries from -the private part of the protected definition are also checked. - -This rule has no parameters. - -@node Name_Clashes -@subsection @code{Name_Clashes} -@cindex @code{Name_Clashes} rule (for @command{gnatcheck}) - -@noindent -Check that certain names are not used as defining identifiers. To activate -this rule, you need to supply a reference to the dictionary file(s) as a rule -parameter(s) (more then one dictionary file can be specified). If no -dictionary file is set, this rule will not cause anything to be flagged. -Only defining occurrences, not references, are checked. -The check is not case-sensitive. - -This rule is enabled by default, but without setting any corresponding -dictionary file(s); thus the default effect is to do no checks. - -A dictionary file is a plain text file. The maximum line length for this file -is 1024 characters. If the line is longer then this limit, extra characters -are ignored. - -Each line can be either an empty line, a comment line, or a line containing -a list of identifiers separated by space or HT characters. -A comment is an Ada-style comment (from @code{--} to end-of-line). -Identifiers must follow the Ada syntax for identifiers. -A line containing one or more identifiers may end with a comment. - -@node Non_Qualified_Aggregates -@subsection @code{Non_Qualified_Aggregates} -@cindex @code{Non_Qualified_Aggregates} rule (for @command{gnatcheck}) - -@noindent -Flag each non-qualified aggregate. -A non-qualified aggregate is an -aggregate that is not the expression of a qualified expression. A -string literal is not considered an aggregate, but an array -aggregate of a string type is considered as a normal aggregate. -Aggregates of anonymous array types are not flagged. - -This rule has no parameters. - - -@node Non_Short_Circuit_Operators -@subsection @code{Non_Short_Circuit_Operators} -@cindex @code{Non_Short_Circuit_Operators} rule (for @command{gnatcheck}) - -@noindent -Flag all calls to predefined @code{and} and @code{or} operators for -any boolean type. Calls to -user-defined @code{and} and @code{or} and to operators defined by renaming -declarations are not flagged. Calls to predefined @code{and} and @code{or} -operators for modular types or boolean array types are not flagged. - -This rule has no parameters. - - - -@node Non_SPARK_Attributes -@subsection @code{Non_SPARK_Attributes} -@cindex @code{Non_SPARK_Attributes} rule (for @command{gnatcheck}) - -@noindent -The SPARK language defines the following subset of Ada 95 attribute -designators as those that can be used in SPARK programs. The use of -any other attribute is flagged. - -@itemize @bullet -@item @code{'Adjacent} -@item @code{'Aft} -@item @code{'Base} -@item @code{'Ceiling} -@item @code{'Component_Size} -@item @code{'Compose} -@item @code{'Copy_Sign} -@item @code{'Delta} -@item @code{'Denorm} -@item @code{'Digits} -@item @code{'Exponent} -@item @code{'First} -@item @code{'Floor} -@item @code{'Fore} -@item @code{'Fraction} -@item @code{'Last} -@item @code{'Leading_Part} -@item @code{'Length} -@item @code{'Machine} -@item @code{'Machine_Emax} -@item @code{'Machine_Emin} -@item @code{'Machine_Mantissa} -@item @code{'Machine_Overflows} -@item @code{'Machine_Radix} -@item @code{'Machine_Rounds} -@item @code{'Max} -@item @code{'Min} -@item @code{'Model} -@item @code{'Model_Emin} -@item @code{'Model_Epsilon} -@item @code{'Model_Mantissa} -@item @code{'Model_Small} -@item @code{'Modulus} -@item @code{'Pos} -@item @code{'Pred} -@item @code{'Range} -@item @code{'Remainder} -@item @code{'Rounding} -@item @code{'Safe_First} -@item @code{'Safe_Last} -@item @code{'Scaling} -@item @code{'Signed_Zeros} -@item @code{'Size} -@item @code{'Small} -@item @code{'Succ} -@item @code{'Truncation} -@item @code{'Unbiased_Rounding} -@item @code{'Val} -@item @code{'Valid} -@end itemize - -@noindent -This rule has no parameters. - - -@node Non_Tagged_Derived_Types -@subsection @code{Non_Tagged_Derived_Types} -@cindex @code{Non_Tagged_Derived_Types} rule (for @command{gnatcheck}) - -@noindent -Flag all derived type declarations that do not have a record extension part. - -This rule has no parameters. - - - -@node Non_Visible_Exceptions -@subsection @code{Non_Visible_Exceptions} -@cindex @code{Non_Visible_Exceptions} rule (for @command{gnatcheck}) - -@noindent -Flag constructs leading to the possibility of propagating an exception -out of the scope in which the exception is declared. -Two cases are detected: - -@itemize @bullet -@item -An exception declaration in a subprogram body, task body or block -statement is flagged if the body or statement does not contain a handler for -that exception or a handler with an @code{others} choice. - -@item -A @code{raise} statement in an exception handler of a subprogram body, -task body or block statement is flagged if it (re)raises a locally -declared exception. This may occur under the following circumstances: -@itemize @minus -@item -it explicitly raises a locally declared exception, or -@item -it does not specify an exception name (i.e., it is simply @code{raise;}) -and the enclosing handler contains a locally declared exception in its -exception choices. -@end itemize -@end itemize - -@noindent -Renamings of local exceptions are not flagged. - -This rule has no parameters. - - -@node Numeric_Literals -@subsection @code{Numeric_Literals} -@cindex @code{Numeric_Literals} rule (for @command{gnatcheck}) - -@noindent -Flag each use of a numeric literal in an index expression, and in any -circumstance except for the following: - -@itemize @bullet -@item -a literal occurring in the initialization expression for a constant -declaration or a named number declaration, or - -@item -an integer literal that is less than or equal to a value -specified by the @option{N} rule parameter. -@end itemize - -@noindent -This rule may have the following parameters for the @option{+R} option: - -@table @asis -@item @emph{N} -@emph{N} is an integer literal used as the maximal value that is not flagged -(i.e., integer literals not exceeding this value are allowed) - -@item @code{ALL} -All integer literals are flagged -@end table - -@noindent -If no parameters are set, the maximum unflagged value is 1. - -The last specified check limit (or the fact that there is no limit at -all) is used when multiple @option{+R} options appear. - -The @option{-R} option for this rule has no parameters. -It disables the rule but retains the last specified maximum unflagged value. -If the @option{+R} option subsequently appears, this value is used as the -threshold for the check. - - -@node OTHERS_In_Aggregates -@subsection @code{OTHERS_In_Aggregates} -@cindex @code{OTHERS_In_Aggregates} rule (for @command{gnatcheck}) - -@noindent -Flag each use of an @code{others} choice in extension aggregates. -In record and array aggregates, an @code{others} choice is flagged unless -it is used to refer to all components, or to all but one component. - -If, in case of a named array aggregate, there are two associations, one -with an @code{others} choice and another with a discrete range, the -@code{others} choice is flagged even if the discrete range specifies -exactly one component; for example, @code{(1..1 => 0, others => 1)}. - -This rule has no parameters. - -@node OTHERS_In_CASE_Statements -@subsection @code{OTHERS_In_CASE_Statements} -@cindex @code{OTHERS_In_CASE_Statements} rule (for @command{gnatcheck}) - -@noindent -Flag any use of an @code{others} choice in a @code{case} statement. - -This rule has no parameters. - -@node OTHERS_In_Exception_Handlers -@subsection @code{OTHERS_In_Exception_Handlers} -@cindex @code{OTHERS_In_Exception_Handlers} rule (for @command{gnatcheck}) - -@noindent -Flag any use of an @code{others} choice in an exception handler. - -This rule has no parameters. - - -@node Outer_Loop_Exits -@subsection @code{Outer_Loop_Exits} -@cindex @code{Outer_Loop_Exits} rule (for @command{gnatcheck}) - -@noindent -Flag each @code{exit} statement containing a loop name that is not the name -of the immediately enclosing @code{loop} statement. - -This rule has no parameters. - - -@node Overloaded_Operators -@subsection @code{Overloaded_Operators} -@cindex @code{Overloaded_Operators} rule (for @command{gnatcheck}) - -@noindent -Flag each function declaration that overloads an operator symbol. -A function body is checked only if the body does not have a -separate spec. Formal functions are also checked. For a -renaming declaration, only renaming-as-declaration is checked - -This rule has no parameters. - - -@node Overly_Nested_Control_Structures -@subsection @code{Overly_Nested_Control_Structures} -@cindex @code{Overly_Nested_Control_Structures} rule (for @command{gnatcheck}) - -@noindent -Flag each control structure whose nesting level exceeds the value provided -in the rule parameter. - -The control structures checked are the following: - -@itemize @bullet -@item @code{if} statement -@item @code{case} statement -@item @code{loop} statement -@item Selective accept statement -@item Timed entry call statement -@item Conditional entry call -@item Asynchronous select statement -@end itemize - -@noindent -The rule has the following parameter for the @option{+R} option: - -@table @emph -@item N -Positive integer specifying the maximal control structure nesting -level that is not flagged -@end table - -@noindent -If the parameter for the @option{+R} option is not specified or -if it is not a positive integer, @option{+R} option is ignored. - -If more then one option is specified for the gnatcheck call, the later option and -new parameter override the previous one(s). - - -@node Parameters_Out_Of_Order -@subsection @code{Parameters_Out_Of_Order} -@cindex @code{Parameters_Out_Of_Order} rule (for @command{gnatcheck}) - -@noindent -Flag each subprogram and entry declaration whose formal parameters are not -ordered according to the following scheme: - -@itemize @bullet - -@item @code{in} and @code{access} parameters first, -then @code{in out} parameters, -and then @code{out} parameters; - -@item for @code{in} mode, parameters with default initialization expressions -occur last -@end itemize - -@noindent -Only the first violation of the described order is flagged. - -The following constructs are checked: - -@itemize @bullet -@item subprogram declarations (including null procedures); -@item generic subprogram declarations; -@item formal subprogram declarations; -@item entry declarations; -@item subprogram bodies and subprogram body stubs that do not -have separate specifications -@end itemize - -@noindent -Subprogram renamings are not checked. - -This rule has no parameters. - - -@node Positional_Actuals_For_Defaulted_Generic_Parameters -@subsection @code{Positional_Actuals_For_Defaulted_Generic_Parameters} -@cindex @code{Positional_Actuals_For_Defaulted_Generic_Parameters} rule (for @command{gnatcheck}) - -@noindent -Flag each generic actual parameter corresponding to a generic formal -parameter with a default initialization, if positional notation is used. - -This rule has no parameters. - -@node Positional_Actuals_For_Defaulted_Parameters -@subsection @code{Positional_Actuals_For_Defaulted_Parameters} -@cindex @code{Positional_Actuals_For_Defaulted_Parameters} rule (for @command{gnatcheck}) - -@noindent -Flag each actual parameter to a subprogram or entry call where the -corresponding formal parameter has a default expression, if positional -notation is used. - -This rule has no parameters. - -@node Positional_Components -@subsection @code{Positional_Components} -@cindex @code{Positional_Components} rule (for @command{gnatcheck}) - -@noindent -Flag each array, record and extension aggregate that includes positional -notation. - -This rule has no parameters. - - -@node Positional_Generic_Parameters -@subsection @code{Positional_Generic_Parameters} -@cindex @code{Positional_Generic_Parameters} rule (for @command{gnatcheck}) - -@noindent -Flag each positional actual generic parameter except for the case when -the generic unit being iinstantiated has exactly one generic formal -parameter. - -This rule has no parameters. - - -@node Positional_Parameters -@subsection @code{Positional_Parameters} -@cindex @code{Positional_Parameters} rule (for @command{gnatcheck}) - -@noindent -Flag each positional parameter notation in a subprogram or entry call, -except for the following: - -@itemize @bullet -@item -Parameters of calls to of prefix or infix operators are not flagged -@item -If the called subprogram or entry has only one formal parameter, -the parameter of the call is not flagged; -@item -If a subprogram call uses the @emph{Object.Operation} notation, then -@itemize @minus -@item -the first parameter (that is, @emph{Object}) is not flagged; -@item -if the called subprogram has only two parameters, the second parameter -of the call is not flagged; -@end itemize -@end itemize - -@noindent -This rule has no parameters. - - - - -@node Predefined_Numeric_Types -@subsection @code{Predefined_Numeric_Types} -@cindex @code{Predefined_Numeric_Types} rule (for @command{gnatcheck}) - -@noindent -Flag each explicit use of the name of any numeric type or subtype defined -in package @code{Standard}. - -The rationale for this rule is to detect when the -program may depend on platform-specific characteristics of the implementation -of the predefined numeric types. Note that this rule is over-pessimistic; -for example, a program that uses @code{String} indexing -likely needs a variable of type @code{Integer}. -Another example is the flagging of predefined numeric types with explicit -constraints: - -@smallexample @c ada - subtype My_Integer is Integer range Left .. Right; - Vy_Var : My_Integer; -@end smallexample - -@noindent -This rule detects only numeric types and subtypes defined in -@code{Standard}. The use of numeric types and subtypes defined in other -predefined packages (such as @code{System.Any_Priority} or -@code{Ada.Text_IO.Count}) is not flagged - -This rule has no parameters. - - - -@node Raising_External_Exceptions -@subsection @code{Raising_External_Exceptions} -@cindex @code{Raising_External_Exceptions} rule (for @command{gnatcheck}) - -@noindent -Flag any @code{raise} statement, in a program unit declared in a library -package or in a generic library package, for an exception that is -neither a predefined exception nor an exception that is also declared (or -renamed) in the visible part of the package. - -This rule has no parameters. - - - -@node Raising_Predefined_Exceptions -@subsection @code{Raising_Predefined_Exceptions} -@cindex @code{Raising_Predefined_Exceptions} rule (for @command{gnatcheck}) - -@noindent -Flag each @code{raise} statement that raises a predefined exception -(i.e., one of the exceptions @code{Constraint_Error}, @code{Numeric_Error}, -@code{Program_Error}, @code{Storage_Error}, or @code{Tasking_Error}). - -This rule has no parameters. - -@node Separate_Numeric_Error_Handlers -@subsection @code{Separate_Numeric_Error_Handlers} -@cindex @code{Separate_Numeric_Error_Handlers} rule (for @command{gnatcheck}) - -@noindent -Flags each exception handler that contains a choice for -the predefined @code{Constraint_Error} exception, but does not contain -the choice for the predefined @code{Numeric_Error} exception, or -that contains the choice for @code{Numeric_Error}, but does not contain the -choice for @code{Constraint_Error}. - -This rule has no parameters. - -@ignore -@node Recursion -@subsection @code{Recursion} (under construction, GLOBAL) -@cindex @code{Recursion} rule (for @command{gnatcheck}) - -@noindent -Flag recursive subprograms (cycles in the call graph). Declarations, and not -calls, of recursive subprograms are detected. - -This rule has no parameters. -@end ignore - -@ignore -@node Side_Effect_Functions -@subsection @code{Side_Effect_Functions} (under construction, GLOBAL) -@cindex @code{Side_Effect_Functions} rule (for @command{gnatcheck}) - -@noindent -Flag functions with side effects. - -We define a side effect as changing any data object that is not local for the -body of this function. - -At the moment, we do NOT consider a side effect any input-output operations -(changing a state or a content of any file). - -We do not consider protected functions for this rule (???) - -There are the following sources of side effect: - -@enumerate -@item Explicit (or direct) side-effect: - -@itemize @bullet -@item -direct assignment to a non-local variable; - -@item -direct call to an entity that is known to change some data object that is - not local for the body of this function (Note, that if F1 calls F2 and F2 - does have a side effect, this does not automatically mean that F1 also - have a side effect, because it may be the case that F2 is declared in - F1's body and it changes some data object that is global for F2, but - local for F1); -@end itemize - -@item Indirect side-effect: -@itemize @bullet -@item -Subprogram calls implicitly issued by: -@itemize @bullet -@item -computing initialization expressions from type declarations as a part - of object elaboration or allocator evaluation; -@item -computing implicit parameters of subprogram or entry calls or generic - instantiations; -@end itemize - -@item -activation of a task that change some non-local data object (directly or - indirectly); - -@item -elaboration code of a package that is a result of a package instantiation; - -@item -controlled objects; -@end itemize - -@item Situations when we can suspect a side-effect, but the full static check -is either impossible or too hard: -@itemize @bullet -@item -assignment to access variables or to the objects pointed by access - variables; - -@item -call to a subprogram pointed by access-to-subprogram value - -@item -dispatching calls; -@end itemize -@end enumerate - -@noindent -This rule has no parameters. -@end ignore - -@node Slices -@subsection @code{Slices} -@cindex @code{Slices} rule (for @command{gnatcheck}) - -@noindent -Flag all uses of array slicing - -This rule has no parameters. - - -@node Too_Many_Parents -@subsection @code{Too_Many_Parents} -@cindex @code{Too_Many_Parents} rule (for @command{gnatcheck}) - -@noindent -Flags any type declaration, single task declaration or single protected -declaration that has more then @option{N} parents, @option{N} is a parameter -of the rule. -A parent here is either a (sub)type denoted by the subtype mark from the -parent_subtype_indication (in case of a derived type declaration), or -any of the progenitors from the interface list, if any. - -This rule has the following (mandatory) parameters for the @option{+R} option: - -@table @emph -@item N -Positive integer specifying the maximal allowed number of parents. -@end table - - -@node Unassigned_OUT_Parameters -@subsection @code{Unassigned_OUT_Parameters} -@cindex @code{Unassigned_OUT_Parameters} rule (for @command{gnatcheck}) - -@noindent -Flags procedures' @code{out} parameters that are not assigned, and -identifies the contexts in which the assignments are missing. - -An @code{out} parameter is flagged in the statements in the procedure -body's handled sequence of statements (before the procedure body's -@code{exception} part, if any) if this sequence of statements contains -no assignments to the parameter. - -An @code{out} parameter is flagged in an exception handler in the exception -part of the procedure body's handled sequence of statements if the handler -contains no assignment to the parameter. - -Bodies of generic procedures are also considered. - -The following are treated as assignments to an @code{out} parameter: - -@itemize @bullet -@item -an assignment statement, with the parameter or some component as the target; - -@item -passing the parameter (or one of its components) as an @code{out} or -@code{in out} parameter. -@end itemize - -@noindent -This rule does not have any parameters. - - - -@node Uncommented_BEGIN_In_Package_Bodies -@subsection @code{Uncommented_BEGIN_In_Package_Bodies} -@cindex @code{Uncommented_BEGIN_In_Package_Bodies} rule (for @command{gnatcheck}) - -@noindent -Flags each package body with declarations and a statement part that does not -include a trailing comment on the line containing the @code{begin} keyword; -this trailing comment needs to specify the package name and nothing else. -The @code{begin} is not flagged if the package body does not -contain any declarations. - -If the @code{begin} keyword is placed on the -same line as the last declaration or the first statement, it is flagged -independently of whether the line contains a trailing comment. The -diagnostic message is attached to the line containing the first statement. - -This rule has no parameters. - -@node Unconditional_Exits -@subsection @code{Unconditional_Exits} -@cindex @code{Unconditional_Exits} rule (for @command{gnatcheck}) - -@noindent -Flag unconditional @code{exit} statements. - -This rule has no parameters. - -@node Unconstrained_Array_Returns -@subsection @code{Unconstrained_Array_Returns} -@cindex @code{Unconstrained_Array_Returns} rule (for @command{gnatcheck}) - -@noindent -Flag each function returning an unconstrained array. Function declarations, -function bodies (and body stubs) having no separate specifications, -and generic function instantiations are checked. -Function calls and function renamings are -not checked. - -Generic function declarations, and function declarations in generic -packages are not checked, instead this rule checks the results of -generic instantiations (that is, expanded specification and expanded -body corresponding to an instantiation). - -This rule has no parameters. - -@node Universal_Ranges -@subsection @code{Universal_Ranges} -@cindex @code{Universal_Ranges} rule (for @command{gnatcheck}) - -@noindent -Flag discrete ranges that are a part of an index constraint, constrained -array definition, or @code{for}-loop parameter specification, and whose bounds -are both of type @i{universal_integer}. Ranges that have at least one -bound of a specific type (such as @code{1 .. N}, where @code{N} is a variable -or an expression of non-universal type) are not flagged. - -This rule has no parameters. - - -@node Unnamed_Blocks_And_Loops -@subsection @code{Unnamed_Blocks_And_Loops} -@cindex @code{Unnamed_Blocks_And_Loops} rule (for @command{gnatcheck}) - -@noindent -Flag each unnamed block statement and loop statement. - -The rule has no parameters. - - - -@ignore -@node Unused_Subprograms -@subsection @code{Unused_Subprograms} (under construction, GLOBAL) -@cindex @code{Unused_Subprograms} rule (for @command{gnatcheck}) - -@noindent -Flag all unused subprograms. - -This rule has no parameters. -@end ignore - - - - -@node USE_PACKAGE_Clauses -@subsection @code{USE_PACKAGE_Clauses} -@cindex @code{USE_PACKAGE_Clauses} rule (for @command{gnatcheck}) - -@noindent -Flag all @code{use} clauses for packages; @code{use type} clauses are -not flagged. - -This rule has no parameters. - - -@node Visible_Components -@subsection @code{Visible_Components} -@cindex @code{Visible_Components} rule (for @command{gnatcheck}) - -@noindent -Flags all the type declarations located in the visible part of a library -package or a library generic package that can declare a visible component. A -type is considered as declaring a visible component if it contains a record -definition by its own or as a part of a record extension. Type declaration is -flagged even if it contains a record definition that defines no components. - -Declarations located in private parts of local (generic) packages are not -flagged. Declarations in private packages are not flagged. - -This rule has no parameters. - - -@node Volatile_Objects_Without_Address_Clauses -@subsection @code{Volatile_Objects_Without_Address_Clauses} -@cindex @code{Volatile_Objects_Without_Address_Clauses} rule (for @command{gnatcheck}) - -@noindent -Flag each volatile object that does not have an address clause. - -The following check is made: if the pragma @code{Volatile} is applied to a -data object or to its type, then an address clause must -be supplied for this object. - -This rule does not check the components of data objects, -array components that are volatile as a result of the pragma -@code{Volatile_Components}, or objects that are volatile because -they are atomic as a result of pragmas @code{Atomic} or -@code{Atomic_Components}. - -Only variable declarations, and not constant declarations, are checked. +The predefined rules implemented in @command{gnatcheck} +are described in a companion document, +@cite{GNATcheck Reference Manual -- Predefined Rules}. +The rule identifier is +used as a parameter of @command{gnatcheck}'s @option{+R} or @option{-R} +switches. -This rule has no parameters. @node Example of gnatcheck Usage @section Example of @command{gnatcheck} Usage @@ -23157,7 +17895,9 @@ option @option{^--no-exception^/NO_EXCEPTION^} (see below). @command{gnatstub} has the command-line interface of the form @smallexample -$ gnatstub @ovar{switches} @var{filename} @ovar{directory} +@c $ gnatstub @ovar{switches} @var{filename} @ovar{directory} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatstub @r{[}@var{switches}@r{]} @var{filename} @r{[}@var{directory}@r{]} @r{[}-cargs @var{gcc_switches}@r{]} @end smallexample @noindent @@ -23185,6 +17925,14 @@ indicates the directory in which the body stub is to be placed (the default is the current directory) +@item @samp{@var{gcc_switches}} is a list of switches for +@command{gcc}. They will be passed on to all compiler invocations made by +@command{gnatelim} to generate the ASIS trees. Here you can provide +@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path, +use the @option{-gnatec} switch to set the configuration file, +use the @option{-gnat05} switch if sources should be compiled in +Ada 2005 mode etc. + @item switches is an optional sequence of switches as described in the next section @end table @@ -23326,10 +18074,23 @@ Verbose mode: generate version information. @findex binding @noindent -GNAT now comes with a new experimental binding generator for C and C++ -headers which is intended to do 95% of the tedious work of generating -Ada specs from C or C++ header files. Note that this still is a work in -progress, not designed to generate 100% correct Ada specs. +GNAT now comes with a binding generator for C and C++ headers which is +intended to do 95% of the tedious work of generating Ada specs from C +or C++ header files. + +Note that this capability is not intended to generate 100% correct Ada specs, +and will is some cases require manual adjustments, although it can often +be used out of the box in practice. + +Some of the known limitations include: + +@itemize @bullet +@item only very simple character constant macros are translated into Ada +constants. Function macros (macros with arguments) are partially translated +as comments, to be completed manually if needed. +@item some extensions (e.g. vector types) are not supported +@item pointers to pointers or complex structures are mapped to System.Address +@end itemize The code generated is using the Ada 2005 syntax, which makes it easier to interface with other languages than previous versions of Ada. @@ -23676,7 +18437,9 @@ be able to click on any identifier and go to its declaration. The command line is as follow: @smallexample -$ perl gnathtml.pl @ovar{^switches^options^} @var{ada-files} +@c $ perl gnathtml.pl @ovar{^switches^options^} @var{ada-files} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ perl gnathtml.pl @r{[}@var{^switches^options^}@r{]} @var{ada-files} @end smallexample @noindent @@ -23782,7 +18545,9 @@ is. The syntax of this line is: Alternatively, you may run the script using the following command line: @smallexample -$ perl gnathtml.pl @ovar{switches} @var{files} +@c $ perl gnathtml.pl @ovar{switches} @var{files} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ perl gnathtml.pl @r{[}@var{switches}@r{]} @var{files} @end smallexample @ifset vms @@ -23982,9 +18747,9 @@ gnatmake -f -pg -P my_project @end smallexample @noindent -Note that only the objects that were compiled with the @samp{-pg} switch will be -profiled; if you need to profile your whole project, use the -@samp{-f} gnatmake switch to force full recompilation. +Note that only the objects that were compiled with the @samp{-pg} switch will +be profiled; if you need to profile your whole project, use the @samp{-f} +gnatmake switch to force full recompilation. @node Program execution @subsection Program execution @@ -24142,6 +18907,7 @@ the incorrect user program. * Ada Exceptions:: * Ada Tasks:: * Debugging Generic Units:: +* Remote Debugging using gdbserver:: * GNAT Abnormal Termination or Failure to Terminate:: * Naming Conventions for GNAT Source Files:: * Getting Internal Debugging Information:: @@ -24287,11 +19053,10 @@ and execution encounters the breakpoint, then the program stops and @code{GDB} signals that the breakpoint was encountered by printing the line of code before which the program is halted. -@item breakpoint exception @var{name} -A special form of the breakpoint command which breakpoints whenever -exception @var{name} is raised. -If @var{name} is omitted, -then a breakpoint will occur when any exception is raised. +@item catch exception @var{name} +This command causes the program execution to stop whenever exception +@var{name} is raised. If @var{name} is omitted, then the execution is +suspended when any exception is raised. @item print @var{expression} This will print the value of the given expression. Most simple @@ -24453,25 +19218,25 @@ The value returned is always that from the first return statement that was stepped through. @node Ada Exceptions -@section Breaking on Ada Exceptions +@section Stopping when Ada Exceptions are Raised @cindex Exceptions @noindent -You can set breakpoints that trip when your program raises -selected exceptions. +You can set catchpoints that stop the program execution when your program +raises selected exceptions. @table @code -@item break exception -Set a breakpoint that trips whenever (any task in the) program raises -any exception. +@item catch exception +Set a catchpoint that stops execution whenever (any task in the) program +raises any exception. -@item break exception @var{name} -Set a breakpoint that trips whenever (any task in the) program raises -the exception @var{name}. +@item catch exception @var{name} +Set a catchpoint that stops execution whenever (any task in the) program +raises the exception @var{name}. -@item break exception unhandled -Set a breakpoint that trips whenever (any task in the) program raises an -exception for which there is no handler. +@item catch exception unhandled +Set a catchpoint that stops executino whenever (any task in the) program +raises an exception for which there is no handler. @item info exceptions @itemx info exceptions @var{regexp} @@ -24600,6 +19365,56 @@ When the breakpoint occurs, you can step through the code of the instance in the normal manner and examine the values of local variables, as for other units. +@node Remote Debugging using gdbserver +@section Remote Debugging using gdbserver +@cindex Remote Debugging using gdbserver + +@noindent +On platforms where gdbserver is supported, it is possible to use this tool +to debug your application remotely. This can be useful in situations +where the program needs to be run on a target host that is different +from the host used for development, particularly when the target has +a limited amount of resources (either CPU and/or memory). + +To do so, start your program using gdbserver on the target machine. +gdbserver then automatically suspends the execution of your program +at its entry point, waiting for a debugger to connect to it. The +following commands starts an application and tells gdbserver to +wait for a connection with the debugger on localhost port 4444. + +@smallexample +$ gdbserver localhost:4444 program +Process program created; pid = 5685 +Listening on port 4444 +@end smallexample + +Once gdbserver has started listening, we can tell the debugger to establish +a connection with this gdbserver, and then start the same debugging session +as if the program was being debugged on the same host, directly under +the control of GDB. + +@smallexample +$ gdb program +(gdb) target remote targethost:4444 +Remote debugging using targethost:4444 +0x00007f29936d0af0 in ?? () from /lib64/ld-linux-x86-64.so. +(gdb) b foo.adb:3 +Breakpoint 1 at 0x401f0c: file foo.adb, line 3. +(gdb) continue +Continuing. + +Breakpoint 1, foo () at foo.adb:4 +4 end foo; +@end smallexample + +It is also possible to use gdbserver to attach to an already running +program, in which case the execution of that program is simply suspended +until the connection between the debugger and gdbserver is established. + +For more information on how to use gdbserver, @ref{Top, Server, Using +the gdbserver Program, gdb, Debugging with GDB}. GNAT Pro provides support +for gdbserver on x86-linux, x86-windows and x86_64-linux. + @node GNAT Abnormal Termination or Failure to Terminate @section GNAT Abnormal Termination or Failure to Terminate @cindex GNAT Abnormal Termination or Failure to Terminate @@ -25951,7 +20766,9 @@ Unlike HP Ada, the GNAT ``@code{EXPORT_}@i{subprogram}'' pragmas require a separate subprogram specification which must appear before the subprogram body. -GNAT also supplies a number of implementation-defined pragmas as follows: +GNAT also supplies a number of implementation-defined pragmas including the +following: + @itemize @bullet @item @code{ABORT_DEFER} @@ -25961,6 +20778,12 @@ GNAT also supplies a number of implementation-defined pragmas as follows: @item @code{ADA_05} +@item @code{Ada_2005} + +@item @code{Ada_12} + +@item @code{Ada_2012} + @item @code{ANNOTATE} @item @code{ASSERT} @@ -26007,7 +20830,7 @@ GNAT also supplies a number of implementation-defined pragmas as follows: @end itemize @noindent -For full details on these GNAT implementation-defined pragmas, +For full details on these and other GNAT implementation-defined pragmas, see @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual}. @@ -26906,6 +21729,7 @@ information about several specific platforms. * AIX-Specific Considerations:: * Irix-Specific Considerations:: * RTX-Specific Considerations:: +* HP-UX-Specific Considerations:: @end menu @node Summary of Run-Time Configurations @@ -27265,10 +22089,47 @@ Windows executables that run in Ring 3 to utilize memory protection @item Real-time subsystem (RTSS) executables that run in Ring 0, where performance can be optimized with RTSS applications taking precedent -over all Windows applications (@emph{rts-rtx-rtss}). +over all Windows applications (@emph{rts-rtx-rtss}). This mode requires +the Microsoft linker to handle RTSS libraries. @end itemize +@node HP-UX-Specific Considerations +@section HP-UX-Specific Considerations +@cindex HP-UX Scheduling + +@noindent +On HP-UX, appropriate privileges are required to change the scheduling +parameters of a task. The calling process must have appropriate +privileges or be a member of a group having @code{PRIV_RTSCHED} access to +successfully change the scheduling parameters. + +By default, GNAT uses the @code{SCHED_HPUX} policy. To have access to the +priority range 0-31 either the @code{FIFO_Within_Priorities} or the +@code{Round_Robin_Within_Priorities} scheduling policies need to be set. + +To specify the @code{FIFO_Within_Priorities} scheduling policy you can use +one of the following: + +@itemize @bullet +@item +@code{pragma Time_Slice (0.0)} +@cindex pragma Time_Slice +@item +the corresponding binder option @option{-T0} +@cindex @option{-T0} option +@item +@code{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)} +@cindex pragma Task_Dispatching_Policy +@end itemize + +@noindent +To specify the @code{Round_Robin_Within_Priorities}, scheduling policy +you should use @code{pragma Time_Slice} with a +value greater than @code{0.0}, or use the corresponding @option{-T} +binder option, or set the @code{pragma Task_Dispatching_Policy +(Round_Robin_Within_Priorities)}. + @c ******************************* @node Example of Binder Output File @appendix Example of Binder Output File @@ -30118,8 +24979,8 @@ Note that in this approach, both declarations are analyzed by the compiler so this can only be used where both declarations are legal, even though one of them will not be used. -Another approach is to define integer constants, e.g.@: @code{Bits_Per_Word}, or -Boolean constants, e.g.@: @code{Little_Endian}, and then write declarations +Another approach is to define integer constants, e.g.@: @code{Bits_Per_Word}, +or Boolean constants, e.g.@: @code{Little_Endian}, and then write declarations that are parameterized by these constants. For example @smallexample @c ada @@ -31725,10 +26586,11 @@ Such code will be referred to below as @emph{64-bit code}. @menu * Address types:: -* Access types:: +* Access types and 32/64-bit allocation:: * Unchecked conversions:: * Predefined constants:: * Interfacing with C:: +* 32/64-bit descriptors:: * Experience with source compatibility:: @end menu @@ -31743,9 +26605,13 @@ approach has been taken: @itemize @bullet @item @code{System.Address} always has a size of 64 bits +@cindex @code{System.Address} size +@cindex @code{Address} size @item @code{System.Short_Address} is a 32-bit subtype of @code{System.Address} +@cindex @code{System.Short_Address} size +@cindex @code{Short_Address} size @end itemize @noindent @@ -31784,31 +26650,64 @@ required in any code setting or accessing the field; the compiler will automatically perform any needed conversions between address formats. -@node Access types -@subsubsection Access types +@node Access types and 32/64-bit allocation +@subsubsection Access types and 32/64-bit allocation +@cindex 32-bit allocation +@cindex 64-bit allocation @noindent -By default, objects designated by access values are always -allocated in the 32-bit -address space. Thus legacy code will never contain -any objects that are not addressable with 32-bit addresses, and -the compiler will never raise exceptions as result of mixing -32-bit and 64-bit addresses. +By default, objects designated by access values are always allocated in +the 64-bit address space, and access values themselves are represented +in 64 bits. If these defaults are not appropriate, and 32-bit allocation +is required (for example if the address of an allocated object is assigned +to a @code{Short_Address} variable), then several alternatives are available: -However, the access values themselves are represented in 64 bits, for optimum -performance and future compatibility with 64-bit code. As was -the case with @code{System.Address}, the compiler will give an error message -if an object or record component has a representation clause that -requires the access value to fit in 32 bits. In such a situation, -an explicit size clause for the access type, specifying 32 bits, -will have the desired effect. +@itemize @bullet +@item +A pool-specific access type (ie, an @w{Ada 83} access type, whose +definition is @code{access T} versus @code{access all T} or +@code{access constant T}), may be declared with a @code{'Size} representation +clause that establishes the size as 32 bits. +In such circumstances allocations for that type will +be from the 32-bit heap. Such a clause is not permitted +for a general access type (declared with @code{access all} or +@code{access constant}) as values of such types must be able to refer +to any object of the designated type, including objects residing outside +the 32-bit address range. Existing @w{Ada 83} code will not contain such +type definitions, however, since general access types were introduced +in @w{Ada 95}. + +@item +Switches for @command{GNAT BIND} control whether the internal GNAT +allocation routine @code{__gnat_malloc} uses 64-bit or 32-bit allocations. +@cindex @code{__gnat_malloc} +The switches are respectively @option{-H64} (the default) and +@option{-H32}. +@cindex @option{-H32} (@command{gnatbind}) +@cindex @option{-H64} (@command{gnatbind}) + +@item +The environment variable (logical name) @code{GNAT$NO_MALLOC_64} +@cindex @code{GNAT$NO_MALLOC_64} environment variable +may be used to force @code{__gnat_malloc} to use 32-bit allocation. +If this variable is left +undefined, or defined as @code{"DISABLE"}, @code{"FALSE"}, or @code{"0"}, +then the default (64-bit) allocation is used. +If defined as @code{"ENABLE"}, @code{"TRUE"}, or @code{"1"}, +then 32-bit allocation is used. The gnatbind qualifiers described above +override this logical name. + +@item +A ^gcc switch^gcc switch^ for OpenVMS, @option{-mno-malloc64}, operates +@cindex @option{-mno-malloc64} (^gcc^gcc^) +at a low level to convert explicit calls to @code{malloc} and related +functions from the C run-time library so that they perform allocations +in the 32-bit heap. +Since all internal allocations from GNAT use @code{__gnat_malloc}, +this switch is not required unless the program makes explicit calls on +@code{malloc} (or related functions) from interfaced C code. +@end itemize -General access types (declared with @code{access all}) can never be -32 bits, as values of such types must be able to refer to any object -of the designated type, -including objects residing outside the 32-bit address range. -Existing Ada 83 code will not contain such type definitions, -however, since general access types were introduced in Ada 95. @node Unchecked conversions @subsubsection Unchecked conversions @@ -31881,6 +26780,20 @@ pragma Convention(C, int_star); for int_star'Size use 64; -- Necessary to get 64 and not 32 bits @end smallexample +@node 32/64-bit descriptors +@subsubsection 32/64-bit descriptors + +@noindent +By default, GNAT uses a 64-bit descriptor mechanism. For an imported +subprogram (i.e., a subprogram identified by pragma @code{Import_Function}, +@code{Import_Procedure}, or @code{Import_Valued_Procedure}) that specifies +@code{Short_Descriptor} as its mechanism, a 32-bit descriptor is used. +@cindex @code{Short_Descriptor} mechanism for imported subprograms + +If the configuration pragma @code{Short_Descriptors} is supplied, then +all descriptors will be 32 bits. +@cindex pragma @code{Short_Descriptors} + @node Experience with source compatibility @subsubsection Experience with source compatibility @@ -31913,8 +26826,6 @@ these sorts of potential source code porting problems. * Making code 64 bit clean:: * Allocating memory from the 64 bit storage pool:: * Restrictions on use of 64 bit objects:: -* Using 64 bit storage pools by default:: -* General access types:: * STARLET and other predefined libraries:: @end menu @@ -31958,13 +26869,10 @@ Any attempt to do this will raise @code{Constraint_Error}. @subsubsection Allocating memory from the 64-bit storage pool @noindent -For any access type @code{T} that potentially requires memory allocations -beyond the 32-bit address space, -use the following representation clause: - -@smallexample @c ada - for T'Storage_Pool use System.Pool_64; -@end smallexample +By default, all allocations -- for both pool-specific and general +access types -- use the 64-bit storage pool. To override +this default, for an individual access type or globally, see +@ref{Access types and 32/64-bit allocation}. @node Restrictions on use of 64 bit objects @subsubsection Restrictions on use of 64-bit objects @@ -31979,46 +26887,6 @@ or assigning it to a variable of type @code{Short_Address}, will cause no exception is raised and execution will become erroneous. -@node Using 64 bit storage pools by default -@subsubsection Using 64-bit storage pools by default - -@noindent -In some cases it may be desirable to have the compiler allocate -from 64-bit storage pools by default. This may be the case for -libraries that are 64-bit clean, but may be used in both 32-bit -and 64-bit contexts. For these cases the following configuration -pragma may be specified: - -@smallexample @c ada - pragma Pool_64_Default; -@end smallexample - -@noindent -Any code compiled in the context of this pragma will by default -use the @code{System.Pool_64} storage pool. This default may be overridden -for a specific access type @code{T} by the representation clause: - -@smallexample @c ada - for T'Storage_Pool use System.Pool_32; -@end smallexample - -@noindent -Any object whose address may be passed to a subprogram with a -@code{Short_Address} argument, or assigned to a variable of type -@code{Short_Address}, needs to be allocated from this pool. - -@node General access types -@subsubsection General access types - -@noindent -Objects designated by access values from a -general access type (declared with @code{access all}) are never allocated -from a 64-bit storage pool. Code that uses general access types will -accept objects allocated in either 32-bit or 64-bit address spaces, -but never allocate objects outside the 32-bit address space. -Using general access types ensures maximum compatibility with both -32-bit and 64-bit code. - @node STARLET and other predefined libraries @subsubsection STARLET and other predefined libraries @@ -32078,8 +26946,8 @@ platforms (NT, 2000, and XP Professional). * Windows Calling Conventions:: * Introduction to Dynamic Link Libraries (DLLs):: * Using DLLs with GNAT:: -* Building DLLs with GNAT:: * Building DLLs with GNAT Project files:: +* Building DLLs with GNAT:: * Building DLLs with gnatdll:: * GNAT and Windows Resources:: * Debugging a DLL:: @@ -32140,11 +27008,7 @@ features are not used, but it is not guaranteed to work. @item It is not possible to link against Microsoft libraries except for -import libraries. The library must be built to be compatible with -@file{MSVCRT.LIB} (/MD Microsoft compiler option), @file{LIBC.LIB} and -@file{LIBCMT.LIB} (/ML or /MT Microsoft compiler options) are known to -not be compatible with the GNAT runtime. Even if the library is -compatible with @file{MSVCRT.LIB} it is not guaranteed to work. +import libraries. Interfacing must be done by the mean of DLLs. @item When the compilation environment is located on FAT32 drives, users may @@ -32235,29 +27099,8 @@ interoperability strategy. If you use @command{gcc} to compile the non-Ada part of your application, there are no Windows-specific restrictions that affect the overall -interoperability with your Ada code. If you plan to use -Microsoft tools (e.g.@: Microsoft Visual C/C++), you should be aware of -the following limitations: - -@itemize @bullet -@item -You cannot link your Ada code with an object or library generated with -Microsoft tools if these use the @code{.tls} section (Thread Local -Storage section) since the GNAT linker does not yet support this section. - -@item -You cannot link your Ada code with an object or library generated with -Microsoft tools if these use I/O routines other than those provided in -the Microsoft DLL: @code{msvcrt.dll}. This is because the GNAT run time -uses the services of @code{msvcrt.dll} for its I/Os. Use of other I/O -libraries can cause a conflict with @code{msvcrt.dll} services. For -instance Visual C++ I/O stream routines conflict with those in -@code{msvcrt.dll}. -@end itemize - -@noindent -If you do want to use the Microsoft tools for your non-Ada code and hit one -of the above limitations, you have two choices: +interoperability with your Ada code. If you do want to use the +Microsoft tools for your non-Ada code, you have two choices: @enumerate @item @@ -32269,8 +27112,8 @@ build the DLL and use GNAT to build your executable @item Or you can encapsulate your Ada code in a DLL to be linked with the other part of your application. In this case, use GNAT to build the DLL -(@pxref{Building DLLs with GNAT}) and use the Microsoft or whatever -environment to build your executable. +(@pxref{Building DLLs with GNAT Project files}) and use the Microsoft +or whatever environment to build your executable. @end enumerate @node Windows Calling Conventions @@ -32278,6 +27121,10 @@ environment to build your executable. @findex Stdcall @findex APIENTRY +This section pertain only to Win32. On Win64 there is a single native +calling convention. All convention specifiers are ignored on this +platform. + @menu * C Calling Convention:: * Stdcall Calling Convention:: @@ -32581,11 +27428,23 @@ $ gnatmake my_ada_app -largs -lAPI @noindent The argument @option{-largs -lAPI} at the end of the @command{gnatmake} command -tells the GNAT linker to look first for a library named @file{API.lib} -(Microsoft-style name) and if not found for a libraries named -@file{libAPI.dll.a}, @file{API.dll.a} or @file{libAPI.a}. -(GNAT-style name). Note that if the Ada package spec for @file{API.dll} -contains the following pragma +tells the GNAT linker to look for an import library. The linker will +look for a library name in this specific order: + +@enumerate +@item @file{libAPI.dll.a} +@item @file{API.dll.a} +@item @file{libAPI.a} +@item @file{API.lib} +@item @file{libAPI.dll} +@item @file{API.dll} +@end enumerate + +The first three are the GNU style import libraries. The third is the +Microsoft style import libraries. The last two are the DLL themself. + +Note that if the Ada package spec for @file{API.dll} contains the +following pragma @smallexample @c ada pragma Linker_Options ("-lAPI"); @@ -32643,7 +27502,7 @@ end API; @noindent Note that a variable is -@strong{always imported with a Stdcall convention}. A function +@strong{always imported with a DLL convention}. A function can have @code{C} or @code{Stdcall} convention. (@pxref{Windows Calling Conventions}). @@ -32824,6 +27683,19 @@ See the Microsoft documentation for further details about the usage of @code{lib}. @end enumerate +@node Building DLLs with GNAT Project files +@section Building DLLs with GNAT Project files +@cindex DLLs, building + +@noindent +There is nothing specific to Windows in the build process. +@pxref{Library Projects}. + +@noindent +Due to a system limitation, it is not possible under Windows to create threads +when inside the @code{DllMain} routine which is used for auto-initialization +of shared libraries, so it is not possible to have library level tasks in SALs. + @node Building DLLs with GNAT @section Building DLLs with GNAT @cindex DLLs, building @@ -32886,19 +27758,6 @@ option. $ gnatmake main -Iapilib -bargs -shared -largs -Lapilib -lAPI @end smallexample -@node Building DLLs with GNAT Project files -@section Building DLLs with GNAT Project files -@cindex DLLs, building - -@noindent -There is nothing specific to Windows in the build process. -@pxref{Library Projects}. - -@noindent -Due to a system limitation, it is not possible under Windows to create threads -when inside the @code{DllMain} routine which is used for auto-initialization -of shared libraries, so it is not possible to have library level tasks in SALs. - @node Building DLLs with gnatdll @section Building DLLs with gnatdll @cindex DLLs, building @@ -32914,9 +27773,9 @@ of shared libraries, so it is not possible to have library level tasks in SALs. @end menu @noindent -Note that it is preferred to use the built-in GNAT DLL support -(@pxref{Building DLLs with GNAT}) or GNAT Project files -(@pxref{Building DLLs with GNAT Project files}) to build DLLs. +Note that it is preferred to use GNAT Project files +(@pxref{Building DLLs with GNAT Project files}) or the built-in GNAT +DLL support (@pxref{Building DLLs with GNAT}) or to build DLLs. This section explains how to build DLLs containing Ada code using @code{gnatdll}. These DLLs will be referred to as Ada DLLs in the @@ -33257,7 +28116,9 @@ static import library for the DLL and the actual DLL. The form of the @smallexample @cartouche -$ gnatdll @ovar{switches} @var{list-of-files} @r{[}-largs @var{opts}@r{]} +@c $ gnatdll @ovar{switches} @var{list-of-files} @r{[}-largs @var{opts}@r{]} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatdll @r{[}@var{switches}@r{]} @var{list-of-files} @r{[}-largs @var{opts}@r{]} @end cartouche @end smallexample @@ -33273,7 +28134,9 @@ missing, only the static import library is generated. You may specify any of the following switches to @code{gnatdll}: @table @code -@item -a@ovar{address} +@c @item -a@ovar{address} +@c Expanding @ovar macro inline (explanation in macro def comments) +@item -a@r{[}@var{address}@r{]} @cindex @option{-a} (@code{gnatdll}) Build a non-relocatable DLL at @var{address}. If @var{address} is not specified the default address @var{0x11000000} will be used. By default, @@ -33476,7 +28339,9 @@ common @code{dlltool} switches. The form of the @code{dlltool} command is @smallexample -$ dlltool @ovar{switches} +@c $ dlltool @ovar{switches} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ dlltool @r{[}@var{switches}@r{]} @end smallexample @noindent @@ -33655,7 +28520,6 @@ The program is built with foreign tools and the DLL is built with @item The program is built with @code{GCC/GNAT} and the DLL is built with foreign tools. -@item @end enumerate @noindent |