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