The basic function of gnatchop is to take a file with multiple units
and split it into separate files. The boundary between units 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 you needing to mark it explicitly and you’ll likely
find this default to be what you want. In this default mode, you may not
submit a file containing only configuration pragmas, or one that ends in
configuration pragmas, to gnatchop.
However, using a special switch to activate ‘compilation mode’,
gnatchop
can perform another function, which is to provide exactly the semantics
required by the RM for the handling of configuration pragmas in a compilation.
In the absence of configuration pragmas at the main file level, this
switch has no effect, but it causes such configuration pragmas to be handled
in a very different manner.
First, in compilation mode, if you give gnatchop a file that consists of
only configuration pragmas, it appends this file 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 Handling of Configuration Pragmas.
Second, in compilation mode, if you give gnatchop a file that
starts with configuration pragmas and contains one or more units, then
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, you will use gnatchop in default mode. You only
use the compilation mode described above if you need precisely
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. This is the mode
in which GNAT processes the ACVC tests.