diff options
Diffstat (limited to 'gcc/doc/cppopts.texi')
| -rw-r--r-- | gcc/doc/cppopts.texi | 557 |
1 files changed, 0 insertions, 557 deletions
diff --git a/gcc/doc/cppopts.texi b/gcc/doc/cppopts.texi deleted file mode 100644 index c0a92b3..0000000 --- a/gcc/doc/cppopts.texi +++ /dev/null @@ -1,557 +0,0 @@ -@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. |