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