1 | This is Info file gcc.info, produced by Makeinfo version 1.67 from the |
---|
2 | input 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, 1996, 1997, 1998 |
---|
10 | Free Software 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: DEC Alpha Options, Next: Clipper Options, Prev: Intel 960 Options, Up: Submodel Options |
---|
34 | |
---|
35 | DEC Alpha Options |
---|
36 | ----------------- |
---|
37 | |
---|
38 | These `-m' options are defined for the DEC Alpha implementations: |
---|
39 | |
---|
40 | `-mno-soft-float' |
---|
41 | `-msoft-float' |
---|
42 | Use (do not use) the hardware floating-point instructions for |
---|
43 | floating-point operations. When `-msoft-float' is specified, |
---|
44 | functions in `libgcc1.c' will be used to perform floating-point |
---|
45 | operations. Unless they are replaced by routines that emulate the |
---|
46 | floating-point operations, or compiled in such a way as to call |
---|
47 | such emulations routines, these routines will issue floating-point |
---|
48 | operations. If you are compiling for an Alpha without |
---|
49 | floating-point operations, you must ensure that the library is |
---|
50 | built so as not to call them. |
---|
51 | |
---|
52 | Note that Alpha implementations without floating-point operations |
---|
53 | are required to have floating-point registers. |
---|
54 | |
---|
55 | `-mfp-reg' |
---|
56 | `-mno-fp-regs' |
---|
57 | Generate code that uses (does not use) the floating-point register |
---|
58 | set. `-mno-fp-regs' implies `-msoft-float'. If the floating-point |
---|
59 | register set is not used, floating point operands are passed in |
---|
60 | integer registers as if they were integers and floating-point |
---|
61 | results are passed in $0 instead of $f0. This is a non-standard |
---|
62 | calling sequence, so any function with a floating-point argument |
---|
63 | or return value called by code compiled with `-mno-fp-regs' must |
---|
64 | also be compiled with that option. |
---|
65 | |
---|
66 | A typical use of this option is building a kernel that does not |
---|
67 | use, and hence need not save and restore, any floating-point |
---|
68 | registers. |
---|
69 | |
---|
70 | `-mieee' |
---|
71 | The Alpha architecture implements floating-point hardware |
---|
72 | optimized for maximum performance. It is mostly compliant with |
---|
73 | the IEEE floating point standard. However, for full compliance, |
---|
74 | software assistance is required. This option generates code fully |
---|
75 | IEEE compliant code *except* that the INEXACT FLAG is not |
---|
76 | maintained (see below). If this option is turned on, the CPP |
---|
77 | macro `_IEEE_FP' is defined during compilation. The option is a |
---|
78 | shorthand for: `-D_IEEE_FP -mfp-trap-mode=su -mtrap-precision=i |
---|
79 | -mieee-conformant'. The resulting code is less efficient but is |
---|
80 | able to correctly support denormalized numbers and exceptional |
---|
81 | IEEE values such as not-a-number and plus/minus infinity. Other |
---|
82 | Alpha compilers call this option `-ieee_with_no_inexact'. |
---|
83 | |
---|
84 | `-mieee-with-inexact' |
---|
85 | This is like `-mieee' except the generated code also maintains the |
---|
86 | IEEE INEXACT FLAG. Turning on this option causes the generated |
---|
87 | code to implement fully-compliant IEEE math. The option is a |
---|
88 | shorthand for `-D_IEEE_FP -D_IEEE_FP_INEXACT' plus the three |
---|
89 | following: `-mieee-conformant', `-mfp-trap-mode=sui', and |
---|
90 | `-mtrap-precision=i'. On some Alpha implementations the resulting |
---|
91 | code may execute significantly slower than the code generated by |
---|
92 | default. Since there is very little code that depends on the |
---|
93 | INEXACT FLAG, you should normally not specify this option. Other |
---|
94 | Alpha compilers call this option `-ieee_with_inexact'. |
---|
95 | |
---|
96 | `-mfp-trap-mode=TRAP MODE' |
---|
97 | This option controls what floating-point related traps are enabled. |
---|
98 | Other Alpha compilers call this option `-fptm 'TRAP MODE. The |
---|
99 | trap mode can be set to one of four values: |
---|
100 | |
---|
101 | `n' |
---|
102 | This is the default (normal) setting. The only traps that |
---|
103 | are enabled are the ones that cannot be disabled in software |
---|
104 | (e.g., division by zero trap). |
---|
105 | |
---|
106 | `u' |
---|
107 | In addition to the traps enabled by `n', underflow traps are |
---|
108 | enabled as well. |
---|
109 | |
---|
110 | `su' |
---|
111 | Like `su', but the instructions are marked to be safe for |
---|
112 | software completion (see Alpha architecture manual for |
---|
113 | details). |
---|
114 | |
---|
115 | `sui' |
---|
116 | Like `su', but inexact traps are enabled as well. |
---|
117 | |
---|
118 | `-mfp-rounding-mode=ROUNDING MODE' |
---|
119 | Selects the IEEE rounding mode. Other Alpha compilers call this |
---|
120 | option `-fprm 'ROUNDING MODE. The ROUNDING MODE can be one of: |
---|
121 | |
---|
122 | `n' |
---|
123 | Normal IEEE rounding mode. Floating point numbers are |
---|
124 | rounded towards the nearest machine number or towards the |
---|
125 | even machine number in case of a tie. |
---|
126 | |
---|
127 | `m' |
---|
128 | Round towards minus infinity. |
---|
129 | |
---|
130 | `c' |
---|
131 | Chopped rounding mode. Floating point numbers are rounded |
---|
132 | towards zero. |
---|
133 | |
---|
134 | `d' |
---|
135 | Dynamic rounding mode. A field in the floating point control |
---|
136 | register (FPCR, see Alpha architecture reference manual) |
---|
137 | controls the rounding mode in effect. The C library |
---|
138 | initializes this register for rounding towards plus infinity. |
---|
139 | Thus, unless your program modifies the FPCR, `d' corresponds |
---|
140 | to round towards plus infinity. |
---|
141 | |
---|
142 | `-mtrap-precision=TRAP PRECISION' |
---|
143 | In the Alpha architecture, floating point traps are imprecise. |
---|
144 | This means without software assistance it is impossible to recover |
---|
145 | from a floating trap and program execution normally needs to be |
---|
146 | terminated. GNU CC can generate code that can assist operating |
---|
147 | system trap handlers in determining the exact location that caused |
---|
148 | a floating point trap. Depending on the requirements of an |
---|
149 | application, different levels of precisions can be selected: |
---|
150 | |
---|
151 | `p' |
---|
152 | Program precision. This option is the default and means a |
---|
153 | trap handler can only identify which program caused a |
---|
154 | floating point exception. |
---|
155 | |
---|
156 | `f' |
---|
157 | Function precision. The trap handler can determine the |
---|
158 | function that caused a floating point exception. |
---|
159 | |
---|
160 | `i' |
---|
161 | Instruction precision. The trap handler can determine the |
---|
162 | exact instruction that caused a floating point exception. |
---|
163 | |
---|
164 | Other Alpha compilers provide the equivalent options called |
---|
165 | `-scope_safe' and `-resumption_safe'. |
---|
166 | |
---|
167 | `-mieee-conformant' |
---|
168 | This option marks the generated code as IEEE conformant. You must |
---|
169 | not use this option unless you also specify `-mtrap-precision=i' |
---|
170 | and either `-mfp-trap-mode=su' or `-mfp-trap-mode=sui'. Its only |
---|
171 | effect is to emit the line `.eflag 48' in the function prologue of |
---|
172 | the generated assembly file. Under DEC Unix, this has the effect |
---|
173 | that IEEE-conformant math library routines will be linked in. |
---|
174 | |
---|
175 | `-mbuild-constants' |
---|
176 | Normally GNU CC examines a 32- or 64-bit integer constant to see |
---|
177 | if it can construct it from smaller constants in two or three |
---|
178 | instructions. If it cannot, it will output the constant as a |
---|
179 | literal and generate code to load it from the data segment at |
---|
180 | runtime. |
---|
181 | |
---|
182 | Use this option to require GNU CC to construct *all* integer |
---|
183 | constants using code, even if it takes more instructions (the |
---|
184 | maximum is six). |
---|
185 | |
---|
186 | You would typically use this option to build a shared library |
---|
187 | dynamic loader. Itself a shared library, it must relocate itself |
---|
188 | in memory before it can find the variables and constants in its |
---|
189 | own data segment. |
---|
190 | |
---|
191 | `-malpha-as' |
---|
192 | `-mgas' |
---|
193 | Select whether to generate code to be assembled by the |
---|
194 | vendor-supplied assembler (`-malpha-as') or by the GNU assembler |
---|
195 | `-mgas'. |
---|
196 | |
---|
197 | `-mbwx' |
---|
198 | `-mno-bwx' |
---|
199 | `-mcix' |
---|
200 | `-mno-cix' |
---|
201 | `-mmax' |
---|
202 | `-mno-max' |
---|
203 | Indicate whether GNU CC should generate code to use the optional |
---|
204 | BWX, CIX, and MAX instruction sets. The default is to use the |
---|
205 | instruction sets supported by the CPU type specified via `-mcpu=' |
---|
206 | option or that of the CPU on which GNU CC was built if none was |
---|
207 | specified. |
---|
208 | |
---|
209 | `-mcpu=CPU_TYPE' |
---|
210 | Set the instruction set, register set, and instruction scheduling |
---|
211 | parameters for machine type CPU_TYPE. You can specify either the |
---|
212 | `EV' style name or the corresponding chip number. GNU CC supports |
---|
213 | scheduling parameters for the EV4 and EV5 family of processors and |
---|
214 | will choose the default values for the instruction set from the |
---|
215 | processor you specify. If you do not specify a processor type, |
---|
216 | GNU CC will default to the processor on which the compiler was |
---|
217 | built. |
---|
218 | |
---|
219 | Supported values for CPU_TYPE are |
---|
220 | |
---|
221 | `ev4' |
---|
222 | `21064' |
---|
223 | Schedules as an EV4 and has no instruction set extensions. |
---|
224 | |
---|
225 | `ev5' |
---|
226 | `21164' |
---|
227 | Schedules as an EV5 and has no instruction set extensions. |
---|
228 | |
---|
229 | `ev56' |
---|
230 | `21164a' |
---|
231 | Schedules as an EV5 and supports the BWX extension. |
---|
232 | |
---|
233 | `pca56' |
---|
234 | `21164PC' |
---|
235 | Schedules as an EV5 and supports the BWX and MAX extensions. |
---|
236 | |
---|
237 | `ev6' |
---|
238 | `21264' |
---|
239 | Schedules as an EV5 (until Digital releases the scheduling |
---|
240 | parameters for the EV6) and supports the BWX, CIX, and MAX |
---|
241 | extensions. |
---|
242 | |
---|
243 | |
---|
244 | File: gcc.info, Node: Clipper Options, Next: H8/300 Options, Prev: DEC Alpha Options, Up: Submodel Options |
---|
245 | |
---|
246 | Clipper Options |
---|
247 | --------------- |
---|
248 | |
---|
249 | These `-m' options are defined for the Clipper implementations: |
---|
250 | |
---|
251 | `-mc300' |
---|
252 | Produce code for a C300 Clipper processor. This is the default. |
---|
253 | |
---|
254 | `-mc400' |
---|
255 | Produce code for a C400 Clipper processor i.e. use floating point |
---|
256 | registers f8..f15. |
---|
257 | |
---|
258 | |
---|
259 | File: gcc.info, Node: H8/300 Options, Next: SH Options, Prev: Clipper Options, Up: Submodel Options |
---|
260 | |
---|
261 | H8/300 Options |
---|
262 | -------------- |
---|
263 | |
---|
264 | These `-m' options are defined for the H8/300 implementations: |
---|
265 | |
---|
266 | `-mrelax' |
---|
267 | Shorten some address references at link time, when possible; uses |
---|
268 | the linker option `-relax'. *Note `ld' and the H8/300: |
---|
269 | (ld.info)H8/300, for a fuller description. |
---|
270 | |
---|
271 | `-mh' |
---|
272 | Generate code for the H8/300H. |
---|
273 | |
---|
274 | `-ms' |
---|
275 | Generate code for the H8/S. |
---|
276 | |
---|
277 | `-mint32' |
---|
278 | Make `int' data 32 bits by default. |
---|
279 | |
---|
280 | `-malign-300' |
---|
281 | On the h8/300h, use the same alignment rules as for the h8/300. |
---|
282 | The default for the h8/300h is to align longs and floats on 4 byte |
---|
283 | boundaries. `-malign-300' causes them to be aligned on 2 byte |
---|
284 | boundaries. This option has no effect on the h8/300. |
---|
285 | |
---|
286 | |
---|
287 | File: gcc.info, Node: SH Options, Next: System V Options, Prev: H8/300 Options, Up: Submodel Options |
---|
288 | |
---|
289 | SH Options |
---|
290 | ---------- |
---|
291 | |
---|
292 | These `-m' options are defined for the SH implementations: |
---|
293 | |
---|
294 | `-m1' |
---|
295 | Generate code for the SH1. |
---|
296 | |
---|
297 | `-m2' |
---|
298 | Generate code for the SH2. |
---|
299 | |
---|
300 | `-m3' |
---|
301 | Generate code for the SH3. |
---|
302 | |
---|
303 | `-m3e' |
---|
304 | Generate code for the SH3e. |
---|
305 | |
---|
306 | `-mb' |
---|
307 | Compile code for the processor in big endian mode. |
---|
308 | |
---|
309 | `-ml' |
---|
310 | Compile code for the processor in little endian mode. |
---|
311 | |
---|
312 | `-mrelax' |
---|
313 | Shorten some address references at link time, when possible; uses |
---|
314 | the linker option `-relax'. |
---|
315 | |
---|
316 | |
---|
317 | File: gcc.info, Node: System V Options, Next: V850 Options, Prev: SH Options, Up: Submodel Options |
---|
318 | |
---|
319 | Options for System V |
---|
320 | -------------------- |
---|
321 | |
---|
322 | These additional options are available on System V Release 4 for |
---|
323 | compatibility with other compilers on those systems: |
---|
324 | |
---|
325 | `-G' |
---|
326 | Create a shared object. It is recommended that `-symbolic' or |
---|
327 | `-shared' be used instead. |
---|
328 | |
---|
329 | `-Qy' |
---|
330 | Identify the versions of each tool used by the compiler, in a |
---|
331 | `.ident' assembler directive in the output. |
---|
332 | |
---|
333 | `-Qn' |
---|
334 | Refrain from adding `.ident' directives to the output file (this is |
---|
335 | the default). |
---|
336 | |
---|
337 | `-YP,DIRS' |
---|
338 | Search the directories DIRS, and no others, for libraries |
---|
339 | specified with `-l'. |
---|
340 | |
---|
341 | `-Ym,DIR' |
---|
342 | Look in the directory DIR to find the M4 preprocessor. The |
---|
343 | assembler uses this option. |
---|
344 | |
---|
345 | |
---|
346 | File: gcc.info, Node: V850 Options, Prev: System V Options, Up: Submodel Options |
---|
347 | |
---|
348 | V850 Options |
---|
349 | ------------ |
---|
350 | |
---|
351 | These `-m' options are defined for V850 implementations: |
---|
352 | |
---|
353 | `-mlong-calls' |
---|
354 | `-mno-long-calls' |
---|
355 | Treat all calls as being far away (near). If calls are assumed to |
---|
356 | be far away, the compiler will always load the functions address |
---|
357 | up into a register, and call indirect through the pointer. |
---|
358 | |
---|
359 | `-mno-ep' |
---|
360 | `-mep' |
---|
361 | Do not optimize (do optimize) basic blocks that use the same index |
---|
362 | pointer 4 or more times to copy pointer into the `ep' register, and |
---|
363 | use the shorter `sld' and `sst' instructions. The `-mep' option |
---|
364 | is on by default if you optimize. |
---|
365 | |
---|
366 | `-mno-prolog-function' |
---|
367 | `-mprolog-function' |
---|
368 | Do not use (do use) external functions to save and restore |
---|
369 | registers at the prolog and epilog of a function. The external |
---|
370 | functions are slower, but use less code space if more than one |
---|
371 | function saves the same number of registers. The |
---|
372 | `-mprolog-function' option is on by default if you optimize. |
---|
373 | |
---|
374 | `-mspace' |
---|
375 | Try to make the code as small as possible. At present, this just |
---|
376 | turns on the `-mep' and `-mprolog-function' options. |
---|
377 | |
---|
378 | `-mtda=N' |
---|
379 | Put static or global variables whose size is N bytes or less into |
---|
380 | the tiny data area that register `ep' points to. The tiny data |
---|
381 | area can hold up to 256 bytes in total (128 bytes for byte |
---|
382 | references). |
---|
383 | |
---|
384 | `-msda=N' |
---|
385 | Put static or global variables whose size is N bytes or less into |
---|
386 | the small data area that register `gp' points to. The small data |
---|
387 | area can hold up to 64 kilobytes. |
---|
388 | |
---|
389 | `-mzda=N' |
---|
390 | Put static or global variables whose size is N bytes or less into |
---|
391 | the first 32 kilobytes of memory. |
---|
392 | |
---|
393 | `-mv850' |
---|
394 | Specify that the target processor is the V850. |
---|
395 | |
---|
396 | `-mbig-switch' |
---|
397 | Generate code suitable for big switch tables. Use this option |
---|
398 | only if the assembler/linker complain about out of range branches |
---|
399 | within a switch table. |
---|
400 | |
---|
401 | |
---|
402 | File: gcc.info, Node: Code Gen Options, Next: Environment Variables, Prev: Submodel Options, Up: Invoking GCC |
---|
403 | |
---|
404 | Options for Code Generation Conventions |
---|
405 | ======================================= |
---|
406 | |
---|
407 | These machine-independent options control the interface conventions |
---|
408 | used in code generation. |
---|
409 | |
---|
410 | Most of them have both positive and negative forms; the negative form |
---|
411 | of `-ffoo' would be `-fno-foo'. In the table below, only one of the |
---|
412 | forms is listed--the one which is not the default. You can figure out |
---|
413 | the other form by either removing `no-' or adding it. |
---|
414 | |
---|
415 | `-fexceptions' |
---|
416 | Enable exception handling, and generate extra code needed to |
---|
417 | propagate exceptions. If you do not specify this option, GNU CC |
---|
418 | enables it by default for languages like C++ that normally require |
---|
419 | exception handling, and disabled for languages like C that do not |
---|
420 | normally require it. However, when compiling C code that needs to |
---|
421 | interoperate properly with exception handlers written in C++, you |
---|
422 | may need to enable this option. You may also wish to disable this |
---|
423 | option is you are compiling older C++ programs that don't use |
---|
424 | exception handling. |
---|
425 | |
---|
426 | `-fpcc-struct-return' |
---|
427 | Return "short" `struct' and `union' values in memory like longer |
---|
428 | ones, rather than in registers. This convention is less |
---|
429 | efficient, but it has the advantage of allowing intercallability |
---|
430 | between GNU CC-compiled files and files compiled with other |
---|
431 | compilers. |
---|
432 | |
---|
433 | The precise convention for returning structures in memory depends |
---|
434 | on the target configuration macros. |
---|
435 | |
---|
436 | Short structures and unions are those whose size and alignment |
---|
437 | match that of some integer type. |
---|
438 | |
---|
439 | `-freg-struct-return' |
---|
440 | Use the convention that `struct' and `union' values are returned |
---|
441 | in registers when possible. This is more efficient for small |
---|
442 | structures than `-fpcc-struct-return'. |
---|
443 | |
---|
444 | If you specify neither `-fpcc-struct-return' nor its contrary |
---|
445 | `-freg-struct-return', GNU CC defaults to whichever convention is |
---|
446 | standard for the target. If there is no standard convention, GNU |
---|
447 | CC defaults to `-fpcc-struct-return', except on targets where GNU |
---|
448 | CC is the principal compiler. In those cases, we can choose the |
---|
449 | standard, and we chose the more efficient register return |
---|
450 | alternative. |
---|
451 | |
---|
452 | `-fshort-enums' |
---|
453 | Allocate to an `enum' type only as many bytes as it needs for the |
---|
454 | declared range of possible values. Specifically, the `enum' type |
---|
455 | will be equivalent to the smallest integer type which has enough |
---|
456 | room. |
---|
457 | |
---|
458 | `-fshort-double' |
---|
459 | Use the same size for `double' as for `float'. |
---|
460 | |
---|
461 | `-fshared-data' |
---|
462 | Requests that the data and non-`const' variables of this |
---|
463 | compilation be shared data rather than private data. The |
---|
464 | distinction makes sense only on certain operating systems, where |
---|
465 | shared data is shared between processes running the same program, |
---|
466 | while private data exists in one copy per process. |
---|
467 | |
---|
468 | `-fno-common' |
---|
469 | Allocate even uninitialized global variables in the bss section of |
---|
470 | the object file, rather than generating them as common blocks. |
---|
471 | This has the effect that if the same variable is declared (without |
---|
472 | `extern') in two different compilations, you will get an error |
---|
473 | when you link them. The only reason this might be useful is if |
---|
474 | you wish to verify that the program will work on other systems |
---|
475 | which always work this way. |
---|
476 | |
---|
477 | `-fno-ident' |
---|
478 | Ignore the `#ident' directive. |
---|
479 | |
---|
480 | `-fno-gnu-linker' |
---|
481 | Do not output global initializations (such as C++ constructors and |
---|
482 | destructors) in the form used by the GNU linker (on systems where |
---|
483 | the GNU linker is the standard method of handling them). Use this |
---|
484 | option when you want to use a non-GNU linker, which also requires |
---|
485 | using the `collect2' program to make sure the system linker |
---|
486 | includes constructors and destructors. (`collect2' is included in |
---|
487 | the GNU CC distribution.) For systems which *must* use |
---|
488 | `collect2', the compiler driver `gcc' is configured to do this |
---|
489 | automatically. |
---|
490 | |
---|
491 | `-finhibit-size-directive' |
---|
492 | Don't output a `.size' assembler directive, or anything else that |
---|
493 | would cause trouble if the function is split in the middle, and the |
---|
494 | two halves are placed at locations far apart in memory. This |
---|
495 | option is used when compiling `crtstuff.c'; you should not need to |
---|
496 | use it for anything else. |
---|
497 | |
---|
498 | `-fverbose-asm' |
---|
499 | Put extra commentary information in the generated assembly code to |
---|
500 | make it more readable. This option is generally only of use to |
---|
501 | those who actually need to read the generated assembly code |
---|
502 | (perhaps while debugging the compiler itself). |
---|
503 | |
---|
504 | `-fno-verbose-asm', the default, causes the extra information to |
---|
505 | be omitted and is useful when comparing two assembler files. |
---|
506 | |
---|
507 | `-fvolatile' |
---|
508 | Consider all memory references through pointers to be volatile. |
---|
509 | |
---|
510 | `-fvolatile-global' |
---|
511 | Consider all memory references to extern and global data items to |
---|
512 | be volatile. |
---|
513 | |
---|
514 | `-fpic' |
---|
515 | Generate position-independent code (PIC) suitable for use in a |
---|
516 | shared library, if supported for the target machine. Such code |
---|
517 | accesses all constant addresses through a global offset table |
---|
518 | (GOT). The dynamic loader resolves the GOT entries when the |
---|
519 | program starts (the dynamic loader is not part of GNU CC; it is |
---|
520 | part of the operating system). If the GOT size for the linked |
---|
521 | executable exceeds a machine-specific maximum size, you get an |
---|
522 | error message from the linker indicating that `-fpic' does not |
---|
523 | work; in that case, recompile with `-fPIC' instead. (These |
---|
524 | maximums are 16k on the m88k, 8k on the Sparc, and 32k on the m68k |
---|
525 | and RS/6000. The 386 has no such limit.) |
---|
526 | |
---|
527 | Position-independent code requires special support, and therefore |
---|
528 | works only on certain machines. For the 386, GNU CC supports PIC |
---|
529 | for System V but not for the Sun 386i. Code generated for the IBM |
---|
530 | RS/6000 is always position-independent. |
---|
531 | |
---|
532 | `-fPIC' |
---|
533 | If supported for the target machine, emit position-independent |
---|
534 | code, suitable for dynamic linking and avoiding any limit on the |
---|
535 | size of the global offset table. This option makes a difference |
---|
536 | on the m68k, m88k, and the Sparc. |
---|
537 | |
---|
538 | Position-independent code requires special support, and therefore |
---|
539 | works only on certain machines. |
---|
540 | |
---|
541 | `-ffixed-REG' |
---|
542 | Treat the register named REG as a fixed register; generated code |
---|
543 | should never refer to it (except perhaps as a stack pointer, frame |
---|
544 | pointer or in some other fixed role). |
---|
545 | |
---|
546 | REG must be the name of a register. The register names accepted |
---|
547 | are machine-specific and are defined in the `REGISTER_NAMES' macro |
---|
548 | in the machine description macro file. |
---|
549 | |
---|
550 | This flag does not have a negative form, because it specifies a |
---|
551 | three-way choice. |
---|
552 | |
---|
553 | `-fcall-used-REG' |
---|
554 | Treat the register named REG as an allocable register that is |
---|
555 | clobbered by function calls. It may be allocated for temporaries |
---|
556 | or variables that do not live across a call. Functions compiled |
---|
557 | this way will not save and restore the register REG. |
---|
558 | |
---|
559 | Use of this flag for a register that has a fixed pervasive role in |
---|
560 | the machine's execution model, such as the stack pointer or frame |
---|
561 | pointer, will produce disastrous results. |
---|
562 | |
---|
563 | This flag does not have a negative form, because it specifies a |
---|
564 | three-way choice. |
---|
565 | |
---|
566 | `-fcall-saved-REG' |
---|
567 | Treat the register named REG as an allocable register saved by |
---|
568 | functions. It may be allocated even for temporaries or variables |
---|
569 | that live across a call. Functions compiled this way will save |
---|
570 | and restore the register REG if they use it. |
---|
571 | |
---|
572 | Use of this flag for a register that has a fixed pervasive role in |
---|
573 | the machine's execution model, such as the stack pointer or frame |
---|
574 | pointer, will produce disastrous results. |
---|
575 | |
---|
576 | A different sort of disaster will result from the use of this flag |
---|
577 | for a register in which function values may be returned. |
---|
578 | |
---|
579 | This flag does not have a negative form, because it specifies a |
---|
580 | three-way choice. |
---|
581 | |
---|
582 | `-fpack-struct' |
---|
583 | Pack all structure members together without holes. Usually you |
---|
584 | would not want to use this option, since it makes the code |
---|
585 | suboptimal, and the offsets of structure members won't agree with |
---|
586 | system libraries. |
---|
587 | |
---|
588 | `-fcheck-memory-usage' |
---|
589 | Generate extra code to check each memory access. GNU CC will |
---|
590 | generate code that is suitable for a detector of bad memory |
---|
591 | accesses such as `Checker'. If you specify this option, you can |
---|
592 | not use the `asm' or `__asm__' keywords. |
---|
593 | |
---|
594 | You must also specify this option when you compile functions you |
---|
595 | call that have side effects. If you do not, you may get erroneous |
---|
596 | messages from the detector. Normally, you should compile all |
---|
597 | your code with this option. If you use functions from a library |
---|
598 | that have side-effects (such as `read'), you may not be able to |
---|
599 | recompile the library and specify this option. In that case, you |
---|
600 | can enable the `-fprefix-function-name' option, which requests GNU |
---|
601 | CC to encapsulate your code and make other functions look as if |
---|
602 | they were compiled with `-fcheck-memory-usage'. This is done by |
---|
603 | calling "stubs", which are provided by the detector. If you |
---|
604 | cannot find or build stubs for every function you call, you may |
---|
605 | have to specify `-fcheck-memory-usage' without |
---|
606 | `-fprefix-function-name'. |
---|
607 | |
---|
608 | `-fprefix-function-name' |
---|
609 | Request GNU CC to add a prefix to the symbols generated for |
---|
610 | function names. GNU CC adds a prefix to the names of functions |
---|
611 | defined as well as functions called. Code compiled with this |
---|
612 | option and code compiled without the option can't be linked |
---|
613 | together, unless or stubs are used. |
---|
614 | |
---|
615 | If you compile the following code with `-fprefix-function-name' |
---|
616 | extern void bar (int); |
---|
617 | void |
---|
618 | foo (int a) |
---|
619 | { |
---|
620 | return bar (a + 5); |
---|
621 | |
---|
622 | } |
---|
623 | |
---|
624 | GNU CC will compile the code as if it was written: |
---|
625 | extern void prefix_bar (int); |
---|
626 | void |
---|
627 | prefix_foo (int a) |
---|
628 | { |
---|
629 | return prefix_bar (a + 5); |
---|
630 | } |
---|
631 | This option is designed to be used with `-fcheck-memory-usage'. |
---|
632 | |
---|
633 | `-fstack-check' |
---|
634 | Generate code to verify that you do not go beyond the boundary of |
---|
635 | the stack. You should specify this flag if you are running in an |
---|
636 | environment with multiple threads, but only rarely need to specify |
---|
637 | it in a single-threaded environment since stack overflow is |
---|
638 | automatically detected on nearly all systems if there is only one |
---|
639 | stack. |
---|
640 | |
---|
641 | `+e0' |
---|
642 | `+e1' |
---|
643 | Control whether virtual function definitions in classes are used to |
---|
644 | generate code, or only to define interfaces for their callers. |
---|
645 | (C++ only). |
---|
646 | |
---|
647 | These options are provided for compatibility with `cfront' 1.x |
---|
648 | usage; the recommended alternative GNU C++ usage is in flux. |
---|
649 | *Note Declarations and Definitions in One Header: C++ Interface. |
---|
650 | |
---|
651 | With `+e0', virtual function definitions in classes are declared |
---|
652 | `extern'; the declaration is used only as an interface |
---|
653 | specification, not to generate code for the virtual functions (in |
---|
654 | this compilation). |
---|
655 | |
---|
656 | With `+e1', G++ actually generates the code implementing virtual |
---|
657 | functions defined in the code, and makes them publicly visible. |
---|
658 | |
---|
659 | |
---|
660 | File: gcc.info, Node: Environment Variables, Next: Running Protoize, Prev: Code Gen Options, Up: Invoking GCC |
---|
661 | |
---|
662 | Environment Variables Affecting GNU CC |
---|
663 | ====================================== |
---|
664 | |
---|
665 | This section describes several environment variables that affect how |
---|
666 | GNU CC operates. They work by specifying directories or prefixes to use |
---|
667 | when searching for various kinds of files. |
---|
668 | |
---|
669 | Note that you can also specify places to search using options such as |
---|
670 | `-B', `-I' and `-L' (*note Directory Options::.). These take |
---|
671 | precedence over places specified using environment variables, which in |
---|
672 | turn take precedence over those specified by the configuration of GNU |
---|
673 | CC. *Note Driver::. |
---|
674 | |
---|
675 | `TMPDIR' |
---|
676 | If `TMPDIR' is set, it specifies the directory to use for temporary |
---|
677 | files. GNU CC uses temporary files to hold the output of one |
---|
678 | stage of compilation which is to be used as input to the next |
---|
679 | stage: for example, the output of the preprocessor, which is the |
---|
680 | input to the compiler proper. |
---|
681 | |
---|
682 | `GCC_EXEC_PREFIX' |
---|
683 | If `GCC_EXEC_PREFIX' is set, it specifies a prefix to use in the |
---|
684 | names of the subprograms executed by the compiler. No slash is |
---|
685 | added when this prefix is combined with the name of a subprogram, |
---|
686 | but you can specify a prefix that ends with a slash if you wish. |
---|
687 | |
---|
688 | If GNU CC cannot find the subprogram using the specified prefix, it |
---|
689 | tries looking in the usual places for the subprogram. |
---|
690 | |
---|
691 | The default value of `GCC_EXEC_PREFIX' is `PREFIX/lib/gcc-lib/' |
---|
692 | where PREFIX is the value of `prefix' when you ran the `configure' |
---|
693 | script. |
---|
694 | |
---|
695 | Other prefixes specified with `-B' take precedence over this |
---|
696 | prefix. |
---|
697 | |
---|
698 | This prefix is also used for finding files such as `crt0.o' that |
---|
699 | are used for linking. |
---|
700 | |
---|
701 | In addition, the prefix is used in an unusual way in finding the |
---|
702 | directories to search for header files. For each of the standard |
---|
703 | directories whose name normally begins with |
---|
704 | `/usr/local/lib/gcc-lib' (more precisely, with the value of |
---|
705 | `GCC_INCLUDE_DIR'), GNU CC tries replacing that beginning with the |
---|
706 | specified prefix to produce an alternate directory name. Thus, |
---|
707 | with `-Bfoo/', GNU CC will search `foo/bar' where it would |
---|
708 | normally search `/usr/local/lib/bar'. These alternate directories |
---|
709 | are searched first; the standard directories come next. |
---|
710 | |
---|
711 | `COMPILER_PATH' |
---|
712 | The value of `COMPILER_PATH' is a colon-separated list of |
---|
713 | directories, much like `PATH'. GNU CC tries the directories thus |
---|
714 | specified when searching for subprograms, if it can't find the |
---|
715 | subprograms using `GCC_EXEC_PREFIX'. |
---|
716 | |
---|
717 | `LIBRARY_PATH' |
---|
718 | The value of `LIBRARY_PATH' is a colon-separated list of |
---|
719 | directories, much like `PATH'. When configured as a native |
---|
720 | compiler, GNU CC tries the directories thus specified when |
---|
721 | searching for special linker files, if it can't find them using |
---|
722 | `GCC_EXEC_PREFIX'. Linking using GNU CC also uses these |
---|
723 | directories when searching for ordinary libraries for the `-l' |
---|
724 | option (but directories specified with `-L' come first). |
---|
725 | |
---|
726 | `C_INCLUDE_PATH' |
---|
727 | `CPLUS_INCLUDE_PATH' |
---|
728 | `OBJC_INCLUDE_PATH' |
---|
729 | These environment variables pertain to particular languages. Each |
---|
730 | variable's value is a colon-separated list of directories, much |
---|
731 | like `PATH'. When GNU CC searches for header files, it tries the |
---|
732 | directories listed in the variable for the language you are using, |
---|
733 | after the directories specified with `-I' but before the standard |
---|
734 | header file directories. |
---|
735 | |
---|
736 | `DEPENDENCIES_OUTPUT' |
---|
737 | If this variable is set, its value specifies how to output |
---|
738 | dependencies for Make based on the header files processed by the |
---|
739 | compiler. This output looks much like the output from the `-M' |
---|
740 | option (*note Preprocessor Options::.), but it goes to a separate |
---|
741 | file, and is in addition to the usual results of compilation. |
---|
742 | |
---|
743 | The value of `DEPENDENCIES_OUTPUT' can be just a file name, in |
---|
744 | which case the Make rules are written to that file, guessing the |
---|
745 | target name from the source file name. Or the value can have the |
---|
746 | form `FILE TARGET', in which case the rules are written to file |
---|
747 | FILE using TARGET as the target name. |
---|
748 | |
---|
749 | |
---|
750 | File: gcc.info, Node: Running Protoize, Prev: Environment Variables, Up: Invoking GCC |
---|
751 | |
---|
752 | Running Protoize |
---|
753 | ================ |
---|
754 | |
---|
755 | The program `protoize' is an optional part of GNU C. You can use it |
---|
756 | to add prototypes to a program, thus converting the program to ANSI C |
---|
757 | in one respect. The companion program `unprotoize' does the reverse: |
---|
758 | it removes argument types from any prototypes that are found. |
---|
759 | |
---|
760 | When you run these programs, you must specify a set of source files |
---|
761 | as command line arguments. The conversion programs start out by |
---|
762 | compiling these files to see what functions they define. The |
---|
763 | information gathered about a file FOO is saved in a file named `FOO.X'. |
---|
764 | |
---|
765 | After scanning comes actual conversion. The specified files are all |
---|
766 | eligible to be converted; any files they include (whether sources or |
---|
767 | just headers) are eligible as well. |
---|
768 | |
---|
769 | But not all the eligible files are converted. By default, |
---|
770 | `protoize' and `unprotoize' convert only source and header files in the |
---|
771 | current directory. You can specify additional directories whose files |
---|
772 | should be converted with the `-d DIRECTORY' option. You can also |
---|
773 | specify particular files to exclude with the `-x FILE' option. A file |
---|
774 | is converted if it is eligible, its directory name matches one of the |
---|
775 | specified directory names, and its name within the directory has not |
---|
776 | been excluded. |
---|
777 | |
---|
778 | Basic conversion with `protoize' consists of rewriting most function |
---|
779 | definitions and function declarations to specify the types of the |
---|
780 | arguments. The only ones not rewritten are those for varargs functions. |
---|
781 | |
---|
782 | `protoize' optionally inserts prototype declarations at the |
---|
783 | beginning of the source file, to make them available for any calls that |
---|
784 | precede the function's definition. Or it can insert prototype |
---|
785 | declarations with block scope in the blocks where undeclared functions |
---|
786 | are called. |
---|
787 | |
---|
788 | Basic conversion with `unprotoize' consists of rewriting most |
---|
789 | function declarations to remove any argument types, and rewriting |
---|
790 | function definitions to the old-style pre-ANSI form. |
---|
791 | |
---|
792 | Both conversion programs print a warning for any function |
---|
793 | declaration or definition that they can't convert. You can suppress |
---|
794 | these warnings with `-q'. |
---|
795 | |
---|
796 | The output from `protoize' or `unprotoize' replaces the original |
---|
797 | source file. The original file is renamed to a name ending with |
---|
798 | `.save'. If the `.save' file already exists, then the source file is |
---|
799 | simply discarded. |
---|
800 | |
---|
801 | `protoize' and `unprotoize' both depend on GNU CC itself to scan the |
---|
802 | program and collect information about the functions it uses. So |
---|
803 | neither of these programs will work until GNU CC is installed. |
---|
804 | |
---|
805 | Here is a table of the options you can use with `protoize' and |
---|
806 | `unprotoize'. Each option works with both programs unless otherwise |
---|
807 | stated. |
---|
808 | |
---|
809 | `-B DIRECTORY' |
---|
810 | Look for the file `SYSCALLS.c.X' in DIRECTORY, instead of the |
---|
811 | usual directory (normally `/usr/local/lib'). This file contains |
---|
812 | prototype information about standard system functions. This option |
---|
813 | applies only to `protoize'. |
---|
814 | |
---|
815 | `-c COMPILATION-OPTIONS' |
---|
816 | Use COMPILATION-OPTIONS as the options when running `gcc' to |
---|
817 | produce the `.X' files. The special option `-aux-info' is always |
---|
818 | passed in addition, to tell `gcc' to write a `.X' file. |
---|
819 | |
---|
820 | Note that the compilation options must be given as a single |
---|
821 | argument to `protoize' or `unprotoize'. If you want to specify |
---|
822 | several `gcc' options, you must quote the entire set of |
---|
823 | compilation options to make them a single word in the shell. |
---|
824 | |
---|
825 | There are certain `gcc' arguments that you cannot use, because they |
---|
826 | would produce the wrong kind of output. These include `-g', `-O', |
---|
827 | `-c', `-S', and `-o' If you include these in the |
---|
828 | COMPILATION-OPTIONS, they are ignored. |
---|
829 | |
---|
830 | `-C' |
---|
831 | Rename files to end in `.C' instead of `.c'. This is convenient |
---|
832 | if you are converting a C program to C++. This option applies |
---|
833 | only to `protoize'. |
---|
834 | |
---|
835 | `-g' |
---|
836 | Add explicit global declarations. This means inserting explicit |
---|
837 | declarations at the beginning of each source file for each function |
---|
838 | that is called in the file and was not declared. These |
---|
839 | declarations precede the first function definition that contains a |
---|
840 | call to an undeclared function. This option applies only to |
---|
841 | `protoize'. |
---|
842 | |
---|
843 | `-i STRING' |
---|
844 | Indent old-style parameter declarations with the string STRING. |
---|
845 | This option applies only to `protoize'. |
---|
846 | |
---|
847 | `unprotoize' converts prototyped function definitions to old-style |
---|
848 | function definitions, where the arguments are declared between the |
---|
849 | argument list and the initial `{'. By default, `unprotoize' uses |
---|
850 | five spaces as the indentation. If you want to indent with just |
---|
851 | one space instead, use `-i " "'. |
---|
852 | |
---|
853 | `-k' |
---|
854 | Keep the `.X' files. Normally, they are deleted after conversion |
---|
855 | is finished. |
---|
856 | |
---|
857 | `-l' |
---|
858 | Add explicit local declarations. `protoize' with `-l' inserts a |
---|
859 | prototype declaration for each function in each block which calls |
---|
860 | the function without any declaration. This option applies only to |
---|
861 | `protoize'. |
---|
862 | |
---|
863 | `-n' |
---|
864 | Make no real changes. This mode just prints information about the |
---|
865 | conversions that would have been done without `-n'. |
---|
866 | |
---|
867 | `-N' |
---|
868 | Make no `.save' files. The original files are simply deleted. |
---|
869 | Use this option with caution. |
---|
870 | |
---|
871 | `-p PROGRAM' |
---|
872 | Use the program PROGRAM as the compiler. Normally, the name `gcc' |
---|
873 | is used. |
---|
874 | |
---|
875 | `-q' |
---|
876 | Work quietly. Most warnings are suppressed. |
---|
877 | |
---|
878 | `-v' |
---|
879 | Print the version number, just like `-v' for `gcc'. |
---|
880 | |
---|
881 | If you need special compiler options to compile one of your program's |
---|
882 | source files, then you should generate that file's `.X' file specially, |
---|
883 | by running `gcc' on that source file with the appropriate options and |
---|
884 | the option `-aux-info'. Then run `protoize' on the entire set of |
---|
885 | files. `protoize' will use the existing `.X' file because it is newer |
---|
886 | than the source file. For example: |
---|
887 | |
---|
888 | gcc -Dfoo=bar file1.c -aux-info |
---|
889 | protoize *.c |
---|
890 | |
---|
891 | You need to include the special files along with the rest in the |
---|
892 | `protoize' command, even though their `.X' files already exist, because |
---|
893 | otherwise they won't get converted. |
---|
894 | |
---|
895 | *Note Protoize Caveats::, for more information on how to use |
---|
896 | `protoize' successfully. |
---|
897 | |
---|