Mercurial > hg > CbC > CbC_gcc
comparison gcc/doc/cpp.1 @ 0:a06113de4d67
first commit
author | kent <kent@cr.ie.u-ryukyu.ac.jp> |
---|---|
date | Fri, 17 Jul 2009 14:47:48 +0900 |
parents | |
children | 58ad6c70ea60 |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:a06113de4d67 |
---|---|
1 .\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.07) | |
2 .\" | |
3 .\" Standard preamble: | |
4 .\" ======================================================================== | |
5 .de Sh \" Subsection heading | |
6 .br | |
7 .if t .Sp | |
8 .ne 5 | |
9 .PP | |
10 \fB\\$1\fR | |
11 .PP | |
12 .. | |
13 .de Sp \" Vertical space (when we can't use .PP) | |
14 .if t .sp .5v | |
15 .if n .sp | |
16 .. | |
17 .de Vb \" Begin verbatim text | |
18 .ft CW | |
19 .nf | |
20 .ne \\$1 | |
21 .. | |
22 .de Ve \" End verbatim text | |
23 .ft R | |
24 .fi | |
25 .. | |
26 .\" Set up some character translations and predefined strings. \*(-- will | |
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 .\" double quote, and \*(R" will give a right double quote. \*(C+ will | |
29 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and | |
30 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, | |
31 .\" nothing in troff, for use with C<>. | |
32 .tr \(*W- | |
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 .ie n \{\ | |
35 . ds -- \(*W- | |
36 . ds PI pi | |
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 . ds L" "" | |
40 . ds R" "" | |
41 . ds C` "" | |
42 . ds C' "" | |
43 'br\} | |
44 .el\{\ | |
45 . ds -- \|\(em\| | |
46 . ds PI \(*p | |
47 . ds L" `` | |
48 . ds R" '' | |
49 'br\} | |
50 .\" | |
51 .\" Escape single quotes in literal strings from groff's Unicode transform. | |
52 .ie \n(.g .ds Aq \(aq | |
53 .el .ds Aq ' | |
54 .\" | |
55 .\" If the F register is turned on, we'll generate index entries on stderr for | |
56 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
57 .\" entries marked with X<> in POD. Of course, you'll have to process the | |
58 .\" output yourself in some meaningful fashion. | |
59 .ie \nF \{\ | |
60 . de IX | |
61 . tm Index:\\$1\t\\n%\t"\\$2" | |
62 .. | |
63 . nr % 0 | |
64 . rr F | |
65 .\} | |
66 .el \{\ | |
67 . de IX | |
68 .. | |
69 .\} | |
70 .\" | |
71 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
72 .\" Fear. Run. Save yourself. No user-serviceable parts. | |
73 . \" fudge factors for nroff and troff | |
74 .if n \{\ | |
75 . ds #H 0 | |
76 . ds #V .8m | |
77 . ds #F .3m | |
78 . ds #[ \f1 | |
79 . ds #] \fP | |
80 .\} | |
81 .if t \{\ | |
82 . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
83 . ds #V .6m | |
84 . ds #F 0 | |
85 . ds #[ \& | |
86 . ds #] \& | |
87 .\} | |
88 . \" simple accents for nroff and troff | |
89 .if n \{\ | |
90 . ds ' \& | |
91 . ds ` \& | |
92 . ds ^ \& | |
93 . ds , \& | |
94 . ds ~ ~ | |
95 . ds / | |
96 .\} | |
97 .if t \{\ | |
98 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
99 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
100 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
101 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
102 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
103 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
104 .\} | |
105 . \" troff and (daisy-wheel) nroff accents | |
106 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
107 .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
108 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
109 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
110 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
111 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
112 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
113 .ds ae a\h'-(\w'a'u*4/10)'e | |
114 .ds Ae A\h'-(\w'A'u*4/10)'E | |
115 . \" corrections for vroff | |
116 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
117 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
118 . \" for low resolution devices (crt and lpr) | |
119 .if \n(.H>23 .if \n(.V>19 \ | |
120 \{\ | |
121 . ds : e | |
122 . ds 8 ss | |
123 . ds o a | |
124 . ds d- d\h'-1'\(ga | |
125 . ds D- D\h'-1'\(hy | |
126 . ds th \o'bp' | |
127 . ds Th \o'LP' | |
128 . ds ae ae | |
129 . ds Ae AE | |
130 .\} | |
131 .rm #[ #] #H #V #F C | |
132 .\" ======================================================================== | |
133 .\" | |
134 .IX Title "CPP 1" | |
135 .TH CPP 1 "2009-04-21" "gcc-4.4.0" "GNU" | |
136 .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
137 .\" way too many mistakes in technical documents. | |
138 .if n .ad l | |
139 .nh | |
140 .SH "NAME" | |
141 cpp \- The C Preprocessor | |
142 .SH "SYNOPSIS" | |
143 .IX Header "SYNOPSIS" | |
144 cpp [\fB\-D\fR\fImacro\fR[=\fIdefn\fR]...] [\fB\-U\fR\fImacro\fR] | |
145 [\fB\-I\fR\fIdir\fR...] [\fB\-iquote\fR\fIdir\fR...] | |
146 [\fB\-W\fR\fIwarn\fR...] | |
147 [\fB\-M\fR|\fB\-MM\fR] [\fB\-MG\fR] [\fB\-MF\fR \fIfilename\fR] | |
148 [\fB\-MP\fR] [\fB\-MQ\fR \fItarget\fR...] | |
149 [\fB\-MT\fR \fItarget\fR...] | |
150 [\fB\-P\fR] [\fB\-fno\-working\-directory\fR] | |
151 [\fB\-x\fR \fIlanguage\fR] [\fB\-std=\fR\fIstandard\fR] | |
152 \fIinfile\fR \fIoutfile\fR | |
153 .PP | |
154 Only the most useful options are listed here; see below for the remainder. | |
155 .SH "DESCRIPTION" | |
156 .IX Header "DESCRIPTION" | |
157 The C preprocessor, often known as \fIcpp\fR, is a \fImacro processor\fR | |
158 that is used automatically by the C compiler to transform your program | |
159 before compilation. It is called a macro processor because it allows | |
160 you to define \fImacros\fR, which are brief abbreviations for longer | |
161 constructs. | |
162 .PP | |
163 The C preprocessor is intended to be used only with C, \*(C+, and | |
164 Objective-C source code. In the past, it has been abused as a general | |
165 text processor. It will choke on input which does not obey C's lexical | |
166 rules. For example, apostrophes will be interpreted as the beginning of | |
167 character constants, and cause errors. Also, you cannot rely on it | |
168 preserving characteristics of the input which are not significant to | |
169 C\-family languages. If a Makefile is preprocessed, all the hard tabs | |
170 will be removed, and the Makefile will not work. | |
171 .PP | |
172 Having said that, you can often get away with using cpp on things which | |
173 are not C. Other Algol-ish programming languages are often safe | |
174 (Pascal, Ada, etc.) So is assembly, with caution. \fB\-traditional\-cpp\fR | |
175 mode preserves more white space, and is otherwise more permissive. Many | |
176 of the problems can be avoided by writing C or \*(C+ style comments | |
177 instead of native language comments, and keeping macros simple. | |
178 .PP | |
179 Wherever possible, you should use a preprocessor geared to the language | |
180 you are writing in. Modern versions of the \s-1GNU\s0 assembler have macro | |
181 facilities. Most high level programming languages have their own | |
182 conditional compilation and inclusion mechanism. If all else fails, | |
183 try a true general text processor, such as \s-1GNU\s0 M4. | |
184 .PP | |
185 C preprocessors vary in some details. This manual discusses the \s-1GNU\s0 C | |
186 preprocessor, which provides a small superset of the features of \s-1ISO\s0 | |
187 Standard C. In its default mode, the \s-1GNU\s0 C preprocessor does not do a | |
188 few things required by the standard. These are features which are | |
189 rarely, if ever, used, and may cause surprising changes to the meaning | |
190 of a program which does not expect them. To get strict \s-1ISO\s0 Standard C, | |
191 you should use the \fB\-std=c89\fR or \fB\-std=c99\fR options, depending | |
192 on which version of the standard you want. To get all the mandatory | |
193 diagnostics, you must also use \fB\-pedantic\fR. | |
194 .PP | |
195 This manual describes the behavior of the \s-1ISO\s0 preprocessor. To | |
196 minimize gratuitous differences, where the \s-1ISO\s0 preprocessor's | |
197 behavior does not conflict with traditional semantics, the | |
198 traditional preprocessor should behave the same way. The various | |
199 differences that do exist are detailed in the section \fBTraditional | |
200 Mode\fR. | |
201 .PP | |
202 For clarity, unless noted otherwise, references to \fB\s-1CPP\s0\fR in this | |
203 manual refer to \s-1GNU\s0 \s-1CPP\s0. | |
204 .SH "OPTIONS" | |
205 .IX Header "OPTIONS" | |
206 The C preprocessor expects two file names as arguments, \fIinfile\fR and | |
207 \&\fIoutfile\fR. The preprocessor reads \fIinfile\fR together with any | |
208 other files it specifies with \fB#include\fR. All the output generated | |
209 by the combined input files is written in \fIoutfile\fR. | |
210 .PP | |
211 Either \fIinfile\fR or \fIoutfile\fR may be \fB\-\fR, which as | |
212 \&\fIinfile\fR means to read from standard input and as \fIoutfile\fR | |
213 means to write to standard output. Also, if either file is omitted, it | |
214 means the same as if \fB\-\fR had been specified for that file. | |
215 .PP | |
216 Unless otherwise noted, or the option ends in \fB=\fR, all options | |
217 which take an argument may have that argument appear either immediately | |
218 after the option, or with a space between option and argument: | |
219 \&\fB\-Ifoo\fR and \fB\-I foo\fR have the same effect. | |
220 .PP | |
221 Many options have multi-letter names; therefore multiple single-letter | |
222 options may \fInot\fR be grouped: \fB\-dM\fR is very different from | |
223 \&\fB\-d\ \-M\fR. | |
224 .IP "\fB\-D\fR \fIname\fR" 4 | |
225 .IX Item "-D name" | |
226 Predefine \fIname\fR as a macro, with definition \f(CW1\fR. | |
227 .IP "\fB\-D\fR \fIname\fR\fB=\fR\fIdefinition\fR" 4 | |
228 .IX Item "-D name=definition" | |
229 The contents of \fIdefinition\fR are tokenized and processed as if | |
230 they appeared during translation phase three in a \fB#define\fR | |
231 directive. In particular, the definition will be truncated by | |
232 embedded newline characters. | |
233 .Sp | |
234 If you are invoking the preprocessor from a shell or shell-like | |
235 program you may need to use the shell's quoting syntax to protect | |
236 characters such as spaces that have a meaning in the shell syntax. | |
237 .Sp | |
238 If you wish to define a function-like macro on the command line, write | |
239 its argument list with surrounding parentheses before the equals sign | |
240 (if any). Parentheses are meaningful to most shells, so you will need | |
241 to quote the option. With \fBsh\fR and \fBcsh\fR, | |
242 \&\fB\-D'\fR\fIname\fR\fB(\fR\fIargs...\fR\fB)=\fR\fIdefinition\fR\fB'\fR works. | |
243 .Sp | |
244 \&\fB\-D\fR and \fB\-U\fR options are processed in the order they | |
245 are given on the command line. All \fB\-imacros\fR \fIfile\fR and | |
246 \&\fB\-include\fR \fIfile\fR options are processed after all | |
247 \&\fB\-D\fR and \fB\-U\fR options. | |
248 .IP "\fB\-U\fR \fIname\fR" 4 | |
249 .IX Item "-U name" | |
250 Cancel any previous definition of \fIname\fR, either built in or | |
251 provided with a \fB\-D\fR option. | |
252 .IP "\fB\-undef\fR" 4 | |
253 .IX Item "-undef" | |
254 Do not predefine any system-specific or GCC-specific macros. The | |
255 standard predefined macros remain defined. | |
256 .IP "\fB\-I\fR \fIdir\fR" 4 | |
257 .IX Item "-I dir" | |
258 Add the directory \fIdir\fR to the list of directories to be searched | |
259 for header files. | |
260 .Sp | |
261 Directories named by \fB\-I\fR are searched before the standard | |
262 system include directories. If the directory \fIdir\fR is a standard | |
263 system include directory, the option is ignored to ensure that the | |
264 default search order for system directories and the special treatment | |
265 of system headers are not defeated | |
266 \&. | |
267 If \fIdir\fR begins with \f(CW\*(C`=\*(C'\fR, then the \f(CW\*(C`=\*(C'\fR will be replaced | |
268 by the sysroot prefix; see \fB\-\-sysroot\fR and \fB\-isysroot\fR. | |
269 .IP "\fB\-o\fR \fIfile\fR" 4 | |
270 .IX Item "-o file" | |
271 Write output to \fIfile\fR. This is the same as specifying \fIfile\fR | |
272 as the second non-option argument to \fBcpp\fR. \fBgcc\fR has a | |
273 different interpretation of a second non-option argument, so you must | |
274 use \fB\-o\fR to specify the output file. | |
275 .IP "\fB\-Wall\fR" 4 | |
276 .IX Item "-Wall" | |
277 Turns on all optional warnings which are desirable for normal code. | |
278 At present this is \fB\-Wcomment\fR, \fB\-Wtrigraphs\fR, | |
279 \&\fB\-Wmultichar\fR and a warning about integer promotion causing a | |
280 change of sign in \f(CW\*(C`#if\*(C'\fR expressions. Note that many of the | |
281 preprocessor's warnings are on by default and have no options to | |
282 control them. | |
283 .IP "\fB\-Wcomment\fR" 4 | |
284 .IX Item "-Wcomment" | |
285 .PD 0 | |
286 .IP "\fB\-Wcomments\fR" 4 | |
287 .IX Item "-Wcomments" | |
288 .PD | |
289 Warn whenever a comment-start sequence \fB/*\fR appears in a \fB/*\fR | |
290 comment, or whenever a backslash-newline appears in a \fB//\fR comment. | |
291 (Both forms have the same effect.) | |
292 .IP "\fB\-Wtrigraphs\fR" 4 | |
293 .IX Item "-Wtrigraphs" | |
294 Most trigraphs in comments cannot affect the meaning of the program. | |
295 However, a trigraph that would form an escaped newline (\fB??/\fR at | |
296 the end of a line) can, by changing where the comment begins or ends. | |
297 Therefore, only trigraphs that would form escaped newlines produce | |
298 warnings inside a comment. | |
299 .Sp | |
300 This option is implied by \fB\-Wall\fR. If \fB\-Wall\fR is not | |
301 given, this option is still enabled unless trigraphs are enabled. To | |
302 get trigraph conversion without warnings, but get the other | |
303 \&\fB\-Wall\fR warnings, use \fB\-trigraphs \-Wall \-Wno\-trigraphs\fR. | |
304 .IP "\fB\-Wtraditional\fR" 4 | |
305 .IX Item "-Wtraditional" | |
306 Warn about certain constructs that behave differently in traditional and | |
307 \&\s-1ISO\s0 C. Also warn about \s-1ISO\s0 C constructs that have no traditional C | |
308 equivalent, and problematic constructs which should be avoided. | |
309 .IP "\fB\-Wundef\fR" 4 | |
310 .IX Item "-Wundef" | |
311 Warn whenever an identifier which is not a macro is encountered in an | |
312 \&\fB#if\fR directive, outside of \fBdefined\fR. Such identifiers are | |
313 replaced with zero. | |
314 .IP "\fB\-Wunused\-macros\fR" 4 | |
315 .IX Item "-Wunused-macros" | |
316 Warn about macros defined in the main file that are unused. A macro | |
317 is \fIused\fR if it is expanded or tested for existence at least once. | |
318 The preprocessor will also warn if the macro has not been used at the | |
319 time it is redefined or undefined. | |
320 .Sp | |
321 Built-in macros, macros defined on the command line, and macros | |
322 defined in include files are not warned about. | |
323 .Sp | |
324 \&\fINote:\fR If a macro is actually used, but only used in skipped | |
325 conditional blocks, then \s-1CPP\s0 will report it as unused. To avoid the | |
326 warning in such a case, you might improve the scope of the macro's | |
327 definition by, for example, moving it into the first skipped block. | |
328 Alternatively, you could provide a dummy use with something like: | |
329 .Sp | |
330 .Vb 2 | |
331 \& #if defined the_macro_causing_the_warning | |
332 \& #endif | |
333 .Ve | |
334 .IP "\fB\-Wendif\-labels\fR" 4 | |
335 .IX Item "-Wendif-labels" | |
336 Warn whenever an \fB#else\fR or an \fB#endif\fR are followed by text. | |
337 This usually happens in code of the form | |
338 .Sp | |
339 .Vb 5 | |
340 \& #if FOO | |
341 \& ... | |
342 \& #else FOO | |
343 \& ... | |
344 \& #endif FOO | |
345 .Ve | |
346 .Sp | |
347 The second and third \f(CW\*(C`FOO\*(C'\fR should be in comments, but often are not | |
348 in older programs. This warning is on by default. | |
349 .IP "\fB\-Werror\fR" 4 | |
350 .IX Item "-Werror" | |
351 Make all warnings into hard errors. Source code which triggers warnings | |
352 will be rejected. | |
353 .IP "\fB\-Wsystem\-headers\fR" 4 | |
354 .IX Item "-Wsystem-headers" | |
355 Issue warnings for code in system headers. These are normally unhelpful | |
356 in finding bugs in your own code, therefore suppressed. If you are | |
357 responsible for the system library, you may want to see them. | |
358 .IP "\fB\-w\fR" 4 | |
359 .IX Item "-w" | |
360 Suppress all warnings, including those which \s-1GNU\s0 \s-1CPP\s0 issues by default. | |
361 .IP "\fB\-pedantic\fR" 4 | |
362 .IX Item "-pedantic" | |
363 Issue all the mandatory diagnostics listed in the C standard. Some of | |
364 them are left out by default, since they trigger frequently on harmless | |
365 code. | |
366 .IP "\fB\-pedantic\-errors\fR" 4 | |
367 .IX Item "-pedantic-errors" | |
368 Issue all the mandatory diagnostics, and make all mandatory diagnostics | |
369 into errors. This includes mandatory diagnostics that \s-1GCC\s0 issues | |
370 without \fB\-pedantic\fR but treats as warnings. | |
371 .IP "\fB\-M\fR" 4 | |
372 .IX Item "-M" | |
373 Instead of outputting the result of preprocessing, output a rule | |
374 suitable for \fBmake\fR describing the dependencies of the main | |
375 source file. The preprocessor outputs one \fBmake\fR rule containing | |
376 the object file name for that source file, a colon, and the names of all | |
377 the included files, including those coming from \fB\-include\fR or | |
378 \&\fB\-imacros\fR command line options. | |
379 .Sp | |
380 Unless specified explicitly (with \fB\-MT\fR or \fB\-MQ\fR), the | |
381 object file name consists of the name of the source file with any | |
382 suffix replaced with object file suffix and with any leading directory | |
383 parts removed. If there are many included files then the rule is | |
384 split into several lines using \fB\e\fR\-newline. The rule has no | |
385 commands. | |
386 .Sp | |
387 This option does not suppress the preprocessor's debug output, such as | |
388 \&\fB\-dM\fR. To avoid mixing such debug output with the dependency | |
389 rules you should explicitly specify the dependency output file with | |
390 \&\fB\-MF\fR, or use an environment variable like | |
391 \&\fB\s-1DEPENDENCIES_OUTPUT\s0\fR. Debug output | |
392 will still be sent to the regular output stream as normal. | |
393 .Sp | |
394 Passing \fB\-M\fR to the driver implies \fB\-E\fR, and suppresses | |
395 warnings with an implicit \fB\-w\fR. | |
396 .IP "\fB\-MM\fR" 4 | |
397 .IX Item "-MM" | |
398 Like \fB\-M\fR but do not mention header files that are found in | |
399 system header directories, nor header files that are included, | |
400 directly or indirectly, from such a header. | |
401 .Sp | |
402 This implies that the choice of angle brackets or double quotes in an | |
403 \&\fB#include\fR directive does not in itself determine whether that | |
404 header will appear in \fB\-MM\fR dependency output. This is a | |
405 slight change in semantics from \s-1GCC\s0 versions 3.0 and earlier. | |
406 .IP "\fB\-MF\fR \fIfile\fR" 4 | |
407 .IX Item "-MF file" | |
408 When used with \fB\-M\fR or \fB\-MM\fR, specifies a | |
409 file to write the dependencies to. If no \fB\-MF\fR switch is given | |
410 the preprocessor sends the rules to the same place it would have sent | |
411 preprocessed output. | |
412 .Sp | |
413 When used with the driver options \fB\-MD\fR or \fB\-MMD\fR, | |
414 \&\fB\-MF\fR overrides the default dependency output file. | |
415 .IP "\fB\-MG\fR" 4 | |
416 .IX Item "-MG" | |
417 In conjunction with an option such as \fB\-M\fR requesting | |
418 dependency generation, \fB\-MG\fR assumes missing header files are | |
419 generated files and adds them to the dependency list without raising | |
420 an error. The dependency filename is taken directly from the | |
421 \&\f(CW\*(C`#include\*(C'\fR directive without prepending any path. \fB\-MG\fR | |
422 also suppresses preprocessed output, as a missing header file renders | |
423 this useless. | |
424 .Sp | |
425 This feature is used in automatic updating of makefiles. | |
426 .IP "\fB\-MP\fR" 4 | |
427 .IX Item "-MP" | |
428 This option instructs \s-1CPP\s0 to add a phony target for each dependency | |
429 other than the main file, causing each to depend on nothing. These | |
430 dummy rules work around errors \fBmake\fR gives if you remove header | |
431 files without updating the \fIMakefile\fR to match. | |
432 .Sp | |
433 This is typical output: | |
434 .Sp | |
435 .Vb 1 | |
436 \& test.o: test.c test.h | |
437 \& | |
438 \& test.h: | |
439 .Ve | |
440 .IP "\fB\-MT\fR \fItarget\fR" 4 | |
441 .IX Item "-MT target" | |
442 Change the target of the rule emitted by dependency generation. By | |
443 default \s-1CPP\s0 takes the name of the main input file, deletes any | |
444 directory components and any file suffix such as \fB.c\fR, and | |
445 appends the platform's usual object suffix. The result is the target. | |
446 .Sp | |
447 An \fB\-MT\fR option will set the target to be exactly the string you | |
448 specify. If you want multiple targets, you can specify them as a single | |
449 argument to \fB\-MT\fR, or use multiple \fB\-MT\fR options. | |
450 .Sp | |
451 For example, \fB\-MT\ '$(objpfx)foo.o'\fR might give | |
452 .Sp | |
453 .Vb 1 | |
454 \& $(objpfx)foo.o: foo.c | |
455 .Ve | |
456 .IP "\fB\-MQ\fR \fItarget\fR" 4 | |
457 .IX Item "-MQ target" | |
458 Same as \fB\-MT\fR, but it quotes any characters which are special to | |
459 Make. \fB\-MQ\ '$(objpfx)foo.o'\fR gives | |
460 .Sp | |
461 .Vb 1 | |
462 \& $$(objpfx)foo.o: foo.c | |
463 .Ve | |
464 .Sp | |
465 The default target is automatically quoted, as if it were given with | |
466 \&\fB\-MQ\fR. | |
467 .IP "\fB\-MD\fR" 4 | |
468 .IX Item "-MD" | |
469 \&\fB\-MD\fR is equivalent to \fB\-M \-MF\fR \fIfile\fR, except that | |
470 \&\fB\-E\fR is not implied. The driver determines \fIfile\fR based on | |
471 whether an \fB\-o\fR option is given. If it is, the driver uses its | |
472 argument but with a suffix of \fI.d\fR, otherwise it takes the name | |
473 of the input file, removes any directory components and suffix, and | |
474 applies a \fI.d\fR suffix. | |
475 .Sp | |
476 If \fB\-MD\fR is used in conjunction with \fB\-E\fR, any | |
477 \&\fB\-o\fR switch is understood to specify the dependency output file, but if used without \fB\-E\fR, each \fB\-o\fR | |
478 is understood to specify a target object file. | |
479 .Sp | |
480 Since \fB\-E\fR is not implied, \fB\-MD\fR can be used to generate | |
481 a dependency output file as a side-effect of the compilation process. | |
482 .IP "\fB\-MMD\fR" 4 | |
483 .IX Item "-MMD" | |
484 Like \fB\-MD\fR except mention only user header files, not system | |
485 header files. | |
486 .IP "\fB\-x c\fR" 4 | |
487 .IX Item "-x c" | |
488 .PD 0 | |
489 .IP "\fB\-x c++\fR" 4 | |
490 .IX Item "-x c++" | |
491 .IP "\fB\-x objective-c\fR" 4 | |
492 .IX Item "-x objective-c" | |
493 .IP "\fB\-x assembler-with-cpp\fR" 4 | |
494 .IX Item "-x assembler-with-cpp" | |
495 .PD | |
496 Specify the source language: C, \*(C+, Objective-C, or assembly. This has | |
497 nothing to do with standards conformance or extensions; it merely | |
498 selects which base syntax to expect. If you give none of these options, | |
499 cpp will deduce the language from the extension of the source file: | |
500 \&\fB.c\fR, \fB.cc\fR, \fB.m\fR, or \fB.S\fR. Some other common | |
501 extensions for \*(C+ and assembly are also recognized. If cpp does not | |
502 recognize the extension, it will treat the file as C; this is the most | |
503 generic mode. | |
504 .Sp | |
505 \&\fINote:\fR Previous versions of cpp accepted a \fB\-lang\fR option | |
506 which selected both the language and the standards conformance level. | |
507 This option has been removed, because it conflicts with the \fB\-l\fR | |
508 option. | |
509 .IP "\fB\-std=\fR\fIstandard\fR" 4 | |
510 .IX Item "-std=standard" | |
511 .PD 0 | |
512 .IP "\fB\-ansi\fR" 4 | |
513 .IX Item "-ansi" | |
514 .PD | |
515 Specify the standard to which the code should conform. Currently \s-1CPP\s0 | |
516 knows about C and \*(C+ standards; others may be added in the future. | |
517 .Sp | |
518 \&\fIstandard\fR | |
519 may be one of: | |
520 .RS 4 | |
521 .ie n .IP """iso9899:1990""" 4 | |
522 .el .IP "\f(CWiso9899:1990\fR" 4 | |
523 .IX Item "iso9899:1990" | |
524 .PD 0 | |
525 .ie n .IP """c89""" 4 | |
526 .el .IP "\f(CWc89\fR" 4 | |
527 .IX Item "c89" | |
528 .PD | |
529 The \s-1ISO\s0 C standard from 1990. \fBc89\fR is the customary shorthand for | |
530 this version of the standard. | |
531 .Sp | |
532 The \fB\-ansi\fR option is equivalent to \fB\-std=c89\fR. | |
533 .ie n .IP """iso9899:199409""" 4 | |
534 .el .IP "\f(CWiso9899:199409\fR" 4 | |
535 .IX Item "iso9899:199409" | |
536 The 1990 C standard, as amended in 1994. | |
537 .ie n .IP """iso9899:1999""" 4 | |
538 .el .IP "\f(CWiso9899:1999\fR" 4 | |
539 .IX Item "iso9899:1999" | |
540 .PD 0 | |
541 .ie n .IP """c99""" 4 | |
542 .el .IP "\f(CWc99\fR" 4 | |
543 .IX Item "c99" | |
544 .ie n .IP """iso9899:199x""" 4 | |
545 .el .IP "\f(CWiso9899:199x\fR" 4 | |
546 .IX Item "iso9899:199x" | |
547 .ie n .IP """c9x""" 4 | |
548 .el .IP "\f(CWc9x\fR" 4 | |
549 .IX Item "c9x" | |
550 .PD | |
551 The revised \s-1ISO\s0 C standard, published in December 1999. Before | |
552 publication, this was known as C9X. | |
553 .ie n .IP """gnu89""" 4 | |
554 .el .IP "\f(CWgnu89\fR" 4 | |
555 .IX Item "gnu89" | |
556 The 1990 C standard plus \s-1GNU\s0 extensions. This is the default. | |
557 .ie n .IP """gnu99""" 4 | |
558 .el .IP "\f(CWgnu99\fR" 4 | |
559 .IX Item "gnu99" | |
560 .PD 0 | |
561 .ie n .IP """gnu9x""" 4 | |
562 .el .IP "\f(CWgnu9x\fR" 4 | |
563 .IX Item "gnu9x" | |
564 .PD | |
565 The 1999 C standard plus \s-1GNU\s0 extensions. | |
566 .ie n .IP """c++98""" 4 | |
567 .el .IP "\f(CWc++98\fR" 4 | |
568 .IX Item "c++98" | |
569 The 1998 \s-1ISO\s0 \*(C+ standard plus amendments. | |
570 .ie n .IP """gnu++98""" 4 | |
571 .el .IP "\f(CWgnu++98\fR" 4 | |
572 .IX Item "gnu++98" | |
573 The same as \fB\-std=c++98\fR plus \s-1GNU\s0 extensions. This is the | |
574 default for \*(C+ code. | |
575 .RE | |
576 .RS 4 | |
577 .RE | |
578 .IP "\fB\-I\-\fR" 4 | |
579 .IX Item "-I-" | |
580 Split the include path. Any directories specified with \fB\-I\fR | |
581 options before \fB\-I\-\fR are searched only for headers requested with | |
582 \&\f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR; they are not searched for | |
583 \&\f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\fR. If additional directories are | |
584 specified with \fB\-I\fR options after the \fB\-I\-\fR, those | |
585 directories are searched for all \fB#include\fR directives. | |
586 .Sp | |
587 In addition, \fB\-I\-\fR inhibits the use of the directory of the current | |
588 file directory as the first search directory for \f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR. | |
589 .Sp | |
590 This option has been deprecated. | |
591 .IP "\fB\-nostdinc\fR" 4 | |
592 .IX Item "-nostdinc" | |
593 Do not search the standard system directories for header files. | |
594 Only the directories you have specified with \fB\-I\fR options | |
595 (and the directory of the current file, if appropriate) are searched. | |
596 .IP "\fB\-nostdinc++\fR" 4 | |
597 .IX Item "-nostdinc++" | |
598 Do not search for header files in the \*(C+\-specific standard directories, | |
599 but do still search the other standard directories. (This option is | |
600 used when building the \*(C+ library.) | |
601 .IP "\fB\-include\fR \fIfile\fR" 4 | |
602 .IX Item "-include file" | |
603 Process \fIfile\fR as if \f(CW\*(C`#include "file"\*(C'\fR appeared as the first | |
604 line of the primary source file. However, the first directory searched | |
605 for \fIfile\fR is the preprocessor's working directory \fIinstead of\fR | |
606 the directory containing the main source file. If not found there, it | |
607 is searched for in the remainder of the \f(CW\*(C`#include "..."\*(C'\fR search | |
608 chain as normal. | |
609 .Sp | |
610 If multiple \fB\-include\fR options are given, the files are included | |
611 in the order they appear on the command line. | |
612 .IP "\fB\-imacros\fR \fIfile\fR" 4 | |
613 .IX Item "-imacros file" | |
614 Exactly like \fB\-include\fR, except that any output produced by | |
615 scanning \fIfile\fR is thrown away. Macros it defines remain defined. | |
616 This allows you to acquire all the macros from a header without also | |
617 processing its declarations. | |
618 .Sp | |
619 All files specified by \fB\-imacros\fR are processed before all files | |
620 specified by \fB\-include\fR. | |
621 .IP "\fB\-idirafter\fR \fIdir\fR" 4 | |
622 .IX Item "-idirafter dir" | |
623 Search \fIdir\fR for header files, but do it \fIafter\fR all | |
624 directories specified with \fB\-I\fR and the standard system directories | |
625 have been exhausted. \fIdir\fR is treated as a system include directory. | |
626 If \fIdir\fR begins with \f(CW\*(C`=\*(C'\fR, then the \f(CW\*(C`=\*(C'\fR will be replaced | |
627 by the sysroot prefix; see \fB\-\-sysroot\fR and \fB\-isysroot\fR. | |
628 .IP "\fB\-iprefix\fR \fIprefix\fR" 4 | |
629 .IX Item "-iprefix prefix" | |
630 Specify \fIprefix\fR as the prefix for subsequent \fB\-iwithprefix\fR | |
631 options. If the prefix represents a directory, you should include the | |
632 final \fB/\fR. | |
633 .IP "\fB\-iwithprefix\fR \fIdir\fR" 4 | |
634 .IX Item "-iwithprefix dir" | |
635 .PD 0 | |
636 .IP "\fB\-iwithprefixbefore\fR \fIdir\fR" 4 | |
637 .IX Item "-iwithprefixbefore dir" | |
638 .PD | |
639 Append \fIdir\fR to the prefix specified previously with | |
640 \&\fB\-iprefix\fR, and add the resulting directory to the include search | |
641 path. \fB\-iwithprefixbefore\fR puts it in the same place \fB\-I\fR | |
642 would; \fB\-iwithprefix\fR puts it where \fB\-idirafter\fR would. | |
643 .IP "\fB\-isysroot\fR \fIdir\fR" 4 | |
644 .IX Item "-isysroot dir" | |
645 This option is like the \fB\-\-sysroot\fR option, but applies only to | |
646 header files. See the \fB\-\-sysroot\fR option for more information. | |
647 .IP "\fB\-imultilib\fR \fIdir\fR" 4 | |
648 .IX Item "-imultilib dir" | |
649 Use \fIdir\fR as a subdirectory of the directory containing | |
650 target-specific \*(C+ headers. | |
651 .IP "\fB\-isystem\fR \fIdir\fR" 4 | |
652 .IX Item "-isystem dir" | |
653 Search \fIdir\fR for header files, after all directories specified by | |
654 \&\fB\-I\fR but before the standard system directories. Mark it | |
655 as a system directory, so that it gets the same special treatment as | |
656 is applied to the standard system directories. | |
657 .Sp | |
658 If \fIdir\fR begins with \f(CW\*(C`=\*(C'\fR, then the \f(CW\*(C`=\*(C'\fR will be replaced | |
659 by the sysroot prefix; see \fB\-\-sysroot\fR and \fB\-isysroot\fR. | |
660 .IP "\fB\-iquote\fR \fIdir\fR" 4 | |
661 .IX Item "-iquote dir" | |
662 Search \fIdir\fR only for header files requested with | |
663 \&\f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR; they are not searched for | |
664 \&\f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\fR, before all directories specified by | |
665 \&\fB\-I\fR and before the standard system directories. | |
666 .Sp | |
667 If \fIdir\fR begins with \f(CW\*(C`=\*(C'\fR, then the \f(CW\*(C`=\*(C'\fR will be replaced | |
668 by the sysroot prefix; see \fB\-\-sysroot\fR and \fB\-isysroot\fR. | |
669 .IP "\fB\-fdirectives\-only\fR" 4 | |
670 .IX Item "-fdirectives-only" | |
671 When preprocessing, handle directives, but do not expand macros. | |
672 .Sp | |
673 The option's behavior depends on the \fB\-E\fR and \fB\-fpreprocessed\fR | |
674 options. | |
675 .Sp | |
676 With \fB\-E\fR, preprocessing is limited to the handling of directives | |
677 such as \f(CW\*(C`#define\*(C'\fR, \f(CW\*(C`#ifdef\*(C'\fR, and \f(CW\*(C`#error\*(C'\fR. Other | |
678 preprocessor operations, such as macro expansion and trigraph | |
679 conversion are not performed. In addition, the \fB\-dD\fR option is | |
680 implicitly enabled. | |
681 .Sp | |
682 With \fB\-fpreprocessed\fR, predefinition of command line and most | |
683 builtin macros is disabled. Macros such as \f(CW\*(C`_\|_LINE_\|_\*(C'\fR, which are | |
684 contextually dependent, are handled normally. This enables compilation of | |
685 files previously preprocessed with \f(CW\*(C`\-E \-fdirectives\-only\*(C'\fR. | |
686 .Sp | |
687 With both \fB\-E\fR and \fB\-fpreprocessed\fR, the rules for | |
688 \&\fB\-fpreprocessed\fR take precedence. This enables full preprocessing of | |
689 files previously preprocessed with \f(CW\*(C`\-E \-fdirectives\-only\*(C'\fR. | |
690 .IP "\fB\-fdollars\-in\-identifiers\fR" 4 | |
691 .IX Item "-fdollars-in-identifiers" | |
692 Accept \fB$\fR in identifiers. | |
693 .IP "\fB\-fextended\-identifiers\fR" 4 | |
694 .IX Item "-fextended-identifiers" | |
695 Accept universal character names in identifiers. This option is | |
696 experimental; in a future version of \s-1GCC\s0, it will be enabled by | |
697 default for C99 and \*(C+. | |
698 .IP "\fB\-fpreprocessed\fR" 4 | |
699 .IX Item "-fpreprocessed" | |
700 Indicate to the preprocessor that the input file has already been | |
701 preprocessed. This suppresses things like macro expansion, trigraph | |
702 conversion, escaped newline splicing, and processing of most directives. | |
703 The preprocessor still recognizes and removes comments, so that you can | |
704 pass a file preprocessed with \fB\-C\fR to the compiler without | |
705 problems. In this mode the integrated preprocessor is little more than | |
706 a tokenizer for the front ends. | |
707 .Sp | |
708 \&\fB\-fpreprocessed\fR is implicit if the input file has one of the | |
709 extensions \fB.i\fR, \fB.ii\fR or \fB.mi\fR. These are the | |
710 extensions that \s-1GCC\s0 uses for preprocessed files created by | |
711 \&\fB\-save\-temps\fR. | |
712 .IP "\fB\-ftabstop=\fR\fIwidth\fR" 4 | |
713 .IX Item "-ftabstop=width" | |
714 Set the distance between tab stops. This helps the preprocessor report | |
715 correct column numbers in warnings or errors, even if tabs appear on the | |
716 line. If the value is less than 1 or greater than 100, the option is | |
717 ignored. The default is 8. | |
718 .IP "\fB\-fexec\-charset=\fR\fIcharset\fR" 4 | |
719 .IX Item "-fexec-charset=charset" | |
720 Set the execution character set, used for string and character | |
721 constants. The default is \s-1UTF\-8\s0. \fIcharset\fR can be any encoding | |
722 supported by the system's \f(CW\*(C`iconv\*(C'\fR library routine. | |
723 .IP "\fB\-fwide\-exec\-charset=\fR\fIcharset\fR" 4 | |
724 .IX Item "-fwide-exec-charset=charset" | |
725 Set the wide execution character set, used for wide string and | |
726 character constants. The default is \s-1UTF\-32\s0 or \s-1UTF\-16\s0, whichever | |
727 corresponds to the width of \f(CW\*(C`wchar_t\*(C'\fR. As with | |
728 \&\fB\-fexec\-charset\fR, \fIcharset\fR can be any encoding supported | |
729 by the system's \f(CW\*(C`iconv\*(C'\fR library routine; however, you will have | |
730 problems with encodings that do not fit exactly in \f(CW\*(C`wchar_t\*(C'\fR. | |
731 .IP "\fB\-finput\-charset=\fR\fIcharset\fR" 4 | |
732 .IX Item "-finput-charset=charset" | |
733 Set the input character set, used for translation from the character | |
734 set of the input file to the source character set used by \s-1GCC\s0. If the | |
735 locale does not specify, or \s-1GCC\s0 cannot get this information from the | |
736 locale, the default is \s-1UTF\-8\s0. This can be overridden by either the locale | |
737 or this command line option. Currently the command line option takes | |
738 precedence if there's a conflict. \fIcharset\fR can be any encoding | |
739 supported by the system's \f(CW\*(C`iconv\*(C'\fR library routine. | |
740 .IP "\fB\-fworking\-directory\fR" 4 | |
741 .IX Item "-fworking-directory" | |
742 Enable generation of linemarkers in the preprocessor output that will | |
743 let the compiler know the current working directory at the time of | |
744 preprocessing. When this option is enabled, the preprocessor will | |
745 emit, after the initial linemarker, a second linemarker with the | |
746 current working directory followed by two slashes. \s-1GCC\s0 will use this | |
747 directory, when it's present in the preprocessed input, as the | |
748 directory emitted as the current working directory in some debugging | |
749 information formats. This option is implicitly enabled if debugging | |
750 information is enabled, but this can be inhibited with the negated | |
751 form \fB\-fno\-working\-directory\fR. If the \fB\-P\fR flag is | |
752 present in the command line, this option has no effect, since no | |
753 \&\f(CW\*(C`#line\*(C'\fR directives are emitted whatsoever. | |
754 .IP "\fB\-fno\-show\-column\fR" 4 | |
755 .IX Item "-fno-show-column" | |
756 Do not print column numbers in diagnostics. This may be necessary if | |
757 diagnostics are being scanned by a program that does not understand the | |
758 column numbers, such as \fBdejagnu\fR. | |
759 .IP "\fB\-A\fR \fIpredicate\fR\fB=\fR\fIanswer\fR" 4 | |
760 .IX Item "-A predicate=answer" | |
761 Make an assertion with the predicate \fIpredicate\fR and answer | |
762 \&\fIanswer\fR. This form is preferred to the older form \fB\-A\fR | |
763 \&\fIpredicate\fR\fB(\fR\fIanswer\fR\fB)\fR, which is still supported, because | |
764 it does not use shell special characters. | |
765 .IP "\fB\-A \-\fR\fIpredicate\fR\fB=\fR\fIanswer\fR" 4 | |
766 .IX Item "-A -predicate=answer" | |
767 Cancel an assertion with the predicate \fIpredicate\fR and answer | |
768 \&\fIanswer\fR. | |
769 .IP "\fB\-dCHARS\fR" 4 | |
770 .IX Item "-dCHARS" | |
771 \&\fI\s-1CHARS\s0\fR is a sequence of one or more of the following characters, | |
772 and must not be preceded by a space. Other characters are interpreted | |
773 by the compiler proper, or reserved for future versions of \s-1GCC\s0, and so | |
774 are silently ignored. If you specify characters whose behavior | |
775 conflicts, the result is undefined. | |
776 .RS 4 | |
777 .IP "\fBM\fR" 4 | |
778 .IX Item "M" | |
779 Instead of the normal output, generate a list of \fB#define\fR | |
780 directives for all the macros defined during the execution of the | |
781 preprocessor, including predefined macros. This gives you a way of | |
782 finding out what is predefined in your version of the preprocessor. | |
783 Assuming you have no file \fIfoo.h\fR, the command | |
784 .Sp | |
785 .Vb 1 | |
786 \& touch foo.h; cpp \-dM foo.h | |
787 .Ve | |
788 .Sp | |
789 will show all the predefined macros. | |
790 .Sp | |
791 If you use \fB\-dM\fR without the \fB\-E\fR option, \fB\-dM\fR is | |
792 interpreted as a synonym for \fB\-fdump\-rtl\-mach\fR. | |
793 .IP "\fBD\fR" 4 | |
794 .IX Item "D" | |
795 Like \fBM\fR except in two respects: it does \fInot\fR include the | |
796 predefined macros, and it outputs \fIboth\fR the \fB#define\fR | |
797 directives and the result of preprocessing. Both kinds of output go to | |
798 the standard output file. | |
799 .IP "\fBN\fR" 4 | |
800 .IX Item "N" | |
801 Like \fBD\fR, but emit only the macro names, not their expansions. | |
802 .IP "\fBI\fR" 4 | |
803 .IX Item "I" | |
804 Output \fB#include\fR directives in addition to the result of | |
805 preprocessing. | |
806 .IP "\fBU\fR" 4 | |
807 .IX Item "U" | |
808 Like \fBD\fR except that only macros that are expanded, or whose | |
809 definedness is tested in preprocessor directives, are output; the | |
810 output is delayed until the use or test of the macro; and | |
811 \&\fB#undef\fR directives are also output for macros tested but | |
812 undefined at the time. | |
813 .RE | |
814 .RS 4 | |
815 .RE | |
816 .IP "\fB\-P\fR" 4 | |
817 .IX Item "-P" | |
818 Inhibit generation of linemarkers in the output from the preprocessor. | |
819 This might be useful when running the preprocessor on something that is | |
820 not C code, and will be sent to a program which might be confused by the | |
821 linemarkers. | |
822 .IP "\fB\-C\fR" 4 | |
823 .IX Item "-C" | |
824 Do not discard comments. All comments are passed through to the output | |
825 file, except for comments in processed directives, which are deleted | |
826 along with the directive. | |
827 .Sp | |
828 You should be prepared for side effects when using \fB\-C\fR; it | |
829 causes the preprocessor to treat comments as tokens in their own right. | |
830 For example, comments appearing at the start of what would be a | |
831 directive line have the effect of turning that line into an ordinary | |
832 source line, since the first token on the line is no longer a \fB#\fR. | |
833 .IP "\fB\-CC\fR" 4 | |
834 .IX Item "-CC" | |
835 Do not discard comments, including during macro expansion. This is | |
836 like \fB\-C\fR, except that comments contained within macros are | |
837 also passed through to the output file where the macro is expanded. | |
838 .Sp | |
839 In addition to the side-effects of the \fB\-C\fR option, the | |
840 \&\fB\-CC\fR option causes all \*(C+\-style comments inside a macro | |
841 to be converted to C\-style comments. This is to prevent later use | |
842 of that macro from inadvertently commenting out the remainder of | |
843 the source line. | |
844 .Sp | |
845 The \fB\-CC\fR option is generally used to support lint comments. | |
846 .IP "\fB\-traditional\-cpp\fR" 4 | |
847 .IX Item "-traditional-cpp" | |
848 Try to imitate the behavior of old-fashioned C preprocessors, as | |
849 opposed to \s-1ISO\s0 C preprocessors. | |
850 .IP "\fB\-trigraphs\fR" 4 | |
851 .IX Item "-trigraphs" | |
852 Process trigraph sequences. | |
853 .IP "\fB\-remap\fR" 4 | |
854 .IX Item "-remap" | |
855 Enable special code to work around file systems which only permit very | |
856 short file names, such as MS-DOS. | |
857 .IP "\fB\-\-help\fR" 4 | |
858 .IX Item "--help" | |
859 .PD 0 | |
860 .IP "\fB\-\-target\-help\fR" 4 | |
861 .IX Item "--target-help" | |
862 .PD | |
863 Print text describing all the command line options instead of | |
864 preprocessing anything. | |
865 .IP "\fB\-v\fR" 4 | |
866 .IX Item "-v" | |
867 Verbose mode. Print out \s-1GNU\s0 \s-1CPP\s0's version number at the beginning of | |
868 execution, and report the final form of the include path. | |
869 .IP "\fB\-H\fR" 4 | |
870 .IX Item "-H" | |
871 Print the name of each header file used, in addition to other normal | |
872 activities. Each name is indented to show how deep in the | |
873 \&\fB#include\fR stack it is. Precompiled header files are also | |
874 printed, even if they are found to be invalid; an invalid precompiled | |
875 header file is printed with \fB...x\fR and a valid one with \fB...!\fR . | |
876 .IP "\fB\-version\fR" 4 | |
877 .IX Item "-version" | |
878 .PD 0 | |
879 .IP "\fB\-\-version\fR" 4 | |
880 .IX Item "--version" | |
881 .PD | |
882 Print out \s-1GNU\s0 \s-1CPP\s0's version number. With one dash, proceed to | |
883 preprocess as normal. With two dashes, exit immediately. | |
884 .SH "ENVIRONMENT" | |
885 .IX Header "ENVIRONMENT" | |
886 This section describes the environment variables that affect how \s-1CPP\s0 | |
887 operates. You can use them to specify directories or prefixes to use | |
888 when searching for include files, or to control dependency output. | |
889 .PP | |
890 Note that you can also specify places to search using options such as | |
891 \&\fB\-I\fR, and control dependency output with options like | |
892 \&\fB\-M\fR. These take precedence over | |
893 environment variables, which in turn take precedence over the | |
894 configuration of \s-1GCC\s0. | |
895 .IP "\fB\s-1CPATH\s0\fR" 4 | |
896 .IX Item "CPATH" | |
897 .PD 0 | |
898 .IP "\fBC_INCLUDE_PATH\fR" 4 | |
899 .IX Item "C_INCLUDE_PATH" | |
900 .IP "\fB\s-1CPLUS_INCLUDE_PATH\s0\fR" 4 | |
901 .IX Item "CPLUS_INCLUDE_PATH" | |
902 .IP "\fB\s-1OBJC_INCLUDE_PATH\s0\fR" 4 | |
903 .IX Item "OBJC_INCLUDE_PATH" | |
904 .PD | |
905 Each variable's value is a list of directories separated by a special | |
906 character, much like \fB\s-1PATH\s0\fR, in which to look for header files. | |
907 The special character, \f(CW\*(C`PATH_SEPARATOR\*(C'\fR, is target-dependent and | |
908 determined at \s-1GCC\s0 build time. For Microsoft Windows-based targets it is a | |
909 semicolon, and for almost all other targets it is a colon. | |
910 .Sp | |
911 \&\fB\s-1CPATH\s0\fR specifies a list of directories to be searched as if | |
912 specified with \fB\-I\fR, but after any paths given with \fB\-I\fR | |
913 options on the command line. This environment variable is used | |
914 regardless of which language is being preprocessed. | |
915 .Sp | |
916 The remaining environment variables apply only when preprocessing the | |
917 particular language indicated. Each specifies a list of directories | |
918 to be searched as if specified with \fB\-isystem\fR, but after any | |
919 paths given with \fB\-isystem\fR options on the command line. | |
920 .Sp | |
921 In all these variables, an empty element instructs the compiler to | |
922 search its current working directory. Empty elements can appear at the | |
923 beginning or end of a path. For instance, if the value of | |
924 \&\fB\s-1CPATH\s0\fR is \f(CW\*(C`:/special/include\*(C'\fR, that has the same | |
925 effect as \fB\-I.\ \-I/special/include\fR. | |
926 .IP "\fB\s-1DEPENDENCIES_OUTPUT\s0\fR" 4 | |
927 .IX Item "DEPENDENCIES_OUTPUT" | |
928 If this variable is set, its value specifies how to output | |
929 dependencies for Make based on the non-system header files processed | |
930 by the compiler. System header files are ignored in the dependency | |
931 output. | |
932 .Sp | |
933 The value of \fB\s-1DEPENDENCIES_OUTPUT\s0\fR can be just a file name, in | |
934 which case the Make rules are written to that file, guessing the target | |
935 name from the source file name. Or the value can have the form | |
936 \&\fIfile\fR\fB \fR\fItarget\fR, in which case the rules are written to | |
937 file \fIfile\fR using \fItarget\fR as the target name. | |
938 .Sp | |
939 In other words, this environment variable is equivalent to combining | |
940 the options \fB\-MM\fR and \fB\-MF\fR, | |
941 with an optional \fB\-MT\fR switch too. | |
942 .IP "\fB\s-1SUNPRO_DEPENDENCIES\s0\fR" 4 | |
943 .IX Item "SUNPRO_DEPENDENCIES" | |
944 This variable is the same as \fB\s-1DEPENDENCIES_OUTPUT\s0\fR (see above), | |
945 except that system header files are not ignored, so it implies | |
946 \&\fB\-M\fR rather than \fB\-MM\fR. However, the dependence on the | |
947 main input file is omitted. | |
948 .SH "SEE ALSO" | |
949 .IX Header "SEE ALSO" | |
950 \&\fIgpl\fR\|(7), \fIgfdl\fR\|(7), \fIfsf\-funding\fR\|(7), | |
951 \&\fIgcc\fR\|(1), \fIas\fR\|(1), \fIld\fR\|(1), and the Info entries for \fIcpp\fR, \fIgcc\fR, and | |
952 \&\fIbinutils\fR. | |
953 .SH "COPYRIGHT" | |
954 .IX Header "COPYRIGHT" | |
955 Copyright (c) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, | |
956 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 | |
957 Free Software Foundation, Inc. | |
958 .PP | |
959 Permission is granted to copy, distribute and/or modify this document | |
960 under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.2 or | |
961 any later version published by the Free Software Foundation. A copy of | |
962 the license is included in the | |
963 man page \fIgfdl\fR\|(7). | |
964 This manual contains no Invariant Sections. The Front-Cover Texts are | |
965 (a) (see below), and the Back-Cover Texts are (b) (see below). | |
966 .PP | |
967 (a) The \s-1FSF\s0's Front-Cover Text is: | |
968 .PP | |
969 .Vb 1 | |
970 \& A GNU Manual | |
971 .Ve | |
972 .PP | |
973 (b) The \s-1FSF\s0's Back-Cover Text is: | |
974 .PP | |
975 .Vb 3 | |
976 \& You have freedom to copy and modify this GNU Manual, like GNU | |
977 \& software. Copies published by the Free Software Foundation raise | |
978 \& funds for GNU development. | |
979 .Ve |