From d77de738290156fafe079182888e5e03a2f835f1 Mon Sep 17 00:00:00 2001 From: Martin Liska Date: Sun, 13 Nov 2022 21:59:29 +0100 Subject: Revert "sphinx: remove texinfo files" This reverts commit 54ca4eef58661a7d7a511e2bbbe309bde1732abf. --- gcc/doc/cppopts.texi | 557 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 557 insertions(+) create mode 100644 gcc/doc/cppopts.texi (limited to 'gcc/doc/cppopts.texi') diff --git a/gcc/doc/cppopts.texi b/gcc/doc/cppopts.texi new file mode 100644 index 0000000..c0a92b3 --- /dev/null +++ b/gcc/doc/cppopts.texi @@ -0,0 +1,557 @@ +@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. -- cgit v1.1