1 | This is Info file gcc.info, produced by Makeinfo-1.55 from the input |
---|
2 | file gcc.texi. |
---|
3 | |
---|
4 | This file documents the use and the internals of the GNU compiler. |
---|
5 | |
---|
6 | Published by the Free Software Foundation 59 Temple Place - Suite 330 |
---|
7 | Boston, MA 02111-1307 USA |
---|
8 | |
---|
9 | Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995 Free Software |
---|
10 | Foundation, Inc. |
---|
11 | |
---|
12 | Permission is granted to make and distribute verbatim copies of this |
---|
13 | manual provided the copyright notice and this permission notice are |
---|
14 | preserved on all copies. |
---|
15 | |
---|
16 | Permission is granted to copy and distribute modified versions of |
---|
17 | this manual under the conditions for verbatim copying, provided also |
---|
18 | that the sections entitled "GNU General Public License," "Funding for |
---|
19 | Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are |
---|
20 | included exactly as in the original, and provided that the entire |
---|
21 | resulting derived work is distributed under the terms of a permission |
---|
22 | notice identical to this one. |
---|
23 | |
---|
24 | Permission is granted to copy and distribute translations of this |
---|
25 | manual into another language, under the above conditions for modified |
---|
26 | versions, except that the sections entitled "GNU General Public |
---|
27 | License," "Funding for Free Software," and "Protect Your Freedom--Fight |
---|
28 | `Look And Feel'", and this permission notice, may be included in |
---|
29 | translations approved by the Free Software Foundation instead of in the |
---|
30 | original English. |
---|
31 | |
---|
32 | |
---|
33 | File: gcc.info, Node: Warning Options, Next: Debugging Options, Prev: C++ Dialect Options, Up: Invoking GCC |
---|
34 | |
---|
35 | Options to Request or Suppress Warnings |
---|
36 | ======================================= |
---|
37 | |
---|
38 | Warnings are diagnostic messages that report constructions which are |
---|
39 | not inherently erroneous but which are risky or suggest there may have |
---|
40 | been an error. |
---|
41 | |
---|
42 | You can request many specific warnings with options beginning `-W', |
---|
43 | for example `-Wimplicit' to request warnings on implicit declarations. |
---|
44 | Each of these specific warning options also has a negative form |
---|
45 | beginning `-Wno-' to turn off warnings; for example, `-Wno-implicit'. |
---|
46 | This manual lists only one of the two forms, whichever is not the |
---|
47 | default. |
---|
48 | |
---|
49 | These options control the amount and kinds of warnings produced by |
---|
50 | GNU CC: |
---|
51 | |
---|
52 | `-fsyntax-only' |
---|
53 | Check the code for syntax errors, but don't do anything beyond |
---|
54 | that. |
---|
55 | |
---|
56 | `-pedantic' |
---|
57 | Issue all the warnings demanded by strict ANSI standard C; reject |
---|
58 | all programs that use forbidden extensions. |
---|
59 | |
---|
60 | Valid ANSI standard C programs should compile properly with or |
---|
61 | without this option (though a rare few will require `-ansi'). |
---|
62 | However, without this option, certain GNU extensions and |
---|
63 | traditional C features are supported as well. With this option, |
---|
64 | they are rejected. |
---|
65 | |
---|
66 | `-pedantic' does not cause warning messages for use of the |
---|
67 | alternate keywords whose names begin and end with `__'. Pedantic |
---|
68 | warnings are also disabled in the expression that follows |
---|
69 | `__extension__'. However, only system header files should use |
---|
70 | these escape routes; application programs should avoid them. |
---|
71 | *Note Alternate Keywords::. |
---|
72 | |
---|
73 | This option is not intended to be useful; it exists only to satisfy |
---|
74 | pedants who would otherwise claim that GNU CC fails to support the |
---|
75 | ANSI standard. |
---|
76 | |
---|
77 | Some users try to use `-pedantic' to check programs for strict ANSI |
---|
78 | C conformance. They soon find that it does not do quite what they |
---|
79 | want: it finds some non-ANSI practices, but not all--only those |
---|
80 | for which ANSI C *requires* a diagnostic. |
---|
81 | |
---|
82 | A feature to report any failure to conform to ANSI C might be |
---|
83 | useful in some instances, but would require considerable |
---|
84 | additional work and would be quite different from `-pedantic'. We |
---|
85 | recommend, rather, that users take advantage of the extensions of |
---|
86 | GNU C and disregard the limitations of other compilers. Aside |
---|
87 | from certain supercomputers and obsolete small machines, there is |
---|
88 | less and less reason ever to use any other C compiler other than |
---|
89 | for bootstrapping GNU CC. |
---|
90 | |
---|
91 | `-pedantic-errors' |
---|
92 | Like `-pedantic', except that errors are produced rather than |
---|
93 | warnings. |
---|
94 | |
---|
95 | `-w' |
---|
96 | Inhibit all warning messages. |
---|
97 | |
---|
98 | `-Wno-import' |
---|
99 | Inhibit warning messages about the use of `#import'. |
---|
100 | |
---|
101 | `-Wchar-subscripts' |
---|
102 | Warn if an array subscript has type `char'. This is a common cause |
---|
103 | of error, as programmers often forget that this type is signed on |
---|
104 | some machines. |
---|
105 | |
---|
106 | `-Wcomment' |
---|
107 | Warn whenever a comment-start sequence `/*' appears in a comment. |
---|
108 | |
---|
109 | `-Wformat' |
---|
110 | Check calls to `printf' and `scanf', etc., to make sure that the |
---|
111 | arguments supplied have types appropriate to the format string |
---|
112 | specified. |
---|
113 | |
---|
114 | `-Wimplicit' |
---|
115 | Warn whenever a function or parameter is implicitly declared. |
---|
116 | |
---|
117 | `-Wparentheses' |
---|
118 | Warn if parentheses are omitted in certain contexts, such as when |
---|
119 | there is an assignment in a context where a truth value is |
---|
120 | expected, or when operators are nested whose precedence people |
---|
121 | often get confused about. |
---|
122 | |
---|
123 | `-Wreturn-type' |
---|
124 | Warn whenever a function is defined with a return-type that |
---|
125 | defaults to `int'. Also warn about any `return' statement with no |
---|
126 | return-value in a function whose return-type is not `void'. |
---|
127 | |
---|
128 | `-Wswitch' |
---|
129 | Warn whenever a `switch' statement has an index of enumeral type |
---|
130 | and lacks a `case' for one or more of the named codes of that |
---|
131 | enumeration. (The presence of a `default' label prevents this |
---|
132 | warning.) `case' labels outside the enumeration range also |
---|
133 | provoke warnings when this option is used. |
---|
134 | |
---|
135 | `-Wtrigraphs' |
---|
136 | Warn if any trigraphs are encountered (assuming they are enabled). |
---|
137 | |
---|
138 | `-Wunused' |
---|
139 | Warn whenever a variable is unused aside from its declaration, |
---|
140 | whenever a function is declared static but never defined, whenever |
---|
141 | a label is declared but not used, and whenever a statement |
---|
142 | computes a result that is explicitly not used. |
---|
143 | |
---|
144 | To suppress this warning for an expression, simply cast it to |
---|
145 | void. For unused variables and parameters, use the `unused' |
---|
146 | attribute (*note Variable Attributes::.). |
---|
147 | |
---|
148 | `-Wuninitialized' |
---|
149 | An automatic variable is used without first being initialized. |
---|
150 | |
---|
151 | These warnings are possible only in optimizing compilation, |
---|
152 | because they require data flow information that is computed only |
---|
153 | when optimizing. If you don't specify `-O', you simply won't get |
---|
154 | these warnings. |
---|
155 | |
---|
156 | These warnings occur only for variables that are candidates for |
---|
157 | register allocation. Therefore, they do not occur for a variable |
---|
158 | that is declared `volatile', or whose address is taken, or whose |
---|
159 | size is other than 1, 2, 4 or 8 bytes. Also, they do not occur for |
---|
160 | structures, unions or arrays, even when they are in registers. |
---|
161 | |
---|
162 | Note that there may be no warning about a variable that is used |
---|
163 | only to compute a value that itself is never used, because such |
---|
164 | computations may be deleted by data flow analysis before the |
---|
165 | warnings are printed. |
---|
166 | |
---|
167 | These warnings are made optional because GNU CC is not smart |
---|
168 | enough to see all the reasons why the code might be correct |
---|
169 | despite appearing to have an error. Here is one example of how |
---|
170 | this can happen: |
---|
171 | |
---|
172 | { |
---|
173 | int x; |
---|
174 | switch (y) |
---|
175 | { |
---|
176 | case 1: x = 1; |
---|
177 | break; |
---|
178 | case 2: x = 4; |
---|
179 | break; |
---|
180 | case 3: x = 5; |
---|
181 | } |
---|
182 | foo (x); |
---|
183 | } |
---|
184 | |
---|
185 | If the value of `y' is always 1, 2 or 3, then `x' is always |
---|
186 | initialized, but GNU CC doesn't know this. Here is another common |
---|
187 | case: |
---|
188 | |
---|
189 | { |
---|
190 | int save_y; |
---|
191 | if (change_y) save_y = y, y = new_y; |
---|
192 | ... |
---|
193 | if (change_y) y = save_y; |
---|
194 | } |
---|
195 | |
---|
196 | This has no bug because `save_y' is used only if it is set. |
---|
197 | |
---|
198 | Some spurious warnings can be avoided if you declare all the |
---|
199 | functions you use that never return as `noreturn'. *Note Function |
---|
200 | Attributes::. |
---|
201 | |
---|
202 | `-Wenum-clash' |
---|
203 | Warn about conversion between different enumeration types. (C++ |
---|
204 | only). |
---|
205 | |
---|
206 | `-Wreorder (C++ only)' |
---|
207 | Warn when the order of member initializers given in the code does |
---|
208 | not match the order in which they must be executed. For instance: |
---|
209 | |
---|
210 | struct A { |
---|
211 | int i; |
---|
212 | int j; |
---|
213 | A(): j (0), i (1) { } |
---|
214 | }; |
---|
215 | |
---|
216 | Here the compiler will warn that the member initializers for `i' |
---|
217 | and `j' will be rearranged to match the declaration order of the |
---|
218 | members. |
---|
219 | |
---|
220 | `-Wtemplate-debugging' |
---|
221 | When using templates in a C++ program, warn if debugging is not yet |
---|
222 | fully available (C++ only). |
---|
223 | |
---|
224 | `-Wall' |
---|
225 | All of the above `-W' options combined. These are all the options |
---|
226 | which pertain to usage that we recommend avoiding and that we |
---|
227 | believe is easy to avoid, even in conjunction with macros. |
---|
228 | |
---|
229 | The remaining `-W...' options are not implied by `-Wall' because |
---|
230 | they warn about constructions that we consider reasonable to use, on |
---|
231 | occasion, in clean programs. |
---|
232 | |
---|
233 | `-W' |
---|
234 | Print extra warning messages for these events: |
---|
235 | |
---|
236 | * A nonvolatile automatic variable might be changed by a call to |
---|
237 | `longjmp'. These warnings as well are possible only in |
---|
238 | optimizing compilation. |
---|
239 | |
---|
240 | The compiler sees only the calls to `setjmp'. It cannot know |
---|
241 | where `longjmp' will be called; in fact, a signal handler |
---|
242 | could call it at any point in the code. As a result, you may |
---|
243 | get a warning even when there is in fact no problem because |
---|
244 | `longjmp' cannot in fact be called at the place which would |
---|
245 | cause a problem. |
---|
246 | |
---|
247 | * A function can return either with or without a value. |
---|
248 | (Falling off the end of the function body is considered |
---|
249 | returning without a value.) For example, this function would |
---|
250 | evoke such a warning: |
---|
251 | |
---|
252 | foo (a) |
---|
253 | { |
---|
254 | if (a > 0) |
---|
255 | return a; |
---|
256 | } |
---|
257 | |
---|
258 | * An expression-statement or the left-hand side of a comma |
---|
259 | expression contains no side effects. To suppress the |
---|
260 | warning, cast the unused expression to void. For example, an |
---|
261 | expression such as `x[i,j]' will cause a warning, but |
---|
262 | `x[(void)i,j]' will not. |
---|
263 | |
---|
264 | * An unsigned value is compared against zero with `<' or `<='. |
---|
265 | |
---|
266 | * A comparison like `x<=y<=z' appears; this is equivalent to |
---|
267 | `(x<=y ? 1 : 0) <= z', which is a different interpretation |
---|
268 | from that of ordinary mathematical notation. |
---|
269 | |
---|
270 | * Storage-class specifiers like `static' are not the first |
---|
271 | things in a declaration. According to the C Standard, this |
---|
272 | usage is obsolescent. |
---|
273 | |
---|
274 | * If `-Wall' or `-Wunused' is also specified, warn about unused |
---|
275 | arguments. |
---|
276 | |
---|
277 | * An aggregate has a partly bracketed initializer. For |
---|
278 | example, the following code would evoke such a warning, |
---|
279 | because braces are missing around the initializer for `x.h': |
---|
280 | |
---|
281 | struct s { int f, g; }; |
---|
282 | struct t { struct s h; int i; }; |
---|
283 | struct t x = { 1, 2, 3 }; |
---|
284 | |
---|
285 | `-Wtraditional' |
---|
286 | Warn about certain constructs that behave differently in |
---|
287 | traditional and ANSI C. |
---|
288 | |
---|
289 | * Macro arguments occurring within string constants in the |
---|
290 | macro body. These would substitute the argument in |
---|
291 | traditional C, but are part of the constant in ANSI C. |
---|
292 | |
---|
293 | * A function declared external in one block and then used after |
---|
294 | the end of the block. |
---|
295 | |
---|
296 | * A `switch' statement has an operand of type `long'. |
---|
297 | |
---|
298 | `-Wshadow' |
---|
299 | Warn whenever a local variable shadows another local variable. |
---|
300 | |
---|
301 | `-Wid-clash-LEN' |
---|
302 | Warn whenever two distinct identifiers match in the first LEN |
---|
303 | characters. This may help you prepare a program that will compile |
---|
304 | with certain obsolete, brain-damaged compilers. |
---|
305 | |
---|
306 | `-Wlarger-than-LEN' |
---|
307 | Warn whenever an object of larger than LEN bytes is defined. |
---|
308 | |
---|
309 | `-Wpointer-arith' |
---|
310 | Warn about anything that depends on the "size of" a function type |
---|
311 | or of `void'. GNU C assigns these types a size of 1, for |
---|
312 | convenience in calculations with `void *' pointers and pointers to |
---|
313 | functions. |
---|
314 | |
---|
315 | `-Wbad-function-cast' |
---|
316 | Warn whenever a function call is cast to a non-matching type. For |
---|
317 | example, warn if `int malloc()' is cast to `anything *'. |
---|
318 | |
---|
319 | `-Wcast-qual' |
---|
320 | Warn whenever a pointer is cast so as to remove a type qualifier |
---|
321 | from the target type. For example, warn if a `const char *' is |
---|
322 | cast to an ordinary `char *'. |
---|
323 | |
---|
324 | `-Wcast-align' |
---|
325 | Warn whenever a pointer is cast such that the required alignment |
---|
326 | of the target is increased. For example, warn if a `char *' is |
---|
327 | cast to an `int *' on machines where integers can only be accessed |
---|
328 | at two- or four-byte boundaries. |
---|
329 | |
---|
330 | `-Wwrite-strings' |
---|
331 | Give string constants the type `const char[LENGTH]' so that |
---|
332 | copying the address of one into a non-`const' `char *' pointer |
---|
333 | will get a warning. These warnings will help you find at compile |
---|
334 | time code that can try to write into a string constant, but only |
---|
335 | if you have been very careful about using `const' in declarations |
---|
336 | and prototypes. Otherwise, it will just be a nuisance; this is |
---|
337 | why we did not make `-Wall' request these warnings. |
---|
338 | |
---|
339 | `-Wconversion' |
---|
340 | Warn if a prototype causes a type conversion that is different |
---|
341 | from what would happen to the same argument in the absence of a |
---|
342 | prototype. This includes conversions of fixed point to floating |
---|
343 | and vice versa, and conversions changing the width or signedness |
---|
344 | of a fixed point argument except when the same as the default |
---|
345 | promotion. |
---|
346 | |
---|
347 | Also, warn if a negative integer constant expression is implicitly |
---|
348 | converted to an unsigned type. For example, warn about the |
---|
349 | assignment `x = -1' if `x' is unsigned. But do not warn about |
---|
350 | explicit casts like `(unsigned) -1'. |
---|
351 | |
---|
352 | `-Waggregate-return' |
---|
353 | Warn if any functions that return structures or unions are defined |
---|
354 | or called. (In languages where you can return an array, this also |
---|
355 | elicits a warning.) |
---|
356 | |
---|
357 | `-Wstrict-prototypes' |
---|
358 | Warn if a function is declared or defined without specifying the |
---|
359 | argument types. (An old-style function definition is permitted |
---|
360 | without a warning if preceded by a declaration which specifies the |
---|
361 | argument types.) |
---|
362 | |
---|
363 | `-Wmissing-prototypes' |
---|
364 | Warn if a global function is defined without a previous prototype |
---|
365 | declaration. This warning is issued even if the definition itself |
---|
366 | provides a prototype. The aim is to detect global functions that |
---|
367 | fail to be declared in header files. |
---|
368 | |
---|
369 | `-Wmissing-declarations' |
---|
370 | Warn if a global function is defined without a previous |
---|
371 | declaration. Do so even if the definition itself provides a |
---|
372 | prototype. Use this option to detect global functions that are |
---|
373 | not declared in header files. |
---|
374 | |
---|
375 | `-Wredundant-decls' |
---|
376 | Warn if anything is declared more than once in the same scope, |
---|
377 | even in cases where multiple declaration is valid and changes |
---|
378 | nothing. |
---|
379 | |
---|
380 | `-Wnested-externs' |
---|
381 | Warn if an `extern' declaration is encountered within an function. |
---|
382 | |
---|
383 | `-Winline' |
---|
384 | Warn if a function can not be inlined, and either it was declared |
---|
385 | as inline, or else the `-finline-functions' option was given. |
---|
386 | |
---|
387 | `-Woverloaded-virtual' |
---|
388 | Warn when a derived class function declaration may be an error in |
---|
389 | defining a virtual function (C++ only). In a derived class, the |
---|
390 | definitions of virtual functions must match the type signature of a |
---|
391 | virtual function declared in the base class. With this option, the |
---|
392 | compiler warns when you define a function with the same name as a |
---|
393 | virtual function, but with a type signature that does not match any |
---|
394 | declarations from the base class. |
---|
395 | |
---|
396 | `-Wsynth (C++ only)' |
---|
397 | Warn when g++'s synthesis behavior does not match that of cfront. |
---|
398 | For instance: |
---|
399 | |
---|
400 | struct A { |
---|
401 | operator int (); |
---|
402 | A& operator = (int); |
---|
403 | }; |
---|
404 | |
---|
405 | main () |
---|
406 | { |
---|
407 | A a,b; |
---|
408 | a = b; |
---|
409 | } |
---|
410 | |
---|
411 | In this example, g++ will synthesize a default `A& operator = |
---|
412 | (const A&);', while cfront will use the user-defined `operator ='. |
---|
413 | |
---|
414 | `-Werror' |
---|
415 | Make all warnings into errors. |
---|
416 | |
---|
417 | |
---|
418 | File: gcc.info, Node: Debugging Options, Next: Optimize Options, Prev: Warning Options, Up: Invoking GCC |
---|
419 | |
---|
420 | Options for Debugging Your Program or GNU CC |
---|
421 | ============================================ |
---|
422 | |
---|
423 | GNU CC has various special options that are used for debugging |
---|
424 | either your program or GCC: |
---|
425 | |
---|
426 | `-g' |
---|
427 | Produce debugging information in the operating system's native |
---|
428 | format (stabs, COFF, XCOFF, or DWARF). GDB can work with this |
---|
429 | debugging information. |
---|
430 | |
---|
431 | On most systems that use stabs format, `-g' enables use of extra |
---|
432 | debugging information that only GDB can use; this extra information |
---|
433 | makes debugging work better in GDB but will probably make other |
---|
434 | debuggers crash or refuse to read the program. If you want to |
---|
435 | control for certain whether to generate the extra information, use |
---|
436 | `-gstabs+', `-gstabs', `-gxcoff+', `-gxcoff', `-gdwarf+', or |
---|
437 | `-gdwarf' (see below). |
---|
438 | |
---|
439 | Unlike most other C compilers, GNU CC allows you to use `-g' with |
---|
440 | `-O'. The shortcuts taken by optimized code may occasionally |
---|
441 | produce surprising results: some variables you declared may not |
---|
442 | exist at all; flow of control may briefly move where you did not |
---|
443 | expect it; some statements may not be executed because they |
---|
444 | compute constant results or their values were already at hand; |
---|
445 | some statements may execute in different places because they were |
---|
446 | moved out of loops. |
---|
447 | |
---|
448 | Nevertheless it proves possible to debug optimized output. This |
---|
449 | makes it reasonable to use the optimizer for programs that might |
---|
450 | have bugs. |
---|
451 | |
---|
452 | The following options are useful when GNU CC is generated with the |
---|
453 | capability for more than one debugging format. |
---|
454 | |
---|
455 | `-ggdb' |
---|
456 | Produce debugging information in the native format (if that is |
---|
457 | supported), including GDB extensions if at all possible. |
---|
458 | |
---|
459 | `-gstabs' |
---|
460 | Produce debugging information in stabs format (if that is |
---|
461 | supported), without GDB extensions. This is the format used by |
---|
462 | DBX on most BSD systems. On MIPS, Alpha and System V Release 4 |
---|
463 | systems this option produces stabs debugging output which is not |
---|
464 | understood by DBX or SDB. On System V Release 4 systems this |
---|
465 | option requires the GNU assembler. |
---|
466 | |
---|
467 | `-gstabs+' |
---|
468 | Produce debugging information in stabs format (if that is |
---|
469 | supported), using GNU extensions understood only by the GNU |
---|
470 | debugger (GDB). The use of these extensions is likely to make |
---|
471 | other debuggers crash or refuse to read the program. |
---|
472 | |
---|
473 | `-gcoff' |
---|
474 | Produce debugging information in COFF format (if that is |
---|
475 | supported). This is the format used by SDB on most System V |
---|
476 | systems prior to System V Release 4. |
---|
477 | |
---|
478 | `-gxcoff' |
---|
479 | Produce debugging information in XCOFF format (if that is |
---|
480 | supported). This is the format used by the DBX debugger on IBM |
---|
481 | RS/6000 systems. |
---|
482 | |
---|
483 | `-gxcoff+' |
---|
484 | Produce debugging information in XCOFF format (if that is |
---|
485 | supported), using GNU extensions understood only by the GNU |
---|
486 | debugger (GDB). The use of these extensions is likely to make |
---|
487 | other debuggers crash or refuse to read the program, and may cause |
---|
488 | assemblers other than the GNU assembler (GAS) to fail with an |
---|
489 | error. |
---|
490 | |
---|
491 | `-gdwarf' |
---|
492 | Produce debugging information in DWARF format (if that is |
---|
493 | supported). This is the format used by SDB on most System V |
---|
494 | Release 4 systems. |
---|
495 | |
---|
496 | `-gdwarf+' |
---|
497 | Produce debugging information in DWARF format (if that is |
---|
498 | supported), using GNU extensions understood only by the GNU |
---|
499 | debugger (GDB). The use of these extensions is likely to make |
---|
500 | other debuggers crash or refuse to read the program. |
---|
501 | |
---|
502 | `-gLEVEL' |
---|
503 | `-ggdbLEVEL' |
---|
504 | `-gstabsLEVEL' |
---|
505 | `-gcoffLEVEL' |
---|
506 | `-gxcoffLEVEL' |
---|
507 | `-gdwarfLEVEL' |
---|
508 | Request debugging information and also use LEVEL to specify how |
---|
509 | much information. The default level is 2. |
---|
510 | |
---|
511 | Level 1 produces minimal information, enough for making backtraces |
---|
512 | in parts of the program that you don't plan to debug. This |
---|
513 | includes descriptions of functions and external variables, but no |
---|
514 | information about local variables and no line numbers. |
---|
515 | |
---|
516 | Level 3 includes extra information, such as all the macro |
---|
517 | definitions present in the program. Some debuggers support macro |
---|
518 | expansion when you use `-g3'. |
---|
519 | |
---|
520 | `-p' |
---|
521 | Generate extra code to write profile information suitable for the |
---|
522 | analysis program `prof'. You must use this option when compiling |
---|
523 | the source files you want data about, and you must also use it when |
---|
524 | linking. |
---|
525 | |
---|
526 | `-pg' |
---|
527 | Generate extra code to write profile information suitable for the |
---|
528 | analysis program `gprof'. You must use this option when compiling |
---|
529 | the source files you want data about, and you must also use it when |
---|
530 | linking. |
---|
531 | |
---|
532 | `-a' |
---|
533 | Generate extra code to write profile information for basic blocks, |
---|
534 | which will record the number of times each basic block is |
---|
535 | executed, the basic block start address, and the function name |
---|
536 | containing the basic block. If `-g' is used, the line number and |
---|
537 | filename of the start of the basic block will also be recorded. |
---|
538 | If not overridden by the machine description, the default action is |
---|
539 | to append to the text file `bb.out'. |
---|
540 | |
---|
541 | This data could be analyzed by a program like `tcov'. Note, |
---|
542 | however, that the format of the data is not what `tcov' expects. |
---|
543 | Eventually GNU `gprof' should be extended to process this data. |
---|
544 | |
---|
545 | `-dLETTERS' |
---|
546 | Says to make debugging dumps during compilation at times specified |
---|
547 | by LETTERS. This is used for debugging the compiler. The file |
---|
548 | names for most of the dumps are made by appending a word to the |
---|
549 | source file name (e.g. `foo.c.rtl' or `foo.c.jump'). Here are the |
---|
550 | possible letters for use in LETTERS, and their meanings: |
---|
551 | |
---|
552 | `M' |
---|
553 | Dump all macro definitions, at the end of preprocessing, and |
---|
554 | write no output. |
---|
555 | |
---|
556 | `N' |
---|
557 | Dump all macro names, at the end of preprocessing. |
---|
558 | |
---|
559 | `D' |
---|
560 | Dump all macro definitions, at the end of preprocessing, in |
---|
561 | addition to normal output. |
---|
562 | |
---|
563 | `y' |
---|
564 | Dump debugging information during parsing, to standard error. |
---|
565 | |
---|
566 | `r' |
---|
567 | Dump after RTL generation, to `FILE.rtl'. |
---|
568 | |
---|
569 | `x' |
---|
570 | Just generate RTL for a function instead of compiling it. |
---|
571 | Usually used with `r'. |
---|
572 | |
---|
573 | `j' |
---|
574 | Dump after first jump optimization, to `FILE.jump'. |
---|
575 | |
---|
576 | `s' |
---|
577 | Dump after CSE (including the jump optimization that sometimes |
---|
578 | follows CSE), to `FILE.cse'. |
---|
579 | |
---|
580 | `L' |
---|
581 | Dump after loop optimization, to `FILE.loop'. |
---|
582 | |
---|
583 | `t' |
---|
584 | Dump after the second CSE pass (including the jump |
---|
585 | optimization that sometimes follows CSE), to `FILE.cse2'. |
---|
586 | |
---|
587 | `f' |
---|
588 | Dump after flow analysis, to `FILE.flow'. |
---|
589 | |
---|
590 | `c' |
---|
591 | Dump after instruction combination, to the file |
---|
592 | `FILE.combine'. |
---|
593 | |
---|
594 | `S' |
---|
595 | Dump after the first instruction scheduling pass, to |
---|
596 | `FILE.sched'. |
---|
597 | |
---|
598 | `l' |
---|
599 | Dump after local register allocation, to `FILE.lreg'. |
---|
600 | |
---|
601 | `g' |
---|
602 | Dump after global register allocation, to `FILE.greg'. |
---|
603 | |
---|
604 | `R' |
---|
605 | Dump after the second instruction scheduling pass, to |
---|
606 | `FILE.sched2'. |
---|
607 | |
---|
608 | `J' |
---|
609 | Dump after last jump optimization, to `FILE.jump2'. |
---|
610 | |
---|
611 | `d' |
---|
612 | Dump after delayed branch scheduling, to `FILE.dbr'. |
---|
613 | |
---|
614 | `k' |
---|
615 | Dump after conversion from registers to stack, to |
---|
616 | `FILE.stack'. |
---|
617 | |
---|
618 | `a' |
---|
619 | Produce all the dumps listed above. |
---|
620 | |
---|
621 | `m' |
---|
622 | Print statistics on memory usage, at the end of the run, to |
---|
623 | standard error. |
---|
624 | |
---|
625 | `p' |
---|
626 | Annotate the assembler output with a comment indicating which |
---|
627 | pattern and alternative was used. |
---|
628 | |
---|
629 | `-fpretend-float' |
---|
630 | When running a cross-compiler, pretend that the target machine |
---|
631 | uses the same floating point format as the host machine. This |
---|
632 | causes incorrect output of the actual floating constants, but the |
---|
633 | actual instruction sequence will probably be the same as GNU CC |
---|
634 | would make when running on the target machine. |
---|
635 | |
---|
636 | `-save-temps' |
---|
637 | Store the usual "temporary" intermediate files permanently; place |
---|
638 | them in the current directory and name them based on the source |
---|
639 | file. Thus, compiling `foo.c' with `-c -save-temps' would produce |
---|
640 | files `foo.i' and `foo.s', as well as `foo.o'. |
---|
641 | |
---|
642 | `-print-file-name=LIBRARY' |
---|
643 | Print the full absolute name of the library file LIBRARY that |
---|
644 | would be used when linking--and don't do anything else. With this |
---|
645 | option, GNU CC does not compile or link anything; it just prints |
---|
646 | the file name. |
---|
647 | |
---|
648 | `-print-prog-name=PROGRAM' |
---|
649 | Like `-print-file-name', but searches for a program such as `cpp'. |
---|
650 | |
---|
651 | `-print-libgcc-file-name' |
---|
652 | Same as `-print-file-name=libgcc.a'. |
---|
653 | |
---|
654 | This is useful when you use `-nostdlib' or `-nodefaultlibs' but |
---|
655 | you do want to link with `libgcc.a'. You can do |
---|
656 | |
---|
657 | gcc -nostdlib FILES... `gcc -print-libgcc-file-name` |
---|
658 | |
---|
659 | `-print-search-dirs' |
---|
660 | Print the name of the configured installation directory and a list |
---|
661 | of program and library directories gcc will search--and don't do |
---|
662 | anything else. |
---|
663 | |
---|
664 | This is useful when gcc prints the error message `installation |
---|
665 | problem, cannot exec cpp: No such file or directory'. To resolve |
---|
666 | this you either need to put `cpp' and the other compiler |
---|
667 | components where gcc expects to find them, or you can set the |
---|
668 | environment variable `GCC_EXEC_PREFIX' to the directory where you |
---|
669 | installed them. Don't forget the trailing '/'. *Note Environment |
---|
670 | Variables::. |
---|
671 | |
---|
672 | |
---|
673 | File: gcc.info, Node: Optimize Options, Next: Preprocessor Options, Prev: Debugging Options, Up: Invoking GCC |
---|
674 | |
---|
675 | Options That Control Optimization |
---|
676 | ================================= |
---|
677 | |
---|
678 | These options control various sorts of optimizations: |
---|
679 | |
---|
680 | `-O' |
---|
681 | `-O1' |
---|
682 | Optimize. Optimizing compilation takes somewhat more time, and a |
---|
683 | lot more memory for a large function. |
---|
684 | |
---|
685 | Without `-O', the compiler's goal is to reduce the cost of |
---|
686 | compilation and to make debugging produce the expected results. |
---|
687 | Statements are independent: if you stop the program with a |
---|
688 | breakpoint between statements, you can then assign a new value to |
---|
689 | any variable or change the program counter to any other statement |
---|
690 | in the function and get exactly the results you would expect from |
---|
691 | the source code. |
---|
692 | |
---|
693 | Without `-O', the compiler only allocates variables declared |
---|
694 | `register' in registers. The resulting compiled code is a little |
---|
695 | worse than produced by PCC without `-O'. |
---|
696 | |
---|
697 | With `-O', the compiler tries to reduce code size and execution |
---|
698 | time. |
---|
699 | |
---|
700 | When you specify `-O', the compiler turns on `-fthread-jumps' and |
---|
701 | `-fdefer-pop' on all machines. The compiler turns on |
---|
702 | `-fdelayed-branch' on machines that have delay slots, and |
---|
703 | `-fomit-frame-pointer' on machines that can support debugging even |
---|
704 | without a frame pointer. On some machines the compiler also turns |
---|
705 | on other flags. |
---|
706 | |
---|
707 | `-O2' |
---|
708 | Optimize even more. GNU CC performs nearly all supported |
---|
709 | optimizations that do not involve a space-speed tradeoff. The |
---|
710 | compiler does not perform loop unrolling or function inlining when |
---|
711 | you specify `-O2'. As compared to `-O', this option increases |
---|
712 | both compilation time and the performance of the generated code. |
---|
713 | |
---|
714 | `-O2' turns on all optional optimizations except for loop unrolling |
---|
715 | and function inlining. It also turns on the `-fforce-mem' option |
---|
716 | on all machines and frame pointer elimination on machines where |
---|
717 | doing so does not interfere with debugging. |
---|
718 | |
---|
719 | `-O3' |
---|
720 | Optimize yet more. `-O3' turns on all optimizations specified by |
---|
721 | `-O2' and also turns on the `inline-functions' option. |
---|
722 | |
---|
723 | `-O0' |
---|
724 | Do not optimize. |
---|
725 | |
---|
726 | If you use multiple `-O' options, with or without level numbers, |
---|
727 | the last such option is the one that is effective. |
---|
728 | |
---|
729 | Options of the form `-fFLAG' specify machine-independent flags. |
---|
730 | Most flags have both positive and negative forms; the negative form of |
---|
731 | `-ffoo' would be `-fno-foo'. In the table below, only one of the forms |
---|
732 | is listed--the one which is not the default. You can figure out the |
---|
733 | other form by either removing `no-' or adding it. |
---|
734 | |
---|
735 | `-ffloat-store' |
---|
736 | Do not store floating point variables in registers, and inhibit |
---|
737 | other options that might change whether a floating point value is |
---|
738 | taken from a register or memory. |
---|
739 | |
---|
740 | This option prevents undesirable excess precision on machines such |
---|
741 | as the 68000 where the floating registers (of the 68881) keep more |
---|
742 | precision than a `double' is supposed to have. For most programs, |
---|
743 | the excess precision does only good, but a few programs rely on the |
---|
744 | precise definition of IEEE floating point. Use `-ffloat-store' for |
---|
745 | such programs. |
---|
746 | |
---|
747 | `-fno-default-inline' |
---|
748 | Do not make member functions inline by default merely because they |
---|
749 | are defined inside the class scope (C++ only). Otherwise, when |
---|
750 | you specify `-O', member functions defined inside class scope are |
---|
751 | compiled inline by default; i.e., you don't need to add `inline' |
---|
752 | in front of the member function name. |
---|
753 | |
---|
754 | `-fno-defer-pop' |
---|
755 | Always pop the arguments to each function call as soon as that |
---|
756 | function returns. For machines which must pop arguments after a |
---|
757 | function call, the compiler normally lets arguments accumulate on |
---|
758 | the stack for several function calls and pops them all at once. |
---|
759 | |
---|
760 | `-fforce-mem' |
---|
761 | Force memory operands to be copied into registers before doing |
---|
762 | arithmetic on them. This produces better code by making all memory |
---|
763 | references potential common subexpressions. When they are not |
---|
764 | common subexpressions, instruction combination should eliminate |
---|
765 | the separate register-load. The `-O2' option turns on this option. |
---|
766 | |
---|
767 | `-fforce-addr' |
---|
768 | Force memory address constants to be copied into registers before |
---|
769 | doing arithmetic on them. This may produce better code just as |
---|
770 | `-fforce-mem' may. |
---|
771 | |
---|
772 | `-fomit-frame-pointer' |
---|
773 | Don't keep the frame pointer in a register for functions that |
---|
774 | don't need one. This avoids the instructions to save, set up and |
---|
775 | restore frame pointers; it also makes an extra register available |
---|
776 | in many functions. *It also makes debugging impossible on some |
---|
777 | machines.* |
---|
778 | |
---|
779 | On some machines, such as the Vax, this flag has no effect, because |
---|
780 | the standard calling sequence automatically handles the frame |
---|
781 | pointer and nothing is saved by pretending it doesn't exist. The |
---|
782 | machine-description macro `FRAME_POINTER_REQUIRED' controls |
---|
783 | whether a target machine supports this flag. *Note Registers::. |
---|
784 | |
---|
785 | `-fno-inline' |
---|
786 | Don't pay attention to the `inline' keyword. Normally this option |
---|
787 | is used to keep the compiler from expanding any functions inline. |
---|
788 | Note that if you are not optimizing, no functions can be expanded |
---|
789 | inline. |
---|
790 | |
---|
791 | `-finline-functions' |
---|
792 | Integrate all simple functions into their callers. The compiler |
---|
793 | heuristically decides which functions are simple enough to be worth |
---|
794 | integrating in this way. |
---|
795 | |
---|
796 | If all calls to a given function are integrated, and the function |
---|
797 | is declared `static', then the function is normally not output as |
---|
798 | assembler code in its own right. |
---|
799 | |
---|
800 | `-fkeep-inline-functions' |
---|
801 | Even if all calls to a given function are integrated, and the |
---|
802 | function is declared `static', nevertheless output a separate |
---|
803 | run-time callable version of the function. |
---|
804 | |
---|
805 | `-fno-function-cse' |
---|
806 | Do not put function addresses in registers; make each instruction |
---|
807 | that calls a constant function contain the function's address |
---|
808 | explicitly. |
---|
809 | |
---|
810 | This option results in less efficient code, but some strange hacks |
---|
811 | that alter the assembler output may be confused by the |
---|
812 | optimizations performed when this option is not used. |
---|
813 | |
---|
814 | `-ffast-math' |
---|
815 | This option allows GCC to violate some ANSI or IEEE rules and/or |
---|
816 | specifications in the interest of optimizing code for speed. For |
---|
817 | example, it allows the compiler to assume arguments to the `sqrt' |
---|
818 | function are non-negative numbers and that no floating-point values |
---|
819 | are NaNs. |
---|
820 | |
---|
821 | This option should never be turned on by any `-O' option since it |
---|
822 | can result in incorrect output for programs which depend on an |
---|
823 | exact implementation of IEEE or ANSI rules/specifications for math |
---|
824 | functions. |
---|
825 | |
---|
826 | The following options control specific optimizations. The `-O2' |
---|
827 | option turns on all of these optimizations except `-funroll-loops' and |
---|
828 | `-funroll-all-loops'. On most machines, the `-O' option turns on the |
---|
829 | `-fthread-jumps' and `-fdelayed-branch' options, but specific machines |
---|
830 | may handle it differently. |
---|
831 | |
---|
832 | You can use the following flags in the rare cases when "fine-tuning" |
---|
833 | of optimizations to be performed is desired. |
---|
834 | |
---|
835 | `-fstrength-reduce' |
---|
836 | Perform the optimizations of loop strength reduction and |
---|
837 | elimination of iteration variables. |
---|
838 | |
---|
839 | `-fthread-jumps' |
---|
840 | Perform optimizations where we check to see if a jump branches to a |
---|
841 | location where another comparison subsumed by the first is found. |
---|
842 | If so, the first branch is redirected to either the destination of |
---|
843 | the second branch or a point immediately following it, depending |
---|
844 | on whether the condition is known to be true or false. |
---|
845 | |
---|
846 | `-fcse-follow-jumps' |
---|
847 | In common subexpression elimination, scan through jump instructions |
---|
848 | when the target of the jump is not reached by any other path. For |
---|
849 | example, when CSE encounters an `if' statement with an `else' |
---|
850 | clause, CSE will follow the jump when the condition tested is |
---|
851 | false. |
---|
852 | |
---|
853 | `-fcse-skip-blocks' |
---|
854 | This is similar to `-fcse-follow-jumps', but causes CSE to follow |
---|
855 | jumps which conditionally skip over blocks. When CSE encounters a |
---|
856 | simple `if' statement with no else clause, `-fcse-skip-blocks' |
---|
857 | causes CSE to follow the jump around the body of the `if'. |
---|
858 | |
---|
859 | `-frerun-cse-after-loop' |
---|
860 | Re-run common subexpression elimination after loop optimizations |
---|
861 | has been performed. |
---|
862 | |
---|
863 | `-fexpensive-optimizations' |
---|
864 | Perform a number of minor optimizations that are relatively |
---|
865 | expensive. |
---|
866 | |
---|
867 | `-fdelayed-branch' |
---|
868 | If supported for the target machine, attempt to reorder |
---|
869 | instructions to exploit instruction slots available after delayed |
---|
870 | branch instructions. |
---|
871 | |
---|
872 | `-fschedule-insns' |
---|
873 | If supported for the target machine, attempt to reorder |
---|
874 | instructions to eliminate execution stalls due to required data |
---|
875 | being unavailable. This helps machines that have slow floating |
---|
876 | point or memory load instructions by allowing other instructions |
---|
877 | to be issued until the result of the load or floating point |
---|
878 | instruction is required. |
---|
879 | |
---|
880 | `-fschedule-insns2' |
---|
881 | Similar to `-fschedule-insns', but requests an additional pass of |
---|
882 | instruction scheduling after register allocation has been done. |
---|
883 | This is especially useful on machines with a relatively small |
---|
884 | number of registers and where memory load instructions take more |
---|
885 | than one cycle. |
---|
886 | |
---|
887 | `-fcaller-saves' |
---|
888 | Enable values to be allocated in registers that will be clobbered |
---|
889 | by function calls, by emitting extra instructions to save and |
---|
890 | restore the registers around such calls. Such allocation is done |
---|
891 | only when it seems to result in better code than would otherwise |
---|
892 | be produced. |
---|
893 | |
---|
894 | This option is enabled by default on certain machines, usually |
---|
895 | those which have no call-preserved registers to use instead. |
---|
896 | |
---|
897 | `-funroll-loops' |
---|
898 | Perform the optimization of loop unrolling. This is only done for |
---|
899 | loops whose number of iterations can be determined at compile time |
---|
900 | or run time. `-funroll-loop' implies both `-fstrength-reduce' and |
---|
901 | `-frerun-cse-after-loop'. |
---|
902 | |
---|
903 | `-funroll-all-loops' |
---|
904 | Perform the optimization of loop unrolling. This is done for all |
---|
905 | loops and usually makes programs run more slowly. |
---|
906 | `-funroll-all-loops' implies `-fstrength-reduce' as well as |
---|
907 | `-frerun-cse-after-loop'. |
---|
908 | |
---|
909 | `-fno-peephole' |
---|
910 | Disable any machine-specific peephole optimizations. |
---|
911 | |
---|
912 | |
---|
913 | File: gcc.info, Node: Preprocessor Options, Next: Assembler Options, Prev: Optimize Options, Up: Invoking GCC |
---|
914 | |
---|
915 | Options Controlling the Preprocessor |
---|
916 | ==================================== |
---|
917 | |
---|
918 | These options control the C preprocessor, which is run on each C |
---|
919 | source file before actual compilation. |
---|
920 | |
---|
921 | If you use the `-E' option, nothing is done except preprocessing. |
---|
922 | Some of these options make sense only together with `-E' because they |
---|
923 | cause the preprocessor output to be unsuitable for actual compilation. |
---|
924 | |
---|
925 | `-include FILE' |
---|
926 | Process FILE as input before processing the regular input file. |
---|
927 | In effect, the contents of FILE are compiled first. Any `-D' and |
---|
928 | `-U' options on the command line are always processed before |
---|
929 | `-include FILE', regardless of the order in which they are |
---|
930 | written. All the `-include' and `-imacros' options are processed |
---|
931 | in the order in which they are written. |
---|
932 | |
---|
933 | `-imacros FILE' |
---|
934 | Process FILE as input, discarding the resulting output, before |
---|
935 | processing the regular input file. Because the output generated |
---|
936 | from FILE is discarded, the only effect of `-imacros FILE' is to |
---|
937 | make the macros defined in FILE available for use in the main |
---|
938 | input. |
---|
939 | |
---|
940 | Any `-D' and `-U' options on the command line are always processed |
---|
941 | before `-imacros FILE', regardless of the order in which they are |
---|
942 | written. All the `-include' and `-imacros' options are processed |
---|
943 | in the order in which they are written. |
---|
944 | |
---|
945 | `-idirafter DIR' |
---|
946 | Add the directory DIR to the second include path. The directories |
---|
947 | on the second include path are searched when a header file is not |
---|
948 | found in any of the directories in the main include path (the one |
---|
949 | that `-I' adds to). |
---|
950 | |
---|
951 | `-iprefix PREFIX' |
---|
952 | Specify PREFIX as the prefix for subsequent `-iwithprefix' options. |
---|
953 | |
---|
954 | `-iwithprefix DIR' |
---|
955 | Add a directory to the second include path. The directory's name |
---|
956 | is made by concatenating PREFIX and DIR, where PREFIX was |
---|
957 | specified previously with `-iprefix'. If you have not specified a |
---|
958 | prefix yet, the directory containing the installed passes of the |
---|
959 | compiler is used as the default. |
---|
960 | |
---|
961 | `-iwithprefixbefore DIR' |
---|
962 | Add a directory to the main include path. The directory's name is |
---|
963 | made by concatenating PREFIX and DIR, as in the case of |
---|
964 | `-iwithprefix'. |
---|
965 | |
---|
966 | `-isystem DIR' |
---|
967 | Add a directory to the beginning of the second include path, |
---|
968 | marking it as a system directory, so that it gets the same special |
---|
969 | treatment as is applied to the standard system directories. |
---|
970 | |
---|
971 | `-nostdinc' |
---|
972 | Do not search the standard system directories for header files. |
---|
973 | Only the directories you have specified with `-I' options (and the |
---|
974 | current directory, if appropriate) are searched. *Note Directory |
---|
975 | Options::, for information on `-I'. |
---|
976 | |
---|
977 | By using both `-nostdinc' and `-I-', you can limit the include-file |
---|
978 | search path to only those directories you specify explicitly. |
---|
979 | |
---|
980 | `-undef' |
---|
981 | Do not predefine any nonstandard macros. (Including architecture |
---|
982 | flags). |
---|
983 | |
---|
984 | `-E' |
---|
985 | Run only the C preprocessor. Preprocess all the C source files |
---|
986 | specified and output the results to standard output or to the |
---|
987 | specified output file. |
---|
988 | |
---|
989 | `-C' |
---|
990 | Tell the preprocessor not to discard comments. Used with the `-E' |
---|
991 | option. |
---|
992 | |
---|
993 | `-P' |
---|
994 | Tell the preprocessor not to generate `#line' directives. Used |
---|
995 | with the `-E' option. |
---|
996 | |
---|
997 | `-M' |
---|
998 | Tell the preprocessor to output a rule suitable for `make' |
---|
999 | describing the dependencies of each object file. For each source |
---|
1000 | file, the preprocessor outputs one `make'-rule whose target is the |
---|
1001 | object file name for that source file and whose dependencies are |
---|
1002 | all the `#include' header files it uses. This rule may be a |
---|
1003 | single line or may be continued with `\'-newline if it is long. |
---|
1004 | The list of rules is printed on standard output instead of the |
---|
1005 | preprocessed C program. |
---|
1006 | |
---|
1007 | `-M' implies `-E'. |
---|
1008 | |
---|
1009 | Another way to specify output of a `make' rule is by setting the |
---|
1010 | environment variable `DEPENDENCIES_OUTPUT' (*note Environment |
---|
1011 | Variables::.). |
---|
1012 | |
---|
1013 | `-MM' |
---|
1014 | Like `-M' but the output mentions only the user header files |
---|
1015 | included with `#include "FILE"'. System header files included |
---|
1016 | with `#include <FILE>' are omitted. |
---|
1017 | |
---|
1018 | `-MD' |
---|
1019 | Like `-M' but the dependency information is written to a file made |
---|
1020 | by replacing ".c" with ".d" at the end of the input file names. |
---|
1021 | This is in addition to compiling the file as specified--`-MD' does |
---|
1022 | not inhibit ordinary compilation the way `-M' does. |
---|
1023 | |
---|
1024 | In Mach, you can use the utility `md' to merge multiple dependency |
---|
1025 | files into a single dependency file suitable for using with the |
---|
1026 | `make' command. |
---|
1027 | |
---|
1028 | `-MMD' |
---|
1029 | Like `-MD' except mention only user header files, not system |
---|
1030 | header files. |
---|
1031 | |
---|
1032 | `-MG' |
---|
1033 | Treat missing header files as generated files and assume they live |
---|
1034 | in the same directory as the source file. If you specify `-MG', |
---|
1035 | you must also specify either `-M' or `-MM'. `-MG' is not |
---|
1036 | supported with `-MD' or `-MMD'. |
---|
1037 | |
---|
1038 | `-H' |
---|
1039 | Print the name of each header file used, in addition to other |
---|
1040 | normal activities. |
---|
1041 | |
---|
1042 | `-AQUESTION(ANSWER)' |
---|
1043 | Assert the answer ANSWER for QUESTION, in case it is tested with a |
---|
1044 | preprocessing conditional such as `#if #QUESTION(ANSWER)'. `-A-' |
---|
1045 | disables the standard assertions that normally describe the target |
---|
1046 | machine. |
---|
1047 | |
---|
1048 | `-DMACRO' |
---|
1049 | Define macro MACRO with the string `1' as its definition. |
---|
1050 | |
---|
1051 | `-DMACRO=DEFN' |
---|
1052 | Define macro MACRO as DEFN. All instances of `-D' on the command |
---|
1053 | line are processed before any `-U' options. |
---|
1054 | |
---|
1055 | `-UMACRO' |
---|
1056 | Undefine macro MACRO. `-U' options are evaluated after all `-D' |
---|
1057 | options, but before any `-include' and `-imacros' options. |
---|
1058 | |
---|
1059 | `-dM' |
---|
1060 | Tell the preprocessor to output only a list of the macro |
---|
1061 | definitions that are in effect at the end of preprocessing. Used |
---|
1062 | with the `-E' option. |
---|
1063 | |
---|
1064 | `-dD' |
---|
1065 | Tell the preprocessing to pass all macro definitions into the |
---|
1066 | output, in their proper sequence in the rest of the output. |
---|
1067 | |
---|
1068 | `-dN' |
---|
1069 | Like `-dD' except that the macro arguments and contents are |
---|
1070 | omitted. Only `#define NAME' is included in the output. |
---|
1071 | |
---|
1072 | `-trigraphs' |
---|
1073 | Support ANSI C trigraphs. The `-ansi' option also has this effect. |
---|
1074 | |
---|
1075 | `-Wp,OPTION' |
---|
1076 | Pass OPTION as an option to the preprocessor. If OPTION contains |
---|
1077 | commas, it is split into multiple options at the commas. |
---|
1078 | |
---|
1079 | |
---|
1080 | File: gcc.info, Node: Assembler Options, Next: Link Options, Prev: Preprocessor Options, Up: Invoking GCC |
---|
1081 | |
---|
1082 | Passing Options to the Assembler |
---|
1083 | ================================ |
---|
1084 | |
---|
1085 | You can pass options to the assembler. |
---|
1086 | |
---|
1087 | `-Wa,OPTION' |
---|
1088 | Pass OPTION as an option to the assembler. If OPTION contains |
---|
1089 | commas, it is split into multiple options at the commas. |
---|
1090 | |
---|
1091 | |
---|
1092 | File: gcc.info, Node: Link Options, Next: Directory Options, Prev: Assembler Options, Up: Invoking GCC |
---|
1093 | |
---|
1094 | Options for Linking |
---|
1095 | =================== |
---|
1096 | |
---|
1097 | These options come into play when the compiler links object files |
---|
1098 | into an executable output file. They are meaningless if the compiler is |
---|
1099 | not doing a link step. |
---|
1100 | |
---|
1101 | `OBJECT-FILE-NAME' |
---|
1102 | A file name that does not end in a special recognized suffix is |
---|
1103 | considered to name an object file or library. (Object files are |
---|
1104 | distinguished from libraries by the linker according to the file |
---|
1105 | contents.) If linking is done, these object files are used as |
---|
1106 | input to the linker. |
---|
1107 | |
---|
1108 | `-c' |
---|
1109 | `-S' |
---|
1110 | `-E' |
---|
1111 | If any of these options is used, then the linker is not run, and |
---|
1112 | object file names should not be used as arguments. *Note Overall |
---|
1113 | Options::. |
---|
1114 | |
---|
1115 | `-lLIBRARY' |
---|
1116 | Search the library named LIBRARY when linking. |
---|
1117 | |
---|
1118 | It makes a difference where in the command you write this option; |
---|
1119 | the linker searches processes libraries and object files in the |
---|
1120 | order they are specified. Thus, `foo.o -lz bar.o' searches |
---|
1121 | library `z' after file `foo.o' but before `bar.o'. If `bar.o' |
---|
1122 | refers to functions in `z', those functions may not be loaded. |
---|
1123 | |
---|
1124 | The linker searches a standard list of directories for the library, |
---|
1125 | which is actually a file named `libLIBRARY.a'. The linker then |
---|
1126 | uses this file as if it had been specified precisely by name. |
---|
1127 | |
---|
1128 | The directories searched include several standard system |
---|
1129 | directories plus any that you specify with `-L'. |
---|
1130 | |
---|
1131 | Normally the files found this way are library files--archive files |
---|
1132 | whose members are object files. The linker handles an archive |
---|
1133 | file by scanning through it for members which define symbols that |
---|
1134 | have so far been referenced but not defined. But if the file that |
---|
1135 | is found is an ordinary object file, it is linked in the usual |
---|
1136 | fashion. The only difference between using an `-l' option and |
---|
1137 | specifying a file name is that `-l' surrounds LIBRARY with `lib' |
---|
1138 | and `.a' and searches several directories. |
---|
1139 | |
---|
1140 | `-lobjc' |
---|
1141 | You need this special case of the `-l' option in order to link an |
---|
1142 | Objective C program. |
---|
1143 | |
---|
1144 | `-nostartfiles' |
---|
1145 | Do not use the standard system startup files when linking. The |
---|
1146 | standard system libraries are used normally, unless `-nostdlib' or |
---|
1147 | `-nodefaultlibs' is used. |
---|
1148 | |
---|
1149 | `-nodefaultlibs' |
---|
1150 | Do not use the standard system libraries when linking. Only the |
---|
1151 | libraries you specify will be passed to the linker. The standard |
---|
1152 | startup files are used normally, unless `-nostartfiles' is used. |
---|
1153 | |
---|
1154 | `-nostdlib' |
---|
1155 | Do not use the standard system startup files or libraries when |
---|
1156 | linking. No startup files and only the libraries you specify will |
---|
1157 | be passed to the linker. |
---|
1158 | |
---|
1159 | One of the standard libraries bypassed by `-nostdlib' and |
---|
1160 | `-nodefaultlibs' is `libgcc.a', a library of internal subroutines |
---|
1161 | that GNU CC uses to overcome shortcomings of particular machines, |
---|
1162 | or special needs for some languages. (*Note Interfacing to GNU CC |
---|
1163 | Output: Interface, for more discussion of `libgcc.a'.) In most |
---|
1164 | cases, you need `libgcc.a' even when you want to avoid other |
---|
1165 | standard libraries. In other words, when you specify `-nostdlib' |
---|
1166 | or `-nodefaultlibs' you should usually specify `-lgcc' as well. |
---|
1167 | This ensures that you have no unresolved references to internal |
---|
1168 | GNU CC library subroutines. (For example, `__main', used to |
---|
1169 | ensure C++ constructors will be called; *note `collect2': |
---|
1170 | Collect2..) |
---|
1171 | |
---|
1172 | `-s' |
---|
1173 | Remove all symbol table and relocation information from the |
---|
1174 | executable. |
---|
1175 | |
---|
1176 | `-static' |
---|
1177 | On systems that support dynamic linking, this prevents linking |
---|
1178 | with the shared libraries. On other systems, this option has no |
---|
1179 | effect. |
---|
1180 | |
---|
1181 | `-shared' |
---|
1182 | Produce a shared object which can then be linked with other |
---|
1183 | objects to form an executable. Only a few systems support this |
---|
1184 | option. |
---|
1185 | |
---|
1186 | `-symbolic' |
---|
1187 | Bind references to global symbols when building a shared object. |
---|
1188 | Warn about any unresolved references (unless overridden by the |
---|
1189 | link editor option `-Xlinker -z -Xlinker defs'). Only a few |
---|
1190 | systems support this option. |
---|
1191 | |
---|
1192 | `-Xlinker OPTION' |
---|
1193 | Pass OPTION as an option to the linker. You can use this to |
---|
1194 | supply system-specific linker options which GNU CC does not know |
---|
1195 | how to recognize. |
---|
1196 | |
---|
1197 | If you want to pass an option that takes an argument, you must use |
---|
1198 | `-Xlinker' twice, once for the option and once for the argument. |
---|
1199 | For example, to pass `-assert definitions', you must write |
---|
1200 | `-Xlinker -assert -Xlinker definitions'. It does not work to write |
---|
1201 | `-Xlinker "-assert definitions"', because this passes the entire |
---|
1202 | string as a single argument, which is not what the linker expects. |
---|
1203 | |
---|
1204 | `-Wl,OPTION' |
---|
1205 | Pass OPTION as an option to the linker. If OPTION contains |
---|
1206 | commas, it is split into multiple options at the commas. |
---|
1207 | |
---|
1208 | `-u SYMBOL' |
---|
1209 | Pretend the symbol SYMBOL is undefined, to force linking of |
---|
1210 | library modules to define it. You can use `-u' multiple times with |
---|
1211 | different symbols to force loading of additional library modules. |
---|
1212 | |
---|