From patchwork Tue Jun 22 09:02:24 2010 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Arnaud Charlet X-Patchwork-Id: 56431 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) by ozlabs.org (Postfix) with SMTP id ECE57B6EF0 for ; Tue, 22 Jun 2010 19:04:29 +1000 (EST) Received: (qmail 29332 invoked by alias); 22 Jun 2010 09:04:25 -0000 Received: (qmail 25170 invoked by uid 22791); 22 Jun 2010 09:03:28 -0000 X-SWARE-Spam-Status: No, hits=-0.4 required=5.0 tests=AWL, BAYES_50, TW_GT, TW_TX, T_RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from mel.act-europe.fr (HELO mel.act-europe.fr) (212.99.106.210) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Tue, 22 Jun 2010 09:02:26 +0000 Received: from localhost (localhost [127.0.0.1]) by filtered-smtp.eu.adacore.com (Postfix) with ESMTP id 6092DCB027F; Tue, 22 Jun 2010 11:02:25 +0200 (CEST) Received: from mel.act-europe.fr ([127.0.0.1]) by localhost (smtp.eu.adacore.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id CrcwI27JRaxr; Tue, 22 Jun 2010 11:02:25 +0200 (CEST) Received: from saumur.act-europe.fr (saumur.act-europe.fr [10.10.0.183]) by mel.act-europe.fr (Postfix) with ESMTP id 11750CB024F; Tue, 22 Jun 2010 11:02:25 +0200 (CEST) Received: by saumur.act-europe.fr (Postfix, from userid 525) id 04C96D9B31; Tue, 22 Jun 2010 11:02:24 +0200 (CEST) Date: Tue, 22 Jun 2010 11:02:24 +0200 From: Arnaud Charlet To: gcc-patches@gcc.gnu.org Cc: Emmanuel Briot Subject: [Ada] Doc clean ups Message-ID: <20100622090224.GA4781@adacore.com> Mime-Version: 1.0 Content-Disposition: inline User-Agent: Mutt/1.5.9i X-IsSubscribed: yes Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org This patch moves all the project-related documentation into projects.texi, and reorganizes the corresponding documentation as explained in the changelog. Tested on x86_64-pc-linux-gnu, committed on trunk 2010-06-22 Emmanuel Briot * gnat_rm.texi, gnat_ugn.texi, projects.texi: Remove all project files related sections from user's guide and reference manual, since they have now been merged together into a separate document (projects.texi). This removes a lot of duplication where attributes where described in several places. The grammar for the project files is now in each of the sections (packages,expressions,...) instead of being duplicates in two other sections (one in the user's guide that contained the full grammar, and various sections in the rm that contained extracts of the same grammar). Added the full list of all supported attributes, since existing lists were incomplete Rename "associative array" into "indexed attribute" Remove sections that were duplicates ("External References in Project Files" and "External Values", and "Project Extensions" for instance). The list of valid packages in project files is now in a single place. Index: gnat_rm.texi =================================================================== --- gnat_rm.texi (revision 161073) +++ gnat_rm.texi (working copy) @@ -81,7 +81,6 @@ AdaCore * Interfacing to Other Languages:: * Specialized Needs Annexes:: * Implementation of Specific Ada Features:: -* Project File Reference:: * Obsolescent Features:: * GNU Free Documentation License:: * Index:: @@ -463,8 +462,6 @@ Implementation of Specific Ada Features * The Size of Discriminated Records with Default Discriminants:: * Strict Conformance to the Ada Reference Manual:: -Project File Reference - Obsolescent Features GNU Free Documentation License @@ -582,10 +579,6 @@ to GNAT's implementation of machine code other features. @item -@ref{Project File Reference}, presents the syntax and semantics -of project files. - -@item @ref{Obsolescent Features} documents implementation dependent features, including pragmas and attributes, which are considered obsolescent, since there are other preferred ways of achieving the same results. These @@ -15945,1133 +15938,6 @@ machines that are not fully compliant wi behavior (although at the cost of a significant performance penalty), so infinite and and NaN values are properly generated. -@node Project File Reference -@chapter Project File Reference - -@noindent -This chapter describes the syntax and semantics of project files. -Project files specify the options to be used when building a system. -Project files can specify global settings for all tools, -as well as tool-specific settings. -@xref{Examples of Project Files,,, gnat_ugn, @value{EDITION} User's Guide}, -for examples of use. - -@menu -* Reserved Words:: -* Lexical Elements:: -* Declarations:: -* Empty declarations:: -* Typed string declarations:: -* Variables:: -* Expressions:: -* Attributes:: -* Project Attributes:: -* Attribute References:: -* External Values:: -* Case Construction:: -* Packages:: -* Package Renamings:: -* Projects:: -* Project Extensions:: -* Project File Elaboration:: -@end menu - -@node Reserved Words -@section Reserved Words - -@noindent -All Ada reserved words are reserved in project files, and cannot be used -as variable names or project names. In addition, the following are -also reserved in project files: - -@itemize -@item @code{extends} - -@item @code{external} - -@item @code{project} - -@end itemize - -@node Lexical Elements -@section Lexical Elements - -@noindent -Rules for identifiers are the same as in Ada. Identifiers -are case-insensitive. Strings are case sensitive, except where noted. -Comments have the same form as in Ada. - -@noindent -Syntax: - -@smallexample -simple_name ::= - identifier - -name ::= - simple_name @{. simple_name@} -@end smallexample - -@node Declarations -@section Declarations - -@noindent -Declarations introduce new entities that denote types, variables, attributes, -and packages. Some declarations can only appear immediately within a project -declaration. Others can appear within a project or within a package. - -Syntax: -@smallexample -declarative_item ::= - simple_declarative_item | - typed_string_declaration | - package_declaration - -simple_declarative_item ::= - variable_declaration | - typed_variable_declaration | - attribute_declaration | - case_construction | - empty_declaration -@end smallexample - -@node Empty declarations -@section Empty declarations - -@smallexample -empty_declaration ::= - @b{null} ; -@end smallexample - -An empty declaration is allowed anywhere a declaration is allowed. -It has no effect. - -@node Typed string declarations -@section Typed string declarations - -@noindent -Typed strings are sequences of string literals. Typed strings are the only -named types in project files. They are used in case constructions, where they -provide support for conditional attribute definitions. - -Syntax: -@smallexample -typed_string_declaration ::= - @b{type} _simple_name @b{is} - ( string_literal @{, string_literal@} ); -@end smallexample - -@noindent -A typed string declaration can only appear immediately within a project -declaration. - -All the string literals in a typed string declaration must be distinct. - -@node Variables -@section Variables - -@noindent -Variables denote values, and appear as constituents of expressions. - -@smallexample -typed_variable_declaration ::= - simple_name : name := string_expression ; - -variable_declaration ::= - simple_name := expression; -@end smallexample - -@noindent -The elaboration of a variable declaration introduces the variable and -assigns to it the value of the expression. The name of the variable is -available after the assignment symbol. - -@noindent -A typed_variable can only be declare once. - -@noindent -a non-typed variable can be declared multiple times. - -@noindent -Before the completion of its first declaration, the value of variable -is the null string. - -@node Expressions -@section Expressions - -@noindent -An expression is a formula that defines a computation or retrieval of a value. -In a project file the value of an expression is either a string or a list -of strings. A string value in an expression is either a literal, the current -value of a variable, an external value, an attribute reference, or a -concatenation operation. - -Syntax: - -@smallexample -expression ::= - term @{& term@} - -term ::= - string_literal | - string_list | - name | - external_value | - attribute_reference - -string_literal ::= - (same as Ada) - -string_list ::= - ( expression @{ , expression @} ) -@end smallexample - -@subsection Concatenation -@noindent -The following concatenation functions are defined: - -@smallexample @c ada - function "&" (X : String; Y : String) return String; - function "&" (X : String_List; Y : String) return String_List; - function "&" (X : String_List; Y : String_List) return String_List; -@end smallexample - -@node Attributes -@section Attributes - -@noindent -An attribute declaration defines a property of a project or package. This -property can later be queried by means of an attribute reference. -Attribute values are strings or string lists. - -Some attributes are associative arrays. These attributes are mappings whose -domain is a set of strings. These attributes are declared one association -at a time, by specifying a point in the domain and the corresponding image -of the attribute. They may also be declared as a full associative array, -getting the same associations as the corresponding attribute in an imported -or extended project. - -Attributes that are not associative arrays are called simple attributes. - -Syntax: -@smallexample -attribute_declaration ::= - full_associative_array_declaration | - @b{for} attribute_designator @b{use} expression ; - -full_associative_array_declaration ::= - @b{for} simple_name @b{use} - simple_name [ . simple_Name ] ' simple_name ; - -attribute_designator ::= - simple_name | - simple_name ( string_literal ) -@end smallexample - -@noindent -Some attributes are project-specific, and can only appear immediately within -a project declaration. Others are package-specific, and can only appear within -the proper package. - -The expression in an attribute definition must be a string or a string_list. -The string literal appearing in the attribute_designator of an associative -array attribute is case-insensitive. - -@node Project Attributes -@section Project Attributes - -@noindent -The following attributes apply to a project. All of them are simple -attributes. - -@table @code -@item Object_Dir -Expression must be a path name. The attribute defines the -directory in which the object files created by the build are to be placed. If -not specified, object files are placed in the project directory. - -@item Exec_Dir -Expression must be a path name. The attribute defines the -directory in which the executables created by the build are to be placed. -If not specified, executables are placed in the object directory. - -@item Source_Dirs -Expression must be a list of path names. The attribute -defines the directories in which the source files for the project are to be -found. If not specified, source files are found in the project directory. -If a string in the list ends with "/**", then the directory that precedes -"/**" and all of its subdirectories (recursively) are included in the list -of source directories. - -@item Excluded_Source_Dirs -Expression must be a list of strings. Each entry designates a directory that -is not to be included in the list of source directories of the project. -This is normally used when there are strings ending with "/**" in the value -of attribute Source_Dirs. - -@item Source_Files -Expression must be a list of file names. The attribute -defines the individual files, in the project directory, which are to be used -as sources for the project. File names are path_names that contain no directory -information. If the project has no sources the attribute must be declared -explicitly with an empty list. - -@item Excluded_Source_Files (Locally_Removed_Files) -Expression must be a list of strings that are legal file names. -Each file name must designate a source that would normally be a source file -in the source directories of the project or, if the project file is an -extending project file, inherited by the current project file. It cannot -designate an immediate source that is not inherited. Each of the source files -in the list are not considered to be sources of the project file: they are not -inherited. Attribute Locally_Removed_Files is obsolescent, attribute -Excluded_Source_Files is preferred. - -@item Source_List_File -Expression must a single path name. The attribute -defines a text file that contains a list of source file names to be used -as sources for the project - -@item Library_Dir -Expression must be a path name. The attribute defines the -directory in which a library is to be built. The directory must exist, must -be distinct from the project's object directory, and must be writable. - -@item Library_Name -Expression must be a string that is a legal file name, -without extension. The attribute defines a string that is used to generate -the name of the library to be built by the project. - -@item Library_Kind -Argument must be a string value that must be one of the -following @code{"static"}, @code{"dynamic"} or @code{"relocatable"}. This -string is case-insensitive. If this attribute is not specified, the library is -a static library. Otherwise, the library may be dynamic or relocatable. This -distinction is operating-system dependent. - -@item Library_Version -Expression must be a string value whose interpretation -is platform dependent. 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}. - -@item Library_Interface -Expression must be a string list. Each element of the string list -must designate a unit of the project. -If this attribute is present in a Library Project File, then the project -file is a Stand-alone Library_Project_File. - -@item Library_Auto_Init -Expression must be a single string "true" or "false", case-insensitive. -If this attribute is present in a Stand-alone Library Project File, -it indicates if initialization is automatic when the dynamic library -is loaded. - -@item Library_Options -Expression must be a string list. Indicates additional switches that -are to be used when building a shared library. - -@item Library_GCC -Expression must be a single string. Designates an alternative to "gcc" -for building shared libraries. - -@item Library_Src_Dir -Expression must be a path name. The attribute defines the -directory in which the sources of the interfaces of a Stand-alone Library will -be copied. The directory must exist, must be distinct from the project's -object directory and source directories of all projects in the project tree, -and must be writable. - -@item Library_ALI_Dir -Expression must be a path name. The attribute defines the -directory in which the ALI files of a Library will -be copied. The directory must exist, must be distinct from the project's -object directory and source directories of all projects in the project tree, -and must be writable. - -@item Library_Symbol_File -Expression must be a single string. Its value is the single file name of a -symbol file to be created when building a stand-alone library when the -symbol policy is either "compliant", "controlled" or "restricted", -on platforms that support symbol control, such as VMS. When symbol policy -is "direct", then a file with this name must exist in the object directory. - -@item Library_Reference_Symbol_File -Expression must be a single string. Its value is the path name of a -reference symbol file that is read when the symbol policy is either -"compliant" or "controlled", on platforms that support symbol control, -such as VMS, when building a stand-alone library. The path may be an absolute -path or a path relative to the project directory. - -@item Library_Symbol_Policy -Expression must be a single string. Its case-insensitive value can only be -"autonomous", "default", "compliant", "controlled", "restricted" or "direct". - -This attribute is not taken into account on all platforms. It controls the -policy for exported symbols and, on some platforms (like VMS) that have the -notions of major and minor IDs built in the library files, it controls -the setting of these IDs. - -"autonomous" or "default": exported symbols are not controlled. - -"compliant": if attribute Library_Reference_Symbol_File is not defined, then -it is equivalent to policy "autonomous". If there are exported symbols in -the reference symbol file that are not in the object files of the interfaces, -the major ID of the library is increased. If there are symbols in the -object files of the interfaces that are not in the reference symbol file, -these symbols are put at the end of the list in the newly created symbol file -and the minor ID is increased. - -"controlled": the attribute Library_Reference_Symbol_File must be defined. -The library will fail to build if the exported symbols in the object files of -the interfaces do not match exactly the symbol in the symbol file. - -"restricted": The attribute Library_Symbol_File must be defined. The library -will fail to build if there are symbols in the symbol file that are not in -the exported symbols of the object files of the interfaces. Additional symbols -in the object files are not added to the symbol file. - -"direct": The attribute Library_Symbol_File must be defined and must designate -an existing file in the object directory. This symbol file is passed directly -to the underlying linker without any symbol processing. - -@item Main -Expression must be a list of strings that are legal file names. -These file names designate existing compilation units in the source directory -that are legal main subprograms. - -When a project file is elaborated, as part of the execution of a gnatmake -command, one or several executables are built and placed in the Exec_Dir. -If the gnatmake command does not include explicit file names, the executables -that are built correspond to the files specified by this attribute. - -@item Externally_Built -Expression must be a single string. Its value must be either "true" of "false", -case-insensitive. The default is "false". When the value of this attribute is -"true", no attempt is made to compile the sources or to build the library, -when the project is a library project. - -@item Main_Language -This is a simple attribute. Its value is a string that specifies the -language of the main program. - -@item Languages -Expression must be a string list. Each string designates -a programming language that is known to GNAT. The strings are case-insensitive. - -@end table - -@node Attribute References -@section Attribute References - -@noindent -Attribute references are used to retrieve the value of previously defined -attribute for a package or project. -Syntax: -@smallexample -attribute_reference ::= - attribute_prefix ' simple_name [ ( string_literal ) ] - -attribute_prefix ::= - @b{project} | - simple_name . package_identifier -@end smallexample - -@noindent -If an attribute has not been specified for a given package or project, its -value is the null string or the empty list. - -@node External Values -@section External Values - -@noindent -An external value is an expression whose value is obtained from the command -that invoked the processing of the current project file (typically a -gnatmake command). - -Syntax: -@smallexample -external_value ::= - @b{external} ( string_literal [, string_literal] ) -@end smallexample - -@noindent -The first string_literal is the string to be used on the command line or -in the environment to specify the external value. The second string_literal, -if present, is the default to use if there is no specification for this -external value either on the command line or in the environment. - -@node Case Construction -@section Case Construction - -@noindent -A case construction supports attribute and variable declarations that depend -on the value of a previously declared variable. - -Syntax: -@smallexample -case_construction ::= - @b{case} name @b{is} - @{case_item@} - @b{end case} ; - -case_item ::= - @b{when} discrete_choice_list => - @{case_construction | - attribute_declaration | - variable_declaration | - empty_declaration@} - -discrete_choice_list ::= - string_literal @{| string_literal@} | - @b{others} -@end smallexample - -@noindent -Inside a case construction, variable declarations must be for variables that -have already been declared before the case construction. - -All choices in a choice list must be distinct. The choice lists of two -distinct alternatives must be disjoint. Unlike Ada, the choice lists of all -alternatives do not need to include all values of the type. An @code{others} -choice must appear last in the list of alternatives. - -@node Packages -@section Packages - -@noindent -A package provides a grouping of variable declarations and attribute -declarations to be used when invoking various GNAT tools. The name of -the package indicates the tool(s) to which it applies. -Syntax: - -@smallexample -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} | @code{IDE} | @code{Pretty_Printer} | @code{Check} -@end smallexample - -@subsection Package Naming - -@noindent -The attributes of a @code{Naming} package specifies the naming conventions -that apply to the source files in a project. When invoking other GNAT tools, -they will use the sources in the source directories that satisfy these -naming conventions. - -The following attributes apply to a @code{Naming} package: - -@table @code -@item Casing -This is a simple attribute whose value is a string. Legal values of this -string are @code{"lowercase"}, @code{"uppercase"} or @code{"mixedcase"}. -These strings are themselves case insensitive. - -@noindent -If @code{Casing} is not specified, then the default is @code{"lowercase"}. - -@item Dot_Replacement -This is a simple attribute whose string value satisfies the following -requirements: - -@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{'.'} if longer than one character -@end itemize - -@noindent -If @code{Dot_Replacement} is not specified, then the default is @code{"-"}. - -@item Spec_Suffix -This is an associative array attribute, defined on language names, -whose image is a string that must satisfy the following -conditions: - -@itemize @bullet -@item It must not be empty -@item It cannot start with an alphanumeric character -@item It cannot start with an underscore followed by an alphanumeric character -@end itemize - -@noindent -For Ada, the attribute denotes the suffix used in file names that contain -library unit declarations, that is to say units that are package and -subprogram declarations. If @code{Spec_Suffix ("Ada")} is not -specified, then the default is @code{".ads"}. - -For C and C++, the attribute denotes the suffix used in file names that -contain prototypes. - -@item Body_Suffix -This is an associative array attribute defined on language names, -whose image is a string that must satisfy the following -conditions: - -@itemize @bullet -@item It must not be empty -@item It cannot start with an alphanumeric character -@item It cannot start with an underscore followed by an alphanumeric character -@item It cannot be a suffix of @code{Spec_Suffix} -@end itemize - -@noindent -For Ada, the attribute denotes the suffix used in file names that contain -library bodies, that is to say units that are package and subprogram bodies. -If @code{Body_Suffix ("Ada")} is not specified, then the default is -@code{".adb"}. - -For C and C++, the attribute denotes the suffix used in file names that contain -source code. - -@item Separate_Suffix -This is a simple attribute whose value satisfies the same conditions as -@code{Body_Suffix}. - -This attribute is specific to Ada. It denotes the suffix used in file names -that contain separate bodies. If it is not specified, then it defaults to same -value as @code{Body_Suffix ("Ada")}. - -@item Spec -This is an associative array attribute, specific to Ada, defined over -compilation unit names. The image is a string that is the name of the file -that contains that library unit. The file name is case sensitive if the -conventions of the host operating system require it. - -@item Body -This is an associative array attribute, specific to Ada, defined over -compilation unit names. The image is a string that is the name of the file -that contains the library unit body for the named unit. The file name is case -sensitive if the conventions of the host operating system require it. - -@item Specification_Exceptions -This is an associative array attribute defined on language names, -whose value is a list of strings. - -This attribute is not significant for Ada. - -For C and C++, each string in the list denotes the name of a file that -contains prototypes, but whose suffix is not necessarily the -@code{Spec_Suffix} for the language. - -@item Implementation_Exceptions -This is an associative array attribute defined on language names, -whose value is a list of strings. - -This attribute is not significant for Ada. - -For C and C++, each string in the list denotes the name of a file that -contains source code, but whose suffix is not necessarily the -@code{Body_Suffix} for the language. -@end table - -The following attributes of package @code{Naming} are obsolescent. They are -kept as synonyms of other attributes for compatibility with previous versions -of the Project Manager. - -@table @code -@item Specification_Suffix -This is a synonym of @code{Spec_Suffix}. - -@item Implementation_Suffix -This is a synonym of @code{Body_Suffix}. - -@item Specification -This is a synonym of @code{Spec}. - -@item Implementation -This is a synonym of @code{Body}. -@end table - -@subsection package Compiler - -@noindent -The attributes of the @code{Compiler} package specify the compilation options -to be used by the underlying compiler. - -@table @code -@item Default_Switches -This is an associative array attribute. Its -domain is a set of language names. Its range is a string list that -specifies the compilation options to be used when compiling a component -written in that language, for which no file-specific switches have been -specified. - -@item Switches -This is an associative array attribute. Its domain is -a set of file names. Its range is a string list that specifies the -compilation options to be used when compiling the named file. If a file -is not specified in the Switches attribute, it is compiled with the -options specified by Default_Switches of its language, if defined. - -@item Local_Configuration_Pragmas. -This is a simple attribute, whose -value is a path name that designates a file containing configuration pragmas -to be used for all invocations of the compiler for immediate sources of the -project. -@end table - -@subsection package Builder - -@noindent -The attributes of package @code{Builder} specify the compilation, binding, and -linking options to be used when building an executable for a project. The -following attributes apply to package @code{Builder}: - -@table @code -@item Default_Switches -This is an associative array attribute. Its -domain is a set of language names. Its range is a string list that -specifies options to be used when building a main -written in that language, for which no file-specific switches have been -specified. - -@item Switches -This is an associative array attribute. Its domain is -a set of file names. Its range is a string list that specifies -options to be used when building the named main file. If a main file -is not specified in the Switches attribute, it is built with the -options specified by Default_Switches of its language, if defined. - -@item Global_Configuration_Pragmas -This is a simple attribute, whose -value is a path name that designates a file that contains configuration pragmas -to be used in every build of an executable. If both local and global -configuration pragmas are specified, a compilation makes use of both sets. - -@item Executable -This is an associative array attribute. Its domain is -a set of main source file names. Its range is a simple string that specifies -the executable file name to be used when linking the specified main source. -If a main source is not specified in the Executable attribute, the executable -file name is deducted from the main source file name. -This attribute has no effect if its value is the empty string. - -@item Executable_Suffix -This is a simple attribute whose value is the suffix to be added to -the executables that don't have an attribute Executable specified. -@end table - -@subsection package Gnatls - -@noindent -The attributes of package @code{Gnatls} specify the tool options to be used -when invoking the library browser @command{gnatls}. -The following attributes apply to package @code{Gnatls}: - -@table @code -@item Switches -This is a single attribute with a string list value. Each nonempty string -in the list is an option when invoking @code{gnatls}. -@end table - -@subsection package Binder - -@noindent -The attributes of package @code{Binder} specify the options to be used -when invoking the binder in the construction of an executable. -The following attributes apply to package @code{Binder}: - -@table @code -@item Default_Switches -This is an associative array attribute. Its -domain is a set of language names. Its range is a string list that -specifies options to be used when binding a main -written in that language, for which no file-specific switches have been -specified. - -@item Switches -This is an associative array attribute. Its domain is -a set of file names. Its range is a string list that specifies -options to be used when binding the named main file. If a main file -is not specified in the Switches attribute, it is bound with the -options specified by Default_Switches of its language, if defined. -@end table - -@subsection package Linker - -@noindent -The attributes of package @code{Linker} specify the options to be used when -invoking the linker in the construction of an executable. -The following attributes apply to package @code{Linker}: - -@table @code -@item Default_Switches -This is an associative array attribute. Its -domain is a set of language names. Its range is a string list that -specifies options to be used when linking a main -written in that language, for which no file-specific switches have been -specified. - -@item Switches -This is an associative array attribute. Its domain is -a set of file names. Its range is a string list that specifies -options to be used when linking the named main file. If a main file -is not specified in the Switches attribute, it is linked with the -options specified by Default_Switches of its language, if defined. - -@item Linker_Options -This is a string list attribute. Its value specifies additional options that -be given to the linker when linking an executable. This attribute is not -used in the main project, only in projects imported directly or indirectly. - -@end table - -@subsection package Cross_Reference - -@noindent -The attributes of package @code{Cross_Reference} specify the tool options -to be used -when invoking the library tool @command{gnatxref}. -The following attributes apply to package @code{Cross_Reference}: - -@table @code -@item Default_Switches -This is an associative array attribute. Its -domain is a set of language names. Its range is a string list that -specifies options to be used when calling @command{gnatxref} on a source -written in that language, for which no file-specific switches have been -specified. - -@item Switches -This is an associative array attribute. Its domain is -a set of file names. Its range is a string list that specifies -options to be used when calling @command{gnatxref} on the named main source. -If a source is not specified in the Switches attribute, @command{gnatxref} will -be called with the options specified by Default_Switches of its language, -if defined. -@end table - -@subsection package Finder - -@noindent -The attributes of package @code{Finder} specify the tool options to be used -when invoking the search tool @command{gnatfind}. -The following attributes apply to package @code{Finder}: - -@table @code -@item Default_Switches -This is an associative array attribute. Its -domain is a set of language names. Its range is a string list that -specifies options to be used when calling @command{gnatfind} on a source -written in that language, for which no file-specific switches have been -specified. - -@item Switches -This is an associative array attribute. Its domain is -a set of file names. Its range is a string list that specifies -options to be used when calling @command{gnatfind} on the named main source. -If a source is not specified in the Switches attribute, @command{gnatfind} will -be called with the options specified by Default_Switches of its language, -if defined. -@end table - -@subsection package Check - -@noindent -The attributes of package @code{Check} -specify the checking rule options to be used -when invoking the checking tool @command{gnatcheck}. -The following attributes apply to package @code{Check}: - -@table @code -@item Default_switches -This is an associative array attribute. Its -domain is a set of language names. Its range is a string list that -specifies options to be used when calling @command{gnatcheck} on a source -written in that language. The first string in the range should always be -@code{"-rules"} to specify that all the other options belong to the -@code{-rules} section of the parameters of @command{gnatcheck} call. - -@end table - -@subsection package Pretty_Printer - -@noindent -The attributes of package @code{Pretty_Printer} -specify the tool options to be used -when invoking the formatting tool @command{gnatpp}. -The following attributes apply to package @code{Pretty_Printer}: - -@table @code -@item Default_switches -This is an associative array attribute. Its -domain is a set of language names. Its range is a string list that -specifies options to be used when calling @command{gnatpp} on a source -written in that language, for which no file-specific switches have been -specified. - -@item Switches -This is an associative array attribute. Its domain is -a set of file names. Its range is a string list that specifies -options to be used when calling @command{gnatpp} on the named main source. -If a source is not specified in the Switches attribute, @command{gnatpp} will -be called with the options specified by Default_Switches of its language, -if defined. -@end table - -@subsection package gnatstub - -@noindent -The attributes of package @code{gnatstub} -specify the tool options to be used -when invoking the tool @command{gnatstub}. -The following attributes apply to package @code{gnatstub}: - -@table @code -@item Default_switches -This is an associative array attribute. Its -domain is a set of language names. Its range is a string list that -specifies options to be used when calling @command{gnatstub} on a source -written in that language, for which no file-specific switches have been -specified. - -@item Switches -This is an associative array attribute. Its domain is -a set of file names. Its range is a string list that specifies -options to be used when calling @command{gnatstub} on the named main source. -If a source is not specified in the Switches attribute, @command{gnatpp} will -be called with the options specified by Default_Switches of its language, -if defined. -@end table - -@subsection package Eliminate - -@noindent -The attributes of package @code{Eliminate} -specify the tool options to be used -when invoking the tool @command{gnatelim}. -The following attributes apply to package @code{Eliminate}: - -@table @code -@item Default_switches -This is an associative array attribute. Its -domain is a set of language names. Its range is a string list that -specifies options to be used when calling @command{gnatelim} on a source -written in that language, for which no file-specific switches have been -specified. - -@item Switches -This is an associative array attribute. Its domain is -a set of file names. Its range is a string list that specifies -options to be used when calling @command{gnatelim} on the named main source. -If a source is not specified in the Switches attribute, @command{gnatelim} will -be called with the options specified by Default_Switches of its language, -if defined. -@end table - -@subsection package Metrics - -@noindent -The attributes of package @code{Metrics} -specify the tool options to be used -when invoking the tool @command{gnatmetric}. -The following attributes apply to package @code{Metrics}: - -@table @code -@item Default_switches -This is an associative array attribute. Its -domain is a set of language names. Its range is a string list that -specifies options to be used when calling @command{gnatmetric} on a source -written in that language, for which no file-specific switches have been -specified. - -@item Switches -This is an associative array attribute. Its domain is -a set of file names. Its range is a string list that specifies -options to be used when calling @command{gnatmetric} on the named main source. -If a source is not specified in the Switches attribute, @command{gnatmetric} -will be called with the options specified by Default_Switches of its language, -if defined. -@end table - -@subsection package IDE - -@noindent -The attributes of package @code{IDE} specify the options to be used when using -an Integrated Development Environment such as @command{GPS}. - -@table @code -@item Remote_Host -This is a simple attribute. Its value is a string that designates the remote -host in a cross-compilation environment, to be used for remote compilation and -debugging. This field should not be specified when running on the local -machine. - -@item Program_Host -This is a simple attribute. Its value is a string that specifies the -name of IP address of the embedded target in a cross-compilation environment, -on which the program should execute. - -@item Communication_Protocol -This is a simple string attribute. Its value is the name of the protocol -to use to communicate with the target in a cross-compilation environment, -e.g.@: @code{"wtx"} or @code{"vxworks"}. - -@item Compiler_Command -This is an associative array attribute, whose domain is a language name. Its -value is string that denotes the command to be used to invoke the compiler. -The value of @code{Compiler_Command ("Ada")} is expected to be compatible with -gnatmake, in particular in the handling of switches. - -@item Debugger_Command -This is simple attribute, Its value is a string that specifies the name of -the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4. - -@item Default_Switches -This is an associative array attribute. Its indexes are the name of the -external tools that the GNAT Programming System (GPS) is supporting. Its -value is a list of switches to use when invoking that tool. - -@item Gnatlist -This is a simple attribute. Its value is a string that specifies the name -of the @command{gnatls} utility to be used to retrieve information about the -predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}. - -@item VCS_Kind -This is a simple attribute. Its value is a string used to specify the -Version Control System (VCS) to be used for this project, e.g.@: CVS, RCS -ClearCase or Perforce. - -@item VCS_File_Check -This is a simple attribute. Its value is a string that specifies the -command used by the VCS to check the validity of a file, either -when the user explicitly asks for a check, or as a sanity check before -doing the check-in. - -@item VCS_Log_Check -This is a simple attribute. Its value is a string that specifies -the command used by the VCS to check the validity of a log file. - -@item VCS_Repository_Root -The VCS repository root path. This is used to create tags or branches -of the repository. For subversion the value should be the @code{URL} -as specified to check-out the working copy of the repository. - -@item VCS_Patch_Root -The local root directory to use for building patch file. All patch chunks -will be relative to this path. The root project directory is used if -this value is not defined. - -@end table - -@node Package Renamings -@section Package Renamings - -@noindent -A package can be defined by a renaming declaration. The new package renames -a package declared in a different project file, and has the same attributes -as the package it renames. -Syntax: -@smallexample -package_renaming ::== - @b{package} package_identifier @b{renames} - simple_name.package_identifier ; -@end smallexample - -@noindent -The package_identifier of the renamed package must be the same as the -package_identifier. The project whose name is the prefix of the renamed -package must contain a package declaration with this name. This project -must appear in the context_clause of the enclosing project declaration, -or be the parent project of the enclosing child project. - -@node Projects -@section Projects - -@noindent -A project file specifies a set of rules for constructing a software system. -A project file can be self-contained, or depend on other project files. -Dependencies are expressed through a context clause that names other projects. - -Syntax: - -@smallexample -project ::= - context_clause project_declaration - -project_declaration ::= - simple_project_declaration | project_extension - -simple_project_declaration ::= - @b{project} simple_name @b{is} - @{declarative_item@} - @b{end} simple_name; - -context_clause ::= - @{with_clause@} - -with_clause ::= - [@b{limited}] @b{with} path_name @{ , path_name @} ; - -path_name ::= - string_literal -@end smallexample - -@noindent -A path name denotes a project file. A path name can be absolute or relative. -An absolute path name includes a sequence of directories, in the syntax of -the host operating system, that identifies uniquely the project file in the -file system. A relative path name identifies the project file, relative -to the directory that contains the current project, or relative to a -directory listed in the environment variable ADA_PROJECT_PATH. -Path names are case sensitive if file names in the host operating system -are case sensitive. - -The syntax of the environment variable ADA_PROJECT_PATH is a list of -directory names separated by colons (semicolons on Windows). - -A given project name can appear only once in a context_clause. - -It is illegal for a project imported by a context clause to refer, directly -or indirectly, to the project in which this context clause appears (the -dependency graph cannot contain cycles), except when one of the with_clause -in the cycle is a @code{limited with}. - -@node Project Extensions -@section Project Extensions - -@noindent -A project extension introduces a new project, which inherits the declarations -of another project. -Syntax: -@smallexample - -project_extension ::= - @b{project} simple_name @b{extends} path_name @b{is} - @{declarative_item@} - @b{end} simple_name; -@end smallexample - -@noindent -The project extension declares a child project. The child project inherits -all the declarations and all the files of the parent project, These inherited -declaration can be overridden in the child project, by means of suitable -declarations. - -@node Project File Elaboration -@section Project File Elaboration - -@noindent -A project file is processed as part of the invocation of a gnat tool that -uses the project option. Elaboration of the process file consists in the -sequential elaboration of all its declarations. The computed values of -attributes and variables in the project are then used to establish the -environment in which the gnat tool will execute. - @node Obsolescent Features @chapter Obsolescent Features Index: gnat_ugn.texi =================================================================== --- gnat_ugn.texi (revision 161073) +++ gnat_ugn.texi (working copy) @@ -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 Conventio * 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^ @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 pro 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,3794 +11730,203 @@ 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. +@include projects.texi -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. +@c ***************************************** +@c * Cross-referencing tools +@c ***************************************** -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 +@node The Cross-Referencing Tools gnatxref and gnatfind +@chapter The Cross-Referencing Tools @code{gnatxref} and @code{gnatfind} +@findex gnatxref +@findex gnatfind @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}. +The compiler generates cross-referencing information (unless +you set the @samp{-gnatx} switch), which are saved in the @file{.ali} files. +This information indicates where in the source each entity is declared and +referenced. Note that entities in package Standard are not included, but +entities in all other predefined units are included in the output. -@c ***************************** -@c * Examples of Project Files * -@c ***************************** +Before using any of these two tools, you need to compile successfully your +application, so that GNAT gets a chance to generate the cross-referencing +information. -@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. +The two tools @code{gnatxref} and @code{gnatfind} take advantage of this +information to provide the user with the capability to easily locate the +declaration and references to an entity. These tools are quite similar, +the difference being that @code{gnatfind} is intended for locating +definitions and/or references to a specified entity or entities, whereas +@code{gnatxref} is oriented to generating a full report of all +cross-references. -@menu -* Common Sources with Different ^Switches^Switches^ and Directories:: -* Using External Variables:: -* Importing Other Projects:: -* Extending a Project:: -@end menu +To use these tools, you must not compile your application using the +@option{-gnatx} switch on the @command{gnatmake} command line +(@pxref{The GNAT Make Program gnatmake}). Otherwise, cross-referencing +information will not be generated. -@node Common Sources with Different ^Switches^Switches^ and Directories -@subsection Common Sources with Different ^Switches^Switches^ and Directories +Note: to invoke @code{gnatxref} or @code{gnatfind} with a project file, +use the @code{gnat} driver (see @ref{The GNAT Driver and Project Files}). @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):: +* Switches for gnatxref:: +* Switches for gnatfind:: +* Project Files for gnatxref and gnatfind:: +* Regular Expressions in gnatfind and gnatxref:: +* Examples of gnatxref Usage:: +* Examples of gnatfind Usage:: @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 +@node Switches for gnatxref +@section @code{gnatxref} Switches @noindent -The GNAT project files shown below, respectively @file{debug.gpr} and -@file{release.gpr} in the @file{/common} directory, achieve these effects. - -Schematically: +The command invocation for @code{gnatxref} is: @smallexample -@group -^/common^[COMMON]^ - debug.gpr - release.gpr - pack.ads - pack.adb - proc.adb -@end group -@group -^/common/debug^[COMMON.DEBUG]^ - proc.ali, proc.o - pack.ali, pack.o -@end group -@group -^/common/release^[COMMON.RELEASE]^ - proc.ali, proc.o - pack.ali, pack.o -@end group -@end smallexample -Here are the corresponding project files: - -@smallexample @c projectfile -@group -project Debug is - for Object_Dir use "debug"; - for Main use ("proc"); - - package Builder is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-g^-g^"); - for Executable ("proc.adb") use "proc1"; - end Builder; -@end group - -@group - package Compiler is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("-fstack-check", - "^-gnata^-gnata^", - "^-gnato^-gnato^", - "^-gnatE^-gnatE^"); - end Compiler; -end Debug; -@end group +@c $ gnatxref @ovar{switches} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatxref @r{[}@var{switches}@r{]} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]} @end smallexample -@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"}. +@noindent +where -@smallexample @c projectfile -@group -project Build is - for Main use ("proc"); +@table @var +@item sourcefile1 +@itemx sourcefile2 +identifies the source files for which a report is to be generated. The +``with''ed units will be processed too. You must provide at least one file. - type Style_Type is ("deb", "rel"); - Style : Style_Type := external ("STYLE", "deb"); +These file names are considered to be regular expressions, so for instance +specifying @file{source*.adb} is the same as giving every file in the current +directory whose name starts with @file{source} and whose extension is +@file{adb}. - case Style is - when "deb" => - for Object_Dir use "debug"; +You shouldn't specify any directory name, just base names. @command{gnatxref} +and @command{gnatfind} will be able to locate these files by themselves using +the source path. If you specify directories, no result is produced. - when "rel" => - for Object_Dir use "release"; - for Exec_Dir use "."; - end case; -@end group +@end table -@group - package Builder is +@noindent +The switches can be: +@table @option +@c !sort! +@item --version +@cindex @option{--version} @command{gnatxref} +Display Copyright and version, then exit disregarding all other options. - case Style is - when "deb" => - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-g^-g^"); - for Executable ("proc") use "proc1"; - when others => - null; - end case; +@item --help +@cindex @option{--help} @command{gnatxref} +If @option{--version} was not used, display usage, then exit disregarding +all other options. - end Builder; -@end group +@item ^-a^/ALL_FILES^ +@cindex @option{^-a^/ALL_FILES^} (@command{gnatxref}) +If this switch is present, @code{gnatfind} and @code{gnatxref} will parse +the read-only files found in the library search path. Otherwise, these files +will be ignored. This option can be used to protect Gnat sources or your own +libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref} +much faster, and their output much smaller. Read-only here refers to access +or permissions status in the file system for the current user. -@group - package Compiler is +@item -aIDIR +@cindex @option{-aIDIR} (@command{gnatxref}) +When looking for source files also look in directory DIR. The order in which +source file search is undertaken is the same as for @command{gnatmake}. - case Style is - when "deb" => - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-gnata^-gnata^", - "^-gnato^-gnato^", - "^-gnatE^-gnatE^"); +@item -aODIR +@cindex @option{-aODIR} (@command{gnatxref}) +When searching for library and object files, look in directory +DIR. The order in which library files are searched is the same as for +@command{gnatmake}. - when "rel" => - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-O2^-O2^"); - end case; +@item -nostdinc +@cindex @option{-nostdinc} (@command{gnatxref}) +Do not look for sources in the system default directory. - end Compiler; +@item -nostdlib +@cindex @option{-nostdlib} (@command{gnatxref}) +Do not look for library files in the system default directory. -end Build; -@end group -@end smallexample +@item --RTS=@var{rts-path} +@cindex @option{--RTS} (@command{gnatxref}) +Specifies the default location of the runtime library. Same meaning as the +equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}). -@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. +@item ^-d^/DERIVED_TYPES^ +@cindex @option{^-d^/DERIVED_TYPES^} (@command{gnatxref}) +If this switch is set @code{gnatxref} will output the parent type +reference for each matching derived types. -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. +@item ^-f^/FULL_PATHNAME^ +@cindex @option{^-f^/FULL_PATHNAME^} (@command{gnatxref}) +If this switch is set, the output file names will be preceded by their +directory (if the file was found in the search path). If this switch is +not set, the directory will not be printed. -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 +@item ^-g^/IGNORE_LOCALS^ +@cindex @option{^-g^/IGNORE_LOCALS^} (@command{gnatxref}) +If this switch is set, information is output only for library-level +entities, ignoring local entities. The use of this switch may accelerate +@code{gnatfind} and @code{gnatxref}. -@ifset vms -@smallexample -gnatmake /PROJECT_FILE=[COMMON]BUILD.GPR /EXTERNAL_REFERENCE=STYLE=deb -@end smallexample -@end ifset +@item -IDIR +@cindex @option{-IDIR} (@command{gnatxref}) +Equivalent to @samp{-aODIR -aIDIR}. -@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 +@item -pFILE +@cindex @option{-pFILE} (@command{gnatxref}) +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}). -@noindent -since @code{"deb"} is the default for @code{STYLE}. +By default, @code{gnatxref} and @code{gnatfind} will try to locate a +project file in the current directory. -Analogously, +If a project file is either specified or found by the tools, then the content +of the source directory and object directory lines are added as if they +had been specified respectively by @samp{^-aI^/SOURCE_SEARCH^} +and @samp{^-aO^OBJECT_SEARCH^}. +@item ^-u^/UNUSED^ +Output only unused symbols. This may be really useful if you give your +main compilation unit on the command line, as @code{gnatxref} will then +display every unused entity and 'with'ed package. @ifclear vms -@smallexample -gnatmake -P/common/build.gpr -XSTYLE=rel -@end smallexample +@item -v +Instead of producing the default output, @code{gnatxref} will generate a +@file{tags} file that can be used by vi. For examples how to use this +feature, see @ref{Examples of gnatxref Usage}. The tags file is output +to the standard output, thus you will have to redirect it to a file. @end ifclear -@ifset vms -@smallexample -GNAT MAKE /PROJECT_FILE=[COMMON]BUILD.GPR /EXTERNAL_REFERENCE=STYLE=rel -@end smallexample -@end ifset +@end table @noindent -is equivalent to the @command{gnatmake} invocation using the project file -@file{release.gpr} in the earlier example. +All these switches may be in any order on the command line, and may even +appear after the file names. They need not be separated by spaces, thus +you can say @samp{gnatxref ^-ag^/ALL_FILES/IGNORE_LOCALS^} instead of +@samp{gnatxref ^-a -g^/ALL_FILES /IGNORE_LOCALS^}. -@node Importing Other Projects -@subsection Importing Other Projects -@cindex @code{ADA_PROJECT_PATH} -@cindex @code{GPR_PROJECT_PATH} +@node Switches for gnatfind +@section @code{gnatfind} Switches @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: +The command line for @code{gnatfind} is: @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 +@c $ gnatfind @ovar{switches} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]} +@c @r{[}@var{file1} @var{file2} @dots{}] +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatfind @r{[}@var{switches}@r{]} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]} + @r{[}@var{file1} @var{file2} @dots{}@r{]} @end smallexample @noindent -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{'}: -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=^ -@cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool) -Add directory 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^= -@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 -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} simple_name @b{is} - @{declarative_item@} - @b{end} simple_name; - -project_extension ::= - @b{project} simple_name @b{extends} path_name @b{is} - @{declarative_item@} - @b{end} 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} - simple_name.package_identifier ; - -typed_string_declaration ::= - @b{type} _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} simple_name @b{use} - simple_name [ . simple_Name ] ' simple_name ; - -attribute_designator ::= - simple_name | - simple_name ( string_literal ) - -typed_variable_declaration ::= - simple_name : name := string_expression ; - -variable_declaration ::= - simple_name := expression; - -expression ::= - term @{& term@} - -term ::= - literal_string | - string_list | - name | - external_value | - attribute_reference - -string_literal ::= - (same as Ada) - -string_list ::= - ( expression @{ , expression @} ) - -external_value ::= - @b{external} ( string_literal [, string_literal] ) - -attribute_reference ::= - attribute_prefix ' simple_name [ ( literal_string ) ] - -attribute_prefix ::= - @b{project} | - simple_name | package_identifier | - simple_name . package_identifier - -case_construction ::= - @b{case} 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 - -@node The Cross-Referencing Tools gnatxref and gnatfind -@chapter The Cross-Referencing Tools @code{gnatxref} and @code{gnatfind} -@findex gnatxref -@findex gnatfind - -@noindent -The compiler generates cross-referencing information (unless -you set the @samp{-gnatx} switch), which are saved in the @file{.ali} files. -This information indicates where in the source each entity is declared and -referenced. Note that entities in package Standard are not included, but -entities in all other predefined units are included in the output. - -Before using any of these two tools, you need to compile successfully your -application, so that GNAT gets a chance to generate the cross-referencing -information. - -The two tools @code{gnatxref} and @code{gnatfind} take advantage of this -information to provide the user with the capability to easily locate the -declaration and references to an entity. These tools are quite similar, -the difference being that @code{gnatfind} is intended for locating -definitions and/or references to a specified entity or entities, whereas -@code{gnatxref} is oriented to generating a full report of all -cross-references. - -To use these tools, you must not compile your application using the -@option{-gnatx} switch on the @command{gnatmake} command line -(@pxref{The GNAT Make Program gnatmake}). Otherwise, cross-referencing -information will not be generated. - -Note: to invoke @code{gnatxref} or @code{gnatfind} with a project file, -use the @code{gnat} driver (see @ref{The GNAT Driver and Project Files}). - -@menu -* Switches for gnatxref:: -* Switches for gnatfind:: -* Project Files for gnatxref and gnatfind:: -* Regular Expressions in gnatfind and gnatxref:: -* Examples of gnatxref Usage:: -* Examples of gnatfind Usage:: -@end menu - -@node Switches for gnatxref -@section @code{gnatxref} Switches - -@noindent -The command invocation for @code{gnatxref} is: -@smallexample -@c $ gnatxref @ovar{switches} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]} -@c Expanding @ovar macro inline (explanation in macro def comments) -$ gnatxref @r{[}@var{switches}@r{]} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]} -@end smallexample - -@noindent -where - -@table @var -@item sourcefile1 -@itemx sourcefile2 -identifies the source files for which a report is to be generated. The -``with''ed units will be processed too. You must provide at least one file. - -These file names are considered to be regular expressions, so for instance -specifying @file{source*.adb} is the same as giving every file in the current -directory whose name starts with @file{source} and whose extension is -@file{adb}. - -You shouldn't specify any directory name, just base names. @command{gnatxref} -and @command{gnatfind} will be able to locate these files by themselves using -the source path. If you specify directories, no result is produced. - -@end table - -@noindent -The switches can be: -@table @option -@c !sort! -@item --version -@cindex @option{--version} @command{gnatxref} -Display Copyright and version, then exit disregarding all other options. - -@item --help -@cindex @option{--help} @command{gnatxref} -If @option{--version} was not used, display usage, then exit disregarding -all other options. - -@item ^-a^/ALL_FILES^ -@cindex @option{^-a^/ALL_FILES^} (@command{gnatxref}) -If this switch is present, @code{gnatfind} and @code{gnatxref} will parse -the read-only files found in the library search path. Otherwise, these files -will be ignored. This option can be used to protect Gnat sources or your own -libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref} -much faster, and their output much smaller. Read-only here refers to access -or permissions status in the file system for the current user. - -@item -aIDIR -@cindex @option{-aIDIR} (@command{gnatxref}) -When looking for source files also look in directory DIR. The order in which -source file search is undertaken is the same as for @command{gnatmake}. - -@item -aODIR -@cindex @option{-aODIR} (@command{gnatxref}) -When searching for library and object files, look in directory -DIR. The order in which library files are searched is the same as for -@command{gnatmake}. - -@item -nostdinc -@cindex @option{-nostdinc} (@command{gnatxref}) -Do not look for sources in the system default directory. - -@item -nostdlib -@cindex @option{-nostdlib} (@command{gnatxref}) -Do not look for library files in the system default directory. - -@item --RTS=@var{rts-path} -@cindex @option{--RTS} (@command{gnatxref}) -Specifies the default location of the runtime library. Same meaning as the -equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}). - -@item ^-d^/DERIVED_TYPES^ -@cindex @option{^-d^/DERIVED_TYPES^} (@command{gnatxref}) -If this switch is set @code{gnatxref} will output the parent type -reference for each matching derived types. - -@item ^-f^/FULL_PATHNAME^ -@cindex @option{^-f^/FULL_PATHNAME^} (@command{gnatxref}) -If this switch is set, the output file names will be preceded by their -directory (if the file was found in the search path). If this switch is -not set, the directory will not be printed. - -@item ^-g^/IGNORE_LOCALS^ -@cindex @option{^-g^/IGNORE_LOCALS^} (@command{gnatxref}) -If this switch is set, information is output only for library-level -entities, ignoring local entities. The use of this switch may accelerate -@code{gnatfind} and @code{gnatxref}. - -@item -IDIR -@cindex @option{-IDIR} (@command{gnatxref}) -Equivalent to @samp{-aODIR -aIDIR}. - -@item -pFILE -@cindex @option{-pFILE} (@command{gnatxref}) -Specify a project file to use @xref{Project Files}. -If you need to use the @file{.gpr} -project files, you should use gnatxref through the GNAT driver -(@command{gnat xref -Pproject}). - -By default, @code{gnatxref} and @code{gnatfind} will try to locate a -project file in the current directory. - -If a project file is either specified or found by the tools, then the content -of the source directory and object directory lines are added as if they -had been specified respectively by @samp{^-aI^/SOURCE_SEARCH^} -and @samp{^-aO^OBJECT_SEARCH^}. -@item ^-u^/UNUSED^ -Output only unused symbols. This may be really useful if you give your -main compilation unit on the command line, as @code{gnatxref} will then -display every unused entity and 'with'ed package. - -@ifclear vms -@item -v -Instead of producing the default output, @code{gnatxref} will generate a -@file{tags} file that can be used by vi. For examples how to use this -feature, see @ref{Examples of gnatxref Usage}. The tags file is output -to the standard output, thus you will have to redirect it to a file. -@end ifclear - -@end table - -@noindent -All these switches may be in any order on the command line, and may even -appear after the file names. They need not be separated by spaces, thus -you can say @samp{gnatxref ^-ag^/ALL_FILES/IGNORE_LOCALS^} instead of -@samp{gnatxref ^-a -g^/ALL_FILES /IGNORE_LOCALS^}. - -@node Switches for gnatfind -@section @code{gnatfind} Switches - -@noindent -The command line for @code{gnatfind} is: - -@smallexample -@c $ gnatfind @ovar{switches} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]} -@c @r{[}@var{file1} @var{file2} @dots{}] -@c Expanding @ovar macro inline (explanation in macro def comments) -$ gnatfind @r{[}@var{switches}@r{]} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]} - @r{[}@var{file1} @var{file2} @dots{}@r{]} -@end smallexample - -@noindent -where +where @table @var @item pattern @@ -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@ @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 Index: projects.texi =================================================================== --- projects.texi (revision 0) +++ projects.texi (revision 0) @@ -0,0 +1,4032 @@ +@set gprconfig GPRconfig + +@c --------------------------------------------- macro +@c This macro can be used to insert code sample. Each line should end with +@c @NL{}, since otherwise texinfo doesn't guarantee that newlines will be +@c preserved +@macro CODESAMPLE{TXT} +@ifhtml +@smallexample +@group +\TXT\ +@end group +@end smallexample +@end ifhtml +@ifnothtml +@smallexample +@group +\TXT\ +@end group +@end smallexample +@end ifnothtml +@end macro + +@macro PROJECTFILE{TXT} +@CODESAMPLE{\TXT\} +@end macro + +@c simulates a newline when in a @CODESAMPLE +@macro NL{} +@end macro + +@c --------------------------------------------- macro +@c This macro can be used to insert a "Tip" or "Did you know" box. In HTML, +@c this box is displayed in the right margin of the text, and thus doesn't +@c disturbs the normal reading flow, but provides additional useful +@c information. A small icon is displayed on the left of the box. +@c Calls to this macro should be followed by @noindent for proper rendering +@c in pdf +@macro TIP{TXT} +@ifhtml +@html +
+@end html +\TXT\ +@html +
+@end html +@end ifhtml +@ifnothtml +@quotation +@noindent +@c @image{tip,15pt} \TXT\ +@end quotation +@end ifnothtml +@end macro + +@c --------------------------------------------- macro +@c This macro is similar to TIP, but only has an effect in html output, +@c and displayed a note in the margin. This can be used to highlight important +@c points that are repeated in the text. In the other outputs, we do not +@c know how to create margin notes, and whether that would only duplicate +@c information in the main text +@macro TIPHTML{TXT} +@ifhtml +@html +
+@end html +\TXT\ +@html +
+@end html +@end ifhtml +@end macro + +@c --------------------------------------------- macro +@c This macro can be used to insert an "Important" box in the text. +@c This box is displayed inline in the main body of the text, but is +@c surrounded by a frame, and has a small icon on the left. +@c Calls to this macro should be followed by @noindent for proper rendering +@c in pdf +@macro IMPORTANT{TXT} +@ifhtml +@html +
+@end html +\TXT\ +@html +
+@end html +@end ifhtml +@ifnothtml +@quotation +@noindent +@c @image{important,15pt} \TXT\ +@end quotation +@end ifnothtml +@end macro + +@c --------------------------------------------- macro +@c This macro can be used to insert a "Note" box in the text. It is +@c displayed inline in the main body of the text, but has a different +@c icon that the "Important" box +@c Calls to this macro should be followed by @noindent for proper rendering +@c in pdf +@macro NOTE{TXT} +@ifhtml +@html +
+@end html +\TXT\ +@html +
+@end html +@end ifhtml +@ifnothtml +@quotation +@noindent +@c @image{note,15pt} \TXT\ +@end quotation +@end ifnothtml +@end macro + +@c --------------------------------------------- macro +@c This macro creates index entries. Optionally, it can display that +@c entry in the right-side margin of the text in HTML, to help people +@c locate where exactly the index entry points to. + +@macro CINDEX{TXT} +@cindex \TXT\ +@ifset useindex +@ifhtml +@html +
+@end html +\TXT\ +@html +
+@end html +@end ifhtml +@end ifset +@end macro + +@menu +* GNAT Project Manager:: +* Tools Supporting Project Files:: +@end menu + +@c --------------------------------------------- +@node GNAT Project Manager +@chapter GNAT Project Manager +@c --------------------------------------------- + +@noindent + + +@menu +* Introduction:: +* Building With Projects:: +* Organizing Projects into Subsystems:: +* Scenarios in Projects:: +* Library Projects:: +* Project Extension:: +* Project File Reference:: +@end menu + +@c --------------------------------------------- +@node Introduction +@section Introduction +@c --------------------------------------------- + +@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 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, etc.) is to be placed +@item The directory in which the executable programs are to be placed +@item Switch settings for any of the project-enabled tools; + 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) +@item Source file naming conventions; you can specify these either globally or for + individual compilation units (@pxref{Naming Schemes}). +@item Change any of the above settings depending on external values, thus enabling + the reuse of the projects in various @b{scenarios} (@pxref{Scenarios + in Projects}). +@item Automatically build libraries as part of the build process + (@pxref{Library Projects}). + +@end itemize + +@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 (@pxref{Project File Reference}). + +Project files can be built hierarchically from other project files, simplifying +complex system integration and project reuse (@pxref{Organizing Projects into +Subsystems}). + +@itemize @bullet +@item One project can import other projects containing needed source files. + 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 settings) used for different subsystems. +@item You can organize GNAT projects in a hierarchy: a child project + can extend a parent project, inheriting the parent's source files and + optionally overriding any of them with alternative versions + (@pxref{Project Extension}). + +@end itemize + +@noindent +Several tools support project files, generally in addition to specifying +the information on the command line itself). They share common switches +to control the loading of the project (in particular +@option{^-P^/PROJECT_FILE=^@emph{projectfile}} and +@option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}}). +@xref{Switches Related to Project Files}. + +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 and generating object files in different + directories via different switch settings. It can be used for instance, for + generating separate sets of object files for debugging and for production. +@item Using a mostly-shared set of source files with different versions of + some units or subunits. It can be used for instance, for grouping and hiding +@end itemize + +@noindent +all OS dependencies in a small number of implementation units. + +Project files can be used 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 tool +that might be used by the developers. + +The various sections below introduce the different concepts related to +projects. Each section starts with examples and use cases, and then goes into +the details of related project file capabilities. + +@c --------------------------------------------- +@node Building With Projects +@section Building With Projects +@c --------------------------------------------- + +@noindent +In its simplest form, a unique project is used to build a single executable. +This section concentrates on such a simple setup. Later sections will extend +this basic model to more complex setups. + +The following concepts are the foundation of project files, and will be further +detailed later in this documentation. They are summarized here as a reference. + +@table @asis +@item @b{Project file}: + A text file using an Ada-like syntax, generally using the @file{.gpr} + extension. It defines build-related characteristics of an application. + The characteristics include the list of sources, the location of those + sources, the location for the generated object files, the name of + the main program, and the options for the various tools involved in the + build process. + +@item @b{Project attribute}: + A specific project characteristic is defined by an attribute clause. Its + value is a string or a sequence of strings. All settings in a project + are defined through a list of predefined attributes with precise + semantics. @xref{Attributes}. + +@item @b{Package in a project}: + Global attributes are defined at the top level of a project. + Attributes affecting specific tools are grouped in a + package whose name is related to tool's function. The most common + packages are @code{Builder}, @code{Compiler}, @code{Binder}, + and @code{Linker}. @xref{Packages}. + +@item @b{Project variables}: + In addition to attributes, a project can use variables to store intermediate + values and avoid duplication in complex expressions. It can be initialized with a value coming from the environment + Z frequent use of variables is to define scenarios. + @xref{External Values}, @xref{Scenarios in Projects}, and @xref{Variables}. + +@item @b{Source files} and @b{source directories}: + A source file is associated with a language through a naming convention. For + instance, @code{foo.c} is typically the name of a C source file; + @code{bar.ads} or @code{bar.1.ada} are two common naming conventions for a + file containing an Ada spec. A compilation unit is often composed of a main + source file and potentially several auxiliary ones, such as header files in C. + The naming conventions can be user defined @xref{Naming Schemes}, and will + drive the builder to call the appropriate compiler for the given source file. + Source files are searched for in the source directories associated with the + project through the @b{Source_Dirs} attribute. By default, all the files (in + these source directories) following the naming conventions associated with the + declared languages are considered to be part of the project. It is also + possible to limit the list of source files using the @b{Source_Files} or + @b{Source_List_File} attributes. Note that those last two attributes only + accept basenames with no directory information. + +@item @b{Object files} and @b{object directory}: + An object file is an intermediate file produced by the compiler from a + compilation unit. It is used by post-compilation tools to produce + final executables or libraries. Object files produced in the context of + a given project are stored in a single directory that can be specified by the + @b{Object_Dir} attribute. In order to store objects in + two or more object directories, the system must be split into + distinct subsystems with their own project file. + +@end table + +The following subsections introduce gradually all the attributes of interest +for simple build needs. Here is the simple setup that will be used in the +following examples. + +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 with the switch @option{-O2}, and put the resulting files in +the directory @file{obj/}. + +@smallexample +@group +^common/^[COMMON]^ + pack.ads + pack.adb + proc.adb +@end group +@group +^common/release/^[COMMON.RELEASE]^ + proc.ali, proc.o pack.ali, pack.o +@end group +@end smallexample + +@noindent +Our project is to be called @emph{Build}. By convention, the name of the +file is the name of the project (lower-cased) with the +@file{.gpr} extension, therefore the project file name is @file{build.gpr}. This +is not mandatory, but a warning is issued when this convention is not followed. + +This is a very simple example, and as stated above, a single project +file is enough for it. We will thus create a new file, that for now +should contain the following code: + +@smallexample +@b{project} Build @b{is} +@b{end} Build; +@end smallexample + +@menu +* Source Files and Directories:: +* Object and Exec Directory:: +* Main Subprograms:: +* Tools Options in Project Files:: +* Compiling with Project Files:: +* Executable File Names:: +* Avoid Duplication With Variables:: +* Naming Schemes:: +@end menu + +@c --------------------------------------------- +@node Source Files and Directories +@subsection Source Files and Directories +@c --------------------------------------------- + +@noindent +When you create a new project, the first thing to describe is how to find the +corresponding source files. This is the only settings that are needed by all +the tools that will use this project (builder, compiler, binder and linker for +the compilation, IDEs to edit the source files,@dots{}). + +@CINDEX{Source directories} +First step is to declare the source directories, which are the directories +to be searched to find source files. In the case of the example, +the @file{common} directory is the only source directory. + +@CINDEX{@code{Source_Dirs}} +There are several ways of defining source directories: + +@itemize @bullet +@item When the attribute @b{Source_Dirs} is not used, a project contains a + single source directory which is the one where the project file itself resides. + In our example, if @file{build.gpr} is placed in the @file{common} directory, + the project has the needed implicit source directory. + +@item The attribute @b{Source_Dirs} can be set to a list of path names, one + for each of the source directories. Such paths can either be absolute + names (for instance @file{"/usr/local/common/"} on UNIX), or relative to the + directory in which the project file resides (for instance "." if + @file{build.gpr} is inside @file{common/}, or "common" if it is one level up). + Each of the source directories must exist and be readable. + + @CINDEX{portability} + The syntax for directories is platform specific. For portability, however, the + project manager will always properly translate UNIX-like path names to the + native format of specific platform. For instance, when the same project file + is to be used both on Unix and Windows, "/" should be used as the directory + separator rather than "\". + +@item The attribute @b{Source_Dirs} can automatically include subdirectories using + a special syntax inspired by some UNIX shells. If any of the path in the + list ends with @emph{"/**"}, then that path and all its subdirectories + (recursively) are included in the list of source directories. For + instance, @file{./**} represent the complete directory tree rooted at ".". + @CINDEX{Source directories, recursive} + + @CINDEX{@code{Excluded_Source_Dirs}} + When using that construct, it can sometimes be convenient to also use + the attribute @b{Excluded_Source_Dirs}, which is also a list of paths. + Each entry specifies a directory whose immediate content, not including + subdirs, is to be excluded. It is also possible to exclude a complete directory + subtree using the "**" notation. + +@end itemize + +@noindent +When applied to the simple example, and because we generally prefer to have +the project file at the toplevel directory rather than mixed with the sources, +we will create the following file + +@smallexample + build.gpr + @b{project} Build @b{is} + @b{for} Source_Dirs @b{use} ("common"); -- <<<< + @b{end} Build; +@end smallexample + +@noindent +Once source directories have been specified, one may need to indicate +source files of interest. By default, all source files present in the source +directories are considered by the project manager. When this is not desired, +it is possible to specify the list of sources to consider explicitly. +In such a case, only source file base names are indicated and not +their absolute or relative path names. The project manager is in charge of +locating the specified source files in the specified source directories. + +@itemize @bullet +@item By default, the project manager search for all source files of all + specified languages in all the source directories. + + Since the project manager was initially developed for Ada environments, the + default language is Ada and the above project file is complete: it defines + without ambiguity the sources composing the project: that is to say, all + the sources in subdirectory "common" for the default language (Ada) using + the default naming convention. + + @CINDEX{@code{Languages}} + However, when compiling a multi-language application, or a pure C + application, the project + manager must be told which languages are of interest, which is done by setting + the @b{Languages} attribute to a list of strings, each of which is the + name of a language. Tools like @command{gnatmake} only know about Ada, + while other tools like @command{gprbuild} know about many more + languages such as C, C++, Fortran, assembly and others can be added dynamically. + + @CINDEX{Naming scheme} + Even when using only Ada, the default naming might not be suitable. Indeed, + how does the project manager recognizes an "Ada file" from any other + file ? Project files can describe the naming scheme used for source files, + and override the default (@pxref{Naming Schemes}). The default is the + standard GNAT extension (@file{.adb} for bodies and @file{.ads} for + specs), which is what is used in our example, explaining why no naming scheme + is explicitly specified. + @xref{Naming Schemes}. + +@item @CINDEX{@code{Source_Files}} + In some cases, source directories might contain files that should not be + included in a project. One can specify the explicit list of file names to + be considered through the @b{Source_Files} attribute. + When this attribute is defined, instead of looking at every file in the + source directories, the project manager takes only those names into + consideration reports errors if they cannot be found in the source + directories or does not correspond to the naming scheme. + +@item For various reasons, it is sometimes useful to have a project with no + sources (most of the time because the attributes defined in the project + file will be reused in other projects, as explained in @pxref{Organizing + Projects into Subsystems}. To do this, the attribute + @emph{Source_Files} is set to the empty list, i.e. @code{()}. Alternatively, + @emph{Source_Dirs} can be set to the empty list, with the same + result. + +@item @CINDEX{@code{Source_List_File}} + If ther is a great number of files, it might be more convenient to use + the attribute @b{Source_List_File}, which specifies the full path of a file. + This file must contain a list of source file names (one per line, no + directory information) that are searched as if they had been defined + through @emph{Source_Files}. Such a file can easily be created through + external tools. + + 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. + +@item @CINDEX{@code{Excluded_Source_Files}} + @CINDEX{@code{Locally_Removed_Files}} + @CINDEX{@code{Excluded_Source_List_File}} + Specifying an explicit list of files is not always convenient.It might be + more convenient to use the default search rules with specific exceptions. + This can be done thanks to the attribute @b{Excluded_Source_Files} + (or its synonym @b{Locally_Removed_Files}). + Its value is the list of file names that should not be taken into account. + This attribute is often used when extending a project, @xref{Project Extension}. + A similar attribute @b{Excluded_Source_List_File} plays the same role + but takes the name of file containing file names similarly to + @code{Source_List_File}. + +@end itemize + +@noindent +In most simple cases, such as the above example, the default source file search +behavior provides the expected result, and we do not need to add anything after +setting @code{Source_Dirs}. The project manager automatically finds +@file{pack.ads}, @file{pack.adb} and @file{proc.adb} as source files of the +project. + +Note that it is considered an error for a project file to have no sources +attached to it unless explicitly declared as mentionend above. + +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 sitting in different directories +of the project. In this case, only the file in the first directory is considered +as a source of the project and the others are hidden. 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, since there would be an ambiguity as to which one +should be used. + +@c --------------------------------------------- +@node Object and Exec Directory +@subsection Object and Exec Directory +@c --------------------------------------------- + +@noindent +The next step when writing a project is to indicate where the compiler should +put the object files. In fact, the compiler and other tools might create several +different kind of files (for GNAT, there is the @code{.o} object file and the +@code{.ali} file for instance). One of the important concepts in projects is +that most tools may consider source directories as read-only and do not attempt +to create new or temporary files there. Instead, all files are created +in the object directory. It is of course not true for project-aware IDEs, +whose purpose it is to create the source files. + +@CINDEX{@code{Object_Dir}} +The object directory is specified through the @b{Object_Dir} attribute. +Its value is the path to the object directory, either absolute or +relative to the directory containing the project file. This +directory must already exist and be readable and writable, although +some tools have a switch to create the directory if needed (See +the switch @code{-p} for @command{gnatmake} and @command{gprbuild}). + +If the attribute @code{Object_Dir} is not specified, it defaults to +the directory that contains the project file. + +For our example, we can specify the object dir in this way: + +@smallexample + @b{project} Build @b{is} + @b{for} Source_Dirs @b{use} ("common"); + @b{for} Object_Dir @b{use} "obj"; -- <<<< + @b{end} Build; +@end smallexample + +@noindent +As mentioned earlier, there is a single object directory per project. +As a result, if you have an existing system where the object files are spread +in several directories, you can either move all of them into the same directory +if you want to build it with a single project file, or +study the section on subsystems +(@pxref{Organizing Projects into Subsystems}) to see how each separate object +directory can be associated with one of the subsystem constituting the application. + +When the @command{linker} is called, it usually creates an executable. By +default, this executable is placed in the object directory of the project. It +might be convenient to store it in its own directory. + +@CINDEX{@code{Exec_Dir}} +This can be done through the @code{Exec_Dir} attribute, which, like +@emph{Object_Dir} contains a single absolute or relative path and must point to +an existing and writable directory, unless you ask the tool to create it on your +behalf. When not specified, It defaults to the object directory and therefore to +the project file's directory if neither @emph{Object_Dir} nor @emph{Exec_Dir} +was specified. + +In the case of the example, let's place the executable in the root +of the hierarchy, ie the same directory as @file{build.gpr}. Hence +the project file is now + +@smallexample + @b{project} Build @b{is} + @b{for} Source_Dirs @b{use} ("common"); + @b{for} Object_Dir @b{use} "obj"; + @b{for} Exec_Dir @b{use} "."; -- <<<< + @b{end} Build; +@end smallexample + +@c --------------------------------------------- +@node Main Subprograms +@subsection Main Subprograms +@c --------------------------------------------- + +@noindent +In the previous section, executables were mentioned. The project manager needs +to be taught what they are. In a project file, an executable is indicated by +pointing to source file of the main subprogram. In C this is the file that +contains the @code{main} function, and in Ada the file that contains the main +unit. + +There can be any number of such main files within a given project, and thus +several executables can be built in the context of a single project file. Of +course, one givene executable might not (and in fact will not) need all the +source files referenced by the project. As opposed to other build environments +such as @command{makefile}, one does not need to specify the list of +dependencies of each executable, the project-aware builders knows enough of the +semantics of the languages to build ands link only the necessary elements. + +@CINDEX{@code{Main}} +The list of main files is specified via the @b{Main} attribute. It contains +a list of file names (no directories). If a project defines this +attribute, it is not necessary to identify main files on the +command line when invoking a builder, and editors like +@command{GPS} will be able to create extra menus to spawn or debug the +corresponding executables. + +@smallexample + @b{project} Build @b{is} + @b{for} Source_Dirs @b{use} ("common"); + @b{for} Object_Dir @b{use} "obj"; + @b{for} Exec_Dir @b{use} "."; + @b{for} Main @b{use} ("proc.adb"); -- <<<< + @b{end} Build; +@end smallexample + +@noindent +If this attribute is defined in the project, then spawning the builder +with a command such as + +@smallexample + gnatmake ^-Pbuild^/PROJECT_FILE=build^ +@end smallexample + +@noindent +automatically builds all the executables corresponding to the files +listed in the @emph{Main} attribute. It is possible to specify one +or more executables on the command line to build a subset of them. + +@CINDEX{@code{Main_Language}} +The attribute @b{Main_Language} contains a string that specifies the +language of the main program. +@c ??? What is this for, we already have the naming scheme + +@c --------------------------------------------- +@node Tools Options in Project Files +@subsection Tools Options in Project Files +@c --------------------------------------------- + +@noindent +We now have a project file that fully describes our environment, and can be used +to build the application with a simple @command{gnatmake} command as seen in the +previous section. In fact, the empty project we showed immediately at the +beginning (with no attribute at all) could already fullfill that need if it was +put in the @file{common} directory. + +Of course, we always want more control. This section will show you how to +specify the compilation switches that the various tools involved in the +building of the executable should use. + +@CINDEX{command line length} +Since source names and locations are described into the project file, it is not +necessary to use switches on the command line for this purpose (switches such as +-I for gcc). This removes a major source of command line length overflow. +Clearly, the builders will have to communicate this information one way or +another to the underlying compilers and tools they call but they usually use +response files for this and thus should not be subject to command line +overflows. + +Several tools are participating to the creation of an executable: the +compiler produces object files from the source files; the binder (in the Ada +case) creates an source file that takes care, among other things, of elaboration +issues and global variables initialization; and the linker gathers everything +into a single executable that users can execute. All these tools are known by +the project manager and will be called with user defined switches from the +project files. However, we need to introduce a new project file concept to +express which switches to be used for any of the tools involved in the build. + +@CINDEX{project file packages} +A project file is subdivided into zero or more @b{packages}, each of which +contains the attributes specific to one tool (or one set of tools). Project +files use an Ada-like syntax for packages. Package names permitted in project +files are restricted to a predefined set (@pxref{Packages}), and the contents of +packages are limited to a small set of constructs and attributes +(@pxref{Attributes}). + +Our example project file can be extended with the following empty +packages. At this stage, they could all be omitted since they are empty, +but they show which packages would be involved in the build process. + +@smallexample + @b{project} Build @b{is} + @b{for} Source_Dirs @b{use} ("common"); + @b{for} Object_Dir @b{use} "obj"; + @b{for} Exec_Dir @b{use} "."; + @b{for} Main @b{use} ("proc.adb"); + @b{end} Build; + + @b{package} Builder @b{is} --<<< for gnatmake and gprbuild + @b{end} Builder; + + @b{package} Compiler @b{is} --<<< for the compiler + @b{end} Builder; + + @b{package} Binder @b{is} --<<< for the binder + @b{end} Builder; + + @b{package} Linker @b{is} --<<< for the linker + @b{end} Builder; +@end smallexample + +@noindent +Let's first examine the compiler switches. As stated in the initial description +of the example, we want to compile all files with @option{-O2}. This is a +compiler switch, although it is usual, on the command line, to pass it to the +builder which then passes it to the compiler. It is recommended to use directly +the right package, which will make the setup easier to understand for other +people. + +Several attributes can be used to specify the switches: + +@table @asis +@item @b{Default_Switches}: + @CINDEX{@code{Default_Switches}} + This is the first mention in this manual of an @b{indexed attribute}. When + this attribute is defined, one must supply an @emph{index} in the form of a + literal string. + In the case of @emph{Default_Switches}, the index is the name of the + language to which the switches apply (since a different compiler will + likely be used for each language, and each compiler has its own set of + switches). The value of the attribute is a list of switches. + + In this example, we want to compile all Ada source files with the + @option{-O2} switch, and the resulting project file is as follows + (only the @code{Compiler} package is shown): + + @smallexample + @b{package} Compiler @b{is} + @b{for} Default_Switches ("Ada") @b{use} ("-O2"); + @b{end} Compiler; + @end smallexample + +@item @b{Switches}: + @CINDEX{@code{Switches}} + in some cases, we might want to use specific switches + for one or more files. For instance, compiling @file{proc.adb} might not be + possible at high level of optimization because of a compiler issue. + In such a case, the @emph{Switches} + attribute (indexed on the file name) can be used and will override the + switches defined by @emph{Default_Switches}. Our project file would + become: + + @smallexample + @b{package} Compiler @b{is} + @b{for} Default_Switches ("Ada") @b{use} ("-O2"); + @b{for} Switches ("proc.adb") @b{use} ("-O0"); + @b{end} Compiler; + @end smallexample + + @noindent + @code{Switches} can also be given a language name as index instead of a file name + in which case it has the same semantics as @emph{Default_Switches}. + +@item @b{Local_Configuration_Pragams}: + @CINDEX{@code{Local_Configuration_Pragmas}} + this attribute may specify the path + of a file containing configuration pragmas for use by the Ada compiler, + such as @code{pragma Restrictions (No_Tasking)}. These pragmas will be + used for all the sources of the project. + +@end table + +The switches for the other tools are defined in a similar manner through the +@b{Default_Switches} and @b{Switches} attributes, respectively in the +@emph{Builder} package (for @command{gnatmake} and @command{gprbuild}), +the @emph{Binder} package (for @command{gnatbind} and @command{gprbind}) +and the @emph{Linker} package (for @command{gnatlink} and @command{gprlink}). + +@c --------------------------------------------- +@node Compiling with Project Files +@subsection Compiling with Project Files +@c --------------------------------------------- + +@noindent +Now that our project files are written, let's build our executable. +Here is the command we would use from the command line: + +@smallexample + gnatmake ^-Pbuild^/PROJECT_FILE=build^ +@end smallexample + +@noindent +This will automatically build the executables specified through the +@emph{Main} attribute: for each, it will compile or recompile the +sources for which the object file does not exist or is not up-to-date; it +will then run the binder; and finally run the linker to create the +executable itself. + +@command{gnatmake} only knows how to handle Ada files. By using +@command{gprbuild} as a builder, you could automatically manage C files the +same way: create the file @file{utils.c} in the @file{common} directory, +set the attribute @emph{Languages} to @code{"(Ada, C)"}, and run + +@smallexample + gprbuild ^-Pbuild^/PROJECT_FILE=build^ +@end smallexample + +@noindent +Gprbuild knows how to recompile the C files and will +recompile them only if one of their dependencies has changed. No direct +indication on how to build the various elements is given in the +project file, which describes the project properties rather than a +set of actions to be executed. Here is the invocation of +@command{gprbuild} when building a multi-language program: + +@smallexample +$ gprbuild -Pbuild +gcc -c proc.adb -o proc.o +gcc -c pack.adb -o pack.o +gcc -c utils.c -o utils.o +gprbind proc +... +gcc proc.o -o proc.exe +@end smallexample + +@noindent +Notice the three steps described earlier: + +@itemize @bullet +@item The first three gcc commands correspond to the compilation phase. +@item The gprbind command corresponds to the post-compilation phase. +@item The last gcc command corresponds to the final link. + +@end itemize + +@noindent +@CINDEX{@option{-v} option (for GPRbuild)} +The default output of GPRbuild's execution is kept reasonably simple and easy to +understand. In particular, some of the less frequently used commands are not +shown, and some parameters are abbreviated. So it is not possible to rerun the +effect ofthe gprbuild command by cut-and-pasting its output. GPRbuild's option +@code{-v} provides a much more verbose output which includes, among other +information, more complete compilation, post-compilation and link commands. + +@c --------------------------------------------- +@node Executable File Names +@subsection Executable File Names +@c --------------------------------------------- + +@noindent +@CINDEX{@code{Executable}} +By default, the executable name corresponding to a main file is +computed from the main source file name. Through the attribute +@b{Builder.Executable}, it is possible to change this default. + +For instance, instead of building @command{proc} (or @command{proc.exe} +on Windows), we could configure our project file to build "proc1" +(resp proc1.exe) with the following addition: + +@smallexample @c projectfile + project Build is + ... -- same as before + package Builder is + for Executable ("proc.adb") use "proc1"; + end Builder + end Build; +@end smallexample + +@noindent +@CINDEX{@code{Executable_Suffix}} +Attribute @b{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. +By default, the latter is empty on UNIX and ".exe" on Windows. + +It is also possible to change the name of the produced executable by using the +command line switch @option{-o}. when several mains are defined in the project, +it is not possible to use the @option{-o} switch and the only way to change the +names of the executable is provided by Attributes @code{Executable} and +@code{Executable_Suffix}. + +@c --------------------------------------------- +@node Avoid Duplication With Variables +@subsection Avoid Duplication With Variables +@c --------------------------------------------- + +@noindent +To illustrate some other project capabilities, here is a slightly more complex +project using similar sources and a main program in C: + +@smallexample @c projectfile +project C_Main is + for Languages use ("Ada", "C"); + for Source_Dirs use ("common"); + for Object_Dir use "obj"; + for Main use ("main.c"); + package Compiler is + C_Switches := ("-pedantic"); + for Default_Switches ("C") use C_Switches; + for Default_Switches ("Ada") use ("-gnaty"); + for Switches ("main.c") use C_Switches & ("-g"); + end Compiler; +end C_Main; +@end smallexample + +@noindent +This project has many similarities with the previous one. +As expected, its @code{Main} attribute now refers to a C source. +The attribute @emph{Exec_Dir} is now omitted, thus the resulting +executable will be put in the directory @file{obj}. + +The most noticeable difference is the use of a variable in the +@emph{Compiler} package to store settings used in several attributes. +This avoids text duplication, and eases maintenance (a single place to +modify if we want to add new switches for C files). We will revisit +the use of variables in the context of scenarios (@pxref{Scenarios in +Projects}). + +In this example, we see how the file @file{main.c} can be compiled with +the switches used for all the other C files, plus @option{-g}. +In this specific situation the use of a variable could have been +replaced by a reference to the @code{Default_Switches} attribute: + +@smallexample @c projectfile + for Switches ("c_main.c") use Compiler'Default_Switches ("C") & ("-g"); +@end smallexample + +@noindent +Note the tick (@emph{'}) used to refer to attributes defined in a package. + +Here is the output of the GPRbuild command using this project: + +@smallexample +$gprbuild -Pc_main +gcc -c -pedantic -g main.c -o main.o +gcc -c -gnaty proc.adb -o proc.o +gcc -c -gnaty pack.adb -o pack.o +gcc -c -pedantic utils.c -o utils.o +gprbind main +... +gcc main.o -o main.exe +@end smallexample + +@noindent +The default switches for Ada sources, +the default switches for C sources (in the compilation of @file{lib.c}), +and the specific switches for @file{c_main.c} have all been taken into +account. + +@c --------------------------------------------- +@node Naming Schemes +@subsection Naming Schemes +@c --------------------------------------------- + +@noindent +Sometimes an Ada software system is ported from one compilation environment to +another (say GNAT), and the file are not named using 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 @b{Naming} package of your project file. + +The naming scheme has two distinct goals for the project manager: it +allows finding of source files when searching in the source +directories, and given a source file name it makes it possible to guess +the associated language, and thus the compiler to use. + +Note that the use of pragmas described in +@ref{Alternative File Naming Schemes,,,gnat_ugn} 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 specify +other configuration pragmas (@pxref{Specifying Configuration Pragmas}). + +The following attributes can be defined in package @code{Naming}: + +@table @asis +@item @b{Casing}: + @CINDEX{@code{Casing}} + Its value must be one of @code{"lowercase"} (the default if + unspecified), @code{"uppercase"} or @code{"mixedcase"}. It describes the + casing of file names with regards to the Ada unit name. Given an Ada unit + My_Unit, the file name will respectively be @file{my_unit.adb} (lowercase), + @file{MY_UNIT.ADB} (uppercase) or @file{My_Unit.adb} (mixedcase). + On Windows, file names are case insensitive, so this attribute is + irrelevant. + +@item @b{Dot_Replacement}: + @CINDEX{@code{Dot_Replacement}} + This attribute specifies the string that should replace the "." in unit + names. Its default value is @code{"-"} so that a unit + @code{Parent.Child}is expected to be found in the file @file{parent-child.adb}. + The replacement string must satisfy the following requirements to + avoid ambiguities in the naming scheme: + + @itemize - + @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 + +@item @b{Spec_Suffix} and @b{Specification_Suffix}: + @CINDEX{@code{Spec_Suffix}} + @CINDEX{@code{Specification_Suffix}} + For Ada, these attributes give the suffix used in file names that contain + specifications. For other languages, they give the extension for files + that contain declaration (header files in C for instance). The attribute + is indexed on the language. + The two attributes are equivalent, but the latter is obsolescent. + If @code{Spec_Suffix ("Ada")} is not specified, then the default is + @code{"^.ads^.ADS^"}. + The value must satisfy the following requirements: + + @itemize - + @item It must not be empty + @item It cannot start with an alphanumeric character + @item It cannot start with an underscore followed by an alphanumeric character + @item It must include at least one dot + + @end itemize + +@item @b{Body_Suffix} and @b{Implementation_Suffix}: + @CINDEX{@code{Body_Suffix}} + @CINDEX{@code{Implementation_Suffix}} + These attributes give the extension used for file names that contain + code (bodies in Ada). They are indexed on the language. The second + version is obsolescent and fully replaced by the first attribute. + + These attributes must satisfy the same requirements as @code{Spec_Suffix}. + In addition, they must be different from any of the values in + @code{Spec_Suffix}. + If @code{Body_Suffix ("Ada")} is not specified, then the default is + @code{"^.adb^.ADB^"}. + + 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 capability is usually not interesting when building. + 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). + +@item @b{Separate_Suffix}: + @CINDEX{@code{Separate_Suffix}} + This attribute is specific to Ada. It denotes the suffix used in file names + that contain separate bodies. If it is not specified, then it defaults to + same value as @code{Body_Suffix ("Ada")}. The same rules apply as for the + @code{Body_Suffix} attribute. The only accepted index is "Ada". + +@item @b{Spec} or @b{Specification}: + @CINDEX{@code{Spec}} + @CINDEX{@code{Specification}} + This attribute @code{Spec} can be used to define the source file name for a + given Ada compilation unit's spec. The index is the literal name of the Ada + unit (case insensitive). The value is the literal base name of the file that + contains this unit's spec (case sensitive or insensitive depending on the + operating system). This attribute allows the definition of exceptions to the + general naming scheme, in case some files do not follow the usual + convention. + + When a source file contains several units, the relative position of the unit + can be indicated. The first unit in the file is at position 1 + + @smallexample @c projectfile + for Spec ("MyPack.MyChild") use "mypack.mychild.spec"; + for Spec ("top") use "foo.a" at 1; + for Spec ("foo") use "foo.a" at 2; + @end smallexample + +@item @b{Body} or @b{Implementation}: + @CINDEX{@code{Body}} + @CINDEX{@code{Implementation}} + These attribute play the same role as @emph{Spec} for Ada bodies. + +@item @b{Specification_Exceptions} and @b{Implementation_Exceptions}: + @CINDEX{@code{Specification_Exceptions}} + @CINDEX{@code{Implementation_Exceptions}} + These attributes define exceptions to the naming scheme for languages + other than Ada. They are indexed on the language name, and contain + a list of file names respectively for headers and source code. + + +@end table + +@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"; + for Body_Suffix ("Ada") use ".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 + +@c --------------------------------------------- +@node Organizing Projects into Subsystems +@section Organizing Projects into Subsystems +@c --------------------------------------------- + +@noindent +A @b{subsystem} is a coherent part of the complete system to be built. It is +represented by a set of sources and one single object directory. A system can be +composed of a single subsystem when it is simple as we have seen in the first +section,. Complex systems are usually composed of several interdependent +subsystems. A subsystem is dependent on another subsystem if knowledge of the +other one is required to build it, and in particular if visibility on some of +the sources of this other subsystem is required. Each subsystem is usually +represented by its own project file. + +In this section, the previous example is being extended. Let's assume some +sources of our @code{Build} project depend on other sources. +For instance, when building a graphical interface, it is usual to depend upon +a graphical library toolkit such as GtkAda. Furthermore, we also need +sources from a logging module we had previously written. + +@menu +* Project Dependencies:: +* Cyclic Project Dependencies:: +* Sharing Between Projects:: +* Global Attributes:: +@end menu + +@c --------------------------------------------- +@node Project Dependencies +@subsection Project Dependencies +@c --------------------------------------------- + +@noindent +GtkAda comes with its own project file (appropriately called +@file{gtkada.gpr}), and we will assume we have already built a project +called @file{logging.gpr} for the logging module. With the information provided +so far in @file{build.gpr}, building the application would fail with an error +indicating that the gtkada and logging units that are relied upon by the sources +of this project cannot be found. + +This is easily solved by adding the following @b{with} clauses at the beginning +of our project: + +@smallexample @c projectfile + with "gtkada.gpr"; + with "a/b/logging.gpr"; + project Build is + ... -- as before + end Build; +@end smallexample + +@noindent +@CINDEX{@code{Externally_Built}} +When such a project is compiled, @command{gnatmake} will automatically +check the other projects and recompile their sources when needed. It will also +recompile the sources from @code{Build} when needed, and finally create the +executable. In some cases, +the implementation units needed to recompile a project are not available, +or come from some third-party and +you do not want to recompile it yourself. In this case, the +attribute @b{Externally_Built} to "true" can be set, indicating to the builder + that this project can be assumed to be up-to-date, and should not be considered +for recompilation. In Ada, if the sources of this externally built project +were compiled with another version of the compiler or with incompatible options, +the binder will issue an error. + +The project's @code{with} clause has several effects. It provides source +visibility between projects during the compilation process. +It also guarantees that the necessary object files from @code{Logging} +and @code{GtkAda} are available when +linking @code{Build}. + +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 after @code{with} is the path +(absolute or relative) to a project file. The @code{.gpr} extension is +optional, although we recommend adding it. If no extension is specified, +and no project file with the @file{^.gpr^.GPR} extension is found, then +the file is searched for exactly as written in the @code{with} clause, +that is with no extension. + +@CINDEX{project path} +When a relative path or a base name is used, the +project files are searched relative to each of the directories in the +@b{project path}. This path includes all the directories found with the +following algorithm, in that order, as soon as a matching file is found, +the search stops: + +@itemize @bullet +@item First, the file is searched relative to the directory that contains the + current project file. +@item @CINDEX{@code{ADA_PROJECT_PATH}} + @CINDEX{@code{GPR_PROJECT_PATH}} + Then it is searched relative to all the directories specified in the + ^environment variables^logical names^ @b{GPR_PROJECT_PATH} and + @b{ADA_PROJECT_PATH} (in that order) if they exist.. The former is + recommended, the latter is kept for backward compatibility. +@item Finally, it is searched relative to the default project directories. + Such directories are defined by the compiler and are relative to the + installation directory of that compiler (in the @file{lib/gnat/} and + @file{lib/gpr/} subdirectories). In our example, @file{gtkada.gpr} + is found in the predefined directory if it was installed at the same root + as GNAT. + +@end itemize + +@noindent +Some tools also support extending the project path from the command line, +generally through the @option{-aP}. You can see the value of the project +path by using the @command{gnatls -v} command. + +Any symbolic link will be fully resolved in the directory of the +importing project file before the imported project file is examined. + +Any source file in the imported project can be used by the sources of the +importing project, transitively. +Thus if @code{A} imports @code{B}, which imports @code{C}, the sources of +@code{A} may depend on the 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. @command{gprbuild} has a switch @option{--no-indirect-imports} +that will report such indirect dependencies. + +One very important aspect of a project hierarchy is that +@b{a given source can only belong to one project} (otherwise the project manager +would not know which settings apply to it and when to recompile it). It means +that different project files do not usually share source directories or +when they do, they need to specify precisely which project owns which sources +using attribute @code{Source_Files} or equivalent. By contrast, 2 projects +can each own a source with the same base file name as long as they live in +different directories. The latter is not true for Ada Sources because of the +correlation betwen source files and Ada units: it is not possible to link an + +@c --------------------------------------------- +@node Cyclic Project Dependencies +@subsection Cyclic Project Dependencies +@c --------------------------------------------- + +@noindent +Cyclic dependencies are mostly forbidden: +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 @b{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} through a @code{limited with}. + +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 importing it. In particular, its packages cannot be renamed and +its variables cannot be referred to. + +@smallexample @c 0projectfile +with "b.gpr"; +with "c.gpr"; +project A is + For Exec_Dir use B'Exec_Dir; -- ok +end A; + +limited with "a.gpr"; -- Cyclic dependency: A -> B -> A +project B is + For Exec_Dir use A'Exec_Dir; -- not ok +end B; + +with "d.gpr"; +project C is +end C; + +limited with "a.gpr"; -- Cyclic dependency: A -> C -> D -> A +project D is + For Exec_Dir use A'Exec_Dir; -- not ok +end D; +@end smallexample + +@c --------------------------------------------- +@node Sharing Between Projects +@subsection Sharing Between Projects +@c --------------------------------------------- + +@noindent +When building an application, it is common to have similar needs in the projects +corresponding to the subsystems under construction. For instance, they will all +have the same compilation switches. +such as @code{Build} and @code{Logging}, while not wanting to affect +external subsystems, such as @code{GtkAda} in our example. + +As seen before (@pxref{Tools Options in Project Files}), setting compilation +switches for all sources of a subsystem is simple: it is just a matter of adding +a @code{Compiler.Default_Switches} attribute to each project files with the same +value. Of course, that means duplication of data, and both places need to be changed +in order to recompile the whole application with different switches. It can become +a real problem if there are many subsystems and thus many project files to edit. + +There are two main approaches to avoiding this duplication: + +@itemize @bullet +@item Since @file{build.gpr} imports @file{logging.gpr}, we could change it + to reference the attribute in Logging, either through a package renaming, + or by referencing the attribute. The following example shows both cases: + + @smallexample @c projectfile + project Logging is + package Compiler is + for Switches ("Ada") use ("-O2"); + end Compiler; + package Binder is + for Switches ("Ada") use ("-E"); + end Binder; + end Logging; + + with "logging.gpr"; + project Build is + package Compiler renames Logging.Compiler; + package Binder is + for Switches ("Ada") use Logging.Binder'Switches ("Ada"); + end Binder; + end Build; + @end smallexample + + @noindent + The solution used for @code{Compiler} gets the same value for all + attributes of the package, but you cannot modify anything from the + package (adding extra switches or some exceptions). The second + version is more flexible, but more verbose. + + If you need to refer to the value of a variable in an imported + project, rather than an attribute, the syntax is similar but uses + a "." rather than an apostrophe. For instance: + + @smallexample @c projectfile + with "imported"; + project Main is + Var1 := Imported.Var; + end Main; + @end smallexample + +@item The second approach is to define the switches in a third project. + That project is setup without any sources (so that, as opposed to + the first example, none of the project plays a special role), and + will only be used to define the attributes. Such a project is + typically called @file{shared.gpr}. + + @smallexample @c projectfile + abstract project Shared is + for Source_Files use (); -- no project + package Compiler is + for Switches ("Ada") use ("-O2"); + end Compiler; + end Shared; + + with "shared.gpr"; + project Logging is + package Compiler renames Shared.Compiler; + end Logging; + + with "shared.gpr"; + project Build is + package Compiler renames Shared.Compiler; + end Build; + @end smallexample + + @noindent + As for the first example, we could have chosen to set the attributes + one by one rather than rename a package. The reason we explicitly + indicate that @code{Shared} has no sources is so that it can be created + in any directory and we are sure it shares no sources with @code{Build} + or @code{Logging}, which of course would be invalid. + + @CINDEX{project qualifier} + Note the additional use of the @b{abstract} qualifier in @file{shared.gpr}. + This qualifier is optional, but helps convey the message that we do not + intend this project to have sources (@pxref{Qualified Projects} for + more qualifiers). +@end itemize + + +@c --------------------------------------------- +@node Global Attributes +@subsection Global Attributes +@c --------------------------------------------- + +@noindent +We have already seen many examples of attributes used to specify a special +option of one of the tools involved in the build process. Most of those +attributes are project specific. That it to say, they only affect the invocation +of tools on the sources of the project where they are defined. + +There are a few additional attributes that apply to all projects in a +hierarchy as long as they are defined on the "main" project. +The main project is the project explicitly mentioned on the command-line. +The project hierarchy is the "with"-closure of the main project. + +Here is a list of commonly used global attributes: + +@table @asis +@item @b{Builder.Global_Configuration_Pragmas}: + @CINDEX{@code{Global_Configuration_Pragmas}} + This attribute points to a file that contains configuration pragmas + to use when building executables. These pragmas apply for all + executables build from this project hierarchy. As we have seen before, + additional pragmas can be specified on a per-project basis by setting the + @code{Compiler.Local_Configuration_Pragmas} attribute. + +@item @b{Builder.Global_Compilation_Switches}: + @CINDEX{@code{Global_Compilation_Switches}} + This attribute is a list of compiler switches to use when compiling any + source file in the project hierarchy. These switches are used in addition + to the ones defined in the @code{Compiler} package, which only apply to + the sources of the corresponding project. This attribute is indexed on + the name of the language. + +@end table + +Using such global capabilities is convenient. It can also lead to unexpected +behavior. Especially when several subsystems are shared among different main +projects and the different global attributes are not +compatible. Note that using aggregate projects can be a safer and more powerful +replacement to global attributes. + +@c --------------------------------------------- +@node Scenarios in Projects +@section Scenarios in Projects +@c --------------------------------------------- + +@noindent +Various aspects of the projects can be modified based on @b{scenarios}. These +are user-defined modes that change the behavior of a project. Typical +examples are the setup of platform-specific compiler options, or the use of +a debug and a release mode (the former would activate the generation of debug +information, when the second will focus on improving code optimization). + +Let's enhance our example to support a debug and a release modes.The issue is to +let the user choose what kind of system he is building: +use @option{-g} as compiler switches in debug mode and @option{-O2} +in release mode. We will also setup the projects so that we do not share the +same object directory in both modes, otherwise switching from one to the other +might trigger more recompilations than needed or mix objects from the 2 modes. + +One naive approach is to create two different project files, say +@file{build_debug.gpr} and @file{build_release.gpr}, that set the appropriate +attributes as explained in previous sections. This solution does not scale well, +because in presence of multiple projects depending on each other, +you will also have to duplicate the complete hierarchy and adapt the project +files to point to the right copies. + +@CINDEX{scenarios} +Instead, project files support the notion of scenarios controlled +by external values. Such values can come from several sources (in decreasing +order of priority): + +@table @asis +@item @b{Command line}: + @CINDEX{@option{-X}} + When launching @command{gnatmake} or @command{gprbuild}, the user can pass + extra @option{-X} switches to define the external value. In + our case, the command line might look like + + @smallexample + gnatmake -Pbuild.gpr -Xmode=debug + or gnatmake -Pbuild.gpr -Xmode=release + @end smallexample + +@item @b{^Environment variables^Logical names^}: + When the external value does not come from the command line, it can come from + the value of ^environment variables^logical names^ of the appropriate name. + In our case, if ^an environment variable^a logical name^ called "mode" + exist, its value will be taken into account. + +@item @b{External function second parameter} + +@end table + +@CINDEX{@code{external}} +We now need to get that value in the project. The general form is to use +the predefined function @b{external} which returns the current value of +the external. For instance, we could setup the object directory to point to +either @file{obj/debug} or @file{obj/release} by changing our project to + +@smallexample @c projectfile + project Build is + for Object_Dir use "obj/" & external ("mode", "debug"); + ... -- as before + end Build; +@end smallexample + +@noindent +The second parameter to @code{external} is optional, and is the default +value to use if "mode" is not set from the command line or the environment. + +In order to set the switches according to the different scenarios, other +constructs have to be introduced such as typed variables and case statements. + +@CINDEX{typed variable} +@CINDEX{case statement} +A @b{typed variable} is a variable that +can take only a limited number of values, similar to an enumeration in Ada. +Such a variable can then be used in a @b{case statement} and create conditional +sections in the project. The following example shows how this can be done: + +@smallexample @c projectfile + project Build is + type Mode_Type is ("debug", "release"); -- all possible values + Mode : Mode_Type := external ("mode", "debug"); -- a typed variable + + package Compiler is + case Mode is + when "debug" => + for Switches ("Ada") use ("-g"); + when "release" => + for Switches ("Ada") use ("-O2"); + end case; + end Compiler; + end Build; +@end smallexample + +@noindent +The project has suddenly grown in size, but has become much more flexible. +@code{Mode_Type} defines the only valid values for the @code{mode} variable. If +any other value is read from the environment, an error is reported and the +project is considered as invalid. + +The @code{Mode} variable is initialized with an external value +defaulting to @code{"debug"}. This default could be omitted and that would +force the user to define the value. Finally, we can use a case statement to set the +switches depending on the scenario the user has chosen. + +Most aspects of the projects can depend on scenarios. The notable exception +are project dependencies (@code{with} clauses), which may not depend on a scenario. + +Scenarios work the same way with @b{project hierarchies}: you can either +duplicate a variable similar to @code{Mode} in each of the project (as long +as the first argument to @code{external} is always the same and the type is +the same), or simply set the variable in the @file{shared.gpr} project +(@pxref{Sharing Between Projects}). + +@c --------------------------------------------- +@node Library Projects +@section Library Projects +@c --------------------------------------------- + +@noindent +So far, we have seen examples of projects that create executables. However, +it is also possible to create libraries instead. A @b{library} is a specific +type of subsystem where, for convenience, objects are grouped together +using system-specific means such as archives or windows DLLs. + +Library projects provide a system- and language-independent way of building both @b{static} +and @b{dynamic} libraries. They also support the concept of @b{standalone +libraries} (SAL) which offers two significant properties: the elaboration +(e.g. initialization) of the library is either automatic or very simple; +a change in the +implementation part of the library implies minimal post-compilation actions on +the complete system and potentially no action at all for the rest of the +system in the case of dynamic SALs. + +The GNAT Project Manager takes complete care of the library build, rebuild and +installation tasks, including recompilation of the source files for which +objects do not exist or are not up to date, assembly of the library archive, and +installation of the library (i.e., copying associated source, object and +@file{ALI} files to the specified location). + +@menu +* Building Libraries:: +* Using Library Projects:: +* Stand-alone Library Projects:: +* Installing a library with project files:: +@end menu + +@c --------------------------------------------- +@node Building Libraries +@subsection Building Libraries +@c --------------------------------------------- + +@noindent +Let's enhance our example and transform the @code{logging} subsystem into a +library.In orer to do so, a few changes need to be made to @file{logging.gpr}. +A number of specific attributes needs to be defined: at least @code{Library_Name} +and @code{Library_Dir}; in addition, a number of other attributes can be used +to specify specific aspects of the library. For readablility, it is also +recommended (although not mandatory), to use the qualifier @code{library} in +front of the @code{project} keyword. + +@table @asis +@item @b{Library_Name}: + @CINDEX{@code{Library_Name}} + This attribute is the name of the library to be built. There is no + restriction on the name of a library imposed by the project manager; + however, there may be system specific restrictions on the name. + In general, it is recommended to stick to alphanumeric characters + (and possibly underscores) to help portability. + +@item @b{Library_Dir}: + @CINDEX{@code{Library_Dir}} + This attribute is the path (absolute or relative) of the directory where + the library is to be installed. In the process of building a library, + the sources are compiled, the object files end up in the explicit or + implicit @code{Object_Dir} directory. When all sources of a library + are compiled, some of the compilation artifacts, including the library itself, + are copied to the library_dir directory. This directory must exists and be + writable. It must also be different from the object directory so that cleanup + activities in the Library_Dir do not affect recompilation needs. + +@end table + +Here is the new version of @file{logging.gpr} that makes it a library: + +@smallexample @c projectfile +library project Logging is -- "library" is optional + for Library_Name use "logging"; -- will create "liblogging.a" on Unix + for Object_Dir use "obj"; + for Library_Dir use "lib"; -- different from object_dir +end Logging; +@end smallexample + +@noindent +Once the above two attributes are defined, the library project is valid and +is enough for building a library with default characteristics. +Other library-related attributes can be used to change the defaults: + +@table @asis +@item @b{Library_Kind}: + @CINDEX{@code{Library_Kind}} + The value of this attribute must be either @code{"static"}, @code{"dynamic"} or + @code{"relocatable"} (the latter is a synonym for dynamic). It indicates + which kind of library should be build (the default is to build a + static library, that is an archive of object files that can potentially + be linked into a static executable). When the library is set to be dynamic, + a separate image is created that will be loaded independnently, usually + at the start of the main program execution. Support for dynamic libraries is + very platform specific, for instance on Windows it takes the form of a DLL + while on GNU/Linux, it is a dynamic elf image whose suffix is usually + @file{.so}. Library project files, on the other hand, can be written in + a platform independant way so that the same project file can be used to build + a library on different Oses. + + If you need to build both a static and a dynamic library, it is recommended + use two different object directories, since in some cases some extra code + needs to be generated for the latter. For such cases, one can + either define two different project files, or a single one which uses scenarios + to indicate at the various kinds of library to be build and their + corresponding object_dir. + +@item @b{Library_ALI_Dir}: + @CINDEX{@code{Library_ALI_Dir}} + This attribute may be specified to indicate the directory where the ALI + files of the library are installed. By default, they are copied into the + @code{Library_Dir} directory, but as for the executables where we have a + separate @code{Exec_Dir} attribute, you might want to put them in a separate + directory since there can be hundreds of them. The same restrictions as for + the @code{Library_Dir} attribute apply. + +@item @b{Library_Version}: + @CINDEX{@code{Library_Version}} + This attribute is platform dependent, and has no effect on VMS and Windows. + On Unix, it is used only for dynamic 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}. This follows the usual installation schemes + for dynamic libraries on many Unix systems. + + @smallexample @c projectfile + @group + project Logging is + Version := "1"; + for Library_Dir use "lib"; + for Library_Name use "logging"; + for Library_Kind use "dynamic"; + for Library_Version use "liblogging.so." & Version; + end Loggin; + @end group + @end smallexample + + @noindent + After the compilation, the directory @file{lib} will contain both a + @file{libdummy.so.1} library and a symbolic link to it called + @file{libdummy.so}. + +@item @b{Library_GCC}: + @CINDEX{@code{Library_GCC}} + This attribute is the name of the tool to use instead of "gcc" to link shared + libraries. A common use of this attribute is to define a wrapper script that + accomplishes specific actions before calling gcc (which itself is calling the + linker to build the library image). + +@item @b{Linker.Linker_Options}: + @CINDEX{@code{Linker_Options}} + This attribute specifies additional switches to be given to the linker when + linking an executable. It is ignored when defined in the main project and + taken into account in all other projects that are imported directly or + indirectly. These switches complement the @code{Linker.Switches} + defined in the main project. This is useful when a particular subsystem + depends on an external library: adding this dependency as a + @code{Linker_Options} in the project of the subsystem is more convenient than + adding it to all the @code{Linker.Switches} of the main projects that depend + upon this subsystem. +@end table + + +@c --------------------------------------------- +@node Using Library Projects +@subsection Using Library Projects +@c --------------------------------------------- + +@noindent +When the builder detects that a project file is a library project file, it +recompiles all sources of the project that need recompilation and rebuild the +library if any of the sources have been recompiled. It then groups all object +files into a single file, which is a shared or a static library. This library +can later on be linked with multiple executables. Note that the use +of shard libraries reduces the size of the final executable and can also reduce +the memory footprint at execution time when the library is shared among several +executables. + +It is also possible to build @b{multi-language libraries}. When using +@command{gprbuild} as a builder, multi-language library projects allow naturally +the creation of multi-language libraries . @command{gnatmake}, does n ot try to +compile non Ada sources. However, when the project is multi-language, it 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 does not +apply to Ada-only projects which only take into account the objects +corresponding to the sources of the project. + +A non-library project can import a library project. When the builder is invoked +on the former, the library of the latter is only rebuilt when absolutely +necessary. For instance, if a unit of the +library is not up-to-date but non of the executables need this unit, then the +unit is not recompiled and the library is not reassembled. +For instance, let's assume in our example that logging has the following +sources: @file{log1.ads}, @file{log1.adb}, @file{log2.ads} and +@file{log2.adb}. If @file{log1.adb} has been modified, then the library +@file{liblogging} will be rebuilt when compiling all the sources of +@code{Build} only if @file{proc.ads}, @file{pack.ads} or @file{pack.adb} +include a @code{"with Log1"}. + +To ensure that all the sources in the @code{Logging} library are +up to date, and that all the sources of @code{Build} are also up to date, +the following two commands needs to be used: + +@smallexample +gnatmake -Plogging.gpr +gnatmake -Pbuild.gpr +@end smallexample + +@noindent +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 +Library projects can also be useful to describe a library that need to be used +but, for some reason, cannot be rebuilt. For instance, it is the case when some +of the library sources are not available. Such library projects need simply to +use the @code{Externally_Built} attribute as in the example below: + +@smallexample @c projectfile +library project Extern_Lib is + for Languages use ("Ada", "C"); + for Source_Dirs use ("lib_src"); + for Library_Dir use "lib2"; + for Library_Kind use "dynamic"; + for Library_Name use "l2"; + for Externally_Built use "true"; -- <<<< +end Extern_Lib; +@end smallexample + +@noindent +In the case of externally built libraries, the @code{Object_Dir} +attribute does not need to be specified because it will never be +used. + +The main effect of using such an externally built library project is mostly to +affect the linker command in order to reference the desired library. It can +also be achieved by using @code{Linker.Linker_Options} or @code{Linker.Switches} +in the project corresponding to the subsystem needing this external library. +This latter method is more straightforward in simple cases but when several +subsystems depend upon the same external library, finding the proper place +for the @code{Linker.Linker_Options} might not be easy and if it is +not placed properly, the final link command is likely to present ordering issues. +In such a situation, it is better to use the externally built library project +so that all other subsystems depending on it can declare this dependency thanks +to a project @code{with} clause, which in turn will trigger the builder to find +the proper order of libraries in the final link command. +@end ifclear + +@c --------------------------------------------- +@node Stand-alone Library Projects +@subsection Stand-alone Library Projects +@c --------------------------------------------- + +@noindent +@CINDEX{standalone libraries} +A @b{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 a convenient way to add an Ada subsystem to a more global system +whose main is not in Ada since it makes the elaboration of the Ada part mostly +transparent. However, stand-alone libraries are also useful when the main is in +Ada: they provide a means for minimizing relinking & redeployement of complex +systems when localized changes are made. + +The most proeminent characteristic of a stand-alone library is that it offers a +distinction between interface units and implementation units. Only the former +are visible to units outside the library. A stand-alone library project is thus +characterised by a third attribute, @b{Library_Interface}, in addition to the +two attributes that make a project a Library Project (@code{Library_Name} and +@code{Library_Dir}). + +@table @asis +@item @b{Library_Interface}: + @CINDEX{@code{Library_Interface}} + This attribute defines an explicit subset of the units of the project. + Projects importing this library project may only "with" units whose sources + are listed in the @code{Library_Interface}. Other sources are considered + implementation units. + + @smallexample @c projectfile + @group + for Library_Dir use "lib"; + for Library_Name use "loggin"; + for Library_Interface use ("lib1", "lib2"); -- unit names + @end group + @end smallexample + +@end table + +In order to include the elaboration code in the stand-alone library, the binder +is invoked on the closure of the library units creating a package whose name +depends on the library name (^b~logging.ads/b^B$LOGGING.ADS/B^ in the example). +This binder-generated package includes @b{initialization} and @b{finalization} +procedures whose names depend on the library name (@code{logginginit} and +@code{loggingfinal} in the example). The object corresponding to this package is +included in the library. + +@table @asis +@item @b{Library_Auto_Init}: + @CINDEX{@code{Library_Auto_Init}} + A dynamic stand-alone Library is automatically initialized + if automatic initialization of Stand-alone Libraries is supported on the + platform and if attribute @b{Library_Auto_Init} is not specified or + is specified with the value "true". A static Stand-alone Library is never + automatically initialized. Specifying "false" for this attribute + prevent automatic initialization. + + 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. + +@item @b{Library_Dir}: + @CINDEX{@code{Library_Dir}} + 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. + +@item @b{Binder.Default_Switches}: + When a stand-alone library is bound, the switches that are specified in + the attribute @b{Binder.Default_Switches ("Ada")} are + used in the call to @command{gnatbind}. + +@item @b{Library_Options}: + @CINDEX{@code{Library_Options}} + This attribute may be used to specified additional switches to @command{gcc} + when linking the library. + +@item @b{Library_Src_Dir}: + @CINDEX{@code{Library_Src_Dir}} + This attribute defines the location (absolute or relative to the project + directory) where the sources of the interface units are copied at + installation time. + These sources includes the specs of the interface units along with the closure + of sources necessary to compile them successfully. That may include bodies and + subunits, when pragmas @code{Inline} are used, or when there is a generic + units in the spec. This directory cannot point to the object directory or + one of the source directories, but it can point to the library directory, + which is the default value for this attribute. + +@item @b{Library_Symbol_Policy}: + @CINDEX{@code{Library_Symbol_Policy}} + This attribute controls the export of symbols and, on some platforms (like + VMS) that have the notions of major and minor IDs built in the library + files, it controls the setting of these IDs. It is not supported on all + platforms (where it will just have no effect). It may have one of the + following values: + + @itemize - + @item @code{"autonomous"} or @code{"default"}: exported symbols are not controlled + @item @code{"compliant"}: if attribute @b{Library_Reference_Symbol_File} + is not defined, then it is equivalent to policy "autonomous". If there + are exported symbols in the reference symbol file that are not in the + object files of the interfaces, the major ID of the library is increased. + If there are symbols in the object files of the interfaces that are not + in the reference symbol file, these symbols are put at the end of the list + in the newly created symbol file and the minor ID is increased. + @item @code{"controlled"}: the attribute @b{Library_Reference_Symbol_File} must be + defined. The library will fail to build if the exported symbols in the + object files of the interfaces do not match exactly the symbol in the + symbol file. + @item @code{"restricted"}: The attribute @b{Library_Symbol_File} must be defined. + The library will fail to build if there are symbols in the symbol file that + are not in the exported symbols of the object files of the interfaces. + Additional symbols in the object files are not added to the symbol file. + @item @code{"direct"}: The attribute @b{Library_Symbol_File} must be defined and + must designate an existing file in the object directory. This symbol file + is passed directly to the underlying linker without any symbol processing. + + @end itemize + +@item @b{Library_Reference_Symbol_File} + @CINDEX{@code{Library_Reference_Symbol_File}} + This attribute may define the path name of a reference symbol file that is + read when the symbol policy is either "compliant" or "controlled", on + platforms that support symbol control, such as VMS, when building a + stand-alone library. The path may be an absolute path or a path relative + to the project directory. + +@item @b{Library_Symbol_File} + @CINDEX{@code{Library_Symbol_File}} + This attribute may define the name of the symbol file to be created when + building a stand-alone library when the symbol policy is either "compliant", + "controlled" or "restricted", on platforms that support symbol control, + such as VMS. When symbol policy is "direct", then a file with this name + must exist in the object directory. +@end table + + +@c --------------------------------------------- +@node Installing a library with project files +@subsection Installing a library with project files +@c --------------------------------------------- + +@noindent +When using 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. @ref{Using Library Projects} + +@c --------------------------------------------- +@node Project Extension +@section Project Extension +@c --------------------------------------------- + +@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 @b{project extension} facility. + +Suppose for instance that our example @code{Build} project is build every night +for the whole team, in some shared directory. A developer usually need to work +on a small part of the system, and might not want to have a copy of all the +sources and all the object files (mostly because that would require too much +disk space, time to recompile everything). He prefers to be able to override +some of the source files in his directory, while taking advantage of all the +object files generated at night. + +Another example can be taken from large software systems, where 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 or remove unnecessary ones. +This facility is the project analog of a type extension in +object-oriented programming. Project hierarchies are permitted (an extending +project may itself be extended), and a project that +extends a project can also import other projects. + +A third example is that of using project extensions to provide different +versions of the same system. For instance, assume that a @code{Common} +project is used by two development branches. One of the branches has now +been frozen, and no further change can be done to it or to @code{Common}. +However, the other development branch still needs evolution of @code{Common}. +Project extensions provide a flexible solution to create a new version +of a subsystem while sharing and reusing as much as possible from the original +one. + +A project extension inherits implicitly all the sources and objects from the +project it extends. It is possible to create a new version of some of the +sources in one of the additional source dirs of the extending project. Those new +versions hide the original versions. Adding new sources or removing existing +ones is also possible. Here is an example on how to extend the project +@code{Build} from previous examples: + +@smallexample @c projectfile + project Work extends "../bld/build.gpr" is + end Work; +@end smallexample + +@noindent +The project after @b{extends} is the one being extended. As usual, it can be +specified using an absolute path, or a path relative to any of the directories +in the project path (@pxref{Project Dependencies}). This project does not +specify source or object directories, so the default value for these attribute +will be used that is to say the current directory (where project @code{Work} is +placed). We can already compile that project with + +@smallexample + gnatmake -Pwork +@end smallexample + +@noindent +If no sources have been placed in the current directory, this command +won't do anything, since this project does not change the +sources it inherited from @code{Build}, therefore all the object files +in @code{Build} and its dependencies are still valid and are reused +automatically. + +Suppose we now want to supply an alternate version of @file{pack.adb} +but use the existing versions of @file{pack.ads} and @file{proc.adb}. +We can create the new file Work's current directory (likely +by copying the one from the @code{Build} project and making changes to +it. If new packages are needed at the same time, we simply create +new files in the source directory of the extending project. + +When we recompile, @command{gnatmake} will now automatically recompile +this file (thus creating @file{pack.o} in the current directory) and +any file that depends on it (thus creating @file{proc.o}). Finally, the +executable is also linked locally. + +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}, and @code{Work} would +import @code{base} and add @file{pack.adb}. In this scenario, @code{base} +cannot contain the original version of @file{pack.adb} otherwise there would be +2 versions of the same unit in the closure of the project and this is not +allowed. Generally speaking, it is not recommended to put the spec and the +body of a unit in different projects since this affects their autonomy and +reusability. + +In a project file that extends another project, it is possible to +indicate that an inherited source is @b{not part} of the sources of the +extending project. This is necessary sometimes when a package spec has +been overridden 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. + +@CINDEX{@code{Excluded_Source_Files}} +@CINDEX{@code{Excluded_Source_List_File}} +For that purpose, the attribute @b{Excluded_Source_Files} is used. +Its value is a list of file names. +It is also possible to use attribute @code{Excluded_Source_List_File}. +Its value is the path of a text file containing one file name per +line. + +@smallexample @c @projectfile +project Work extends "../bld/build.gpr" is + for Source_Files use ("pack.ads"); + -- New spec of Pkg does not need a completion + for Excluded_Source_Files use ("pack.adb"); +end Work; +@end smallexample + +@noindent +An extending project retains all the switches specified in the +extended project. + +@menu +* Project Hierarchy Extension:: +@end menu + +@c --------------------------------------------- +@node Project Hierarchy Extension +@subsection Project Hierarchy Extension +@c --------------------------------------------- + +@noindent +One of the fundamental restrictions in project extension is the following: +@b{A project is not allowed to import directly or indirectly at the same time an +extending project and one of its ancestors}. + +By means of example, consider the following hierarchy of projects. + +@smallexample + a.gpr contains package A1 + b.gpr, imports a.gpr and contains B1, which depends on A1 + c.gpr, imports b.gpr and contains C1, which depends on B1 +@end smallexample + +@noindent +If we want to locally extend the packages @code{A1} and @code{C1}, we need to +create several extending projects: + +@smallexample + a_ext.gpr which extends a.gpr, and overrides A1 + b_ext.gpr which extends b.gpr and imports a_ext.gpr + c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1 +@end smallexample + +@noindent +@smallexample @c projectfile + project A_Ext extends "a.gpr" is + for Source_Files use ("a1.adb", "a1.ads"); + end A_Ext; + + with "a_ext.gpr"; + project B_Ext extends "b.gpr" is + end B_Ext; + + with "b_ext.gpr"; + project C_Ext extends "c.gpr" is + for Source_Files use ("c1.adb"); + end C_Ext; +@end smallexample + +@noindent +The extension @file{b_ext.gpr} is required, even though we are not overriding +any of the sources of @file{b.gpr} because otherwise @file{c_expr.gpr} would +import @file{b.gpr} which itself knows nothing about @file{a_ext.gpr}. + +@CINDEX{extends all} +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 a low layer. In such cases, it is possible to create +an @b{implicit extension} of entire hierarchy using @b{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 implicit projects +that extend every project in the hierarchy; all these implicit projects do not +control sources on their own and use the object directory of +the "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 implicit extending projects +that depend on them, are recompiled. + +Thus, in our example we could create the following projects instead: + +@smallexample + a_ext.gpr, extends a.gpr and overrides A1 + c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1 + +@end smallexample + +@noindent +@smallexample @c projectfile + project A_Ext extends "a.gpr" is + for Source_Files use ("a1.adb", "a1.ads"); + end A_Ext; + + with "a_ext.gpr"; + project C_Ext extends all "c.gpr" is + for Source_Files use ("c1.adb"); + end C_Ext; +@end smallexample + +@noindent +When building project @file{c_ext.gpr}, the entire modified project space is +considered for recompilation, including the sources of @file{b.gpr} that are +impacted by the changes in @code{A1} and @code{C1}. + +@c --------------------------------------------- +@node Project File Reference +@section Project File Reference +@c --------------------------------------------- + +@noindent +This section describes the syntactic structure of project files, the various +constructs that can be used. Finally, it ends with a summary of all available +attributes. + +@menu +* Project Declaration:: +* Qualified Projects:: +* Declarations:: +* Packages:: +* Expressions:: +* External Values:: +* Typed String Declaration:: +* Variables:: +* Attributes:: +* Case Statements:: +@end menu + +@c --------------------------------------------- +@node Project Declaration +@subsection Project Declaration +@c --------------------------------------------- + +@noindent +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. + +@b{Identifiers} (ie the user-defined names such as project or variable names) +have the same syntax as Ada identifiers: they must start with a letter, +and be followed by zero or more letters, digits or underscore characters; +it is also illegal to have two underscores next to each other. Identifiers +are always case-insensitive ("Name" is the same as "name"). + +@smallexample +simple_name ::= identifier +name ::= simple_name @{ . simple_name @} +@end smallexample + +@noindent +@b{Strings} are used for values of attributes or as indexes for these +attributes. They are in general case sensitive, except when noted +otherwise (in particular, strings representing file names will be case +insensitive on some systems, so that "file.adb" and "File.adb" both +represent the same file). + +@b{Reserved words} are the same as for standard Ada 95, and cannot +be used for identifiers. In particular, the following words are currently +used in project files, but others could be added later on. In bold are the +extra reserved words in project files: @code{all, at, case, end, for, is, +limited, null, others, package, renames, type, use, when, with, @b{extends}, +@b{external}, @b{project}}. + +@b{Comments} in project files have the same syntax as in Ada, two consecutive +hyphens through the end of the line. + +A project may be an @b{independent project}, entirely defined by a single +project file. Any source file in an independent project depends only +on the predefined library and other source files in the same project. +But a project may also depend on other projects, either by importing them +through @b{with clauses}, or by @b{extending} at most one other project. Both +types of dependency can be used in the same project. + +A path name denotes a project file. It can be absolute or relative. +An absolute path name includes a sequence of directories, in the syntax of +the host operating system, that identifies uniquely the project file in the +file system. A relative path name identifies the project file, relative +to the directory that contains the current project, or relative to a +directory listed in the environment variables ADA_PROJECT_PATH and +GPR_PROJECT_PATH. Path names are case sensitive if file names in the host +operating system are case sensitive. As a special case, the directory +separator can always be "/" even on Windows systems, so that project files +can be made portable across architectures. +The syntax of the environment variable ADA_PROJECT_PATH and +GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and +semicolons on Windows. + +A given project name can appear only once in a context clause. + +It is illegal for a project imported by a context clause to refer, directly +or indirectly, to the project in which this context clause appears (the +dependency graph cannot contain cycles), except when one of the with clause +in the cycle is a @b{limited with}. +@c ??? Need more details here + +@smallexample @c projectfile +with "other_project.gpr"; +project My_Project extends "extended.gpr" is +end My_Project; +@end smallexample + +@noindent +These dependencies form a @b{directed graph}, potentially cyclic when using +@b{limited with}. The subprogram reflecting the @b{extends} relations is a +tree. + +A project's @b{immediate sources} are the source files directly defined by +that project, either implicitly by residing in the project source directories, +or explicitly through any of the source-related attributes. +More generally, a project sources are the immediate sources of the project +together with the immediate sources (unless overridden) of any +project on which it depends directly or indirectly. + +A @b{project hierarchy} can be created, where projects are children of +other projects. The name of such a child project must be @code{Parent.Child}, +where @code{Parent} is the name of the parent project. In particular, this +makes all @code{with} clauses of the parent project automatically visible +in the child project. + +@smallexample +project ::= context_clause project_declaration + +context_clause ::= @{with_clause@} +with_clause ::= @i{with} path_name @{ , path_name @} ; +path_name ::= string_literal + +project_declaration ::= simple_project_declaration | project_extension +simple_project_declaration ::= + @i{project} @i{}name @i{is} + @{declarative_item@} + @i{end} simple_name; +@end smallexample + +@c --------------------------------------------- +@node Qualified Projects +@subsection Qualified Projects +@c --------------------------------------------- + +@noindent +Before the reserved @code{project}, there may be one or two @b{qualifiers}, that +is identifiers or reserved words, to qualify the project. +The current list of qualifiers is: + +@table @asis +@item @b{abstract}: qualifies a project with no sources. Such a + 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 @b{standard}: a standard project is a non library project with sources. + This is the default (implicit) qualifier. +@item @b{aggregate}: for future extension +@item @b{aggregate library}: for future extension +@item @b{library}: a library project must declare both attributes + @code{Library_Name} and @code{Library_Dir}. +@item @b{configuration}: a configuration project cannot be in a project tree. + It describes compilers and other tools to @code{gprbuild}. +@end table + + +@c --------------------------------------------- +@node Declarations +@subsection Declarations +@c --------------------------------------------- + +@noindent +Declarations introduce new entities that denote types, variables, attributes, +and packages. Some declarations can only appear immediately within a project +declaration. Others can appear within a project or within a package. + +@smallexample +declarative_item ::= simple_declarative_item + | typed_string_declaration + | package_declaration + +simple_declarative_item ::= variable_declaration + | typed_variable_declaration + | attribute_declaration + | case_construction + | empty_declaration + +empty_declaration ::= @i{null} ; +@end smallexample + +@noindent +An empty declaration is allowed anywhere a declaration is allowed. It has +no effect. + +@c --------------------------------------------- +@node Packages +@subsection Packages +@c --------------------------------------------- + +@noindent +A project file may contain @b{packages}, that group attributes (typically +all the attributes that are used by one of the GNAT tools). + +A package with a given name may only appear once in a project file. +The following packages are currently supported in project files +(See @pxref{Attributes} for the list of attributes that each can contain). + +@table @code +@item Binder + This package specifies characteristics useful when invoking the binder either + directly via the @command{gnat} driver or when using a builder such as + @command{gnatmake} or @command{gprbuild}. @xref{Main Subprograms}. +@item Builder + This package specifies the compilation options used when building an + executable or a library for a project. Most of the options should be + set in one of @code{Compiler}, @code{Binder} or @code{Linker} packages, + but there are some general options that should be defined in this + package. @xref{Main Subprograms}, and @pxref{Executable File Names} in + particular. +@item Check + This package specifies the options used when calling the checking tool + @command{gnatcheck} via the @command{gnat} driver. Its attribute + @b{Default_Switches} has the same semantics as for the package + @code{Builder}. The first string should always be @code{-rules} to specify + that all the other options belong to the @code{-rules} section of the + parameters to @command{gnatcheck}. +@item Compiler + This package specifies the compilation options used by the compiler for + each languages. @xref{Tools Options in Project Files}. +@item Cross_Reference + This package specifies the options used when calling the library tool + @command{gnatxref} via the @command{gnat} driver. Its attributes + @b{Default_Switches} and @b{Switches} have the same semantics as for the + package @code{Builder}. +@item Eliminate + This package specifies the options used when calling the tool + @command{gnatelim} via the @command{gnat} driver. Its attributes + @b{Default_Switches} and @b{Switches} have the same semantics as for the + package @code{Builder}. +@item Finder + This package specifies the options used when calling the search tool + @command{gnatfind} via the @command{gnat} driver. Its attributes + @b{Default_Switches} and @b{Switches} have the same semantics as for the + package @code{Builder}. +@item Gnatls + This package the options to use when invoking @command{gnatls} via the + @command{gnat} driver. +@item Gnatstub + This package specifies the options used when calling the tool + @command{gnatstub} via the @command{gnat} driver. Its attributes + @b{Default_Switches} and @b{Switches} have the same semantics as for the + package @code{Builder}. +@item IDE + This package specifies the options used when starting an integrated + development environment, for instance @command{GPS} or @command{Gnatbench}. + @xref{The Development Environments}. +@item Linker + This package specifies the options used by the linker. + @xref{Main Subprograms}. +@item Metrics + This package specifies the options used when calling the tool + @command{gnatmetric} via the @command{gnat} driver. Its attributes + @b{Default_Switches} and @b{Switches} have the same semantics as for the + package @code{Builder}. +@item Naming + This package specifies the naming conventions that apply + to the source files in a project. In particular, these conventions are + used to automatically find all source files in the source directories, + or given a file name to find out its language for proper processing. + @xref{Naming Schemes}. +@item Pretty_Printer + This package specifies the options used when calling the formatting tool + @command{gnatpp} via the @command{gnat} driver. Its attributes + @b{Default_Switches} and @b{Switches} have the same semantics as for the + package @code{Builder}. +@item Stack + This package specifies the options used when calling the tool + @command{gnatstack} via the @command{gnat} driver. Its attributes + @b{Default_Switches} and @b{Switches} have the same semantics as for the + package @code{Builder}. +@item Synchronize + This package specifies the options used when calling the tool + @command{gnatsync} via the @command{gnat} driver. + +@end table + +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 @b{attribute declarations}, +@b{variable declarations} and @b{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}. + +A package can also be defined by a @b{renaming declaration}. The new package +renames a package declared in a different project file, and has the same +attributes as the package it renames. The name of the renamed package +must be the same as the name of the renaming package. The project must +contain a package declaration with this name, and the project +must appear in the context clause of the current project, or be its parent +project. It is not possible to add or override attributes to the renaming +project. If you need to do so, you should declare a standard package, and +assign the value of the attributes one by one (@code{for Switches ("Ada") +use Other_Project.Compiler'Switches ("Ada")}). + +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. This is a very common way to share settings +between projects. + +@smallexample +package_declaration ::= package_spec | package_renaming +package_spec ::= + @i{package} @i{}simple_name @i{is} + @{simple_declarative_item@} + @i{end} package_identifier ; +package_renaming ::== + @i{package} @i{}simple_name @i{renames} @i{}simple_name.package_identifier ; +@end smallexample + +@c --------------------------------------------- +@node Expressions +@subsection Expressions +@c --------------------------------------------- + +@noindent +An expression is any value that can be assigned to an attribute or a +variable. It is either a litteral value, or a construct requiring runtime +computation by the project manager. In a project file, the computed value of +an expression is either a string or a list of strings. + +A string value is one of: +@itemize @bullet +@item A literal string, for instance @code{"comm/my_proj.gpr"} +@item The name of a variable that evaluates to a string (@pxref{Variables}) +@item The name of an attribute that evaluates to a string (@pxref{Attributes}) +@item An external reference (@pxref{External Values}) +@item A concatenation of the above, as in @code{"prefix_" & Var}. + +@end itemize + +@noindent +A list of strings is one of the following: + +@itemize @bullet +@item A parenthesized comma-separated list of zero or more string expressions, for + instance @code{(File_Name, "gnat.adc", File_Name & ".orig")} or @code{()}. +@item The name of a variable that evaluates to a list of strings +@item The name of an attribute that evaluates to a list of strings +@item A concatenation of a list of strings and a string (as defined above), for + instance @code{("A", "B") & "C"} +@item A concatenation of two lists of strings + +@end itemize + +@noindent +The following is the grammar for expressions + +@smallexample +string_literal ::= "@{string_element@}" -- Same as Ada +string_expression ::= string_literal + | @i{variable_}name + | external_value + | attribute_reference + | ( string_expression @{ & string_expression @} ) +string_list ::= ( string_expression @{ , string_expression @} ) + | @i{string_variable}_name + | @i{string_}attribute_reference +term ::= string_expression | string_list +expression ::= term @{ & term @} -- Concatenation +@end smallexample + +@noindent +Concatenation involves strings and list of strings. As soon as a list of +strings is involved, the result of the concatenation is a list of strings. The +following Ada declarations show the existing operators: + +@smallexample @c ada + function "&" (X : String; Y : String) return String; + function "&" (X : String_List; Y : String) return String_List; + function "&" (X : String_List; Y : String_List) return String_List; +@end smallexample + +@noindent +Here are some specific examples: + +@smallexample @c projectfile +@group + List := () & File_Name; -- One string in this list + List2 := List & (File_Name & ".orig"); -- Two strings + Big_List := List & Lists2; -- Three strings + Illegal := "gnat.adc" & List2; -- Illegal, must start with list +@end group +@end smallexample + +@c --------------------------------------------- +@node External Values +@subsection External Values +@c --------------------------------------------- + +@noindent +An external value is an expression whose value is obtained from the command +that invoked the processing of the current project file (typically a +gnatmake or gprbuild command). + +@smallexample +external_value ::= @i{external} ( string_literal [, string_literal] ) +@end smallexample + +@noindent +The first string_literal is the string to be used on the command line or +in the environment to specify the external value. The second string_literal, +if present, is the default to use if there is no specification for this +external value either on the command line or in the environment. + +Typically, the external value will either exist in the +^environment variables^logical name^ +or be specified on the command line through the +@option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch. If both +are specified, then the command line value is used, so that a user can more +easily override the value. + +The function @code{external} always returns a string, possibly empty if the +value was not found in the environment and no default was specified in the +call to @code{external}. + +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. + +Most of the time, this construct is used to initialize typed variables, which +are then used in @b{case} statements to control the value assigned to +attributes in various scenarios. Thus such variables are often called +@b{scenario variables}. + +@c --------------------------------------------- +@node Typed String Declaration +@subsection Typed String Declaration +@c --------------------------------------------- + +@noindent +A @b{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. These are the only named +types in project files. A string type may only be declared at the project +level, not inside a package. + +@smallexample +typed_string_declaration ::= + @i{type} @i{}_simple_name @i{is} ( string_literal @{, string_literal@} ); +@end smallexample + +@noindent +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. +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 @b{typed variables}; all other +variables are called @b{untyped variables}. Typed variables are +particularly useful in @code{case} constructions, to support conditional +attribute declarations. (@pxref{Case Statements}). + +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. + +@c --------------------------------------------- +@node Variables +@subsection Variables +@c --------------------------------------------- + +@noindent +@b{Variables} store values (strings or list of strings) and can appear +as part of an expression. The declaration of a variable creates the +variable and assigns the value of the expression to it. The name of the +variable is available immediately after the assignment symbol, if you +need to reuse its old value to compute the new value. Before the completion +of its first declaration, the value of a variable defaults to the empty +string (""). + +A @b{typed} variable can be used as part of a @b{case} expression to +compute the value, but it can only be declared once in the project file, +so that all case statements see the same value for the variable. This +provides more consistency and makes the project easier to understand. +The syntax for its declaration is identical to the Ada syntax for an +object declaration. In effect, a typed variable acts as a constant. + +An @b{untyped} variable can be declared and overridden multiple times +within the same project. It is declared implicitly through an Ada +assignment. The first declaration establishes the kind of the variable +(string or list of strings) and successive declarations must respect +the initial kind. Assignments are executed 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. + +A variable may be declared at the project file level, or within a package. + +@smallexample +typed_variable_declaration ::= + @i{}simple_name : @i{}name := string_expression; +variable_declaration ::= @i{}simple_name := expression; +@end smallexample + +@noindent +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 + + Name := "readme.txt"; + Save_Name := Name & ".saved"; + + Empty_List := (); + List_With_One_Element := ("-gnaty"); + List_With_Two_Elements := List_With_One_Element & "-gnatg"; + Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada"); +@end group +@end smallexample + +@noindent +A @b{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 @b{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 + + +@c --------------------------------------------- +@node Attributes +@subsection Attributes +@c --------------------------------------------- + +@noindent +A project (and its packages) may have @b{attributes} that define +the project's properties. Some attributes have values that are strings; +others have values that are string lists. + +@smallexample +attribute_declaration ::= + simple_attribute_declaration | indexed_attribute_declaration +simple_attribute_declaration ::= @i{for} attribute_designator @i{use} expression ; +indexed_attribute_declaration ::= + @i{for} @i{}simple_name ( string_literal) @i{use} expression ; +attribute_designator ::= + @i{}simple_name + | @i{}simple_name ( string_literal ) +@end smallexample + +@noindent +There are two categories of attributes: @b{simple attributes} +and @b{indexed attributes}. +Each simple attribute has a default value: the empty string (for string +attributes) and the empty list (for string list attributes). +An attribute declaration defines a new value for an attribute, and overrides +the previous value. The syntax of a simple attribute declaration is similar to +that of an attribute definition clause in Ada. + +Some attributes are indexed. These attributes are mappings whose +domain is a set of strings. They are declared one association +at a time, by specifying a point in the domain and the corresponding image +of the attribute. +Like untyped variables and simple attributes, indexed attributes +may be declared several times. Each declaration supplies a new value for the +attribute, and replaces the previous setting. + +Here are some examples of attribute declarations: + +@smallexample @c projectfile + -- simple attributes + for Object_Dir use "objects"; + for Source_Dirs use ("units", "test/drivers"); + + -- indexed attributes + for Body ("main") use "Main.ada"; + for Switches ("main.ada") use ("-v", "-gnatv"); + for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g"; + + -- indexed attributes copy (from package Builder in project Default) + -- The package name must always be specified, even if it is the current + -- package. + for Default_Switches use Default.Builder'Default_Switches; +@end smallexample + +@noindent +Attributes references may be appear anywhere in expressions, and are used +to retrieve the value previously assigned to the attribute. If an attribute +has not been set in a given package or project, its value defaults to the +empty string or the empty list. + +@smallexample +attribute_reference ::= attribute_prefix ' @i{_}simple_name [ (string_literal) ] +attribute_prefix ::= @i{project} + | @i{}simple_name + | package_identifier + | @i{}simple_name . package_identifier +@end smallexample + +@noindent +Examples are: + +@smallexample @c projectfile + project'Object_Dir + Naming'Dot_Replacement + Imported_Project'Source_Dirs + Imported_Project.Naming'Casing + Builder'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 +Legal attribute names are listed below, including the package in +which they must be declared. These names are case-insensitive. The +semantics for the attributes is explained in great details in other sections. + +The column @emph{index} indicates whether the attribute is an indexed attribute, +and when it is whether its index is case sensitive (sensitive) or not (insensitive), or if case sensitivity depends is the same as file names sensitivity on the +system (file). The text is between brackets ([]) if the index is optional. + +@multitable @columnfractions .3 .1 .2 .4 +@headitem Attribute Name @tab Value @tab Package @tab Index +@headitem General attributes @tab @tab @tab @pxref{Building With Projects} +@item Name @tab string @tab - @tab (Read-only, name of project) +@item Project_Dir @tab string @tab - @tab (Read-only, directory of project) +@item Source_Files @tab list @tab - @tab - +@item Source_Dirs @tab list @tab - @tab - +@item Source_List_File @tab string @tab - @tab - +@item Locally_Removed_Files @tab list @tab - @tab - +@item Excluded_Source_Files @tab list @tab - @tab - +@item Object_Dir @tab string @tab - @tab - +@item Exec_Dir @tab string @tab - @tab - +@item Excluded_Source_Dirs @tab list @tab - @tab - +@item Excluded_Source_Files @tab list @tab - @tab - +@item Excluded_Source_List_File @tab list @tab - @tab - +@item Inherit_Source_Path @tab list @tab - @tab insensitive +@item Languages @tab list @tab - @tab - +@item Main @tab list @tab - @tab - +@item Main_Language @tab string @tab - @tab - +@item Externally_Built @tab string @tab - @tab - +@item Roots @tab list @tab - @tab file +@headitem + Library-related attributes @tab @tab @tab @pxref{Library Projects} +@item Library_Dir @tab string @tab - @tab - +@item Library_Name @tab string @tab - @tab - +@item Library_Kind @tab string @tab - @tab - +@item Library_Version @tab string @tab - @tab - +@item Library_Interface @tab string @tab - @tab - +@item Library_Auto_Init @tab string @tab - @tab - +@item Library_Options @tab list @tab - @tab - +@item Library_Src_Dir @tab string @tab - @tab - +@item Library_ALI_Dir @tab string @tab - @tab - +@item Library_GCC @tab string @tab - @tab - +@item Library_Symbol_File @tab string @tab - @tab - +@item Library_Symbol_Policy @tab string @tab - @tab - +@item Library_Reference_Symbol_File @tab string @tab - @tab - +@item Interfaces @tab list @tab - @tab - +@headitem + Naming @tab @tab @tab @pxref{Naming Schemes} +@item Spec_Suffix @tab string @tab Naming @tab insensitive (language) +@item Body_Suffix @tab string @tab Naming @tab insensitive (language) +@item Separate_Suffix @tab string @tab Naming @tab - +@item Casing @tab string @tab Naming @tab - +@item Dot_Replacement @tab string @tab Naming @tab - +@item Spec @tab string @tab Naming @tab insensitive (Ada unit) +@item Body @tab string @tab Naming @tab insensitive (Ada unit) +@item Specification_Exceptions @tab list @tab Naming @tab insensitive (language) +@item Implementation_Exceptions @tab list @tab Naming @tab insensitive (language) +@headitem + Building @tab @tab @tab @pxref{Switches and Project Files} +@item Default_Switches @tab list @tab Builder, Compiler, Binder, Linker, Cross_Reference, Finder, Pretty_Printer, gnatstub, Check, Synchronize, Eliminate, Metrics, IDE @tab insensitive (language name) +@item Switches @tab list @tab Builder, Compiler, Binder, Linker, Cross_Reference, Finder, gnatls, Pretty_Printer, gnatstub, Check, Synchronize, Eliminate, Metrics, Stack @tab [file] (file name) +@item Local_Configuration_Pragmas @tab string @tab Compiler @tab - +@item Local_Config_File @tab string @tab insensitive @tab - +@item Global_Configuration_Pragmas @tab list @tab Builder @tab - +@item Global_Compilation_Switches @tab list @tab Builder @tab language +@item Executable @tab string @tab Builder @tab [file] +@item Executable_Suffix @tab string @tab Builder @tab - +@item Global_Config_File @tab string @tab Builder @tab insensitive (language) +@headitem + IDE (used and created by GPS) @tab @tab @tab +@item Remote_Host @tab string @tab IDE @tab - +@item Program_Host @tab string @tab IDE @tab - +@item Communication_Protocol @tab string @tab IDE @tab - +@item Compiler_Command @tab string @tab IDE @tab insensitive (language) +@item Debugger_Command @tab string @tab IDE @tab - +@item Gnatlist @tab string @tab IDE @tab - +@item VCS_Kind @tab string @tab IDE @tab - +@item VCS_File_Check @tab string @tab IDE @tab - +@item VCS_Log_Check @tab string @tab IDE @tab - +@headitem + Configuration files @tab @tab @tab See gprbuild manual +@item Default_Language @tab string @tab - @tab - +@item Run_Path_Option @tab list @tab - @tab - +@item Run_Path_Origin @tab string @tab - @tab - +@item Separate_Run_Path_Options @tab string @tab - @tab - +@item Toolchain_Version @tab string @tab - @tab insensitive +@item Toolchain_Description @tab string @tab - @tab insensitive +@item Object_Generated @tab string @tab - @tab insensitive +@item Objects_Linked @tab string @tab - @tab insensitive +@item Target @tab string @tab - @tab - +@item Library_Builder @tab string @tab - @tab - +@item Library_Support @tab string @tab - @tab - +@item Archive_Builder @tab list @tab - @tab - +@item Archive_Builder_Append_Option @tab list @tab - @tab - +@item Archive_Indexer @tab list @tab - @tab - +@item Archive_Suffix @tab string @tab - @tab - +@item Library_Partial_Linker @tab list @tab - @tab - +@item Shared_Library_Prefix @tab string @tab - @tab - +@item Shared_Library_Suffix @tab string @tab - @tab - +@item Symbolic_Link_Supported @tab string @tab - @tab - +@item Library_Major_Minor_Id_Supported @tab string @tab - @tab - +@item Library_Auto_Init_Supported @tab string @tab - @tab - +@item Shared_Library_Minimum_Switches @tab list @tab - @tab - +@item Library_Version_Switches @tab list @tab - @tab - +@item Library_Install_Name_Option @tab string @tab - @tab - +@item Runtime_Library_Dir @tab string @tab - @tab insensitive +@item Runtime_Source_Dir @tab string @tab - @tab insensitive +@item Driver @tab string @tab Compiler,Binder,Linker @tab insensitive (language) +@item Required_Switches @tab list @tab Compiler,Binder,Linker @tab insensitive (language) +@item Leading_Required_Switches @tab list @tab Compiler @tab insensitive (language) +@item Trailing_Required_Switches @tab list @tab Compiler @tab insensitive (language) +@item Pic_Options @tab list @tab Compiler @tab insensitive (language) +@item Path_Syntax @tab string @tab Compiler @tab insensitive (language) +@item Object_File_Suffix @tab string @tab Compiler @tab insensitive (language) +@item Object_File_Switches @tab list @tab Compiler @tab insensitive (language) +@item Multi_Unit_Switches @tab list @tab Compiler @tab insensitive (language) +@item Multi_Unit_Object_Separator @tab string @tab Compiler @tab insensitve (language) +@item Mapping_File_Switches @tab list @tab Compiler @tab insensitive (language) +@item Mapping_Spec_Suffix @tab string @tab Compiler @tab insensitive (language) +@item Mapping_body_Suffix @tab string @tab Compiler @tab insensitive (language) +@item Config_File_Switches @tab list @tab Compiler @tab insensitive (language) +@item Config_Body_File_Name @tab string @tab Compiler @tab insensitive (language) +@item Config_Body_File_Name_Index @tab string @tab Compiler @tab insensitive (language) +@item Config_Body_File_Name_Pattern @tab string @tab Compiler @tab insensitive (language) +@item Config_Spec_File_Name @tab string @tab Compiler @tab insensitive (language) +@item Config_Spec_File_Name_Index @tab string @tab Compiler @tab insensitive (language) +@item Config_Spec_File_Name_Pattern @tab string @tab Compiler @tab insensitive (language) +@item Config_File_Unique @tab string @tab Compiler @tab insensitive (language) +@item Dependency_Switches @tab list @tab Compiler @tab insensitive (language) +@item Dependency_Driver @tab list @tab Compiler @tab insensitive (language) +@item Include_Switches @tab list @tab Compiler @tab insensitive (language) +@item Include_Path @tab string @tab Compiler @tab insensitive (language) +@item Include_Path_File @tab string @tab Compiler @tab insensitive (language) +@item Prefix @tab string @tab Binder @tab insensitive (language) +@item Objects_Path @tab string @tab Binder @tab insensitive (language) +@item Objects_Path_File @tab string @tab Binder @tab insensitive (language) +@item Linker_Options @tab list @tab Linker @tab - +@item Map_File_Options @tab string @tab Linker @tab - +@item Executable_Switches @tab list @tab Linker @tab - +@item Lib_Dir_Switch @tab string @tab Linker @tab - +@item Lib_Name_Switch @tab string @tab Linker @tab - +@item Max_Command_Line_Length @tab string @tab Linker @tab - +@item Response_File_Format @tab string @tab Linker @tab - +@item Response_File_Switches @tab list @tab Linker @tab - +@end multitable + +@c --------------------------------------------- +@node Case Statements +@subsection Case Statements +@c --------------------------------------------- + +@noindent +A @b{case} statement is used in a project file to effect conditional +behavior. Through this statement, you can set the value of attributes +and variables depending on the value previously assigned to a typed +variable. + +All choices in a choice list must be distinct. Unlike Ada, the choice +lists of all alternatives do not need to include all values of the type. +An @code{others} choice must appear last in the list of alternatives. + +The syntax of a @code{case} construction is based on the Ada case statement +(although the @code{null} statement for empty alternatives is optional). + +The case expression must be a typed string variable, whose value is often +given by an external reference (@pxref{External Values}). + +Each alternative starts with 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. +After each @code{=>}, there are zero or more statements. The only +statements allowed in a case construction are other case statements, +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. + +@smallexample +case_statement ::= + @i{case} @i{}name @i{is} @{case_item@} @i{end case} ; + +case_item ::= + @i{when} discrete_choice_list => + @{case_statement + | attribute_declaration + | variable_declaration + | empty_declaration@} + +discrete_choice_list ::= string_literal @{| string_literal@} | @i{others} +@end smallexample + +@noindent +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"); + + package Compiler is + case OS is + when "GNU/Linux" | "Unix" => + for Switches ("Ada") use ("-gnath"); + when "NT" => + for Switches ("Ada") use ("-gnatP"); + when others => + end case; + end Compiler; +end MyProj; +@end group +@end smallexample + +@c --------------------------------------------- +@node Tools Supporting Project Files +@chapter Tools Supporting Project Files +@c --------------------------------------------- + +@noindent + + +@menu +* gnatmake and Project Files:: +* The GNAT Driver and Project Files:: +* The Development Environments:: +* Cleaning up with GPRclean:: +@end menu + +@c --------------------------------------------- +@node gnatmake and Project Files +@section gnatmake and Project Files +@c --------------------------------------------- + +@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 Related to Project Files:: +* Switches and Project Files:: +* Specifying Configuration Pragmas:: +* Project Files and Main Subprograms:: +* Library Project Files:: +@end menu + +@c --------------------------------------------- +@node Switches Related to Project Files +@subsection Switches Related to Project Files +@c --------------------------------------------- + +@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 + +There must be only one @option{^-P^/PROJECT_FILE^} switch on the command line. + +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 +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 + +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. + +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 + +The default is ^Default^DEFAULT^: no output for syntactically correct +project files. +If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present, +only the last one is used. + +@item ^-aP^/ADD_PROJECT_SEARCH_DIR=^ +@CINDEX{@option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool)} +Add directory 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^= +@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 +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 --------------------------------------------- +@node Switches and Project Files +@subsection Switches and Project Files +@c --------------------------------------------- + +@noindent +@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 + +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} 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 attribute +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} attribute is indexed on 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 ("main1.adb") + use ("^-O2^-O2^"); + for 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 (@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 + +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 ("a.adb") + use ("^-O1^-O1^"); + for 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 ("main.adb") + use ("^-g^-g^", + "^-O1^-)1^", + "^-f^-f^"); + end Builder; +@end group + +@group + package Compiler is + for 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 + +@noindent +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 ("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 + +@noindent +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. + +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. + +@c --------------------------------------------- +@node Specifying Configuration Pragmas +@subsection Specifying Configuration Pragmas +@c --------------------------------------------- + +@noindent +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. + +@c --------------------------------------------- +@node Project Files and Main Subprograms +@subsection Project Files and Main Subprograms +@c --------------------------------------------- + +@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. + +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}. + +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. + +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. + +@c --------------------------------------------- +@node Library Project Files +@subsection Library Project Files +@c --------------------------------------------- + +@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. + +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 + + +@c --------------------------------------------- +@node The GNAT Driver and Project Files +@section The GNAT Driver and Project Files +@c --------------------------------------------- + +@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^}). + +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. + +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. + +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. + +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 + +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}, +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 + use ("^-a^-a^", + "^-v^-v^"); + end gnatls; +end Proj1; +@end group +@end smallexample + +@noindent +All other packages have two attribute @code{Switches} and +@code{^Default_Switches^Default_Switches^}. + +@code{Switches} is an indexed 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. + +@code{^Default_Switches^Default_Switches^} is an 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} attribute +is specified for the source file. + +@smallexample @c projectfile +@group +project Proj is + + for Source_Dirs use ("./**"); + + package gnatls is + for 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 ("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 ("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 + +@noindent +will compute the metrics for all the immediate units of project +@code{proj}. +@smallexample +gnat metric -Pproj -U +@end smallexample + +@noindent +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 + +@noindent +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 The Development Environments +@section The Development Environments +@c --------------------------------------------- + +@noindent +See the appropriate manuals for more details. These environments will +store a number of settings in the project itself, when they are meant +to be shared by the whole team working on the project. Here are the +attributes defined in the package @b{IDE} in projects. + +@table @code +@item Remote_Host +This is a simple attribute. Its value is a string that designates the remote +host in a cross-compilation environment, to be used for remote compilation and +debugging. This field should not be specified when running on the local +machine. + +@item Program_Host +This is a simple attribute. Its value is a string that specifies the +name of IP address of the embedded target in a cross-compilation environment, +on which the program should execute. + +@item Communication_Protocol +This is a simple string attribute. Its value is the name of the protocol +to use to communicate with the target in a cross-compilation environment, +e.g.@: @code{"wtx"} or @code{"vxworks"}. + +@item Compiler_Command +This is an associative array attribute, whose domain is a language name. Its +value is string that denotes the command to be used to invoke the compiler. +The value of @code{Compiler_Command ("Ada")} is expected to be compatible with +gnatmake, in particular in the handling of switches. + +@item Debugger_Command +This is simple attribute, Its value is a string that specifies the name of +the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4. + +@item Default_Switches +This is an associative array attribute. Its indexes are the name of the +external tools that the GNAT Programming System (GPS) is supporting. Its +value is a list of switches to use when invoking that tool. + +@item Gnatlist +This is a simple attribute. Its value is a string that specifies the name +of the @command{gnatls} utility to be used to retrieve information about the +predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}. +@item VCS_Kind +This is a simple attribute. Its value is a string used to specify the +Version Control System (VCS) to be used for this project, e.g.@: CVS, RCS +ClearCase or Perforce. + +@item VCS_File_Check +This is a simple attribute. Its value is a string that specifies the +command used by the VCS to check the validity of a file, either +when the user explicitly asks for a check, or as a sanity check before +doing the check-in. + +@item VCS_Log_Check +This is a simple attribute. Its value is a string that specifies +the command used by the VCS to check the validity of a log file. + +@item VCS_Repository_Root +The VCS repository root path. This is used to create tags or branches +of the repository. For subversion the value should be the @code{URL} +as specified to check-out the working copy of the repository. + +@item VCS_Patch_Root +The local root directory to use for building patch file. All patch chunks +will be relative to this path. The root project directory is used if +this value is not defined. + +@end table + +@c --------------------------------------------- +@node Cleaning up with GPRclean +@section Cleaning up with GPRclean +@c --------------------------------------------- + +@noindent +The GPRclean tool removes the files created by GPRbuild. +At a minimum, to invoke GPRclean you must specify a main project file +in a command such as @code{gprclean proj.gpr} or @code{gprclean -P proj.gpr}. + +Examples of invocation of GPRclean: + +@smallexample + gprclean -r prj1.gpr + gprclean -c -P prj2.gpr +@end smallexample + +@menu +* Switches for GPRclean:: +@end menu + +@c --------------------------------------------- +@node Switches for GPRclean +@subsection Switches for GPRclean +@c --------------------------------------------- + +@noindent +The switches for GPRclean are: + +@itemize @bullet +@item @option{--config=
} : Specify the + configuration project file name + +@item @option{--autoconf=} + + This specifies a configuration project file name that already exists or will + be created automatically. Option @option{--autoconf=} + cannot be specified more than once. If the configuration project file + specified with @option{--autoconf=} exists, then it is used. Otherwise, + @value{gprconfig} is invoked to create it automatically. + +@item @option{-c} : Only delete compiler-generated files. Do not delete + executables and libraries. + +@item @option{-f} : Force deletions of unwritable files + +@item @option{-F} : Display full project path name in brief error messages + +@item @option{-h} : Display this message + +@item @option{-n} : Do not delete files, only list files to delete + +@item @option{-P} : Use Project File @emph{}. + +@item @option{-q} : Be quiet/terse. There is no output, except to report + problems. + +@item @option{-r} : (recursive) Clean all projects referenced by the main + project directly or indirectly. Without this switch, GPRclean only + cleans the main project. + +@item @option{-v} : Verbose mode + +@item @option{-vPx} : Specify verbosity when parsing Project Files. + x = 0 (default), 1 or 2. + +@item @option{-Xnm=val} : Specify an external reference for Project Files. +@end itemize + + +