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