GNAT Project Manager
********************

Introduction
============

This chapter describes GNAT's Project Manager, a facility that allows you to manage complex builds involving a number of source files, directories, and options for different system configurations. In particular, project files allow you to specify:

  * The directory or set of directories containing the source files, and/or the names of the specific source files themselves

  * The directory in which the compiler's output (ALI files, object files, tree files, etc.) is to be placed

  * The directory in which the executable programs are to be placed

  * Switch settings for any of the project-enabled tools; you can apply these settings either globally or to individual compilation units.

  * The source files containing the main subprogram(s) to be built

  * The source programming language(s)

  * Source file naming conventions; you can specify these either globally or for individual compilation units (see Naming Schemes).

  * Change any of the above settings depending on external values, thus enabling the reuse of the projects in various scenarios (see Scenarios in Projects).

  * Automatically build libraries as part of the build process (see Library Projects).

Project files are written in a syntax close to that of Ada, using familiar notions such as packages, context clauses, declarations, default values, assignments, and inheritance (see Project File Reference).

Project files can be built hierarchically from other project files, simplifying complex system integration and project reuse (see Organizing Projects into Subsystems).

  * One project can import other projects containing needed source files. More generally, the Project Manager lets you structure large development efforts into hierarchical subsystems, where build decisions are delegated to the subsystem level, and thus different compilation environments (switch settings) used for different subsystems.

  * 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 (see Project Extension).

Several tools support project files, generally in addition to specifying the information on the command line itself). They share common switches to control the loading of the project (in particular ^-P^/PROJECT_FILE=^projectfile and ^-X^/EXTERNAL_REFERENCE=^vbl=value). See Switches Related to Project Files.

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

  * Using a common set of source files and generating object files in different directories via different switch settings. It can be used for instance, for generating separate sets of object files for debugging and for production.

  * Using a mostly-shared set of source files with different versions of some units or subunits. It can be used for instance, for grouping and hiding

all OS dependencies in a small number of implementation units.

Project files can be used 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 tool that might be used by the developers.

The various sections below introduce the different concepts related to projects. Each section starts with examples and use cases, and then goes into the details of related project file capabilities.

Building With Projects
======================

In its simplest form, a unique project is used to build a single executable. This section concentrates on such a simple setup. Later sections will extend this basic model to more complex setups.

The following concepts are the foundation of project files, and will be further detailed later in this documentation. They are summarized here as a reference.

Project file:
     A text file using an Ada-like syntax, generally using the .gpr extension. It defines build-related characteristics of an application. The characteristics include the list of sources, the location of those sources, the location for the generated object files, the name of the main program, and the options for the various tools involved in the build process.

Project attribute:
     A specific project characteristic is defined by an attribute clause. Its value is a string or a sequence of strings. All settings in a project are defined through a list of predefined attributes with precise semantics. See Attributes.

Package in a project:
     Global attributes are defined at the top level of a project. Attributes affecting specific tools are grouped in a package whose name is related to tool's function. The most common packages are Builder, Compiler, Binder, and Linker. See Packages.

Project variables:
     In addition to attributes, a project can use variables to store intermediate values and avoid duplication in complex expressions. It can be initialized with a value coming from the environment. A frequent use of variables is to define scenarios. See External Values, see Scenarios in Projects, and see Variables.

Source files and source directories:
     A source file is associated with a language through a naming convention. For instance, foo.c is typically the name of a C source file; bar.ads or bar.1.ada are two common naming conventions for a file containing an Ada spec. A compilation unit is often composed of a main source file and potentially several auxiliary ones, such as header files in C. The naming conventions can be user defined see Naming Schemes, and will drive the builder to call the appropriate compiler for the given source file. Source files are searched for in the source directories associated with the project through the Source_Dirs attribute. By default, all the files (in these source directories) following the naming conventions associated with the declared languages are considered to be part of the project. It is also possible to limit the list of source files using the Source_Files or Source_List_File attributes. Note that those last two attributes only accept basenames with no directory information.

Object files and object directory:
     An object file is an intermediate file produced by the compiler from a compilation unit. It is used by post-compilation tools to produce final executables or libraries. Object files produced in the context of a given project are stored in a single directory that can be specified by the Object_Dir attribute. In order to store objects in two or more object directories, the system must be split into distinct subsystems with their own project file.

The following subsections introduce gradually all the attributes of interest for simple build needs. Here is the simple setup that will be used in the following examples.

The Ada source files pack.ads, pack.adb, and proc.adb are in the common/ directory. The file proc.adb contains an Ada main subprogram Proc that withs package Pack. We want to compile these source files with the switch -O2, and put the resulting files in the directory obj/.

     ^common/^[COMMON]^
       pack.ads
       pack.adb
       proc.adb

     ^common/release/^[COMMON.RELEASE]^
       proc.ali, proc.o pack.ali, pack.o

Our project is to be called Build. The name of the file is the name of the project (case-insensitive) with the .gpr extension, therefore the project file name is build.gpr. This is not mandatory, but a warning is issued when this convention is not followed.

This is a very simple example, and as stated above, a single project file is enough for it. We will thus create a new file, that for now should contain the following code:

     project Build is
     end Build;

Source Files and Directories
----------------------------

When you create a new project, the first thing to describe is how to find the corresponding source files. This is the only settings that are needed by all the tools that will use this project (builder, compiler, binder and linker for the compilation, IDEs to edit the source files,...).

First step is to declare the source directories, which are the directories to be searched to find source files. In the case of the example, the common directory is the only source directory.

There are several ways of defining source directories:

  * When the attribute Source_Dirs is not used, a project contains a single source directory which is the one where the project file itself resides. In our example, if build.gpr is placed in the common directory, the project has the needed implicit source directory.

  * The attribute Source_Dirs can be set to a list of path names, one for each of the source directories. Such paths can either be absolute names (for instance "/usr/local/common/" on UNIX), or relative to the directory in which the project file resides (for instance "." if build.gpr is inside common/, or "common" if it is one level up). Each of the source directories must exist and be readable.

     The syntax for directories is platform specific. For portability, however, the project manager will always properly translate UNIX-like path names to the native format of specific platform. For instance, when the same project file is to be used both on Unix and Windows, "/" should be used as the directory separator rather than "\".

  * The attribute Source_Dirs can automatically include subdirectories using a special syntax inspired by some UNIX shells. If any of the path in the list ends with "**", then that path and all its subdirectories (recursively) are included in the list of source directories. For instance, ** and ./** represent the complete directory tree rooted at ".".

     When using that construct, it can sometimes be convenient to also use the attribute Excluded_Source_Dirs, which is also a list of paths. Each entry specifies a directory whose immediate content, not including subdirs, is to be excluded. It is also possible to exclude a complete directory subtree using the "**" notation.

     It is often desirable to remove, from the source directories, directory subtrees rooted at some subdirectories. An example is the subdirectories created by a Version Control System such as Subversion that creates directory subtrees .svn/**. To do that, attribute  Ignore_Source_Sub_Dirs can be used. It specifies the list of simple file names for the root of these undesirable directory subtrees.

When applied to the simple example, and because we generally prefer to have the project file at the toplevel directory rather than mixed with the sources, we will create the following file

        build.gpr
        project Build is
           for Source_Dirs use ("common");  --  <<<<
        end Build;

Once source directories have been specified, one may need to indicate source files of interest. By default, all source files present in the source directories are considered by the project manager. When this is not desired, it is possible to specify the list of sources to consider explicitly. In such a case, only source file base names are indicated and not their absolute or relative path names. The project manager is in charge of locating the specified source files in the specified source directories.

  * By default, the project manager  search for all source files of all specified languages in all the source directories.

     Since the project manager was initially developed for Ada environments, the default language is usually Ada and the above project file is complete: it defines without ambiguity the sources composing the project: that is to say, all the sources in subdirectory "common" for the default language (Ada) using the default naming convention.

     However, when compiling a multi-language application, or a pure C application, the project manager must be told which languages are of interest, which is done by setting the Languages attribute to a list of strings, each of which is the name of a language. Tools like gnatmake only know about Ada, while other tools like gprbuild know about many more languages such as C, C++, Fortran, assembly and others can be added dynamically.

     Even when using only Ada, the default naming might not be suitable. Indeed, how does the project manager recognizes an "Ada file" from any other file? Project files can describe the naming scheme used for source files, and override the default (see Naming Schemes). The default is the standard GNAT extension (.adb for bodies and .ads for specs), which is what is used in our example, explaining why no naming scheme is explicitly specified. See Naming Schemes.

  * Source Files In some cases, source directories might contain files that should not be included in a project. One can specify the explicit list of file names to be considered through the Source_Files attribute. When this attribute is defined, instead of looking at every file in the source directories, the project manager takes only those names into consideration  reports  errors if they cannot be found in the source directories or does not correspond to the naming scheme.

  * For various reasons, it is sometimes useful to have a project with no sources (most of the time because the attributes defined in the project file will be reused in other projects, as explained in see Organizing Projects into Subsystems. To do this, the attribute Source_Files is set to the empty list, i.e. (). Alternatively, Source_Dirs can be set to the empty list, with the same result.

  * Source_List_File If there is a great number of files, it might be more convenient to use the attribute Source_List_File, which specifies the full path of a file. This file must contain a list of source file names (one per line, no directory information) that are searched as if they had been defined through Source_Files. Such a file can easily be created through external tools.

     A warning is issued if both attributes Source_Files and Source_List_File are given explicit values. In this case, the attribute Source_Files prevails.

  * Excluded_Source_Files Specifying an explicit list of files is not always convenient.It might be more convenient to use the default search rules with specific exceptions. This can be done thanks to the attribute Excluded_Source_Files (or its synonym Locally_Removed_Files). Its value is the list of file names that should not be taken into account. This attribute is often used when extending a project, see Project Extension. A similar attribute Excluded_Source_List_File plays the same role but takes the name of file containing file names similarly to Source_List_File.

In most simple cases, such as the above example, the default source file search behavior provides the expected result, and we do not need to add anything after setting Source_Dirs. The project manager automatically finds pack.ads, pack.adb and proc.adb as source files of the project.

Note that it is considered an error for a project file to have no sources attached to it unless explicitly declared as mentioned above.

If the order of the source directories is known statically, that is if "**" is not used in the string list Source_Dirs, then there may be several files with the same source file name sitting in different directories of the project. In this case, only the file in the first directory is considered as a source of the project and the others are hidden. If "**" is not used in the string list Source_Dirs, it is an error to have several files with the same source file name in the same directory "**" subtree, since there would be an ambiguity as to which one should be used. However, two files with the same source file name may in two single directories or directory subtrees. In this case, the one in the first directory or directory subtree is a source of the project.

Object and Exec Directory
-------------------------

The next step when writing a project is to indicate where the compiler should put the object files. In fact, the compiler and other tools might create several different kind of files (for GNAT, there is the object file and the ALI file for instance). One of the important concepts in projects is that most tools may consider source directories as read-only and do not attempt to create new or temporary files there. Instead, all files are created in the object directory. It is of course not true for project-aware IDEs, whose purpose it is to create the source files.

The object directory is specified through the Object_Dir attribute. Its value is the path to the object directory, either absolute or relative to the directory containing the project file. This directory must already exist and be readable and writable, although some tools have a switch to create the directory if needed (See the switch -p for gnatmake and gprbuild).

If the attribute Object_Dir is not specified, it defaults to the project directory, that is the directory containing the project file.

For our example, we can specify the object dir in this way:

        project Build is
           for Source_Dirs use ("common");
           for Object_Dir use "obj";   --  <<<<
        end Build;

As mentioned earlier, there is a single object directory per project. As a result, if you have an existing system where the object files are spread in several directories, you can either move all of them into the same directory if you want to build it with a single project file, or study the section on subsystems (see Organizing Projects into Subsystems) to see how each separate object directory can be associated with one of the subsystem constituting the application.

When the linker is called, it usually creates an executable. By default, this executable is placed in the object directory of the project. It might be convenient to store it in its own directory.

This can be done through the Exec_Dir attribute, which, like Object_Dir contains a single absolute or relative path and must point to an existing and writable directory, unless you ask the tool to create it on your behalf. When not specified, It defaults to the object directory and therefore to the project file's directory if neither Object_Dir nor Exec_Dir was specified.

In the case of the example, let's place the executable in the root of the hierarchy, ie the same directory as build.gpr. Hence the project file is now

        project Build is
           for Source_Dirs use ("common");
           for Object_Dir use "obj";
           for Exec_Dir use ".";  --   <<<<
        end Build;

Main Subprograms
----------------

In the previous section, executables were mentioned. The project manager needs to be taught what they are. In a project file, an executable is indicated by pointing to source file of the main subprogram. In C this is the file that contains the main function, and in Ada the file that contains the main unit.

There can be any number of such main files within a given project, and thus several executables can be built in the context of a single project file. Of course, one given executable might not (and in fact will not) need all the source files referenced by the project. As opposed to other build environments such as makefile, one does not need to specify the list of dependencies of each executable, the project-aware builders knows enough of the semantics of the languages to build ands link only the necessary elements.

The list of main files is specified via the Main attribute. It contains a list of file names (no directories). If a project defines this attribute, it is not necessary to identify  main files on the command line when invoking a builder, and editors like GPS will be able to create extra menus to spawn or debug the corresponding executables.

        project Build is
           for Source_Dirs use ("common");
           for Object_Dir use "obj";
           for Exec_Dir use ".";
           for Main use ("proc.adb");  --   <<<<
        end Build;

If this attribute is defined in the project, then spawning the builder with a command such as

        gnatmake ^-Pbuild^/PROJECT_FILE=build^

automatically builds all the executables corresponding to the files listed in the Main attribute. It is possible to specify one or more executables on the command line to build a subset of them.

Tools Options in Project Files
------------------------------

We now have a project file that fully describes our environment, and can be used to build the application with a simple gnatmake command as seen in the previous section. In fact, the empty project we showed immediately at the beginning (with no attribute at all) could already fulfill that need if it was put in the common directory.

Of course, we always want more control. This section will show you how to specify the compilation switches that the various tools involved in the building of the executable should use.

Since source names and locations are described into the project file, it is not necessary to use switches on the command line for this purpose (switches such as -I for gcc). This removes a major source of command line length overflow. Clearly, the builders will have to communicate this information one way or another to the underlying compilers and tools they call but they usually use response files for this and thus should not be subject to command line overflows.

Several tools are participating to the creation of an executable: the compiler produces object files from the source files; the binder (in the Ada case) creates an source file that takes care, among other things, of elaboration issues and global variables initialization; and the linker gathers everything into a single executable that users can execute. All these tools are known by the project manager and will be called with user defined switches from the project files. However, we need to introduce a new project file concept to express which switches to be used for any of the tools involved in the build.

A project file is subdivided into zero or more packages, each of which contains the attributes specific to one tool (or one set of tools). Project files use an Ada-like syntax for packages. Package names permitted in project files are restricted to a predefined set (see Packages), and the contents of packages are limited to a small set of constructs and attributes (see Attributes).

Our example project file can be extended with the following empty packages. At this stage, they could all be omitted since they are empty, but they show which packages would be involved in the build process.

        project Build is
           for Source_Dirs use ("common");
           for Object_Dir use "obj";
           for Exec_Dir use ".";
           for Main use ("proc.adb");
        end Build;

        package Builder is  --<<<  for gnatmake and gprbuild
        end Builder;

        package Compiler is --<<<  for the compiler
        end Compiler;

        package Binder is   --<<<  for the binder
        end Binder;

        package Linker is   --<<<  for the linker
        end Linker;

Let's first examine the compiler switches. As stated in the initial description of the example, we want to compile all files with -O2. This is a compiler switch, although it is usual, on the command line, to pass it to the builder which then passes it to the compiler. It is recommended to use directly the right package, which will make the setup easier to understand for other people.

Several attributes can be used to specify the switches:

Default_Switches:
     This is the first mention in this manual of an indexed attribute. When this attribute is defined, one must supply an index in the form of a literal string. In the case of Default_Switches, the index is the name of the language to which the switches apply (since a different compiler will likely be used for each language, and each compiler has its own set of switches). The value of the attribute is a list of switches.

     In this example, we want to compile all Ada source files with the -O2 switch, and the resulting project file is as follows (only the Compiler package is shown):

            package Compiler is
              for Default_Switches ("Ada") use ("-O2");
            end Compiler;

Switches:
     in some cases, we might want to use specific switches for one or more files. For instance, compiling proc.adb might not be possible at high level of optimization because of a compiler issue. In such a case, the Switches attribute (indexed on the file name) can be used and will override the switches defined by Default_Switches. Our project file would become:

            package Compiler is
              for Default_Switches ("Ada") use ("-O2");
              for Switches ("proc.adb") use ("-O0");
            end Compiler;

     Switches may take a pattern as an index, such as in:

            package Compiler is
              for Default_Switches ("Ada") use ("-O2");
              for Switches ("pkg*") use ("-O0");
            end Compiler;

     Sources pkg.adb and pkg-child.adb would be compiled with -O0, not -O2.

     Switches can also be given a language name as index instead of a file name in which case it has the same semantics as Default_Switches. However, indexes with wild cards are never valid for language name.

Local_Configuration_Pragmas:
     this attribute may specify the path of a file containing configuration pragmas for use by the Ada compiler, such as pragma Restrictions (No_Tasking). These pragmas will be used for all the sources of the project.

The switches for the other tools are defined in a similar manner through the Default_Switches and Switches attributes, respectively in the Builder package (for gnatmake and gprbuild), the Binder package (binding Ada executables) and the Linker package (for linking executables).

Compiling with Project Files
----------------------------

Now that our project files are written, let's build our executable. Here is the command we would use from the command line:

        gnatmake ^-Pbuild^/PROJECT_FILE=build^

This will automatically build the executables specified through the Main attribute: for each, it will compile or recompile the sources for which the object file does not exist or is not up-to-date; it will then run the binder; and finally run the linker to create the executable itself.

gnatmake only knows how to handle Ada files. By using gprbuild as a builder, you could automatically manage C files the same way: create the file utils.c in the common directory, set the attribute Languages to "(Ada, C)", and run

        gprbuild ^-Pbuild^/PROJECT_FILE=build^

Gprbuild knows how to recompile the C files and will recompile them only if one of their dependencies has changed. No direct indication on how to build the various elements is given in the project file, which describes the project properties rather than a set of actions to be executed. Here is the invocation of gprbuild when building a multi-language program:

     $ gprbuild -Pbuild
     gcc -c proc.adb
     gcc -c pack.adb
     gcc -c utils.c
     gprbind proc
     ...
     gcc proc.o -o proc

Notice the three steps described earlier:

  * The first three gcc commands correspond to the compilation phase.

  * The gprbind command corresponds to the post-compilation phase.

  * The last gcc command corresponds to the final link.

The default output of GPRbuild's execution is kept reasonably simple and easy to understand. In particular, some of the less frequently used commands are not shown, and some parameters are abbreviated. So it is not possible to rerun the effect of the gprbuild command by cut-and-pasting its output. GPRbuild's option -v provides a much more verbose output which includes, among other information, more complete compilation, post-compilation and link commands.

Executable File Names
---------------------

By default, the executable name corresponding to a main file is computed from the main source file name. Through the attribute Builder.Executable, it is possible to change this default.

For instance, instead of building proc (or proc.exe on Windows), we could configure our project file to build "proc1" (resp proc1.exe) with the following addition:

        project Build is
           ...  --  same as before
           package Builder is
              for Executable ("proc.adb") use "proc1";
           end Builder
        end Build;

Attribute Executable_Suffix, when specified, may change the suffix of the executable files, when no attribute Executable applies: its value replace the platform-specific executable suffix. The default executable suffix is empty on UNIX and ".exe" on Windows.

It is also possible to change the name of the produced executable by using the command line switch -o. When several mains are defined in the project, it is not possible to use the -o switch and the only way to change the names of the executable is provided by Attributes Executable and Executable_Suffix.

Avoid Duplication With Variables
--------------------------------

To illustrate some other project capabilities, here is a slightly more complex project using similar sources and a main program in C:

     project C_Main is
        for Languages    use ("Ada", "C");
        for Source_Dirs  use ("common");
        for Object_Dir   use  "obj";
        for Main         use ("main.c");
        package Compiler is
           C_Switches := ("-pedantic");
           for Default_Switches ("C")   use C_Switches;
           for Default_Switches ("Ada") use ("-gnaty");
           for Switches ("main.c") use C_Switches & ("-g");
        end Compiler;
     end C_Main;

This project has many similarities with the previous one. As expected, its Main attribute now refers to a C source. The attribute Exec_Dir is now omitted, thus the resulting executable will be put in the directory obj.

The most noticeable difference is the use of a variable in the Compiler package to store settings used in several attributes. This avoids text duplication, and eases maintenance (a single place to modify if we want to add new switches for C files). We will revisit the use of variables in the context of scenarios (see Scenarios in Projects).

In this example, we see how the file main.c can be compiled with the switches used for all the other C files, plus -g. In this specific situation the use of a variable could have been replaced by a reference to the Default_Switches attribute:

        for Switches ("c_main.c") use Compiler'Default_Switches ("C") & ("-g");

Note the tick (') used to refer to attributes defined in a package.

Here is the output of the GPRbuild command using this project:

     $gprbuild -Pc_main
     gcc -c -pedantic -g main.c
     gcc -c -gnaty proc.adb
     gcc -c -gnaty pack.adb
     gcc -c -pedantic utils.c
     gprbind main.bexch
     ...
     gcc main.o -o main

The default switches for Ada sources, the default switches for C sources (in the compilation of lib.c), and the specific switches for main.c have all been taken into account.

Naming Schemes
--------------

Sometimes an Ada software system is ported from one compilation environment to another (say GNAT), and the file are not named using the default GNAT conventions. Instead of changing all the file names, which for a variety of reasons might not be possible, you can define the relevant file naming scheme in the Naming package of your project file.

The naming scheme has two distinct goals for the project manager: it allows finding of source files when searching in the source directories, and given a source file name it makes it possible to guess the associated language, and thus the compiler to use.

Note that the use by the Ada compiler of pragmas Source_File_Name is not supported when using project files. You must use the features described in this paragraph. You can however specify other configuration pragmas (see Specifying Configuration Pragmas).

The following attributes can be defined in package Naming:

Casing:
     Its value must be one of "lowercase" (the default if unspecified), "uppercase" or "mixedcase". It describes the casing of file names with regards to the Ada unit name. Given an Ada unit My_Unit, the file name will respectively be my_unit.adb (lowercase), MY_UNIT.ADB (uppercase) or My_Unit.adb (mixedcase). On Windows, file names are case insensitive, so this attribute is irrelevant.

Dot_Replacement:
     This attribute specifies the string that should replace the "." in unit names. Its default value is "-" so that a unit Parent.Child is expected to be found in the file parent-child.adb. The replacement string must satisfy the following requirements to avoid ambiguities in the naming scheme:

       - 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 '.' except if the entire string is "."

Spec_Suffix and Specification_Suffix:
     For Ada, these attributes give the suffix used in file names that contain specifications. For other languages, they give the extension for files that contain declaration (header files in C for instance). The attribute is indexed on the language. The two attributes are equivalent, but the latter is obsolescent. If Spec_Suffix ("Ada") is not specified, then the default is "^.ads^.ADS^". The value must satisfy the following requirements:

       - It must not be empty

       - It cannot start with an alphanumeric character

       - It cannot start with an underscore followed by an alphanumeric character

       - It must include at least one dot

Body_Suffix and Implementation_Suffix:
     These attributes give the extension used for file names that contain code (bodies in Ada). They are indexed on the language. The second version is obsolescent and fully replaced by the first attribute.

     These attributes must satisfy the same requirements as Spec_Suffix. In addition, they must be different from any of the values in Spec_Suffix. If Body_Suffix ("Ada") is not specified, then the default is "^.adb^.ADB^".

     If Body_Suffix ("Ada") and Spec_Suffix ("Ada") end with the same string, then a file name that ends with the longest of these two suffixes will be a body if the longest suffix is Body_Suffix ("Ada") or a spec if the longest suffix is Spec_Suffix ("Ada").

     If the suffix does not start with a '.', a file with a name exactly equal to the suffix will also be part of the project (for instance if you define the suffix as Makefile, a file called Makefile will be part of the project. This capability is usually not interesting  when building. However, it might become useful when a project is also used to find the list of source files in an editor, like the GNAT Programming System (GPS).

Separate_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"). The same rules apply as for the Body_Suffix attribute. The only accepted index is "Ada".

Spec or Specification:
     This attribute Spec can be used to define the source file name for a given Ada compilation unit's spec. The index is the literal name of the Ada unit (case insensitive). The value is the literal base name of the file that contains this unit's spec (case sensitive or insensitive depending on the operating system). This attribute allows the definition of exceptions to the general naming scheme, in case some files do not follow the usual convention.

     When a source file contains several units, the relative position of the unit can be indicated. The first unit in the file is at position 1

             for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
             for Spec ("top") use "foo.a" at 1;
             for Spec ("foo") use "foo.a" at 2;

Body or Implementation:
     These attribute play the same role as Spec for Ada bodies.

Specification_Exceptions and Implementation_Exceptions:
     These attributes define exceptions to the naming scheme for languages other than Ada. They are indexed on the language name, and contain a list of file names respectively for headers and source code.

For example, the following package models the Apex file naming rules:

       package Naming is
         for Casing               use "lowercase";
         for Dot_Replacement      use ".";
         for Spec_Suffix ("Ada")  use ".1.ada";
         for Body_Suffix ("Ada")  use ".2.ada";
       end Naming;

Organizing Projects into Subsystems
===================================

A subsystem is a coherent part of the complete system to be built. It is represented by a set of sources and one single object directory. A system can be composed of a single subsystem when it is simple as we have seen in the first section. Complex systems are usually composed of several interdependent subsystems. A subsystem is dependent on another subsystem if knowledge of the other one is required to build it, and in particular if visibility on some of the sources of this other subsystem is required. Each subsystem is usually represented by its own project file.

In this section, the previous example is being extended. Let's assume some sources of our Build project depend on other sources. For instance, when building a graphical interface, it is usual to depend upon a graphical library toolkit such as GtkAda. Furthermore, we also need sources from a logging module we had previously written.

Project Dependencies
--------------------

GtkAda comes with its own project file (appropriately called gtkada.gpr), and we will assume we have already built a project called logging.gpr for the logging module. With the information provided so far in build.gpr, building the application would fail with an error indicating that the gtkada and logging units that are relied upon by the sources of this project cannot be found.

This is easily solved by adding the following with clauses at the beginning of our project:

       with "gtkada.gpr";
       with "a/b/logging.gpr";
       project Build is
          ...  --  as before
       end Build;

When such a project is compiled, gnatmake will automatically check the other projects and recompile their sources when needed. It will also recompile the sources from Build when needed, and finally create the executable. In some cases, the implementation units needed to recompile a project are not available, or come from some third-party and you do not want to recompile it yourself. In this case, the attribute Externally_Built to "true" can be set, indicating to the builder that this project can be assumed to be up-to-date, and should not be considered for recompilation. In Ada, if the sources of this externally built project were compiled with another version of the compiler or with incompatible options, the binder will issue an error.

The project's with clause has several effects. It provides source visibility between projects during the compilation process. It also guarantees that the necessary object files from Logging and GtkAda are available when linking Build.

As can be seen in this example, the syntax for importing projects is similar to the syntax for importing compilation units in Ada. However, project files use literal strings instead of names, and the with clause identifies project files rather than packages.

Each literal string after with is the path (absolute or relative) to a project file. The .gpr extension is optional, although we recommend adding it. If no extension is specified, and no project file with the ^.gpr^.GPR^ extension is found, then the file is searched for exactly as written in the with clause, that is with no extension.

As mentioned above, the path after a with has to be a literal string, and you cannot use concatenation, or lookup the value of external variables to change the directories from which a project is loaded. A solution if you need something like this is to use aggregate projects (see Aggregate Projects).

When a relative path or a base name is used, the project files are searched relative to each of the directories in the project path. This path includes all the directories found with the following algorithm, in that order, as soon as a matching file is found, the search stops:

  * First, the file is searched relative to the directory that contains the current project file.

  * Then it is searched relative to all the directories specified in the ^environment variables^logical names^ GPR_PROJECT_PATH and ADA_PROJECT_PATH (in that order) if they exist. The former is recommended, the latter is kept for backward compatibility.

  * Finally, it is searched relative to the default project directories. Such directories depends on the tool used. The different locations searched in the specified order are:

       * <prefix>/<target>/lib/gnat (for gnatmake in all cases, and for gprbuild if option --target is specified)

       * <prefix>/share/gpr/ (for gnatmake and gprbuild)

       * <prefix>/lib/gnat/ (for gnatmake and gprbuild)

     In our example, gtkada.gpr is found in the predefined directory if it was installed at the same root as GNAT.

Some tools also support extending the project path from the command line, generally through the -aP. You can see the value of the project path by using the gnatls -v command.

Any symbolic link will be fully resolved in the directory of the importing project file before the imported project file is examined.

Any source file in the imported project can be used by the sources of the importing project, transitively. Thus if A imports B, which imports C, the sources of A may depend on the sources of C, even if A does not import C explicitly. However, this is not recommended, because if and when B ceases to import C, some sources in A will no longer compile. gprbuild has a switch --no-indirect-imports that will report such indirect dependencies.

One very important aspect of a project hierarchy is that a given source can only belong to one project (otherwise the project manager would not know which settings apply to it and when to recompile it). It means that different project files do not usually share source directories or when they do, they need to specify precisely which project owns which sources using attribute Source_Files or equivalent. By contrast, 2 projects can each own a source with the same base file name as long as they live in different directories. The latter is not true for Ada Sources because of the correlation between source files and Ada units.

Cyclic Project Dependencies
---------------------------

Cyclic dependencies are mostly forbidden: if A imports B (directly or indirectly) then B is not allowed to import A. However, there are cases when cyclic dependencies would be beneficial. For these cases, another form of import between projects exists: the limited with.  A project A that imports a project B with a straight with may also be imported, directly or indirectly, by B through a limited with.

The difference between straight with and limited with is that the name of a project imported with a limited with cannot be used in the project importing it. In particular, its packages cannot be renamed and its variables cannot be referred to.

     with "b.gpr";
     with "c.gpr";
     project A is
         For Exec_Dir use B'Exec_Dir; -- ok
     end A;

     limited with "a.gpr";   --  Cyclic dependency: A -> B -> A
     project B is
        For Exec_Dir use A'Exec_Dir; -- not ok
     end B;

     with "d.gpr";
     project C is
     end C;

     limited with "a.gpr";  --  Cyclic dependency: A -> C -> D -> A
     project D is
        For Exec_Dir use A'Exec_Dir; -- not ok
     end D;

Sharing Between Projects
------------------------

When building an application, it is common to have similar needs in several of the projects corresponding to the subsystems under construction. For instance, they will all have the same compilation switches.

As seen before (see Tools Options in Project Files), setting compilation switches for all sources of a subsystem is simple: it is just a matter of adding a Compiler.Default_Switches attribute to each project files with the same value. Of course, that means duplication of data, and both places need to be changed in order to recompile the whole application with different switches. It can become a real problem if there are many subsystems and thus many project files to edit.

There are two main approaches to avoiding this duplication:

  * Since build.gpr imports logging.gpr, we could change it to reference the attribute in Logging, either through a package renaming, or by referencing the attribute. The following example shows both cases:

            project Logging is
               package Compiler is
                  for Switches ("Ada") use ("-O2");
               end Compiler;
               package Binder is
                  for Switches ("Ada") use ("-E");
               end Binder;
            end Logging;

            with "logging.gpr";
            project Build is
               package Compiler renames Logging.Compiler;
               package Binder is
                  for Switches ("Ada") use Logging.Binder'Switches ("Ada");
               end Binder;
            end Build;

     The solution used for Compiler gets the same value for all attributes of the package, but you cannot modify anything from the package (adding extra switches or some exceptions). The second version is more flexible, but more verbose.

     If you need to refer to the value of a variable in an imported project, rather than an attribute, the syntax is similar but uses a "." rather than an apostrophe. For instance:

            with "imported";
            project Main is
               Var1 := Imported.Var;
            end Main;

  * The second approach is to define the switches in a third project. That project is setup without any sources (so that, as opposed to the first example, none of the project plays a special role), and will only be used to define the attributes. Such a project is typically called shared.gpr.

            abstract project Shared is
               for Source_Files use ();   --  no project
               package Compiler is
                  for Switches ("Ada") use ("-O2");
               end Compiler;
            end Shared;

            with "shared.gpr";
            project Logging is
               package Compiler renames Shared.Compiler;
            end Logging;

            with "shared.gpr";
            project Build is
               package Compiler renames Shared.Compiler;
            end Build;

     As for the first example, we could have chosen to set the attributes one by one rather than to rename a package. The reason we explicitly indicate that Shared has no sources is so that it can be created in any directory and we are sure it shares no sources with Build or Logging, which of course would be invalid.

     Note the additional use of the abstract qualifier in shared.gpr. This qualifier is optional, but helps convey the message that we do not intend this project to have sources (see Qualified Projects for more qualifiers).

Global Attributes
-----------------

We have already seen many examples of attributes used to specify a special option of one of the tools involved in the build process. Most of those attributes are project specific. That it to say, they only affect the invocation of tools on the sources of the project where they are defined.

There are a few additional attributes that apply to all projects in a hierarchy as long as they are defined on the "main" project. The main project is the project explicitly mentioned on the command-line. The project hierarchy is the "with"-closure of the main project.

Here is a list of commonly used global attributes:

Builder.Global_Configuration_Pragmas:
     This attribute points to a file that contains configuration pragmas to use when building executables. These pragmas apply for all executables build from this project hierarchy. As we have seen before, additional pragmas can be specified on a per-project basis by setting the Compiler.Local_Configuration_Pragmas attribute.

Builder.Global_Compilation_Switches:
     This attribute is a list of compiler switches to use when compiling any source file in the project hierarchy. These switches are used in addition to the ones defined in the Compiler package, which only apply to the sources of the corresponding project. This attribute is indexed on the name of the language.

Using such global capabilities is convenient. It can also lead to unexpected behavior. Especially when several subsystems are shared among different main projects and the different global attributes are not compatible. Note that using aggregate projects can be a safer and more powerful replacement to global attributes.

Scenarios in Projects
=====================

Various aspects of the projects can be modified based on scenarios. These are user-defined modes that change the behavior of a project. Typical examples are the setup of platform-specific compiler options, or the use of a debug and a release mode (the former would activate the generation of debug information, when the second will focus on improving code optimization).

Let's enhance our example to support a debug and a release modes.The issue is to let the user choose what kind of system he is building: use -g as compiler switches in debug mode and -O2 in release mode. We will also setup the projects so that we do not share the same object directory in both modes, otherwise switching from one to the other might trigger more recompilations than needed or mix objects from the 2 modes.

One naive approach is to create two different project files, say build_debug.gpr and build_release.gpr, that set the appropriate attributes as explained in previous sections. This solution does not scale well, because in presence of multiple projects depending on each other, you will also have to duplicate the complete hierarchy and adapt the project files to point to the right copies.

Instead, project files support the notion of scenarios controlled by external values. Such values can come from several sources (in decreasing order of priority):

Command line:
     When launching gnatmake or gprbuild, the user can pass extra -X switches to define the external value. In our case, the command line might look like

                 gnatmake -Pbuild.gpr -Xmode=debug
             or  gnatmake -Pbuild.gpr -Xmode=release

^Environment variables^Logical names^:
     When the external value does not come from the command line, it can come from the value of ^environment variables^logical names^ of the appropriate name. In our case, if ^an environment variable^a logical name^ called "mode" exist, its value will be taken into account.

External function second parameter

We now need to get that value in the project. The general form is to use the predefined function external which returns the current value of the external. For instance, we could setup the object directory to point to either obj/debug or obj/release by changing our project to

        project Build is
            for Object_Dir use "obj/" & external ("mode", "debug");
            ... --  as before
        end Build;

The second parameter to external is optional, and is the default value to use if "mode" is not set from the command line or the environment.

In order to set the switches according to the different scenarios, other constructs have to be introduced such as typed variables and case statements.

A typed variable is a variable that can take only a limited number of values, similar to an enumeration in Ada. Such a variable can then be used in a case statement and create conditional sections in the project. The following example shows how this can be done:

        project Build is
           type Mode_Type is ("debug", "release");  --  all possible values
           Mode : Mode_Type := external ("mode", "debug"); -- a typed variable

           package Compiler is
              case Mode is
                 when "debug" =>
                    for Switches ("Ada") use ("-g");
                 when "release" =>
                    for Switches ("Ada") use ("-O2");
              end case;
           end Compiler;
        end Build;

The project has suddenly grown in size, but has become much more flexible. Mode_Type defines the only valid values for the mode variable. If any other value is read from the environment, an error is reported and the project is considered as invalid.

The Mode variable is initialized with an external value defaulting to "debug". This default could be omitted and that would force the user to define the value. Finally, we can use a case statement to set the switches depending on the scenario the user has chosen.

Most aspects of the projects can depend on scenarios. The notable exception are project dependencies (with clauses), which may not depend on a scenario.

Scenarios work the same way with project hierarchies: you can either duplicate a variable similar to Mode in each of the project (as long as the first argument to external is always the same and the type is the same), or simply set the variable in the shared.gpr project (see Sharing Between Projects).

Library Projects
================

So far, we have seen examples of projects that create executables. However, it is also possible to create libraries instead. A library is a specific type of subsystem where, for convenience, objects are grouped together using system-specific means such as archives or windows DLLs.

Library projects provide a system- and language-independent way of building both static and dynamic libraries. They also support the concept of standalone libraries (SAL) which offers two significant properties: the elaboration (e.g. initialization) of the library is either automatic or very simple; a change in the implementation part of the library implies minimal post-compilation actions on the complete system and potentially no action at all for the rest of the system in the case of dynamic SALs.

The GNAT Project Manager takes complete care of the library build, rebuild and installation tasks, including recompilation of the source files for which objects do not exist or are not up to date, assembly of the library archive, and installation of the library (i.e., copying associated source, object and ALI files to the specified location).

Building Libraries
------------------

Let's enhance our example and transform the logging subsystem into a library.  In order to do so, a few changes need to be made to logging.gpr. A number of specific attributes needs to be defined: at least Library_Name and Library_Dir; in addition, a number of other attributes can be used to specify specific aspects of the library. For readability, it is also recommended (although not mandatory), to use the qualifier library in front of the project keyword.

Library_Name:
     This attribute is the name of the library to be built. There is no restriction on the name of a library imposed by the project manager, except for stand-alone libraries whose names must follow the syntax of Ada identifiers; however, there may be system specific restrictions on the name. In general, it is recommended to stick to alphanumeric characters (and possibly single underscores) to help portability.

Library_Dir:
     This attribute  is the path (absolute or relative) of the directory where the library is to be installed. In the process of building a library, the sources are compiled, the object files end up  in the explicit or implicit Object_Dir directory. When all sources of a library are compiled, some of the compilation artifacts, including the library itself, are copied to the library_dir directory. This directory must exists and be writable. It must also be different from the object directory so that cleanup activities in the Library_Dir do not affect recompilation needs.

Here is the new version of logging.gpr that makes it a library:

     library project Logging is          --  "library" is optional
        for Library_Name use "logging";  --  will create "liblogging.a" on Unix
        for Object_Dir   use "obj";
        for Library_Dir  use "lib";      --  different from object_dir
     end Logging;

Once the above two attributes are defined, the library project is valid and is enough for building a library with default characteristics. Other library-related attributes can be used to change the defaults:

Library_Kind:
     The value of this attribute must be either "static", "dynamic" or "relocatable" (the latter is a synonym for dynamic). It indicates which kind of library should be build (the default is to build a static library, that is an archive of object files that can potentially be linked into a static executable). When the library is set to be dynamic, a separate image is created that will be loaded independently, usually at the start of the main program execution. Support for dynamic libraries is very platform specific, for instance on Windows it takes the form of a DLL while on GNU/Linux, it is a dynamic elf image whose suffix is usually .so. Library project files, on the other hand, can be written in a platform independent way so that the same project file can be used to build a library on different operating systems.

     If you need to build both a static and a dynamic library, it is recommended use two different object directories, since in some cases some extra code needs to be generated for the latter. For such cases, one can either define two different project files, or a single one which uses scenarios to indicate at the various kinds of library to be build and their corresponding object_dir.

Library_ALI_Dir:
     This attribute may be specified to indicate the directory where the ALI files of the library are installed. By default, they are copied into the Library_Dir directory, but as for the executables where we have a separate Exec_Dir attribute, you might want to put them in a separate directory since there can be hundreds of them. The same restrictions as for the Library_Dir attribute apply.

Library_Version:
     This attribute is platform dependent, and has no effect on VMS and Windows. On Unix, it is used only for dynamic 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. This follows the usual installation schemes for dynamic libraries on many Unix systems.

            project Logging is
               Version := "1";
               for Library_Dir use "lib";
               for Library_Name use "logging";
               for Library_Kind use "dynamic";
               for Library_Version use "liblogging.so." & Version;
            end Logging;

     After the compilation, the directory lib will contain both a libdummy.so.1 library and a symbolic link to it called libdummy.so.

Library_GCC:
     This attribute is the name of the tool to use instead of "gcc" to link shared libraries. A common use of this attribute is to define a wrapper script that accomplishes specific actions before calling gcc (which itself is calling the linker to build the library image).

Library_Options:
     This attribute may be used to specify additional switches (last switches) when linking a shared library.

Leading_Library_Options:
     This attribute, that is taken into account only by gprbuild, may be used to specified leading options (first switches) when linking a shared library.

Linker.Linker_Options:
     This attribute specifies additional switches to be given to the linker when linking an executable. It is ignored when defined in the main project and taken into account in all other projects that are imported directly or indirectly. These switches complement the Linker.Switches defined in the main project. This is useful when a particular subsystem depends on an external library: adding this dependency as a Linker_Options in the project of the subsystem is more convenient than adding it to all the Linker.Switches of the main projects that depend upon this subsystem.

Using Library Projects
----------------------

When the builder detects that a project file is a library project file, it recompiles all sources of the project that need recompilation and rebuild the library if any of the sources have been recompiled. It then groups all object files into a single file, which is a shared or a static library. This library can later on be linked with multiple executables. Note that the use of shard libraries reduces the size of the final executable and can also reduce the memory footprint at execution time when the library is shared among several executables.

It is also possible to build multi-language libraries. When using gprbuild as a builder, multi-language library projects allow naturally the creation of multi-language libraries . gnatmake, does not try to compile non Ada sources. However, when the project is multi-language, it will automatically link all object files found in the object directory, whether or not they were compiled from an Ada source file. This specific behavior does not apply to Ada-only projects which only take into account the objects corresponding to the sources of the project.

A non-library project can import a library project. When the builder is invoked on the former, the library of the latter is only rebuilt when absolutely necessary. For instance, if a unit of the library is not up-to-date but non of the executables need this unit, then the unit is not recompiled and the library is not reassembled. For instance, let's assume in our example that logging has the following sources: log1.ads, log1.adb, log2.ads and log2.adb. If log1.adb has been modified, then the library liblogging will be rebuilt when compiling all the sources of Build only if proc.ads, pack.ads or pack.adb include a "with Log1".

To ensure that all the sources in the Logging library are up to date, and that all the sources of Build are also up to date, the following two commands needs to be used:

     gnatmake -Plogging.gpr
     gnatmake -Pbuild.gpr

All ALI files will also be copied from the object directory to the library directory. To build executables, gnatmake will use the library rather than the individual object files.

Library projects can also be useful to describe a library that need to be used but, for some reason, cannot be rebuilt. For instance, it is the case when some of the library sources are not available. Such library projects need simply to use the Externally_Built attribute as in the example below:

     library project Extern_Lib is
        for Languages    use ("Ada", "C");
        for Source_Dirs  use ("lib_src");
        for Library_Dir  use "lib2";
        for Library_Kind use "dynamic";
        for Library_Name use "l2";
        for Externally_Built use "true";  --  <<<<
     end Extern_Lib;

In the case of externally built libraries, the Object_Dir attribute does not need to be specified because it will never be used.

The main effect of using such an externally built library project is mostly to affect the linker command in order to reference the desired library. It can also be achieved by using Linker.Linker_Options or Linker.Switches in the project corresponding to the subsystem needing this external library. This latter method is more straightforward in simple cases but when several subsystems depend upon the same external library, finding the proper place for the Linker.Linker_Options might not be easy and if it is not placed properly, the final link command is likely to present ordering issues. In such a situation, it is better to use the externally built library project so that all other subsystems depending on it can declare this dependency thanks to a project with clause, which in turn will trigger the builder to find the proper order of libraries in the final link command.

Stand-alone Library Projects
----------------------------

A stand-alone library is a library that contains the necessary code to elaborate the Ada units that are included in the library. A stand-alone library is a convenient way to add an Ada subsystem to a more global system whose main is not in Ada since it makes the elaboration of the Ada part mostly transparent. However, stand-alone libraries are also useful when the main is in Ada: they provide a means for minimizing relinking & redeployment of complex systems when localized changes are made.

The name of a stand-alone library, specified with attribute Library_Name, must have the syntax of an Ada identifier.

The most prominent characteristic of a stand-alone library is that it offers a distinction between interface units and implementation units. Only the former are visible to units outside the library. A stand-alone library project is thus characterised by a third attribute, Library_Interface, in addition to the two attributes that make a project a Library Project (Library_Name and Library_Dir).

Library_Interface:
     This attribute defines an explicit subset of the units of the project. Projects importing this library project may only "with" units whose sources are listed in the Library_Interface. Other sources are considered implementation units.

               for Library_Dir use "lib";
               for Library_Name use "loggin";
               for Library_Interface use ("lib1", "lib2");  --  unit names

In order to include the elaboration code in the stand-alone library, the binder is invoked on the closure of the library units creating a package whose name depends on the library name (^b~logging.ads/b^B$LOGGING.ADS/B^ in the example). This binder-generated package includes initialization and finalization procedures whose names depend on the library name (logginginit and loggingfinal in the example). The object corresponding to this package is included in the library.

Library_Auto_Init:
     A dynamic stand-alone Library is automatically initialized if automatic initialization of Stand-alone Libraries is supported on the platform and if attribute Library_Auto_Init is not specified or is specified with the value "true". A static Stand-alone Library is never automatically initialized. Specifying "false" for this attribute prevent automatic initialization.

     When a non-automatically initialized stand-alone library is used in an executable, its initialization procedure must be called before any service of the library is used. When the main subprogram is in Ada, it may mean that the initialization procedure has to be called during elaboration of another package.

Library_Dir:
     For a stand-alone library, only the ALI files of the interface units (those that are listed in attribute Library_Interface) are copied to the library directory. As a consequence, only the interface units may be imported from Ada units outside of the library. If other units are imported, the binding phase will fail.

Binder.Default_Switches:
     When a stand-alone library is bound, the switches that are specified in the attribute Binder.Default_Switches ("Ada") are used in the call to gnatbind.

Library_Src_Dir:
     This attribute defines the location (absolute or relative to the project directory) where the sources of the interface units are copied at installation time. These sources includes the specs of the interface units along with the closure of sources necessary to compile them successfully. That may include bodies and subunits, when pragmas Inline are used, or when there is a generic units in the spec. This directory cannot point to the object directory or one of the source directories, but it can point to the library directory, which is the default value for this attribute.

Library_Symbol_Policy:
     This attribute controls the export of symbols and, on some platforms (like VMS) that have the notions of major and minor IDs built in the library files, it controls the setting of these IDs. It is not supported on all platforms (where it will just have no effect). It may have one of the following values:

       - "autonomous" or "default": exported symbols are not controlled

       - "compliant": if attribute Library_Reference_Symbol_File is not defined, then it is equivalent to policy "autonomous". If there are exported symbols in the reference symbol file that are not in the object files of the interfaces, the major ID of the library is increased. If there are symbols in the object files of the interfaces that are not in the reference symbol file, these symbols are put at the end of the list in the newly created symbol file and the minor ID is increased.

       - "controlled": the attribute Library_Reference_Symbol_File must be defined. The library will fail to build if the exported symbols in the object files of the interfaces do not match exactly the symbol in the symbol file.

       - "restricted": The attribute Library_Symbol_File must be defined. The library will fail to build if there are symbols in the symbol file that are not in the exported symbols of the object files of the interfaces. Additional symbols in the object files are not added to the symbol file.

       - "direct": The attribute Library_Symbol_File must be defined and must designate an existing file in the object directory. This symbol file is passed directly to the underlying linker without any symbol processing.

Library_Reference_Symbol_File
     This attribute may define the path name of a reference symbol file that is read when the symbol policy is either "compliant" or "controlled", on platforms that support symbol control, such as VMS, when building a stand-alone library. The path may be an absolute path or a path relative to the project directory.

Library_Symbol_File
     This attribute may define the name of the symbol file to be created when building a stand-alone library when the symbol policy is either "compliant", "controlled" or "restricted", on platforms that support symbol control, such as VMS. When symbol policy is "direct", then a file with this name must exist in the object directory.

Installing a library with project files
---------------------------------------

When using project files, library installation is part of the library build process. Thus no further action is needed in order to make use of the libraries that are built as part of the general application build. A usable version of the library is installed in the directory specified by the Library_Dir attribute of the library project file.

You may want to install a library in a context different from where the library is built. This situation arises with third party suppliers, who may want to distribute a library in binary form where the user is not expected to be able to recompile the library. The simplest option in this case is to provide a project file slightly different from the one used to build the library, by using the externally_built attribute. Using Library Projects

Project Extension
=================

During development of a large system, it is sometimes necessary to use modified versions of some of the source files, without changing the original sources. This can be achieved through the project extension facility.

Suppose for instance that our example Build project is build every night for the whole team, in some shared directory. A developer usually need to work on a small part of the system, and might not want to have a copy of all the sources and all the object files (mostly because that would require too much disk space, time to recompile everything). He prefers to be able to override some of the source files in his directory, while taking advantage of all the object files generated at night.

Another example can be taken from large software systems, where it is common to have multiple implementations of a common interface; in Ada terms, multiple versions of a package body for the same spec.  For example, one implementation might be safe for use in tasking programs, while another might only be used in sequential applications.  This can be modeled in GNAT using the concept of project extension.  If one project (the ``child'') extends another project (the ``parent'') then by default all source files of the parent project are inherited by the child, but the child project can override any of the parent's source files with new versions, and can also add new files or remove unnecessary ones. This facility is the project analog of a type extension in object-oriented programming.  Project hierarchies are permitted (an extending project may itself be extended), and a project that extends a project can also import other projects.

A third example is that of using project extensions to provide different versions of the same system. For instance, assume that a Common project is used by two development branches. One of the branches has now been frozen, and no further change can be done to it or to Common. However, the other development branch still needs evolution of Common. Project extensions provide a flexible solution to create a new version of a subsystem while sharing and reusing as much as possible from the original one.

A project extension inherits implicitly all the sources and objects from the project it extends. It is possible to create a new version of some of the sources in one of the additional source dirs of the extending project. Those new versions hide the original versions. Adding new sources or removing existing ones is also possible. Here is an example on how to extend the project Build from previous examples:

        project Work extends "../bld/build.gpr" is
        end Work;

The project after extends is the one being extended. As usual, it can be specified using an absolute path, or a path relative to any of the directories in the project path (see Project Dependencies). This project does not specify source or object directories, so the default value for these attribute will be used that is to say the current directory (where project Work is placed). We can already compile that project with

        gnatmake -Pwork

If no sources have been placed in the current directory, this command won't do anything, since this project does not change the sources it inherited from Build, therefore all the object files in Build and its dependencies are still valid and are reused automatically.

Suppose we now want to supply an alternate version of pack.adb but use the existing versions of pack.ads and proc.adb. We can create the new file Work's current directory  (likely by copying the one from the Build project and making changes to it. If new packages are needed at the same time, we simply create new files in the source directory of the extending project.

When we recompile, gnatmake will now automatically recompile this file (thus creating pack.o in the current directory) and any file that depends on it (thus creating proc.o). Finally, the executable is also linked locally.

Note that we could have obtained the desired behavior using project import rather than project inheritance. A base project would contain the sources for pack.ads and proc.adb, and Work would import base and add pack.adb. In this scenario,  base cannot contain the original version of pack.adb otherwise there would be 2 versions of the same unit in the closure of the project and this is not allowed. Generally speaking, it is not recommended to put the spec and the body of a unit in different projects since this affects their autonomy and reusability.

In a project file that extends another project, it is possible to indicate that an inherited source is not part of the sources of the extending project. This is necessary sometimes when a package spec has been overridden and no longer requires a body: in this case, it is necessary to indicate that the inherited body is not part of the sources of the project, otherwise there will be a compilation error when compiling the spec.

For that purpose, the attribute Excluded_Source_Files is used. Its value is a list of file names. It is also possible to use attribute Excluded_Source_List_File. Its value is the path of a text file containing one file name per line.

     project Work extends "../bld/build.gpr" is
        for Source_Files use ("pack.ads");
        --  New spec of Pkg does not need a completion
        for Excluded_Source_Files use ("pack.adb");
     end Work;

An extending project retains all the switches specified in the extended project.

Project Hierarchy Extension
---------------------------

One of the fundamental restrictions in project extension is the following: A project is not allowed to import directly or indirectly at the same time an extending project and one of its ancestors.

By means of example, consider the following hierarchy of projects.

        a.gpr  contains package A1
        b.gpr, imports a.gpr and contains B1, which depends on A1
        c.gpr, imports b.gpr and contains C1, which depends on B1

If we want to locally extend the packages A1 and C1, we need to create several extending projects:

        a_ext.gpr which extends a.gpr, and overrides A1
        b_ext.gpr which extends b.gpr and imports a_ext.gpr
        c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1

        project A_Ext extends "a.gpr" is
           for Source_Files use ("a1.adb", "a1.ads");
        end A_Ext;

        with "a_ext.gpr";
        project B_Ext extends "b.gpr" is
        end B_Ext;

        with "b_ext.gpr";
        project C_Ext extends "c.gpr" is
           for Source_Files use ("c1.adb");
        end C_Ext;

The extension b_ext.gpr is required, even though we are not overriding any of the sources of b.gpr because otherwise c_expr.gpr would import b.gpr which itself knows nothing about a_ext.gpr.

When extending a large system spanning multiple projects, it is often inconvenient to extend every project in the hierarchy that is impacted by a small change introduced in a low layer. In such cases, it is possible to create an implicit extension of entire hierarchy using extends all relationship.

When the project is extended using extends all inheritance, all projects that are imported by it, both directly and indirectly, are considered virtually extended. That is, the project manager creates implicit projects that extend every project in the hierarchy; all these implicit projects do not control sources on their own and use the object directory of the "extending all" project.

It is possible to explicitly extend one or more projects in the hierarchy in order to modify the sources. These extending projects must be imported by the "extending all" project, which will replace the corresponding virtual projects with the explicit ones.

When building such a project hierarchy extension, the project manager will ensure that both modified sources and sources in implicit extending projects that depend on them, are recompiled.

Thus, in our example we could create the following projects instead:

        a_ext.gpr, extends a.gpr and overrides A1
        c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1

        project A_Ext extends "a.gpr" is
           for Source_Files use ("a1.adb", "a1.ads");
        end A_Ext;

        with "a_ext.gpr";
        project C_Ext extends all "c.gpr" is
          for Source_Files use ("c1.adb");
        end C_Ext;

When building project c_ext.gpr, the entire modified project space is considered for recompilation, including the sources of b.gpr that are impacted by the changes in A1 and C1.

Aggregate Projects
==================

Aggregate projects are an extension of the project paradigm, and are meant to solve a few specific use cases that cannot be solved directly using standard projects. This section will go over a few of these use cases to try and explain what you can use aggregate projects for.

Building all main units from a single project tree
--------------------------------------------------

Most often, an application is organized into modules and submodules, which are very conveniently represented as a project tree or graph (the root project A withs the projects for each modules (say B and C), which in turn with projects for submodules.

Very often, modules will build their own executables (for testing purposes for instance), or libraries (for easier reuse in various contexts).

However, if you build your project through gnatmake or gprbuild, using a syntax similar to

        gprbuild -PA.gpr

this will only rebuild the main units of project A, not those of the imported projects B and C. Therefore you have to spawn several gnatmake commands, one per project, to build all executables. This is a little inconvenient, but more importantly is inefficient (since gnatmake needs to do duplicate work to ensure that sources are up-to-date, and cannot easily compile things in parallel when using the -j switch).

Also libraries are always rebuild when building a project.

You could therefore define an aggregate project Agg that groups A, B and C. Then, when you build with

         gprbuild -PAgg.gpr

this will build all main units from A, B and C.

        aggregate project Agg is
           for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
        end Agg;

If B or C do not define any main unit (through their Main attribute), all their sources are build. When you do not group them in the aggregate project, only those sources that are needed by A will be build.

If you add a main unit to a project P not already explicitly referenced in the aggregate project, you will need to add "p.gpr" in the list of project files for the aggregate project, or the main unit will not be built when building the aggregate project.

Building a set of projects with a single command
------------------------------------------------

One other case is when you have multiple applications and libraries that are build independently from each other (but they can be build in parallel). For instance, you have a project tree rooted at A, and another one (which might share some subprojects) rooted at B.

Using only gprbuild, you could do

       gprbuild -PA.gpr
       gprbuild -PB.gpr

to build both. But again, gprbuild has to do some duplicate work for those files that are shared between the two, and cannot truly build things in parallel efficiently.

If the two projects are really independent, share no sources other than through a common subproject, and have no source files with a common basename, you could create a project C that imports A and B. But these restrictions are often too strong, and one has to build them independently. An aggregate project does not have these limitations, and can aggregate two project trees that have common sources.

     Aggregate projects can group projects with duplicate file names

This scenario is particularly useful in environment like VxWork 653 where the applications running in the multiple partitions can be build in parallel through a single gprbuild command. This also works nicely with Annex E.

        Aggregate projects can be used to build multiple partitions

Define a build environment
--------------------------

The environment variables at the time you launch gprbuild or gprbuild will influence the view these tools have of the project (PATH to find the compiler, ADA_PROJECT_PATH or GPR_PROJECT_PATH to find the projects, environment variables that are referenced in project files through the "external" statement,...). Several command line switches can be used to override those (-X or -aP), but on some systems and with some projects, this might make the command line too long, and on all systems often make it hard to read.

An aggregate project can be used to set the environment for all projects build through that aggregate. One of the nice aspects is that you can put the aggregate project under configuration management, and make sure all your user have a consistent environment when building. The syntax looks like

        aggregate project Agg is
           for Project_Files use ("A.gpr", "B.gpr");
           for Project_Path use ("../dir1", "../dir1/dir2");
           for External ("BUILD") use "PRODUCTION";

           package Builder is
              for Switches ("Ada") use ("-q");
           end Builder;
        end Agg;

One of the often requested features in projects is to be able to reference external variables in with statements, as in

       with external("SETUP") & "path/prj.gpr";   --  ILLEGAL
       project MyProject is
          ...
       end MyProject;

For various reasons, this isn't authorized. But using aggregate projects provide an elegant solution. For instance, you could use a project file like:

     aggregate project Agg is
         for Project_Path use (external("SETUP") % "path");
         for Project_Files use ("myproject.gpr");
     end Agg;

     with "prj.gpr";  --  searched on Agg'Project_Path
     project MyProject is
        ...
     end MyProject;

Performance improvements in builder
-----------------------------------

The loading of aggregate projects is optimized in gprbuild and gnatmake, so that all files are searched for only once on the disk (thus reducing the number of system calls and contributing to faster compilation times especially on systems with sources on remote servers). As part of the loading, gprbuild and gnatmake compute how and where a source file should be compiled, and even if it is found several times in the aggregated projects it will be compiled only once.

Since there is no ambiguity as to which switches should be used, files can be compiled in parallel (through the usual -j switch) and this can be done while maximizing the use of CPUs (compared to launching multiple gprbuild and gnatmake commands in parallel).

Syntax of aggregate projects
----------------------------

An aggregate project follows the general syntax of project files. The recommended extension is still .gpr. However, a special aggregate qualifier must be put before the keyword project.

An aggregate project cannot with any other project (standard or aggregate), except an abstract project which can be used to share attribute values. Building other aggregate projects from an aggregate project is done through the Project_Files attribute (see below).

An aggregate project does not have any source files directly (only through other standard projects). Therefore a number of the standard attributes and packages are forbidden in an aggregate project. Here is the (non exhaustive) list:

  * Languages

  * Source_Files, Source_List_File and other attributes dealing with list of sources.

  * Source_Dirs, Exec_Dir and Object_Dir

  * Library_Dir, Library_Name and other library-related attributes

  * Main

  * Roots

  * Externally_Built

  * Inherit_Source_Path

  * Excluded_Source_Dirs

  * Locally_Removed_Files

  * Excluded_Source_Files

  * Excluded_Source_List_File

  * Interfaces

The only package that is authorized (albeit optional) is Builder. Other packages (in particular Compiler, Binder and Linker) are forbidden. It is an error to have any of these (and such an error prevents the proper loading of the aggregate project).

Three new attributes have been created, which can only be used in the context of aggregate projects:

Project_Files:

     This attribute is compulsory (or else we are not aggregating any project, and thus not doing anything). It specifies a list of .gpr files that are grouped in the aggregate. The list may be empty. The project files can be either other aggregate projects, or standard projects. When grouping standard projects, you can have both the root of a project tree (and you do not need to specify all its imported projects), and any project within the tree.

     Basically, the idea is to specify all those projects that have main units you want to build and link, or libraries you want to build. You can even specify projects that do not use the Main attribute nor the Library_* attributes, and the result will be to build all their source files (not just the ones needed by other projects).

     The file can include paths (absolute or relative). Paths are relative to the location of the aggregate project file itself (if you use a base name, we expect to find the .gpr file in the same directory as the aggregate project file). The extension .gpr is mandatory, since this attribute contains file names, not project names.

     Paths can also include the "*" and "**" globbing patterns. The latter indicates that any subdirectory (recursively) will be searched for matching files. The latter ("**") can only occur at the last position in the directory part (ie "a/**/*.gpr" is supported, but not "**/a/*.gpr"). Starting the pattern with "**" is equivalent to starting with "./**".

     For now, the pattern "*" is only allowed in the filename part, not in the directory part. This is mostly for efficiency reasons to limit the number of system calls that are needed.

     Here are a few valid examples:

              for Project_Files use ("a.gpr", "subdir/b.gpr");
              --  two specific projects relative to the directory of agg.gpr

              for Project_Files use ("**/*.gpr");
              --  all projects recursively

Project_Path:

     This attribute can be used to specify a list of directories in which to look for project files in with statements.

     When you specify a project in Project_Files say "x/y/a.gpr"), and this projects imports a project "b.gpr", only b.gpr is searched in the project path. a.gpr must be exactly at <dir of the aggregate>/x/y/a.gpr.

     This attribute, however, does not affect the search for the aggregated project files specified with Project_Files.

     Each aggregate project has its own (that is if agg1.gpr includes agg2.gpr, they can potentially both have a different project path). This project path is defined as the concatenation, in that order, of the current directory, followed by the command line -aP switches, then the directories from the Project_Path attribute, then the directories from the GPR_PROJECT_PATH and ADA_PROJECT_PATH env. variables, and finally the predefined directories.

     In the example above, agg2.gpr's project path is not influenced by the attribute agg1'Project_Path, nor is agg1 influenced by agg2'Project_Path.

     This can potentially lead to errors. In the following example:

               +---------------+                  +----------------+
               | Agg1.gpr      |-=--includes--=-->| Agg2.gpr       |
               |  'project_path|                  |  'project_path |
               |               |                  |                |
               +---------------+                  +----------------+
                     :                                   :
                     includes                        includes
                     :                                   :
                     v                                   v
                 +-------+                          +---------+
                 | P.gpr |<---------- withs --------|  Q.gpr  |
                 +-------+---------\                +---------+
                     |             |
                     withs         |
                     |             |
                     v             v
                 +-------+      +---------+
                 | R.gpr |      | R'.gpr  |
                 +-------+      +---------+

     When looking for p.gpr, both aggregates find the same physical file on the disk. However, it might happen that with their different project paths, both aggregate projects would in fact find a different r.gpr. Since we have a common project (p.gpr) "with"ing two different r.gpr, this will be reported as an error by the builder.

     Directories are relative to the location of the aggregate project file.

     Here are a few valid examples:

             for Project_Path use ("/usr/local/gpr", "gpr/");

External:

     This attribute can be used to set the value of environment variables as retrieved through the external statement in projects. It does not affect the environment variables themselves (so for instance you cannot use it to change the value of your PATH as seen from the spawned compiler).

     This attribute affects the external values as seen in the rest of the aggreate projects, and in the aggregated projects.

     The exact value of external a variable comes from one of three sources (each level overrides the previous levels):

       * An External attribute in aggregate project, for instance for External ("BUILD_MODE") use "DEBUG";

       * Environment variables

          These override the value given by the attribute, so that users can override the value set in the (presumably shared with others in his team) aggregate project.

       * The -X command line switch to gprbuild and gnatmake

          This always takes precedence.

     This attribute is only taken into account in the main aggregate project (i.e. the one specified on the command line to gprbuild or natmake), and ignored in other aggregate projects. It is invalid in standard projects. The goal is to have a consistent value in all projects that are build through the aggregate, which would not be the case in the diamond case: A groups the aggregate projects B and C, which both (either directly or indirectly) build the project P. If B and C could set different values for the environment variables, we would have two different views of P, which in particular might impact the list of source files in P.

package Builder in aggregate projects
-------------------------------------

As we mentioned before, only the package Builder can be specified in an aggregate project. In this package, only the following attributes are valid:

Switches:
     This attribute gives the list of switches to use for the builder (gprbuild or gnatmake), depending on the language of the main file. For instance,

          for Switches ("Ada") use ("-d", "-p");
          for Switches ("C")   use ("-p");

     These switches are only read from the main aggregate project (the one passed on the command line), and ignored in all other aggregate projects or projects.

     It can only contain builder switches, not compiler switches.

Global_Compilation_Switches

     This attribute gives the list of compiler switches for the various languages. For instance,

          for Global_Compilation_Switches ("Ada") use ("-O1", "-g");
          for Global_Compilation_Switches ("C")   use ("-O2");

     This attribute is only taken into account in the aggregate project specified on the command line, not in other aggregate projects.

     In the projects grouped by that aggregate, the attribute Builder.Global_Compilation_Switches is also ignored. However, the attribute Compiler.Default_Switches will be taken into account (but that of the aggregate have higher priority). The attribute Compiler.Switches is also taken into account and can be used to override the switches for a specific file. As a result, it always has priority.

     The rules are meant to avoid ambiguities when compiling. For instance, aggregate project Agg groups the projects A and B, that both depend on C. Here is an extra for all of these projects:

                aggregate project Agg is
                    for Project_Files use ("a.gpr", "b.gpr");
                    package Builder is
                       for Global_Compilation_Switches ("Ada") use ("-O2");
                    end Builder;
                end Agg;

                with "c.gpr";
                project A is
                    package Builder is
                       for Global_Compilation_Switches ("Ada") use ("-O1");
                       --  ignored
                    end Builder;

                    package Compiler is
                       for Default_Switches ("Ada") use ("-O1", "-g");
                       for Switches ("a_file1.adb") use ("-O0");
                    end Compiler;
                end A;

                with "c.gpr";
                project B is
                    package Compiler is
                       for Default_Switches ("Ada") use ("-O0");
                    end Compiler;
                end B;

                project C is
                    package Compiler is
                       for Default_Switches ("Ada") use ("-O3", "-gnatn");
                       for Switches ("c_file1.adb") use ("-O0", "-g");
                    end Compiler;
                end C;

     then the following switches are used:

       * all files from project A except a_file1.adb are compiled with "-O2 -g", since the aggregate project has priority.

       * the file a_file1.adb is compiled with "-O0", since the Compiler.Switches has priority

       * all files from project B are compiled with "-O2", since the aggregate project has priority

       * all files from C are compiled with "-O2 -gnatn", except for c_file1.adb which is compiled with "-O0 -g"

     Even though C is seen through two paths (through A and through B), the switches used by the compiler are unambiguous.

Global_Configuration_Pragmas

     This attribute can be used to specify a file containing configuration pragmas, to be passed to the compiler.  Since we ignore the package Builder in other aggregate projects and projects, only those pragmas defined in the main aggregate project will be taken into account.

     Projects can locally add to those by using the Compiler.Local_Configuration_Pragmas attribute if they need.

For projects that are build through the aggregate, the package Builder is ignored, except for the Executable attribute which specifies the name of the executables resulting from the link of the main units, and for the Executable_Suffix.

Aggregate Library Projects
==========================

Aggregate library projects make it possible to build a single library using object files built using other standard or library projects. This gives the flexibility to describe an application as having multiple modules (a GUI, database access, ...) using different project files (so possibly built with different compiler options) and yet create a single library (static or relocatable) out of the corresponding object files.

Building aggregate library projects
-----------------------------------

For example, we can define an aggregate project Agg that groups A, B and C:

        aggregate library project Agg is
           for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
           for Library_Name use ("agg");
           for Library_Dir use ("lagg");
        end Agg;

Then, when you build with:

         gprbuild agg.gpr

This will build all units from projects A, B and C and will create a static library named libagg.a into the lagg directory. An aggregate library project has the same set of restriction as a standard library project.

Note that a shared aggregate library project cannot aggregates a static library project. In platforms where a compiler option is required to create relocatable object files, a Builder package in the aggregate library project may be used:

        aggregate library project Agg is
           for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
           for Library_Name use ("agg");
           for Library_Dir use ("lagg");
           for Library_Kind use "relocatable";

           package Builder is
              for Global_Compilation_Switches ("Ada") use ("-fPIC");
           end Builder;
        end Agg;

With the above aggregate library Builder package, the -fPIC option will be passed to the compiler when building any source code from projects a.gpr, b.gpr and c.gpr.

Syntax of aggregate library projects
------------------------------------

An aggregate library project follows the general syntax of project files. The recommended extension is still .gpr. However, a special aggregate library qualifier must be put before the keyword project.

An aggregate library project cannot with any other project (standard or aggregate), except an abstract project which can be used to share attribute values.

An aggregate library project does not have any source files directly (only through other standard projects). Therefore a number of the standard attributes and packages are forbidden in an aggregate library project. Here is the (non exhaustive) list:

  * Languages

  * Source_Files, Source_List_File and other attributes dealing with list of sources.

  * Source_Dirs, Exec_Dir and Object_Dir

  * Main

  * Roots

  * Externally_Built

  * Inherit_Source_Path

  * Excluded_Source_Dirs

  * Locally_Removed_Files

  * Excluded_Source_Files

  * Excluded_Source_List_File

  * Interfaces

The only package that is authorized (albeit optional) is Builder.

The Project_Files attribute (See Aggregate Projects) is used to described the aggregated projects whose object files have to be included into the aggregate library.

Project File Reference
======================

This section describes the syntactic structure of project files, the various constructs that can be used. Finally, it ends with a summary of all available attributes.

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;

Qualified Projects
------------------

Before the reserved project, there may be one or two qualifiers, that is identifiers or reserved words, to qualify the project. The current list of qualifiers is:

abstract: qualifies a project with no sources. Such a
     project must either have no declaration of attributes Source_Dirs, Source_Files, Languages or Source_List_File, or one of Source_Dirs, Source_Files, or Languages must be declared as empty. If it extends another project, the project it extends must also be a qualified abstract project.

standard: a standard project is a non library project with sources.
     This is the default (implicit) qualifier.

aggregate: for future extension

aggregate library: for future extension

library: a library project must declare both attributes
     Library_Name and Library_Dir.

configuration: a configuration project cannot be in a project tree.
     It describes compilers and other tools to gprbuild.

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.

     declarative_item ::= simple_declarative_item
       | typed_string_declaration
       | package_declaration

     simple_declarative_item ::= variable_declaration
       | typed_variable_declaration
       | attribute_declaration
       | case_construction
       | empty_declaration

     empty_declaration ::= null ;

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

Packages
--------

A project file may contain packages, that group attributes (typically all the attributes that are used by one of the GNAT tools).

A package with a given name may only appear once in a project file. The following packages are currently supported in project files (See Attributes for the list of attributes that each can contain).

Binder
     This package specifies characteristics useful when invoking the binder either directly via the gnat driver or when using a builder such as gnatmake or gprbuild. See Main Subprograms.

Builder
     This package specifies the compilation options used when building an executable or a library for a project. Most of the options should be set in one of Compiler, Binder or Linker packages, but there are some general options that should be defined in this package. See Main Subprograms, and see Executable File Names in particular.

Check
     This package specifies the options used when calling the checking tool gnatcheck via the gnat driver. Its attribute Default_Switches has the same semantics as for the package Builder. The first string should always be -rules to specify that all the other options belong to the -rules section of the parameters to gnatcheck.

Compiler
     This package specifies the compilation options used by the compiler for each languages. See Tools Options in Project Files.

Cross_Reference
     This package specifies the options used when calling the library tool gnatxref via the gnat driver. Its attributes Default_Switches and Switches have the same semantics as for the package Builder.

Eliminate
     This package specifies the options used when calling the tool gnatelim via the gnat driver. Its attributes Default_Switches and Switches have the same semantics as for the package Builder.

Finder
     This package specifies the options used when calling the search tool gnatfind via the gnat driver. Its attributes Default_Switches and Switches have the same semantics as for the package Builder.

Gnatls
     This package the options to use when invoking gnatls via the gnat driver.

Gnatstub
     This package specifies the options used when calling the tool gnatstub via the gnat driver. Its attributes Default_Switches and Switches have the same semantics as for the package Builder.

IDE
     This package specifies the options used when starting an integrated development environment, for instance GPS or Gnatbench. See The Development Environments.

Linker
     This package specifies the options used by the linker. See Main Subprograms.

Makefile
     This package is used by the GPS plugin Makefile.py. See the documentation in that plugin (from GPS: /Tools/Plug-ins).

Metrics
     This package specifies the options used when calling the tool gnatmetric via the gnat driver. Its attributes Default_Switches and Switches have the same semantics as for the package Builder.

Naming
     This package specifies the naming conventions that apply to the source files in a project. In particular, these conventions are used to automatically find all source files in the source directories, or given a file name to find out its language for proper processing. See Naming Schemes.

Pretty_Printer
     This package specifies the options used when calling the formatting tool gnatpp via the gnat driver. Its attributes Default_Switches and Switches have the same semantics as for the package Builder.

Stack
     This package specifies the options used when calling the tool gnatstack via the gnat driver. Its attributes Default_Switches and Switches have the same semantics as for the package Builder.

Synchronize
     This package specifies the options used when calling the tool gnatsync via the gnat driver.

In its simplest form, a package may be empty:

     project Simple is
       package Builder is
       end Builder;
     end Simple;

A package may contain attribute declarations, variable declarations and case constructions, as will be described below.

When there is ambiguity between a project name and a package name, the name always designates the project. To avoid possible confusion, it is always a good idea to avoid naming a project with one of the names allowed for packages or any name that starts with gnat.

A package can also 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. The name of the renamed package must be the same as the name of the renaming package. The project must contain a package declaration with this name, and the project must appear in the context clause of the current project, or be its parent project. It is not possible to add or override attributes to the renaming project. If you need to do so, you should use an extending declaration (see below).

Packages that are renamed in other project files often come from project files that have no sources: they are just used as templates. Any modification in the template will be reflected automatically in all the project files that rename a package from the template. This is a very common way to share settings between projects.

Finally, a package can also be defined by an extending declaration. This is similar to a renaming declaration, except that it is possible to add or override attributes.

     package_declaration ::= package_spec | package_renaming | package_extension
     package_spec ::=
       package <package_>simple_name is
         {simple_declarative_item}
       end package_identifier ;
     package_renaming ::==
       package <package_>simple_name renames <project_>simple_name.package_identifier ;
     package_extension ::==
       package <package_>simple_name extends <project_>simple_name.package_identifier is
         {simple_declarative_item}
       end package_identifier ;

Expressions
-----------

An expression is any value that can be assigned to an attribute or a variable. It is either a literal value, or a construct requiring runtime computation by the project manager. In a project file, the computed value of an expression is either a string or a list of strings.

A string value is one of:

  * A literal string, for instance "comm/my_proj.gpr"

  * The name of a variable that evaluates to a string (see Variables)

  * The name of an attribute that evaluates to a string (see Attributes)

  * An external reference (see External Values)

  * A concatenation of the above, as in "prefix_" & Var.

A list of strings is one of the following:

  * A parenthesized comma-separated list of zero or more string expressions, for instance (File_Name, "gnat.adc", File_Name & ".orig") or ().

  * The name of a variable that evaluates to a list of strings

  * The name of an attribute that evaluates to a list of strings

  * A concatenation of a list of strings and a string (as defined above), for instance ("A", "B") & "C"

  * A concatenation of two lists of strings

The following is the grammar for expressions

     string_literal ::= "{string_element}"  --  Same as Ada
     string_expression ::= string_literal
         | variable_name
         | external_value
         | attribute_reference
         | ( string_expression { & string_expression } )
     string_list  ::= ( string_expression { , string_expression } )
        | string_variable_name
        | string_attribute_reference
     term ::= string_expression | string_list
     expression ::= term { & term }     --  Concatenation

Concatenation involves strings and list of strings. As soon as a list of strings is involved, the result of the concatenation is a list of strings. The following Ada declarations show the existing operators:

       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;

Here are some specific examples:

        List := () & File_Name; --  One string in this list
        List2 := List & (File_Name & ".orig"); -- Two strings
        Big_List := List & Lists2;  --  Three strings
        Illegal := "gnat.adc" & List2;  --  Illegal, must start with list

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 or gprbuild command).

There are two kinds of external values, one that returns a single string, and one that returns a string list.

The syntax of a single string external value is:

     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.

Typically, the external value will either exist in the ^environment variables^logical name^ or be specified on the command line through the ^-X^/EXTERNAL_REFERENCE=^vbl=value switch. If both are specified, then the command line value is used, so that a user can more easily override the value.

The function external always returns a string. It is an error if the value was not found in the environment and no default was specified in the call to external.

An external reference may be part of a string expression or of a string list expression, and can therefore appear in a variable declaration or an attribute declaration.

Most of the time, this construct is used to initialize typed variables, which are then used in case statements to control the value assigned to attributes in various scenarios. Thus such variables are often called scenario variables.

The syntax for a string list external value is:

     external_value ::= external_as_list ( 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 is the separator between each component of the string list.

If the external value does not exist in the environment or on the command line, the result is an empty list. This is also the case, if the separator is an empty string or if the external value is only one separator.

Any separator at the beginning or at the end of the external value is discarded. Then, if there is no separator in the external value, the result is a string list with only one string. Otherwise, any string between the beginning and the first separator, between two consecutive separators and between the last separator and the end are components of the string list.

        external_as_list ("SWITCHES", ",")

If the external value is "-O2,-g", the result is ("-O2", "-g").

If the external value is ",-O2,-g,", the result is also ("-O2", "-g").

if the external value is "-gnav", the result is ("-gnatv").

If the external value is ",,", the result is ("").

If the external value is ",", the result is (), the empty string list.

Typed String Declaration
------------------------

A type declaration introduces a discrete set of string literals. If a string variable is declared to have this type, its value is restricted to the given set of literals. These are the only named types in project files. A string type may only be declared at the project level, not inside a package.

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

The string literals in the list are case sensitive and must all be different. They may include any graphic characters allowed in Ada, including spaces. Here is an example of a string type declaration:

        type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS");

Variables of a string type are called typed variables; all other variables are called untyped variables. Typed variables are particularly useful in case constructions, to support conditional attribute declarations. (see Case Statements).

A string type may be referenced by its name if it has been declared in the same project file, or by an expanded name whose prefix is the name of the project in which it is declared.

Variables
---------

Variables store values (strings or list of strings) and can appear as part of an expression. The declaration of a variable creates the variable and assigns the value of the expression to it. The name of the variable is available immediately after the assignment symbol, if you need to reuse its old value to compute the new value. Before the completion of its first declaration, the value of a variable defaults to the empty string ("").

A typed variable can be used as part of a case expression to compute the value, but it can only be declared once in the project file, so that all case statements see the same value for the variable. This provides more consistency and makes the project easier to understand. The syntax for its declaration is identical to the Ada syntax for an object declaration. In effect, a typed variable acts as a constant.

An untyped variable can be declared and overridden multiple times within the same project. It is declared implicitly through an Ada assignment. The first declaration establishes the kind of the variable (string or list of strings) and successive declarations must respect the initial kind. Assignments are executed in the order in which they appear, so the new value replaces the old one and any subsequent reference to the variable uses the new value.

A variable may be declared at the project file level, or within a package.

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

Here are some examples of variable declarations:

        This_OS : OS := external ("OS"); --  a typed variable declaration
        That_OS := "GNU/Linux";          --  an untyped variable declaration

        Name      := "readme.txt";
        Save_Name := Name & ".saved";

        Empty_List := ();
        List_With_One_Element := ("-gnaty");
        List_With_Two_Elements := List_With_One_Element & "-gnatg";
        Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada");

A variable reference may take several forms:

  * The simple variable name, for a variable in the current package (if any) or in the current project

  * An expanded name, whose prefix is a context name.

A context may be one of the following:

  * The name of an existing package in the current project

  * The name of an imported project of the current project

  * The name of an ancestor project (i.e., a project extended by the current project, either directly or indirectly)

  * An expanded name whose prefix is an imported/parent project name, and whose selector is a package name in that project.

Attributes
----------

A project (and its packages) may have attributes that define the project's properties.  Some attributes have values that are strings; others have values that are string lists.

     attribute_declaration ::=
        simple_attribute_declaration | indexed_attribute_declaration
     simple_attribute_declaration ::= for attribute_designator use expression ;
     indexed_attribute_declaration ::=
       for <indexed_attribute_>simple_name ( string_literal) use expression ;
     attribute_designator ::=
       <simple_attribute_>simple_name
       | <indexed_attribute_>simple_name ( string_literal )

There are two categories of attributes: simple attributes and indexed attributes. Each simple attribute has a default value: the empty string (for string attributes) and the empty list (for string list attributes). An attribute declaration defines a new value for an attribute, and overrides the previous value. The syntax of a simple attribute declaration is similar to that of an attribute definition clause in Ada.

Some attributes are indexed. These attributes are mappings whose domain is a set of strings. They are declared one association at a time, by specifying a point in the domain and the corresponding image of the attribute. Like untyped variables and simple attributes, indexed attributes may be declared several times. Each declaration supplies a new value for the attribute, and replaces the previous setting.

Here are some examples of attribute declarations:

        --  simple attributes
        for Object_Dir use "objects";
        for Source_Dirs use ("units", "test/drivers");

        --  indexed attributes
        for Body ("main") use "Main.ada";
        for Switches ("main.ada") use ("-v", "-gnatv");
        for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g";

        --  indexed attributes copy (from package Builder in project Default)
        --  The package name must always be specified, even if it is the current
        --  package.
        for Default_Switches use Default.Builder'Default_Switches;

Attributes references may be appear anywhere in expressions, and are used to retrieve the value previously assigned to the attribute. If an attribute has not been set in a given package or project, its value defaults to the empty string or the empty list.

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

Examples are:

       project'Object_Dir
       Naming'Dot_Replacement
       Imported_Project'Source_Dirs
       Imported_Project.Naming'Casing
       Builder'Default_Switches ("Ada")

The prefix of an attribute may be:

  * project for an attribute of the current project

  * The name of an existing package of the current project

  * The name of an imported project

  * The name of a parent project that is extended by the current project

  * An expanded name whose prefix is imported/parent project name, and whose selector is a package name

Legal attribute names are listed below, including the package in which they must be declared. These names are case-insensitive. The semantics for the attributes is explained in great details in other sections.

The column index indicates whether the attribute is an indexed attribute, and when it is whether its index is case sensitive (sensitive) or not (insensitive), or if case sensitivity depends is the same as file names sensitivity on the system (file). The text is between brackets ([]) if the index is optional.

Attribute Name   Value   Package   Index
General attributes       see Building With Projects
Name   string   -   (Read-only, name of project)
Project_Dir   string   -   (Read-only, directory of project)
Source_Files   list   -   -
Source_Dirs    list   -   -
Source_List_File   string   -   -
Locally_Removed_Files   list   -   -
Excluded_Source_Files   list   -   -
Object_Dir     string   -   -
Exec_Dir       string   -   -
Excluded_Source_Dirs   list   -   -
Excluded_Source_Files   list   -   -
Excluded_Source_List_File   list   -   -
Inherit_Source_Path    list   -   insensitive
Languages   list   -   -
Main        list   -   -
Main_Language   string   -   -
Externally_Built        string   -   -
Roots        list   -   file

Library-related attributes       see Library Projects
Library_Dir   string   -   -
Library_Name   string   -   -
Library_Kind   string   -   -
Library_Version   string   -   -
Library_Interface   string   -   -
Library_Auto_Init   string   -   -
Library_Options   list   -   -
Leading_Library_Options   list   -   -
Library_Src_Dir   string   -   -
Library_ALI_Dir   string   -   -
Library_GCC   string   -   -
Library_Symbol_File   string   -   -
Library_Symbol_Policy   string   -   -
Library_Reference_Symbol_File   string   -   -
Interfaces   list   -   -

Naming       see Naming Schemes
Spec_Suffix   string   Naming   insensitive (language)
Body_Suffix   string   Naming   insensitive (language)
Separate_Suffix   string   Naming   -
Casing   string   Naming   -
Dot_Replacement   string   Naming   -
Spec   string   Naming   insensitive (Ada unit)
Body   string   Naming   insensitive (Ada unit)
Specification_Exceptions   list   Naming   insensitive (language)
Implementation_Exceptions   list   Naming   insensitive (language)

Building       see Switches and Project Files
Default_Switches   list   Builder, Compiler, Binder, Linker, Cross_Reference, Finder, Pretty_Printer, gnatstub, Check, Synchronize, Eliminate, Metrics, IDE   insensitive (language name)
Switches   list   Builder, Compiler, Binder, Linker, Cross_Reference, Finder, gnatls, Pretty_Printer, gnatstub, Check, Synchronize, Eliminate, Metrics, Stack   [file] (file name)
Local_Configuration_Pragmas   string   Compiler   -
Local_Config_File   string   insensitive   -
Global_Configuration_Pragmas   list   Builder   -
Global_Compilation_Switches   list   Builder   language
Executable   string   Builder   [file]
Executable_Suffix   string   Builder   -
Global_Config_File   string   Builder   insensitive (language)

IDE (used and created by GPS)
Remote_Host   string   IDE   -
Program_Host   string   IDE   -
Communication_Protocol   string   IDE   -
Compiler_Command   string   IDE   insensitive (language)
Debugger_Command   string   IDE   -
Gnatlist   string   IDE   -
Gnat   string   IDE   -
VCS_Kind   string   IDE   -
VCS_File_Check   string   IDE   -
VCS_Log_Check   string   IDE   -
Documentation_Dir   string   IDE   -

Configuration files       See gprbuild manual
Default_Language   string   -   -
Run_Path_Option   list   -   -
Run_Path_Origin   string   -   -
Separate_Run_Path_Options   string   -   -
Toolchain_Version   string   -   insensitive
Toolchain_Description   string   -   insensitive
Object_Generated   string   -   insensitive
Objects_Linked   string   -   insensitive
Target   string   -   -
Library_Builder   string   -   -
Library_Support   string   -   -
Archive_Builder   list   -   -
Archive_Builder_Append_Option   list   -   -
Archive_Indexer   list   -   -
Archive_Suffix   string   -   -
Library_Partial_Linker   list   -   -
Shared_Library_Prefix   string   -   -
Shared_Library_Suffix   string   -   -
Symbolic_Link_Supported   string   -   -
Library_Major_Minor_Id_Supported   string   -   -
Library_Auto_Init_Supported   string   -   -
Shared_Library_Minimum_Switches   list   -   -
Library_Version_Switches   list   -   -
Library_Install_Name_Option   string   -   -
Runtime_Library_Dir   string   -   insensitive
Runtime_Source_Dir   string   -   insensitive
Driver   string   Compiler,Binder,Linker   insensitive (language)
Required_Switches   list   Compiler,Binder,Linker   insensitive (language)
Leading_Required_Switches   list   Compiler   insensitive (language)
Trailing_Required_Switches   list   Compiler   insensitive (language)
Pic_Options   list   Compiler   insensitive (language)
Path_Syntax   string   Compiler   insensitive (language)
Object_File_Suffix   string   Compiler   insensitive (language)
Object_File_Switches   list   Compiler   insensitive (language)
Multi_Unit_Switches   list   Compiler   insensitive (language)
Multi_Unit_Object_Separator   string   Compiler   insensitive (language)
Mapping_File_Switches   list   Compiler   insensitive (language)
Mapping_Spec_Suffix   string   Compiler   insensitive (language)
Mapping_body_Suffix   string   Compiler   insensitive (language)
Config_File_Switches   list   Compiler   insensitive (language)
Config_Body_File_Name   string   Compiler   insensitive (language)
Config_Body_File_Name_Index   string   Compiler   insensitive (language)
Config_Body_File_Name_Pattern   string   Compiler   insensitive (language)
Config_Spec_File_Name   string   Compiler   insensitive (language)
Config_Spec_File_Name_Index   string   Compiler   insensitive (language)
Config_Spec_File_Name_Pattern   string   Compiler   insensitive (language)
Config_File_Unique   string   Compiler   insensitive (language)
Dependency_Switches   list   Compiler   insensitive (language)
Dependency_Driver   list   Compiler   insensitive (language)
Include_Switches   list   Compiler   insensitive (language)
Include_Path   string   Compiler   insensitive (language)
Include_Path_File   string   Compiler   insensitive (language)
Prefix   string   Binder   insensitive (language)
Objects_Path   string   Binder   insensitive (language)
Objects_Path_File   string   Binder   insensitive (language)
Linker_Options   list   Linker   -
Leading_Switches   list   Linker   -
Map_File_Options   string   Linker   -
Executable_Switches   list   Linker   -
Lib_Dir_Switch   string   Linker   -
Lib_Name_Switch   string   Linker   -
Max_Command_Line_Length   string   Linker   -
Response_File_Format   string   Linker   -
Response_File_Switches   list   Linker   -

Case Statements
---------------

A case statement is used in a project file to effect conditional behavior. Through this statement, you can set the value of attributes and variables depending on the value previously assigned to a typed variable.

All choices in a choice list must be distinct. 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.

The syntax of a case construction is based on the Ada case statement (although the null statement for empty alternatives is optional).

The case expression must be a typed string variable, whose value is often given by an external reference (see External Values).

Each alternative starts with the reserved word when, either a list of literal strings separated by the "|" character or the reserved word others, and the "=>" token. Each literal string must belong to the string type that is the type of the case variable. After each =>, there are zero or more statements.  The only statements allowed in a case construction are other case statements, attribute declarations and variable declarations. String type declarations and package declarations are not allowed. Variable declarations are restricted to variables that have already been declared before the case construction.

     case_statement ::=
       case <typed_variable_>name is {case_item} end case ;

     case_item ::=
       when discrete_choice_list =>
         {case_statement
           | attribute_declaration
           | variable_declaration
           | empty_declaration}

     discrete_choice_list ::= string_literal {| string_literal} | others

Here is a typical example:

     project MyProj is
        type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
        OS : OS_Type := external ("OS", "GNU/Linux");

        package Compiler is
          case OS is
            when "GNU/Linux" | "Unix" =>
              for Switches ("Ada") use ("-gnath");
            when "NT" =>
              for Switches ("Ada") use ("-gnatP");
            when others =>
              null;
          end case;
        end Compiler;
     end MyProj;

Tools Supporting Project Files
******************************

gnatmake and Project Files
==========================

This section covers several topics related to gnatmake and project files: defining ^switches^switches^ for gnatmake and for the tools that it invokes; specifying configuration pragmas; the use of the Main attribute; building and rebuilding library project files.

Switches Related to Project Files
---------------------------------

The following switches are used by GNAT tools that support project files:

^-P^/PROJECT_FILE=^PROJECT
     Indicates the name of a project file. This project file will be parsed with the verbosity indicated by ^-vP^MESSAGE_PROJECT_FILES=^x, if any, and using the external references indicated by ^-X^/EXTERNAL_REFERENCE^ switches, if any. There may zero, one or more spaces between -P and PROJECT.

     There must be only one ^-P^/PROJECT_FILE^ switch on the command line.

     Since the Project Manager parses the project file only after all the switches on the command line are checked, the order of the switches ^-P^/PROJECT_FILE^, ^-vP^/MESSAGES_PROJECT_FILE=^x or ^-X^/EXTERNAL_REFERENCE^ is not significant.

^-X^/EXTERNAL_REFERENCE=^NAME=VALUE
     Indicates that external variable NAME has the value VALUE. The Project Manager will use this value for occurrences of external(name) when parsing the project file.

     If NAME or VALUE includes a space, then NAME=VALUE should be put between quotes.

            -XOS=NT
            -X"user=John Doe"

     Several ^-X^/EXTERNAL_REFERENCE^ switches can be used simultaneously. If several ^-X^/EXTERNAL_REFERENCE^ switches specify the same NAME, only the last one is used.

     An external variable specified with a ^-X^/EXTERNAL_REFERENCE^ switch takes precedence over the value of the same name in the environment.

^-vP^/MESSAGES_PROJECT_FILE=^x
     Indicates the verbosity of the parsing of GNAT project files.

     -vP0 means Default; -vP1 means Medium; -vP2 means High.

     The default is ^Default^DEFAULT^: no output for syntactically correct project files. If several ^-vP^/MESSAGES_PROJECT_FILE=^x switches are present, only the last one is used.

^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir>
     Add directory <dir> at the beginning of the project search path, in order, after the current working directory.

-eL
     Follow all symbolic links when processing project files.

^--subdirs^/SUBDIRS^=<subdir>
     This switch is recognized by gnatmake and gnatclean. It indicate that the real directories (except the source directories) are the subdirectories <subdir> of the directories specified in the project files. This applies in particular to object directories, library directories and exec directories. If the subdirectories do not exist, they are created automatically.

Switches and Project Files
--------------------------

For each of the packages Builder, Compiler, Binder, and Linker, you can specify a ^Default_Switches^Default_Switches^ attribute, a Switches attribute, or both; as their names imply, these ^switch^switch^-related attributes affect the ^switches^switches^ that are used for each of these GNAT components when gnatmake is invoked.  As will be explained below, these component-specific ^switches^switches^ precede the ^switches^switches^ provided on the gnatmake command line.

The ^Default_Switches^Default_Switches^ attribute is an attribute indexed by language name (case insensitive) whose value is a string list. For example:

     package Compiler is
       for ^Default_Switches^Default_Switches^ ("Ada")
           use ("^-gnaty^-gnaty^",
                "^-v^-v^");
     end Compiler;

The Switches attribute is indexed on a file name (which may or may not be case sensitive, depending on the operating system) whose value is a string list.  For example:

     package Builder is
        for Switches ("main1.adb")
            use ("^-O2^-O2^");
        for Switches ("main2.adb")
            use ("^-g^-g^");
     end Builder;

For the Builder package, the file names must designate source files for main subprograms.  For the Binder and Linker packages, the file names must designate ALI or source files for main subprograms. In each case just the file name without an explicit extension is acceptable.

For each tool used in a program build (gnatmake, the compiler, the binder, and the linker), the corresponding package contributes a set of ^switches^switches^ for each file on which the tool is invoked, based on the ^switch^switch^-related attributes defined in the package. In particular, the ^switches^switches^ that each of these packages contributes for a given file F comprise:

  * the value of attribute Switches (F), if it is specified in the package for the given file,

  * otherwise, the value of ^Default_Switches^Default_Switches^ ("Ada"), if it is specified in the package.

If neither of these attributes is defined in the package, then the package does not contribute any ^switches^switches^ for the given file.

When gnatmake is invoked on a file, the ^switches^switches^ comprise two sets, in the following order: those contributed for the file by the Builder package; and the switches passed on the command line.

When gnatmake invokes a tool (compiler, binder, linker) on a file, the ^switches^switches^ passed to the tool comprise three sets, in the following order:

 1. the applicable ^switches^switches^ contributed for the file by the Builder package in the project file supplied on the command line;

 2. those contributed for the file by the package (in the relevant project file -- see below) corresponding to the tool; and

 3. the applicable switches passed on the command line.

The term applicable ^switches^switches^ reflects the fact that gnatmake ^switches^switches^ may or may not be passed to individual tools, depending on the individual ^switch^switch^.

gnatmake may invoke the compiler on source files from different projects. The Project Manager will use the appropriate project file to determine the Compiler package for each source file being compiled. Likewise for the Binder and Linker packages.

As an example, consider the following package in a project file:

     project Proj1 is
        package Compiler is
           for ^Default_Switches^Default_Switches^ ("Ada")
               use ("^-g^-g^");
           for Switches ("a.adb")
               use ("^-O1^-O1^");
           for Switches ("b.adb")
               use ("^-O2^-O2^",
                    "^-gnaty^-gnaty^");
        end Compiler;
     end Proj1;

If gnatmake is invoked with this project file, and it needs to compile, say, the files a.adb, b.adb, and c.adb, then a.adb will be compiled with the ^switch^switch^ ^-O1^-O1^, b.adb with ^switches^switches^ ^-O2^-O2^ and ^-gnaty^-gnaty^, and c.adb with ^-g^-g^.

The following example illustrates the ordering of the ^switches^switches^ contributed by different packages:

     project Proj2 is
        package Builder is
           for Switches ("main.adb")
               use ("^-g^-g^",
                    "^-O1^-)1^",
                    "^-f^-f^");
        end Builder;

        package Compiler is
           for Switches ("main.adb")
               use ("^-O2^-O2^");
        end Compiler;
     end Proj2;

If you issue the command:

         gnatmake ^-Pproj2^/PROJECT_FILE=PROJ2^ -O0 main

then the compiler will be invoked on main.adb with the following sequence of ^switches^switches^

        ^-g -O1 -O2 -O0^-g -O1 -O2 -O0^

with the last ^-O^-O^ ^switch^switch^ having precedence over the earlier ones; several other ^switches^switches^ (such as ^-c^-c^) are added implicitly.

The ^switches^switches^ ^-g^-g^ and ^-O1^-O1^ are contributed by package Builder,  ^-O2^-O2^ is contributed by the package Compiler and ^-O0^-O0^ comes from the command line.

The ^-g^-g^ ^switch^switch^ will also be passed in the invocation of Gnatlink.

A final example illustrates switch contributions from packages in different project files:

     project Proj3 is
        for Source_Files use ("pack.ads", "pack.adb");
        package Compiler is
           for ^Default_Switches^Default_Switches^ ("Ada")
               use ("^-gnata^-gnata^");
        end Compiler;
     end Proj3;

     with "Proj3";
     project Proj4 is
        for Source_Files use ("foo_main.adb", "bar_main.adb");
        package Builder is
           for Switches ("foo_main.adb")
               use ("^-s^-s^",
                    "^-g^-g^");
        end Builder;
     end Proj4;

     -- Ada source file:
     with Pack;
     procedure Foo_Main is
        ...
     end Foo_Main;

If the command is

     gnatmake ^-PProj4^/PROJECT_FILE=PROJ4^ foo_main.adb -cargs -gnato

then the ^switches^switches^ passed to the compiler for foo_main.adb are ^-g^-g^ (contributed by the package Proj4.Builder) and ^-gnato^-gnato^ (passed on the command line). When the imported package Pack is compiled, the ^switches^switches^ used are ^-g^-g^ from Proj4.Builder, ^-gnata^-gnata^ (contributed from package Proj3.Compiler, and ^-gnato^-gnato^ from the command line.

When using gnatmake with project files, some ^switches^switches^ or arguments may be expressed as relative paths. As the working directory where compilation occurs may change, these relative paths are converted to absolute paths. For the ^switches^switches^ found in a project file, the relative paths are relative to the project file directory, for the switches on the command line, they are relative to the directory where gnatmake is invoked. The ^switches^switches^ for which this occurs are: ^-I^-I^, ^-A^-A^, ^-L^-L^, ^-aO^-aO^, ^-aL^-aL^, ^-aI^-aI^, as well as all arguments that are not switches (arguments to ^switch^switch^ ^-o^-o^, object files specified in package Linker or after -largs on the command line). The exception to this rule is the ^switch^switch^ ^--RTS=^--RTS=^ for which a relative path argument is never converted.

Specifying Configuration Pragmas
--------------------------------

When using gnatmake with project files, if there exists a file gnat.adc that contains configuration pragmas, this file will be ignored.

Configuration pragmas can be defined by means of the following attributes in project files: Global_Configuration_Pragmas in package Builder and Local_Configuration_Pragmas in package Compiler.

Both these attributes are single string attributes. Their values is the path name of a file containing configuration pragmas. If a path name is relative, then it is relative to the project directory of the project file where the attribute is defined.

When compiling a source, the configuration pragmas used are, in order, those listed in the file designated by attribute Global_Configuration_Pragmas in package Builder of the main project file, if it is specified, and those listed in the file designated by attribute Local_Configuration_Pragmas in package Compiler of the project file of the source, if it exists.

Project Files and Main Subprograms
----------------------------------

When using a project file, you can invoke gnatmake with one or several main subprograms, by specifying their source files on the command line.

         gnatmake ^-P^/PROJECT_FILE=^prj main1 main2 main3

Each of these needs to be a source file of the same project, except when the switch ^-u^/UNIQUE^ is used.

When ^-u^/UNIQUE^ is not used, all the mains need to be sources of the same project, one of the project in the tree rooted at the project specified on the command line. The package Builder of this common project, the "main project" is the one that is considered by gnatmake.

When ^-u^/UNIQUE^ is used, the specified source files may be in projects imported directly or indirectly by the project specified on the command line. Note that if such a source file is not part of the project specified on the command line, the ^switches^switches^ found in package Builder of the project specified on the command line, if any, that are transmitted to the compiler will still be used, not those found in the project file of the source file.

When using a project file, you can also invoke gnatmake without explicitly specifying any main, and the effect depends on whether you have defined the Main attribute.  This attribute has a string list value, where each element in the list is the name of a source file (the file extension is optional) that contains a unit that can be a main subprogram.

If the Main attribute is defined in a project file as a non-empty string list and the switch ^-u^/UNIQUE^ is not used on the command line, then invoking gnatmake with this project file but without any main on the command line is equivalent to invoking gnatmake with all the file names in the Main attribute on the command line.

Example:

        project Prj is
           for Main use ("main1", "main2", "main3");
        end Prj;

With this project file, "gnatmake ^-Pprj^/PROJECT_FILE=PRJ^" is equivalent to "gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1 main2 main3".

When the project attribute Main is not specified, or is specified as an empty string list, or when the switch -u is used on the command line, then invoking gnatmake with no main on the command line will result in all immediate sources of the project file being checked, and potentially recompiled. Depending on the presence of the switch -u, sources from other project files on which the immediate sources of the main project file depend are also checked and potentially recompiled. In other words, the -u switch is applied to all of the immediate sources of the main project file.

When no main is specified on the command line and attribute Main exists and includes several mains, or when several mains are specified on the command line, the default ^switches^switches^ in package Builder will be used for all mains, even if there are specific ^switches^switches^ specified for one or several mains.

But the ^switches^switches^ from package Binder or Linker will be the specific ^switches^switches^ for each main, if they are specified.

Library Project Files
---------------------

When gnatmake is invoked with a main project file that is a library project file, it is not allowed to specify one or more mains on the command line.

When a library project file is specified, switches ^-b^/ACTION=BIND^ and ^-l^/ACTION=LINK^ have special meanings.

  * ^-b^/ACTION=BIND^ is only allowed for stand-alone libraries. It indicates to gnatmake that gnatbind should be invoked for the library.

  * ^-l^/ACTION=LINK^ may be used for all library projects. It indicates to gnatmake that the binder generated file should be compiled (in the case of a stand-alone library) and that the library should be built.

The GNAT Driver and Project Files
=================================

A number of GNAT tools, other than ^gnatmake^gnatmake^ can benefit from project files: (^gnatbind^gnatbind^, ^gnatcheck^gnatcheck^, ^gnatclean^gnatclean^, ^gnatelim^gnatelim^, ^gnatfind^gnatfind^, ^gnatlink^gnatlink^, ^gnatls^gnatls^, ^gnatmetric^gnatmetric^, ^gnatpp^gnatpp^, ^gnatstub^gnatstub^, and ^gnatxref^gnatxref^). However, none of these tools can be invoked directly with a project file switch (^-P^/PROJECT_FILE=^). They must be invoked through the gnat driver.

The gnat driver is a wrapper that accepts a number of commands and calls the corresponding tool. It was designed initially for VMS platforms (to convert VMS qualifiers to Unix-style switches), but it is now available on all GNAT platforms.

On non-VMS platforms, the gnat driver accepts the following commands (case insensitive):

  * BIND to invoke ^gnatbind^gnatbind^

  * CHOP to invoke ^gnatchop^gnatchop^

  * CLEAN to invoke ^gnatclean^gnatclean^

  * COMP or COMPILE to invoke the compiler

  * ELIM to invoke ^gnatelim^gnatelim^

  * FIND to invoke ^gnatfind^gnatfind^

  * KR or KRUNCH to invoke ^gnatkr^gnatkr^

  * LINK to invoke ^gnatlink^gnatlink^

  * LS or LIST to invoke ^gnatls^gnatls^

  * MAKE to invoke ^gnatmake^gnatmake^

  * NAME to invoke ^gnatname^gnatname^

  * PREP or PREPROCESS to invoke ^gnatprep^gnatprep^

  * PP or PRETTY to invoke ^gnatpp^gnatpp^

  * METRIC to invoke ^gnatmetric^gnatmetric^

  * STUB to invoke ^gnatstub^gnatstub^

  * XREF to invoke ^gnatxref^gnatxref^

(note that the compiler is invoked using the command ^gnatmake -f -u -c^gnatmake -f -u -c^).

On non-VMS platforms, between gnat and the command, two special switches may be used:

  * -v to display the invocation of the tool.

  * -dn to prevent the gnat driver from removing the temporary files it has created. These temporary files are configuration files and temporary file list files.

The command may be followed by switches and arguments for the invoked tool.

       gnat bind -C main.ali
       gnat ls -a main
       gnat chop foo.txt

Switches may also be put in text files, one switch per line, and the text files may be specified with their path name preceded by '@'.

        gnat bind @args.txt main.ali

In addition, for commands BIND, COMP or COMPILE, FIND, ELIM, LS or LIST, LINK, METRIC, PP or PRETTY, STUB and XREF, the project file related switches (^-P^/PROJECT_FILE^, ^-X^/EXTERNAL_REFERENCE^ and ^-vP^/MESSAGES_PROJECT_FILE=^x) may be used in addition to the switches of the invoking tool.

When GNAT PP or GNAT PRETTY is used with a project file, but with no source specified on the command line, it invokes ^gnatpp^gnatpp^ with all the immediate sources of the specified project file.

When GNAT METRIC is used with a project file, but with no source specified on the command line, it invokes ^gnatmetric^gnatmetric^ with all the immediate sources of the specified project file and with ^-d^/DIRECTORY^ with the parameter pointing to the object directory of the project.

In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with a project file, no source is specified on the command line and switch ^-U^/ALL_PROJECTS^ is specified on the command line, then the underlying tool (^gnatpp^gnatpp^ or ^gnatmetric^gnatmetric^) is invoked for all sources of all projects, not only for the immediate sources of the main project. (-U stands for Universal or Union of the project files of the project tree)

For each of the following commands, there is optionally a corresponding package in the main project.

  * package Binder for command BIND (invoking ^gnatbind^gnatbind^)

  * package Check for command CHECK (invoking ^gnatcheck^gnatcheck^)

  * package Compiler for command COMP or COMPILE (invoking the compiler)

  * package Cross_Reference for command XREF (invoking ^gnatxref^gnatxref^)

  * package Eliminate for command ELIM (invoking ^gnatelim^gnatelim^)

  * package Finder for command FIND (invoking ^gnatfind^gnatfind^)

  * package Gnatls for command LS or LIST (invoking ^gnatls^gnatls^)

  * package Gnatstub for command STUB (invoking ^gnatstub^gnatstub^)

  * package Linker for command LINK (invoking ^gnatlink^gnatlink^)

  * package Check for command CHECK (invoking ^gnatcheck^gnatcheck^)

  * package Metrics for command METRIC (invoking ^gnatmetric^gnatmetric^)

  * package Pretty_Printer for command PP or PRETTY (invoking ^gnatpp^gnatpp^)

Package Gnatls has a unique attribute Switches, a simple variable with a string list value. It contains ^switches^switches^ for the invocation of ^gnatls^gnatls^.

     project Proj1 is
        package gnatls is
           for Switches
               use ("^-a^-a^",
                    "^-v^-v^");
        end gnatls;
     end Proj1;

All other packages have two attribute Switches and ^Default_Switches^Default_Switches^.

Switches is an indexed attribute, indexed by the source file name, that has a string list value: the ^switches^switches^ to be used when the tool corresponding to the package is invoked for the specific source file.

^Default_Switches^Default_Switches^ is an attribute, indexed by  the programming language that has a string list value. ^Default_Switches^Default_Switches^ ("Ada") contains the ^switches^switches^ for the invocation of the tool corresponding to the package, except if a specific Switches attribute is specified for the source file.

     project Proj is

        for Source_Dirs use ("**");

        package gnatls is
           for Switches use
               ("^-a^-a^",
                "^-v^-v^");
        end gnatls;

        package Compiler is
           for ^Default_Switches^Default_Switches^ ("Ada")
               use ("^-gnatv^-gnatv^",
                    "^-gnatwa^-gnatwa^");
        end Binder;

        package Binder is
           for ^Default_Switches^Default_Switches^ ("Ada")
               use ("^-C^-C^",
                    "^-e^-e^");
        end Binder;

        package Linker is
           for ^Default_Switches^Default_Switches^ ("Ada")
               use ("^-C^-C^");
           for Switches ("main.adb")
               use ("^-C^-C^",
                    "^-v^-v^",
                    "^-v^-v^");
        end Linker;

        package Finder is
           for ^Default_Switches^Default_Switches^ ("Ada")
                use ("^-a^-a^",
                     "^-f^-f^");
        end Finder;

        package Cross_Reference is
           for ^Default_Switches^Default_Switches^ ("Ada")
               use ("^-a^-a^",
                    "^-f^-f^",
                    "^-d^-d^",
                    "^-u^-u^");
        end Cross_Reference;
     end Proj;

With the above project file, commands such as

        ^gnat comp -Pproj main^GNAT COMP /PROJECT_FILE=PROJ MAIN^
        ^gnat ls -Pproj main^GNAT LIST /PROJECT_FILE=PROJ MAIN^
        ^gnat xref -Pproj main^GNAT XREF /PROJECT_FILE=PROJ MAIN^
        ^gnat bind -Pproj main.ali^GNAT BIND /PROJECT_FILE=PROJ MAIN.ALI^
        ^gnat link -Pproj main.ali^GNAT LINK /PROJECT_FILE=PROJ MAIN.ALI^

will set up the environment properly and invoke the tool with the switches found in the package corresponding to the tool: ^Default_Switches^Default_Switches^ ("Ada") for all tools, except Switches ("main.adb") for ^gnatlink^gnatlink^. It is also possible to invoke some of the tools, (^gnatcheck^gnatcheck^, ^gnatmetric^gnatmetric^, and ^gnatpp^gnatpp^) on a set of project units thanks to the combination of the switches -P, -U and possibly the main unit when one is interested in its closure. For instance,

     gnat metric -Pproj

will compute the metrics for all the immediate units of project proj.

     gnat metric -Pproj -U

will compute the metrics for all the units of the closure of projects rooted at proj.

     gnat metric -Pproj -U main_unit

will compute the metrics for the closure of units rooted at main_unit. This last possibility relies implicitly on gnatbind's option -R. But if the argument files for the tool invoked by the gnat driver are explicitly  specified either directly or through the tool -files option, then the tool is called only for these explicitly specified files.

The Development Environments
============================

See the appropriate manuals for more details. These environments will store a number of settings in the project itself, when they are meant to be shared by the whole team working on the project. Here are the attributes defined in the package IDE in projects.

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

Gnat
     This is a simple attribute. Its value is a string that specifies the name of the gnat utility to be used when executing various tools from GPS, in particular "gnat pp", "gnat stub",...

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.

VCS_Repository_Root
     The VCS repository root path. This is used to create tags or branches of the repository. For subversion the value should be the URL as specified to check-out the working copy of the repository.

VCS_Patch_Root
     The local root directory to use for building patch file. All patch chunks will be relative to this path. The root project directory is used if this value is not defined.