13. Project File Reference

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. See the chapter on project files in the GNAT Users guide for examples of use.

13.1 Reserved Words
13.2 Lexical Elements
13.3 Declarations
13.4 Empty declarations
13.5 Typed string declarations
13.6 Variables
13.7 Expressions
13.8 Attributes
13.9 Project Attributes
13.10 Attribute References
13.11 External Values
13.12 Case Construction
13.13 Packages
13.14 Package Renamings
13.15 Projects
13.16 Project Extensions
13.17 Project File Elaboration

13.1 Reserved Words

All Ada95 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:

• extends

• external

• project

13.2 Lexical Elements

Rules for identifiers are the same as in Ada95. Identifiers are case-insensitive. Strings are case sensitive, except where noted. Comments have the same form as in Ada95.

Syntax:

simple_name ::= identifier name ::= simple_name {. simple_name}

13.3 Declarations

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:

declarative_item ::= simple_declarative_item | typed_string_declaration | package_declaration simple_declarative_item ::= variable_declaration | typed_variable_declaration | attribute_declaration | case_construction | empty_declaration

13.4 Empty declarations

empty_declaration ::= null ;

An empty declaration is allowed anywhere a declaration is allowed. It has no effect.

13.5 Typed string declarations

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:

typed_string_declaration ::= type <typed_string_>_simple_name is ( string_literal {, string_literal} );

A typed string declaration can only appear immediately within a project declaration.

All the string literals in a typed string declaration must be distinct.

13.6 Variables

Variables denote values, and appear as constituents of expressions.

typed_variable_declaration ::= <typed_variable_>simple_name : <typed_string_>name := string_expression ; variable_declaration ::= <variable_>simple_name := expression;

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.

A typed_variable can only be declare once.

a non typed variable can be declared multiple times.

Before the completion of its first declaration, the value of variable is the null string.

13.7 Expressions

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:

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 } )

13.7.1 Concatenation

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;

13.8 Attributes

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:

attribute_declaration ::= full_associative_array_declaration | for attribute_designator use expression ; full_associative_array_declaration ::= for <associative_array_attribute_>simple_name use <project_>simple_name [ . <package_>simple_Name ] ' <attribute_>simple_name ; attribute_designator ::= <simple_attribute_>simple_name | <associative_array_attribute_>simple_name ( string_literal )

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.

13.9 Project Attributes

The following attributes apply to a project. All of them are simple attributes.

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.

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.

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.

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.

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

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.

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.

Library_Kind

Argument must be a string value that must be one of the following "static", "dynamic" or "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.

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 "soname"). If the library file name (built from the Library_Name) is different from the Library_Version, then the library file will be a symbolic link to the actual file whose name will be Library_Version.

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.

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.

Library_Options

Expression must be a string list. Indicates additional switches that are to be used when building a shared library.

Library_GCC

Expression must be a single string. Designates an alternative to "gcc" for building shared libraries.

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, and must be writable.

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.

Main_Language

This is a simple attribute. Its value is a string that specifies the language of the main program.

Languages

Expression must be a string list. Each string designates a programming language that is known to GNAT. The strings are case-insensitive.

Locally_Removed_Files

This attribute is legal only in a project file that extends another. Expression must be a list of strings that are legal file names. Each file name must designate a source that would normally be 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.

13.10 Attribute References

Attribute references are used to retrieve the value of previously defined attribute for a package or project. Syntax:

attribute_reference ::= attribute_prefix ' <simple_attribute_>simple_name [ ( string_literal ) ] attribute_prefix ::= project | <project_simple_name | package_identifier | <project_>simple_name . package_identifier

If an attribute has not been specified for a given package or project, its value is the null string or the empty list.

13.11 External Values

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:

external_value ::= external ( string_literal [, string_literal] )

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.

13.12 Case Construction

A case construction supports attribute declarations that depend on the value of a previously declared variable.

Syntax:

case_construction ::= case <typed_variable_>name is {case_item} end case ; case_item ::= when discrete_choice_list => {case_construction | attribute_declaration | empty_declaration} discrete_choice_list ::= string_literal {| string_literal} | others

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 others choice must appear last in the list of alternatives.

13.13 Packages

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:

package_declaration ::= package_specification | package_renaming package_specification ::= package package_identifier is {simple_declarative_item} end package_identifier ; package_identifier ::= Naming | Builder | Compiler | Binder | Linker | Finder | Cross_Reference | gnatls | IDE | Pretty_Printer

13.13.1 Package Naming

The attributes of a 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 Naming package:

Casing

This is a simple attribute whose value is a string. Legal values of this string are "lowercase", "uppercase" or "mixedcase". These strings are themselves case insensitive.

If Casing is not specified, then the default is "lowercase".

Dot_Replacement

This is a simple attribute whose string value satisfies the following requirements:

• It must not be empty
• It cannot start or end with an alphanumeric character
• It cannot be a single underscore
• It cannot start with an underscore followed by an alphanumeric
• It cannot contain a dot '.' if longer than one character

If Dot_Replacement is not specified, then the default is "-".

Spec_Suffix

This is an associative array attribute, defined on language names, whose image is a string that must satisfy the following conditions:

• It must not be empty
• It cannot start with an alphanumeric character
• It cannot start with an underscore followed by an alphanumeric character

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 Spec_Suffix ("Ada") is not specified, then the default is ".ads".

For C and C++, the attribute denotes the suffix used in file names that contain prototypes.

Body_Suffix

This is an associative array attribute defined on language names, whose image is a string that must satisfy the following conditions:

• It must not be empty
• It cannot start with an alphanumeric character
• It cannot start with an underscore followed by an alphanumeric character
• It cannot be a suffix of Spec_Suffix

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 Body_Suffix ("Ada") is not specified, then the default is ".adb".

For C and C++, the attribute denotes the suffix used in file names that contain source code.

Separate_Suffix

This is a simple attribute whose value satisfies the same conditions as 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 Body_Suffix ("Ada").

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.

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.

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 Spec_Suffix for the language.

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 Body_Suffix for the language.

The following attributes of package Naming are obsolescent. They are kept as synonyms of other attributes for compatibility with previous versions of the Project Manager.

Specification_Suffix

This is a synonym of Spec_Suffix.

Implementation_Suffix

This is a synonym of Body_Suffix.

Specification

This is a synonym of Spec.

Implementation

This is a synonym of Body.

13.13.2 package Compiler

The attributes of the Compiler package specify the compilation options to be used by the underlying compiler.

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..

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 settings specified by Default_Switches.

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.

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.

13.13.3 package Builder

The attributes of package Builder specify the compilation, binding, and linking options to be used when building an executable for a project. The following attributes apply to package Builder:

Default_Switches

As above.

Switches

As above.

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.

Executable

This is an associative array attribute, defined over compilation unit names. The image is a string that is the name of the executable file corresponding to the main source file index. This attribute has no effect if its value is the empty string.

Executable_Suffix

This is a simple attribute whose value is a suffix to be added to the executables that don't have an attribute Executable specified.

13.13.4 package Gnatls

The attributes of package Gnatls specify the tool options to be used when invoking the library browser gnatls. The following attributes apply to package Gnatls:

Switches

As above.

13.13.5 package Binder

The attributes of package Binder specify the options to be used when invoking the binder in the construction of an executable. The following attributes apply to package Binder:

Default_Switches

As above.

Switches

As above.

13.13.6 package Linker

The attributes of package Linker specify the options to be used when invoking the linker in the construction of an executable. The following attributes apply to package Linker:

Default_Switches

As above

Switches

As above.

13.13.7 package Cross_Reference

The attributes of package Cross_Reference specify the tool options to be used when invoking the library tool gnatxref. The following attributes apply to package Cross_Reference:

Default_Switches

As above.

Switches

As above.

13.13.8 package Finder

The attributes of package Finder specify the tool options to be used when invoking the search tool gnatfind. The following attributes apply to package Finder:

Default_Switches

As above.

Switches

As above.

13.13.9 package Pretty_Printer

The attributes of package Pretty_Printer specify the tool options to be used when invoking the formatting tool gnatpp. The following attributes apply to package Pretty_Printer:

Default_switches

As above.

Switches

As above.

13.13.10 package IDE

The attributes of package IDE specify the options to be used when using an Integrated Development Environment such as GPS.

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.

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.

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. "wtx" or "vxworks".

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 Compiler_Command ("Ada") is expected to be compatible with gnatmake, in particular in the handling of switches.

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.

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.

Gnatlist

This is a simple attribute. Its value is a string that specifies the name of the gnatls utility to be used to retrieve information about the predefined path; e.g., "gnatls", "powerpc-wrs-vxworks-gnatls".

VCS_Kind

This is a simple atribute. Is 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.

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.

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.

13.14 Package Renamings

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:

package_renaming ::== package package_identifier renames <project_>simple_name.package_identifier ;

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.

13.15 Projects

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:

project ::= context_clause project_declaration project_declaration ::= simple_project_declaration | project_extension simple_project_declaration ::= project <project_>simple_name is {declarative_item} end <project_>simple_name; context_clause ::= {with_clause} with_clause ::= [limited] with path_name { , path_name } ; path_name ::= string_literal

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 limited with.

13.16 Project Extensions

A project extension introduces a new project, which inherits the declarations of another project. Syntax:

project_extension ::= project <project_>simple_name extends path_name is {declarative_item} end <project_>simple_name;

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.

13.17 Project File Elaboration

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.