===================================================================
@@ -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} <typed_string_>_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 ::=
- <typed_variable_>simple_name : <typed_string_>name := string_expression ;
-
-variable_declaration ::=
- <variable_>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 |
- <variable_>name |
- external_value |
- attribute_reference
-
-string_literal ::=
- (same as Ada)
-
-string_list ::=
- ( <string_>expression @{ , <string_>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} <associative_array_attribute_>simple_name @b{use}
- <project_>simple_name [ . <package_>simple_Name ] ' <attribute_>simple_name ;
-
-attribute_designator ::=
- <simple_attribute_>simple_name |
- <associative_array_attribute_>simple_name ( string_literal )
-@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_attribute_>simple_name [ ( string_literal ) ]
-
-attribute_prefix ::=
- @b{project} |
- <project_simple_name | package_identifier |
- <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} <typed_variable_>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}
- <project_>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} <project_>simple_name @b{is}
- @{declarative_item@}
- @b{end} <project_>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} <project_>simple_name @b{extends} path_name @b{is}
- @{declarative_item@}
- @b{end} <project_>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
===================================================================
@@ -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{<entity>'<attribute>}:
-Associative array attributes are functions. Associative
-array attribute references must have an argument that is a string literal.
-
-Examples are:
-
-@smallexample @c projectfile
- project'Object_Dir
- Naming'Dot_Replacement
- Imported_Project'Source_Dirs
- Imported_Project.Naming'Casing
- Builder'^Default_Switches^Default_Switches^("Ada")
-@end smallexample
-
-@noindent
-The prefix of an attribute may be:
-@itemize @bullet
-@item @code{project} for an attribute of the current project
-@item The name of an existing package of the current project
-@item The name of an imported project
-@item The name of a parent project that is extended by the current project
-@item An expanded name whose prefix is imported/parent project name,
-and whose selector is a package name
-@end itemize
-
-@noindent
-Example:
-@smallexample @c projectfile
-@group
- project Prj is
- for Source_Dirs use project'Source_Dirs & "units";
- for Source_Dirs use project'Source_Dirs & "test/drivers"
- end Prj;
-@end group
-@end smallexample
-
-@noindent
-In the first attribute declaration, initially the attribute @code{Source_Dirs}
-has the default value: an empty string list. After this declaration,
-@code{Source_Dirs} is a string list of one element: @code{"units"}.
-After the second attribute declaration @code{Source_Dirs} is a string list of
-two elements: @code{"units"} and @code{"test/drivers"}.
-
-Note: this example is for illustration only. In practice,
-the project file would contain only one attribute declaration:
-
-@smallexample @c projectfile
- for Source_Dirs use ("units", "test/drivers");
-@end smallexample
-
-@node Associative Array Attributes
-@subsection Associative Array Attributes
-
-@noindent
-Some attributes are defined as @emph{associative arrays}. An associative
-array may be regarded as a function that takes a string as a parameter
-and delivers a string or string list value as its result.
-
-Here are some examples of single associative array attribute associations:
-
-@smallexample @c projectfile
- for Body ("main") use "Main.ada";
- for ^Switches^Switches^ ("main.ada")
- use ("^-v^-v^",
- "^-gnatv^-gnatv^");
- for ^Switches^Switches^ ("main.ada")
- use Builder'^Switches^Switches^ ("main.ada")
- & "^-g^-g^";
-@end smallexample
-
-@noindent
-Like untyped variables and simple attributes, associative array attributes
-may be declared several times. Each declaration supplies a new value for the
-attribute, and replaces the previous setting.
-
-@noindent
-An associative array attribute may be declared as a full associative array
-declaration, with the value of the same attribute in an imported or extended
-project.
-
-@smallexample @c projectfile
- package Builder is
- for Default_Switches use Default.Builder'Default_Switches;
- end Builder;
-@end smallexample
-
-@noindent
-In this example, @code{Default} must be either a project imported by the
-current project, or the project that the current project extends. If the
-attribute is in a package (in this case, in package @code{Builder}), the same
-package needs to be specified.
-
-@noindent
-A full associative array declaration replaces any other declaration for the
-attribute, including other full associative array declaration. Single
-associative array associations may be declare after a full associative
-declaration, modifying the value for a single association of the attribute.
-
-@node case Constructions
-@subsection @code{case} Constructions
-
-@noindent
-A @code{case} construction is used in a project file to effect conditional
-behavior.
-Here is a typical example:
-
-@smallexample @c projectfile
-@group
-project MyProj is
- type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
-
- OS : OS_Type := external ("OS", "GNU/Linux");
-@end group
-
-@group
- package Compiler is
- case OS is
- when "GNU/Linux" | "Unix" =>
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-gnath^-gnath^");
- when "NT" =>
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-gnatP^-gnatP^");
- when others =>
- end case;
- end Compiler;
-end MyProj;
-@end group
-@end smallexample
-
-@noindent
-The syntax of a @code{case} construction is based on the Ada case statement
-(although there is no @code{null} construction for empty alternatives).
-
-The case expression must be a typed string variable.
-Each alternative comprises the reserved word @code{when}, either a list of
-literal strings separated by the @code{"|"} character or the reserved word
-@code{others}, and the @code{"=>"} token.
-Each literal string must belong to the string type that is the type of the
-case variable.
-An @code{others} alternative, if present, must occur last.
-
-After each @code{=>}, there are zero or more constructions. The only
-constructions allowed in a case construction are other case constructions,
-attribute declarations and variable declarations. String type declarations and
-package declarations are not allowed. Variable declarations are restricted to
-variables that have already been declared before the case construction.
-
-The value of the case variable is often given by an external reference
-(@pxref{External References in Project Files}).
-
-@c ****************************************
-@c * Objects and Sources in Project Files *
-@c ****************************************
-
-@node Objects and Sources in Project Files
-@section Objects and Sources in Project Files
-
-@menu
-* Object Directory::
-* Exec Directory::
-* Source Directories::
-* Source File Names::
-@end menu
-
-@noindent
-Each project has exactly one object directory and one or more source
-directories. The source directories must contain at least one source file,
-unless the project file explicitly specifies that no source files are present
-(@pxref{Source File Names}).
-
-@node Object Directory
-@subsection Object Directory
-
-@noindent
-The object directory for a project is the directory containing the compiler's
-output (such as @file{ALI} files and object files) for the project's immediate
-sources.
-
-The object directory is given by the value of the attribute @code{Object_Dir}
-in the project file.
-
-@smallexample @c projectfile
- for Object_Dir use "objects";
-@end smallexample
-
-@noindent
-The attribute @code{Object_Dir} has a string value, the path name of the object
-directory. The path name may be absolute or relative to the directory of the
-project file. This directory must already exist, and be readable and writable.
-
-By default, when the attribute @code{Object_Dir} is not given an explicit value
-or when its value is the empty string, the object directory is the same as the
-directory containing the project file.
-
-@node Exec Directory
-@subsection Exec Directory
-
-@noindent
-The exec directory for a project is the directory containing the executables
-for the project's main subprograms.
-
-The exec directory is given by the value of the attribute @code{Exec_Dir}
-in the project file.
-
-@smallexample @c projectfile
- for Exec_Dir use "executables";
-@end smallexample
-
-@noindent
-The attribute @code{Exec_Dir} has a string value, the path name of the exec
-directory. The path name may be absolute or relative to the directory of the
-project file. This directory must already exist, and be writable.
-
-By default, when the attribute @code{Exec_Dir} is not given an explicit value
-or when its value is the empty string, the exec directory is the same as the
-object directory of the project file.
-
-@node Source Directories
-@subsection Source Directories
-
-@noindent
-The source directories of a project are specified by the project file
-attribute @code{Source_Dirs}.
-
-This attribute's value is a string list. If the attribute is not given an
-explicit value, then there is only one source directory, the one where the
-project file resides.
-
-A @code{Source_Dirs} attribute that is explicitly defined to be the empty list,
-as in
-
-@smallexample @c projectfile
- for Source_Dirs use ();
-@end smallexample
-
-@noindent
-indicates that the project contains no source files.
-
-Otherwise, each string in the string list designates one or more
-source directories.
-
-@smallexample @c projectfile
- for Source_Dirs use ("sources", "test/drivers");
-@end smallexample
-
-@noindent
-If a string in the list ends with @code{"/**"}, then the directory whose path
-name precedes the two asterisks, as well as all its subdirectories
-(recursively), are source directories.
-
-@smallexample @c projectfile
- for Source_Dirs use ("/system/sources/**");
-@end smallexample
-
-@noindent
-Here the directory @code{/system/sources} and all of its subdirectories
-(recursively) are source directories.
-
-To specify that the source directories are the directory of the project file
-and all of its subdirectories, you can declare @code{Source_Dirs} as follows:
-@smallexample @c projectfile
- for Source_Dirs use ("./**");
-@end smallexample
-
-@noindent
-Each of the source directories must exist and be readable.
-
-@node Source File Names
-@subsection Source File Names
-
-@noindent
-In a project that contains source files, their names may be specified by the
-attributes @code{Source_Files} (a string list) or @code{Source_List_File}
-(a string). Source file names never include any directory information.
-
-If the attribute @code{Source_Files} is given an explicit value, then each
-element of the list is a source file name.
-
-@smallexample @c projectfile
- for Source_Files use ("main.adb");
- for Source_Files use ("main.adb", "pack1.ads", "pack2.adb");
-@end smallexample
-
-@noindent
-If the attribute @code{Source_Files} is not given an explicit value,
-but the attribute @code{Source_List_File} is given a string value,
-then the source file names are contained in the text file whose path name
-(absolute or relative to the directory of the project file) is the
-value of the attribute @code{Source_List_File}.
-
-Each line in the file that is not empty or is not a comment
-contains a source file name.
-
-@smallexample @c projectfile
- for Source_List_File use "source_list.txt";
-@end smallexample
-
-@noindent
-By default, if neither the attribute @code{Source_Files} nor the attribute
-@code{Source_List_File} is given an explicit value, then each file in the
-source directories that conforms to the project's naming scheme
-(@pxref{Naming Schemes}) is an immediate source of the project.
-
-A warning is issued if both attributes @code{Source_Files} and
-@code{Source_List_File} are given explicit values. In this case, the attribute
-@code{Source_Files} prevails.
-
-Each source file name must be the name of one existing source file
-in one of the source directories.
-
-A @code{Source_Files} attribute whose value is an empty list
-indicates that there are no source files in the project.
-
-If the order of the source directories is known statically, that is if
-@code{"/**"} is not used in the string list @code{Source_Dirs}, then there may
-be several files with the same source file name. In this case, only the file
-in the first directory is considered as an immediate source of the project
-file. If the order of the source directories is not known statically, it is
-an error to have several files with the same source file name.
-
-Projects can be specified to have no Ada source
-files: the value of @code{Source_Dirs} or @code{Source_Files} may be an empty
-list, or the @code{"Ada"} may be absent from @code{Languages}:
-
-@smallexample @c projectfile
- for Source_Dirs use ();
- for Source_Files use ();
- for Languages use ("C", "C++");
-@end smallexample
-
-@noindent
-Otherwise, a project must contain at least one immediate source.
-
-Projects with no source files are useful as template packages
-(@pxref{Packages in Project Files}) for other projects; in particular to
-define a package @code{Naming} (@pxref{Naming Schemes}).
-
-@c ****************************
-@c * Importing Projects *
-@c ****************************
-
-@node Importing Projects
-@section Importing Projects
-@cindex @code{ADA_PROJECT_PATH}
-@cindex @code{GPR_PROJECT_PATH}
-
-@noindent
-An immediate source of a project P may depend on source files that
-are neither immediate sources of P nor in the predefined library.
-To get this effect, P must @emph{import} the projects that contain the needed
-source files.
-
-@smallexample @c projectfile
-@group
- with "project1", "utilities.gpr";
- with "/namings/apex.gpr";
- project Main is
- @dots{}
-@end group
-@end smallexample
-
-@noindent
-As can be seen in this example, the syntax for importing projects is similar
-to the syntax for importing compilation units in Ada. However, project files
-use literal strings instead of names, and the @code{with} clause identifies
-project files rather than packages.
-
-Each literal string is the file name or path name (absolute or relative) of a
-project file. If a string corresponds to a file name, with no path or a
-relative path, then its location is determined by the @emph{project path}. The
-latter can be queried using @code{gnatls -v}. It contains:
-
-@itemize @bullet
-@item
-In first position, the directory containing the current project file.
-@item
-In last position, the default project directory. This default project directory
-is part of the GNAT installation and is the standard place to install project
-files giving access to standard support libraries.
-@ifclear vms
-@ref{Installing a library}
-@end ifclear
-
-@item
-In between, all the directories referenced in the
-^environment variables^logical names^ @env{GPR_PROJECT_PATH}
-and @env{ADA_PROJECT_PATH} if they exist, and in that order.
-@end itemize
-
-@noindent
-If a relative pathname is used, as in
-
-@smallexample @c projectfile
- with "tests/proj";
-@end smallexample
-
-@noindent
-then the full path for the project is constructed by concatenating this
-relative path to those in the project path, in order, until a matching file is
-found. Any symbolic link will be fully resolved in the directory of the
-importing project file before the imported project file is examined.
-
-If the @code{with}'ed project file name does not have an extension,
-the default is @file{^.gpr^.GPR^}. If a file with this extension is not found,
-then the file name as specified in the @code{with} clause (no extension) will
-be used. In the above example, if a file @code{project1.gpr} is found, then it
-will be used; otherwise, if a file @code{^project1^PROJECT1^} exists
-then it will be used; if neither file exists, this is an error.
-
-A warning is issued if the name of the project file does not match the
-name of the project; this check is case insensitive.
-
-Any source file that is an immediate source of the imported project can be
-used by the immediate sources of the importing project, transitively. Thus
-if @code{A} imports @code{B}, and @code{B} imports @code{C}, the immediate
-sources of @code{A} may depend on the immediate sources of @code{C}, even if
-@code{A} does not import @code{C} explicitly. However, this is not recommended,
-because if and when @code{B} ceases to import @code{C}, some sources in
-@code{A} will no longer compile.
-
-A side effect of this capability is that normally cyclic dependencies are not
-permitted: if @code{A} imports @code{B} (directly or indirectly) then @code{B}
-is not allowed to import @code{A}. However, there are cases when cyclic
-dependencies would be beneficial. For these cases, another form of import
-between projects exists, the @code{limited with}: a project @code{A} that
-imports a project @code{B} with a straight @code{with} may also be imported,
-directly or indirectly, by @code{B} on the condition that imports from @code{B}
-to @code{A} include at least one @code{limited with}.
-
-@smallexample @c 0projectfile
-with "../b/b.gpr";
-with "../c/c.gpr";
-project A is
-end A;
-
-limited with "../a/a.gpr";
-project B is
-end B;
-
-with "../d/d.gpr";
-project C is
-end C;
-
-limited with "../a/a.gpr";
-project D is
-end D;
-@end smallexample
-
-@noindent
-In the above legal example, there are two project cycles:
-@itemize @bullet
-@item A-> B-> A
-@item A -> C -> D -> A
-@end itemize
-
-@noindent
-In each of these cycle there is one @code{limited with}: import of @code{A}
-from @code{B} and import of @code{A} from @code{D}.
-
-The difference between straight @code{with} and @code{limited with} is that
-the name of a project imported with a @code{limited with} cannot be used in the
-project that imports it. In particular, its packages cannot be renamed and
-its variables cannot be referred to.
-
-An exception to the above rules for @code{limited with} is that for the main
-project specified to @command{gnatmake} or to the @command{GNAT} driver a
-@code{limited with} is equivalent to a straight @code{with}. For example,
-in the example above, projects @code{B} and @code{D} could not be main
-projects for @command{gnatmake} or to the @command{GNAT} driver, because they
-each have a @code{limited with} that is the only one in a cycle of importing
-projects.
-
-@c *********************
-@c * Project Extension *
-@c *********************
-
-@node Project Extension
-@section Project Extension
-
-@noindent
-During development of a large system, it is sometimes necessary to use
-modified versions of some of the source files, without changing the original
-sources. This can be achieved through the @emph{project extension} facility.
-
-@smallexample @c projectfile
- project Modified_Utilities extends "/baseline/utilities.gpr" is @dots{}
-@end smallexample
-
-@noindent
-A project extension declaration introduces an extending project
-(the @emph{child}) and a project being extended (the @emph{parent}).
-
-By default, a child project inherits all the sources of its parent.
-However, inherited sources can be overridden: a unit in a parent is hidden
-by a unit of the same name in the child.
-
-Inherited sources are considered to be sources (but not immediate sources)
-of the child project; see @ref{Project File Syntax}.
-
-An inherited source file retains any switches specified in the parent project.
-
-For example if the project @code{Utilities} contains the spec and the
-body of an Ada package @code{Util_IO}, then the project
-@code{Modified_Utilities} can contain a new body for package @code{Util_IO}.
-The original body of @code{Util_IO} will not be considered in program builds.
-However, the package spec will still be found in the project
-@code{Utilities}.
-
-A child project can have only one parent, except when it is qualified as
-abstract. But it may import any number of other projects.
-
-A project is not allowed to import directly or indirectly at the same time a
-child project and any of its ancestors.
-
-@c *******************************
-@c * Project Hierarchy Extension *
-@c *******************************
-
-@node Project Hierarchy Extension
-@section Project Hierarchy Extension
-
-@noindent
-When extending a large system spanning multiple projects, it is often
-inconvenient to extend every project in the hierarchy that is impacted by a
-small change introduced. In such cases, it is possible to create a virtual
-extension of entire hierarchy using @code{extends all} relationship.
-
-When the project is extended using @code{extends all} inheritance, all projects
-that are imported by it, both directly and indirectly, are considered virtually
-extended. That is, the Project Manager creates "virtual projects"
-that extend every project in the hierarchy; all these virtual projects have
-no sources of their own and have as object directory the object directory of
-the root of "extending all" project.
-
-It is possible to explicitly extend one or more projects in the hierarchy
-in order to modify the sources. These extending projects must be imported by
-the "extending all" project, which will replace the corresponding virtual
-projects with the explicit ones.
-
-When building such a project hierarchy extension, the Project Manager will
-ensure that both modified sources and sources in virtual extending projects
-that depend on them, are recompiled.
-
-By means of example, consider the following hierarchy of projects.
-
-@enumerate
-@item
-project A, containing package P1
-@item
-project B importing A and containing package P2 which depends on P1
-@item
-project C importing B and containing package P3 which depends on P2
-@end enumerate
-
-@noindent
-We want to modify packages P1 and P3.
-
-This project hierarchy will need to be extended as follows:
-
-@enumerate
-@item
-Create project A1 that extends A, placing modified P1 there:
-
-@smallexample @c 0projectfile
-project A1 extends "(@dots{})/A" is
-end A1;
-@end smallexample
-
-@item
-Create project C1 that "extends all" C and imports A1, placing modified
-P3 there:
-
-@smallexample @c 0projectfile
-with "(@dots{})/A1";
-project C1 extends all "(@dots{})/C" is
-end C1;
-@end smallexample
-@end enumerate
-
-When you build project C1, your entire modified project space will be
-recompiled, including the virtual project B1 that has been impacted by the
-"extending all" inheritance of project C.
-
-Note that if a Library Project in the hierarchy is virtually extended,
-the virtual project that extends the Library Project is not a Library Project.
-
-@c ****************************************
-@c * External References in Project Files *
-@c ****************************************
-
-@node External References in Project Files
-@section External References in Project Files
-
-@noindent
-A project file may contain references to external variables; such references
-are called @emph{external references}.
-
-An external variable is either defined as part of the environment (an
-environment variable in Unix, for example) or else specified on the command
-line via the @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch.
-If both, then the command line value is used.
-
-The value of an external reference is obtained by means of the built-in
-function @code{external}, which returns a string value.
-This function has two forms:
-@itemize @bullet
-@item @code{external (external_variable_name)}
-@item @code{external (external_variable_name, default_value)}
-@end itemize
-
-@noindent
-Each parameter must be a string literal. For example:
-
-@smallexample @c projectfile
- external ("USER")
- external ("OS", "GNU/Linux")
-@end smallexample
-
-@noindent
-In the form with one parameter, the function returns the value of
-the external variable given as parameter. If this name is not present in the
-environment, the function returns an empty string.
-
-In the form with two string parameters, the second argument is
-the value returned when the variable given as the first argument is not
-present in the environment. In the example above, if @code{"OS"} is not
-the name of ^an environment variable^a logical name^ and is not passed on
-the command line, then the returned value is @code{"GNU/Linux"}.
-
-An external reference may be part of a string expression or of a string
-list expression, and can therefore appear in a variable declaration or
-an attribute declaration.
-
-@smallexample @c projectfile
-@group
- type Mode_Type is ("Debug", "Release");
- Mode : Mode_Type := external ("MODE");
- case Mode is
- when "Debug" =>
- @dots{}
-@end group
-@end smallexample
-
-@c *****************************
-@c * Packages in Project Files *
-@c *****************************
-
-@node Packages in Project Files
-@section Packages in Project Files
-
-@noindent
-A @emph{package} defines the settings for project-aware tools within a
-project.
-For each such tool one can declare a package; the names for these
-packages are preset (@pxref{Packages}).
-A package may contain variable declarations, attribute declarations, and case
-constructions.
-
-@smallexample @c projectfile
-@group
- project Proj is
- package Builder is -- used by gnatmake
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-v^-v^",
- "^-g^-g^");
- end Builder;
- end Proj;
-@end group
-@end smallexample
-
-@noindent
-The syntax of package declarations mimics that of package in Ada.
-
-Most of the packages have an attribute
-@code{^Default_Switches^Default_Switches^}.
-This attribute is an associative array, and its value is a string list.
-The index of the associative array is the name of a programming language (case
-insensitive). This attribute indicates the ^switch^switch^
-or ^switches^switches^ to be used
-with the corresponding tool.
-
-Some packages also have another attribute, @code{^Switches^Switches^},
-an associative array whose value is a string list.
-The index is the name of a source file.
-This attribute indicates the ^switch^switch^
-or ^switches^switches^ to be used by the corresponding
-tool when dealing with this specific file.
-
-Further information on these ^switch^switch^-related attributes is found in
-@ref{^Switches^Switches^ and Project Files}.
-
-A package may be declared as a @emph{renaming} of another package; e.g., from
-the project file for an imported project.
-
-@smallexample @c projectfile
-@group
- with "/global/apex.gpr";
- project Example is
- package Naming renames Apex.Naming;
- @dots{}
- end Example;
-@end group
-@end smallexample
-
-@noindent
-Packages that are renamed in other project files often come from project files
-that have no sources: they are just used as templates. Any modification in the
-template will be reflected automatically in all the project files that rename
-a package from the template.
-
-In addition to the tool-oriented packages, you can also declare a package
-named @code{Naming} to establish specialized source file naming conventions
-(@pxref{Naming Schemes}).
-
-@c ************************************
-@c * Variables from Imported Projects *
-@c ************************************
-
-@node Variables from Imported Projects
-@section Variables from Imported Projects
-
-@noindent
-An attribute or variable defined in an imported or parent project can
-be used in expressions in the importing / extending project.
-Such an attribute or variable is denoted by an expanded name whose prefix
-is either the name of the project or the expanded name of a package within
-a project.
-
-@smallexample @c projectfile
-@group
- with "imported";
- project Main extends "base" is
- Var1 := Imported.Var;
- Var2 := Base.Var & ".new";
-@end group
-
-@group
- package Builder is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use Imported.Builder'Ada_^Switches^Switches^ &
- "^-gnatg^-gnatg^" &
- "^-v^-v^";
- end Builder;
-@end group
-
-@group
- package Compiler is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use Base.Compiler'Ada_^Switches^Switches^;
- end Compiler;
- end Main;
-@end group
-@end smallexample
-
-@noindent
-In this example:
-
-@itemize @bullet
-@item
-The value of @code{Var1} is a copy of the variable @code{Var} defined
-in the project file @file{"imported.gpr"}
-@item
-the value of @code{Var2} is a copy of the value of variable @code{Var}
-defined in the project file @file{base.gpr}, concatenated with @code{".new"}
-@item
-attribute @code{^Default_Switches^Default_Switches^ ("Ada")} in package
-@code{Builder} is a string list that includes in its value a copy of the value
-of @code{Ada_^Switches^Switches^} defined in the @code{Builder} package
-in project file @file{imported.gpr} plus two new elements:
-@option{"^-gnatg^-gnatg^"}
-and @option{"^-v^-v^"};
-@item
-attribute @code{^Default_Switches^Default_Switches^ ("Ada")} in package
-@code{Compiler} is a copy of the variable @code{Ada_^Switches^Switches^}
-defined in the @code{Compiler} package in project file @file{base.gpr},
-the project being extended.
-@end itemize
-
-@c ******************
-@c * Naming Schemes *
-@c ******************
-
-@node Naming Schemes
-@section Naming Schemes
-
-@noindent
-Sometimes an Ada software system is ported from a foreign compilation
-environment to GNAT, and the file names do not use the default GNAT
-conventions. Instead of changing all the file names (which for a variety
-of reasons might not be possible), you can define the relevant file
-naming scheme in the @code{Naming} package in your project file.
-
-@noindent
-Note that the use of pragmas described in
-@ref{Alternative File Naming Schemes} by mean of a configuration
-pragmas file is not supported when using project files. You must use
-the features described in this paragraph. You can however use specify
-other configuration pragmas (@pxref{Specifying Configuration Pragmas}).
-
-@ifclear vms
-For example, the following
-package models the Apex file naming rules:
-
-@smallexample @c projectfile
-@group
- package Naming is
- for Casing use "lowercase";
- for Dot_Replacement use ".";
- for Spec_Suffix ("Ada") use ".1.ada";
- for Body_Suffix ("Ada") use ".2.ada";
- end Naming;
-@end group
-@end smallexample
-@end ifclear
-
-@ifset vms
-For example, the following package models the HP Ada file naming rules:
-
-@smallexample @c projectfile
-@group
- package Naming is
- for Casing use "lowercase";
- for Dot_Replacement use "__";
- for Spec_Suffix ("Ada") use "_.^ada^ada^";
- for Body_Suffix ("Ada") use ".^ada^ada^";
- end Naming;
-@end group
-@end smallexample
-
-@noindent
-(Note that @code{Casing} is @code{"lowercase"} because GNAT gets the file
-names in lower case)
-@end ifset
-
-@noindent
-You can define the following attributes in package @code{Naming}:
-
-@table @code
-
-@item @code{Casing}
-This must be a string with one of the three values @code{"lowercase"},
-@code{"uppercase"} or @code{"mixedcase"}; these strings are case insensitive.
-
-@noindent
-If @code{Casing} is not specified, then the default is @code{"lowercase"}.
-
-@item @code{Dot_Replacement}
-This must be a string whose value satisfies the following conditions:
-
-@itemize @bullet
-@item It must not be empty
-@item It cannot start or end with an alphanumeric character
-@item It cannot be a single underscore
-@item It cannot start with an underscore followed by an alphanumeric
-@item It cannot contain a dot @code{'.'} except if the entire string
-is @code{"."}
-@end itemize
-
-@noindent
-If @code{Dot_Replacement} is not specified, then the default is @code{"-"}.
-
-@item @code{Spec_Suffix}
-This is an associative array (indexed by the programming language name, case
-insensitive) whose value is a string that must satisfy the following
-conditions:
-
-@itemize @bullet
-@item It must not be empty
-@item It must include at least one dot
-@end itemize
-@noindent
-If @code{Spec_Suffix ("Ada")} is not specified, then the default is
-@code{"^.ads^.ADS^"}.
-
-@item @code{Body_Suffix}
-This is an associative array (indexed by the programming language name, case
-insensitive) whose value is a string that must satisfy the following
-conditions:
-
-@itemize @bullet
-@item It must not be empty
-@item It must include at least one dot
-@item It cannot be the same as @code{Spec_Suffix ("Ada")}
-@end itemize
-@noindent
-If @code{Body_Suffix ("Ada")} and @code{Spec_Suffix ("Ada")} end with the
-same string, then a file name that ends with the longest of these two suffixes
-will be a body if the longest suffix is @code{Body_Suffix ("Ada")} or a spec
-if the longest suffix is @code{Spec_Suffix ("Ada")}.
-
-If the suffix does not start with a '.', a file with a name exactly equal
-to the suffix will also be part of the project (for instance if you define
-the suffix as @code{Makefile}, a file called @file{Makefile} will be part
-of the project. This is not interesting in general when using projects to
-compile. However, it might become useful when a project is also used to
-find the list of source files in an editor, like the GNAT Programming System
-(GPS).
-
-If @code{Body_Suffix ("Ada")} is not specified, then the default is
-@code{"^.adb^.ADB^"}.
-
-@item @code{Separate_Suffix}
-This must be a string whose value satisfies the same conditions as
-@code{Body_Suffix}. The same "longest suffix" rules apply.
-
-@noindent
-If @code{Separate_Suffix ("Ada")} is not specified, then it defaults to same
-value as @code{Body_Suffix ("Ada")}.
-
-@item @code{Spec}
-@noindent
-You can use the associative array attribute @code{Spec} to define
-the source file name for an individual Ada compilation unit's spec. The array
-index must be a string literal that identifies the Ada unit (case insensitive).
-The value of this attribute must be a string that identifies the file that
-contains this unit's spec (case sensitive or insensitive depending on the
-operating system).
-
-@smallexample @c projectfile
- for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
-@end smallexample
-
-When the source file contains several units, you can indicate at what
-position the unit occurs in the file, with the following. The first unit
-in the file has index 1
-
-@smallexample @c projectfile
- for Body ("top") use "foo.a" at 1;
- for Body ("foo") use "foo.a" at 2;
-@end smallexample
-
-@item @code{Body}
-
-You can use the associative array attribute @code{Body} to
-define the source file name for an individual Ada compilation unit's body
-(possibly a subunit). The array index must be a string literal that identifies
-the Ada unit (case insensitive). The value of this attribute must be a string
-that identifies the file that contains this unit's body or subunit (case
-sensitive or insensitive depending on the operating system).
-
-@smallexample @c projectfile
- for Body ("MyPack.MyChild") use "mypack.mychild.body";
-@end smallexample
-@end table
-
-@c ********************
-@c * Library Projects *
-@c ********************
-
-@node Library Projects
-@section Library Projects
-
-@noindent
-@emph{Library projects} are projects whose object code is placed in a library.
-(Note that this facility is not yet supported on all platforms).
-
-@code{gnatmake} or @code{gprbuild} will collect all object files into a
-single archive, which might either be a shared or a static library. This
-library can later on be linked with multiple executables, potentially
-reducing their sizes.
-
-If your project file specifies languages other than Ada, but you are still
-using @code{gnatmake} to compile and link, the latter will not try to
-compile your sources other than Ada (you should use @code{gprbuild} if that
-is your intent). However, @code{gnatmake} will automatically link all object
-files found in the object directory, whether or not they were compiled from
-an Ada source file. This specific behavior only applies when multiple
-languages are specified.
-
-To create a library project, you need to define in its project file
-two project-level attributes: @code{Library_Name} and @code{Library_Dir}.
-Additionally, you may define other library-related attributes such as
-@code{Library_Kind}, @code{Library_Version}, @code{Library_Interface},
-@code{Library_Auto_Init}, @code{Library_Options} and @code{Library_GCC}.
-
-The @code{Library_Name} attribute has a string value. There is no restriction
-on the name of a library. It is the responsibility of the developer to
-choose a name that will be accepted by the platform. It is recommended to
-choose names that could be Ada identifiers; such names are almost guaranteed
-to be acceptable on all platforms.
-
-The @code{Library_Dir} attribute has a string value that designates the path
-(absolute or relative) of the directory where the library will reside.
-It must designate an existing directory. When the project is not externally
-built, this directory must be writable, different from the project's object
-directory and from any source directory in the project tree.
-
-If both @code{Library_Name} and @code{Library_Dir} are specified and
-are legal, then the project file defines a library project. The optional
-library-related attributes are checked only for such project files.
-
-The @code{Library_Kind} attribute has a string value that must be one of the
-following (case insensitive): @code{"static"}, @code{"dynamic"} or
-@code{"relocatable"} (which is a synonym for @code{"dynamic"}). If this
-attribute is not specified, the library is a static library, that is
-an archive of object files that can be potentially linked into a
-static executable. Otherwise, the library may be dynamic or
-relocatable, that is a library that is loaded only at the start of execution.
-
-If you need to build both a static and a dynamic library, you should use two
-different object directories, since in some cases some extra code needs to
-be generated for the latter. For such cases, it is recommended to either use
-two different project files, or a single one which uses external variables
-to indicate what kind of library should be build.
-
-The @code{Library_ALI_Dir} attribute may be specified to indicate the
-directory where the ALI files of the library will be copied. When it is
-not specified, the ALI files are copied to the directory specified in
-attribute @code{Library_Dir}. Except when the project is externally built, the
-directory specified by @code{Library_ALI_Dir} must be writable and different
-from the project's object directory and from any source directory in the
-project tree.
-
-The @code{Library_Version} attribute has a string value whose interpretation
-is platform dependent. It has no effect on VMS and Windows. On Unix, it is
-used only for dynamic/relocatable libraries as the internal name of the
-library (the @code{"soname"}). If the library file name (built from the
-@code{Library_Name}) is different from the @code{Library_Version}, then the
-library file will be a symbolic link to the actual file whose name will be
-@code{Library_Version}.
-
-Example (on Unix):
-
-@smallexample @c projectfile
-@group
-project Plib is
-
- Version := "1";
-
- for Library_Dir use "lib_dir";
- for Library_Name use "dummy";
- for Library_Kind use "relocatable";
- for Library_Version use "libdummy.so." & Version;
-
-end Plib;
-@end group
-@end smallexample
-
-@noindent
-Directory @file{lib_dir} will contain the internal library file whose name
-will be @file{libdummy.so.1}, and @file{libdummy.so} will be a symbolic link to
-@file{libdummy.so.1}.
-
-When @command{gnatmake} detects that a project file
-is a library project file, it will check all immediate sources of the project
-and rebuild the library if any of the sources have been recompiled.
-
-Standard project files can import library project files. In such cases,
-the libraries will only be rebuilt if some of its sources are recompiled
-because they are in the closure of some other source in an importing project.
-Sources of the library project files that are not in such a closure will
-not be checked, unless the full library is checked, because one of its sources
-needs to be recompiled.
-
-For instance, assume the project file @code{A} imports the library project file
-@code{L}. The immediate sources of A are @file{a1.adb}, @file{a2.ads} and
-@file{a2.adb}. The immediate sources of L are @file{l1.ads}, @file{l1.adb},
-@file{l2.ads}, @file{l2.adb}.
-
-If @file{l1.adb} has been modified, then the library associated with @code{L}
-will be rebuilt when compiling all the immediate sources of @code{A} only
-if @file{a1.ads}, @file{a2.ads} or @file{a2.adb} includes a statement
-@code{"with L1;"}.
-
-To be sure that all the sources in the library associated with @code{L} are
-up to date, and that all the sources of project @code{A} are also up to date,
-the following two commands needs to be used:
-
-@smallexample
-gnatmake -Pl.gpr
-gnatmake -Pa.gpr
-@end smallexample
-
-When a library is built or rebuilt, an attempt is made first to delete all
-files in the library directory.
-All @file{ALI} files will also be copied from the object directory to the
-library directory. To build executables, @command{gnatmake} will use the
-library rather than the individual object files.
-
-@ifclear vms
-It is also possible to create library project files for third-party libraries
-that are precompiled and cannot be compiled locally thanks to the
-@code{externally_built} attribute. (See @ref{Installing a library}).
-@end ifclear
-
-@c *******************************
-@c * Stand-alone Library Projects *
-@c *******************************
-
-@node Stand-alone Library Projects
-@section Stand-alone Library Projects
-
-@noindent
-A Stand-alone Library is a library that contains the necessary code to
-elaborate the Ada units that are included in the library. A Stand-alone
-Library is suitable to be used in an executable when the main is not
-in Ada. However, Stand-alone Libraries may also be used with an Ada main
-subprogram.
-
-A Stand-alone Library Project is a Library Project where the library is
-a Stand-alone Library.
-
-To be a Stand-alone Library Project, in addition to the two attributes
-that make a project a Library Project (@code{Library_Name} and
-@code{Library_Dir}, see @ref{Library Projects}), the attribute
-@code{Library_Interface} must be defined.
-
-@smallexample @c projectfile
-@group
- for Library_Dir use "lib_dir";
- for Library_Name use "dummy";
- for Library_Interface use ("int1", "int1.child");
-@end group
-@end smallexample
-
-Attribute @code{Library_Interface} has a nonempty string list value,
-each string in the list designating a unit contained in an immediate source
-of the project file.
-
-When a Stand-alone Library is built, first the binder is invoked to build
-a package whose name depends on the library name
-(^b~dummy.ads/b^B$DUMMY.ADS/B^ in the example above).
-This binder-generated package includes initialization and
-finalization procedures whose
-names depend on the library name (dummyinit and dummyfinal in the example
-above). The object corresponding to this package is included in the library.
-
-A dynamic or relocatable Stand-alone Library is automatically initialized
-if automatic initialization of Stand-alone Libraries is supported on the
-platform and if attribute @code{Library_Auto_Init} is not specified or
-is specified with the value "true". A static Stand-alone Library is never
-automatically initialized.
-
-Single string attribute @code{Library_Auto_Init} may be specified with only
-two possible values: "false" or "true" (case-insensitive). Specifying
-"false" for attribute @code{Library_Auto_Init} will prevent automatic
-initialization of dynamic or relocatable libraries.
-
-When a non-automatically initialized Stand-alone Library is used
-in an executable, its initialization procedure must be called before
-any service of the library is used.
-When the main subprogram is in Ada, it may mean that the initialization
-procedure has to be called during elaboration of another package.
-
-For a Stand-Alone Library, only the @file{ALI} files of the Interface Units
-(those that are listed in attribute @code{Library_Interface}) are copied to
-the Library Directory. As a consequence, only the Interface Units may be
-imported from Ada units outside of the library. If other units are imported,
-the binding phase will fail.
-
-When a Stand-Alone Library is bound, the switches that are specified in
-the attribute @code{Default_Switches ("Ada")} in package @code{Binder} are
-used in the call to @command{gnatbind}.
-
-The string list attribute @code{Library_Options} may be used to specified
-additional switches to the call to @command{gcc} to link the library.
-
-The attribute @code{Library_Src_Dir}, may be specified for a
-Stand-Alone Library. @code{Library_Src_Dir} is a simple attribute that has a
-single string value. Its value must be the path (absolute or relative to the
-project directory) of an existing directory. This directory cannot be the
-object directory or one of the source directories, but it can be the same as
-the library directory. The sources of the Interface
-Units of the library, necessary to an Ada client of the library, will be
-copied to the designated directory, called Interface Copy directory.
-These sources includes the specs of the Interface Units, but they may also
-include bodies and subunits, when pragmas @code{Inline} or @code{Inline_Always}
-are used, or when there is a generic units in the spec. Before the sources
-are copied to the Interface Copy directory, an attempt is made to delete all
-files in the Interface Copy directory.
-
-@c *************************************
-@c * Switches Related to Project Files *
-@c *************************************
-@node Switches Related to Project Files
-@section Switches Related to Project Files
-
-@noindent
-The following switches are used by GNAT tools that support project files:
-
-@table @option
-
-@item ^-P^/PROJECT_FILE=^@var{project}
-@cindex @option{^-P^/PROJECT_FILE^} (any project-aware tool)
-Indicates the name of a project file. This project file will be parsed with
-the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}},
-if any, and using the external references indicated
-by @option{^-X^/EXTERNAL_REFERENCE^} switches, if any.
-@ifclear vms
-There may zero, one or more spaces between @option{-P} and @var{project}.
-@end ifclear
-
-@noindent
-There must be only one @option{^-P^/PROJECT_FILE^} switch on the command line.
-
-@noindent
-Since the Project Manager parses the project file only after all the switches
-on the command line are checked, the order of the switches
-@option{^-P^/PROJECT_FILE^},
-@option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}}
-or @option{^-X^/EXTERNAL_REFERENCE^} is not significant.
-
-@item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
-@cindex @option{^-X^/EXTERNAL_REFERENCE^} (any project-aware tool)
-Indicates that external variable @var{name} has the value @var{value}.
-The Project Manager will use this value for occurrences of
-@code{external(name)} when parsing the project file.
-
-@ifclear vms
-@noindent
-If @var{name} or @var{value} includes a space, then @var{name=value} should be
-put between quotes.
-@smallexample
- -XOS=NT
- -X"user=John Doe"
-@end smallexample
-@end ifclear
-
-@noindent
-Several @option{^-X^/EXTERNAL_REFERENCE^} switches can be used simultaneously.
-If several @option{^-X^/EXTERNAL_REFERENCE^} switches specify the same
-@var{name}, only the last one is used.
-
-@noindent
-An external variable specified with a @option{^-X^/EXTERNAL_REFERENCE^} switch
-takes precedence over the value of the same name in the environment.
-
-@item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
-@cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (any project-aware tool)
-Indicates the verbosity of the parsing of GNAT project files.
-
-@ifclear vms
-@option{-vP0} means Default;
-@option{-vP1} means Medium;
-@option{-vP2} means High.
-@end ifclear
-
-@ifset vms
-There are three possible options for this qualifier: DEFAULT, MEDIUM and
-HIGH.
-@end ifset
-
-@noindent
-The default is ^Default^DEFAULT^: no output for syntactically correct
-project files.
-@noindent
-If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present,
-only the last one is used.
-
-@item ^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir>
-@cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool)
-Add directory <dir> at the beginning of the project search path, in order,
-after the current working directory.
-
-@ifclear vms
-@item -eL
-@cindex @option{-eL} (any project-aware tool)
-Follow all symbolic links when processing project files.
-@end ifclear
-
-@item ^--subdirs^/SUBDIRS^=<subdir>
-@cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean)
-This switch is recognized by gnatmake and gnatclean. It indicate that the real
-directories (except the source directories) are the subdirectories <subdir>
-of the directories specified in the project files. This applies in particular
-to object directories, library directories and exec directories. If the
-subdirectories do not exist, they are created automatically.
-
-@end table
-
-@c **********************************
-@c * Tools Supporting Project Files *
-@c **********************************
-
-@node Tools Supporting Project Files
-@section Tools Supporting Project Files
-
-@menu
-* gnatmake and Project Files::
-* The GNAT Driver and Project Files::
-@end menu
-
-@node gnatmake and Project Files
-@subsection gnatmake and Project Files
-
-@noindent
-This section covers several topics related to @command{gnatmake} and
-project files: defining ^switches^switches^ for @command{gnatmake}
-and for the tools that it invokes; specifying configuration pragmas;
-the use of the @code{Main} attribute; building and rebuilding library project
-files.
-
-@menu
-* ^Switches^Switches^ and Project Files::
-* Specifying Configuration Pragmas::
-* Project Files and Main Subprograms::
-* Library Project Files::
-@end menu
-
-@node ^Switches^Switches^ and Project Files
-@subsubsection ^Switches^Switches^ and Project Files
-
-@ifset vms
-It is not currently possible to specify VMS style qualifiers in the project
-files; only Unix style ^switches^switches^ may be specified.
-@end ifset
-
-@noindent
-For each of the packages @code{Builder}, @code{Compiler}, @code{Binder}, and
-@code{Linker}, you can specify a @code{^Default_Switches^Default_Switches^}
-attribute, a @code{^Switches^Switches^} attribute, or both;
-as their names imply, these ^switch^switch^-related
-attributes affect the ^switches^switches^ that are used for each of these GNAT
-components when
-@command{gnatmake} is invoked. As will be explained below, these
-component-specific ^switches^switches^ precede
-the ^switches^switches^ provided on the @command{gnatmake} command line.
-
-The @code{^Default_Switches^Default_Switches^} attribute is an associative
-array indexed by language name (case insensitive) whose value is a string list.
-For example:
-
-@smallexample @c projectfile
-@group
-package Compiler is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-gnaty^-gnaty^",
- "^-v^-v^");
-end Compiler;
-@end group
-@end smallexample
-
-@noindent
-The @code{^Switches^Switches^} attribute is also an associative array,
-indexed by a file name (which may or may not be case sensitive, depending
-on the operating system) whose value is a string list. For example:
-
-@smallexample @c projectfile
-@group
-package Builder is
- for ^Switches^Switches^ ("main1.adb")
- use ("^-O2^-O2^");
- for ^Switches^Switches^ ("main2.adb")
- use ("^-g^-g^");
-end Builder;
-@end group
-@end smallexample
-
-@noindent
-For the @code{Builder} package, the file names must designate source files
-for main subprograms. For the @code{Binder} and @code{Linker} packages, the
-file names must designate @file{ALI} or source files for main subprograms.
-In each case just the file name without an explicit extension is acceptable.
-
-For each tool used in a program build (@command{gnatmake}, the compiler, the
-binder, and the linker), the corresponding package @dfn{contributes} a set of
-^switches^switches^ for each file on which the tool is invoked, based on the
-^switch^switch^-related attributes defined in the package.
-In particular, the ^switches^switches^
-that each of these packages contributes for a given file @var{f} comprise:
-
-@itemize @bullet
-@item
-the value of attribute @code{^Switches^Switches^ (@var{f})},
-if it is specified in the package for the given file,
-@item
-otherwise, the value of @code{^Default_Switches^Default_Switches^ ("Ada")},
-if it is specified in the package.
-@end itemize
-
-@noindent
-If neither of these attributes is defined in the package, then the package does
-not contribute any ^switches^switches^ for the given file.
-
-When @command{gnatmake} is invoked on a file, the ^switches^switches^ comprise
-two sets, in the following order: those contributed for the file
-by the @code{Builder} package;
-and the switches passed on the command line.
-
-When @command{gnatmake} invokes a tool (compiler, binder, linker) on a file,
-the ^switches^switches^ passed to the tool comprise three sets,
-in the following order:
-
-@enumerate
-@item
-the applicable ^switches^switches^ contributed for the file
-by the @code{Builder} package in the project file supplied on the command line;
-
-@item
-those contributed for the file by the package (in the relevant project file --
-see below) corresponding to the tool; and
-
-@item
-the applicable switches passed on the command line.
-@end enumerate
-
-@noindent
-The term @emph{applicable ^switches^switches^} reflects the fact that
-@command{gnatmake} ^switches^switches^ may or may not be passed to individual
-tools, depending on the individual ^switch^switch^.
-
-@command{gnatmake} may invoke the compiler on source files from different
-projects. The Project Manager will use the appropriate project file to
-determine the @code{Compiler} package for each source file being compiled.
-Likewise for the @code{Binder} and @code{Linker} packages.
-
-As an example, consider the following package in a project file:
-
-@smallexample @c projectfile
-@group
-project Proj1 is
- package Compiler is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-g^-g^");
- for ^Switches^Switches^ ("a.adb")
- use ("^-O1^-O1^");
- for ^Switches^Switches^ ("b.adb")
- use ("^-O2^-O2^",
- "^-gnaty^-gnaty^");
- end Compiler;
-end Proj1;
-@end group
-@end smallexample
-
-@noindent
-If @command{gnatmake} is invoked with this project file, and it needs to
-compile, say, the files @file{a.adb}, @file{b.adb}, and @file{c.adb}, then
-@file{a.adb} will be compiled with the ^switch^switch^
-@option{^-O1^-O1^},
-@file{b.adb} with ^switches^switches^
-@option{^-O2^-O2^}
-and @option{^-gnaty^-gnaty^},
-and @file{c.adb} with @option{^-g^-g^}.
-
-The following example illustrates the ordering of the ^switches^switches^
-contributed by different packages:
-
-@smallexample @c projectfile
-@group
-project Proj2 is
- package Builder is
- for ^Switches^Switches^ ("main.adb")
- use ("^-g^-g^",
- "^-O1^-)1^",
- "^-f^-f^");
- end Builder;
-@end group
-
-@group
- package Compiler is
- for ^Switches^Switches^ ("main.adb")
- use ("^-O2^-O2^");
- end Compiler;
-end Proj2;
-@end group
-@end smallexample
-
-@noindent
-If you issue the command:
-
-@smallexample
- gnatmake ^-Pproj2^/PROJECT_FILE=PROJ2^ -O0 main
-@end smallexample
-
-@noindent
-then the compiler will be invoked on @file{main.adb} with the following
-sequence of ^switches^switches^
-
-@smallexample
- ^-g -O1 -O2 -O0^-g -O1 -O2 -O0^
-@end smallexample
-
-with the last @option{^-O^-O^}
-^switch^switch^ having precedence over the earlier ones;
-several other ^switches^switches^
-(such as @option{^-c^-c^}) are added implicitly.
-
-The ^switches^switches^
-@option{^-g^-g^}
-and @option{^-O1^-O1^} are contributed by package
-@code{Builder}, @option{^-O2^-O2^} is contributed
-by the package @code{Compiler}
-and @option{^-O0^-O0^} comes from the command line.
-
-The @option{^-g^-g^}
-^switch^switch^ will also be passed in the invocation of
-@command{Gnatlink.}
-
-A final example illustrates switch contributions from packages in different
-project files:
-
-@smallexample @c projectfile
-@group
-project Proj3 is
- for Source_Files use ("pack.ads", "pack.adb");
- package Compiler is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-gnata^-gnata^");
- end Compiler;
-end Proj3;
-@end group
-
-@group
-with "Proj3";
-project Proj4 is
- for Source_Files use ("foo_main.adb", "bar_main.adb");
- package Builder is
- for ^Switches^Switches^ ("foo_main.adb")
- use ("^-s^-s^",
- "^-g^-g^");
- end Builder;
-end Proj4;
-@end group
-
-@group
-with Pack;
-procedure Foo_Main is
- @dots{}
-end Foo_Main;
-@end group
-@end smallexample
-
-If the command is
-@smallexample
-gnatmake ^-PProj4^/PROJECT_FILE=PROJ4^ foo_main.adb -cargs -gnato
-@end smallexample
-
-@noindent
-then the ^switches^switches^ passed to the compiler for @file{foo_main.adb} are
-@option{^-g^-g^} (contributed by the package @code{Proj4.Builder}) and
-@option{^-gnato^-gnato^} (passed on the command line).
-When the imported package @code{Pack} is compiled, the ^switches^switches^ used
-are @option{^-g^-g^} from @code{Proj4.Builder},
-@option{^-gnata^-gnata^} (contributed from package @code{Proj3.Compiler},
-and @option{^-gnato^-gnato^} from the command line.
-
-@noindent
-When using @command{gnatmake} with project files, some ^switches^switches^ or
-arguments may be expressed as relative paths. As the working directory where
-compilation occurs may change, these relative paths are converted to absolute
-paths. For the ^switches^switches^ found in a project file, the relative paths
-are relative to the project file directory, for the switches on the command
-line, they are relative to the directory where @command{gnatmake} is invoked.
-The ^switches^switches^ for which this occurs are:
-^-I^-I^,
-^-A^-A^,
-^-L^-L^,
-^-aO^-aO^,
-^-aL^-aL^,
-^-aI^-aI^, as well as all arguments that are not switches (arguments to
-^switch^switch^
-^-o^-o^, object files specified in package @code{Linker} or after
--largs on the command line). The exception to this rule is the ^switch^switch^
-^--RTS=^--RTS=^ for which a relative path argument is never converted.
-
-@node Specifying Configuration Pragmas
-@subsubsection Specifying Configuration Pragmas
-
-When using @command{gnatmake} with project files, if there exists a file
-@file{gnat.adc} that contains configuration pragmas, this file will be
-ignored.
-
-Configuration pragmas can be defined by means of the following attributes in
-project files: @code{Global_Configuration_Pragmas} in package @code{Builder}
-and @code{Local_Configuration_Pragmas} in package @code{Compiler}.
-
-Both these attributes are single string attributes. Their values is the path
-name of a file containing configuration pragmas. If a path name is relative,
-then it is relative to the project directory of the project file where the
-attribute is defined.
-
-When compiling a source, the configuration pragmas used are, in order,
-those listed in the file designated by attribute
-@code{Global_Configuration_Pragmas} in package @code{Builder} of the main
-project file, if it is specified, and those listed in the file designated by
-attribute @code{Local_Configuration_Pragmas} in package @code{Compiler} of
-the project file of the source, if it exists.
-
-@node Project Files and Main Subprograms
-@subsubsection Project Files and Main Subprograms
-
-@noindent
-When using a project file, you can invoke @command{gnatmake}
-with one or several main subprograms, by specifying their source files on the
-command line.
-
-@smallexample
- gnatmake ^-P^/PROJECT_FILE=^prj main1 main2 main3
-@end smallexample
-
-@noindent
-Each of these needs to be a source file of the same project, except
-when the switch ^-u^/UNIQUE^ is used.
-
-@noindent
-When ^-u^/UNIQUE^ is not used, all the mains need to be sources of the
-same project, one of the project in the tree rooted at the project specified
-on the command line. The package @code{Builder} of this common project, the
-"main project" is the one that is considered by @command{gnatmake}.
-
-@noindent
-When ^-u^/UNIQUE^ is used, the specified source files may be in projects
-imported directly or indirectly by the project specified on the command line.
-Note that if such a source file is not part of the project specified on the
-command line, the ^switches^switches^ found in package @code{Builder} of the
-project specified on the command line, if any, that are transmitted
-to the compiler will still be used, not those found in the project file of
-the source file.
-
-@noindent
-When using a project file, you can also invoke @command{gnatmake} without
-explicitly specifying any main, and the effect depends on whether you have
-defined the @code{Main} attribute. This attribute has a string list value,
-where each element in the list is the name of a source file (the file
-extension is optional) that contains a unit that can be a main subprogram.
-
-If the @code{Main} attribute is defined in a project file as a non-empty
-string list and the switch @option{^-u^/UNIQUE^} is not used on the command
-line, then invoking @command{gnatmake} with this project file but without any
-main on the command line is equivalent to invoking @command{gnatmake} with all
-the file names in the @code{Main} attribute on the command line.
-
-Example:
-@smallexample @c projectfile
-@group
- project Prj is
- for Main use ("main1", "main2", "main3");
- end Prj;
-@end group
-@end smallexample
-
-@noindent
-With this project file, @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^"}
-is equivalent to
-@code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1 main2 main3"}.
-
-When the project attribute @code{Main} is not specified, or is specified
-as an empty string list, or when the switch @option{-u} is used on the command
-line, then invoking @command{gnatmake} with no main on the command line will
-result in all immediate sources of the project file being checked, and
-potentially recompiled. Depending on the presence of the switch @option{-u},
-sources from other project files on which the immediate sources of the main
-project file depend are also checked and potentially recompiled. In other
-words, the @option{-u} switch is applied to all of the immediate sources of the
-main project file.
-
-When no main is specified on the command line and attribute @code{Main} exists
-and includes several mains, or when several mains are specified on the
-command line, the default ^switches^switches^ in package @code{Builder} will
-be used for all mains, even if there are specific ^switches^switches^
-specified for one or several mains.
-
-But the ^switches^switches^ from package @code{Binder} or @code{Linker} will be
-the specific ^switches^switches^ for each main, if they are specified.
-
-@node Library Project Files
-@subsubsection Library Project Files
-
-@noindent
-When @command{gnatmake} is invoked with a main project file that is a library
-project file, it is not allowed to specify one or more mains on the command
-line.
-
-@noindent
-When a library project file is specified, switches ^-b^/ACTION=BIND^ and
-^-l^/ACTION=LINK^ have special meanings.
-
-@itemize @bullet
-@item ^-b^/ACTION=BIND^ is only allowed for stand-alone libraries. It indicates
-to @command{gnatmake} that @command{gnatbind} should be invoked for the
-library.
-
-@item ^-l^/ACTION=LINK^ may be used for all library projects. It indicates
-to @command{gnatmake} that the binder generated file should be compiled
-(in the case of a stand-alone library) and that the library should be built.
-
-@end itemize
-
-@node The GNAT Driver and Project Files
-@subsection The GNAT Driver and Project Files
-
-@noindent
-A number of GNAT tools, other than @command{^gnatmake^gnatmake^}
-can benefit from project files:
-(@command{^gnatbind^gnatbind^},
-@command{^gnatcheck^gnatcheck^},
-@command{^gnatclean^gnatclean^},
-@command{^gnatelim^gnatelim^},
-@command{^gnatfind^gnatfind^},
-@command{^gnatlink^gnatlink^},
-@command{^gnatls^gnatls^},
-@command{^gnatmetric^gnatmetric^},
-@command{^gnatpp^gnatpp^},
-@command{^gnatstub^gnatstub^},
-and @command{^gnatxref^gnatxref^}). However, none of these tools can be invoked
-directly with a project file switch (@option{^-P^/PROJECT_FILE=^}).
-They must be invoked through the @command{gnat} driver.
-
-The @command{gnat} driver is a wrapper that accepts a number of commands and
-calls the corresponding tool. It was designed initially for VMS platforms (to
-convert VMS qualifiers to Unix-style switches), but it is now available on all
-GNAT platforms.
-
-On non-VMS platforms, the @command{gnat} driver accepts the following commands
-(case insensitive):
-
-@itemize @bullet
-@item
-BIND to invoke @command{^gnatbind^gnatbind^}
-@item
-CHOP to invoke @command{^gnatchop^gnatchop^}
-@item
-CLEAN to invoke @command{^gnatclean^gnatclean^}
-@item
-COMP or COMPILE to invoke the compiler
-@item
-ELIM to invoke @command{^gnatelim^gnatelim^}
-@item
-FIND to invoke @command{^gnatfind^gnatfind^}
-@item
-KR or KRUNCH to invoke @command{^gnatkr^gnatkr^}
-@item
-LINK to invoke @command{^gnatlink^gnatlink^}
-@item
-LS or LIST to invoke @command{^gnatls^gnatls^}
-@item
-MAKE to invoke @command{^gnatmake^gnatmake^}
-@item
-NAME to invoke @command{^gnatname^gnatname^}
-@item
-PREP or PREPROCESS to invoke @command{^gnatprep^gnatprep^}
-@item
-PP or PRETTY to invoke @command{^gnatpp^gnatpp^}
-@item
-METRIC to invoke @command{^gnatmetric^gnatmetric^}
-@item
-STUB to invoke @command{^gnatstub^gnatstub^}
-@item
-XREF to invoke @command{^gnatxref^gnatxref^}
-@end itemize
-
-@noindent
-(note that the compiler is invoked using the command
-@command{^gnatmake -f -u -c^gnatmake -f -u -c^}).
-
-@noindent
-On non-VMS platforms, between @command{gnat} and the command, two
-special switches may be used:
-
-@itemize @bullet
-@item
-@command{-v} to display the invocation of the tool.
-@item
-@command{-dn} to prevent the @command{gnat} driver from removing
-the temporary files it has created. These temporary files are
-configuration files and temporary file list files.
-@end itemize
-
-@noindent
-The command may be followed by switches and arguments for the invoked
-tool.
-
-@smallexample
- gnat bind -C main.ali
- gnat ls -a main
- gnat chop foo.txt
-@end smallexample
-
-@noindent
-Switches may also be put in text files, one switch per line, and the text
-files may be specified with their path name preceded by '@@'.
-
-@smallexample
- gnat bind @@args.txt main.ali
-@end smallexample
-
-@noindent
-In addition, for commands BIND, COMP or COMPILE, FIND, ELIM, LS or LIST, LINK,
-METRIC, PP or PRETTY, STUB and XREF, the project file related switches
-(@option{^-P^/PROJECT_FILE^},
-@option{^-X^/EXTERNAL_REFERENCE^} and
-@option{^-vP^/MESSAGES_PROJECT_FILE=^x}) may be used in addition to
-the switches of the invoking tool.
-
-@noindent
-When GNAT PP or GNAT PRETTY is used with a project file, but with no source
-specified on the command line, it invokes @command{^gnatpp^gnatpp^} with all
-the immediate sources of the specified project file.
-
-@noindent
-When GNAT METRIC is used with a project file, but with no source
-specified on the command line, it invokes @command{^gnatmetric^gnatmetric^}
-with all the immediate sources of the specified project file and with
-@option{^-d^/DIRECTORY^} with the parameter pointing to the object directory
-of the project.
-
-@noindent
-In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with
-a project file, no source is specified on the command line and
-switch ^-U^/ALL_PROJECTS^ is specified on the command line, then
-the underlying tool (^gnatpp^gnatpp^ or
-^gnatmetric^gnatmetric^) is invoked for all sources of all projects,
-not only for the immediate sources of the main project.
-@ifclear vms
-(-U stands for Universal or Union of the project files of the project tree)
-@end ifclear
-
-@noindent
-For each of the following commands, there is optionally a corresponding
-package in the main project.
-
-@itemize @bullet
-@item
-package @code{Binder} for command BIND (invoking @code{^gnatbind^gnatbind^})
-
-@item
-package @code{Check} for command CHECK (invoking
-@code{^gnatcheck^gnatcheck^})
-
-@item
-package @code{Compiler} for command COMP or COMPILE (invoking the compiler)
-
-@item
-package @code{Cross_Reference} for command XREF (invoking
-@code{^gnatxref^gnatxref^})
-
-@item
-package @code{Eliminate} for command ELIM (invoking
-@code{^gnatelim^gnatelim^})
-
-@item
-package @code{Finder} for command FIND (invoking @code{^gnatfind^gnatfind^})
-
-@item
-package @code{Gnatls} for command LS or LIST (invoking @code{^gnatls^gnatls^})
-
-@item
-package @code{Gnatstub} for command STUB
-(invoking @code{^gnatstub^gnatstub^})
-
-@item
-package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^})
-
-@item
-package @code{Check} for command CHECK
-(invoking @code{^gnatcheck^gnatcheck^})
-
-@item
-package @code{Metrics} for command METRIC
-(invoking @code{^gnatmetric^gnatmetric^})
-
-@item
-package @code{Pretty_Printer} for command PP or PRETTY
-(invoking @code{^gnatpp^gnatpp^})
-
-@end itemize
-
-@noindent
-Package @code{Gnatls} has a unique attribute @code{^Switches^Switches^},
-a simple variable with a string list value. It contains ^switches^switches^
-for the invocation of @code{^gnatls^gnatls^}.
-
-@smallexample @c projectfile
-@group
-project Proj1 is
- package gnatls is
- for ^Switches^Switches^
- use ("^-a^-a^",
- "^-v^-v^");
- end gnatls;
-end Proj1;
-@end group
-@end smallexample
-
-@noindent
-All other packages have two attribute @code{^Switches^Switches^} and
-@code{^Default_Switches^Default_Switches^}.
-
-@noindent
-@code{^Switches^Switches^} is an associative array attribute, indexed by the
-source file name, that has a string list value: the ^switches^switches^ to be
-used when the tool corresponding to the package is invoked for the specific
-source file.
-
-@noindent
-@code{^Default_Switches^Default_Switches^} is an associative array attribute,
-indexed by the programming language that has a string list value.
-@code{^Default_Switches^Default_Switches^ ("Ada")} contains the
-^switches^switches^ for the invocation of the tool corresponding
-to the package, except if a specific @code{^Switches^Switches^} attribute
-is specified for the source file.
-
-@smallexample @c projectfile
-@group
-project Proj is
-
- for Source_Dirs use ("./**");
-
- package gnatls is
- for ^Switches^Switches^ use
- ("^-a^-a^",
- "^-v^-v^");
- end gnatls;
-@end group
-@group
-
- package Compiler is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-gnatv^-gnatv^",
- "^-gnatwa^-gnatwa^");
- end Binder;
-@end group
-@group
-
- package Binder is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-C^-C^",
- "^-e^-e^");
- end Binder;
-@end group
-@group
-
- package Linker is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-C^-C^");
- for ^Switches^Switches^ ("main.adb")
- use ("^-C^-C^",
- "^-v^-v^",
- "^-v^-v^");
- end Linker;
-@end group
-@group
-
- package Finder is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-a^-a^",
- "^-f^-f^");
- end Finder;
-@end group
-@group
-
- package Cross_Reference is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-a^-a^",
- "^-f^-f^",
- "^-d^-d^",
- "^-u^-u^");
- end Cross_Reference;
-end Proj;
-@end group
-@end smallexample
-
-@noindent
-With the above project file, commands such as
-
-@smallexample
- ^gnat comp -Pproj main^GNAT COMP /PROJECT_FILE=PROJ MAIN^
- ^gnat ls -Pproj main^GNAT LIST /PROJECT_FILE=PROJ MAIN^
- ^gnat xref -Pproj main^GNAT XREF /PROJECT_FILE=PROJ MAIN^
- ^gnat bind -Pproj main.ali^GNAT BIND /PROJECT_FILE=PROJ MAIN.ALI^
- ^gnat link -Pproj main.ali^GNAT LINK /PROJECT_FILE=PROJ MAIN.ALI^
-@end smallexample
-
-@noindent
-will set up the environment properly and invoke the tool with the switches
-found in the package corresponding to the tool:
-@code{^Default_Switches^Default_Switches^ ("Ada")} for all tools,
-except @code{^Switches^Switches^ ("main.adb")}
-for @code{^gnatlink^gnatlink^}.
-It is also possible to invoke some of the tools,
-(@code{^gnatcheck^gnatcheck^},
-@code{^gnatmetric^gnatmetric^},
-and @code{^gnatpp^gnatpp^})
-on a set of project units thanks to the combination of the switches
-@option{-P}, @option{-U} and possibly the main unit when one is interested
-in its closure. For instance,
-@smallexample
-gnat metric -Pproj
-@end smallexample
-will compute the metrics for all the immediate units of project
-@code{proj}.
-@smallexample
-gnat metric -Pproj -U
-@end smallexample
-will compute the metrics for all the units of the closure of projects
-rooted at @code{proj}.
-@smallexample
-gnat metric -Pproj -U main_unit
-@end smallexample
-will compute the metrics for the closure of units rooted at
-@code{main_unit}. This last possibility relies implicitly
-on @command{gnatbind}'s option @option{-R}. But if the argument files for the
-tool invoked by the the @command{gnat} driver are explicitly specified
-either directly or through the tool @option{-files} option, then the tool
-is called only for these explicitly specified files.
-
-@c **********************
-@node An Extended Example
-@section An Extended Example
-
-@noindent
-Suppose that we have two programs, @var{prog1} and @var{prog2},
-whose sources are in corresponding directories. We would like
-to build them with a single @command{gnatmake} command, and we want to place
-their object files into @file{build} subdirectories of the source directories.
-Furthermore, we want to have to have two separate subdirectories
-in @file{build} -- @file{release} and @file{debug} -- which will contain
-the object files compiled with different set of compilation flags.
-
-In other words, we have the following structure:
-
-@smallexample
-@group
- main
- |- prog1
- | |- build
- | | debug
- | | release
- |- prog2
- |- build
- | debug
- | release
-@end group
-@end smallexample
-
-@noindent
-Here are the project files that we must place in a directory @file{main}
-to maintain this structure:
-
-@enumerate
-
-@item We create a @code{Common} project with a package @code{Compiler} that
-specifies the compilation ^switches^switches^:
-
-@smallexample
-File "common.gpr":
-@group
-@b{project} Common @b{is}
-
- @b{for} Source_Dirs @b{use} (); -- No source files
-@end group
-
-@group
- @b{type} Build_Type @b{is} ("release", "debug");
- Build : Build_Type := External ("BUILD", "debug");
-@end group
-@group
- @b{package} Compiler @b{is}
- @b{case} Build @b{is}
- @b{when} "release" =>
- @b{for} ^Default_Switches^Default_Switches^ ("Ada")
- @b{use} ("^-O2^-O2^");
- @b{when} "debug" =>
- @b{for} ^Default_Switches^Default_Switches^ ("Ada")
- @b{use} ("^-g^-g^");
- @b{end case};
- @b{end} Compiler;
-
-@b{end} Common;
-@end group
-@end smallexample
-
-@item We create separate projects for the two programs:
-
-@smallexample
-@group
-File "prog1.gpr":
-
-@b{with} "common";
-@b{project} Prog1 @b{is}
-
- @b{for} Source_Dirs @b{use} ("prog1");
- @b{for} Object_Dir @b{use} "prog1/build/" & Common.Build;
-
- @b{package} Compiler @b{renames} Common.Compiler;
-
-@b{end} Prog1;
-@end group
-@end smallexample
-
-@smallexample
-@group
-File "prog2.gpr":
-
-@b{with} "common";
-@b{project} Prog2 @b{is}
-
- @b{for} Source_Dirs @b{use} ("prog2");
- @b{for} Object_Dir @b{use} "prog2/build/" & Common.Build;
-
- @b{package} Compiler @b{renames} Common.Compiler;
-
-@end group
-@b{end} Prog2;
-@end smallexample
-
-@item We create a wrapping project @code{Main}:
-
-@smallexample
-@group
-File "main.gpr":
-
-@b{with} "common";
-@b{with} "prog1";
-@b{with} "prog2";
-@b{project} Main @b{is}
-
- @b{package} Compiler @b{renames} Common.Compiler;
-
-@b{end} Main;
-@end group
-@end smallexample
-
-@item Finally we need to create a dummy procedure that @code{with}s (either
-explicitly or implicitly) all the sources of our two programs.
-
-@end enumerate
-
-@noindent
-Now we can build the programs using the command
-
-@smallexample
- gnatmake ^-P^/PROJECT_FILE=^main dummy
-@end smallexample
-
-@noindent
-for the Debug mode, or
-
-@ifclear vms
-@smallexample
- gnatmake -Pmain -XBUILD=release
-@end smallexample
-@end ifclear
-
-@ifset vms
-@smallexample
- GNAT MAKE /PROJECT_FILE=main /EXTERNAL_REFERENCE=BUILD=release
-@end smallexample
-@end ifset
-
-@noindent
-for the Release mode.
-
-@c ********************************
-@c * Project File Complete Syntax *
-@c ********************************
-
-@node Project File Complete Syntax
-@section Project File Complete Syntax
-
-@smallexample
-project ::=
- context_clause project_declaration
-
-context_clause ::=
- @{with_clause@}
-
-with_clause ::=
- @b{with} path_name @{ , path_name @} ;
-
-path_name ::=
- string_literal
-
-project_declaration ::=
- simple_project_declaration | project_extension
-
-simple_project_declaration ::=
- @b{project} <project_>simple_name @b{is}
- @{declarative_item@}
- @b{end} <project_>simple_name;
-
-project_extension ::=
- @b{project} <project_>simple_name @b{extends} path_name @b{is}
- @{declarative_item@}
- @b{end} <project_>simple_name;
-
-declarative_item ::=
- package_declaration |
- typed_string_declaration |
- other_declarative_item
-
-package_declaration ::=
- package_spec | package_renaming
-
-package_spec ::=
- @b{package} package_identifier @b{is}
- @{simple_declarative_item@}
- @b{end} package_identifier ;
-
-package_identifier ::=
- @code{Naming} | @code{Builder} | @code{Compiler} | @code{Binder} |
- @code{Linker} | @code{Finder} | @code{Cross_Reference} |
- @code{^gnatls^gnatls^} | @code{IDE} | @code{Pretty_Printer}
-
-package_renaming ::==
- @b{package} package_identifier @b{renames}
- <project_>simple_name.package_identifier ;
-
-typed_string_declaration ::=
- @b{type} <typed_string_>_simple_name @b{is}
- ( string_literal @{, string_literal@} );
-
-other_declarative_item ::=
- attribute_declaration |
- typed_variable_declaration |
- variable_declaration |
- case_construction
-
-attribute_declaration ::=
- full_associative_array_declaration |
- @b{for} attribute_designator @b{use} expression ;
-
-full_associative_array_declaration ::=
- @b{for} <associative_array_attribute_>simple_name @b{use}
- <project_>simple_name [ . <package_>simple_Name ] ' <attribute_>simple_name ;
-
-attribute_designator ::=
- <simple_attribute_>simple_name |
- <associative_array_attribute_>simple_name ( string_literal )
-
-typed_variable_declaration ::=
- <typed_variable_>simple_name : <typed_string_>name := string_expression ;
-
-variable_declaration ::=
- <variable_>simple_name := expression;
-
-expression ::=
- term @{& term@}
-
-term ::=
- literal_string |
- string_list |
- <variable_>name |
- external_value |
- attribute_reference
-
-string_literal ::=
- (same as Ada)
-
-string_list ::=
- ( <string_>expression @{ , <string_>expression @} )
-
-external_value ::=
- @b{external} ( string_literal [, string_literal] )
-
-attribute_reference ::=
- attribute_prefix ' <simple_attribute_>simple_name [ ( literal_string ) ]
-
-attribute_prefix ::=
- @b{project} |
- <project_>simple_name | package_identifier |
- <project_>simple_name . package_identifier
-
-case_construction ::=
- @b{case} <typed_variable_>name @b{is}
- @{case_item@}
- @b{end case} ;
-
-case_item ::=
- @b{when} discrete_choice_list =>
- @{case_construction | attribute_declaration@}
-
-discrete_choice_list ::=
- string_literal @{| string_literal@} |
- @b{others}
-
-name ::=
- simple_name @{. simple_name@}
-
-simple_name ::=
- identifier (same as Ada)
-
-@end smallexample
-
-@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
===================================================================
@@ -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
+<div class="tip">
+@end html
+\TXT\
+@html
+</div>
+@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
+<div class="tip">
+@end html
+\TXT\
+@html
+</div>
+@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
+<div class="important">
+@end html
+\TXT\
+@html
+</div>
+@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
+<div class="note">
+@end html
+\TXT\
+@html
+</div>
+@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
+<div class="side"><a href="#Index">
+@end html
+\TXT\
+@html
+</a></div>
+@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{<project_>}name @i{is}
+ @{declarative_item@}
+ @i{end} <project_>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{<package_>}simple_name @i{is}
+ @{simple_declarative_item@}
+ @i{end} package_identifier ;
+package_renaming ::==
+ @i{package} @i{<package_>}simple_name @i{renames} @i{<project_>}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{<typed_string_>}_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{<typed_variable_>}simple_name : @i{<typed_string_>}name := string_expression;
+variable_declaration ::= @i{<variable_>}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{<indexed_attribute_>}simple_name ( string_literal) @i{use} expression ;
+attribute_designator ::=
+ @i{<simple_attribute_>}simple_name
+ | @i{<indexed_attribute_>}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_attribute>_}simple_name [ (string_literal) ]
+attribute_prefix ::= @i{project}
+ | @i{<project_>}simple_name
+ | package_identifier
+ | @i{<project_>}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{<typed_variable_>}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=^<dir>
+@CINDEX{@option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool)}
+Add directory <dir> at the beginning of the project search path, in order,
+after the current working directory.
+
+@ifclear vms
+@item -eL
+@CINDEX{@option{-eL} (any project-aware tool)}
+Follow all symbolic links when processing project files.
+@end ifclear
+
+@item ^--subdirs^/SUBDIRS^=<subdir>
+@CINDEX{@option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean)}
+This switch is recognized by gnatmake and gnatclean. It indicate that the real
+directories (except the source directories) are the subdirectories <subdir>
+of the directories specified in the project files. This applies in particular
+to object directories, library directories and exec directories. If the
+subdirectories do not exist, they are created automatically.
+
+@end table
+
+@c ---------------------------------------------
+@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=<main config project file name>} : Specify the
+ configuration project file name
+
+@item @option{--autoconf=<config project file name>}
+
+ 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<proj>} : Use Project File @emph{<proj>}.
+
+@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
+
+
+