1@c Copyright (C) 1999-2020 Free Software Foundation, Inc. 2@c This is part of the CPP and GCC manuals. 3@c For copying conditions, see the file gcc.texi. 4 5@c --------------------------------------------------------------------- 6@c Options affecting the preprocessor 7@c --------------------------------------------------------------------- 8 9@c If this file is included with the flag ``cppmanual'' set, it is 10@c formatted for inclusion in the CPP manual; otherwise the main GCC manual. 11 12@item -D @var{name} 13@opindex D 14Predefine @var{name} as a macro, with definition @code{1}. 15 16@item -D @var{name}=@var{definition} 17The contents of @var{definition} are tokenized and processed as if 18they appeared during translation phase three in a @samp{#define} 19directive. In particular, the definition is truncated by 20embedded newline characters. 21 22If you are invoking the preprocessor from a shell or shell-like 23program you may need to use the shell's quoting syntax to protect 24characters such as spaces that have a meaning in the shell syntax. 25 26If you wish to define a function-like macro on the command line, write 27its argument list with surrounding parentheses before the equals sign 28(if any). Parentheses are meaningful to most shells, so you should 29quote the option. With @command{sh} and @command{csh}, 30@option{-D'@var{name}(@var{args@dots{}})=@var{definition}'} works. 31 32@option{-D} and @option{-U} options are processed in the order they 33are given on the command line. All @option{-imacros @var{file}} and 34@option{-include @var{file}} options are processed after all 35@option{-D} and @option{-U} options. 36 37@item -U @var{name} 38@opindex U 39Cancel any previous definition of @var{name}, either built in or 40provided with a @option{-D} option. 41 42@item -include @var{file} 43@opindex include 44Process @var{file} as if @code{#include "file"} appeared as the first 45line of the primary source file. However, the first directory searched 46for @var{file} is the preprocessor's working directory @emph{instead of} 47the directory containing the main source file. If not found there, it 48is searched for in the remainder of the @code{#include "@dots{}"} search 49chain as normal. 50 51If multiple @option{-include} options are given, the files are included 52in the order they appear on the command line. 53 54@item -imacros @var{file} 55@opindex imacros 56Exactly like @option{-include}, except that any output produced by 57scanning @var{file} is thrown away. Macros it defines remain defined. 58This allows you to acquire all the macros from a header without also 59processing its declarations. 60 61All files specified by @option{-imacros} are processed before all files 62specified by @option{-include}. 63 64@item -undef 65@opindex undef 66Do not predefine any system-specific or GCC-specific macros. The 67standard predefined macros remain defined. 68@ifset cppmanual 69@xref{Standard Predefined Macros}. 70@end ifset 71 72@item -pthread 73@opindex pthread 74Define additional macros required for using the POSIX threads library. 75You should use this option consistently for both compilation and linking. 76This option is supported on GNU/Linux targets, most other Unix derivatives, 77and also on x86 Cygwin and MinGW targets. 78 79@item -M 80@opindex M 81@cindex @command{make} 82@cindex dependencies, @command{make} 83Instead of outputting the result of preprocessing, output a rule 84suitable for @command{make} describing the dependencies of the main 85source file. The preprocessor outputs one @command{make} rule containing 86the object file name for that source file, a colon, and the names of all 87the included files, including those coming from @option{-include} or 88@option{-imacros} command-line options. 89 90Unless specified explicitly (with @option{-MT} or @option{-MQ}), the 91object file name consists of the name of the source file with any 92suffix replaced with object file suffix and with any leading directory 93parts removed. If there are many included files then the rule is 94split into several lines using @samp{\}-newline. The rule has no 95commands. 96 97This option does not suppress the preprocessor's debug output, such as 98@option{-dM}. To avoid mixing such debug output with the dependency 99rules you should explicitly specify the dependency output file with 100@option{-MF}, or use an environment variable like 101@env{DEPENDENCIES_OUTPUT} (@pxref{Environment Variables}). Debug output 102is still sent to the regular output stream as normal. 103 104Passing @option{-M} to the driver implies @option{-E}, and suppresses 105warnings with an implicit @option{-w}. 106 107@item -MM 108@opindex MM 109Like @option{-M} but do not mention header files that are found in 110system header directories, nor header files that are included, 111directly or indirectly, from such a header. 112 113This implies that the choice of angle brackets or double quotes in an 114@samp{#include} directive does not in itself determine whether that 115header appears in @option{-MM} dependency output. 116 117@anchor{dashMF} 118@item -MF @var{file} 119@opindex MF 120When used with @option{-M} or @option{-MM}, specifies a 121file to write the dependencies to. If no @option{-MF} switch is given 122the preprocessor sends the rules to the same place it would send 123preprocessed output. 124 125When used with the driver options @option{-MD} or @option{-MMD}, 126@option{-MF} overrides the default dependency output file. 127 128If @var{file} is @file{-}, then the dependencies are written to @file{stdout}. 129 130@item -MG 131@opindex MG 132In conjunction with an option such as @option{-M} requesting 133dependency generation, @option{-MG} assumes missing header files are 134generated files and adds them to the dependency list without raising 135an error. The dependency filename is taken directly from the 136@code{#include} directive without prepending any path. @option{-MG} 137also suppresses preprocessed output, as a missing header file renders 138this useless. 139 140This feature is used in automatic updating of makefiles. 141 142@item -MP 143@opindex MP 144This option instructs CPP to add a phony target for each dependency 145other than the main file, causing each to depend on nothing. These 146dummy rules work around errors @command{make} gives if you remove header 147files without updating the @file{Makefile} to match. 148 149This is typical output: 150 151@smallexample 152test.o: test.c test.h 153 154test.h: 155@end smallexample 156 157@item -MT @var{target} 158@opindex MT 159 160Change the target of the rule emitted by dependency generation. By 161default CPP takes the name of the main input file, deletes any 162directory components and any file suffix such as @samp{.c}, and 163appends the platform's usual object suffix. The result is the target. 164 165An @option{-MT} option sets the target to be exactly the string you 166specify. If you want multiple targets, you can specify them as a single 167argument to @option{-MT}, or use multiple @option{-MT} options. 168 169For example, @option{@w{-MT '$(objpfx)foo.o'}} might give 170 171@smallexample 172$(objpfx)foo.o: foo.c 173@end smallexample 174 175@item -MQ @var{target} 176@opindex MQ 177 178Same as @option{-MT}, but it quotes any characters which are special to 179Make. @option{@w{-MQ '$(objpfx)foo.o'}} gives 180 181@smallexample 182$$(objpfx)foo.o: foo.c 183@end smallexample 184 185The default target is automatically quoted, as if it were given with 186@option{-MQ}. 187 188@item -MD 189@opindex MD 190@option{-MD} is equivalent to @option{-M -MF @var{file}}, except that 191@option{-E} is not implied. The driver determines @var{file} based on 192whether an @option{-o} option is given. If it is, the driver uses its 193argument but with a suffix of @file{.d}, otherwise it takes the name 194of the input file, removes any directory components and suffix, and 195applies a @file{.d} suffix. 196 197If @option{-MD} is used in conjunction with @option{-E}, any 198@option{-o} switch is understood to specify the dependency output file 199(@pxref{dashMF,,-MF}), but if used without @option{-E}, each @option{-o} 200is understood to specify a target object file. 201 202Since @option{-E} is not implied, @option{-MD} can be used to generate 203a dependency output file as a side effect of the compilation process. 204 205@item -MMD 206@opindex MMD 207Like @option{-MD} except mention only user header files, not system 208header files. 209 210@item -fpreprocessed 211@opindex fpreprocessed 212Indicate to the preprocessor that the input file has already been 213preprocessed. This suppresses things like macro expansion, trigraph 214conversion, escaped newline splicing, and processing of most directives. 215The preprocessor still recognizes and removes comments, so that you can 216pass a file preprocessed with @option{-C} to the compiler without 217problems. In this mode the integrated preprocessor is little more than 218a tokenizer for the front ends. 219 220@option{-fpreprocessed} is implicit if the input file has one of the 221extensions @samp{.i}, @samp{.ii} or @samp{.mi}. These are the 222extensions that GCC uses for preprocessed files created by 223@option{-save-temps}. 224 225@item -cxx-isystem @var{dir} 226@opindex cxxisystem 227Search @var{dir} for C++ header files, after all directories specified by 228@option{-I} but before the standard system directories. Mark it 229as a system directory, so that it gets the same special treatment as 230is applied to the standard system directories. 231@ifset cppmanual 232@xref{System Headers}. 233@end ifset 234 235@item -fdirectives-only 236@opindex fdirectives-only 237When preprocessing, handle directives, but do not expand macros. 238 239The option's behavior depends on the @option{-E} and @option{-fpreprocessed} 240options. 241 242With @option{-E}, preprocessing is limited to the handling of directives 243such as @code{#define}, @code{#ifdef}, and @code{#error}. Other 244preprocessor operations, such as macro expansion and trigraph 245conversion are not performed. In addition, the @option{-dD} option is 246implicitly enabled. 247 248With @option{-fpreprocessed}, predefinition of command line and most 249builtin macros is disabled. Macros such as @code{__LINE__}, which are 250contextually dependent, are handled normally. This enables compilation of 251files previously preprocessed with @code{-E -fdirectives-only}. 252 253With both @option{-E} and @option{-fpreprocessed}, the rules for 254@option{-fpreprocessed} take precedence. This enables full preprocessing of 255files previously preprocessed with @code{-E -fdirectives-only}. 256 257@item -iremap @var{src}:@var{dst} 258@opindex iremap 259Replace the prefix @var{src} in __FILE__ with @var{dst} at expansion time. 260This option can be specified more than once. Processing stops at the first 261match. 262 263@item -fdollars-in-identifiers 264@opindex fdollars-in-identifiers 265@anchor{fdollars-in-identifiers} 266Accept @samp{$} in identifiers. 267@ifset cppmanual 268@xref{Identifier characters}. 269@end ifset 270 271@item -fextended-identifiers 272@opindex fextended-identifiers 273Accept universal character names and extended characters in 274identifiers. This option is enabled by default for C99 (and later C 275standard versions) and C++. 276 277@item -fno-canonical-system-headers 278@opindex fno-canonical-system-headers 279When preprocessing, do not shorten system header paths with canonicalization. 280 281@item -fmax-include-depth=@var{depth} 282@opindex fmax-include-depth 283Set the maximum depth of the nested #include. The default is 200. 284 285@item -ftabstop=@var{width} 286@opindex ftabstop 287Set the distance between tab stops. This helps the preprocessor report 288correct column numbers in warnings or errors, even if tabs appear on the 289line. If the value is less than 1 or greater than 100, the option is 290ignored. The default is 8. 291 292@item -ftrack-macro-expansion@r{[}=@var{level}@r{]} 293@opindex ftrack-macro-expansion 294Track locations of tokens across macro expansions. This allows the 295compiler to emit diagnostic about the current macro expansion stack 296when a compilation error occurs in a macro expansion. Using this 297option makes the preprocessor and the compiler consume more 298memory. The @var{level} parameter can be used to choose the level of 299precision of token location tracking thus decreasing the memory 300consumption if necessary. Value @samp{0} of @var{level} de-activates 301this option. Value @samp{1} tracks tokens locations in a 302degraded mode for the sake of minimal memory overhead. In this mode 303all tokens resulting from the expansion of an argument of a 304function-like macro have the same location. Value @samp{2} tracks 305tokens locations completely. This value is the most memory hungry. 306When this option is given no argument, the default parameter value is 307@samp{2}. 308 309Note that @code{-ftrack-macro-expansion=2} is activated by default. 310 311@item -fmacro-prefix-map=@var{old}=@var{new} 312@opindex fmacro-prefix-map 313When preprocessing files residing in directory @file{@var{old}}, 314expand the @code{__FILE__} and @code{__BASE_FILE__} macros as if the 315files resided in directory @file{@var{new}} instead. This can be used 316to change an absolute path to a relative path by using @file{.} for 317@var{new} which can result in more reproducible builds that are 318location independent. This option also affects 319@code{__builtin_FILE()} during compilation. See also 320@option{-ffile-prefix-map}. 321 322@item -fexec-charset=@var{charset} 323@opindex fexec-charset 324@cindex character set, execution 325Set the execution character set, used for string and character 326constants. The default is UTF-8. @var{charset} can be any encoding 327supported by the system's @code{iconv} library routine. 328 329@item -fwide-exec-charset=@var{charset} 330@opindex fwide-exec-charset 331@cindex character set, wide execution 332Set the wide execution character set, used for wide string and 333character constants. The default is one of UTF-32BE, UTF-32LE, UTF-16BE, 334or UTF-16LE, whichever corresponds to the width of @code{wchar_t} and the 335big-endian or little-endian byte order being used for code generation. As 336with @option{-fexec-charset}, @var{charset} can be any encoding supported 337by the system's @code{iconv} library routine; however, you will have 338problems with encodings that do not fit exactly in @code{wchar_t}. 339 340@item -finput-charset=@var{charset} 341@opindex finput-charset 342@cindex character set, input 343Set the input character set, used for translation from the character 344set of the input file to the source character set used by GCC@. If the 345locale does not specify, or GCC cannot get this information from the 346locale, the default is UTF-8. This can be overridden by either the locale 347or this command-line option. Currently the command-line option takes 348precedence if there's a conflict. @var{charset} can be any encoding 349supported by the system's @code{iconv} library routine. 350 351@ifclear cppmanual 352@item -fpch-deps 353@opindex fpch-deps 354When using precompiled headers (@pxref{Precompiled Headers}), this flag 355causes the dependency-output flags to also list the files from the 356precompiled header's dependencies. If not specified, only the 357precompiled header are listed and not the files that were used to 358create it, because those files are not consulted when a precompiled 359header is used. 360 361@item -fpch-preprocess 362@opindex fpch-preprocess 363This option allows use of a precompiled header (@pxref{Precompiled 364Headers}) together with @option{-E}. It inserts a special @code{#pragma}, 365@code{#pragma GCC pch_preprocess "@var{filename}"} in the output to mark 366the place where the precompiled header was found, and its @var{filename}. 367When @option{-fpreprocessed} is in use, GCC recognizes this @code{#pragma} 368and loads the PCH@. 369 370This option is off by default, because the resulting preprocessed output 371is only really suitable as input to GCC@. It is switched on by 372@option{-save-temps}. 373 374You should not write this @code{#pragma} in your own code, but it is 375safe to edit the filename if the PCH file is available in a different 376location. The filename may be absolute or it may be relative to GCC's 377current directory. 378@end ifclear 379 380@item -fworking-directory 381@opindex fworking-directory 382@opindex fno-working-directory 383Enable generation of linemarkers in the preprocessor output that 384let the compiler know the current working directory at the time of 385preprocessing. When this option is enabled, the preprocessor 386emits, after the initial linemarker, a second linemarker with the 387current working directory followed by two slashes. GCC uses this 388directory, when it's present in the preprocessed input, as the 389directory emitted as the current working directory in some debugging 390information formats. This option is implicitly enabled if debugging 391information is enabled, but this can be inhibited with the negated 392form @option{-fno-working-directory}. If the @option{-P} flag is 393present in the command line, this option has no effect, since no 394@code{#line} directives are emitted whatsoever. 395 396@item -A @var{predicate}=@var{answer} 397@opindex A 398Make an assertion with the predicate @var{predicate} and answer 399@var{answer}. This form is preferred to the older form @option{-A 400@var{predicate}(@var{answer})}, which is still supported, because 401it does not use shell special characters. 402@ifset cppmanual 403@xref{Obsolete Features}. 404@end ifset 405 406@item -A -@var{predicate}=@var{answer} 407Cancel an assertion with the predicate @var{predicate} and answer 408@var{answer}. 409 410@item -C 411@opindex C 412Do not discard comments. All comments are passed through to the output 413file, except for comments in processed directives, which are deleted 414along with the directive. 415 416You should be prepared for side effects when using @option{-C}; it 417causes the preprocessor to treat comments as tokens in their own right. 418For example, comments appearing at the start of what would be a 419directive line have the effect of turning that line into an ordinary 420source line, since the first token on the line is no longer a @samp{#}. 421 422@item -CC 423@opindex CC 424Do not discard comments, including during macro expansion. This is 425like @option{-C}, except that comments contained within macros are 426also passed through to the output file where the macro is expanded. 427 428In addition to the side effects of the @option{-C} option, the 429@option{-CC} option causes all C++-style comments inside a macro 430to be converted to C-style comments. This is to prevent later use 431of that macro from inadvertently commenting out the remainder of 432the source line. 433 434The @option{-CC} option is generally used to support lint comments. 435 436@item -P 437@opindex P 438Inhibit generation of linemarkers in the output from the preprocessor. 439This might be useful when running the preprocessor on something that is 440not C code, and will be sent to a program which might be confused by the 441linemarkers. 442@ifset cppmanual 443@xref{Preprocessor Output}. 444@end ifset 445 446@cindex traditional C language 447@cindex C language, traditional 448@item -traditional 449@itemx -traditional-cpp 450@opindex traditional-cpp 451@opindex traditional 452 453Try to imitate the behavior of pre-standard C preprocessors, as 454opposed to ISO C preprocessors. 455@ifset cppmanual 456@xref{Traditional Mode}. 457@end ifset 458@ifclear cppmanual 459See the GNU CPP manual for details. 460@end ifclear 461 462Note that GCC does not otherwise attempt to emulate a pre-standard 463C compiler, and these options are only supported with the @option{-E} 464switch, or when invoking CPP explicitly. 465 466@item -trigraphs 467@opindex trigraphs 468Support ISO C trigraphs. 469These are three-character sequences, all starting with @samp{??}, that 470are defined by ISO C to stand for single characters. For example, 471@samp{??/} stands for @samp{\}, so @samp{'??/n'} is a character 472constant for a newline. 473@ifset cppmanual 474@xref{Initial processing}. 475@end ifset 476 477@ifclear cppmanual 478The nine trigraphs and their replacements are 479 480@smallexample 481Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- 482Replacement: [ ] @{ @} # \ ^ | ~ 483@end smallexample 484@end ifclear 485 486By default, GCC ignores trigraphs, but in 487standard-conforming modes it converts them. See the @option{-std} and 488@option{-ansi} options. 489 490@item -remap 491@opindex remap 492Enable special code to work around file systems which only permit very 493short file names, such as MS-DOS@. 494 495@item -H 496@opindex H 497Print the name of each header file used, in addition to other normal 498activities. Each name is indented to show how deep in the 499@samp{#include} stack it is. Precompiled header files are also 500printed, even if they are found to be invalid; an invalid precompiled 501header file is printed with @samp{...x} and a valid one with @samp{...!} . 502 503@item -d@var{letters} 504@opindex d 505Says to make debugging dumps during compilation as specified by 506@var{letters}. The flags documented here are those relevant to the 507preprocessor. Other @var{letters} are interpreted 508by the compiler proper, or reserved for future versions of GCC, and so 509are silently ignored. If you specify @var{letters} whose behavior 510conflicts, the result is undefined. 511@ifclear cppmanual 512@xref{Developer Options}, for more information. 513@end ifclear 514 515@table @gcctabopt 516@item -dM 517@opindex dM 518Instead of the normal output, generate a list of @samp{#define} 519directives for all the macros defined during the execution of the 520preprocessor, including predefined macros. This gives you a way of 521finding out what is predefined in your version of the preprocessor. 522Assuming you have no file @file{foo.h}, the command 523 524@smallexample 525touch foo.h; cpp -dM foo.h 526@end smallexample 527 528@noindent 529shows all the predefined macros. 530 531@ifclear cppmanual 532If you use @option{-dM} without the @option{-E} option, @option{-dM} is 533interpreted as a synonym for @option{-fdump-rtl-mach}. 534@xref{Developer Options, , ,gcc}. 535@end ifclear 536 537@item -dD 538@opindex dD 539Like @option{-dM} except in two respects: it does @emph{not} include the 540predefined macros, and it outputs @emph{both} the @samp{#define} 541directives and the result of preprocessing. Both kinds of output go to 542the standard output file. 543 544@item -dN 545@opindex dN 546Like @option{-dD}, but emit only the macro names, not their expansions. 547 548@item -dI 549@opindex dI 550Output @samp{#include} directives in addition to the result of 551preprocessing. 552 553@item -dU 554@opindex dU 555Like @option{-dD} except that only macros that are expanded, or whose 556definedness is tested in preprocessor directives, are output; the 557output is delayed until the use or test of the macro; and 558@samp{#undef} directives are also output for macros tested but 559undefined at the time. 560@end table 561 562@item -fdebug-cpp 563@opindex fdebug-cpp 564This option is only useful for debugging GCC. When used from CPP or with 565@option{-E}, it dumps debugging information about location maps. Every 566token in the output is preceded by the dump of the map its location 567belongs to. 568 569When used from GCC without @option{-E}, this option has no effect. 570