1 @c Copyright (c) 1999, 2000, 2001, 2002
2 @c Free Software Foundation, Inc.
3 @c This is part of the CPP and GCC manuals.
4 @c For copying conditions, see the file gcc.texi.
6 @c ---------------------------------------------------------------------
7 @c Options affecting the preprocessor
8 @c ---------------------------------------------------------------------
10 @c If this file is included with the flag ``cppmanual'' set, it is
11 @c formatted for inclusion in the CPP manual; otherwise the main GCC manual.
16 Predefine @var{name} as a macro, with definition @code{1}.
18 @item -D @var{name}=@var{definition}
19 Predefine @var{name} as a macro, with definition @var{definition}.
20 There are no restrictions on the contents of @var{definition}, but if
21 you are invoking the preprocessor from a shell or shell-like program you
22 may need to use the shell's quoting syntax to protect characters such as
23 spaces that have a meaning in the shell syntax.
25 If you wish to define a function-like macro on the command line, write
26 its argument list with surrounding parentheses before the equals sign
27 (if any). Parentheses are meaningful to most shells, so you will need
28 to quote the option. With @command{sh} and @command{csh},
29 @option{-D'@var{name}(@var{args@dots{}})=@var{definition}'} works.
31 @option{-D} and @option{-U} options are processed in the order they
32 are given on the command line. All @option{-imacros @var{file}} and
33 @option{-include @var{file}} options are processed after all
34 @option{-D} and @option{-U} options.
38 Cancel any previous definition of @var{name}, either built in or
39 provided with a @option{-D} option.
43 Do not predefine any system-specific macros. The common predefined
44 macros remain defined.
48 Add the directory @var{dir} to the list of directories to be searched
53 Directories named by @option{-I} are searched before the standard
54 system include directories.
56 It is dangerous to specify a standard system include directory in an
57 @option{-I} option. This defeats the special treatment of system
60 (@pxref{System Headers})
62 . It can also defeat the repairs to buggy system headers which GCC
63 makes when it is installed.
67 Write output to @var{file}. This is the same as specifying @var{file}
68 as the second non-option argument to @command{cpp}. @command{gcc} has a
69 different interpretation of a second non-option argument, so you must
70 use @option{-o} to specify the output file.
74 Turns on all optional warnings which are desirable for normal code. At
75 present this is @option{-Wcomment} and @option{-Wtrigraphs}. Note that
76 many of the preprocessor's warnings are on by default and have no
77 options to control them.
83 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
84 comment, or whenever a backslash-newline appears in a @samp{//} comment.
85 (Both forms have the same effect.)
89 Warn if any trigraphs are encountered. This option used to take effect
90 only if @option{-trigraphs} was also specified, but now works
91 independently. Warnings are not given for trigraphs within comments, as
92 they do not affect the meaning of the program.
96 Warn about certain constructs that behave differently in traditional and
97 ISO C@. Also warn about ISO C constructs that have no traditional C
98 equivalent, and problematic constructs which should be avoided.
100 @xref{Traditional Mode}.
105 Warn the first time @samp{#import} is used.
109 Warn whenever an identifier which is not a macro is encountered in an
110 @samp{#if} directive, outside of @samp{defined}. Such identifiers are
115 Make all warnings into hard errors. Source code which triggers warnings
118 @item -Wsystem-headers
119 @opindex Wsystem-headers
120 Issue warnings for code in system headers. These are normally unhelpful
121 in finding bugs in your own code, therefore suppressed. If you are
122 responsible for the system library, you may want to see them.
126 Suppress all warnings, including those which GNU CPP issues by default.
130 Issue all the mandatory diagnostics listed in the C standard. Some of
131 them are left out by default, since they trigger frequently on harmless
134 @item -pedantic-errors
135 @opindex pedantic-errors
136 Issue all the mandatory diagnostics, and make all mandatory diagnostics
137 into errors. This includes mandatory diagnostics that GCC issues
138 without @samp{-pedantic} but treats as warnings.
143 @cindex dependencies, make
144 Instead of outputting the result of preprocessing, output a rule
145 suitable for @command{make} describing the dependencies of the main
146 source file. The preprocessor outputs one @command{make} rule containing
147 the object file name for that source file, a colon, and the names of all
148 the included files, including those coming from @option{-include} or
149 @option{-imacros} command line options.
151 Unless specified explicitly (with @option{-MT} or @option{-MQ}), the
152 object file name consists of the basename of the source file with any
153 suffix replaced with object file suffix. If there are many included
154 files then the rule is split into several lines using @samp{\}-newline.
155 The rule has no commands.
157 This option does not suppress the preprocessor's debug output, such as
158 @option{-dM}. To avoid mixing such debug output with the dependency
159 rules you should explicitly specify the dependency output file with
160 @option{-MF}, or use an environment variable like
161 @env{DEPENDENCIES_OUTPUT} (@pxref{DEPENDENCIES_OUTPUT}). Debug output
162 will still be sent to the regular output stream as normal.
164 Passing @option{-M} to the driver implies @option{-E}.
168 Like @option{-M} but do not mention header files that are found in
169 system header directories, nor header files that are included,
170 directly or indirectly, from such a header.
172 This implies that the choice of angle brackets or double quotes in an
173 @samp{#include} directive does not in itself determine whether that
174 header will appear in @option{-MM} dependency output. This is a
175 slight change in semantics from GCC versions 3.0 and earlier.
180 When used with @option{-M} or @option{-MM}, specifies a
181 file to write the dependencies to. If no @option{-MF} switch is given
182 the preprocessor sends the rules to the same place it would have sent
185 When used with the driver options @option{-MD} or @option{-MMD},
186 @option{-MF} overrides the default dependency output file.
190 When used with @option{-M} or @option{-MM}, @option{-MG} says to treat missing
191 header files as generated files and assume they live in the same
192 directory as the source file. It suppresses preprocessed output, as a
193 missing header file is ordinarily an error.
195 This feature is used in automatic updating of makefiles.
199 This option instructs CPP to add a phony target for each dependency
200 other than the main file, causing each to depend on nothing. These
201 dummy rules work around errors @command{make} gives if you remove header
202 files without updating the @file{Makefile} to match.
204 This is typical output:
207 test.o: test.c test.h
212 @item -MT @var{target}
215 Change the target of the rule emitted by dependency generation. By
216 default CPP takes the name of the main input file, including any path,
217 deletes any file suffix such as @samp{.c}, and appends the platform's
218 usual object suffix. The result is the target.
220 An @option{-MT} option will set the target to be exactly the string you
221 specify. If you want multiple targets, you can specify them as a single
222 argument to @option{-MT}, or use multiple @option{-MT} options.
224 For example, @option{@w{-MT '$(objpfx)foo.o'}} might give
227 $(objpfx)foo.o: foo.c
230 @item -MQ @var{target}
233 Same as @option{-MT}, but it quotes any characters which are special to
234 Make. @option{@w{-MQ '$(objpfx)foo.o'}} gives
237 $$(objpfx)foo.o: foo.c
240 The default target is automatically quoted, as if it were given with
245 @option{-MD} is equivalent to @option{-M -MF @var{file}}, except that
246 @option{-E} is not implied. The driver determines @var{file} based on
247 whether an @option{-o} option is given. If it is, the driver uses its
248 argument but with a suffix of @file{.d}, otherwise it take the
249 basename of the input file and applies a @file{.d} suffix.
251 If @option{-MD} is used in conjunction with @option{-E}, any
252 @option{-o} switch is understood to specify the dependency output file
253 (but @pxref{-MF}), but if used without @option{-E}, each @option{-o}
254 is understood to specify a target object file.
256 Since @option{-E} is not implied, @option{-MD} can be used to generate
257 a dependency output file as a side-effect of the compilation process.
261 Like @option{-MD} except mention only user header files, not system
266 @itemx -x objective-c
267 @itemx -x assembler-with-cpp
269 Specify the source language: C, C++, Objective-C, or assembly. This has
270 nothing to do with standards conformance or extensions; it merely
271 selects which base syntax to expect. If you give none of these options,
272 cpp will deduce the language from the extension of the source file:
273 @samp{.c}, @samp{.cc}, @samp{.m}, or @samp{.S}. Some other common
274 extensions for C++ and assembly are also recognized. If cpp does not
275 recognize the extension, it will treat the file as C; this is the most
278 @strong{Note:} Previous versions of cpp accepted a @option{-lang} option
279 which selected both the language and the standards conformance level.
280 This option has been removed, because it conflicts with the @option{-l}
283 @item -std=@var{standard}
287 Specify the standard to which the code should conform. Currently cpp
288 only knows about the standards for C; other language standards will be
296 The ISO C standard from 1990. @samp{c89} is the customary shorthand for
297 this version of the standard.
299 The @option{-ansi} option is equivalent to @option{-std=c89}.
302 The 1990 C standard, as amended in 1994.
308 The revised ISO C standard, published in December 1999. Before
309 publication, this was known as C9X@.
312 The 1990 C standard plus GNU extensions. This is the default.
316 The 1999 C standard plus GNU extensions.
321 Split the include path. Any directories specified with @option{-I}
322 options before @option{-I-} are searched only for headers requested with
323 @code{@w{#include "@var{file}"}}; they are not searched for
324 @code{@w{#include <@var{file}>}}. If additional directories are
325 specified with @option{-I} options after the @option{-I-}, those
326 directories are searched for all @samp{#include} directives.
328 In addition, @option{-I-} inhibits the use of the directory of the current
329 file directory as the first search directory for @code{@w{#include
337 Do not search the standard system directories for header files.
338 Only the directories you have specified with @option{-I} options
339 (and the directory of the current file, if appropriate) are searched.
343 Do not search for header files in the C++-specific standard directories,
344 but do still search the other standard directories. (This option is
345 used when building the C++ library.)
347 @item -include @var{file}
349 Process @var{file} as if @code{#include "file"} appeared as the first
350 line of the primary source file. However, the first directory searched
351 for @var{file} is the preprocessor's working directory @emph{instead of}
352 the directory containing the main source file. If not found there, it
353 is searched for in the remainder of the @code{#include "@dots{}"} search
356 If multiple @option{-include} options are given, the files are included
357 in the order they appear on the command line.
359 @item -imacros @var{file}
361 Exactly like @option{-include}, except that any output produced by
362 scanning @var{file} is thrown away. Macros it defines remain defined.
363 This allows you to acquire all the macros from a header without also
364 processing its declarations.
366 All files specified by @option{-imacros} are processed before all files
367 specified by @option{-include}.
369 @item -idirafter @var{dir}
371 Search @var{dir} for header files, but do it @emph{after} all
372 directories specified with @option{-I} and the standard system directories
373 have been exhausted. @var{dir} is treated as a system include directory.
375 @item -iprefix @var{prefix}
377 Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix}
378 options. If the prefix represents a directory, you should include the
381 @item -iwithprefix @var{dir}
382 @itemx -iwithprefixbefore @var{dir}
384 @opindex iwithprefixbefore
385 Append @var{dir} to the prefix specified previously with
386 @option{-iprefix}, and add the resulting directory to the include search
387 path. @option{-iwithprefixbefore} puts it in the same place @option{-I}
388 would; @option{-iwithprefix} puts it where @option{-idirafter} would.
390 Use of these options is discouraged.
392 @item -isystem @var{dir}
394 Search @var{dir} for header files, after all directories specified by
395 @option{-I} but before the standard system directories. Mark it
396 as a system directory, so that it gets the same special treatment as
397 is applied to the standard system directories.
399 @xref{System Headers}.
403 @opindex fpreprocessed
404 Indicate to the preprocessor that the input file has already been
405 preprocessed. This suppresses things like macro expansion, trigraph
406 conversion, escaped newline splicing, and processing of most directives.
407 The preprocessor still recognizes and removes comments, so that you can
408 pass a file preprocessed with @option{-C} to the compiler without
409 problems. In this mode the integrated preprocessor is little more than
410 a tokenizer for the front ends.
412 @option{-fpreprocessed} is implicit if the input file has one of the
413 extensions @samp{.i}, @samp{.ii} or @samp{.mi}. These are the
414 extensions that GCC uses for preprocessed files created by
415 @option{-save-temps}.
417 @item -ftabstop=@var{width}
419 Set the distance between tab stops. This helps the preprocessor report
420 correct column numbers in warnings or errors, even if tabs appear on the
421 line. If the value is less than 1 or greater than 100, the option is
422 ignored. The default is 8.
424 @item -fno-show-column
425 @opindex fno-show-column
426 Do not print column numbers in diagnostics. This may be necessary if
427 diagnostics are being scanned by a program that does not understand the
428 column numbers, such as @command{dejagnu}.
430 @item -A @var{predicate}=@var{answer}
432 Make an assertion with the predicate @var{predicate} and answer
433 @var{answer}. This form is preferred to the older form @option{-A
434 @var{predicate}(@var{answer})}, which is still supported, because
435 it does not use shell special characters.
440 @item -A -@var{predicate}=@var{answer}
441 Cancel an assertion with the predicate @var{predicate} and answer
446 Cancel all predefined assertions and all assertions preceding it on
447 the command line. Also, undefine all predefined macros and all
448 macros preceding it on the command line. (This is a historical wart and
449 may change in the future.)
452 @var{CHARS} is a sequence of one or more of the following characters,
453 and must not be preceded by a space. Other characters are interpreted
454 by the compiler proper, or reserved for future versions of GCC, and so
455 are silently ignored. If you specify characters whose behavior
456 conflicts, the result is undefined.
461 Instead of the normal output, generate a list of @samp{#define}
462 directives for all the macros defined during the execution of the
463 preprocessor, including predefined macros. This gives you a way of
464 finding out what is predefined in your version of the preprocessor.
465 Assuming you have no file @file{foo.h}, the command
468 touch foo.h; cpp -dM foo.h
472 will show all the predefined macros.
476 Like @samp{M} except in two respects: it does @emph{not} include the
477 predefined macros, and it outputs @emph{both} the @samp{#define}
478 directives and the result of preprocessing. Both kinds of output go to
479 the standard output file.
483 Like @samp{D}, but emit only the macro names, not their expansions.
487 Output @samp{#include} directives in addition to the result of
493 Inhibit generation of linemarkers in the output from the preprocessor.
494 This might be useful when running the preprocessor on something that is
495 not C code, and will be sent to a program which might be confused by the
498 @xref{Preprocessor Output}.
503 Do not discard comments. All comments are passed through to the output
504 file, except for comments in processed directives, which are deleted
505 along with the directive.
507 You should be prepared for side effects when using @option{-C}; it
508 causes the preprocessor to treat comments as tokens in their own right.
509 For example, comments appearing at the start of what would be a
510 directive line have the effect of turning that line into an ordinary
511 source line, since the first token on the line is no longer a @samp{#}.
515 Define the macros @sc{__gnuc__}, @sc{__gnuc_minor__} and
516 @sc{__gnuc_patchlevel__}. These are defined automatically when you use
517 @command{gcc -E}; you can turn them off in that case with
522 Try to imitate the behavior of old-fashioned C, as opposed to ISO
525 @xref{Traditional Mode}.
530 Process trigraph sequences.
532 @xref{Initial processing}.
535 These are three-character sequences, all starting with @samp{??}, that
536 are defined by ISO C to stand for single characters. For example,
537 @samp{??/} stands for @samp{\}, so @samp{'??/n'} is a character
538 constant for a newline. By default, GCC ignores trigraphs, but in
539 standard-conforming modes it converts them. See the @option{-std} and
540 @option{-ansi} options.
542 The nine trigraphs and their replacements are
545 Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??-
546 Replacement: [ ] @{ @} # \ ^ | ~
552 Enable special code to work around file systems which only permit very
553 short file names, such as MS-DOS@.
557 Forbid the use of @samp{$} in identifiers. The C standard allows
558 implementations to define extra characters that can appear in
559 identifiers. By default GNU CPP permits @samp{$}, a common extension.
567 Print text describing all the command line options instead of
568 preprocessing anything.
572 Verbose mode. Print out GNU CPP's version number at the beginning of
573 execution, and report the final form of the include path.
577 Print the name of each header file used, in addition to other normal
578 activities. Each name is indented to show how deep in the
579 @samp{#include} stack it is.
584 Print out GNU CPP's version number. With one dash, proceed to
585 preprocess as normal. With two dashes, exit immediately.