diff options
Diffstat (limited to 'share/doc/cpp/Invocation.html')
| -rw-r--r-- | share/doc/cpp/Invocation.html | 889 |
1 files changed, 889 insertions, 0 deletions
diff --git a/share/doc/cpp/Invocation.html b/share/doc/cpp/Invocation.html new file mode 100644 index 0000000..a1acc15 --- /dev/null +++ b/share/doc/cpp/Invocation.html @@ -0,0 +1,889 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Invocation</title> + +<meta name="description" content="The C Preprocessor: Invocation"> +<meta name="keywords" content="The C Preprocessor: Invocation"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Environment-Variables.html#Environment-Variables" rel="next" title="Environment Variables"> +<link href="Obsolete-Features.html#Obsolete-Features" rel="previous" title="Obsolete Features"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Invocation"></a> +<div class="header"> +<p> +Next: <a href="Environment-Variables.html#Environment-Variables" accesskey="n" rel="next">Environment Variables</a>, Previous: <a href="Implementation-Details.html#Implementation-Details" accesskey="p" rel="previous">Implementation Details</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Invocation-1"></a> +<h2 class="chapter">12 Invocation</h2> +<a name="index-invocation"></a> +<a name="index-command-line"></a> + +<p>Most often when you use the C preprocessor you do not have to invoke it +explicitly: the C compiler does so automatically. However, the +preprocessor is sometimes useful on its own. You can invoke the +preprocessor either with the <code>cpp</code> command, or via <code>gcc -E</code>. +In GCC, the preprocessor is actually integrated with the compiler +rather than a separate program, and both of these commands invoke +GCC and tell it to stop after the preprocessing phase. +</p> +<p>The <code>cpp</code> options listed here are also accepted by +<code>gcc</code> and have the same meaning. Likewise the <code>cpp</code> +command accepts all the usual <code>gcc</code> driver options, although those +pertaining to compilation phases after preprocessing are ignored. +</p> +<p>Only options specific to preprocessing behavior are documented here. +Refer to the GCC manual for full documentation of other driver options. +</p> + +<p>The <code>cpp</code> command expects two file names as arguments, <var>infile</var> and +<var>outfile</var>. The preprocessor reads <var>infile</var> together with any +other files it specifies with ‘<samp>#include</samp>’. All the output generated +by the combined input files is written in <var>outfile</var>. +</p> +<p>Either <var>infile</var> or <var>outfile</var> may be <samp>-</samp>, which as +<var>infile</var> means to read from standard input and as <var>outfile</var> +means to write to standard output. If either file is omitted, it +means the same as if <samp>-</samp> had been specified for that file. +You can also use the <samp>-o <var>outfile</var></samp> option to specify the +output file. +</p> +<p>Unless otherwise noted, or the option ends in ‘<samp>=</samp>’, all options +which take an argument may have that argument appear either immediately +after the option, or with a space between option and argument: +<samp>-Ifoo</samp> and <samp>-I foo</samp> have the same effect. +</p> +<a name="index-grouping-options"></a> +<a name="index-options_002c-grouping"></a> +<p>Many options have multi-letter names; therefore multiple single-letter +options may <em>not</em> be grouped: <samp>-dM</samp> is very different from +‘<samp><span class="nolinebreak">-d</span> <span class="nolinebreak">-M</span></samp>’<!-- /@w -->. +</p> +<a name="index-options"></a> + +<dl compact="compact"> +<dd> + + +<a name="index-D"></a> +</dd> +<dt><code>-D <var>name</var></code></dt> +<dd><p>Predefine <var>name</var> as a macro, with definition <code>1</code>. +</p> +</dd> +<dt><code>-D <var>name</var>=<var>definition</var></code></dt> +<dd><p>The contents of <var>definition</var> are tokenized and processed as if +they appeared during translation phase three in a ‘<samp>#define</samp>’ +directive. In particular, the definition is truncated by +embedded newline characters. +</p> +<p>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. +</p> +<p>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 <code>sh</code> and <code>csh</code>, +<samp>-D'<var>name</var>(<var>args…</var>)=<var>definition</var>'</samp> works. +</p> +<p><samp>-D</samp> and <samp>-U</samp> options are processed in the order they +are given on the command line. All <samp>-imacros <var>file</var></samp> and +<samp>-include <var>file</var></samp> options are processed after all +<samp>-D</samp> and <samp>-U</samp> options. +</p> +<a name="index-U"></a> +</dd> +<dt><code>-U <var>name</var></code></dt> +<dd><p>Cancel any previous definition of <var>name</var>, either built in or +provided with a <samp>-D</samp> option. +</p> +<a name="index-include"></a> +</dd> +<dt><code>-include <var>file</var></code></dt> +<dd><p>Process <var>file</var> as if <code>#include "file"</code> appeared as the first +line of the primary source file. However, the first directory searched +for <var>file</var> is the preprocessor’s working directory <em>instead of</em> +the directory containing the main source file. If not found there, it +is searched for in the remainder of the <code>#include "…"</code> search +chain as normal. +</p> +<p>If multiple <samp>-include</samp> options are given, the files are included +in the order they appear on the command line. +</p> +<a name="index-imacros"></a> +</dd> +<dt><code>-imacros <var>file</var></code></dt> +<dd><p>Exactly like <samp>-include</samp>, except that any output produced by +scanning <var>file</var> is thrown away. Macros it defines remain defined. +This allows you to acquire all the macros from a header without also +processing its declarations. +</p> +<p>All files specified by <samp>-imacros</samp> are processed before all files +specified by <samp>-include</samp>. +</p> +<a name="index-undef"></a> +</dd> +<dt><code>-undef</code></dt> +<dd><p>Do not predefine any system-specific or GCC-specific macros. The +standard predefined macros remain defined. +See <a href="Standard-Predefined-Macros.html#Standard-Predefined-Macros">Standard Predefined Macros</a>. +</p> +<a name="index-pthread"></a> +</dd> +<dt><code>-pthread</code></dt> +<dd><p>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. +</p> +<a name="index-M"></a> +<a name="index-make"></a> +<a name="index-dependencies_002c-make"></a> +</dd> +<dt><code>-M</code></dt> +<dd><p>Instead of outputting the result of preprocessing, output a rule +suitable for <code>make</code> describing the dependencies of the main +source file. The preprocessor outputs one <code>make</code> rule containing +the object file name for that source file, a colon, and the names of all +the included files, including those coming from <samp>-include</samp> or +<samp>-imacros</samp> command-line options. +</p> +<p>Unless specified explicitly (with <samp>-MT</samp> or <samp>-MQ</samp>), 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>\</samp>’-newline. The rule has no +commands. +</p> +<p>This option does not suppress the preprocessor’s debug output, such as +<samp>-dM</samp>. To avoid mixing such debug output with the dependency +rules you should explicitly specify the dependency output file with +<samp>-MF</samp>, or use an environment variable like +<code>DEPENDENCIES_OUTPUT</code> (see <a href="Environment-Variables.html#Environment-Variables">Environment Variables</a>). Debug output +is still sent to the regular output stream as normal. +</p> +<p>Passing <samp>-M</samp> to the driver implies <samp>-E</samp>, and suppresses +warnings with an implicit <samp>-w</samp>. +</p> +<a name="index-MM"></a> +</dd> +<dt><code>-MM</code></dt> +<dd><p>Like <samp>-M</samp> 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. +</p> +<p>This implies that the choice of angle brackets or double quotes in an +‘<samp>#include</samp>’ directive does not in itself determine whether that +header appears in <samp>-MM</samp> dependency output. +</p> +<a name="dashMF"></a><a name="index-MF"></a> +</dd> +<dt><code>-MF <var>file</var></code></dt> +<dd><p>When used with <samp>-M</samp> or <samp>-MM</samp>, specifies a +file to write the dependencies to. If no <samp>-MF</samp> switch is given +the preprocessor sends the rules to the same place it would send +preprocessed output. +</p> +<p>When used with the driver options <samp>-MD</samp> or <samp>-MMD</samp>, +<samp>-MF</samp> overrides the default dependency output file. +</p> +<p>If <var>file</var> is <samp>-</samp>, then the dependencies are written to <samp>stdout</samp>. +</p> +<a name="index-MG"></a> +</dd> +<dt><code>-MG</code></dt> +<dd><p>In conjunction with an option such as <samp>-M</samp> requesting +dependency generation, <samp>-MG</samp> 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</code> directive without prepending any path. <samp>-MG</samp> +also suppresses preprocessed output, as a missing header file renders +this useless. +</p> +<p>This feature is used in automatic updating of makefiles. +</p> +<a name="index-Mno_002dmodules"></a> +</dd> +<dt><code>-Mno-modules</code></dt> +<dd><p>Disable dependency generation for compiled module interfaces. +</p> +<a name="index-MP"></a> +</dd> +<dt><code>-MP</code></dt> +<dd><p>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 <code>make</code> gives if you remove header +files without updating the <samp>Makefile</samp> to match. +</p> +<p>This is typical output: +</p> +<div class="smallexample"> +<pre class="smallexample">test.o: test.c test.h + +test.h: +</pre></div> + +<a name="index-MT"></a> +</dd> +<dt><code>-MT <var>target</var></code></dt> +<dd> +<p>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</samp>’, and +appends the platform’s usual object suffix. The result is the target. +</p> +<p>An <samp>-MT</samp> 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 <samp>-MT</samp>, or use multiple <samp>-MT</samp> options. +</p> +<p>For example, <samp><span class="nolinebreak">-MT</span> '$(objpfx)foo.o'<!-- /@w --></samp> might give +</p> +<div class="smallexample"> +<pre class="smallexample">$(objpfx)foo.o: foo.c +</pre></div> + +<a name="index-MQ"></a> +</dd> +<dt><code>-MQ <var>target</var></code></dt> +<dd> +<p>Same as <samp>-MT</samp>, but it quotes any characters which are special to +Make. <samp><span class="nolinebreak">-MQ</span> '$(objpfx)foo.o'<!-- /@w --></samp> gives +</p> +<div class="smallexample"> +<pre class="smallexample">$$(objpfx)foo.o: foo.c +</pre></div> + +<p>The default target is automatically quoted, as if it were given with +<samp>-MQ</samp>. +</p> +<a name="index-MD"></a> +</dd> +<dt><code>-MD</code></dt> +<dd><p><samp>-MD</samp> is equivalent to <samp>-M -MF <var>file</var></samp>, except that +<samp>-E</samp> is not implied. The driver determines <var>file</var> based on +whether an <samp>-o</samp> option is given. If it is, the driver uses its +argument but with a suffix of <samp>.d</samp>, otherwise it takes the name +of the input file, removes any directory components and suffix, and +applies a <samp>.d</samp> suffix. +</p> +<p>If <samp>-MD</samp> is used in conjunction with <samp>-E</samp>, any +<samp>-o</samp> switch is understood to specify the dependency output file +(see <a href="#dashMF">-MF</a>), but if used without <samp>-E</samp>, each <samp>-o</samp> +is understood to specify a target object file. +</p> +<p>Since <samp>-E</samp> is not implied, <samp>-MD</samp> can be used to generate +a dependency output file as a side effect of the compilation process. +</p> +<a name="index-MMD"></a> +</dd> +<dt><code>-MMD</code></dt> +<dd><p>Like <samp>-MD</samp> except mention only user header files, not system +header files. +</p> +<a name="index-fpreprocessed"></a> +</dd> +<dt><code>-fpreprocessed</code></dt> +<dd><p>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 <samp>-C</samp> to the compiler without +problems. In this mode the integrated preprocessor is little more than +a tokenizer for the front ends. +</p> +<p><samp>-fpreprocessed</samp> is implicit if the input file has one of the +extensions ‘<samp>.i</samp>’, ‘<samp>.ii</samp>’ or ‘<samp>.mi</samp>’. These are the +extensions that GCC uses for preprocessed files created by +<samp>-save-temps</samp>. +</p> +<a name="index-fdirectives_002donly"></a> +</dd> +<dt><code>-fdirectives-only</code></dt> +<dd><p>When preprocessing, handle directives, but do not expand macros. +</p> +<p>The option’s behavior depends on the <samp>-E</samp> and <samp>-fpreprocessed</samp> +options. +</p> +<p>With <samp>-E</samp>, preprocessing is limited to the handling of directives +such as <code>#define</code>, <code>#ifdef</code>, and <code>#error</code>. Other +preprocessor operations, such as macro expansion and trigraph +conversion are not performed. In addition, the <samp>-dD</samp> option is +implicitly enabled. +</p> +<p>With <samp>-fpreprocessed</samp>, predefinition of command line and most +builtin macros is disabled. Macros such as <code>__LINE__</code>, which are +contextually dependent, are handled normally. This enables compilation of +files previously preprocessed with <code>-E -fdirectives-only</code>. +</p> +<p>With both <samp>-E</samp> and <samp>-fpreprocessed</samp>, the rules for +<samp>-fpreprocessed</samp> take precedence. This enables full preprocessing of +files previously preprocessed with <code>-E -fdirectives-only</code>. +</p> +<a name="index-fdollars_002din_002didentifiers"></a> +</dd> +<dt><code>-fdollars-in-identifiers</code></dt> +<dd><a name="fdollars_002din_002didentifiers"></a><p>Accept ‘<samp>$</samp>’ in identifiers. +See <a href="Implementation_002ddefined-behavior.html#Identifier-characters">Identifier characters</a>. +</p> +<a name="index-fextended_002didentifiers"></a> +</dd> +<dt><code>-fextended-identifiers</code></dt> +<dd><p>Accept universal character names and extended characters in +identifiers. This option is enabled by default for C99 (and later C +standard versions) and C++. +</p> +<a name="index-fno_002dcanonical_002dsystem_002dheaders"></a> +</dd> +<dt><code>-fno-canonical-system-headers</code></dt> +<dd><p>When preprocessing, do not shorten system header paths with canonicalization. +</p> +<a name="index-fmax_002dinclude_002ddepth"></a> +</dd> +<dt><code>-fmax-include-depth=<var>depth</var></code></dt> +<dd><p>Set the maximum depth of the nested #include. The default is 200. +</p> +<a name="index-ftabstop"></a> +</dd> +<dt><code>-ftabstop=<var>width</var></code></dt> +<dd><p>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. +</p> +<a name="index-ftrack_002dmacro_002dexpansion"></a> +</dd> +<dt><code>-ftrack-macro-expansion<span class="roman">[</span>=<var>level</var><span class="roman">]</span></code></dt> +<dd><p>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</var> parameter can be used to choose the level of +precision of token location tracking thus decreasing the memory +consumption if necessary. Value ‘<samp>0</samp>’ of <var>level</var> de-activates +this option. Value ‘<samp>1</samp>’ 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</samp>’ 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</samp>’. +</p> +<p>Note that <code>-ftrack-macro-expansion=2</code> is activated by default. +</p> +<a name="index-fmacro_002dprefix_002dmap"></a> +</dd> +<dt><code>-fmacro-prefix-map=<var>old</var>=<var>new</var></code></dt> +<dd><p>When preprocessing files residing in directory <samp><var>old</var></samp>, +expand the <code>__FILE__</code> and <code>__BASE_FILE__</code> macros as if the +files resided in directory <samp><var>new</var></samp> instead. This can be used +to change an absolute path to a relative path by using <samp>.</samp> for +<var>new</var> which can result in more reproducible builds that are +location independent. This option also affects +<code>__builtin_FILE()</code> during compilation. See also +<samp>-ffile-prefix-map</samp> and <samp>-fcanon-prefix-map</samp>. +</p> +<a name="index-fexec_002dcharset"></a> +<a name="index-character-set_002c-execution"></a> +</dd> +<dt><code>-fexec-charset=<var>charset</var></code></dt> +<dd><p>Set the execution character set, used for string and character +constants. The default is UTF-8. <var>charset</var> can be any encoding +supported by the system’s <code>iconv</code> library routine. +</p> +<a name="index-fwide_002dexec_002dcharset"></a> +<a name="index-character-set_002c-wide-execution"></a> +</dd> +<dt><code>-fwide-exec-charset=<var>charset</var></code></dt> +<dd><p>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</code> and the +big-endian or little-endian byte order being used for code generation. As +with <samp>-fexec-charset</samp>, <var>charset</var> can be any encoding supported +by the system’s <code>iconv</code> library routine; however, you will have +problems with encodings that do not fit exactly in <code>wchar_t</code>. +</p> +<a name="index-finput_002dcharset"></a> +<a name="index-character-set_002c-input"></a> +</dd> +<dt><code>-finput-charset=<var>charset</var></code></dt> +<dd><p>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</var> can be any encoding +supported by the system’s <code>iconv</code> library routine. +</p> + +<a name="index-fworking_002ddirectory"></a> +<a name="index-fno_002dworking_002ddirectory"></a> +</dd> +<dt><code>-fworking-directory</code></dt> +<dd><p>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 <samp>-fno-working-directory</samp>. If the <samp>-P</samp> flag is +present in the command line, this option has no effect, since no +<code>#line</code> directives are emitted whatsoever. +</p> +<a name="index-A"></a> +</dd> +<dt><code>-A <var>predicate</var>=<var>answer</var></code></dt> +<dd><p>Make an assertion with the predicate <var>predicate</var> and answer +<var>answer</var>. This form is preferred to the older form <samp>-A +<var>predicate</var>(<var>answer</var>)</samp>, which is still supported, because +it does not use shell special characters. +See <a href="Obsolete-Features.html#Obsolete-Features">Obsolete Features</a>. +</p> +</dd> +<dt><code>-A -<var>predicate</var>=<var>answer</var></code></dt> +<dd><p>Cancel an assertion with the predicate <var>predicate</var> and answer +<var>answer</var>. +</p> +<a name="index-C"></a> +</dd> +<dt><code>-C</code></dt> +<dd><p>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. +</p> +<p>You should be prepared for side effects when using <samp>-C</samp>; 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>#</samp>’. +</p> +<a name="index-CC"></a> +</dd> +<dt><code>-CC</code></dt> +<dd><p>Do not discard comments, including during macro expansion. This is +like <samp>-C</samp>, except that comments contained within macros are +also passed through to the output file where the macro is expanded. +</p> +<p>In addition to the side effects of the <samp>-C</samp> option, the +<samp>-CC</samp> 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. +</p> +<p>The <samp>-CC</samp> option is generally used to support lint comments. +</p> +<a name="index-P"></a> +</dd> +<dt><code>-P</code></dt> +<dd><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. +See <a href="Preprocessor-Output.html#Preprocessor-Output">Preprocessor Output</a>. +</p> +<a name="index-traditional-C-language"></a> +<a name="index-C-language_002c-traditional"></a> +<a name="index-traditional_002dcpp"></a> +<a name="index-traditional"></a> +</dd> +<dt><code>-traditional</code></dt> +<dt><code>-traditional-cpp</code></dt> +<dd> +<p>Try to imitate the behavior of pre-standard C preprocessors, as +opposed to ISO C preprocessors. +See <a href="Traditional-Mode.html#Traditional-Mode">Traditional Mode</a>. +</p> +<p>Note that GCC does not otherwise attempt to emulate a pre-standard +C compiler, and these options are only supported with the <samp>-E</samp> +switch, or when invoking CPP explicitly. +</p> +<a name="index-trigraphs-1"></a> +</dd> +<dt><code>-trigraphs</code></dt> +<dd><p>Support ISO C trigraphs. +These are three-character sequences, all starting with ‘<samp>??</samp>’, that +are defined by ISO C to stand for single characters. For example, +‘<samp>??/</samp>’ stands for ‘<samp>\</samp>’, so ‘<samp>'??/n'</samp>’ is a character +constant for a newline. +See <a href="Initial-processing.html#Initial-processing">Initial processing</a>. +</p> + +<p>By default, GCC ignores trigraphs, but in +standard-conforming modes it converts them. See the <samp>-std</samp> and +<samp>-ansi</samp> options. +</p> +<a name="index-remap"></a> +</dd> +<dt><code>-remap</code></dt> +<dd><p>Enable special code to work around file systems which only permit very +short file names, such as MS-DOS. +</p> +<a name="index-H"></a> +</dd> +<dt><code>-H</code></dt> +<dd><p>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</samp>’ 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</samp>’ and a valid one with ‘<samp>...!</samp>’ . +</p> +<a name="index-d"></a> +</dd> +<dt><code>-d<var>letters</var></code></dt> +<dd><p>Says to make debugging dumps during compilation as specified by +<var>letters</var>. The flags documented here are those relevant to the +preprocessor. Other <var>letters</var> are interpreted +by the compiler proper, or reserved for future versions of GCC, and so +are silently ignored. If you specify <var>letters</var> whose behavior +conflicts, the result is undefined. +</p> +<dl compact="compact"> +<dd><a name="index-dM"></a> +</dd> +<dt><code>-dM</code></dt> +<dd><p>Instead of the normal output, generate a list of ‘<samp>#define</samp>’ +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 <samp>foo.h</samp>, the command +</p> +<div class="smallexample"> +<pre class="smallexample">touch foo.h; cpp -dM foo.h +</pre></div> + +<p>shows all the predefined macros. +</p> + +<a name="index-dD"></a> +</dd> +<dt><code>-dD</code></dt> +<dd><p>Like <samp>-dM</samp> except in two respects: it does <em>not</em> include the +predefined macros, and it outputs <em>both</em> the ‘<samp>#define</samp>’ +directives and the result of preprocessing. Both kinds of output go to +the standard output file. +</p> +<a name="index-dN"></a> +</dd> +<dt><code>-dN</code></dt> +<dd><p>Like <samp>-dD</samp>, but emit only the macro names, not their expansions. +</p> +<a name="index-dI"></a> +</dd> +<dt><code>-dI</code></dt> +<dd><p>Output ‘<samp>#include</samp>’ directives in addition to the result of +preprocessing. +</p> +<a name="index-dU"></a> +</dd> +<dt><code>-dU</code></dt> +<dd><p>Like <samp>-dD</samp> 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</samp>’ directives are also output for macros tested but +undefined at the time. +</p></dd> +</dl> + +<a name="index-fdebug_002dcpp"></a> +</dd> +<dt><code>-fdebug-cpp</code></dt> +<dd><p>This option is only useful for debugging GCC. When used from CPP or with +<samp>-E</samp>, it dumps debugging information about location maps. Every +token in the output is preceded by the dump of the map its location +belongs to. +</p> +<p>When used from GCC without <samp>-E</samp>, this option has no effect. +</p> + + +<a name="index-I"></a> +<a name="index-iquote"></a> +<a name="index-isystem"></a> +<a name="index-idirafter"></a> +</dd> +<dt><code>-I <var>dir</var></code></dt> +<dt><code>-iquote <var>dir</var></code></dt> +<dt><code>-isystem <var>dir</var></code></dt> +<dt><code>-idirafter <var>dir</var></code></dt> +<dd><p>Add the directory <var>dir</var> to the list of directories to be searched +for header files during preprocessing. +See <a href="Search-Path.html#Search-Path">Search Path</a>. +If <var>dir</var> begins with ‘<samp>=</samp>’ or <code>$SYSROOT</code>, then the ‘<samp>=</samp>’ +or <code>$SYSROOT</code> is replaced by the sysroot prefix; see +<samp>--sysroot</samp> and <samp>-isysroot</samp>. +</p> +<p>Directories specified with <samp>-iquote</samp> apply only to the quote +form of the directive, <code>#include "<var>file</var>"<!-- /@w --></code>. +Directories specified with <samp>-I</samp>, <samp>-isystem</samp>, +or <samp>-idirafter</samp> apply to lookup for both the +<code>#include "<var>file</var>"<!-- /@w --></code> and +<code>#include <<var>file</var>><!-- /@w --></code> directives. +</p> +<p>You can specify any number or combination of these options on the +command line to search for header files in several directories. +The lookup order is as follows: +</p> +<ol> +<li> For the quote form of the include directive, the directory of the current +file is searched first. + +</li><li> For the quote form of the include directive, the directories specified +by <samp>-iquote</samp> options are searched in left-to-right order, +as they appear on the command line. + +</li><li> Directories specified with <samp>-I</samp> options are scanned in +left-to-right order. + +</li><li> Directories specified with <samp>-isystem</samp> options are scanned in +left-to-right order. + +</li><li> Standard system directories are scanned. + +</li><li> Directories specified with <samp>-idirafter</samp> options are scanned in +left-to-right order. +</li></ol> + +<p>You can use <samp>-I</samp> to override a system header +file, substituting your own version, since these directories are +searched before the standard system header file directories. +However, you should +not use this option to add directories that contain vendor-supplied +system header files; use <samp>-isystem</samp> for that. +</p> +<p>The <samp>-isystem</samp> and <samp>-idirafter</samp> options also mark the directory +as a system directory, so that it gets the same special treatment that +is applied to the standard system directories. +See <a href="System-Headers.html#System-Headers">System Headers</a>. +</p> +<p>If a standard system include directory, or a directory specified with +<samp>-isystem</samp>, is also specified with <samp>-I</samp>, the <samp>-I</samp> +option is ignored. The directory is still searched but as a +system directory at its normal position in the system include chain. +This is to ensure that GCC’s procedure to fix buggy system headers and +the ordering for the <code>#include_next</code> directive are not inadvertently +changed. +If you really need to change the search order for system directories, +use the <samp>-nostdinc</samp> and/or <samp>-isystem</samp> options. +See <a href="System-Headers.html#System-Headers">System Headers</a>. +</p> +<a name="index-I_002d"></a> +</dd> +<dt><code>-I-</code></dt> +<dd><p>Split the include path. +This option has been deprecated. Please use <samp>-iquote</samp> instead for +<samp>-I</samp> directories before the <samp>-I-</samp> and remove the <samp>-I-</samp> +option. +</p> +<p>Any directories specified with <samp>-I</samp> +options before <samp>-I-</samp> are searched only for headers requested with +<code>#include "<var>file</var>"<!-- /@w --></code>; they are not searched for +<code>#include <<var>file</var>><!-- /@w --></code>. If additional directories are +specified with <samp>-I</samp> options after the <samp>-I-</samp>, those +directories are searched for all ‘<samp>#include</samp>’ directives. +</p> +<p>In addition, <samp>-I-</samp> inhibits the use of the directory of the current +file directory as the first search directory for <code>#include "<var>file</var>"<!-- /@w --></code>. There is no way to override this effect of <samp>-I-</samp>. +See <a href="Search-Path.html#Search-Path">Search Path</a>. +</p> +<a name="index-iprefix"></a> +</dd> +<dt><code>-iprefix <var>prefix</var></code></dt> +<dd><p>Specify <var>prefix</var> as the prefix for subsequent <samp>-iwithprefix</samp> +options. If the prefix represents a directory, you should include the +final ‘<samp>/</samp>’. +</p> +<a name="index-iwithprefix"></a> +<a name="index-iwithprefixbefore"></a> +</dd> +<dt><code>-iwithprefix <var>dir</var></code></dt> +<dt><code>-iwithprefixbefore <var>dir</var></code></dt> +<dd><p>Append <var>dir</var> to the prefix specified previously with +<samp>-iprefix</samp>, and add the resulting directory to the include search +path. <samp>-iwithprefixbefore</samp> puts it in the same place <samp>-I</samp> +would; <samp>-iwithprefix</samp> puts it where <samp>-idirafter</samp> would. +</p> +<a name="index-isysroot"></a> +</dd> +<dt><code>-isysroot <var>dir</var></code></dt> +<dd><p>This option is like the <samp>--sysroot</samp> option, but applies only to +header files (except for Darwin targets, where it applies to both header +files and libraries). See the <samp>--sysroot</samp> option for more +information. +</p> +<a name="index-imultilib"></a> +</dd> +<dt><code>-imultilib <var>dir</var></code></dt> +<dd><p>Use <var>dir</var> as a subdirectory of the directory containing +target-specific C++ headers. +</p> +<a name="index-nostdinc"></a> +</dd> +<dt><code>-nostdinc</code></dt> +<dd><p>Do not search the standard system directories for header files. +Only the directories explicitly specified with <samp>-I</samp>, +<samp>-iquote</samp>, <samp>-isystem</samp>, and/or <samp>-idirafter</samp> +options (and the directory of the current file, if appropriate) +are searched. +</p> +<a name="index-nostdinc_002b_002b"></a> +</dd> +<dt><code>-nostdinc++</code></dt> +<dd><p>Do not search for header files in the C++-specific standard directories, +but do still search the other standard directories. (This option is +used when building the C++ library.) +</p> + + + +<a name="index-Wcomment"></a> +<a name="index-Wcomments"></a> +</dd> +<dt><code>-Wcomment</code></dt> +<dt><code>-Wcomments</code></dt> +<dd><p>Warn whenever a comment-start sequence ‘<samp>/*</samp>’ appears in a ‘<samp>/*</samp>’ +comment, or whenever a backslash-newline appears in a ‘<samp>//</samp>’ comment. +This warning is enabled by <samp>-Wall</samp>. +</p> +<a name="index-Wtrigraphs"></a> +</dd> +<dt><code>-Wtrigraphs</code></dt> +<dd><a name="Wtrigraphs"></a><p>Warn if any trigraphs are encountered that might change the meaning of +the program. Trigraphs within comments are not warned about, +except those that would form escaped newlines. +</p> +<p>This option is implied by <samp>-Wall</samp>. If <samp>-Wall</samp> is not +given, this option is still enabled unless trigraphs are enabled. To +get trigraph conversion without warnings, but get the other +<samp>-Wall</samp> warnings, use ‘<samp>-trigraphs -Wall -Wno-trigraphs</samp>’. +</p> +<a name="index-Wundef"></a> +<a name="index-Wno_002dundef"></a> +</dd> +<dt><code>-Wundef</code></dt> +<dd><p>Warn if an undefined identifier is evaluated in an <code>#if</code> directive. +Such identifiers are replaced with zero. +</p> +<a name="index-Wexpansion_002dto_002ddefined"></a> +</dd> +<dt><code>-Wexpansion-to-defined</code></dt> +<dd><p>Warn whenever ‘<samp>defined</samp>’ is encountered in the expansion of a macro +(including the case where the macro is expanded by an ‘<samp>#if</samp>’ directive). +Such usage is not portable. +This warning is also enabled by <samp>-Wpedantic</samp> and <samp>-Wextra</samp>. +</p> +<a name="index-Wunused_002dmacros"></a> +</dd> +<dt><code>-Wunused-macros</code></dt> +<dd><p>Warn about macros defined in the main file that are unused. A macro +is <em>used</em> if it is expanded or tested for existence at least once. +The preprocessor also warns if the macro has not been used at the +time it is redefined or undefined. +</p> +<p>Built-in macros, macros defined on the command line, and macros +defined in include files are not warned about. +</p> +<p><em>Note:</em> If a macro is actually used, but only used in skipped +conditional blocks, then the preprocessor reports it as unused. To avoid the +warning in such a case, you might improve the scope of the macro’s +definition by, for example, moving it into the first skipped block. +Alternatively, you could provide a dummy use with something like: +</p> +<div class="smallexample"> +<pre class="smallexample">#if defined the_macro_causing_the_warning +#endif +</pre></div> + +<a name="index-Wno_002dendif_002dlabels"></a> +<a name="index-Wendif_002dlabels"></a> +</dd> +<dt><code>-Wno-endif-labels</code></dt> +<dd><p>Do not warn whenever an <code>#else</code> or an <code>#endif</code> are followed by text. +This sometimes happens in older programs with code of the form +</p> +<div class="smallexample"> +<pre class="smallexample">#if FOO +… +#else FOO +… +#endif FOO +</pre></div> + +<p>The second and third <code>FOO</code> should be in comments. +This warning is on by default. +</p></dd> +</dl> + +<hr> +<div class="header"> +<p> +Next: <a href="Environment-Variables.html#Environment-Variables" accesskey="n" rel="next">Environment Variables</a>, Previous: <a href="Implementation-Details.html#Implementation-Details" accesskey="p" rel="previous">Implementation Details</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |