8. Renaming Files Using gnatchop

This chapter discusses how to handle files with multiple units by using the gnatchop utility. This utility is also useful in renaming files to meet the standard GNAT default file naming conventions.

8.1 Handling Files with Multiple Units
8.2 Operating gnatchop in Compilation Mode
8.3 Command Line for gnatchop
8.4 Switches for gnatchop
8.5 Examples of gnatchop Usage

8.1 Handling Files with Multiple Units

The basic compilation model of GNAT requires that a file submitted to the compiler have only one unit and there be a strict correspondence between the file name and the unit name.

The gnatchop utility allows both of these rules to be relaxed, allowing GNAT to process files which contain multiple compilation units and files with arbitrary file names. gnatchop reads the specified file and generates one or more output files, containing one unit per file. The unit and the file name correspond, as required by GNAT.

If you want to permanently restructure a set of "foreign" files so that they match the GNAT rules, and do the remaining development using the GNAT structure, you can simply use gnatchop once, generate the new set of files and work with them from that point on.

Alternatively, if you want to keep your files in the "foreign" format, perhaps to maintain compatibility with some other Ada compilation system, you can set up a procedure where you use gnatchop each time you compile, regarding the source files that it writes as temporary files that you throw away.

8.2 Operating gnatchop in Compilation Mode

The basic function of gnatchop is to take a file with multiple units and split it into separate files. The boundary between files is reasonably clear, except for the issue of comments and pragmas. In default mode, the rule is that any pragmas between units belong to the previous unit, except that configuration pragmas always belong to the following unit. Any comments belong to the following unit. These rules almost always result in the right choice of the split point without needing to mark it explicitly and most users will find this default to be what they want. In this default mode it is incorrect to submit a file containing only configuration pragmas, or one that ends in configuration pragmas, to gnatchop.

However, using a special option to activate "compilation mode", gnatchop can perform another function, which is to provide exactly the semantics required by the RM for handling of configuration pragmas in a compilation. In the absence of configuration pragmas (at the main file level), this option has no effect, but it causes such configuration pragmas to be handled in a quite different manner.

First, in compilation mode, if gnatchop is given a file that consists of only configuration pragmas, then this file is appended to the `gnat.adc' file in the current directory. This behavior provides the required behavior described in the RM for the actions to be taken on submitting such a file to the compiler, namely that these pragmas should apply to all subsequent compilations in the same compilation environment. Using GNAT, the current directory, possibly containing a `gnat.adc' file is the representation of a compilation environment. For more information on the `gnat.adc' file, see 9.1 Handling of Configuration Pragmas.

Second, in compilation mode, if gnatchop is given a file that starts with configuration pragmas, and contains one or more units, then these configuration pragmas are prepended to each of the chopped files. This behavior provides the required behavior described in the RM for the actions to be taken on compiling such a file, namely that the pragmas apply to all units in the compilation, but not to subsequently compiled units.

Finally, if configuration pragmas appear between units, they are appended to the previous unit. This results in the previous unit being illegal, since the compiler does not accept configuration pragmas that follow a unit. This provides the required RM behavior that forbids configuration pragmas other than those preceding the first compilation unit of a compilation.

For most purposes, gnatchop will be used in default mode. The compilation mode described above is used only if you need exactly accurate behavior with respect to compilations, and you have files that contain multiple units and configuration pragmas. In this circumstance the use of gnatchop with the compilation mode switch provides the required behavior, and is for example the mode in which GNAT processes the ACVC tests.

8.3 Command Line for gnatchop

The gnatchop command has the form:

$ gnatchop switches file name [file name file name ...] [directory]

The only required argument is the file name of the file to be chopped. There are no restrictions on the form of this file name. The file itself contains one or more Ada units, in normal GNAT format, concatenated together. As shown, more than one file may be presented to be chopped.

When run in default mode, gnatchop generates one output file in the current directory for each unit in each of the files.

directory, if specified, gives the name of the directory to which the output files will be written. If it is not specified, all files are written to the current directory.

For example, given a file called `hellofiles' containing

procedure hello; with Text_IO; use Text_IO; procedure hello is begin Put_Line ("Hello"); end hello;

the command

$ gnatchop hellofiles

generates two files in the current directory, one called `hello.ads' containing the single line that is the procedure spec, and the other called `hello.adb' containing the remaining text. The original file is not affected. The generated files can be compiled in the normal manner.

When gnatchop is invoked on a file that is empty or that contains only empty lines and/or comments, gnatchop will not fail, but will not produce any new sources.

For example, given a file called `toto.txt' containing

-- Just a comment

the command

$ gnatchop toto.txt

will not produce any new file and will result in the following warnings:

toto.txt:1:01: warning: empty file, contains no compilation units no compilation units found no source files written

8.4 Switches for gnatchop

gnatchop recognizes the following switches:

`-c'

Causes gnatchop to operate in compilation mode, in which configuration pragmas are handled according to strict RM rules. See previous section for a full description of this mode.

`-gnatxxx'

This passes the given `-gnatxxx' switch to gnat which is used to parse the given file. Not all xxx options make sense, but for example, the use of `-gnati2' allows gnatchop to process a source file that uses Latin-2 coding for identifiers.

`-h'

Causes gnatchop to generate a brief help summary to the standard output file showing usage information.

`-kmm'

Limit generated file names to the specified number mm of characters. This is useful if the resulting set of files is required to be interoperable with systems which limit the length of file names. No space is allowed between the `-k' and the numeric value. The numeric value may be omitted in which case a default of `-k8', suitable for use with DOS-like file systems, is used. If no `-k' switch is present then there is no limit on the length of file names.

`-p'

Causes the file modification time stamp of the input file to be preserved and used for the time stamp of the output file(s). This may be useful for preserving coherency of time stamps in an environment where gnatchop is used as part of a standard build process.

`-q'

Causes output of informational messages indicating the set of generated files to be suppressed. Warnings and error messages are unaffected.

`-r'

Generate Source_Reference pragmas. Use this switch if the output files are regarded as temporary and development is to be done in terms of the original unchopped file. This switch causes Source_Reference pragmas to be inserted into each of the generated files to refers back to the original file name and line number. The result is that all error messages refer back to the original unchopped file. In addition, the debugging information placed into the object file (when the `-g' switch of gcc or gnatmake is specified) also refers back to this original file so that tools like profilers and debuggers will give information in terms of the original unchopped file.

If the original file to be chopped itself contains a Source_Reference pragma referencing a third file, then gnatchop respects this pragma, and the generated Source_Reference pragmas in the chopped file refer to the original file, with appropriate line numbers. This is particularly useful when gnatchop is used in conjunction with gnatprep to compile files that contain preprocessing statements and multiple units.

`-v'

Causes gnatchop to operate in verbose mode. The version number and copyright notice are output, as well as exact copies of the gnat1 commands spawned to obtain the chop control information.

`-w'

Overwrite existing file names. Normally gnatchop regards it as a fatal error if there is already a file with the same name as a file it would otherwise output, in other words if the files to be chopped contain duplicated units. This switch bypasses this check, and causes all but the last instance of such duplicated units to be skipped.

`--GCC=xxxx'

Specify the path of the GNAT parser to be used. When this switch is used, no attempt is made to add the prefix to the GNAT parser executable.

8.5 Examples of gnatchop Usage

gnatchop -w hello_s.ada prerelease/files

Chops the source file `hello_s.ada'. The output files will be placed in the directory `prerelease/files', overwriting any files with matching names in that directory (no files in the current directory are modified).

gnatchop archive

Chops the source file `archive' into the current directory. One useful application of gnatchop is in sending sets of sources around, for example in email messages. The required sources are simply concatenated (for example, using a Unix cat command), and then gnatchop is used at the other end to reconstitute the original file names.

gnatchop file1 file2 file3 direc

Chops all units in files `file1', `file2', `file3', placing the resulting files in the directory `direc'. Note that if any units occur more than once anywhere within this set of files, an error message is generated, and no files are written. To override this check, use the `-w' switch, in which case the last occurrence in the last file will be the one that is output, and earlier duplicate occurrences for a given unit will be skipped.