5.7.3 Define a build environment

The environment variables at the time you launch `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" built-in function, ...). 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 built 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' declarations, as in

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

For various reasons, this is not allowed. 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;