diff options
Diffstat (limited to 'gcc/ada/gnat_ugn.texi')
| -rw-r--r-- | gcc/ada/gnat_ugn.texi | 3675 |
1 files changed, 13 insertions, 3662 deletions
diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi index 4e32b1ba271..21f0352d06f 100644 --- a/gcc/ada/gnat_ugn.texi +++ b/gcc/ada/gnat_ugn.texi @@ -176,6 +176,7 @@ AdaCore@* * Configuration Pragmas:: * Handling Arbitrary File Naming Conventions Using gnatname:: * GNAT Project Manager:: +* Tools Supporting Project Files:: * The Cross-Referencing Tools gnatxref and gnatfind:: * The GNAT Pretty-Printer gnatpp:: * The GNAT Metric Tool gnatmetric:: @@ -376,26 +377,6 @@ Handling Arbitrary File Naming Conventions Using gnatname * Switches for gnatname:: * Examples of gnatname Usage:: -GNAT Project Manager - -* Introduction:: -* Examples of Project Files:: -* Project File Syntax:: -* Objects and Sources in Project Files:: -* Importing Projects:: -* Project Extension:: -* Project Hierarchy Extension:: -* External References in Project Files:: -* Packages in Project Files:: -* Variables from Imported Projects:: -* Naming Schemes:: -* Library Projects:: -* Stand-alone Library Projects:: -* Switches Related to Project Files:: -* Tools Supporting Project Files:: -* An Extended Example:: -* Project File Complete Syntax:: - The Cross-Referencing Tools gnatxref and gnatfind * Switches for gnatxref:: @@ -9464,7 +9445,7 @@ directories. @item ^-P^/PROJECT_FILE=^@var{project} @cindex @option{^-P^/PROJECT_FILE^} (@command{gnatmake}) Use project file @var{project}. Only one such switch can be used. -@xref{gnatmake and Project Files}. +@xref{^gnatmake^gnatmake^ and Project Files}. @item ^-q^/QUIET^ @cindex @option{^-q^/QUIET^} (@command{gnatmake}) @@ -9516,7 +9497,7 @@ Verbosity level High. Equivalent to ^-v^/REASONS^. @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x} Indicate the verbosity of the parsing of GNAT project files. -@xref{Switches Related to Project Files}. +@xref{^Switches^Switches^ Related to Project Files}. @item ^-x^/NON_PROJECT_UNIT_COMPILATION^ @cindex @option{^-x^/NON_PROJECT_UNIT_COMPILATION^} (@command{gnatmake}) @@ -9533,7 +9514,7 @@ command line need to be sources of a project file. Indicate 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. -@xref{Switches Related to Project Files}. +@xref{^Switches^Switches^ Related to Project Files}. @item ^-z^/NOMAIN^ @cindex @option{^-z^/NOMAIN^} (@command{gnatmake}) @@ -11749,3603 +11730,12 @@ 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 +@include projects.texi -@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: - -@smallexample -@group -File "prog1.gpr": - -@b{with} "common"; -@b{project} Prog1 @b{is} - - @b{for} Source_Dirs @b{use} ("prog1"); - @b{for} Object_Dir @b{use} "prog1/build/" & Common.Build; - - @b{package} Compiler @b{renames} Common.Compiler; - -@b{end} Prog1; -@end group -@end smallexample - -@smallexample -@group -File "prog2.gpr": - -@b{with} "common"; -@b{project} Prog2 @b{is} - - @b{for} Source_Dirs @b{use} ("prog2"); - @b{for} Object_Dir @b{use} "prog2/build/" & Common.Build; - - @b{package} Compiler @b{renames} Common.Compiler; - -@end group -@b{end} Prog2; -@end smallexample - -@item We create a wrapping project @code{Main}: - -@smallexample -@group -File "main.gpr": - -@b{with} "common"; -@b{with} "prog1"; -@b{with} "prog2"; -@b{project} Main @b{is} - - @b{package} Compiler @b{renames} Common.Compiler; - -@b{end} Main; -@end group -@end smallexample - -@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 - -@smallexample - gnatmake ^-P^/PROJECT_FILE=^main dummy -@end smallexample - -@noindent -for the Debug mode, or - -@ifclear vms -@smallexample - gnatmake -Pmain -XBUILD=release -@end smallexample -@end ifclear - -@ifset vms -@smallexample - GNAT MAKE /PROJECT_FILE=main /EXTERNAL_REFERENCE=BUILD=release -@end smallexample -@end ifset - -@noindent -for the Release mode. - -@c ******************************** -@c * Project File Complete Syntax * -@c ******************************** - -@node Project File Complete Syntax -@section Project File Complete Syntax - -@smallexample -project ::= - context_clause project_declaration - -context_clause ::= - @{with_clause@} - -with_clause ::= - @b{with} path_name @{ , path_name @} ; - -path_name ::= - string_literal - -project_declaration ::= - simple_project_declaration | project_extension - -simple_project_declaration ::= - @b{project} <project_>simple_name @b{is} - @{declarative_item@} - @b{end} <project_>simple_name; - -project_extension ::= - @b{project} <project_>simple_name @b{extends} path_name @b{is} - @{declarative_item@} - @b{end} <project_>simple_name; - -declarative_item ::= - package_declaration | - typed_string_declaration | - other_declarative_item - -package_declaration ::= - package_spec | package_renaming - -package_spec ::= - @b{package} package_identifier @b{is} - @{simple_declarative_item@} - @b{end} package_identifier ; - -package_identifier ::= - @code{Naming} | @code{Builder} | @code{Compiler} | @code{Binder} | - @code{Linker} | @code{Finder} | @code{Cross_Reference} | - @code{^gnatls^gnatls^} | @code{IDE} | @code{Pretty_Printer} - -package_renaming ::== - @b{package} package_identifier @b{renames} - <project_>simple_name.package_identifier ; - -typed_string_declaration ::= - @b{type} <typed_string_>_simple_name @b{is} - ( string_literal @{, string_literal@} ); - -other_declarative_item ::= - attribute_declaration | - typed_variable_declaration | - variable_declaration | - case_construction - -attribute_declaration ::= - full_associative_array_declaration | - @b{for} attribute_designator @b{use} expression ; - -full_associative_array_declaration ::= - @b{for} <associative_array_attribute_>simple_name @b{use} - <project_>simple_name [ . <package_>simple_Name ] ' <attribute_>simple_name ; - -attribute_designator ::= - <simple_attribute_>simple_name | - <associative_array_attribute_>simple_name ( string_literal ) - -typed_variable_declaration ::= - <typed_variable_>simple_name : <typed_string_>name := string_expression ; - -variable_declaration ::= - <variable_>simple_name := expression; - -expression ::= - term @{& term@} - -term ::= - literal_string | - string_list | - <variable_>name | - external_value | - attribute_reference - -string_literal ::= - (same as Ada) - -string_list ::= - ( <string_>expression @{ , <string_>expression @} ) - -external_value ::= - @b{external} ( string_literal [, string_literal] ) - -attribute_reference ::= - attribute_prefix ' <simple_attribute_>simple_name [ ( literal_string ) ] - -attribute_prefix ::= - @b{project} | - <project_>simple_name | package_identifier | - <project_>simple_name . package_identifier - -case_construction ::= - @b{case} <typed_variable_>name @b{is} - @{case_item@} - @b{end case} ; - -case_item ::= - @b{when} discrete_choice_list => - @{case_construction | attribute_declaration@} - -discrete_choice_list ::= - string_literal @{| string_literal@} | - @b{others} - -name ::= - simple_name @{. simple_name@} - -simple_name ::= - identifier (same as Ada) - -@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} @@ -15488,7 +11878,7 @@ Equivalent to @samp{-aODIR -aIDIR}. @item -pFILE @cindex @option{-pFILE} (@command{gnatxref}) -Specify a project file to use @xref{Project Files}. +Specify a project file to use @xref{GNAT Project Manager}. If you need to use the @file{.gpr} project files, you should use gnatxref through the GNAT driver (@command{gnat xref -Pproject}). @@ -15671,7 +12061,7 @@ Equivalent to @samp{-aODIR -aIDIR}. @item -pFILE @cindex @option{-pFILE} (@command{gnatfind}) -Specify a project file (@pxref{Project Files}) to use. +Specify a project file (@pxref{GNAT Project Manager}) to use. By default, @code{gnatxref} and @code{gnatfind} will try to locate a project file in the current directory. @@ -18944,14 +15334,14 @@ Verbose mode. @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x} @cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (@code{gnatclean}) Indicates the verbosity of the parsing of GNAT project files. -@xref{Switches Related to Project Files}. +@xref{^Switches^Switches^ Related to Project Files}. @item ^-X^/EXTERNAL_REFERENCE=^@var{name=value} @cindex @option{^-X^/EXTERNAL_REFERENCE^} (@code{gnatclean}) 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. -@xref{Switches Related to Project Files}. +@xref{^Switches^Switches^ Related to Project Files}. @item ^-aO^/OBJECT_SEARCH=^@var{dir} @cindex @option{^-aO^/OBJECT_SEARCH^} (@code{gnatclean}) @@ -19166,46 +15556,7 @@ be accessed by the directive @option{-l@var{xxx}} at link time. @noindent If you use project files, library installation is part of the library build -process. Thus no further action is needed in order to make use of the -libraries that are built as part of the general application build. A usable -version of the library is installed in the directory specified by the -@code{Library_Dir} attribute of the library project file. - -You may want to install a library in a context different from where the library -is built. This situation arises with third party suppliers, who may want -to distribute a library in binary form where the user is not expected to be -able to recompile the library. The simplest option in this case is to provide -a project file slightly different from the one used to build the library, by -using the @code{externally_built} attribute. For instance, the project -file used to build the library in the previous section can be changed into the -following one when the library is installed: - -@smallexample @c projectfile -project My_Lib is - for Source_Dirs use ("src1", "src2"); - for Library_Name use "mylib"; - for Library_Dir use "lib"; - for Library_Kind use "dynamic"; - for Externally_Built use "true"; -end My_lib; -@end smallexample - -@noindent -This project file assumes that the directories @file{src1}, -@file{src2}, and @file{lib} exist in -the directory containing the project file. The @code{externally_built} -attribute makes it clear to the GNAT builder that it should not attempt to -recompile any of the units from this library. It allows the library provider to -restrict the source set to the minimum necessary for clients to make use of the -library as described in the first section of this chapter. It is the -responsibility of the library provider to install the necessary sources, ALI -files and libraries in the directories mentioned in the project file. For -convenience, the user's library project file should be installed in a location -that will be searched automatically by the GNAT -builder. These are the directories referenced in the @env{GPR_PROJECT_PATH} -environment variable (@pxref{Importing Projects}), and also the default GNAT -library location that can be queried with @command{gnatls -v} and is usually of -the form $gnat_install_root/lib/gnat. +process (@pxref{Installing a library with project files}). When project files are not an option, it is also possible, but not recommended, to install the library so that the sources needed to use the library are on the |