| <html lang="en"> |
| <head> |
| <title>Invocation - The C Preprocessor</title> |
| <meta http-equiv="Content-Type" content="text/html"> |
| <meta name="description" content="The C Preprocessor"> |
| <meta name="generator" content="makeinfo 4.13"> |
| <link title="Top" rel="start" href="index.html#Top"> |
| <link rel="prev" href="Implementation-Details.html#Implementation-Details" title="Implementation Details"> |
| <link rel="next" href="Environment-Variables.html#Environment-Variables" title="Environment Variables"> |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> |
| <!-- |
| Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, |
| 2008, 2009, 2010 |
| 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.2 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. |
| --> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <style type="text/css"><!-- |
| pre.display { font-family:inherit } |
| pre.format { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| pre.smallformat { font-family:inherit; font-size:smaller } |
| pre.smallexample { font-size:smaller } |
| pre.smalllisp { font-size:smaller } |
| span.sc { font-variant:small-caps } |
| span.roman { font-family:serif; font-weight:normal; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| <link rel="stylesheet" type="text/css" href="../cs.css"> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="Invocation"></a> |
| <p> |
| Next: <a rel="next" accesskey="n" href="Environment-Variables.html#Environment-Variables">Environment Variables</a>, |
| Previous: <a rel="previous" accesskey="p" href="Implementation-Details.html#Implementation-Details">Implementation Details</a>, |
| Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a> |
| <hr> |
| </div> |
| |
| <h2 class="chapter">12 Invocation</h2> |
| |
| <p><a name="index-invocation-118"></a><a name="index-command-line-119"></a> |
| Most often when you use the C preprocessor you will not have to invoke it |
| explicitly: the C compiler will do so automatically. However, the |
| preprocessor is sometimes useful on its own. All the options listed |
| here are also acceptable to the C compiler and have the same meaning, |
| except that the C compiler has different rules for specifying the output |
| file. |
| |
| <p><em>Note:</em> Whether you use the preprocessor by way of <samp><span class="command">gcc</span></samp> |
| or <samp><span class="command">cpp</span></samp>, the <dfn>compiler driver</dfn> is run first. This |
| program's purpose is to translate your command into invocations of the |
| programs that do the actual work. Their command line interfaces are |
| similar but not identical to the documented interface, and may change |
| without notice. |
| |
| <!-- man begin OPTIONS --> |
| <p>The C preprocessor 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><span class="samp">#include</span></samp>’. All the output generated |
| by the combined input files is written in <var>outfile</var>. |
| |
| <p>Either <var>infile</var> or <var>outfile</var> may be <samp><span class="option">-</span></samp>, which as |
| <var>infile</var> means to read from standard input and as <var>outfile</var> |
| means to write to standard output. Also, if either file is omitted, it |
| means the same as if <samp><span class="option">-</span></samp> had been specified for that file. |
| |
| <p>Unless otherwise noted, or the option ends in ‘<samp><span class="samp">=</span></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><span class="option">-Ifoo</span></samp> and <samp><span class="option">-I foo</span></samp> have the same effect. |
| |
| <p><a name="index-grouping-options-120"></a><a name="index-options_002c-grouping-121"></a>Many options have multi-letter names; therefore multiple single-letter |
| options may <em>not</em> be grouped: <samp><span class="option">-dM</span></samp> is very different from |
| ‘<samp><span class="samp">-d -M</span></samp>’<!-- /@w -->. |
| |
| <p><a name="index-options-122"></a> |
| |
| <!-- Copyright (c) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, --> |
| <!-- 2010, Free Software Foundation, Inc. --> |
| <!-- This is part of the CPP and GCC manuals. --> |
| <!-- For copying conditions, see the file gcc.texi. --> |
| <!-- --> |
| <!-- Options affecting the preprocessor --> |
| <!-- --> |
| <!-- If this file is included with the flag ``cppmanual'' set, it is --> |
| <!-- formatted for inclusion in the CPP manual; otherwise the main GCC manual. --> |
| <dl> |
| <dt><code>-D </code><var>name</var><dd><a name="index-D-123"></a>Predefine <var>name</var> as a macro, with definition <code>1</code>. |
| |
| <br><dt><code>-D </code><var>name</var><code>=</code><var>definition</var><dd>The contents of <var>definition</var> are tokenized and processed as if |
| they appeared during translation phase three in a ‘<samp><span class="samp">#define</span></samp>’ |
| directive. In particular, the definition will be truncated by |
| embedded newline characters. |
| |
| <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>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 will need |
| to quote the option. With <samp><span class="command">sh</span></samp> and <samp><span class="command">csh</span></samp>, |
| <samp><span class="option">-D'</span><var>name</var><span class="option">(</span><var>args<small class="dots">...</small></var><span class="option">)=</span><var>definition</var><span class="option">'</span></samp> works. |
| |
| <p><samp><span class="option">-D</span></samp> and <samp><span class="option">-U</span></samp> options are processed in the order they |
| are given on the command line. All <samp><span class="option">-imacros </span><var>file</var></samp> and |
| <samp><span class="option">-include </span><var>file</var></samp> options are processed after all |
| <samp><span class="option">-D</span></samp> and <samp><span class="option">-U</span></samp> options. |
| |
| <br><dt><code>-U </code><var>name</var><dd><a name="index-U-124"></a>Cancel any previous definition of <var>name</var>, either built in or |
| provided with a <samp><span class="option">-D</span></samp> option. |
| |
| <br><dt><code>-undef</code><dd><a name="index-undef-125"></a>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>. |
| |
| <br><dt><code>-I </code><var>dir</var><dd><a name="index-I-126"></a>Add the directory <var>dir</var> to the list of directories to be searched |
| for header files. |
| See <a href="Search-Path.html#Search-Path">Search Path</a>. |
| Directories named by <samp><span class="option">-I</span></samp> are searched before the standard |
| system include directories. If the directory <var>dir</var> is a standard |
| system include directory, the option is ignored to ensure that the |
| default search order for system directories and the special treatment |
| of system headers are not defeated |
| (see <a href="System-Headers.html#System-Headers">System Headers</a>) |
| . |
| If <var>dir</var> begins with <code>=</code>, then the <code>=</code> will be replaced |
| by the sysroot prefix; see <samp><span class="option">--sysroot</span></samp> and <samp><span class="option">-isysroot</span></samp>. |
| |
| <br><dt><code>-o </code><var>file</var><dd><a name="index-o-127"></a>Write output to <var>file</var>. This is the same as specifying <var>file</var> |
| as the second non-option argument to <samp><span class="command">cpp</span></samp>. <samp><span class="command">gcc</span></samp> has a |
| different interpretation of a second non-option argument, so you must |
| use <samp><span class="option">-o</span></samp> to specify the output file. |
| |
| <br><dt><code>-Wall</code><dd><a name="index-Wall-128"></a>Turns on all optional warnings which are desirable for normal code. |
| At present this is <samp><span class="option">-Wcomment</span></samp>, <samp><span class="option">-Wtrigraphs</span></samp>, |
| <samp><span class="option">-Wmultichar</span></samp> and a warning about integer promotion causing a |
| change of sign in <code>#if</code> expressions. Note that many of the |
| preprocessor's warnings are on by default and have no options to |
| control them. |
| |
| <br><dt><code>-Wcomment</code><dt><code>-Wcomments</code><dd><a name="index-Wcomment-129"></a><a name="index-Wcomments-130"></a>Warn whenever a comment-start sequence ‘<samp><span class="samp">/*</span></samp>’ appears in a ‘<samp><span class="samp">/*</span></samp>’ |
| comment, or whenever a backslash-newline appears in a ‘<samp><span class="samp">//</span></samp>’ comment. |
| (Both forms have the same effect.) |
| |
| <br><dt><code>-Wtrigraphs</code><dd><a name="index-Wtrigraphs-131"></a><a name="Wtrigraphs"></a>Most trigraphs in comments cannot affect the meaning of the program. |
| However, a trigraph that would form an escaped newline (‘<samp><span class="samp">??/</span></samp>’ at |
| the end of a line) can, by changing where the comment begins or ends. |
| Therefore, only trigraphs that would form escaped newlines produce |
| warnings inside a comment. |
| |
| <p>This option is implied by <samp><span class="option">-Wall</span></samp>. If <samp><span class="option">-Wall</span></samp> is not |
| given, this option is still enabled unless trigraphs are enabled. To |
| get trigraph conversion without warnings, but get the other |
| <samp><span class="option">-Wall</span></samp> warnings, use ‘<samp><span class="samp">-trigraphs -Wall -Wno-trigraphs</span></samp>’. |
| |
| <br><dt><code>-Wtraditional</code><dd><a name="index-Wtraditional-132"></a>Warn about certain constructs that behave differently in traditional and |
| ISO C. Also warn about ISO C constructs that have no traditional C |
| equivalent, and problematic constructs which should be avoided. |
| See <a href="Traditional-Mode.html#Traditional-Mode">Traditional Mode</a>. |
| |
| <br><dt><code>-Wundef</code><dd><a name="index-Wundef-133"></a>Warn whenever an identifier which is not a macro is encountered in an |
| ‘<samp><span class="samp">#if</span></samp>’ directive, outside of ‘<samp><span class="samp">defined</span></samp>’. Such identifiers are |
| replaced with zero. |
| |
| <br><dt><code>-Wunused-macros</code><dd><a name="index-Wunused_002dmacros-134"></a>Warn about macros defined in the main file that are unused. A macro |
| is <dfn>used</dfn> if it is expanded or tested for existence at least once. |
| The preprocessor will also warn if the macro has not been used at the |
| time it is redefined or undefined. |
| |
| <p>Built-in macros, macros defined on the command line, and macros |
| defined in include files are not warned about. |
| |
| <p><em>Note:</em> If a macro is actually used, but only used in skipped |
| conditional blocks, then CPP will report 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: |
| |
| <pre class="smallexample"> #if defined the_macro_causing_the_warning |
| #endif |
| </pre> |
| <br><dt><code>-Wendif-labels</code><dd><a name="index-Wendif_002dlabels-135"></a>Warn whenever an ‘<samp><span class="samp">#else</span></samp>’ or an ‘<samp><span class="samp">#endif</span></samp>’ are followed by text. |
| This usually happens in code of the form |
| |
| <pre class="smallexample"> #if FOO |
| ... |
| #else FOO |
| ... |
| #endif FOO |
| </pre> |
| <p class="noindent">The second and third <code>FOO</code> should be in comments, but often are not |
| in older programs. This warning is on by default. |
| |
| <br><dt><code>-Werror</code><dd><a name="index-Werror-136"></a>Make all warnings into hard errors. Source code which triggers warnings |
| will be rejected. |
| |
| <br><dt><code>-Wsystem-headers</code><dd><a name="index-Wsystem_002dheaders-137"></a>Issue warnings for code in system headers. These are normally unhelpful |
| in finding bugs in your own code, therefore suppressed. If you are |
| responsible for the system library, you may want to see them. |
| |
| <br><dt><code>-w</code><dd><a name="index-w-138"></a>Suppress all warnings, including those which GNU CPP issues by default. |
| |
| <br><dt><code>-pedantic</code><dd><a name="index-pedantic-139"></a>Issue all the mandatory diagnostics listed in the C standard. Some of |
| them are left out by default, since they trigger frequently on harmless |
| code. |
| |
| <br><dt><code>-pedantic-errors</code><dd><a name="index-pedantic_002derrors-140"></a>Issue all the mandatory diagnostics, and make all mandatory diagnostics |
| into errors. This includes mandatory diagnostics that GCC issues |
| without ‘<samp><span class="samp">-pedantic</span></samp>’ but treats as warnings. |
| |
| <br><dt><code>-M</code><dd><a name="index-M-141"></a><a name="index-make-142"></a><a name="index-dependencies_002c-make-143"></a>Instead of outputting the result of preprocessing, output a rule |
| suitable for <samp><span class="command">make</span></samp> describing the dependencies of the main |
| source file. The preprocessor outputs one <samp><span class="command">make</span></samp> 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><span class="option">-include</span></samp> or |
| <samp><span class="option">-imacros</span></samp> command line options. |
| |
| <p>Unless specified explicitly (with <samp><span class="option">-MT</span></samp> or <samp><span class="option">-MQ</span></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><span class="samp">\</span></samp>’-newline. The rule has no |
| commands. |
| |
| <p>This option does not suppress the preprocessor's debug output, such as |
| <samp><span class="option">-dM</span></samp>. To avoid mixing such debug output with the dependency |
| rules you should explicitly specify the dependency output file with |
| <samp><span class="option">-MF</span></samp>, or use an environment variable like |
| <samp><span class="env">DEPENDENCIES_OUTPUT</span></samp> (see <a href="Environment-Variables.html#Environment-Variables">Environment Variables</a>). Debug output |
| will still be sent to the regular output stream as normal. |
| |
| <p>Passing <samp><span class="option">-M</span></samp> to the driver implies <samp><span class="option">-E</span></samp>, and suppresses |
| warnings with an implicit <samp><span class="option">-w</span></samp>. |
| |
| <br><dt><code>-MM</code><dd><a name="index-MM-144"></a>Like <samp><span class="option">-M</span></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>This implies that the choice of angle brackets or double quotes in an |
| ‘<samp><span class="samp">#include</span></samp>’ directive does not in itself determine whether that |
| header will appear in <samp><span class="option">-MM</span></samp> dependency output. This is a |
| slight change in semantics from GCC versions 3.0 and earlier. |
| |
| <p><a name="dashMF"></a><br><dt><code>-MF </code><var>file</var><dd><a name="index-MF-145"></a>When used with <samp><span class="option">-M</span></samp> or <samp><span class="option">-MM</span></samp>, specifies a |
| file to write the dependencies to. If no <samp><span class="option">-MF</span></samp> switch is given |
| the preprocessor sends the rules to the same place it would have sent |
| preprocessed output. |
| |
| <p>When used with the driver options <samp><span class="option">-MD</span></samp> or <samp><span class="option">-MMD</span></samp>, |
| <samp><span class="option">-MF</span></samp> overrides the default dependency output file. |
| |
| <br><dt><code>-MG</code><dd><a name="index-MG-146"></a>In conjunction with an option such as <samp><span class="option">-M</span></samp> requesting |
| dependency generation, <samp><span class="option">-MG</span></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><span class="option">-MG</span></samp> |
| also suppresses preprocessed output, as a missing header file renders |
| this useless. |
| |
| <p>This feature is used in automatic updating of makefiles. |
| |
| <br><dt><code>-MP</code><dd><a name="index-MP-147"></a>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 <samp><span class="command">make</span></samp> gives if you remove header |
| files without updating the <samp><span class="file">Makefile</span></samp> to match. |
| |
| <p>This is typical output: |
| |
| <pre class="smallexample"> test.o: test.c test.h |
| |
| test.h: |
| </pre> |
| <br><dt><code>-MT </code><var>target</var><dd><a name="index-MT-148"></a> |
| 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><span class="samp">.c</span></samp>’, and |
| appends the platform's usual object suffix. The result is the target. |
| |
| <p>An <samp><span class="option">-MT</span></samp> option will set the target to be exactly the string you |
| specify. If you want multiple targets, you can specify them as a single |
| argument to <samp><span class="option">-MT</span></samp>, or use multiple <samp><span class="option">-MT</span></samp> options. |
| |
| <p>For example, <samp><span class="option">-MT '$(objpfx)foo.o'<!-- /@w --></span></samp> might give |
| |
| <pre class="smallexample"> $(objpfx)foo.o: foo.c |
| </pre> |
| <br><dt><code>-MQ </code><var>target</var><dd><a name="index-MQ-149"></a> |
| Same as <samp><span class="option">-MT</span></samp>, but it quotes any characters which are special to |
| Make. <samp><span class="option">-MQ '$(objpfx)foo.o'<!-- /@w --></span></samp> gives |
| |
| <pre class="smallexample"> $$(objpfx)foo.o: foo.c |
| </pre> |
| <p>The default target is automatically quoted, as if it were given with |
| <samp><span class="option">-MQ</span></samp>. |
| |
| <br><dt><code>-MD</code><dd><a name="index-MD-150"></a><samp><span class="option">-MD</span></samp> is equivalent to <samp><span class="option">-M -MF </span><var>file</var></samp>, except that |
| <samp><span class="option">-E</span></samp> is not implied. The driver determines <var>file</var> based on |
| whether an <samp><span class="option">-o</span></samp> option is given. If it is, the driver uses its |
| argument but with a suffix of <samp><span class="file">.d</span></samp>, otherwise it takes the name |
| of the input file, removes any directory components and suffix, and |
| applies a <samp><span class="file">.d</span></samp> suffix. |
| |
| <p>If <samp><span class="option">-MD</span></samp> is used in conjunction with <samp><span class="option">-E</span></samp>, any |
| <samp><span class="option">-o</span></samp> switch is understood to specify the dependency output file |
| (see <a href="dashMF.html#dashMF">-MF</a>), but if used without <samp><span class="option">-E</span></samp>, each <samp><span class="option">-o</span></samp> |
| is understood to specify a target object file. |
| |
| <p>Since <samp><span class="option">-E</span></samp> is not implied, <samp><span class="option">-MD</span></samp> can be used to generate |
| a dependency output file as a side-effect of the compilation process. |
| |
| <br><dt><code>-MMD</code><dd><a name="index-MMD-151"></a>Like <samp><span class="option">-MD</span></samp> except mention only user header files, not system |
| header files. |
| |
| <br><dt><code>-x c</code><dt><code>-x c++</code><dt><code>-x objective-c</code><dt><code>-x assembler-with-cpp</code><dd><a name="index-x-152"></a>Specify the source language: C, C++, Objective-C, or assembly. This has |
| nothing to do with standards conformance or extensions; it merely |
| selects which base syntax to expect. If you give none of these options, |
| cpp will deduce the language from the extension of the source file: |
| ‘<samp><span class="samp">.c</span></samp>’, ‘<samp><span class="samp">.cc</span></samp>’, ‘<samp><span class="samp">.m</span></samp>’, or ‘<samp><span class="samp">.S</span></samp>’. Some other common |
| extensions for C++ and assembly are also recognized. If cpp does not |
| recognize the extension, it will treat the file as C; this is the most |
| generic mode. |
| |
| <p><em>Note:</em> Previous versions of cpp accepted a <samp><span class="option">-lang</span></samp> option |
| which selected both the language and the standards conformance level. |
| This option has been removed, because it conflicts with the <samp><span class="option">-l</span></samp> |
| option. |
| |
| <br><dt><code>-std=</code><var>standard</var><dt><code>-ansi</code><dd><a name="index-ansi-153"></a><a name="index-std_003d-154"></a>Specify the standard to which the code should conform. Currently CPP |
| knows about C and C++ standards; others may be added in the future. |
| |
| <p><var>standard</var> |
| may be one of: |
| <dl> |
| <dt><code>c90</code><dt><code>c89</code><dt><code>iso9899:1990</code><dd>The ISO C standard from 1990. ‘<samp><span class="samp">c90</span></samp>’ is the customary shorthand for |
| this version of the standard. |
| |
| <p>The <samp><span class="option">-ansi</span></samp> option is equivalent to <samp><span class="option">-std=c90</span></samp>. |
| |
| <br><dt><code>iso9899:199409</code><dd>The 1990 C standard, as amended in 1994. |
| |
| <br><dt><code>iso9899:1999</code><dt><code>c99</code><dt><code>iso9899:199x</code><dt><code>c9x</code><dd>The revised ISO C standard, published in December 1999. Before |
| publication, this was known as C9X. |
| |
| <br><dt><code>gnu90</code><dt><code>gnu89</code><dd>The 1990 C standard plus GNU extensions. This is the default. |
| |
| <br><dt><code>gnu99</code><dt><code>gnu9x</code><dd>The 1999 C standard plus GNU extensions. |
| |
| <br><dt><code>c++98</code><dd>The 1998 ISO C++ standard plus amendments. |
| |
| <br><dt><code>gnu++98</code><dd>The same as <samp><span class="option">-std=c++98</span></samp> plus GNU extensions. This is the |
| default for C++ code. |
| </dl> |
| |
| <br><dt><code>-I-</code><dd><a name="index-I_002d-155"></a>Split the include path. Any directories specified with <samp><span class="option">-I</span></samp> |
| options before <samp><span class="option">-I-</span></samp> are searched only for headers requested with |
| <code>#include "</code><var>file</var><code>"<!-- /@w --></code>; they are not searched for |
| <code>#include <</code><var>file</var><code>><!-- /@w --></code>. If additional directories are |
| specified with <samp><span class="option">-I</span></samp> options after the <samp><span class="option">-I-</span></samp>, those |
| directories are searched for all ‘<samp><span class="samp">#include</span></samp>’ directives. |
| |
| <p>In addition, <samp><span class="option">-I-</span></samp> inhibits the use of the directory of the current |
| file directory as the first search directory for <code>#include "</code><var>file</var><code>"<!-- /@w --></code>. |
| See <a href="Search-Path.html#Search-Path">Search Path</a>. |
| This option has been deprecated. |
| |
| <br><dt><code>-nostdinc</code><dd><a name="index-nostdinc-156"></a>Do not search the standard system directories for header files. |
| Only the directories you have specified with <samp><span class="option">-I</span></samp> options |
| (and the directory of the current file, if appropriate) are searched. |
| |
| <br><dt><code>-nostdinc++</code><dd><a name="index-nostdinc_002b_002b-157"></a>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.) |
| |
| <br><dt><code>-include </code><var>file</var><dd><a name="index-include-158"></a>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>If multiple <samp><span class="option">-include</span></samp> options are given, the files are included |
| in the order they appear on the command line. |
| |
| <br><dt><code>-imacros </code><var>file</var><dd><a name="index-imacros-159"></a>Exactly like <samp><span class="option">-include</span></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>All files specified by <samp><span class="option">-imacros</span></samp> are processed before all files |
| specified by <samp><span class="option">-include</span></samp>. |
| |
| <br><dt><code>-idirafter </code><var>dir</var><dd><a name="index-idirafter-160"></a>Search <var>dir</var> for header files, but do it <em>after</em> all |
| directories specified with <samp><span class="option">-I</span></samp> and the standard system directories |
| have been exhausted. <var>dir</var> is treated as a system include directory. |
| If <var>dir</var> begins with <code>=</code>, then the <code>=</code> will be replaced |
| by the sysroot prefix; see <samp><span class="option">--sysroot</span></samp> and <samp><span class="option">-isysroot</span></samp>. |
| |
| <br><dt><code>-iprefix </code><var>prefix</var><dd><a name="index-iprefix-161"></a>Specify <var>prefix</var> as the prefix for subsequent <samp><span class="option">-iwithprefix</span></samp> |
| options. If the prefix represents a directory, you should include the |
| final ‘<samp><span class="samp">/</span></samp>’. |
| |
| <br><dt><code>-iwithprefix </code><var>dir</var><dt><code>-iwithprefixbefore </code><var>dir</var><dd><a name="index-iwithprefix-162"></a><a name="index-iwithprefixbefore-163"></a>Append <var>dir</var> to the prefix specified previously with |
| <samp><span class="option">-iprefix</span></samp>, and add the resulting directory to the include search |
| path. <samp><span class="option">-iwithprefixbefore</span></samp> puts it in the same place <samp><span class="option">-I</span></samp> |
| would; <samp><span class="option">-iwithprefix</span></samp> puts it where <samp><span class="option">-idirafter</span></samp> would. |
| |
| <br><dt><code>-isysroot </code><var>dir</var><dd><a name="index-isysroot-164"></a>This option is like the <samp><span class="option">--sysroot</span></samp> option, but applies only to |
| header files. See the <samp><span class="option">--sysroot</span></samp> option for more information. |
| |
| <br><dt><code>-imultilib </code><var>dir</var><dd><a name="index-imultilib-165"></a>Use <var>dir</var> as a subdirectory of the directory containing |
| target-specific C++ headers. |
| |
| <br><dt><code>-isystem </code><var>dir</var><dd><a name="index-isystem-166"></a>Search <var>dir</var> for header files, after all directories specified by |
| <samp><span class="option">-I</span></samp> but before the standard system directories. Mark it |
| as a system directory, so that it gets the same special treatment as |
| is applied to the standard system directories. |
| See <a href="System-Headers.html#System-Headers">System Headers</a>. |
| If <var>dir</var> begins with <code>=</code>, then the <code>=</code> will be replaced |
| by the sysroot prefix; see <samp><span class="option">--sysroot</span></samp> and <samp><span class="option">-isysroot</span></samp>. |
| |
| <br><dt><code>-iquote </code><var>dir</var><dd><a name="index-iquote-167"></a>Search <var>dir</var> only for header files requested with |
| <code>#include "</code><var>file</var><code>"<!-- /@w --></code>; they are not searched for |
| <code>#include <</code><var>file</var><code>><!-- /@w --></code>, before all directories specified by |
| <samp><span class="option">-I</span></samp> and before the standard system directories. |
| See <a href="Search-Path.html#Search-Path">Search Path</a>. |
| If <var>dir</var> begins with <code>=</code>, then the <code>=</code> will be replaced |
| by the sysroot prefix; see <samp><span class="option">--sysroot</span></samp> and <samp><span class="option">-isysroot</span></samp>. |
| |
| <br><dt><code>-fdirectives-only</code><dd><a name="index-fdirectives_002donly-168"></a>When preprocessing, handle directives, but do not expand macros. |
| |
| <p>The option's behavior depends on the <samp><span class="option">-E</span></samp> and <samp><span class="option">-fpreprocessed</span></samp> |
| options. |
| |
| <p>With <samp><span class="option">-E</span></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><span class="option">-dD</span></samp> option is |
| implicitly enabled. |
| |
| <p>With <samp><span class="option">-fpreprocessed</span></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>With both <samp><span class="option">-E</span></samp> and <samp><span class="option">-fpreprocessed</span></samp>, the rules for |
| <samp><span class="option">-fpreprocessed</span></samp> take precedence. This enables full preprocessing of |
| files previously preprocessed with <code>-E -fdirectives-only</code>. |
| |
| <br><dt><code>-fdollars-in-identifiers</code><dd><a name="index-fdollars_002din_002didentifiers-169"></a><a name="fdollars_002din_002didentifiers"></a>Accept ‘<samp><span class="samp">$</span></samp>’ in identifiers. |
| See <a href="Identifier-characters.html#Identifier-characters">Identifier characters</a>. |
| |
| <br><dt><code>-fextended-identifiers</code><dd><a name="index-fextended_002didentifiers-170"></a>Accept universal character names in identifiers. This option is |
| experimental; in a future version of GCC, it will be enabled by |
| default for C99 and C++. |
| |
| <br><dt><code>-fpreprocessed</code><dd><a name="index-fpreprocessed-171"></a>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><span class="option">-C</span></samp> to the compiler without |
| problems. In this mode the integrated preprocessor is little more than |
| a tokenizer for the front ends. |
| |
| <p><samp><span class="option">-fpreprocessed</span></samp> is implicit if the input file has one of the |
| extensions ‘<samp><span class="samp">.i</span></samp>’, ‘<samp><span class="samp">.ii</span></samp>’ or ‘<samp><span class="samp">.mi</span></samp>’. These are the |
| extensions that GCC uses for preprocessed files created by |
| <samp><span class="option">-save-temps</span></samp>. |
| |
| <br><dt><code>-ftabstop=</code><var>width</var><dd><a name="index-ftabstop-172"></a>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. |
| |
| <br><dt><code>-fexec-charset=</code><var>charset</var><dd><a name="index-fexec_002dcharset-173"></a><a name="index-character-set_002c-execution-174"></a>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. |
| |
| <br><dt><code>-fwide-exec-charset=</code><var>charset</var><dd><a name="index-fwide_002dexec_002dcharset-175"></a><a name="index-character-set_002c-wide-execution-176"></a>Set the wide execution character set, used for wide string and |
| character constants. The default is UTF-32 or UTF-16, whichever |
| corresponds to the width of <code>wchar_t</code>. As with |
| <samp><span class="option">-fexec-charset</span></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>. |
| |
| <br><dt><code>-finput-charset=</code><var>charset</var><dd><a name="index-finput_002dcharset-177"></a><a name="index-character-set_002c-input-178"></a>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. |
| |
| <br><dt><code>-fworking-directory</code><dd><a name="index-fworking_002ddirectory-179"></a><a name="index-fno_002dworking_002ddirectory-180"></a>Enable generation of linemarkers in the preprocessor output that will |
| let the compiler know the current working directory at the time of |
| preprocessing. When this option is enabled, the preprocessor will |
| emit, after the initial linemarker, a second linemarker with the |
| current working directory followed by two slashes. GCC will use 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><span class="option">-fno-working-directory</span></samp>. If the <samp><span class="option">-P</span></samp> flag is |
| present in the command line, this option has no effect, since no |
| <code>#line</code> directives are emitted whatsoever. |
| |
| <br><dt><code>-fno-show-column</code><dd><a name="index-fno_002dshow_002dcolumn-181"></a>Do not print column numbers in diagnostics. This may be necessary if |
| diagnostics are being scanned by a program that does not understand the |
| column numbers, such as <samp><span class="command">dejagnu</span></samp>. |
| |
| <br><dt><code>-A </code><var>predicate</var><code>=</code><var>answer</var><dd><a name="index-A-182"></a>Make an assertion with the predicate <var>predicate</var> and answer |
| <var>answer</var>. This form is preferred to the older form <samp><span class="option">-A |
| </span><var>predicate</var><span class="option">(</span><var>answer</var><span class="option">)</span></samp>, which is still supported, because |
| it does not use shell special characters. |
| See <a href="Obsolete-Features.html#Obsolete-Features">Obsolete Features</a>. |
| |
| <br><dt><code>-A -</code><var>predicate</var><code>=</code><var>answer</var><dd>Cancel an assertion with the predicate <var>predicate</var> and answer |
| <var>answer</var>. |
| |
| <br><dt><code>-dCHARS</code><dd><var>CHARS</var> is a sequence of one or more of the following characters, |
| and must not be preceded by a space. Other characters are interpreted |
| by the compiler proper, or reserved for future versions of GCC, and so |
| are silently ignored. If you specify characters whose behavior |
| conflicts, the result is undefined. |
| |
| <dl> |
| <dt>‘<samp><span class="samp">M</span></samp>’<dd><a name="index-dM-183"></a>Instead of the normal output, generate a list of ‘<samp><span class="samp">#define</span></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><span class="file">foo.h</span></samp>, the command |
| |
| <pre class="smallexample"> touch foo.h; cpp -dM foo.h |
| </pre> |
| <p class="noindent">will show all the predefined macros. |
| |
| <p>If you use <samp><span class="option">-dM</span></samp> without the <samp><span class="option">-E</span></samp> option, <samp><span class="option">-dM</span></samp> is |
| interpreted as a synonym for <samp><span class="option">-fdump-rtl-mach</span></samp>. |
| See <a href="../gcc/Debugging-Options.html#Debugging-Options">Debugging Options</a>. |
| |
| <br><dt>‘<samp><span class="samp">D</span></samp>’<dd><a name="index-dD-184"></a>Like ‘<samp><span class="samp">M</span></samp>’ except in two respects: it does <em>not</em> include the |
| predefined macros, and it outputs <em>both</em> the ‘<samp><span class="samp">#define</span></samp>’ |
| directives and the result of preprocessing. Both kinds of output go to |
| the standard output file. |
| |
| <br><dt>‘<samp><span class="samp">N</span></samp>’<dd><a name="index-dN-185"></a>Like ‘<samp><span class="samp">D</span></samp>’, but emit only the macro names, not their expansions. |
| |
| <br><dt>‘<samp><span class="samp">I</span></samp>’<dd><a name="index-dI-186"></a>Output ‘<samp><span class="samp">#include</span></samp>’ directives in addition to the result of |
| preprocessing. |
| |
| <br><dt>‘<samp><span class="samp">U</span></samp>’<dd><a name="index-dU-187"></a>Like ‘<samp><span class="samp">D</span></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><span class="samp">#undef</span></samp>’ directives are also output for macros tested but |
| undefined at the time. |
| </dl> |
| |
| <br><dt><code>-P</code><dd><a name="index-P-188"></a>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>. |
| |
| <br><dt><code>-C</code><dd><a name="index-C-189"></a>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>You should be prepared for side effects when using <samp><span class="option">-C</span></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><span class="samp">#</span></samp>’. |
| |
| <br><dt><code>-CC</code><dd>Do not discard comments, including during macro expansion. This is |
| like <samp><span class="option">-C</span></samp>, except that comments contained within macros are |
| also passed through to the output file where the macro is expanded. |
| |
| <p>In addition to the side-effects of the <samp><span class="option">-C</span></samp> option, the |
| <samp><span class="option">-CC</span></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>The <samp><span class="option">-CC</span></samp> option is generally used to support lint comments. |
| |
| <br><dt><code>-traditional-cpp</code><dd><a name="index-traditional_002dcpp-190"></a>Try to imitate the behavior of old-fashioned C preprocessors, as |
| opposed to ISO C preprocessors. |
| See <a href="Traditional-Mode.html#Traditional-Mode">Traditional Mode</a>. |
| |
| <br><dt><code>-trigraphs</code><dd><a name="index-trigraphs-191"></a>Process trigraph sequences. |
| See <a href="Initial-processing.html#Initial-processing">Initial processing</a>. |
| |
| <br><dt><code>-remap</code><dd><a name="index-remap-192"></a>Enable special code to work around file systems which only permit very |
| short file names, such as MS-DOS. |
| |
| <dt><code>--help</code><dt><code>--target-help</code><dd><a name="index-help-193"></a><a name="index-target_002dhelp-194"></a>Print text describing all the command line options instead of |
| preprocessing anything. |
| |
| <br><dt><code>-v</code><dd><a name="index-v-195"></a>Verbose mode. Print out GNU CPP's version number at the beginning of |
| execution, and report the final form of the include path. |
| |
| <br><dt><code>-H</code><dd><a name="index-H-196"></a>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><span class="samp">#include</span></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><span class="samp">...x</span></samp>’ and a valid one with ‘<samp><span class="samp">...!</span></samp>’ . |
| |
| <br><dt><code>-version</code><dt><code>--version</code><dd><a name="index-version-197"></a>Print out GNU CPP's version number. With one dash, proceed to |
| preprocess as normal. With two dashes, exit immediately. |
| </dl> |
| <!-- man end --> |
| |
| </body></html> |
| |