7.6.7 Options for Controlling the Preprocessor

Table 7-14. Preprocessor Options
Option	Definition
`-Aquestion (answer)`	Assert the answer `answer` for question `question`, in case it is tested with a preprocessing conditional such as `#if #question(answer)`. `-A-` disables the standard assertions that normally describe the target machine. For example, the function prototype for main might be declared as follows: `#if #environ(freestanding) int main(void); #else int main(int argc, char *argv[]); #endif` A `-A` command-line option could then be used to select between the two prototypes. For example, to select the first of the two, the following command-line option could be used: `-Aenviron(freestanding)`
`-A -predicate =answer`	Cancel an assertion with the predicate `predicate` and answer `answer`.
`-A predicate =answer`	Make an assertion with the predicate `predicate` and answer `answer`. This form is preferred to the older form `-A predicate(answer)`, which is still supported, because it does not use shell special characters.
`-C`	Tell the preprocessor not to discard comments. Used with the `-E` option.
`-dD`	Tell the preprocessor to not remove macro definitions into the output, in their proper sequence.
`-Dmacro`	Define macro `macro` with the string 1 as its definition.
`-Dmacro=defn`	Define macro `macro` as `defn`. All instances of `-D` on the command line are processed before any `-U` options.
`-dM`	Tell the preprocessor to output only a list of the macro definitions that are in effect at the end of preprocessing. Used with the `-E` option.
`-dN`	Like `-dD` except that the macro arguments and contents are omitted. Only `#define name` is included in the output.
`-fno-show-column`	Do not print column numbers in diagnostics. This may be necessary if diagnostics are being scanned by a program that does not understand the column numbers, such as dejagnu.
`-H`	Print the name of each header file used, in addition to other normal activities.
`-iquote`, `-I-`	Any directories you specify with `-I` options before the `-iquote` options are searched only for the case of `#include "file"`; they are not searched for `#include <file>`. If additional directories are specified with `-I` options after the `-iquote`, these directories are searched for all `#include` directives (ordinarily all `-I` directories are used this way). In addition, the `iquote` option inhibits the use of the current directory (where the current input file came from) as the first search directory for `#include "file"`. There is no way to override this effect of `iquote`. With `-I.` you can specify searching the directory that was current when the compiler was invoked. That is not exactly the same as what the preprocessor does by default, but it is often satisfactory. `iquote` does not inhibit the use of the standard system directories for header files. Thus, `iquote` and `-nostdinc` are independent.
`-Idir`	Add the directory `dir` to the head of the list of directories to be searched for header files. This can be used to override a system header file, substituting your own version, since these directories are searched before the system header file directories. If you use more than one `-I` option, the directories are scanned in left-to-right order; the standard system directories come after.
`-idirafter dir`	Add the directory `dir` to the second include path. The directories on the second include path are searched when a header file is not found in any of the directories in the main include path (the directory that `-I` adds within).
`-imacros file`	Process file as input, discarding the resulting output, before processing the regular input file. Because the output generated from the file is discarded, the only effect of `-imacros file` is to make the macros defined in file available for use in the main input. Any `-D` and `-U` options on the command line are always processed before `-imacros file`, regardless of the order in which they are written. All the `-include` and  `-imacros` options are processed in the order in which they are written.
`-include file`	Process file as input before processing the regular input file. In effect, the contents of file are compiled first. Any `-D` and `-U` options on the command line are always processed before `-include file`, regardless of the order in which they are written. All the `-include` and `-imacros` options are processed in the order in which they are written.
`-iprefix prefix`	Specify `prefix` as the prefix for subsequent `-iwithprefix` options.
`-isystem dir`	Add a directory to the beginning of the second include path, marking it as a system directory, so that it gets the same special treatment as is applied to the standard system directories.
`-iwithprefix dir`	Add a directory to the second include path. The directory’s name is made by concatenating prefix and `dir`, where prefix was specified previously with `-iprefix`. If a prefix has not yet been specified, the directory containing the installed passes of the compiler is used as the default.
`-iwithprefixbefore dir`	Add a directory to the main include path. The directory’s name is made by concatenating prefix and `dir`, as in the case of `-iwithprefix`.
`-M`	Tell the preprocessor to output a rule suitable for `make` describing the dependencies of each object file. For each source file, the preprocessor outputs one make-rule whose target is the object file name for that source file and whose dependencies are all the `#include` header files it uses. This rule may be a single line or may be continued with `\`-newline if it is long. The list of rules is printed on standard output instead of the preprocessed C program. `-M` implies `-E` (see the Options for Controlling the Kind of Output section).
`-MD`	Like `-M` but the dependency information is written to a file and compilation continues. The file containing the dependency information is given the same name as the source file with a `.d` extension.
`-MF file`	When used with `-M` or `-MM`, specifies a file in which to write the dependencies. If no `-MF` switch is given, the preprocessor sends the rules to the same place it would have sent preprocessed output. When used with the driver options, `-MD` or `-MMD`, `-MF`, overrides the default dependency output file.
`-MG`	Treat missing header files as generated files and assume they live in the same directory as the source file. If `-MG` is specified, then either `-M` or `-MM` must also be specified. `-MG` is not supported with `-MD` or `-MMD`.
`-MM`	Like `-M` but the output mentions only the user header files included with `#include “file”`. System header files included with `#include <file>` are omitted.
`-MMD`	Like `-MD` except mention only user header files, not system header files.
`-MP`	This option instructs CPP to add a phony target for each dependency other than the main file, causing each to depend on nothing. These dummy rules work around errors `make` gives if you remove header files without updating the make-file to match. This is typical output: `test.o: test.c test.h` `test.h:`
`-MQ`	Same as `-MT`, but it quotes any characters which are special to `make`. `-MQ '$(objpfx)foo.o'` gives `$$(objpfx)foo.o: foo.c` The default target is automatically quoted, as if it were given with `-MQ`.
`-MT target`	Change the target of the rule emitted by dependency generation. By default, CPP takes the name of the main input file, including any path, deletes any file suffix such as `.c`, and appends the platform’s usual object suffix. The result is the target. An `-MT` option will set the target to be exactly the string you specify. If you want multiple targets, you can specify them as a single argument to `-MT`, or use multiple `-MT` options. For example: `-MT '$(objpfx)foo.o'` might give `$(objpfx)foo.o: foo.c`
`-nostdinc`	Do not search the standard system directories for header files. Only the directories you have specified with `-I` options (and the current directory, if appropriate) are searched. See Options for Directory Search for information on `-I`. By using both `-nostdinc` and `-I-`, the include-file search path can be limited to only those directories explicitly specified.
`-P`	Tell the preprocessor not to generate `#line` directives. Used with the `-E` option (see theOptions for Controlling the Kind of Output section).
`-trigraphs`	Support ANSI C trigraphs. The `-ansi` option also has this effect.
`-Umacro`	Undefine macro `macro`. `-U` options are evaluated after all `-D` options, but before any `-include` and `-imacros` options.
`-undef`	Do not predefine any nonstandard macros (including architecture flags).

-Aquestion
                            (answer)

Assert the answer answer for question question, in case it is tested with a preprocessing conditional such as

#if
                                    #question(answer)

. -A- disables the standard assertions that normally describe the target machine.

For example, the function prototype for main might be declared as follows:

#if #environ(freestanding)
int main(void);
#else
int main(int argc, char *argv[]);
#endif

A -A command-line option could then be used to select between the two prototypes. For example, to select the first of the two, the following command-line option could be used:

-Aenviron(freestanding)

-A -predicate
                            =answer

Cancel an assertion with the predicate predicate and answer answer.

-A predicate
                            =answer

Make an assertion with the predicate predicate and answer answer. This form is preferred to the older form -A predicate(answer), which is still supported, because it does not use shell special characters.

-C

Tell the preprocessor not to discard comments. Used with the -E option.

-dD

Tell the preprocessor to not remove macro definitions into the output, in their proper sequence.

-Dmacro

Define macro macro with the string 1 as its definition.

-Dmacro=defn

Define macro macro as defn. All instances of -D on the command line are processed before any -U options.

-dM

Tell the preprocessor to output only a list of the macro definitions that are in effect at the end of preprocessing. Used with the -E option.

-dN

Like -dD except that the macro arguments and contents are omitted. Only

#define
                                name

is included in the output.

-fno-show-column

Do not print column numbers in diagnostics. This may be necessary if diagnostics are being scanned by a program that does not understand the column numbers, such as dejagnu.

-H

Print the name of each header file used, in addition to other normal activities.

-iquote, -I-

Any directories you specify with -I options before the -iquote options are searched only for the case of

#include
                                "file"

; they are not searched for

#include
                                    <file>

.

If additional directories are specified with -I options after the -iquote, these directories are searched for all #include directives (ordinarily all -I directories are used this way).

In addition, the iquote option inhibits the use of the current directory (where the current input file came from) as the first search directory for #include "file". There is no way to override this effect of iquote. With -I. you can specify searching the directory that was current when the compiler was invoked. That is not exactly the same as what the preprocessor does by default, but it is often satisfactory.

iquote does not inhibit the use of the standard system directories for header files. Thus, iquote and -nostdinc are independent.

-Idir

Add the directory dir to the head of the list of directories to be searched for header files. This can be used to override a system header file, substituting your own version, since these directories are searched before the system header file directories. If you use more than one -I option, the directories are scanned in left-to-right order; the standard system directories come after.

-idirafter
                            dir

Add the directory dir to the second include path. The directories on the second include path are searched when a header file is not found in any of the directories in the main include path (the directory that -I adds within).

-imacros
                            file

Process file as input, discarding the resulting output, before processing the regular input file. Because the output generated from the file is discarded, the only effect of -imacros file is to make the macros defined in file available for use in the main input.

Any -D and -U options on the command line are always processed before -imacros file, regardless of the order in which they are written. All the -include and  -imacros options are processed in the order in which they are written.

-include
                            file

Process file as input before processing the regular input file. In effect, the contents of file are compiled first. Any -D and -U options on the command line are always processed before

-include
                                file

, regardless of the order in which they are written. All the -include and -imacros options are processed in the order in which they are written.

-iprefix
                            prefix

Specify prefix as the prefix for subsequent -iwithprefix options.

-isystem
                            dir

Add a directory to the beginning of the second include path, marking it as a system directory, so that it gets the same special treatment as is applied to the standard system directories.

-iwithprefix
                                dir

Add a directory to the second include path. The directory’s name is made by concatenating prefix and dir, where prefix was specified previously with -iprefix. If a prefix has not yet been specified, the directory containing the installed passes of the compiler is used as the default.

-iwithprefixbefore
                                dir

Add a directory to the main include path. The directory’s name is made by concatenating prefix and dir, as in the case of -iwithprefix.

-M

Tell the preprocessor to output a rule suitable for make describing the dependencies of each object file. For each source file, the preprocessor outputs one make-rule whose target is the object file name for that source file and whose dependencies are all the #include header files it uses. This rule may be a single line or may be continued with \-newline if it is long. The list of rules is printed on standard output instead of the preprocessed C program.

-M implies -E (see the Options for Controlling the Kind of Output section).

-MD

Like -M but the dependency information is written to a file and compilation continues. The file containing the dependency information is given the same name as the source file with a .d extension.

-MF file

When used with -M or -MM, specifies a file in which to write the dependencies. If no -MF switch is given, the preprocessor sends the rules to the same place it would have sent preprocessed output.

When used with the driver options, -MD or -MMD, -MF, overrides the default dependency output file.

-MG

Treat missing header files as generated files and assume they live in the same directory as the source file. If -MG is specified, then either -M or -MM must also be specified. -MG is not supported with -MD or -MMD.

-MM

Like -M but the output mentions only the user header files included with

#include
                                    “file”

. System header files included with #include <file> are omitted.

-MMD

Like -MD except mention only user header files, not system header files.

-MP

This option instructs CPP to add a phony target for each dependency other than the main file, causing each to depend on nothing. These dummy rules work around errors make gives if you remove header files without updating the make-file to match.

This is typical output:

test.o: test.c test.h

test.h:

-MQ

Same as -MT, but it quotes any characters which are special to make.

-MQ '$(objpfx)foo.o' gives $$(objpfx)foo.o: foo.c

The default target is automatically quoted, as if it were given with -MQ.

-MT target

Change the target of the rule emitted by dependency generation. By default, CPP takes the name of the main input file, including any path, deletes any file suffix such as .c, and appends the platform’s usual object suffix. The result is the target.

An -MT option will set the target to be exactly the string you specify. If you want multiple targets, you can specify them as a single argument to -MT, or use multiple -MT options.

For example:

-MT '$(objpfx)foo.o' might give $(objpfx)foo.o: foo.c

-nostdinc

Do not search the standard system directories for header files. Only the directories you have specified with -I options (and the current directory, if appropriate) are searched. See Options for Directory Search for information on -I.

By using both -nostdinc and -I-, the include-file search path can be limited to only those directories explicitly specified.

-P

Tell the preprocessor not to generate #line directives. Used with the -E option (see theOptions for Controlling the Kind of Output section).

-trigraphs

Support ANSI C trigraphs. The -ansi option also has this effect.

-Umacro

Undefine macro macro. -U options are evaluated after all -D options, but before any -include and -imacros options.

-undef

Do not predefine any nonstandard macros (including architecture flags).