11.7.1 Project Declaration

Project files have an Ada-like syntax. The minimal project file is:

     project Empty is
     end Empty;

The identifier Empty is the name of the project. This project name must be present after the reserved word end at the end of the project file, followed by a semi-colon.

Identifiers (i.e. 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").

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

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

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: all, at, case, end, for, is, limited, null, others, package, renames, type, use, when, with, extends, external, project.

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 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 with clauses, or by 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 limited with.

     with "other_project.gpr";
     project My_Project extends "extended.gpr" is
     end My_Project;

These dependencies form a directed graph, potentially cyclic when using limited with. The subprogram reflecting the extends relations is a tree.

A project's 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 project hierarchy can be created, where projects are children of other projects. The name of such a child project must be Parent.Child, where Parent is the name of the parent project. In particular, this makes all with clauses of the parent project automatically visible in the child project.

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