6.2 The GNAT Driver and Project Files

A number of GNAT tools beyond `gnatmake' can benefit from project files:

• `gnatbind'
• `gnatclean'
• `gnatfind'
• `gnatlink'
• `gnatls'
• `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):

• BIND to invoke `gnatbind'
• CHOP to invoke `gnatchop'
• CLEAN to invoke `gnatclean'
• COMP or COMPILE to invoke the compiler
• FIND to invoke `gnatfind'
• KR or KRUNCH to invoke `gnatkr'
• LINK to invoke `gnatlink'
• LS or LIST to invoke `gnatls'
• MAKE to invoke `gnatmake'
• NAME to invoke `gnatname'
• PREP or PREPROCESS to invoke `gnatprep'
• XREF to invoke `gnatxref'

Note that the command `gnatmake -c -f -u' is used to invoke the compiler.

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 the following commands the project file related switches (`-P', `-X' and `-vPx') may be used in addition to the switches of the invoking tool:

• BIND
• COMP or COMPILE
• FIND
• LS or LIST
• LINK
• XREF

For each of the following commands, there is optionally a corresponding package in the main project.

• package Binder for command BIND (invoking gnatbind)
• package Compiler for command COMP or COMPILE (invoking the compiler)
• package Cross_Reference for command XREF (invoking gnatxref)
• package Finder for command FIND (invoking gnatfind)
• package Gnatls for command LS or LIST (invoking gnatls)
• package Linker for command LINK (invoking gnatlink)

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.