2.1.1. GNAT Projects

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 (if any), 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 Project Explorer project presentation 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 User’s Guide, section 11 “GNAT Project Manager”, for full details of the Project Manager and project files.

2.1.2. Foreign Ada Source Files

A file containing Ada source code must be part of a GNATbench project in order for the relevant capabilities of GNATbench to function properly. For example, navigation based on the Ada constructs within the file cannot succeed if the file is not part of a GNATbench project.

Being “part of a GNATbench project” means that it is located in a “source directory”, i.e., one specified, directly or indirectly, in the Source_Dirs attribute of a project managed by GNATbench. All other Ada source files are “foreign” and will not be processed by GNATbench, except for the most basic of functions. Foreign files are not included in a project build, for example, and navigation and cross referencing for such files will also fail to operate properly.

Foreign files are an issue because there are ways within Eclipse to open arbitrary files, including files containing Ada source code, located either inside or outside the Eclipse workspace. Although the Ada editor will be opened for such a file, and will be able to function somewhat for editing, other functionality will fail.

When such files are intended to be part of GNATbench they should be located in a source directory specified in the Source_Dirs attribute of an existing GNATbench project. There are various ways to do so, including importing the containing folder from the file system via the “Import...” wizard and then ensuring it is in the list of directories in the Source_Dirs attribute. Alternatively, you can import an entire external GNAT (not GNATbench) project into Eclipse, so that it becomes a GNATbench project too. You could even simply copy the file to an existing source directory, but one way or the other, the directory containing the file in question must be a “source directory.”

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

project file editor example

Project hierarchies are formed when the so-called “root” project file imports other GNAT project files via “with clauses”, as illustrated in the first line of the following project file:

project file with-clauses example

2.1.4. GNAT Project Manager

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.