11.5 Importing Projects

An immediate source of a project P may depend on source files that are neither immediate sources of P nor in the predefined library. To get this effect, P must import the projects that contain the needed source files.

       with "project1", "utilities.gpr";
       with "/namings/apex.gpr";
       project Main is
         ...

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 is the file name or path name (absolute or relative) of a project file. If a string corresponds to a file name, with no path or a relative path, then its location is determined by the project path. The latter can be queried using gnatls -v. It contains:

• In first position, the directory containing the current project file.
• In last position, the default project directory. This default project directory is part of the GNAT installation and is the standard place to install project files giving access to standard support libraries. Installing a library
• In between, all the directories referenced in the environment variable ADA_PROJECT_PATH if it exists.

If a relative pathname is used, as in

       with "tests/proj";

then the full path for the project is constructed by concatenating this relative path to those in the project path, in order, until a matching file is found. Any symbolic link will be fully resolved in the directory of the importing project file before the imported project file is examined.

If the with'ed project file name does not have an extension, the default is .gpr. If a file with this extension is not found, then the file name as specified in the with clause (no extension) will be used. In the above example, if a file project1.gpr is found, then it will be used; otherwise, if a file project1 exists then it will be used; if neither file exists, this is an error.

A warning is issued if the name of the project file does not match the name of the project; this check is case insensitive.

Any source file that is an immediate source of the imported project can be used by the immediate sources of the importing project, transitively. Thus if A imports B, and B imports C, the immediate sources of A may depend on the immediate 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.

A side effect of this capability is that normally cyclic dependencies are not permitted: 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 on the condition that imports from B to A include at least one limited with.

     with "../b/b.gpr";
     with "../c/c.gpr";
     project A is
     end A;
     
     limited with "../a/a.gpr";
     project B is
     end B;
     
     with "../d/d.gpr";
     project C is
     end C;
     
     limited with "../a/a.gpr";
     project D is
     end D;

In the above legal example, there are two project cycles:

• A-> B-> A
• A -> C -> D -> A

In each of these cycle there is one limited with: import of A from B and import of A from D.

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 that imports it. In particular, its packages cannot be renamed and its variables cannot be referred to.

An exception to the above rules for limited with is that for the main project specified to gnatmake or to the GNAT driver a limited with is equivalent to a straight with. For example, in the example above, projects B and D could not be main projects for gnatmake or to the GNAT driver, because they each have a limited with that is the only one in a cycle of importing projects.