Next: , Previous: gnatmake and Project Files, Up: Tools Supporting Project Files   [Contents][Index]

2.2 The GNAT Driver and Project Files

A number of GNAT tools, other than gnatmake can benefit from project files: (gnatbind, gnatcheck, gnatclean, gnatelim, gnatfind, gnatlink, gnatls, gnatmetric, gnatpp, gnatstub, and gnatxref). However, none of these tools can be invoked directly with a project file switch (-P). 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):

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

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

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, -X and -vPx) 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 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 with all the immediate sources of the specified project file and with -d 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 is specified on the command line, then the underlying tool (gnatpp or 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 Gnatls has a unique attribute Switches, a simple variable with a string list value. It contains switches for the invocation of gnatls.

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

All other packages have two attribute Switches and Default_Switches.

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

Default_Switches is an attribute, indexed by the programming language that has a string list value. Default_Switches ("Ada") contains the 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",
           "-v");
   end gnatls;
   package Compiler is
      for Default_Switches ("Ada")
          use ("-gnatv",
               "-gnatwa");
   end Binder;
   package Binder is
      for Default_Switches ("Ada")
          use ("-C",
               "-e");
   end Binder;
   package Linker is
      for Default_Switches ("Ada")
          use ("-C");
      for Switches ("main.adb")
          use ("-C",
               "-v",
               "-v");
   end Linker;
   package Finder is
      for Default_Switches ("Ada")
           use ("-a",
                "-f");
   end Finder;
   package Cross_Reference is
      for Default_Switches ("Ada")
          use ("-a",
               "-f",
               "-d",
               "-u");
   end Cross_Reference;
end Proj;

With the above project file, commands such as

   gnat comp -Pproj main
   gnat ls -Pproj main
   gnat xref -Pproj main
   gnat bind -Pproj main.ali
   gnat link -Pproj 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 ("Ada") for all tools, except Switches ("main.adb") for gnatlink. It is also possible to invoke some of the tools, (gnatcheck, gnatmetric, and 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 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.