@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
* 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
* 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::
* 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::
* 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::
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
@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.
@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)
@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
@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
@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
@item -gnatn
@cindex @option{-gnatn} (@command{gcc})
Activate inlining for subprograms for which
-pragma @code{inline} is specified. This inlining is performed
+pragma @code{Inline} is specified. This inlining is performed
by the GCC back-end.
@item -gnatN
@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}).
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).
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}
@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})
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.}
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})
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
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
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
* 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
@cindex @option{^-aI^/SOURCE_SEARCH^} (@command{gnatbind})
Specify directory to be searched for source file.
+@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})
Generate brief messages to @file{stderr} even if verbose mode set.
@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:
@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.
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})
@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
@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
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
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
@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 and the
+@option{^-gnatn^/INLINE^} switch is used on the command line, 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
There is a @code{pragma Inline} for the subprogram.
@item
-@cindex @option{-gnatn} (@command{gcc})
-The @option{^-gnatn^/INLINE^} switch
-is used in the @command{gcc} command line
+The @option{^-gnatn^/INLINE^} switch is used on the command line.
@end itemize
Even if all these conditions are met, it may not be possible for
@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
@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 etc.
+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:
Ada_95
Ada_05
Ada_2005
+ Ada_12
+ Ada_2012
Assertion_Policy
Assume_No_Invalid_Values
C_Pass_By_Copy
Restrictions
Restrictions_Warnings
Reviewable
+ Short_Circuit_And_Or
Source_File_Name
Source_File_Name_Project
Style_Checks
@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.
the Naming Patterns, an indication of whether the file contains a unit,
and if so the name of the unit.
-@item ^-v -v^/VERBOSE /VERBOSE^
-@cindex @option{^-v -v^/VERBOSE /VERBOSE^} (@code{gnatname})
-Very Verbose mode. In addition to the output produced in verbose mode,
-for each file in the searched directories whose name matches none of
-the Naming Patterns, an indication is given that there is no match.
-
-@item ^-x^/EXCLUDED_PATTERN=^@file{pattern}
-@cindex @option{^-x^/EXCLUDED_PATTERN^} (@code{gnatname})
-Excluded patterns. Using this switch, it is possible to exclude some files
-that would match the name patterns. For example,
-@smallexample
-gnatname ^-x "*_nt.ada"^/EXCLUDED_PATTERN=*_nt.ada^ "*.ada"
-@end smallexample
-@noindent
-will look for Ada units in all files with the @file{.ada} extension,
-except those whose names end with @file{_nt.ada}.
-
-@end table
-
-@node Examples of gnatname Usage
-@section Examples of @code{gnatname} Usage
-
-@ifset vms
-@smallexample
-$ gnatname /CONFIG_FILE=[HOME.ME]NAMES.ADC /SOURCE_DIRS=SOURCES "[a-z]*.ada*"
-@end smallexample
-@end ifset
-
-@ifclear vms
-@smallexample
-$ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*"
-@end smallexample
-@end ifclear
-
-@noindent
-In this example, the directory @file{^/home/me^[HOME.ME]^} must already exist
-and be writable. In addition, the directory
-@file{^/home/me/sources^[HOME.ME.SOURCES]^} (specified by
-@option{^-d sources^/SOURCE_DIRS=SOURCES^}) must exist and be readable.
-
-@ifclear vms
-Note the optional spaces after @option{-c} and @option{-d}.
-@end ifclear
-
-@smallexample
-@ifclear vms
-$ gnatname -P/home/me/proj -x "*_nt_body.ada"
- -dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*"
-@end ifclear
-@ifset vms
-$ gnatname /PROJECT_FILE=[HOME.ME]PROJ
- /EXCLUDED_PATTERN=*_nt_body.ada
- /SOURCE_DIRS=(SOURCES,[SOURCES.PLUS])
- /DIRS_FILE=COMMON_DIRS.TXT "body_*" "spec_*"
-@end ifset
-@end smallexample
-
-Note that several switches @option{^-d^/SOURCE_DIRS^} may be used,
-even in conjunction with one or several switches
-@option{^-D^/DIRS_FILE^}. Several Naming Patterns and one excluded pattern
-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. When the project is not externally
-built, 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}. Except when the project is externally built, 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.
-
-@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.
-@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}. But if the argument files for the
-tool invoked by the the @command{gnat} driver are explicitly specified
-either directly or through the tool @option{-files} option, then the tool
-is called only for these explicitly specified files.
-
-@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:
+@item ^-v -v^/VERBOSE /VERBOSE^
+@cindex @option{^-v -v^/VERBOSE /VERBOSE^} (@code{gnatname})
+Very Verbose mode. In addition to the output produced in verbose mode,
+for each file in the searched directories whose name matches none of
+the Naming Patterns, an indication is given that there is no match.
+@item ^-x^/EXCLUDED_PATTERN=^@file{pattern}
+@cindex @option{^-x^/EXCLUDED_PATTERN^} (@code{gnatname})
+Excluded patterns. Using this switch, it is possible to exclude some files
+that would match the name patterns. For example,
@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
+gnatname ^-x "*_nt.ada"^/EXCLUDED_PATTERN=*_nt.ada^ "*.ada"
@end smallexample
+@noindent
+will look for Ada units in all files with the @file{.ada} extension,
+except those whose names end with @file{_nt.ada}.
-@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
+@end table
-@item We create a wrapping project @code{Main}:
+@node Examples of gnatname Usage
+@section Examples of @code{gnatname} Usage
+@ifset vms
@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;
-@end group
+$ gnatname /CONFIG_FILE=[HOME.ME]NAMES.ADC /SOURCE_DIRS=SOURCES "[a-z]*.ada*"
@end smallexample
+@end ifset
-@item Finally we need to create a dummy procedure that @code{with}s (either
-explicitly or implicitly) all the sources of our two programs.
-
-@end enumerate
-
-@noindent
-Now we can build the programs using the command
-
+@ifclear vms
@smallexample
- gnatmake ^-P^/PROJECT_FILE=^main dummy
+$ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*"
@end smallexample
+@end ifclear
@noindent
-for the Debug mode, or
+In this example, the directory @file{^/home/me^[HOME.ME]^} must already exist
+and be writable. In addition, the directory
+@file{^/home/me/sources^[HOME.ME.SOURCES]^} (specified by
+@option{^-d sources^/SOURCE_DIRS=SOURCES^}) must exist and be readable.
@ifclear vms
-@smallexample
- gnatmake -Pmain -XBUILD=release
-@end smallexample
+Note the optional spaces after @option{-c} and @option{-d}.
@end ifclear
-@ifset vms
@smallexample
- GNAT MAKE /PROJECT_FILE=main /EXTERNAL_REFERENCE=BUILD=release
-@end smallexample
+@ifclear vms
+$ gnatname -P/home/me/proj -x "*_nt_body.ada"
+ -dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*"
+@end ifclear
+@ifset vms
+$ gnatname /PROJECT_FILE=[HOME.ME]PROJ
+ /EXCLUDED_PATTERN=*_nt_body.ada
+ /SOURCE_DIRS=(SOURCES,[SOURCES.PLUS])
+ /DIRS_FILE=COMMON_DIRS.TXT "body_*" "spec_*"
@end ifset
+@end smallexample
-@noindent
-for the Release mode.
+Note that several switches @option{^-d^/SOURCE_DIRS^} may be used,
+even in conjunction with one or several switches
+@option{^-D^/DIRS_FILE^}. Several Naming Patterns and one excluded pattern
+are used in this example.
-@c ********************************
-@c * Project File Complete Syntax *
-@c ********************************
+@c *****************************************
+@c * G N A T P r o j e c t M a n a g e r *
+@c *****************************************
-@node Project File Complete Syntax
-@section Project File Complete Syntax
+@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
+@macro CODESAMPLE{TXT}
@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 @} )
+@group
+\TXT\
+@end group
+@end smallexample
+@end macro
-external_value ::=
- @b{external} ( string_literal [, string_literal] )
+@macro PROJECTFILE{TXT}
+@CODESAMPLE{\TXT\}
+@end macro
-attribute_reference ::=
- attribute_prefix ' <simple_attribute_>simple_name [ ( literal_string ) ]
+@c simulates a newline when in a @CODESAMPLE
+@macro NL{}
+@end macro
-attribute_prefix ::=
- @b{project} |
- <project_>simple_name | package_identifier |
- <project_>simple_name . package_identifier
+@macro TIP{TXT}
+@quotation
+@noindent
+\TXT\
+@end quotation
+@end macro
-case_construction ::=
- @b{case} <typed_variable_>name @b{is}
- @{case_item@}
- @b{end case} ;
+@macro TIPHTML{TXT}
+\TXT\
+@end macro
-case_item ::=
- @b{when} discrete_choice_list =>
- @{case_construction | attribute_declaration@}
+@macro IMPORTANT{TXT}
+@quotation
+@noindent
+\TXT\
+@end quotation
-discrete_choice_list ::=
- string_literal @{| string_literal@} |
- @b{others}
+@end macro
-name ::=
- simple_name @{. simple_name@}
+@macro NOTE{TXT}
+@quotation
+@noindent
+\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}
@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
@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}).
@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.
@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 etc.
+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
@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
@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
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
@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
@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
@cindex Report file (for @code{gnatcheck})
@noindent
-The @command{gnatcheck} tool outputs on @file{stdout} all messages concerning
-rule violations.
-It also creates a text file that
-contains the complete report of the last gnatcheck run. By default this file
-is named named @file{^gnatcheck.out^GNATCHECK.OUT^} and it is located in the
+The @command{gnatcheck} tool outputs on @file{stderr} all messages concerning
+rule violations except if running in quiet mode. It also creates a text file
+that contains the complete report of the last gnatcheck run. By default this file
+is named @file{^gnatcheck.out^GNATCHECK.OUT^} and it is located in the
current directory; the @option{^-o^/OUTPUT^} option can be used to change the
name and/or location of the report file. This report contains:
+
@itemize @bullet
-@item date and time of @command{gnatcheck} run, the version of
-the tool that has generated this report and the full parameters
-of the @command{gnatcheck} invocation;
-@item list of enabled rules;
-@item total number of detected violations;
-@item list of source files where rule violations have been detected;
-@item list of source files where no violations have been detected.
+
+@item general details of the @command{gnatcheck} run: date and time of the run,
+the version of the tool that has generated this report, full parameters
+of the @command{gnatcheck} invocation, reference to the list of checked
+sources and applied rules (coding standard);
+@item summary of the run (number of checked sources and detected violations);
+@item list of exempted coding standard violations;
+@item list of non-exempted coding standard violations;
+@item list of problems in the definition of exemption sections;
+@item of language violations (compile-time errors) detected in processed sources;
@end itemize
@node General gnatcheck Switches
@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 etc.
+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 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
* 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::
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
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}
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
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}
@item @code{ADA_05}
+@item @code{Ada_2005}
+
+@item @code{Ada_12}
+
+@item @code{Ada_2012}
+
@item @code{ANNOTATE}
@item @code{ASSERT}
@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}.
@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
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
@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
@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
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
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
* 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
@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
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
* 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::
@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
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
@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
@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::
@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");
@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}).
@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
@item building the DLL
-To build the DLL you must use @command{gcc}'s @option{-shared}
-option. It is quite simple to use this method:
+To build the DLL you must use @command{gcc}'s @option{-shared} and
+@option{-shared-libgcc} options. It is quite simple to use this method:
@smallexample
-$ gcc -shared -o api.dll obj1.o obj2.o @dots{}
+$ gcc -shared -shared-libgcc -o api.dll obj1.o obj2.o @dots{}
@end smallexample
It is important to note that in this case all symbols found in the
file, @pxref{The Definition File}. For example:
@smallexample
-$ gcc -shared -o api.dll api.def obj1.o obj2.o @dots{}
+$ gcc -shared -shared-libgcc -o api.dll api.def obj1.o obj2.o @dots{}
@end smallexample
If you use a definition file you must export the elaboration procedures
$ 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
@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
@item
The program is built with @code{GCC/GNAT} and the DLL is built with
foreign tools.
-@item
@end enumerate
@noindent
OSDN Git Service
