]>
Commit | Line | Data |
---|---|---|
2b6dd222 | 1 | @c Copyright (c) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 |
40adaa27 NB |
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. | |
5 | ||
6 | @c --------------------------------------------------------------------- | |
7 | @c Options affecting the preprocessor | |
8 | @c --------------------------------------------------------------------- | |
9 | ||
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. | |
12 | ||
13 | @table @gcctabopt | |
14 | @item -D @var{name} | |
15 | @opindex D | |
16 | Predefine @var{name} as a macro, with definition @code{1}. | |
17 | ||
18 | @item -D @var{name}=@var{definition} | |
a09d4744 NB |
19 | The contents of @var{definition} are tokenized and processed as if |
20 | they appeared during translation phase three in a @samp{#define} | |
21 | directive. In particular, the definition will be truncated by | |
22 | embedded newline characters. | |
23 | ||
24 | If you are invoking the preprocessor from a shell or shell-like | |
25 | program you may need to use the shell's quoting syntax to protect | |
26 | characters such as spaces that have a meaning in the shell syntax. | |
40adaa27 NB |
27 | |
28 | If you wish to define a function-like macro on the command line, write | |
29 | its argument list with surrounding parentheses before the equals sign | |
30 | (if any). Parentheses are meaningful to most shells, so you will need | |
31 | to quote the option. With @command{sh} and @command{csh}, | |
32 | @option{-D'@var{name}(@var{args@dots{}})=@var{definition}'} works. | |
33 | ||
34 | @option{-D} and @option{-U} options are processed in the order they | |
35 | are given on the command line. All @option{-imacros @var{file}} and | |
36 | @option{-include @var{file}} options are processed after all | |
37 | @option{-D} and @option{-U} options. | |
38 | ||
39 | @item -U @var{name} | |
40 | @opindex U | |
41 | Cancel any previous definition of @var{name}, either built in or | |
42 | provided with a @option{-D} option. | |
43 | ||
44 | @item -undef | |
45 | @opindex undef | |
6e270179 NB |
46 | Do not predefine any system-specific or GCC-specific macros. The |
47 | standard predefined macros remain defined. | |
48 | @ifset cppmanual | |
79406520 | 49 | @xref{Standard Predefined Macros}. |
6e270179 | 50 | @end ifset |
40adaa27 NB |
51 | |
52 | @item -I @var{dir} | |
53 | @opindex I | |
54 | Add the directory @var{dir} to the list of directories to be searched | |
55 | for header files. | |
56 | @ifset cppmanual | |
57 | @xref{Search Path}. | |
58 | @end ifset | |
59 | Directories named by @option{-I} are searched before the standard | |
48209ce5 JDA |
60 | system include directories. If the directory @var{dir} is a standard |
61 | system include directory, the option is ignored to ensure that the | |
62 | default search order for system directories and the special treatment | |
63 | of system headers are not defeated | |
40adaa27 NB |
64 | @ifset cppmanual |
65 | (@pxref{System Headers}) | |
66 | @end ifset | |
48209ce5 | 67 | . |
40adaa27 NB |
68 | |
69 | @item -o @var{file} | |
70 | @opindex o | |
71 | Write output to @var{file}. This is the same as specifying @var{file} | |
72 | as the second non-option argument to @command{cpp}. @command{gcc} has a | |
73 | different interpretation of a second non-option argument, so you must | |
74 | use @option{-o} to specify the output file. | |
75 | ||
76 | @item -Wall | |
77 | @opindex Wall | |
a8eb6044 NB |
78 | Turns on all optional warnings which are desirable for normal code. |
79 | At present this is @option{-Wcomment}, @option{-Wtrigraphs}, | |
80 | @option{-Wmultichar} and a warning about integer promotion causing a | |
81 | change of sign in @code{#if} expressions. Note that many of the | |
82 | preprocessor's warnings are on by default and have no options to | |
83 | control them. | |
40adaa27 NB |
84 | |
85 | @item -Wcomment | |
86 | @itemx -Wcomments | |
87 | @opindex Wcomment | |
88 | @opindex Wcomments | |
89 | Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*} | |
90 | comment, or whenever a backslash-newline appears in a @samp{//} comment. | |
91 | (Both forms have the same effect.) | |
92 | ||
93 | @item -Wtrigraphs | |
94 | @opindex Wtrigraphs | |
a8eb6044 | 95 | @anchor{Wtrigraphs} |
1fecc266 NB |
96 | Most trigraphs in comments cannot affect the meaning of the program. |
97 | However, a trigraph that would form an escaped newline (@samp{??/} at | |
98 | the end of a line) can, by changing where the comment begins or ends. | |
99 | Therefore, only trigraphs that would form escaped newlines produce | |
100 | warnings inside a comment. | |
101 | ||
102 | This option is implied by @option{-Wall}. If @option{-Wall} is not | |
103 | given, this option is still enabled unless trigraphs are enabled. To | |
104 | get trigraph conversion without warnings, but get the other | |
105 | @option{-Wall} warnings, use @samp{-trigraphs -Wall -Wno-trigraphs}. | |
40adaa27 NB |
106 | |
107 | @item -Wtraditional | |
108 | @opindex Wtraditional | |
109 | Warn about certain constructs that behave differently in traditional and | |
110 | ISO C@. Also warn about ISO C constructs that have no traditional C | |
111 | equivalent, and problematic constructs which should be avoided. | |
112 | @ifset cppmanual | |
113 | @xref{Traditional Mode}. | |
114 | @end ifset | |
115 | ||
116 | @item -Wimport | |
117 | @opindex Wimport | |
118 | Warn the first time @samp{#import} is used. | |
119 | ||
120 | @item -Wundef | |
121 | @opindex Wundef | |
122 | Warn whenever an identifier which is not a macro is encountered in an | |
123 | @samp{#if} directive, outside of @samp{defined}. Such identifiers are | |
124 | replaced with zero. | |
125 | ||
a69cbaac NB |
126 | @item -Wunused-macros |
127 | @opindex Wunused-macros | |
128 | Warn about macros defined in the main file that are unused. A macro | |
129 | is @dfn{used} if it is expanded or tested for existence at least once. | |
130 | The preprocessor will also warn if the macro has not been used at the | |
131 | time it is redefined or undefined. | |
132 | ||
133 | Built-in macros, macros defined on the command line, and macros | |
134 | defined in include files are not warned about. | |
135 | ||
f4559287 | 136 | @emph{Note:} If a macro is actually used, but only used in skipped |
b41f25cf NB |
137 | conditional blocks, then CPP will report it as unused. To avoid the |
138 | warning in such a case, you might improve the scope of the macro's | |
139 | definition by, for example, moving it into the first skipped block. | |
140 | Alternatively, you could provide a dummy use with something like: | |
141 | ||
142 | @smallexample | |
143 | #if defined the_macro_causing_the_warning | |
144 | #endif | |
145 | @end smallexample | |
146 | ||
909de5da PE |
147 | @item -Wendif-labels |
148 | @opindex Wendif-labels | |
149 | Warn whenever an @samp{#else} or an @samp{#endif} are followed by text. | |
150 | This usually happens in code of the form | |
151 | ||
152 | @smallexample | |
153 | #if FOO | |
154 | @dots{} | |
155 | #else FOO | |
156 | @dots{} | |
157 | #endif FOO | |
158 | @end smallexample | |
159 | ||
160 | @noindent | |
161 | The second and third @code{FOO} should be in comments, but often are not | |
162 | in older programs. This warning is on by default. | |
163 | ||
40adaa27 NB |
164 | @item -Werror |
165 | @opindex Werror | |
166 | Make all warnings into hard errors. Source code which triggers warnings | |
167 | will be rejected. | |
168 | ||
169 | @item -Wsystem-headers | |
170 | @opindex Wsystem-headers | |
171 | Issue warnings for code in system headers. These are normally unhelpful | |
172 | in finding bugs in your own code, therefore suppressed. If you are | |
173 | responsible for the system library, you may want to see them. | |
174 | ||
175 | @item -w | |
176 | @opindex w | |
177 | Suppress all warnings, including those which GNU CPP issues by default. | |
178 | ||
179 | @item -pedantic | |
180 | @opindex pedantic | |
181 | Issue all the mandatory diagnostics listed in the C standard. Some of | |
182 | them are left out by default, since they trigger frequently on harmless | |
183 | code. | |
184 | ||
185 | @item -pedantic-errors | |
186 | @opindex pedantic-errors | |
187 | Issue all the mandatory diagnostics, and make all mandatory diagnostics | |
188 | into errors. This includes mandatory diagnostics that GCC issues | |
189 | without @samp{-pedantic} but treats as warnings. | |
190 | ||
191 | @item -M | |
192 | @opindex M | |
193 | @cindex make | |
194 | @cindex dependencies, make | |
195 | Instead of outputting the result of preprocessing, output a rule | |
196 | suitable for @command{make} describing the dependencies of the main | |
197 | source file. The preprocessor outputs one @command{make} rule containing | |
198 | the object file name for that source file, a colon, and the names of all | |
199 | the included files, including those coming from @option{-include} or | |
200 | @option{-imacros} command line options. | |
201 | ||
202 | Unless specified explicitly (with @option{-MT} or @option{-MQ}), the | |
203 | object file name consists of the basename of the source file with any | |
204 | suffix replaced with object file suffix. If there are many included | |
205 | files then the rule is split into several lines using @samp{\}-newline. | |
206 | The rule has no commands. | |
207 | ||
208 | This option does not suppress the preprocessor's debug output, such as | |
209 | @option{-dM}. To avoid mixing such debug output with the dependency | |
210 | rules you should explicitly specify the dependency output file with | |
211 | @option{-MF}, or use an environment variable like | |
caba570b | 212 | @env{DEPENDENCIES_OUTPUT} (@pxref{Environment Variables}). Debug output |
40adaa27 NB |
213 | will still be sent to the regular output stream as normal. |
214 | ||
49e7b251 NB |
215 | Passing @option{-M} to the driver implies @option{-E}, and suppresses |
216 | warnings with an implicit @option{-w}. | |
40adaa27 NB |
217 | |
218 | @item -MM | |
219 | @opindex MM | |
220 | Like @option{-M} but do not mention header files that are found in | |
221 | system header directories, nor header files that are included, | |
222 | directly or indirectly, from such a header. | |
223 | ||
224 | This implies that the choice of angle brackets or double quotes in an | |
225 | @samp{#include} directive does not in itself determine whether that | |
226 | header will appear in @option{-MM} dependency output. This is a | |
227 | slight change in semantics from GCC versions 3.0 and earlier. | |
228 | ||
5560a945 | 229 | @anchor{dashMF} |
40adaa27 NB |
230 | @item -MF @var{file} |
231 | @opindex MF | |
40adaa27 NB |
232 | When used with @option{-M} or @option{-MM}, specifies a |
233 | file to write the dependencies to. If no @option{-MF} switch is given | |
234 | the preprocessor sends the rules to the same place it would have sent | |
235 | preprocessed output. | |
236 | ||
237 | When used with the driver options @option{-MD} or @option{-MMD}, | |
238 | @option{-MF} overrides the default dependency output file. | |
239 | ||
240 | @item -MG | |
241 | @opindex MG | |
3f8ffc7c RS |
242 | In conjunction with an option such as @option{-M} requesting |
243 | dependency generation, @option{-MG} assumes missing header files are | |
244 | generated files and adds them to the dependency list without raising | |
245 | an error. The dependency filename is taken directly from the | |
246 | @code{#include} directive without prepending any path. @option{-MG} | |
247 | also suppresses preprocessed output, as a missing header file renders | |
248 | this useless. | |
40adaa27 NB |
249 | |
250 | This feature is used in automatic updating of makefiles. | |
251 | ||
252 | @item -MP | |
253 | @opindex MP | |
254 | This option instructs CPP to add a phony target for each dependency | |
255 | other than the main file, causing each to depend on nothing. These | |
256 | dummy rules work around errors @command{make} gives if you remove header | |
257 | files without updating the @file{Makefile} to match. | |
258 | ||
259 | This is typical output: | |
260 | ||
3ab51846 | 261 | @smallexample |
40adaa27 NB |
262 | test.o: test.c test.h |
263 | ||
264 | test.h: | |
3ab51846 | 265 | @end smallexample |
40adaa27 NB |
266 | |
267 | @item -MT @var{target} | |
268 | @opindex MT | |
269 | ||
270 | Change the target of the rule emitted by dependency generation. By | |
271 | default CPP takes the name of the main input file, including any path, | |
272 | deletes any file suffix such as @samp{.c}, and appends the platform's | |
273 | usual object suffix. The result is the target. | |
274 | ||
275 | An @option{-MT} option will set the target to be exactly the string you | |
276 | specify. If you want multiple targets, you can specify them as a single | |
277 | argument to @option{-MT}, or use multiple @option{-MT} options. | |
278 | ||
279 | For example, @option{@w{-MT '$(objpfx)foo.o'}} might give | |
280 | ||
3ab51846 | 281 | @smallexample |
40adaa27 | 282 | $(objpfx)foo.o: foo.c |
3ab51846 | 283 | @end smallexample |
40adaa27 NB |
284 | |
285 | @item -MQ @var{target} | |
286 | @opindex MQ | |
287 | ||
288 | Same as @option{-MT}, but it quotes any characters which are special to | |
289 | Make. @option{@w{-MQ '$(objpfx)foo.o'}} gives | |
290 | ||
3ab51846 | 291 | @smallexample |
40adaa27 | 292 | $$(objpfx)foo.o: foo.c |
3ab51846 | 293 | @end smallexample |
40adaa27 NB |
294 | |
295 | The default target is automatically quoted, as if it were given with | |
296 | @option{-MQ}. | |
297 | ||
298 | @item -MD | |
299 | @opindex MD | |
300 | @option{-MD} is equivalent to @option{-M -MF @var{file}}, except that | |
301 | @option{-E} is not implied. The driver determines @var{file} based on | |
302 | whether an @option{-o} option is given. If it is, the driver uses its | |
303 | argument but with a suffix of @file{.d}, otherwise it take the | |
304 | basename of the input file and applies a @file{.d} suffix. | |
305 | ||
306 | If @option{-MD} is used in conjunction with @option{-E}, any | |
307 | @option{-o} switch is understood to specify the dependency output file | |
e8c96d09 | 308 | (@pxref{dashMF,,-MF}), but if used without @option{-E}, each @option{-o} |
40adaa27 NB |
309 | is understood to specify a target object file. |
310 | ||
311 | Since @option{-E} is not implied, @option{-MD} can be used to generate | |
312 | a dependency output file as a side-effect of the compilation process. | |
313 | ||
314 | @item -MMD | |
315 | @opindex MMD | |
316 | Like @option{-MD} except mention only user header files, not system | |
78466c0e | 317 | header files. |
40adaa27 | 318 | |
17211ab5 GK |
319 | @ifclear cppmanual |
320 | @item -fpch-deps | |
321 | @opindex fpch-deps | |
322 | When using precompiled headers (@pxref{Precompiled Headers}), this flag | |
323 | will cause the dependency-output flags to also list the files from the | |
324 | precompiled header's dependencies. If not specified only the | |
325 | precompiled header would be listed and not the files that were used to | |
326 | create it because those files are not consulted when a precompiled | |
327 | header is used. | |
328 | ||
c0d578e6 GK |
329 | @item -fpch-preprocess |
330 | @opindex fpch-preprocess | |
331 | This option allows use of a precompiled header (@pxref{Precompiled | |
332 | Headers}) together with @option{-E}. It inserts a special @code{#pragma}, | |
333 | @code{#pragma GCC pch_preprocess "<filename>"} in the output to mark | |
334 | the place where the precompiled header was found, and its filename. When | |
4ec7afd7 | 335 | @option{-fpreprocessed} is in use, GCC recognizes this @code{#pragma} and |
8a36672b | 336 | loads the PCH@. |
c0d578e6 GK |
337 | |
338 | This option is off by default, because the resulting preprocessed output | |
8a36672b | 339 | is only really suitable as input to GCC@. It is switched on by |
c0d578e6 GK |
340 | @option{-save-temps}. |
341 | ||
342 | You should not write this @code{#pragma} in your own code, but it is | |
343 | safe to edit the filename if the PCH file is available in a different | |
344 | location. The filename may be absolute or it may be relative to GCC's | |
345 | current directory. | |
346 | ||
17211ab5 | 347 | @end ifclear |
40adaa27 NB |
348 | @item -x c |
349 | @itemx -x c++ | |
350 | @itemx -x objective-c | |
351 | @itemx -x assembler-with-cpp | |
352 | @opindex x | |
353 | Specify the source language: C, C++, Objective-C, or assembly. This has | |
354 | nothing to do with standards conformance or extensions; it merely | |
355 | selects which base syntax to expect. If you give none of these options, | |
356 | cpp will deduce the language from the extension of the source file: | |
357 | @samp{.c}, @samp{.cc}, @samp{.m}, or @samp{.S}. Some other common | |
358 | extensions for C++ and assembly are also recognized. If cpp does not | |
359 | recognize the extension, it will treat the file as C; this is the most | |
360 | generic mode. | |
361 | ||
f4559287 | 362 | @emph{Note:} Previous versions of cpp accepted a @option{-lang} option |
40adaa27 NB |
363 | which selected both the language and the standards conformance level. |
364 | This option has been removed, because it conflicts with the @option{-l} | |
365 | option. | |
366 | ||
367 | @item -std=@var{standard} | |
368 | @itemx -ansi | |
369 | @opindex ansi | |
370 | @opindex std= | |
f749a36b NB |
371 | Specify the standard to which the code should conform. Currently CPP |
372 | knows about C and C++ standards; others may be added in the future. | |
40adaa27 NB |
373 | |
374 | @var{standard} | |
375 | may be one of: | |
376 | @table @code | |
377 | @item iso9899:1990 | |
378 | @itemx c89 | |
379 | The ISO C standard from 1990. @samp{c89} is the customary shorthand for | |
380 | this version of the standard. | |
381 | ||
382 | The @option{-ansi} option is equivalent to @option{-std=c89}. | |
383 | ||
384 | @item iso9899:199409 | |
385 | The 1990 C standard, as amended in 1994. | |
386 | ||
387 | @item iso9899:1999 | |
388 | @itemx c99 | |
389 | @itemx iso9899:199x | |
390 | @itemx c9x | |
391 | The revised ISO C standard, published in December 1999. Before | |
392 | publication, this was known as C9X@. | |
393 | ||
394 | @item gnu89 | |
395 | The 1990 C standard plus GNU extensions. This is the default. | |
396 | ||
397 | @item gnu99 | |
398 | @itemx gnu9x | |
399 | The 1999 C standard plus GNU extensions. | |
f749a36b NB |
400 | |
401 | @item c++98 | |
402 | The 1998 ISO C++ standard plus amendments. | |
403 | ||
404 | @item gnu++98 | |
405 | The same as @option{-std=c++98} plus GNU extensions. This is the | |
406 | default for C++ code. | |
40adaa27 NB |
407 | @end table |
408 | ||
409 | @item -I- | |
410 | @opindex I- | |
411 | Split the include path. Any directories specified with @option{-I} | |
412 | options before @option{-I-} are searched only for headers requested with | |
413 | @code{@w{#include "@var{file}"}}; they are not searched for | |
414 | @code{@w{#include <@var{file}>}}. If additional directories are | |
415 | specified with @option{-I} options after the @option{-I-}, those | |
416 | directories are searched for all @samp{#include} directives. | |
417 | ||
418 | In addition, @option{-I-} inhibits the use of the directory of the current | |
419 | file directory as the first search directory for @code{@w{#include | |
420 | "@var{file}"}}. | |
421 | @ifset cppmanual | |
422 | @xref{Search Path}. | |
423 | @end ifset | |
4bed3787 | 424 | This option has been deprecated. |
40adaa27 NB |
425 | |
426 | @item -nostdinc | |
427 | @opindex nostdinc | |
428 | Do not search the standard system directories for header files. | |
429 | Only the directories you have specified with @option{-I} options | |
430 | (and the directory of the current file, if appropriate) are searched. | |
431 | ||
432 | @item -nostdinc++ | |
433 | @opindex nostdinc++ | |
434 | Do not search for header files in the C++-specific standard directories, | |
435 | but do still search the other standard directories. (This option is | |
436 | used when building the C++ library.) | |
437 | ||
438 | @item -include @var{file} | |
439 | @opindex include | |
440 | Process @var{file} as if @code{#include "file"} appeared as the first | |
441 | line of the primary source file. However, the first directory searched | |
442 | for @var{file} is the preprocessor's working directory @emph{instead of} | |
443 | the directory containing the main source file. If not found there, it | |
444 | is searched for in the remainder of the @code{#include "@dots{}"} search | |
445 | chain as normal. | |
446 | ||
447 | If multiple @option{-include} options are given, the files are included | |
448 | in the order they appear on the command line. | |
449 | ||
450 | @item -imacros @var{file} | |
451 | @opindex imacros | |
452 | Exactly like @option{-include}, except that any output produced by | |
453 | scanning @var{file} is thrown away. Macros it defines remain defined. | |
454 | This allows you to acquire all the macros from a header without also | |
455 | processing its declarations. | |
456 | ||
457 | All files specified by @option{-imacros} are processed before all files | |
458 | specified by @option{-include}. | |
459 | ||
460 | @item -idirafter @var{dir} | |
461 | @opindex idirafter | |
462 | Search @var{dir} for header files, but do it @emph{after} all | |
463 | directories specified with @option{-I} and the standard system directories | |
464 | have been exhausted. @var{dir} is treated as a system include directory. | |
465 | ||
466 | @item -iprefix @var{prefix} | |
467 | @opindex iprefix | |
468 | Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix} | |
469 | options. If the prefix represents a directory, you should include the | |
470 | final @samp{/}. | |
471 | ||
472 | @item -iwithprefix @var{dir} | |
473 | @itemx -iwithprefixbefore @var{dir} | |
474 | @opindex iwithprefix | |
475 | @opindex iwithprefixbefore | |
476 | Append @var{dir} to the prefix specified previously with | |
477 | @option{-iprefix}, and add the resulting directory to the include search | |
478 | path. @option{-iwithprefixbefore} puts it in the same place @option{-I} | |
479 | would; @option{-iwithprefix} puts it where @option{-idirafter} would. | |
480 | ||
160633c6 MM |
481 | @item -isysroot @var{dir} |
482 | @opindex isysroot | |
483 | This option is like the @option{--sysroot} option, but applies only to | |
484 | header files. See the @option{--sysroot} option for more information. | |
485 | ||
2b6dd222 JM |
486 | @item -imultilib @var{dir} |
487 | @opindex imultilib | |
488 | Use @var{dir} as a subdirectory of the directory containing | |
489 | target-specific C++ headers. | |
490 | ||
40adaa27 NB |
491 | @item -isystem @var{dir} |
492 | @opindex isystem | |
493 | Search @var{dir} for header files, after all directories specified by | |
494 | @option{-I} but before the standard system directories. Mark it | |
495 | as a system directory, so that it gets the same special treatment as | |
496 | is applied to the standard system directories. | |
497 | @ifset cppmanual | |
498 | @xref{System Headers}. | |
499 | @end ifset | |
500 | ||
4bed3787 MS |
501 | @item -iquote @var{dir} |
502 | @opindex iquote | |
503 | Search @var{dir} only for header files requested with | |
504 | @code{@w{#include "@var{file}"}}; they are not searched for | |
505 | @code{@w{#include <@var{file}>}}, before all directories specified by | |
506 | @option{-I} and before the standard system directories. | |
507 | @ifset cppmanual | |
508 | @xref{Search Path}. | |
509 | @end ifset | |
510 | ||
b1822ccc NB |
511 | @item -fdollars-in-identifiers |
512 | @opindex fdollars-in-identifiers | |
513 | @anchor{fdollars-in-identifiers} | |
514 | Accept @samp{$} in identifiers. | |
515 | @ifset cppmanual | |
516 | @xref{Identifier characters}. | |
517 | @end ifset | |
518 | ||
af15a2fe JM |
519 | @item -fextended-identifiers |
520 | @opindex fextended-identifiers | |
521 | Accept universal character names in identifiers. This option is | |
522 | experimental; in a future version of GCC, it will be enabled by | |
523 | default for C99 and C++. | |
524 | ||
40adaa27 NB |
525 | @item -fpreprocessed |
526 | @opindex fpreprocessed | |
527 | Indicate to the preprocessor that the input file has already been | |
528 | preprocessed. This suppresses things like macro expansion, trigraph | |
529 | conversion, escaped newline splicing, and processing of most directives. | |
530 | The preprocessor still recognizes and removes comments, so that you can | |
531 | pass a file preprocessed with @option{-C} to the compiler without | |
532 | problems. In this mode the integrated preprocessor is little more than | |
533 | a tokenizer for the front ends. | |
534 | ||
535 | @option{-fpreprocessed} is implicit if the input file has one of the | |
536 | extensions @samp{.i}, @samp{.ii} or @samp{.mi}. These are the | |
537 | extensions that GCC uses for preprocessed files created by | |
538 | @option{-save-temps}. | |
539 | ||
540 | @item -ftabstop=@var{width} | |
541 | @opindex ftabstop | |
542 | Set the distance between tab stops. This helps the preprocessor report | |
543 | correct column numbers in warnings or errors, even if tabs appear on the | |
544 | line. If the value is less than 1 or greater than 100, the option is | |
545 | ignored. The default is 8. | |
546 | ||
e6cc3a24 ZW |
547 | @item -fexec-charset=@var{charset} |
548 | @opindex fexec-charset | |
50668cf6 | 549 | @cindex character set, execution |
e6cc3a24 ZW |
550 | Set the execution character set, used for string and character |
551 | constants. The default is UTF-8. @var{charset} can be any encoding | |
552 | supported by the system's @code{iconv} library routine. | |
553 | ||
554 | @item -fwide-exec-charset=@var{charset} | |
555 | @opindex fwide-exec-charset | |
50668cf6 | 556 | @cindex character set, wide execution |
e6cc3a24 ZW |
557 | Set the wide execution character set, used for wide string and |
558 | character constants. The default is UTF-32 or UTF-16, whichever | |
559 | corresponds to the width of @code{wchar_t}. As with | |
bc4c01b7 | 560 | @option{-fexec-charset}, @var{charset} can be any encoding supported |
e6cc3a24 ZW |
561 | by the system's @code{iconv} library routine; however, you will have |
562 | problems with encodings that do not fit exactly in @code{wchar_t}. | |
563 | ||
16dd5cfe EC |
564 | @item -finput-charset=@var{charset} |
565 | @opindex finput-charset | |
50668cf6 | 566 | @cindex character set, input |
16dd5cfe | 567 | Set the input character set, used for translation from the character |
8a36672b | 568 | set of the input file to the source character set used by GCC@. If the |
16dd5cfe | 569 | locale does not specify, or GCC cannot get this information from the |
8a36672b JM |
570 | locale, the default is UTF-8. This can be overridden by either the locale |
571 | or this command line option. Currently the command line option takes | |
572 | precedence if there's a conflict. @var{charset} can be any encoding | |
16dd5cfe EC |
573 | supported by the system's @code{iconv} library routine. |
574 | ||
b20d9f0c AO |
575 | @item -fworking-directory |
576 | @opindex fworking-directory | |
577 | @opindex fno-working-directory | |
578 | Enable generation of linemarkers in the preprocessor output that will | |
579 | let the compiler know the current working directory at the time of | |
580 | preprocessing. When this option is enabled, the preprocessor will | |
581 | emit, after the initial linemarker, a second linemarker with the | |
582 | current working directory followed by two slashes. GCC will use this | |
583 | directory, when it's present in the preprocessed input, as the | |
584 | directory emitted as the current working directory in some debugging | |
585 | information formats. This option is implicitly enabled if debugging | |
586 | information is enabled, but this can be inhibited with the negated | |
587 | form @option{-fno-working-directory}. If the @option{-P} flag is | |
588 | present in the command line, this option has no effect, since no | |
589 | @code{#line} directives are emitted whatsoever. | |
590 | ||
40adaa27 NB |
591 | @item -fno-show-column |
592 | @opindex fno-show-column | |
593 | Do not print column numbers in diagnostics. This may be necessary if | |
594 | diagnostics are being scanned by a program that does not understand the | |
595 | column numbers, such as @command{dejagnu}. | |
596 | ||
597 | @item -A @var{predicate}=@var{answer} | |
598 | @opindex A | |
599 | Make an assertion with the predicate @var{predicate} and answer | |
600 | @var{answer}. This form is preferred to the older form @option{-A | |
601 | @var{predicate}(@var{answer})}, which is still supported, because | |
602 | it does not use shell special characters. | |
603 | @ifset cppmanual | |
604 | @xref{Assertions}. | |
605 | @end ifset | |
606 | ||
607 | @item -A -@var{predicate}=@var{answer} | |
608 | Cancel an assertion with the predicate @var{predicate} and answer | |
609 | @var{answer}. | |
610 | ||
40adaa27 NB |
611 | @item -dCHARS |
612 | @var{CHARS} is a sequence of one or more of the following characters, | |
613 | and must not be preceded by a space. Other characters are interpreted | |
614 | by the compiler proper, or reserved for future versions of GCC, and so | |
615 | are silently ignored. If you specify characters whose behavior | |
616 | conflicts, the result is undefined. | |
617 | ||
618 | @table @samp | |
619 | @item M | |
620 | @opindex dM | |
621 | Instead of the normal output, generate a list of @samp{#define} | |
622 | directives for all the macros defined during the execution of the | |
623 | preprocessor, including predefined macros. This gives you a way of | |
624 | finding out what is predefined in your version of the preprocessor. | |
625 | Assuming you have no file @file{foo.h}, the command | |
626 | ||
3ab51846 | 627 | @smallexample |
40adaa27 | 628 | touch foo.h; cpp -dM foo.h |
3ab51846 | 629 | @end smallexample |
40adaa27 NB |
630 | |
631 | @noindent | |
632 | will show all the predefined macros. | |
633 | ||
634 | @item D | |
635 | @opindex dD | |
636 | Like @samp{M} except in two respects: it does @emph{not} include the | |
637 | predefined macros, and it outputs @emph{both} the @samp{#define} | |
638 | directives and the result of preprocessing. Both kinds of output go to | |
639 | the standard output file. | |
640 | ||
641 | @item N | |
642 | @opindex dN | |
643 | Like @samp{D}, but emit only the macro names, not their expansions. | |
644 | ||
645 | @item I | |
646 | @opindex dI | |
647 | Output @samp{#include} directives in addition to the result of | |
648 | preprocessing. | |
649 | @end table | |
650 | ||
651 | @item -P | |
652 | @opindex P | |
653 | Inhibit generation of linemarkers in the output from the preprocessor. | |
654 | This might be useful when running the preprocessor on something that is | |
655 | not C code, and will be sent to a program which might be confused by the | |
656 | linemarkers. | |
657 | @ifset cppmanual | |
658 | @xref{Preprocessor Output}. | |
659 | @end ifset | |
660 | ||
661 | @item -C | |
662 | @opindex C | |
663 | Do not discard comments. All comments are passed through to the output | |
664 | file, except for comments in processed directives, which are deleted | |
665 | along with the directive. | |
666 | ||
667 | You should be prepared for side effects when using @option{-C}; it | |
668 | causes the preprocessor to treat comments as tokens in their own right. | |
669 | For example, comments appearing at the start of what would be a | |
670 | directive line have the effect of turning that line into an ordinary | |
671 | source line, since the first token on the line is no longer a @samp{#}. | |
672 | ||
477cdac7 JT |
673 | @item -CC |
674 | Do not discard comments, including during macro expansion. This is | |
675 | like @option{-C}, except that comments contained within macros are | |
676 | also passed through to the output file where the macro is expanded. | |
677 | ||
678 | In addition to the side-effects of the @option{-C} option, the | |
679 | @option{-CC} option causes all C++-style comments inside a macro | |
680 | to be converted to C-style comments. This is to prevent later use | |
9a376494 | 681 | of that macro from inadvertently commenting out the remainder of |
477cdac7 JT |
682 | the source line. |
683 | ||
684 | The @option{-CC} option is generally used to support lint comments. | |
685 | ||
b6fb43ab NB |
686 | @item -traditional-cpp |
687 | @opindex traditional-cpp | |
688 | Try to imitate the behavior of old-fashioned C preprocessors, as | |
689 | opposed to ISO C preprocessors. | |
40adaa27 NB |
690 | @ifset cppmanual |
691 | @xref{Traditional Mode}. | |
692 | @end ifset | |
693 | ||
694 | @item -trigraphs | |
695 | @opindex trigraphs | |
696 | Process trigraph sequences. | |
697 | @ifset cppmanual | |
698 | @xref{Initial processing}. | |
699 | @end ifset | |
700 | @ifclear cppmanual | |
701 | These are three-character sequences, all starting with @samp{??}, that | |
702 | are defined by ISO C to stand for single characters. For example, | |
703 | @samp{??/} stands for @samp{\}, so @samp{'??/n'} is a character | |
704 | constant for a newline. By default, GCC ignores trigraphs, but in | |
705 | standard-conforming modes it converts them. See the @option{-std} and | |
706 | @option{-ansi} options. | |
707 | ||
708 | The nine trigraphs and their replacements are | |
709 | ||
478c9e72 | 710 | @smallexample |
40adaa27 NB |
711 | Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- |
712 | Replacement: [ ] @{ @} # \ ^ | ~ | |
478c9e72 | 713 | @end smallexample |
40adaa27 NB |
714 | @end ifclear |
715 | ||
716 | @item -remap | |
717 | @opindex remap | |
718 | Enable special code to work around file systems which only permit very | |
719 | short file names, such as MS-DOS@. | |
720 | ||
40adaa27 NB |
721 | @itemx --help |
722 | @itemx --target-help | |
40adaa27 NB |
723 | @opindex help |
724 | @opindex target-help | |
725 | Print text describing all the command line options instead of | |
726 | preprocessing anything. | |
727 | ||
728 | @item -v | |
729 | @opindex v | |
730 | Verbose mode. Print out GNU CPP's version number at the beginning of | |
731 | execution, and report the final form of the include path. | |
732 | ||
733 | @item -H | |
734 | @opindex H | |
735 | Print the name of each header file used, in addition to other normal | |
736 | activities. Each name is indented to show how deep in the | |
79406520 GK |
737 | @samp{#include} stack it is. Precompiled header files are also |
738 | printed, even if they are found to be invalid; an invalid precompiled | |
739 | header file is printed with @samp{...x} and a valid one with @samp{...!} . | |
40adaa27 NB |
740 | |
741 | @item -version | |
742 | @itemx --version | |
743 | @opindex version | |
744 | Print out GNU CPP's version number. With one dash, proceed to | |
745 | preprocess as normal. With two dashes, exit immediately. | |
746 | @end table |