|
0
|
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
|
