Mercurial > hg > CbC > CbC_gcc
comparison gcc/doc/cppopts.texi @ 111:04ced10e8804
gcc 7
author | kono |
---|---|
date | Fri, 27 Oct 2017 22:46:09 +0900 |
parents | f6334be47118 |
children | 84e7813d76e9 |
comparison
equal
deleted
inserted
replaced
68:561a7518be6b | 111:04ced10e8804 |
---|---|
1 @c Copyright (c) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, | 1 @c Copyright (C) 1999-2017 Free Software Foundation, Inc. |
2 @c 2010, Free Software Foundation, Inc. | |
3 @c This is part of the CPP and GCC manuals. | 2 @c This is part of the CPP and GCC manuals. |
4 @c For copying conditions, see the file gcc.texi. | 3 @c For copying conditions, see the file gcc.texi. |
5 | 4 |
6 @c --------------------------------------------------------------------- | 5 @c --------------------------------------------------------------------- |
7 @c Options affecting the preprocessor | 6 @c Options affecting the preprocessor |
8 @c --------------------------------------------------------------------- | 7 @c --------------------------------------------------------------------- |
9 | 8 |
10 @c If this file is included with the flag ``cppmanual'' set, it is | 9 @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. | 10 @c formatted for inclusion in the CPP manual; otherwise the main GCC manual. |
12 | 11 |
13 @table @gcctabopt | |
14 @item -D @var{name} | 12 @item -D @var{name} |
15 @opindex D | 13 @opindex D |
16 Predefine @var{name} as a macro, with definition @code{1}. | 14 Predefine @var{name} as a macro, with definition @code{1}. |
17 | 15 |
18 @item -D @var{name}=@var{definition} | 16 @item -D @var{name}=@var{definition} |
19 The contents of @var{definition} are tokenized and processed as if | 17 The contents of @var{definition} are tokenized and processed as if |
20 they appeared during translation phase three in a @samp{#define} | 18 they appeared during translation phase three in a @samp{#define} |
21 directive. In particular, the definition will be truncated by | 19 directive. In particular, the definition is truncated by |
22 embedded newline characters. | 20 embedded newline characters. |
23 | 21 |
24 If you are invoking the preprocessor from a shell or shell-like | 22 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 | 23 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. | 24 characters such as spaces that have a meaning in the shell syntax. |
27 | 25 |
28 If you wish to define a function-like macro on the command line, write | 26 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 | 27 its argument list with surrounding parentheses before the equals sign |
30 (if any). Parentheses are meaningful to most shells, so you will need | 28 (if any). Parentheses are meaningful to most shells, so you should |
31 to quote the option. With @command{sh} and @command{csh}, | 29 quote the option. With @command{sh} and @command{csh}, |
32 @option{-D'@var{name}(@var{args@dots{}})=@var{definition}'} works. | 30 @option{-D'@var{name}(@var{args@dots{}})=@var{definition}'} works. |
33 | 31 |
34 @option{-D} and @option{-U} options are processed in the order they | 32 @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 | 33 are given on the command line. All @option{-imacros @var{file}} and |
36 @option{-include @var{file}} options are processed after all | 34 @option{-include @var{file}} options are processed after all |
38 | 36 |
39 @item -U @var{name} | 37 @item -U @var{name} |
40 @opindex U | 38 @opindex U |
41 Cancel any previous definition of @var{name}, either built in or | 39 Cancel any previous definition of @var{name}, either built in or |
42 provided with a @option{-D} option. | 40 provided with a @option{-D} option. |
41 | |
42 @item -include @var{file} | |
43 @opindex include | |
44 Process @var{file} as if @code{#include "file"} appeared as the first | |
45 line of the primary source file. However, the first directory searched | |
46 for @var{file} is the preprocessor's working directory @emph{instead of} | |
47 the directory containing the main source file. If not found there, it | |
48 is searched for in the remainder of the @code{#include "@dots{}"} search | |
49 chain as normal. | |
50 | |
51 If multiple @option{-include} options are given, the files are included | |
52 in the order they appear on the command line. | |
53 | |
54 @item -imacros @var{file} | |
55 @opindex imacros | |
56 Exactly like @option{-include}, except that any output produced by | |
57 scanning @var{file} is thrown away. Macros it defines remain defined. | |
58 This allows you to acquire all the macros from a header without also | |
59 processing its declarations. | |
60 | |
61 All files specified by @option{-imacros} are processed before all files | |
62 specified by @option{-include}. | |
43 | 63 |
44 @item -undef | 64 @item -undef |
45 @opindex undef | 65 @opindex undef |
46 Do not predefine any system-specific or GCC-specific macros. The | 66 Do not predefine any system-specific or GCC-specific macros. The |
47 standard predefined macros remain defined. | 67 standard predefined macros remain defined. |
48 @ifset cppmanual | 68 @ifset cppmanual |
49 @xref{Standard Predefined Macros}. | 69 @xref{Standard Predefined Macros}. |
50 @end ifset | 70 @end ifset |
51 | 71 |
52 @item -I @var{dir} | 72 @item -pthread |
53 @opindex I | 73 @opindex pthread |
54 Add the directory @var{dir} to the list of directories to be searched | 74 Define additional macros required for using the POSIX threads library. |
55 for header files. | 75 You should use this option consistently for both compilation and linking. |
56 @ifset cppmanual | 76 This option is supported on GNU/Linux targets, most other Unix derivatives, |
57 @xref{Search Path}. | 77 and also on x86 Cygwin and MinGW targets. |
58 @end ifset | |
59 Directories named by @option{-I} are searched before the standard | |
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 | |
64 @ifset cppmanual | |
65 (@pxref{System Headers}) | |
66 @end ifset | |
67 . | |
68 If @var{dir} begins with @code{=}, then the @code{=} will be replaced | |
69 by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}. | |
70 | |
71 @item -o @var{file} | |
72 @opindex o | |
73 Write output to @var{file}. This is the same as specifying @var{file} | |
74 as the second non-option argument to @command{cpp}. @command{gcc} has a | |
75 different interpretation of a second non-option argument, so you must | |
76 use @option{-o} to specify the output file. | |
77 | |
78 @item -Wall | |
79 @opindex Wall | |
80 Turns on all optional warnings which are desirable for normal code. | |
81 At present this is @option{-Wcomment}, @option{-Wtrigraphs}, | |
82 @option{-Wmultichar} and a warning about integer promotion causing a | |
83 change of sign in @code{#if} expressions. Note that many of the | |
84 preprocessor's warnings are on by default and have no options to | |
85 control them. | |
86 | |
87 @item -Wcomment | |
88 @itemx -Wcomments | |
89 @opindex Wcomment | |
90 @opindex Wcomments | |
91 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*} | |
92 comment, or whenever a backslash-newline appears in a @samp{//} comment. | |
93 (Both forms have the same effect.) | |
94 | |
95 @item -Wtrigraphs | |
96 @opindex Wtrigraphs | |
97 @anchor{Wtrigraphs} | |
98 Most trigraphs in comments cannot affect the meaning of the program. | |
99 However, a trigraph that would form an escaped newline (@samp{??/} at | |
100 the end of a line) can, by changing where the comment begins or ends. | |
101 Therefore, only trigraphs that would form escaped newlines produce | |
102 warnings inside a comment. | |
103 | |
104 This option is implied by @option{-Wall}. If @option{-Wall} is not | |
105 given, this option is still enabled unless trigraphs are enabled. To | |
106 get trigraph conversion without warnings, but get the other | |
107 @option{-Wall} warnings, use @samp{-trigraphs -Wall -Wno-trigraphs}. | |
108 | |
109 @item -Wtraditional | |
110 @opindex Wtraditional | |
111 Warn about certain constructs that behave differently in traditional and | |
112 ISO C@. Also warn about ISO C constructs that have no traditional C | |
113 equivalent, and problematic constructs which should be avoided. | |
114 @ifset cppmanual | |
115 @xref{Traditional Mode}. | |
116 @end ifset | |
117 | |
118 @item -Wundef | |
119 @opindex Wundef | |
120 Warn whenever an identifier which is not a macro is encountered in an | |
121 @samp{#if} directive, outside of @samp{defined}. Such identifiers are | |
122 replaced with zero. | |
123 | |
124 @item -Wunused-macros | |
125 @opindex Wunused-macros | |
126 Warn about macros defined in the main file that are unused. A macro | |
127 is @dfn{used} if it is expanded or tested for existence at least once. | |
128 The preprocessor will also warn if the macro has not been used at the | |
129 time it is redefined or undefined. | |
130 | |
131 Built-in macros, macros defined on the command line, and macros | |
132 defined in include files are not warned about. | |
133 | |
134 @emph{Note:} If a macro is actually used, but only used in skipped | |
135 conditional blocks, then CPP will report it as unused. To avoid the | |
136 warning in such a case, you might improve the scope of the macro's | |
137 definition by, for example, moving it into the first skipped block. | |
138 Alternatively, you could provide a dummy use with something like: | |
139 | |
140 @smallexample | |
141 #if defined the_macro_causing_the_warning | |
142 #endif | |
143 @end smallexample | |
144 | |
145 @item -Wendif-labels | |
146 @opindex Wendif-labels | |
147 Warn whenever an @samp{#else} or an @samp{#endif} are followed by text. | |
148 This usually happens in code of the form | |
149 | |
150 @smallexample | |
151 #if FOO | |
152 @dots{} | |
153 #else FOO | |
154 @dots{} | |
155 #endif FOO | |
156 @end smallexample | |
157 | |
158 @noindent | |
159 The second and third @code{FOO} should be in comments, but often are not | |
160 in older programs. This warning is on by default. | |
161 | |
162 @item -Werror | |
163 @opindex Werror | |
164 Make all warnings into hard errors. Source code which triggers warnings | |
165 will be rejected. | |
166 | |
167 @item -Wsystem-headers | |
168 @opindex Wsystem-headers | |
169 Issue warnings for code in system headers. These are normally unhelpful | |
170 in finding bugs in your own code, therefore suppressed. If you are | |
171 responsible for the system library, you may want to see them. | |
172 | |
173 @item -w | |
174 @opindex w | |
175 Suppress all warnings, including those which GNU CPP issues by default. | |
176 | |
177 @item -pedantic | |
178 @opindex pedantic | |
179 Issue all the mandatory diagnostics listed in the C standard. Some of | |
180 them are left out by default, since they trigger frequently on harmless | |
181 code. | |
182 | |
183 @item -pedantic-errors | |
184 @opindex pedantic-errors | |
185 Issue all the mandatory diagnostics, and make all mandatory diagnostics | |
186 into errors. This includes mandatory diagnostics that GCC issues | |
187 without @samp{-pedantic} but treats as warnings. | |
188 | 78 |
189 @item -M | 79 @item -M |
190 @opindex M | 80 @opindex M |
191 @cindex @command{make} | 81 @cindex @command{make} |
192 @cindex dependencies, @command{make} | 82 @cindex dependencies, @command{make} |
193 Instead of outputting the result of preprocessing, output a rule | 83 Instead of outputting the result of preprocessing, output a rule |
194 suitable for @command{make} describing the dependencies of the main | 84 suitable for @command{make} describing the dependencies of the main |
195 source file. The preprocessor outputs one @command{make} rule containing | 85 source file. The preprocessor outputs one @command{make} rule containing |
196 the object file name for that source file, a colon, and the names of all | 86 the object file name for that source file, a colon, and the names of all |
197 the included files, including those coming from @option{-include} or | 87 the included files, including those coming from @option{-include} or |
198 @option{-imacros} command line options. | 88 @option{-imacros} command-line options. |
199 | 89 |
200 Unless specified explicitly (with @option{-MT} or @option{-MQ}), the | 90 Unless specified explicitly (with @option{-MT} or @option{-MQ}), the |
201 object file name consists of the name of the source file with any | 91 object file name consists of the name of the source file with any |
202 suffix replaced with object file suffix and with any leading directory | 92 suffix replaced with object file suffix and with any leading directory |
203 parts removed. If there are many included files then the rule is | 93 parts removed. If there are many included files then the rule is |
207 This option does not suppress the preprocessor's debug output, such as | 97 This option does not suppress the preprocessor's debug output, such as |
208 @option{-dM}. To avoid mixing such debug output with the dependency | 98 @option{-dM}. To avoid mixing such debug output with the dependency |
209 rules you should explicitly specify the dependency output file with | 99 rules you should explicitly specify the dependency output file with |
210 @option{-MF}, or use an environment variable like | 100 @option{-MF}, or use an environment variable like |
211 @env{DEPENDENCIES_OUTPUT} (@pxref{Environment Variables}). Debug output | 101 @env{DEPENDENCIES_OUTPUT} (@pxref{Environment Variables}). Debug output |
212 will still be sent to the regular output stream as normal. | 102 is still sent to the regular output stream as normal. |
213 | 103 |
214 Passing @option{-M} to the driver implies @option{-E}, and suppresses | 104 Passing @option{-M} to the driver implies @option{-E}, and suppresses |
215 warnings with an implicit @option{-w}. | 105 warnings with an implicit @option{-w}. |
216 | 106 |
217 @item -MM | 107 @item -MM |
220 system header directories, nor header files that are included, | 110 system header directories, nor header files that are included, |
221 directly or indirectly, from such a header. | 111 directly or indirectly, from such a header. |
222 | 112 |
223 This implies that the choice of angle brackets or double quotes in an | 113 This implies that the choice of angle brackets or double quotes in an |
224 @samp{#include} directive does not in itself determine whether that | 114 @samp{#include} directive does not in itself determine whether that |
225 header will appear in @option{-MM} dependency output. This is a | 115 header appears in @option{-MM} dependency output. |
226 slight change in semantics from GCC versions 3.0 and earlier. | |
227 | 116 |
228 @anchor{dashMF} | 117 @anchor{dashMF} |
229 @item -MF @var{file} | 118 @item -MF @var{file} |
230 @opindex MF | 119 @opindex MF |
231 When used with @option{-M} or @option{-MM}, specifies a | 120 When used with @option{-M} or @option{-MM}, specifies a |
232 file to write the dependencies to. If no @option{-MF} switch is given | 121 file to write the dependencies to. If no @option{-MF} switch is given |
233 the preprocessor sends the rules to the same place it would have sent | 122 the preprocessor sends the rules to the same place it would send |
234 preprocessed output. | 123 preprocessed output. |
235 | 124 |
236 When used with the driver options @option{-MD} or @option{-MMD}, | 125 When used with the driver options @option{-MD} or @option{-MMD}, |
237 @option{-MF} overrides the default dependency output file. | 126 @option{-MF} overrides the default dependency output file. |
127 | |
128 If @var{file} is @file{-}, then the dependencies are written to @file{stdout}. | |
238 | 129 |
239 @item -MG | 130 @item -MG |
240 @opindex MG | 131 @opindex MG |
241 In conjunction with an option such as @option{-M} requesting | 132 In conjunction with an option such as @option{-M} requesting |
242 dependency generation, @option{-MG} assumes missing header files are | 133 dependency generation, @option{-MG} assumes missing header files are |
269 Change the target of the rule emitted by dependency generation. By | 160 Change the target of the rule emitted by dependency generation. By |
270 default CPP takes the name of the main input file, deletes any | 161 default CPP takes the name of the main input file, deletes any |
271 directory components and any file suffix such as @samp{.c}, and | 162 directory components and any file suffix such as @samp{.c}, and |
272 appends the platform's usual object suffix. The result is the target. | 163 appends the platform's usual object suffix. The result is the target. |
273 | 164 |
274 An @option{-MT} option will set the target to be exactly the string you | 165 An @option{-MT} option sets the target to be exactly the string you |
275 specify. If you want multiple targets, you can specify them as a single | 166 specify. If you want multiple targets, you can specify them as a single |
276 argument to @option{-MT}, or use multiple @option{-MT} options. | 167 argument to @option{-MT}, or use multiple @option{-MT} options. |
277 | 168 |
278 For example, @option{@w{-MT '$(objpfx)foo.o'}} might give | 169 For example, @option{@w{-MT '$(objpfx)foo.o'}} might give |
279 | 170 |
313 | 204 |
314 @item -MMD | 205 @item -MMD |
315 @opindex MMD | 206 @opindex MMD |
316 Like @option{-MD} except mention only user header files, not system | 207 Like @option{-MD} except mention only user header files, not system |
317 header files. | 208 header files. |
318 | |
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 | |
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 "@var{filename}"} in the output to mark | |
334 the place where the precompiled header was found, and its @var{filename}. | |
335 When @option{-fpreprocessed} is in use, GCC recognizes this @code{#pragma} | |
336 and loads the PCH@. | |
337 | |
338 This option is off by default, because the resulting preprocessed output | |
339 is only really suitable as input to GCC@. It is switched on by | |
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 | |
347 @end ifclear | |
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 | |
362 @emph{Note:} Previous versions of cpp accepted a @option{-lang} option | |
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= | |
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. | |
373 | |
374 @var{standard} | |
375 may be one of: | |
376 @table @code | |
377 @item c90 | |
378 @itemx c89 | |
379 @itemx iso9899:1990 | |
380 The ISO C standard from 1990. @samp{c90} is the customary shorthand for | |
381 this version of the standard. | |
382 | |
383 The @option{-ansi} option is equivalent to @option{-std=c90}. | |
384 | |
385 @item iso9899:199409 | |
386 The 1990 C standard, as amended in 1994. | |
387 | |
388 @item iso9899:1999 | |
389 @itemx c99 | |
390 @itemx iso9899:199x | |
391 @itemx c9x | |
392 The revised ISO C standard, published in December 1999. Before | |
393 publication, this was known as C9X@. | |
394 | |
395 @item c1x | |
396 The next version of the ISO C standard, still under development. | |
397 | |
398 @item gnu90 | |
399 @itemx gnu89 | |
400 The 1990 C standard plus GNU extensions. This is the default. | |
401 | |
402 @item gnu99 | |
403 @itemx gnu9x | |
404 The 1999 C standard plus GNU extensions. | |
405 | |
406 @item gnu1x | |
407 The next version of the ISO C standard, still under development, plus | |
408 GNU extensions. | |
409 | |
410 @item c++98 | |
411 The 1998 ISO C++ standard plus amendments. | |
412 | |
413 @item gnu++98 | |
414 The same as @option{-std=c++98} plus GNU extensions. This is the | |
415 default for C++ code. | |
416 @end table | |
417 | |
418 @item -I- | |
419 @opindex I- | |
420 Split the include path. Any directories specified with @option{-I} | |
421 options before @option{-I-} are searched only for headers requested with | |
422 @code{@w{#include "@var{file}"}}; they are not searched for | |
423 @code{@w{#include <@var{file}>}}. If additional directories are | |
424 specified with @option{-I} options after the @option{-I-}, those | |
425 directories are searched for all @samp{#include} directives. | |
426 | |
427 In addition, @option{-I-} inhibits the use of the directory of the current | |
428 file directory as the first search directory for @code{@w{#include | |
429 "@var{file}"}}. | |
430 @ifset cppmanual | |
431 @xref{Search Path}. | |
432 @end ifset | |
433 This option has been deprecated. | |
434 | |
435 @item -nostdinc | |
436 @opindex nostdinc | |
437 Do not search the standard system directories for header files. | |
438 Only the directories you have specified with @option{-I} options | |
439 (and the directory of the current file, if appropriate) are searched. | |
440 | |
441 @item -nostdinc++ | |
442 @opindex nostdinc++ | |
443 Do not search for header files in the C++-specific standard directories, | |
444 but do still search the other standard directories. (This option is | |
445 used when building the C++ library.) | |
446 | |
447 @item -include @var{file} | |
448 @opindex include | |
449 Process @var{file} as if @code{#include "file"} appeared as the first | |
450 line of the primary source file. However, the first directory searched | |
451 for @var{file} is the preprocessor's working directory @emph{instead of} | |
452 the directory containing the main source file. If not found there, it | |
453 is searched for in the remainder of the @code{#include "@dots{}"} search | |
454 chain as normal. | |
455 | |
456 If multiple @option{-include} options are given, the files are included | |
457 in the order they appear on the command line. | |
458 | |
459 @item -imacros @var{file} | |
460 @opindex imacros | |
461 Exactly like @option{-include}, except that any output produced by | |
462 scanning @var{file} is thrown away. Macros it defines remain defined. | |
463 This allows you to acquire all the macros from a header without also | |
464 processing its declarations. | |
465 | |
466 All files specified by @option{-imacros} are processed before all files | |
467 specified by @option{-include}. | |
468 | |
469 @item -idirafter @var{dir} | |
470 @opindex idirafter | |
471 Search @var{dir} for header files, but do it @emph{after} all | |
472 directories specified with @option{-I} and the standard system directories | |
473 have been exhausted. @var{dir} is treated as a system include directory. | |
474 If @var{dir} begins with @code{=}, then the @code{=} will be replaced | |
475 by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}. | |
476 | |
477 @item -iprefix @var{prefix} | |
478 @opindex iprefix | |
479 Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix} | |
480 options. If the prefix represents a directory, you should include the | |
481 final @samp{/}. | |
482 | |
483 @item -iwithprefix @var{dir} | |
484 @itemx -iwithprefixbefore @var{dir} | |
485 @opindex iwithprefix | |
486 @opindex iwithprefixbefore | |
487 Append @var{dir} to the prefix specified previously with | |
488 @option{-iprefix}, and add the resulting directory to the include search | |
489 path. @option{-iwithprefixbefore} puts it in the same place @option{-I} | |
490 would; @option{-iwithprefix} puts it where @option{-idirafter} would. | |
491 | |
492 @item -isysroot @var{dir} | |
493 @opindex isysroot | |
494 This option is like the @option{--sysroot} option, but applies only to | |
495 header files (except for Darwin targets, where it applies to both header | |
496 files and libraries). See the @option{--sysroot} option for more | |
497 information. | |
498 | |
499 @item -imultilib @var{dir} | |
500 @opindex imultilib | |
501 Use @var{dir} as a subdirectory of the directory containing | |
502 target-specific C++ headers. | |
503 | |
504 @item -isystem @var{dir} | |
505 @opindex isystem | |
506 Search @var{dir} for header files, after all directories specified by | |
507 @option{-I} but before the standard system directories. Mark it | |
508 as a system directory, so that it gets the same special treatment as | |
509 is applied to the standard system directories. | |
510 @ifset cppmanual | |
511 @xref{System Headers}. | |
512 @end ifset | |
513 If @var{dir} begins with @code{=}, then the @code{=} will be replaced | |
514 by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}. | |
515 | |
516 @item -iquote @var{dir} | |
517 @opindex iquote | |
518 Search @var{dir} only for header files requested with | |
519 @code{@w{#include "@var{file}"}}; they are not searched for | |
520 @code{@w{#include <@var{file}>}}, before all directories specified by | |
521 @option{-I} and before the standard system directories. | |
522 @ifset cppmanual | |
523 @xref{Search Path}. | |
524 @end ifset | |
525 If @var{dir} begins with @code{=}, then the @code{=} will be replaced | |
526 by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}. | |
527 | |
528 @item -fdirectives-only | |
529 @opindex fdirectives-only | |
530 When preprocessing, handle directives, but do not expand macros. | |
531 | |
532 The option's behavior depends on the @option{-E} and @option{-fpreprocessed} | |
533 options. | |
534 | |
535 With @option{-E}, preprocessing is limited to the handling of directives | |
536 such as @code{#define}, @code{#ifdef}, and @code{#error}. Other | |
537 preprocessor operations, such as macro expansion and trigraph | |
538 conversion are not performed. In addition, the @option{-dD} option is | |
539 implicitly enabled. | |
540 | |
541 With @option{-fpreprocessed}, predefinition of command line and most | |
542 builtin macros is disabled. Macros such as @code{__LINE__}, which are | |
543 contextually dependent, are handled normally. This enables compilation of | |
544 files previously preprocessed with @code{-E -fdirectives-only}. | |
545 | |
546 With both @option{-E} and @option{-fpreprocessed}, the rules for | |
547 @option{-fpreprocessed} take precedence. This enables full preprocessing of | |
548 files previously preprocessed with @code{-E -fdirectives-only}. | |
549 | |
550 @item -fdollars-in-identifiers | |
551 @opindex fdollars-in-identifiers | |
552 @anchor{fdollars-in-identifiers} | |
553 Accept @samp{$} in identifiers. | |
554 @ifset cppmanual | |
555 @xref{Identifier characters}. | |
556 @end ifset | |
557 | |
558 @item -fextended-identifiers | |
559 @opindex fextended-identifiers | |
560 Accept universal character names in identifiers. This option is | |
561 experimental; in a future version of GCC, it will be enabled by | |
562 default for C99 and C++. | |
563 | 209 |
564 @item -fpreprocessed | 210 @item -fpreprocessed |
565 @opindex fpreprocessed | 211 @opindex fpreprocessed |
566 Indicate to the preprocessor that the input file has already been | 212 Indicate to the preprocessor that the input file has already been |
567 preprocessed. This suppresses things like macro expansion, trigraph | 213 preprocessed. This suppresses things like macro expansion, trigraph |
574 @option{-fpreprocessed} is implicit if the input file has one of the | 220 @option{-fpreprocessed} is implicit if the input file has one of the |
575 extensions @samp{.i}, @samp{.ii} or @samp{.mi}. These are the | 221 extensions @samp{.i}, @samp{.ii} or @samp{.mi}. These are the |
576 extensions that GCC uses for preprocessed files created by | 222 extensions that GCC uses for preprocessed files created by |
577 @option{-save-temps}. | 223 @option{-save-temps}. |
578 | 224 |
225 @item -fdirectives-only | |
226 @opindex fdirectives-only | |
227 When preprocessing, handle directives, but do not expand macros. | |
228 | |
229 The option's behavior depends on the @option{-E} and @option{-fpreprocessed} | |
230 options. | |
231 | |
232 With @option{-E}, preprocessing is limited to the handling of directives | |
233 such as @code{#define}, @code{#ifdef}, and @code{#error}. Other | |
234 preprocessor operations, such as macro expansion and trigraph | |
235 conversion are not performed. In addition, the @option{-dD} option is | |
236 implicitly enabled. | |
237 | |
238 With @option{-fpreprocessed}, predefinition of command line and most | |
239 builtin macros is disabled. Macros such as @code{__LINE__}, which are | |
240 contextually dependent, are handled normally. This enables compilation of | |
241 files previously preprocessed with @code{-E -fdirectives-only}. | |
242 | |
243 With both @option{-E} and @option{-fpreprocessed}, the rules for | |
244 @option{-fpreprocessed} take precedence. This enables full preprocessing of | |
245 files previously preprocessed with @code{-E -fdirectives-only}. | |
246 | |
247 @item -fdollars-in-identifiers | |
248 @opindex fdollars-in-identifiers | |
249 @anchor{fdollars-in-identifiers} | |
250 Accept @samp{$} in identifiers. | |
251 @ifset cppmanual | |
252 @xref{Identifier characters}. | |
253 @end ifset | |
254 | |
255 @item -fextended-identifiers | |
256 @opindex fextended-identifiers | |
257 Accept universal character names in identifiers. This option is | |
258 enabled by default for C99 (and later C standard versions) and C++. | |
259 | |
260 @item -fno-canonical-system-headers | |
261 @opindex fno-canonical-system-headers | |
262 When preprocessing, do not shorten system header paths with canonicalization. | |
263 | |
579 @item -ftabstop=@var{width} | 264 @item -ftabstop=@var{width} |
580 @opindex ftabstop | 265 @opindex ftabstop |
581 Set the distance between tab stops. This helps the preprocessor report | 266 Set the distance between tab stops. This helps the preprocessor report |
582 correct column numbers in warnings or errors, even if tabs appear on the | 267 correct column numbers in warnings or errors, even if tabs appear on the |
583 line. If the value is less than 1 or greater than 100, the option is | 268 line. If the value is less than 1 or greater than 100, the option is |
584 ignored. The default is 8. | 269 ignored. The default is 8. |
270 | |
271 @item -ftrack-macro-expansion@r{[}=@var{level}@r{]} | |
272 @opindex ftrack-macro-expansion | |
273 Track locations of tokens across macro expansions. This allows the | |
274 compiler to emit diagnostic about the current macro expansion stack | |
275 when a compilation error occurs in a macro expansion. Using this | |
276 option makes the preprocessor and the compiler consume more | |
277 memory. The @var{level} parameter can be used to choose the level of | |
278 precision of token location tracking thus decreasing the memory | |
279 consumption if necessary. Value @samp{0} of @var{level} de-activates | |
280 this option. Value @samp{1} tracks tokens locations in a | |
281 degraded mode for the sake of minimal memory overhead. In this mode | |
282 all tokens resulting from the expansion of an argument of a | |
283 function-like macro have the same location. Value @samp{2} tracks | |
284 tokens locations completely. This value is the most memory hungry. | |
285 When this option is given no argument, the default parameter value is | |
286 @samp{2}. | |
287 | |
288 Note that @code{-ftrack-macro-expansion=2} is activated by default. | |
585 | 289 |
586 @item -fexec-charset=@var{charset} | 290 @item -fexec-charset=@var{charset} |
587 @opindex fexec-charset | 291 @opindex fexec-charset |
588 @cindex character set, execution | 292 @cindex character set, execution |
589 Set the execution character set, used for string and character | 293 Set the execution character set, used for string and character |
605 @cindex character set, input | 309 @cindex character set, input |
606 Set the input character set, used for translation from the character | 310 Set the input character set, used for translation from the character |
607 set of the input file to the source character set used by GCC@. If the | 311 set of the input file to the source character set used by GCC@. If the |
608 locale does not specify, or GCC cannot get this information from the | 312 locale does not specify, or GCC cannot get this information from the |
609 locale, the default is UTF-8. This can be overridden by either the locale | 313 locale, the default is UTF-8. This can be overridden by either the locale |
610 or this command line option. Currently the command line option takes | 314 or this command-line option. Currently the command-line option takes |
611 precedence if there's a conflict. @var{charset} can be any encoding | 315 precedence if there's a conflict. @var{charset} can be any encoding |
612 supported by the system's @code{iconv} library routine. | 316 supported by the system's @code{iconv} library routine. |
317 | |
318 @ifclear cppmanual | |
319 @item -fpch-deps | |
320 @opindex fpch-deps | |
321 When using precompiled headers (@pxref{Precompiled Headers}), this flag | |
322 causes the dependency-output flags to also list the files from the | |
323 precompiled header's dependencies. If not specified, only the | |
324 precompiled header are listed and not the files that were used to | |
325 create it, because those files are not consulted when a precompiled | |
326 header is used. | |
327 | |
328 @item -fpch-preprocess | |
329 @opindex fpch-preprocess | |
330 This option allows use of a precompiled header (@pxref{Precompiled | |
331 Headers}) together with @option{-E}. It inserts a special @code{#pragma}, | |
332 @code{#pragma GCC pch_preprocess "@var{filename}"} in the output to mark | |
333 the place where the precompiled header was found, and its @var{filename}. | |
334 When @option{-fpreprocessed} is in use, GCC recognizes this @code{#pragma} | |
335 and loads the PCH@. | |
336 | |
337 This option is off by default, because the resulting preprocessed output | |
338 is only really suitable as input to GCC@. It is switched on by | |
339 @option{-save-temps}. | |
340 | |
341 You should not write this @code{#pragma} in your own code, but it is | |
342 safe to edit the filename if the PCH file is available in a different | |
343 location. The filename may be absolute or it may be relative to GCC's | |
344 current directory. | |
345 @end ifclear | |
613 | 346 |
614 @item -fworking-directory | 347 @item -fworking-directory |
615 @opindex fworking-directory | 348 @opindex fworking-directory |
616 @opindex fno-working-directory | 349 @opindex fno-working-directory |
617 Enable generation of linemarkers in the preprocessor output that will | 350 Enable generation of linemarkers in the preprocessor output that |
618 let the compiler know the current working directory at the time of | 351 let the compiler know the current working directory at the time of |
619 preprocessing. When this option is enabled, the preprocessor will | 352 preprocessing. When this option is enabled, the preprocessor |
620 emit, after the initial linemarker, a second linemarker with the | 353 emits, after the initial linemarker, a second linemarker with the |
621 current working directory followed by two slashes. GCC will use this | 354 current working directory followed by two slashes. GCC uses this |
622 directory, when it's present in the preprocessed input, as the | 355 directory, when it's present in the preprocessed input, as the |
623 directory emitted as the current working directory in some debugging | 356 directory emitted as the current working directory in some debugging |
624 information formats. This option is implicitly enabled if debugging | 357 information formats. This option is implicitly enabled if debugging |
625 information is enabled, but this can be inhibited with the negated | 358 information is enabled, but this can be inhibited with the negated |
626 form @option{-fno-working-directory}. If the @option{-P} flag is | 359 form @option{-fno-working-directory}. If the @option{-P} flag is |
627 present in the command line, this option has no effect, since no | 360 present in the command line, this option has no effect, since no |
628 @code{#line} directives are emitted whatsoever. | 361 @code{#line} directives are emitted whatsoever. |
629 | |
630 @item -fno-show-column | |
631 @opindex fno-show-column | |
632 Do not print column numbers in diagnostics. This may be necessary if | |
633 diagnostics are being scanned by a program that does not understand the | |
634 column numbers, such as @command{dejagnu}. | |
635 | 362 |
636 @item -A @var{predicate}=@var{answer} | 363 @item -A @var{predicate}=@var{answer} |
637 @opindex A | 364 @opindex A |
638 Make an assertion with the predicate @var{predicate} and answer | 365 Make an assertion with the predicate @var{predicate} and answer |
639 @var{answer}. This form is preferred to the older form @option{-A | 366 @var{answer}. This form is preferred to the older form @option{-A |
645 | 372 |
646 @item -A -@var{predicate}=@var{answer} | 373 @item -A -@var{predicate}=@var{answer} |
647 Cancel an assertion with the predicate @var{predicate} and answer | 374 Cancel an assertion with the predicate @var{predicate} and answer |
648 @var{answer}. | 375 @var{answer}. |
649 | 376 |
650 @item -dCHARS | 377 @item -C |
651 @var{CHARS} is a sequence of one or more of the following characters, | 378 @opindex C |
652 and must not be preceded by a space. Other characters are interpreted | 379 Do not discard comments. All comments are passed through to the output |
653 by the compiler proper, or reserved for future versions of GCC, and so | 380 file, except for comments in processed directives, which are deleted |
654 are silently ignored. If you specify characters whose behavior | 381 along with the directive. |
655 conflicts, the result is undefined. | 382 |
656 | 383 You should be prepared for side effects when using @option{-C}; it |
657 @table @samp | 384 causes the preprocessor to treat comments as tokens in their own right. |
658 @item M | 385 For example, comments appearing at the start of what would be a |
659 @opindex dM | 386 directive line have the effect of turning that line into an ordinary |
660 Instead of the normal output, generate a list of @samp{#define} | 387 source line, since the first token on the line is no longer a @samp{#}. |
661 directives for all the macros defined during the execution of the | 388 |
662 preprocessor, including predefined macros. This gives you a way of | 389 @item -CC |
663 finding out what is predefined in your version of the preprocessor. | 390 @opindex CC |
664 Assuming you have no file @file{foo.h}, the command | 391 Do not discard comments, including during macro expansion. This is |
665 | 392 like @option{-C}, except that comments contained within macros are |
666 @smallexample | 393 also passed through to the output file where the macro is expanded. |
667 touch foo.h; cpp -dM foo.h | 394 |
668 @end smallexample | 395 In addition to the side-effects of the @option{-C} option, the |
669 | 396 @option{-CC} option causes all C++-style comments inside a macro |
670 @noindent | 397 to be converted to C-style comments. This is to prevent later use |
671 will show all the predefined macros. | 398 of that macro from inadvertently commenting out the remainder of |
672 | 399 the source line. |
673 If you use @option{-dM} without the @option{-E} option, @option{-dM} is | 400 |
674 interpreted as a synonym for @option{-fdump-rtl-mach}. | 401 The @option{-CC} option is generally used to support lint comments. |
675 @xref{Debugging Options, , ,gcc}. | |
676 | |
677 @item D | |
678 @opindex dD | |
679 Like @samp{M} except in two respects: it does @emph{not} include the | |
680 predefined macros, and it outputs @emph{both} the @samp{#define} | |
681 directives and the result of preprocessing. Both kinds of output go to | |
682 the standard output file. | |
683 | |
684 @item N | |
685 @opindex dN | |
686 Like @samp{D}, but emit only the macro names, not their expansions. | |
687 | |
688 @item I | |
689 @opindex dI | |
690 Output @samp{#include} directives in addition to the result of | |
691 preprocessing. | |
692 | |
693 @item U | |
694 @opindex dU | |
695 Like @samp{D} except that only macros that are expanded, or whose | |
696 definedness is tested in preprocessor directives, are output; the | |
697 output is delayed until the use or test of the macro; and | |
698 @samp{#undef} directives are also output for macros tested but | |
699 undefined at the time. | |
700 @end table | |
701 | 402 |
702 @item -P | 403 @item -P |
703 @opindex P | 404 @opindex P |
704 Inhibit generation of linemarkers in the output from the preprocessor. | 405 Inhibit generation of linemarkers in the output from the preprocessor. |
705 This might be useful when running the preprocessor on something that is | 406 This might be useful when running the preprocessor on something that is |
707 linemarkers. | 408 linemarkers. |
708 @ifset cppmanual | 409 @ifset cppmanual |
709 @xref{Preprocessor Output}. | 410 @xref{Preprocessor Output}. |
710 @end ifset | 411 @end ifset |
711 | 412 |
712 @item -C | 413 @cindex traditional C language |
713 @opindex C | 414 @cindex C language, traditional |
714 Do not discard comments. All comments are passed through to the output | 415 @item -traditional |
715 file, except for comments in processed directives, which are deleted | 416 @itemx -traditional-cpp |
716 along with the directive. | |
717 | |
718 You should be prepared for side effects when using @option{-C}; it | |
719 causes the preprocessor to treat comments as tokens in their own right. | |
720 For example, comments appearing at the start of what would be a | |
721 directive line have the effect of turning that line into an ordinary | |
722 source line, since the first token on the line is no longer a @samp{#}. | |
723 | |
724 @item -CC | |
725 Do not discard comments, including during macro expansion. This is | |
726 like @option{-C}, except that comments contained within macros are | |
727 also passed through to the output file where the macro is expanded. | |
728 | |
729 In addition to the side-effects of the @option{-C} option, the | |
730 @option{-CC} option causes all C++-style comments inside a macro | |
731 to be converted to C-style comments. This is to prevent later use | |
732 of that macro from inadvertently commenting out the remainder of | |
733 the source line. | |
734 | |
735 The @option{-CC} option is generally used to support lint comments. | |
736 | |
737 @item -traditional-cpp | |
738 @opindex traditional-cpp | 417 @opindex traditional-cpp |
739 Try to imitate the behavior of old-fashioned C preprocessors, as | 418 @opindex traditional |
419 | |
420 Try to imitate the behavior of pre-standard C preprocessors, as | |
740 opposed to ISO C preprocessors. | 421 opposed to ISO C preprocessors. |
741 @ifset cppmanual | 422 @ifset cppmanual |
742 @xref{Traditional Mode}. | 423 @xref{Traditional Mode}. |
743 @end ifset | 424 @end ifset |
425 @ifclear cppmanual | |
426 See the GNU CPP manual for details. | |
427 @end ifclear | |
428 | |
429 Note that GCC does not otherwise attempt to emulate a pre-standard | |
430 C compiler, and these options are only supported with the @option{-E} | |
431 switch, or when invoking CPP explicitly. | |
744 | 432 |
745 @item -trigraphs | 433 @item -trigraphs |
746 @opindex trigraphs | 434 @opindex trigraphs |
747 Process trigraph sequences. | 435 Support ISO C trigraphs. |
436 These are three-character sequences, all starting with @samp{??}, that | |
437 are defined by ISO C to stand for single characters. For example, | |
438 @samp{??/} stands for @samp{\}, so @samp{'??/n'} is a character | |
439 constant for a newline. | |
748 @ifset cppmanual | 440 @ifset cppmanual |
749 @xref{Initial processing}. | 441 @xref{Initial processing}. |
750 @end ifset | 442 @end ifset |
443 | |
751 @ifclear cppmanual | 444 @ifclear cppmanual |
752 These are three-character sequences, all starting with @samp{??}, that | |
753 are defined by ISO C to stand for single characters. For example, | |
754 @samp{??/} stands for @samp{\}, so @samp{'??/n'} is a character | |
755 constant for a newline. By default, GCC ignores trigraphs, but in | |
756 standard-conforming modes it converts them. See the @option{-std} and | |
757 @option{-ansi} options. | |
758 | |
759 The nine trigraphs and their replacements are | 445 The nine trigraphs and their replacements are |
760 | 446 |
761 @smallexample | 447 @smallexample |
762 Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- | 448 Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- |
763 Replacement: [ ] @{ @} # \ ^ | ~ | 449 Replacement: [ ] @{ @} # \ ^ | ~ |
764 @end smallexample | 450 @end smallexample |
765 @end ifclear | 451 @end ifclear |
766 | 452 |
453 By default, GCC ignores trigraphs, but in | |
454 standard-conforming modes it converts them. See the @option{-std} and | |
455 @option{-ansi} options. | |
456 | |
767 @item -remap | 457 @item -remap |
768 @opindex remap | 458 @opindex remap |
769 Enable special code to work around file systems which only permit very | 459 Enable special code to work around file systems which only permit very |
770 short file names, such as MS-DOS@. | 460 short file names, such as MS-DOS@. |
771 | |
772 @itemx --help | |
773 @itemx --target-help | |
774 @opindex help | |
775 @opindex target-help | |
776 Print text describing all the command line options instead of | |
777 preprocessing anything. | |
778 | |
779 @item -v | |
780 @opindex v | |
781 Verbose mode. Print out GNU CPP's version number at the beginning of | |
782 execution, and report the final form of the include path. | |
783 | 461 |
784 @item -H | 462 @item -H |
785 @opindex H | 463 @opindex H |
786 Print the name of each header file used, in addition to other normal | 464 Print the name of each header file used, in addition to other normal |
787 activities. Each name is indented to show how deep in the | 465 activities. Each name is indented to show how deep in the |
788 @samp{#include} stack it is. Precompiled header files are also | 466 @samp{#include} stack it is. Precompiled header files are also |
789 printed, even if they are found to be invalid; an invalid precompiled | 467 printed, even if they are found to be invalid; an invalid precompiled |
790 header file is printed with @samp{...x} and a valid one with @samp{...!} . | 468 header file is printed with @samp{...x} and a valid one with @samp{...!} . |
791 | 469 |
792 @item -version | 470 @item -d@var{letters} |
793 @itemx --version | 471 @opindex d |
794 @opindex version | 472 Says to make debugging dumps during compilation as specified by |
795 Print out GNU CPP's version number. With one dash, proceed to | 473 @var{letters}. The flags documented here are those relevant to the |
796 preprocess as normal. With two dashes, exit immediately. | 474 preprocessor. Other @var{letters} are interpreted |
475 by the compiler proper, or reserved for future versions of GCC, and so | |
476 are silently ignored. If you specify @var{letters} whose behavior | |
477 conflicts, the result is undefined. | |
478 @ifclear cppmanual | |
479 @xref{Developer Options}, for more information. | |
480 @end ifclear | |
481 | |
482 @table @gcctabopt | |
483 @item -dM | |
484 @opindex dM | |
485 Instead of the normal output, generate a list of @samp{#define} | |
486 directives for all the macros defined during the execution of the | |
487 preprocessor, including predefined macros. This gives you a way of | |
488 finding out what is predefined in your version of the preprocessor. | |
489 Assuming you have no file @file{foo.h}, the command | |
490 | |
491 @smallexample | |
492 touch foo.h; cpp -dM foo.h | |
493 @end smallexample | |
494 | |
495 @noindent | |
496 shows all the predefined macros. | |
497 | |
498 @ifclear cppmanual | |
499 If you use @option{-dM} without the @option{-E} option, @option{-dM} is | |
500 interpreted as a synonym for @option{-fdump-rtl-mach}. | |
501 @xref{Developer Options, , ,gcc}. | |
502 @end ifclear | |
503 | |
504 @item -dD | |
505 @opindex dD | |
506 Like @option{-dM} except in two respects: it does @emph{not} include the | |
507 predefined macros, and it outputs @emph{both} the @samp{#define} | |
508 directives and the result of preprocessing. Both kinds of output go to | |
509 the standard output file. | |
510 | |
511 @item -dN | |
512 @opindex dN | |
513 Like @option{-dD}, but emit only the macro names, not their expansions. | |
514 | |
515 @item -dI | |
516 @opindex dI | |
517 Output @samp{#include} directives in addition to the result of | |
518 preprocessing. | |
519 | |
520 @item -dU | |
521 @opindex dU | |
522 Like @option{-dD} except that only macros that are expanded, or whose | |
523 definedness is tested in preprocessor directives, are output; the | |
524 output is delayed until the use or test of the macro; and | |
525 @samp{#undef} directives are also output for macros tested but | |
526 undefined at the time. | |
797 @end table | 527 @end table |
528 | |
529 @item -fdebug-cpp | |
530 @opindex fdebug-cpp | |
531 This option is only useful for debugging GCC. When used from CPP or with | |
532 @option{-E}, it dumps debugging information about location maps. Every | |
533 token in the output is preceded by the dump of the map its location | |
534 belongs to. | |
535 | |
536 When used from GCC without @option{-E}, this option has no effect. | |
537 |