12.2 The GNAT Driver and Project Files

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

• BIND to invoke ^gnatbind^gnatbind^
• CHOP to invoke ^gnatchop^gnatchop^
• CLEAN to invoke ^gnatclean^gnatclean^
• COMP or COMPILE to invoke the compiler
• ELIM to invoke ^gnatelim^gnatelim^
• FIND to invoke ^gnatfind^gnatfind^
• KR or KRUNCH to invoke ^gnatkr^gnatkr^
• LINK to invoke ^gnatlink^gnatlink^
• LS or LIST to invoke ^gnatls^gnatls^
• MAKE to invoke ^gnatmake^gnatmake^
• NAME to invoke ^gnatname^gnatname^
• PREP or PREPROCESS to invoke ^gnatprep^gnatprep^
• PP or PRETTY to invoke ^gnatpp^gnatpp^
• METRIC to invoke ^gnatmetric^gnatmetric^
• STUB to invoke ^gnatstub^gnatstub^
• XREF to invoke ^gnatxref^gnatxref^

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

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

• -v to display the invocation of the tool.
• -dn to prevent the gnat driver from removing the temporary files it has created. These temporary files are configuration files and temporary file list files.

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^/PROJECT_FILE^, ^-X^/EXTERNAL_REFERENCE^ and ^-vP^/MESSAGES_PROJECT_FILE=^x) 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^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^gnatmetric^ with all the immediate sources of the specified project file and with ^-d^/DIRECTORY^ 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^/ALL_PROJECTS^ is specified on the command line, then the underlying tool (^gnatpp^gnatpp^ or ^gnatmetric^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 Binder for command BIND (invoking ^gnatbind^gnatbind^)
• package Check for command CHECK (invoking ^gnatcheck^gnatcheck^)
• package Compiler for command COMP or COMPILE (invoking the compiler)
• package Cross_Reference for command XREF (invoking ^gnatxref^gnatxref^)
• package Eliminate for command ELIM (invoking ^gnatelim^gnatelim^)
• package Finder for command FIND (invoking ^gnatfind^gnatfind^)
• package Gnatls for command LS or LIST (invoking ^gnatls^gnatls^)
• package Gnatstub for command STUB (invoking ^gnatstub^gnatstub^)
• package Linker for command LINK (invoking ^gnatlink^gnatlink^)
• package Check for command CHECK (invoking ^gnatcheck^gnatcheck^)
• package Metrics for command METRIC (invoking ^gnatmetric^gnatmetric^)
• package Pretty_Printer for command PP or PRETTY (invoking ^gnatpp^gnatpp^)

Package Gnatls has a unique attribute Switches, a simple variable with a string list value. It contains ^switches^switches^ for the invocation of ^gnatls^gnatls^.

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

All other packages have two attribute Switches and ^Default_Switches^Default_Switches^.

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

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

With the above project file, commands such as

        ^gnat comp -Pproj main^GNAT COMP /PROJECT_FILE=PROJ MAIN^
        ^gnat ls -Pproj main^GNAT LIST /PROJECT_FILE=PROJ MAIN^
        ^gnat xref -Pproj main^GNAT XREF /PROJECT_FILE=PROJ MAIN^
        ^gnat bind -Pproj main.ali^GNAT BIND /PROJECT_FILE=PROJ MAIN.ALI^
        ^gnat link -Pproj main.ali^GNAT LINK /PROJECT_FILE=PROJ 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^Default_Switches^ ("Ada") for all tools, except Switches ("main.adb") for ^gnatlink^gnatlink^. It is also possible to invoke some of the tools, (^gnatcheck^gnatcheck^, ^gnatmetric^gnatmetric^, and ^gnatpp^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 gnat driver are explicitly specified either directly or through the tool -files option, then the tool is called only for these explicitly specified files.