3.2.18 Integrated Preprocessing

GNAT sources may be preprocessed immediately before compilation; the actual
text of the source is not the text of the source file, but is derived from it
through a process called preprocessing. Integrated preprocessing is specified
through switches -gnatep and/or -gnateD. -gnatep
indicates, through a text file, the preprocessing data to be used.
-gnateD specifies or modifies the values of preprocessing symbol.

It is recommended that gnatmake switch -s should be
used when Integrated Preprocessing is used. The reason is that preprocessing
with another Preprocessing Data file without changing the sources will
not trigger recompilation without this switch.

Note that gnatmake switch -m will almost
always trigger recompilation for sources that are preprocessed,
because gnatmake cannot compute the checksum of the source after
preprocessing.

The actual preprocessing function is described in details in section
Preprocessing Using gnatprep. This section only describes how integrated
preprocessing is triggered and parameterized.

-gnatep=file

This switch indicates to the compiler the file name (without directory
information) of the preprocessor data file to use. The preprocessor data file
should be found in the source directories.

A preprocessing data file is a text file with significant lines indicating
how should be preprocessed either a specific source or all sources not
mentioned in other lines. A significant line is a non empty, non comment line.
Comments are similar to Ada comments.

Each significant line starts with either a literal string or the character '*'.
A literal string is the file name (without directory information) of the source
to preprocess. A character '*' indicates the preprocessing for all the sources
that are not specified explicitly on other lines (order of the lines is not
significant). It is an error to have two lines with the same file name or two
lines starting with the character '*'.

After the file name or the character '*', another optional literal string
indicating the file name of the definition file to be used for preprocessing
(see Form of Definitions File). The definition files are found by the
compiler in one of the source directories. In some cases, when compiling
a source in a directory other than the current directory, if the definition
file is in the current directory, it may be necessary to add the current
directory as a source directory through switch -I., otherwise
the compiler would not find the definition file.

Then, optionally, switches similar to those of gnatprep may
be found. Those switches are:

-b

Causes both preprocessor lines and the lines deleted by
preprocessing to be replaced by blank lines, preserving the line number.
This switch is always implied; however, if specified after -c
it cancels the effect of -c.

-c

Causes both preprocessor lines and the lines deleted
by preprocessing to be retained as comments marked
with the special string “--! ”.

-Dsymbol=value

Define or redefine a symbol, associated with value. A symbol is an Ada
identifier, or an Ada reserved word, with the exception of if,
else, elsif, end, and, or and then.
value is either a literal string, an Ada identifier or any Ada reserved
word. A symbol declared with this switch replaces a symbol with the
same name defined in a definition file.

-s

Causes a sorted list of symbol names and values to be
listed on the standard output file.

-u

Causes undefined symbols to be treated as having the value FALSE
in the context
of a preprocessor test. In the absence of this option, an undefined symbol in
a #if or #elsif test will be treated as an error.

Define or redefine a preprocessing symbol, associated with value. If no value
is given on the command line, then the value of the symbol is True.
A symbol is an identifier, following normal Ada (case-insensitive)
rules for its syntax, and value is any sequence (including an empty sequence)
of characters from the set (letters, digits, period, underline).
Ada reserved words may be used as symbols, with the exceptions of if,
else, elsif, end, and, or and then.

A symbol declared with this switch on the command line replaces a
symbol with the same name either in a definition file or specified with a
switch -D in the preprocessor data file.