GNAT GPL User's Guide: Handling Arbitrary File Naming Conventions with gnatname

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 10. Handling Arbitrary File Naming Conventions with `gnatname`

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 10.2 Running `gnatname`

The usual form of the `gnatname` command is

    $ gnatname [switches] naming_pattern [naming_patterns]
          [--and [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 (or single quotes on Windows). A Naming Pattern is a regular expression similar to the wildcard patterns used in file names by the Unix shells or the DOS prompt.

`gnatname` may be called with several sections of directories/patterns. Sections are separated by switch `--and`. In each section, there must be at least one pattern. If no directory is specified in a section, the current directory (or the project directory is `-P` is used) is implied. The options other that the directory switches and the patterns apply globally even if they are in different sections.

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 switch `-P`, `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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 10.3 Switches for `gnatname`

Switches for `gnatname` must precede any specified Naming Pattern.

You may specify any of the following switches to `gnatname`:

``--version'`
  Display Copyright and version, then exit disregarding all other options.

``--help'`
  If ``--version'` was not used, display usage, then exit disregarding all other options.

``--subdirs=<dir>'`
  Real object, library or exec directories are subdirectories <dir> of the specified ones.

``--no-backup'`
  Do not create a backup copy of an existing project file.

``--and'`
  Start another section of directories/patterns.

``-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'`. ``dir'` may end with `/**`, that is it may be of the form `root_dir/**`. In this case, the directory `root_dir` and all of its subdirectories, recursively, have to be searched for sources. 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 nonempty line in ``file'` must be a directory. Specifying switch ``-D'` is equivalent to specifying as many switches ``-d'` as there are nonempty lines in ``file'`.

``-eL'`
  Follow symbolic links when processing project files.

``-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. On all platforms, except on VMS, when `gnatname` is invoked for an existing project file <proj>.gpr, a backup copy of the project file is created in the project directory with file name <proj>.gpr.saved_x. 'x' is the first non negative number that makes this backup copy a new file.

``-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'`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 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.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by GNAT Mailserver on April, 17 2014 using texi2html