3.2.17 Integrated Preprocessing

GNAT sources may be preprocessed immediately before compilation. In this case, 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.

Note that when integrated preprocessing is used, the output from the preprocessor is not written to any external file. Instead it is passed internally to the compiler. If you need to preserve the result of preprocessing in a file, then you should use gnatprep to perform the desired preprocessing in stand-alone mode.

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. Note that when the compiler is called by a builder (gnatmake or gprbuild) with a project file, if the object directory is not also a source directory, the builder needs to be called with -x.

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 nonempty, 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.

Examples of valid lines in a preprocessor data file:

            "toto.adb"  "prep.def" -u
            --  preprocess "toto.adb", using definition file "prep.def",
            --  undefined symbol are False.
          
            * -c -DVERSION=V101
            --  preprocess all other sources without a definition file;
            --  suppressed lined are commented; symbol VERSION has the value V101.
          
            "titi.adb" "prep2.def" -s
            --  preprocess "titi.adb", using definition file "prep2.def";
            --  list all symbols with their values.

-gnateDsymbol[=value]

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.

This switch is similar to switch -D of gnatprep.

-gnateG

When integrated preprocessing is performed and the preprocessor modifies the source text, write the result of this preprocessing into a file <source>.prep.