10.1.1 Project Files

A project is a specific set of values for these properties. You can define a project's settings in a project file, a text file with an Ada-like syntax; a property value is either a string or a list of strings. Properties that are not explicitly set receive default values. A project file may interrogate the values of 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. ("Dependence" is in the technical sense; for example, one Ada unit "with"ing another.) However, the Project Manager also allows much more sophisticated arrangements, with the source files in one project depending on source files in other projects:

• One project can import other projects containing needed source files.
• 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

More generally, the Project Manager lets you structure large development efforts into hierarchical subsystems, with build decisions deferred to the subsystem level and thus different compilation environments (switch settings) used for different subsystems.

The Project Manager is invoked through the -Pprojectfile switch to gnatmake or to the gnat front driver. If you want to define (on the command line) an external variable that is queried by the project file, additionally use the -Xvbl=value switch. The Project Manager parses and interprets the project file, and drives the invoked tool based on the project settings.

The Project Manager supports a wide range of development strategies, for systems of all sizes. Some typical practices that are easily handled:

• Using a common set of source files, but generating object files in different directories via different switch settings
• Using a mostly-shared set of source files, but with different versions of some unit or units

The destination of an executable can be controlled inside a project file using the -o switch. In the absence of such a switch either inside the project file or on the command line, any executable files generated by gnatmake will be placed in the directory Exec_Dir specified in the project file. If no 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.