A "GNAT project" is a specific set of values specifying compilation properties, including the switches to be applied, the source files, their directories, their file naming scheme, the name of the executable, and many other aspects.
A GNAT project is described by one or more "project files", text files that contain specifications for the properties to be set. Project files can be used individually but can also be arranged into hierarchical subsystems, where build decisions are delegated to the subsystem level, and thus different compilation environments (switch settings) can be used for different subsystems.
Project files can be used on the command line and in scripts (e.g., makefiles). Using project files considerably simplifies command line and script usage because some or all of the switches are specified by the project file and, therefore, need not be written as explicit tool invocation arguments.
The settings specified by a project file become effective when using the GNAT Project Manager. The Project Manager interprets the content of the project file and applies all the corresponding settings when the tools are invoked.
The Ada Project Explorer is oriented around GNAT projects and displays their sources accordingly. The source files or a project are made available for editing and it is these Ada source files that the Builder will build into an executable.
Because GNAT Project Files and the GNAT Project Manager control what is displayed to the user as well as what and how executables are built, they form the conceptual foundation for development using GNATbench and should be understood by the user.
See the GNAT Native User's Guide, section 11 "GNAT Project Manager", for full details on the Project Manager and project files.
Project file are text files written in a syntax close to that of Ada, using familiar notions such as packages, context clauses, declarations, default values, assignments, and inheritance.
Packages within project files correspond to individual tools and are thus defined not by the user but by AdaCore. For example, there is a package Compiler, a package Naming_Scheme, a package Builder, and so forth. Users set the values of switches for a given tool by defining the property settings within the corresponding package. Global properties may also be defined within a project file, for example the name of the directory to contain all intermediate build products (object files and .ali files).
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 "external variables" (user-defined command-line switches or environment variables), and it may specify property settings conditionally, based on the value of such variables.
Users have available both a GUI interface and a syntax-driven text editor to specify the property values within project files. The following figure shows a simple project file inside the editor (see the corresponding Help files for the details of the GUI and this syntax-driven editor). In this case all defaults are taken for the tools and only global properties are defined. Specifically, the file name of the main subprogram is specified, the executable is directed to the same directory containing the project file itself, and all intermediate products are directed to a directory named "objs" located immediately underneath the directory containing the project file.
The Project Manager is invoked along with a specific tool and applies the properties of a project file to that tool. The specific project file to be applied is specified by the "-P" argument when the tool invoked.
For example, suppose we want to invoke the "gnatmake" tool to do a complete build of everything necessary to generate an executable for some main subprogram. If the project file "myproject.gpr" specifies the name of the main subprogram file, all we have to do is invoke gnatmake with the -P switch and specify the name of that project file:
gnatmake -P myproject.gpr
GNATbench will apply the -P switch for you when the builder is invoked, specifying automatically the project file that corresponds to the Ada project to be built. You can see the application of the -P switch when watching the build output in the Builder Console.