11.7.3 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;