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