10. Handling Arbitrary File Naming Conventions Using gnatname

10.1 Arbitrary File Naming Conventions
10.2 Running gnatname
10.3 Switches for gnatname
10.4 Examples of gnatname Usage

10.1 Arbitrary File Naming Conventions

The GNAT compiler must be able to know the source file name of a compilation unit. When using the standard GNAT default file naming conventions (.ads for specs, .adb for bodies), the GNAT compiler does not need additional information.

When the source file names do not follow the standard GNAT default file naming conventions, the GNAT compiler must be given additional information through a configuration pragmas file (see section 9. Configuration Pragmas) or a project file. When the non standard file naming conventions are well-defined, a small number of pragmas Source_File_Name specifying a naming pattern (see section 2.5 Alternative File Naming Schemes) may be sufficient. However, if the file naming conventions are irregular or arbitrary, a number of pragma Source_File_Name for individual compilation units must be defined. To help maintain the correspondence between compilation unit names and source file names within the compiler, GNAT provides a tool gnatname to generate the required pragmas for a set of files.

10.2 Running gnatname

The usual form of the gnatname command is

$ gnatname [switches] naming_pattern [naming_patterns]

All of the arguments are optional. If invoked without any argument, gnatname will display its usage.

When used with at least one naming pattern, gnatname will attempt to find all the compilation units in files that follow at least one of the naming patterns. To find these compilation units, gnatname will use the GNAT compiler in syntax-check-only mode on all regular files.

One or several Naming Patterns may be given as arguments to gnatname. Each Naming Pattern is enclosed between double quotes. A Naming Pattern is a regular expression similar to the wildcard patterns used in file names by the Unix shells or the DOS prompt.

Examples of Naming Patterns are

"*.[12].ada" "*.ad[sb]*" "body_*" "spec_*"

For a more complete description of the syntax of Naming Patterns, see the second kind of regular expressions described in `g-regexp.ads' (the "Glob" regular expressions).

When invoked with no switches, gnatname will create a configuration pragmas file `gnat.adc' in the current working directory, with pragmas Source_File_Name for each file that contains a valid Ada unit.

10.3 Switches for gnatname

Switches for gnatname must precede any specified Naming Pattern.

You may specify any of the following switches to gnatname:

`-c`file''

Create a configuration pragmas file `file' (instead of the default `gnat.adc'). There may be zero, one or more space between `-c' and `file'. `file' may include directory information. `file' must be writable. There may be only one switch `-c'. When a switch `-c' is specified, no switch `-P' may be specified (see below).

`-d`dir''

Look for source files in directory `dir'. There may be zero, one or more spaces between `-d' and `dir'. When a switch `-d' is specified, the current working directory will not be searched for source files, unless it is explicitly specified with a `-d' or `-D' switch. Several switches `-d' may be specified. If `dir' is a relative path, it is relative to the directory of the configuration pragmas file specified with switch `-c', or to the directory of the project file specified with switch `-P' or, if neither switch `-c' nor switch `-P' are specified, it is relative to the current working directory. The directory specified with switch `-d' must exist and be readable.

`-D`file''

Look for source files in all directories listed in text file `file'. There may be zero, one or more spaces between `-D' and `file'. `file' must be an existing, readable text file. Each non empty line in `file' must be a directory. Specifying switch `-D' is equivalent to specifying as many switches `-d' as there are non empty lines in `file'.

`-f`pattern''

Foreign patterns. Using this switch, it is possible to add sources of languages other than Ada to the list of sources of a project file. It is only useful if a -P switch is used. For example,

gnatname -Pprj -f"*.c" "*.ada"

will look for Ada units in all files with the `.ada' extension, and will add to the list of file for project `prj.gpr' the C files with extension ".c".

`-h'

Output usage (help) information. The output is written to `stdout'.

`-P`proj''

Create or update project file `proj'. There may be zero, one or more space between `-P' and `proj'. `proj' may include directory information. `proj' must be writable. There may be only one switch `-P'. When a switch `-P' is specified, no switch `-c' may be specified.

`-v'

Verbose mode. Output detailed explanation of behavior to `stdout'. This includes name of the file written, the name of the directories to search and, for each file in those directories whose name matches at least one of the Naming Patterns, an indication of whether the file contains a unit, and if so the name of the unit.

`-v -v'

Very Verbose mode. In addition to the output produced in verbose mode, for each file in the searched directories whose name matches none of the Naming Patterns, an indication is given that there is no match.

`-x`pattern''

Excluded patterns. Using this switch, it is possible to exclude some files that would match the name patterns. For example,

gnatname -x "*_nt.ada" "*.ada"

will look for Ada units in all files with the `.ada' extension, except those whose names end with `_nt.ada'.

10.4 Examples of gnatname Usage

$ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*"

In this example, the directory `/home/me' must already exist and be writable. In addition, the directory `/home/me/sources' (specified by `-d sources') must exist and be readable.

Note the optional spaces after `-c' and `-d'.

$ gnatname -P/home/me/proj -x "*_nt_body.ada" -dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*"

Note that several switches `-d' may be used, even in conjunction with one or several switches `-D'. Several Naming Patterns and one excluded pattern are used in this example.