gcc: Preprocessor Options
1
1 3.12 Options Controlling the Preprocessor
1 =========================================
1
1 These options control the C preprocessor, which is run on each C source
1 file before actual compilation.
1
1 If you use the '-E' option, nothing is done except preprocessing. Some
1 of these options make sense only together with '-E' because they cause
1 the preprocessor output to be unsuitable for actual compilation.
1
1 In addition to the options listed here, there are a number of options
11 to control search paths for include files documented in ⇒Directory
Options. Options to control preprocessor diagnostics are listed in
1 ⇒Warning Options.
1
1 '-D NAME'
1 Predefine NAME as a macro, with definition '1'.
1
1 '-D NAME=DEFINITION'
1 The contents of DEFINITION are tokenized and processed as if they
1 appeared during translation phase three in a '#define' directive.
1 In particular, the definition is truncated by embedded newline
1 characters.
1
1 If you are invoking the preprocessor from a shell or shell-like
1 program you may need to use the shell's quoting syntax to protect
1 characters such as spaces that have a meaning in the shell syntax.
1
1 If you wish to define a function-like macro on the command line,
1 write its argument list with surrounding parentheses before the
1 equals sign (if any). Parentheses are meaningful to most shells,
1 so you should quote the option. With 'sh' and 'csh',
1 '-D'NAME(ARGS...)=DEFINITION'' works.
1
1 '-D' and '-U' options are processed in the order they are given on
1 the command line. All '-imacros FILE' and '-include FILE' options
1 are processed after all '-D' and '-U' options.
1
1 '-U NAME'
1 Cancel any previous definition of NAME, either built in or provided
1 with a '-D' option.
1
1 '-include FILE'
1 Process FILE as if '#include "file"' appeared as the first line of
1 the primary source file. However, the first directory searched for
1 FILE is the preprocessor's working directory _instead of_ the
1 directory containing the main source file. If not found there, it
1 is searched for in the remainder of the '#include "..."' search
1 chain as normal.
1
1 If multiple '-include' options are given, the files are included in
1 the order they appear on the command line.
1
1 '-imacros FILE'
1 Exactly like '-include', except that any output produced by
1 scanning FILE is thrown away. Macros it defines remain defined.
1 This allows you to acquire all the macros from a header without
1 also processing its declarations.
1
1 All files specified by '-imacros' are processed before all files
1 specified by '-include'.
1
1 '-undef'
1 Do not predefine any system-specific or GCC-specific macros. The
1 standard predefined macros remain defined.
1
1 '-pthread'
1 Define additional macros required for using the POSIX threads
1 library. You should use this option consistently for both
1 compilation and linking. This option is supported on GNU/Linux
1 targets, most other Unix derivatives, and also on x86 Cygwin and
1 MinGW targets.
1
1 '-M'
1 Instead of outputting the result of preprocessing, output a rule
1 suitable for 'make' describing the dependencies of the main source
1 file. The preprocessor outputs one 'make' rule containing the
1 object file name for that source file, a colon, and the names of
1 all the included files, including those coming from '-include' or
1 '-imacros' command-line options.
1
1 Unless specified explicitly (with '-MT' or '-MQ'), the object file
1 name consists of the name of the source file with any suffix
1 replaced with object file suffix and with any leading directory
1 parts removed. If there are many included files then the rule is
1 split into several lines using '\'-newline. The rule has no
1 commands.
1
1 This option does not suppress the preprocessor's debug output, such
1 as '-dM'. To avoid mixing such debug output with the dependency
1 rules you should explicitly specify the dependency output file with
1 '-MF', or use an environment variable like 'DEPENDENCIES_OUTPUT'
1 (⇒Environment Variables). Debug output is still sent to the
1 regular output stream as normal.
1
1 Passing '-M' to the driver implies '-E', and suppresses warnings
1 with an implicit '-w'.
1
1 '-MM'
1 Like '-M' but do not mention header files that are found in system
1 header directories, nor header files that are included, directly or
1 indirectly, from such a header.
1
1 This implies that the choice of angle brackets or double quotes in
1 an '#include' directive does not in itself determine whether that
1 header appears in '-MM' dependency output.
1
1 '-MF FILE'
1 When used with '-M' or '-MM', specifies a file to write the
1 dependencies to. If no '-MF' switch is given the preprocessor
1 sends the rules to the same place it would send preprocessed
1 output.
1
1 When used with the driver options '-MD' or '-MMD', '-MF' overrides
1 the default dependency output file.
1
1 If FILE is '-', then the dependencies are written to 'stdout'.
1
1 '-MG'
1 In conjunction with an option such as '-M' requesting dependency
1 generation, '-MG' assumes missing header files are generated files
1 and adds them to the dependency list without raising an error. The
1 dependency filename is taken directly from the '#include' directive
1 without prepending any path. '-MG' also suppresses preprocessed
1 output, as a missing header file renders this useless.
1
1 This feature is used in automatic updating of makefiles.
1
1 '-MP'
1 This option instructs CPP to add a phony target for each dependency
1 other than the main file, causing each to depend on nothing. These
1 dummy rules work around errors 'make' gives if you remove header
1 files without updating the 'Makefile' to match.
1
1 This is typical output:
1
1 test.o: test.c test.h
1
1 test.h:
1
1 '-MT TARGET'
1
1 Change the target of the rule emitted by dependency generation. By
1 default CPP takes the name of the main input file, deletes any
1 directory components and any file suffix such as '.c', and appends
1 the platform's usual object suffix. The result is the target.
1
1 An '-MT' option sets the target to be exactly the string you
1 specify. If you want multiple targets, you can specify them as a
1 single argument to '-MT', or use multiple '-MT' options.
1
1 For example, '-MT '$(objpfx)foo.o'' might give
1
1 $(objpfx)foo.o: foo.c
1
1 '-MQ TARGET'
1
1 Same as '-MT', but it quotes any characters which are special to
1 Make. '-MQ '$(objpfx)foo.o'' gives
1
1 $$(objpfx)foo.o: foo.c
1
1 The default target is automatically quoted, as if it were given
1 with '-MQ'.
1
1 '-MD'
1 '-MD' is equivalent to '-M -MF FILE', except that '-E' is not
1 implied. The driver determines FILE based on whether an '-o'
1 option is given. If it is, the driver uses its argument but with a
1 suffix of '.d', otherwise it takes the name of the input file,
1 removes any directory components and suffix, and applies a '.d'
1 suffix.
1
1 If '-MD' is used in conjunction with '-E', any '-o' switch is
11 understood to specify the dependency output file (⇒-MF
dashMF.), but if used without '-E', each '-o' is understood to
1 specify a target object file.
1
1 Since '-E' is not implied, '-MD' can be used to generate a
1 dependency output file as a side effect of the compilation process.
1
1 '-MMD'
1 Like '-MD' except mention only user header files, not system header
1 files.
1
1 '-fpreprocessed'
1 Indicate to the preprocessor that the input file has already been
1 preprocessed. This suppresses things like macro expansion,
1 trigraph conversion, escaped newline splicing, and processing of
1 most directives. The preprocessor still recognizes and removes
1 comments, so that you can pass a file preprocessed with '-C' to the
1 compiler without problems. In this mode the integrated
1 preprocessor is little more than a tokenizer for the front ends.
1
1 '-fpreprocessed' is implicit if the input file has one of the
1 extensions '.i', '.ii' or '.mi'. These are the extensions that GCC
1 uses for preprocessed files created by '-save-temps'.
1
1 '-fdirectives-only'
1 When preprocessing, handle directives, but do not expand macros.
1
1 The option's behavior depends on the '-E' and '-fpreprocessed'
1 options.
1
1 With '-E', preprocessing is limited to the handling of directives
1 such as '#define', '#ifdef', and '#error'. Other preprocessor
1 operations, such as macro expansion and trigraph conversion are not
1 performed. In addition, the '-dD' option is implicitly enabled.
1
1 With '-fpreprocessed', predefinition of command line and most
1 builtin macros is disabled. Macros such as '__LINE__', which are
1 contextually dependent, are handled normally. This enables
1 compilation of files previously preprocessed with '-E
1 -fdirectives-only'.
1
1 With both '-E' and '-fpreprocessed', the rules for '-fpreprocessed'
1 take precedence. This enables full preprocessing of files
1 previously preprocessed with '-E -fdirectives-only'.
1
1 '-fdollars-in-identifiers'
1 Accept '$' in identifiers.
1
1 '-fextended-identifiers'
1 Accept universal character names in identifiers. This option is
1 enabled by default for C99 (and later C standard versions) and C++.
1
1 '-fno-canonical-system-headers'
1 When preprocessing, do not shorten system header paths with
1 canonicalization.
1
1 '-ftabstop=WIDTH'
1 Set the distance between tab stops. This helps the preprocessor
1 report correct column numbers in warnings or errors, even if tabs
1 appear on the line. If the value is less than 1 or greater than
1 100, the option is ignored. The default is 8.
1
1 '-ftrack-macro-expansion[=LEVEL]'
1 Track locations of tokens across macro expansions. This allows the
1 compiler to emit diagnostic about the current macro expansion stack
1 when a compilation error occurs in a macro expansion. Using this
1 option makes the preprocessor and the compiler consume more memory.
1 The LEVEL parameter can be used to choose the level of precision of
1 token location tracking thus decreasing the memory consumption if
1 necessary. Value '0' of LEVEL de-activates this option. Value '1'
1 tracks tokens locations in a degraded mode for the sake of minimal
1 memory overhead. In this mode all tokens resulting from the
1 expansion of an argument of a function-like macro have the same
1 location. Value '2' tracks tokens locations completely. This
1 value is the most memory hungry. When this option is given no
1 argument, the default parameter value is '2'.
1
1 Note that '-ftrack-macro-expansion=2' is activated by default.
1
1 '-fmacro-prefix-map=OLD=NEW'
1 When preprocessing files residing in directory 'OLD', expand the
1 '__FILE__' and '__BASE_FILE__' macros as if the files resided in
1 directory 'NEW' instead. This can be used to change an absolute
1 path to a relative path by using '.' for NEW which can result in
1 more reproducible builds that are location independent. This
1 option also affects '__builtin_FILE()' during compilation. See
1 also '-ffile-prefix-map'.
1
1 '-fexec-charset=CHARSET'
1 Set the execution character set, used for string and character
1 constants. The default is UTF-8. CHARSET can be any encoding
1 supported by the system's 'iconv' library routine.
1
1 '-fwide-exec-charset=CHARSET'
1 Set the wide execution character set, used for wide string and
1 character constants. The default is UTF-32 or UTF-16, whichever
1 corresponds to the width of 'wchar_t'. As with '-fexec-charset',
1 CHARSET can be any encoding supported by the system's 'iconv'
1 library routine; however, you will have problems with encodings
1 that do not fit exactly in 'wchar_t'.
1
1 '-finput-charset=CHARSET'
1 Set the input character set, used for translation from the
1 character set of the input file to the source character set used by
1 GCC. If the locale does not specify, or GCC cannot get this
1 information from the locale, the default is UTF-8. This can be
1 overridden by either the locale or this command-line option.
1 Currently the command-line option takes precedence if there's a
1 conflict. CHARSET can be any encoding supported by the system's
1 'iconv' library routine.
1
1 '-fpch-deps'
1 When using precompiled headers (⇒Precompiled Headers), this
1 flag causes the dependency-output flags to also list the files from
1 the precompiled header's dependencies. If not specified, only the
1 precompiled header are listed and not the files that were used to
1 create it, because those files are not consulted when a precompiled
1 header is used.
1
1 '-fpch-preprocess'
11 This option allows use of a precompiled header (⇒Precompiled
Headers) together with '-E'. It inserts a special '#pragma',
1 '#pragma GCC pch_preprocess "FILENAME"' in the output to mark the
1 place where the precompiled header was found, and its FILENAME.
1 When '-fpreprocessed' is in use, GCC recognizes this '#pragma' and
1 loads the PCH.
1
1 This option is off by default, because the resulting preprocessed
1 output is only really suitable as input to GCC. It is switched on
1 by '-save-temps'.
1
1 You should not write this '#pragma' in your own code, but it is
1 safe to edit the filename if the PCH file is available in a
1 different location. The filename may be absolute or it may be
1 relative to GCC's current directory.
1
1 '-fworking-directory'
1 Enable generation of linemarkers in the preprocessor output that
1 let the compiler know the current working directory at the time of
1 preprocessing. When this option is enabled, the preprocessor
1 emits, after the initial linemarker, a second linemarker with the
1 current working directory followed by two slashes. GCC uses this
1 directory, when it's present in the preprocessed input, as the
1 directory emitted as the current working directory in some
1 debugging information formats. This option is implicitly enabled
1 if debugging information is enabled, but this can be inhibited with
1 the negated form '-fno-working-directory'. If the '-P' flag is
1 present in the command line, this option has no effect, since no
1 '#line' directives are emitted whatsoever.
1
1 '-A PREDICATE=ANSWER'
1 Make an assertion with the predicate PREDICATE and answer ANSWER.
1 This form is preferred to the older form '-A PREDICATE(ANSWER)',
1 which is still supported, because it does not use shell special
1 characters.
1
1 '-A -PREDICATE=ANSWER'
1 Cancel an assertion with the predicate PREDICATE and answer ANSWER.
1
1 '-C'
1 Do not discard comments. All comments are passed through to the
1 output file, except for comments in processed directives, which are
1 deleted along with the directive.
1
1 You should be prepared for side effects when using '-C'; it causes
1 the preprocessor to treat comments as tokens in their own right.
1 For example, comments appearing at the start of what would be a
1 directive line have the effect of turning that line into an
1 ordinary source line, since the first token on the line is no
1 longer a '#'.
1
1 '-CC'
1 Do not discard comments, including during macro expansion. This is
1 like '-C', except that comments contained within macros are also
1 passed through to the output file where the macro is expanded.
1
1 In addition to the side effects of the '-C' option, the '-CC'
1 option causes all C++-style comments inside a macro to be converted
1 to C-style comments. This is to prevent later use of that macro
1 from inadvertently commenting out the remainder of the source line.
1
1 The '-CC' option is generally used to support lint comments.
1
1 '-P'
1 Inhibit generation of linemarkers in the output from the
1 preprocessor. This might be useful when running the preprocessor
1 on something that is not C code, and will be sent to a program
1 which might be confused by the linemarkers.
1
1 '-traditional'
1 '-traditional-cpp'
1
1 Try to imitate the behavior of pre-standard C preprocessors, as
1 opposed to ISO C preprocessors. See the GNU CPP manual for
1 details.
1
1 Note that GCC does not otherwise attempt to emulate a pre-standard
1 C compiler, and these options are only supported with the '-E'
1 switch, or when invoking CPP explicitly.
1
1 '-trigraphs'
1 Support ISO C trigraphs. These are three-character sequences, all
1 starting with '??', that are defined by ISO C to stand for single
1 characters. For example, '??/' stands for '\', so ''??/n'' is a
1 character constant for a newline.
1
1 The nine trigraphs and their replacements are
1
1 Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??-
1 Replacement: [ ] { } # \ ^ | ~
1
1 By default, GCC ignores trigraphs, but in standard-conforming modes
1 it converts them. See the '-std' and '-ansi' options.
1
1 '-remap'
1 Enable special code to work around file systems which only permit
1 very short file names, such as MS-DOS.
1
1 '-H'
1 Print the name of each header file used, in addition to other
1 normal activities. Each name is indented to show how deep in the
1 '#include' stack it is. Precompiled header files are also printed,
1 even if they are found to be invalid; an invalid precompiled header
1 file is printed with '...x' and a valid one with '...!' .
1
1 '-dLETTERS'
1 Says to make debugging dumps during compilation as specified by
1 LETTERS. The flags documented here are those relevant to the
1 preprocessor. Other LETTERS are interpreted by the compiler
1 proper, or reserved for future versions of GCC, and so are silently
1 ignored. If you specify LETTERS whose behavior conflicts, the
1 result is undefined. ⇒Developer Options, for more
1 information.
1
1 '-dM'
1 Instead of the normal output, generate a list of '#define'
1 directives for all the macros defined during the execution of
1 the preprocessor, including predefined macros. This gives you
1 a way of finding out what is predefined in your version of the
1 preprocessor. Assuming you have no file 'foo.h', the command
1
1 touch foo.h; cpp -dM foo.h
1
1 shows all the predefined macros.
1
1 If you use '-dM' without the '-E' option, '-dM' is interpreted
11 as a synonym for '-fdump-rtl-mach'. ⇒(gcc)Developer
Options.
1
1 '-dD'
1 Like '-dM' except in two respects: it does _not_ include the
1 predefined macros, and it outputs _both_ the '#define'
1 directives and the result of preprocessing. Both kinds of
1 output go to the standard output file.
1
1 '-dN'
1 Like '-dD', but emit only the macro names, not their
1 expansions.
1
1 '-dI'
1 Output '#include' directives in addition to the result of
1 preprocessing.
1
1 '-dU'
1 Like '-dD' except that only macros that are expanded, or whose
1 definedness is tested in preprocessor directives, are output;
1 the output is delayed until the use or test of the macro; and
1 '#undef' directives are also output for macros tested but
1 undefined at the time.
1
1 '-fdebug-cpp'
1 This option is only useful for debugging GCC. When used from CPP or
1 with '-E', it dumps debugging information about location maps.
1 Every token in the output is preceded by the dump of the map its
1 location belongs to.
1
1 When used from GCC without '-E', this option has no effect.
1
1 '-Wp,OPTION'
1 You can use '-Wp,OPTION' to bypass the compiler driver and pass
1 OPTION directly through to the preprocessor. If OPTION contains
1 commas, it is split into multiple options at the commas. However,
1 many options are modified, translated or interpreted by the
1 compiler driver before being passed to the preprocessor, and '-Wp'
1 forcibly bypasses this phase. The preprocessor's direct interface
1 is undocumented and subject to change, so whenever possible you
1 should avoid using '-Wp' and let the driver handle the options
1 instead.
1
1 '-Xpreprocessor OPTION'
1 Pass OPTION as an option to the preprocessor. You can use this to
1 supply system-specific preprocessor options that GCC does not
1 recognize.
1
1 If you want to pass an option that takes an argument, you must use
1 '-Xpreprocessor' twice, once for the option and once for the
1 argument.
1
1 '-no-integrated-cpp'
1 Perform preprocessing as a separate pass before compilation. By
1 default, GCC performs preprocessing as an integrated part of input
1 tokenization and parsing. If this option is provided, the
1 appropriate language front end ('cc1', 'cc1plus', or 'cc1obj' for
1 C, C++, and Objective-C, respectively) is instead invoked twice,
1 once for preprocessing only and once for actual compilation of the
1 preprocessed input. This option may be useful in conjunction with
1 the '-B' or '-wrapper' options to specify an alternate preprocessor
1 or perform additional processing of the program source between
1 normal preprocessing and compilation.
1