gcc/gcc.info-5

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