5.6.1 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'.

For 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 an 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.