cpp: Invocation
1
1 12 Invocation
1 *************
1
1 Most often when you use the C preprocessor you do not have to invoke it
1 explicitly: the C compiler does so automatically. However, the
1 preprocessor is sometimes useful on its own. You can invoke the
1 preprocessor either with the 'cpp' command, or via 'gcc -E'. In GCC,
1 the preprocessor is actually integrated with the compiler rather than a
1 separate program, and both of these commands invoke GCC and tell it to
1 stop after the preprocessing phase.
1
1 The 'cpp' options listed here are also accepted by 'gcc' and have the
1 same meaning. Likewise the 'cpp' command accepts all the usual 'gcc'
1 driver options, although those pertaining to compilation phases after
1 preprocessing are ignored.
1
1 Only options specific to preprocessing behavior are documented here.
1 Refer to the GCC manual for full documentation of other driver options.
1
1 The 'cpp' command expects two file names as arguments, INFILE and
1 OUTFILE. The preprocessor reads INFILE together with any other files it
1 specifies with '#include'. All the output generated by the combined
1 input files is written in OUTFILE.
1
1 Either INFILE or OUTFILE may be '-', which as INFILE means to read
1 from standard input and as OUTFILE means to write to standard output.
1 If either file is omitted, it means the same as if '-' had been
1 specified for that file. You can also use the '-o OUTFILE' option to
1 specify the output file.
1
1 Unless otherwise noted, or the option ends in '=', all options which
1 take an argument may have that argument appear either immediately after
1 the option, or with a space between option and argument: '-Ifoo' and '-I
1 foo' have the same effect.
1
1 Many options have multi-letter names; therefore multiple
1 single-letter options may _not_ be grouped: '-dM' is very different from
1 '-d -M'.
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
11 standard predefined macros remain defined. ⇒Standard
Predefined Macros.
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. ⇒Identifier characters.
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 '-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. ⇒Obsolete Features.
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
11 which might be confused by the linemarkers. ⇒Preprocessor
Output.
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. ⇒Traditional Mode.
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. ⇒Initial processing.
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.
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 '-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 '-I DIR'
1 '-iquote DIR'
1 '-isystem DIR'
1 '-idirafter DIR'
1 Add the directory DIR to the list of directories to be searched for
1 header files during preprocessing. ⇒Search Path. If DIR
1 begins with '=' or '$SYSROOT', then the '=' or '$SYSROOT' is
1 replaced by the sysroot prefix; see '--sysroot' and '-isysroot'.
1
1 Directories specified with '-iquote' apply only to the quote form
1 of the directive, '#include "FILE"'. Directories specified with
1 '-I', '-isystem', or '-idirafter' apply to lookup for both the
1 '#include "FILE"' and '#include <FILE>' directives.
1
1 You can specify any number or combination of these options on the
1 command line to search for header files in several directories.
1 The lookup order is as follows:
1
1 1. For the quote form of the include directive, the directory of
1 the current file is searched first.
1
1 2. For the quote form of the include directive, the directories
1 specified by '-iquote' options are searched in left-to-right
1 order, as they appear on the command line.
1
1 3. Directories specified with '-I' options are scanned in
1 left-to-right order.
1
1 4. Directories specified with '-isystem' options are scanned in
1 left-to-right order.
1
1 5. Standard system directories are scanned.
1
1 6. Directories specified with '-idirafter' options are scanned in
1 left-to-right order.
1
1 You can use '-I' to override a system header file, substituting
1 your own version, since these directories are searched before the
1 standard system header file directories. However, you should not
1 use this option to add directories that contain vendor-supplied
1 system header files; use '-isystem' for that.
1
1 The '-isystem' and '-idirafter' options also mark the directory as
1 a system directory, so that it gets the same special treatment that
11 is applied to the standard system directories. ⇒System
Headers.
1
1 If a standard system include directory, or a directory specified
1 with '-isystem', is also specified with '-I', the '-I' option is
1 ignored. The directory is still searched but as a system directory
1 at its normal position in the system include chain. This is to
1 ensure that GCC's procedure to fix buggy system headers and the
1 ordering for the '#include_next' directive are not inadvertently
1 changed. If you really need to change the search order for system
11 directories, use the '-nostdinc' and/or '-isystem' options. ⇒
System Headers.
1
1 '-I-'
1 Split the include path. This option has been deprecated. Please
1 use '-iquote' instead for '-I' directories before the '-I-' and
1 remove the '-I-' option.
1
1 Any directories specified with '-I' options before '-I-' are
1 searched only for headers requested with '#include "FILE"'; they
1 are not searched for '#include <FILE>'. If additional directories
1 are specified with '-I' options after the '-I-', those directories
1 are searched for all '#include' directives.
1
1 In addition, '-I-' inhibits the use of the directory of the current
1 file directory as the first search directory for '#include "FILE"'.
11 There is no way to override this effect of '-I-'. ⇒Search
Path.
1
1 '-iprefix PREFIX'
1 Specify PREFIX as the prefix for subsequent '-iwithprefix' options.
1 If the prefix represents a directory, you should include the final
1 '/'.
1
1 '-iwithprefix DIR'
1 '-iwithprefixbefore DIR'
1 Append DIR to the prefix specified previously with '-iprefix', and
1 add the resulting directory to the include search path.
1 '-iwithprefixbefore' puts it in the same place '-I' would;
1 '-iwithprefix' puts it where '-idirafter' would.
1
1 '-isysroot DIR'
1 This option is like the '--sysroot' option, but applies only to
1 header files (except for Darwin targets, where it applies to both
1 header files and libraries). See the '--sysroot' option for more
1 information.
1
1 '-imultilib DIR'
1 Use DIR as a subdirectory of the directory containing
1 target-specific C++ headers.
1
1 '-nostdinc'
1 Do not search the standard system directories for header files.
1 Only the directories explicitly specified with '-I', '-iquote',
1 '-isystem', and/or '-idirafter' options (and the directory of the
1 current file, if appropriate) are searched.
1
1 '-nostdinc++'
1 Do not search for header files in the C++-specific standard
1 directories, but do still search the other standard directories.
1 (This option is used when building the C++ library.)
1
1 '-Wcomment'
1 '-Wcomments'
1 Warn whenever a comment-start sequence '/*' appears in a '/*'
1 comment, or whenever a backslash-newline appears in a '//' comment.
1 This warning is enabled by '-Wall'.
1
1 '-Wtrigraphs'
1 Warn if any trigraphs are encountered that might change the meaning
1 of the program. Trigraphs within comments are not warned about,
1 except those that would form escaped newlines.
1
1 This option is implied by '-Wall'. If '-Wall' is not given, this
1 option is still enabled unless trigraphs are enabled. To get
1 trigraph conversion without warnings, but get the other '-Wall'
1 warnings, use '-trigraphs -Wall -Wno-trigraphs'.
1
1 '-Wundef'
1 Warn if an undefined identifier is evaluated in an '#if' directive.
1 Such identifiers are replaced with zero.
1
1 '-Wexpansion-to-defined'
1 Warn whenever 'defined' is encountered in the expansion of a macro
1 (including the case where the macro is expanded by an '#if'
1 directive). Such usage is not portable. This warning is also
1 enabled by '-Wpedantic' and '-Wextra'.
1
1 '-Wunused-macros'
1 Warn about macros defined in the main file that are unused. A
1 macro is "used" if it is expanded or tested for existence at least
1 once. The preprocessor also warns if the macro has not been used
1 at the time it is redefined or undefined.
1
1 Built-in macros, macros defined on the command line, and macros
1 defined in include files are not warned about.
1
1 _Note:_ If a macro is actually used, but only used in skipped
1 conditional blocks, then the preprocessor reports it as unused. To
1 avoid the warning in such a case, you might improve the scope of
1 the macro's definition by, for example, moving it into the first
1 skipped block. Alternatively, you could provide a dummy use with
1 something like:
1
1 #if defined the_macro_causing_the_warning
1 #endif
1
1 '-Wno-endif-labels'
1 Do not warn whenever an '#else' or an '#endif' are followed by
1 text. This sometimes happens in older programs with code of the
1 form
1
1 #if FOO
1 ...
1 #else FOO
1 ...
1 #endif FOO
1
1 The second and third 'FOO' should be in comments. This warning is
1 on by default.
1