[8833] | 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 | |
---|