home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / unix / info / gcc.i03 (.txt) < prev    next >
GNU Info File  |  1993-06-12  |  50KB  |  951 lines
  1. This is Info file gcc.info, produced by Makeinfo-1.47 from the input
  2. file gcc.tex.
  3.    This file documents the use and the internals of the GNU compiler.
  4.    Copyright (C) 1988, 1989, 1992 Free Software Foundation, Inc.
  5.    Permission is granted to make and distribute verbatim copies of this
  6. manual provided the copyright notice and this permission notice are
  7. preserved on all copies.
  8.    Permission is granted to copy and distribute modified versions of
  9. this manual under the conditions for verbatim copying, provided also
  10. that the sections entitled "GNU General Public License" and "Protect
  11. Your Freedom--Fight `Look And Feel'" are included exactly as in the
  12. original, and provided that the entire resulting derived work is
  13. distributed under the terms of a permission notice identical to this
  14.    Permission is granted to copy and distribute translations of this
  15. manual into another language, under the above conditions for modified
  16. versions, except that the sections entitled "GNU General Public
  17. License" and "Protect Your Freedom--Fight `Look And Feel'", and this
  18. permission notice, may be included in translations approved by the Free
  19. Software Foundation instead of in the original English.
  20. File: gcc.info,  Node: Link Options,  Next: Directory Options,  Prev: Assembler Options,  Up: Invoking GCC
  21. Options for Linking
  22. ===================
  23.    These options come into play when the compiler links object files
  24. into an executable output file.  They are meaningless if the compiler is
  25. not doing a link step.
  26. `OBJECT-FILE-NAME'
  27.      A file name that does not end in a special recognized suffix is
  28.      considered to name an object file or library.  (Object files are
  29.      distinguished from libraries by the linker according to the file
  30.      contents.)  If linking is done, these object files are used as
  31.      input to the linker.
  32.      If any of these options is used, then the linker is not run, and
  33.      object file names should not be used as arguments.  *Note Overall
  34.      Options::.
  35. `-lLIBRARY'
  36.      Search the library named LIBRARY when linking.
  37.      It makes a difference where in the command you write this option;
  38.      the linker searches processes libraries and object files in the
  39.      order they are specified.  Thus, `foo.o -lz bar.o' searches
  40.      library `z' after file `foo.o' but before `bar.o'.  If `bar.o'
  41.      refers to functions in `z', those functions may not be loaded.
  42.      The linker searches a standard list of directories for the library,
  43.      which is actually a file named `libLIBRARY.a'.  The linker then
  44.      uses this file as if it had been specified precisely by name.
  45.      The directories searched include several standard system
  46.      directories plus any that you specify with `-L'.
  47.      Normally the files found this way are library files--archive files
  48.      whose members are object files.  The linker handles an archive
  49.      file by scanning through it for members which define symbols that
  50.      have so far been referenced but not defined.  But if the file that
  51.      is found is an ordinary object file, it is linked in the usual
  52.      fashion.  The only difference between using an `-l' option and
  53.      specifying a file name is that `-l' surrounds LIBRARY with `lib'
  54.      and `.a' and searches several directories.
  55. `-lobjc'
  56.      This special case of the `-l' option is what you need to do when
  57.      you link an Objective C program.
  58. `-nostdlib'
  59.      Don't use the standard system libraries and startup files when
  60.      linking. Only the files you specify will be passed to the linker.
  61. `-static'
  62.      On systems that support dynamic linking, this prevents linking
  63.      with the shared libraries.  On other systems, this option has no
  64.      effect.
  65. `-shared'
  66.      Produce a shared object which can then be linked with other
  67.      objects to form an executable.  Only a few systems support this
  68.      option.
  69. `-symbolic'
  70.      Bind references to global symbols when building a shared object. 
  71.      Warn about any unresolved references (unless overridden by the
  72.      link editor option `-Xlinker -z -Xlinker defs').  Only a few
  73.      systems support this option.
  74. `-Xlinker OPTION'
  75.      Pass OPTION as an option to the linker.  You can use this to
  76.      supply system-specific linker options which GNU CC does not know
  77.      how to recognize.
  78.      If you want to pass an option that takes an argument, you must use
  79.      `-Xlinker' twice, once for the option and once for the argument.
  80.      For example, to pass `-assert definitions', you must write
  81.      `-Xlinker -assert -Xlinker definitions'.  It does not work to write
  82.      `-Xlinker "-assert definitions"', because this passes the entire
  83.      string as a single argument, which is not what the linker expects.
  84. `-Wl,OPTION'
  85.      Pass OPTION as an option to the linker.  If OPTION contains
  86.      commas, it is split into multiple options at the commas.
  87. `-u SYMBOL'
  88.      Pretend the symbol SYMBOL is undefined, to force linking of
  89.      library modules to define it.  You can use `-u' multiple times with
  90.      different symbols to force loading of additional library modules.
  91. File: gcc.info,  Node: Directory Options,  Next: Target Options,  Prev: Link Options,  Up: Invoking GCC
  92. Options for Directory Search
  93. ============================
  94.    These options specify directories to search for header files, for
  95. libraries and for parts of the compiler:
  96. `-IDIR'
  97.      Append directory DIR to the list of directories searched for
  98.      include files.
  99. `-I-'
  100.      Any directories you specify with `-I' options before the `-I-'
  101.      option are searched only for the case of `#include "FILE"'; they
  102.      are not searched for `#include <FILE>'.
  103.      If additional directories are specified with `-I' options after
  104.      the `-I-', these directories are searched for all `#include'
  105.      directives.  (Ordinarily *all* `-I' directories are used this way.)
  106.      In addition, the `-I-' option inhibits the use of the current
  107.      directory (where the current input file came from) as the first
  108.      search directory for `#include "FILE"'.  There is no way to
  109.      override this effect of `-I-'.  With `-I.' you can specify
  110.      searching the directory which was current when the compiler was
  111.      invoked.  That is not exactly the same as what the preprocessor
  112.      does by default, but it is often satisfactory.
  113.      `-I-' does not inhibit the use of the standard system directories
  114.      for header files.  Thus, `-I-' and `-nostdinc' are independent.
  115. `-LDIR'
  116.      Add directory DIR to the list of directories to be searched for
  117.      `-l'.
  118. `-BPREFIX'
  119.      This option specifies where to find the executables, libraries and
  120.      data files of the compiler itself.
  121.      The compiler driver program runs one or more of the subprograms
  122.      `cpp', `cc1', `as' and `ld'.  It tries PREFIX as a prefix for each
  123.      program it tries to run, both with and without `MACHINE/VERSION/'
  124.      (*note Target Options::.).
  125.      For each subprogram to be run, the compiler driver first tries the
  126.      `-B' prefix, if any.  If that name is not found, or if `-B' was
  127.      not specified, the driver tries two standard prefixes, which are
  128.      `/usr/lib/gcc/' and `/usr/local/lib/gcc-lib/'.  If neither of
  129.      those results in a file name that is found, the unmodified program
  130.      name is searched for using the directories specified in your
  131.      `PATH' environment variable.
  132.      `-B' prefixes that effectively specify directory names also apply
  133.      to libraries in the linker, because the compiler translates these
  134.      options into `-L' options for the linker.
  135.      The run-time support file `libgcc.a' can also be searched for using
  136.      the `-B' prefix, if needed.  If it is not found there, the two
  137.      standard prefixes above are tried, and that is all.  The file is
  138.      left out of the link if it is not found by those means.
  139.      Another way to specify a prefix much like the `-B' prefix is to use
  140.      the environment variable `GCC_EXEC_PREFIX'.  *Note Environment
  141.      Variables::.
  142. File: gcc.info,  Node: Target Options,  Next: Submodel Options,  Prev: Directory Options,  Up: Invoking GCC
  143. Specifying Target Machine and Compiler Version
  144. ==============================================
  145.    By default, GNU CC compiles code for the same type of machine that
  146. you are using.  However, it can also be installed as a cross-compiler,
  147. to compile for some other type of machine.  In fact, several different
  148. configurations of GNU CC, for different target machines, can be
  149. installed side by side.  Then you specify which one to use with the
  150. `-b' option.
  151.    In addition, older and newer versions of GNU CC can be installed side
  152. by side.  One of them (probably the newest) will be the default, but
  153. you may sometimes wish to use another.
  154. `-b MACHINE'
  155.      The argument MACHINE specifies the target machine for compilation.
  156.      This is useful when you have installed GNU CC as a cross-compiler.
  157.      The value to use for MACHINE is the same as was specified as the
  158.      machine type when configuring GNU CC as a cross-compiler.  For
  159.      example, if a cross-compiler was configured with `configure
  160.      i386v', meaning to compile for an 80386 running System V, then you
  161.      would specify `-b i386v' to run that cross compiler.
  162.      When you do not specify `-b', it normally means to compile for the
  163.      same type of machine that you are using.
  164. `-V VERSION'
  165.      The argument VERSION specifies which version of GNU CC to run.
  166.      This is useful when multiple versions are installed.  For example,
  167.      VERSION might be `2.0', meaning to run GNU CC version 2.0.
  168.      The default version, when you do not specify `-V', is controlled
  169.      by the way GNU CC is installed.  Normally, it will be a version
  170.      that is recommended for general use.
  171.    The `-b' and `-V' options actually work by controlling part of the
  172. file name used for the executable files and libraries used for
  173. compilation.  A given version of GNU CC, for a given target machine, is
  174. normally kept in the directory `/usr/local/lib/gcc-lib/MACHINE/VERSION'.
  175.    It follows that sites can customize the effect of `-b' or `-V'
  176. either by changing the names of these directories or adding alternate
  177. names (or symbolic links).  Thus, if `/usr/local/lib/gcc-lib/80386' is
  178. a link to `/usr/local/lib/gcc-lib/i386v', then `-b 80386' becomes an
  179. alias for `-b i386v'.
  180.    In one respect, the `-b' or `-V' do not completely change to a
  181. different compiler: the top-level driver program `gcc' that you
  182. originally invoked continues to run and invoke the other executables
  183. (preprocessor, compiler per se, assembler and linker) that do the real
  184. work.  However, since no real work is done in the driver program, it
  185. usually does not matter that the driver program in use is not the one
  186. for the specified target and version.
  187.    The only way that the driver program depends on the target machine is
  188. in the parsing and handling of special machine-specific options.
  189. However, this is controlled by a file which is found, along with the
  190. other executables, in the directory for the specified version and
  191. target machine.  As a result, a single installed driver program adapts
  192. to any specified target machine and compiler version.
  193.    The driver program executable does control one significant thing,
  194. however: the default version and target machine.  Therefore, you can
  195. install different instances of the driver program, compiled for
  196. different targets or versions, under different names.
  197.    For example, if the driver for version 2.0 is installed as `ogcc'
  198. and that for version 2.1 is installed as `gcc', then the command `gcc'
  199. will use version 2.1 by default, while `ogcc' will use 2.0 by default. 
  200. However, you can choose either version with either command with the
  201. `-V' option.
  202. File: gcc.info,  Node: Submodel Options,  Next: Code Gen Options,  Prev: Target Options,  Up: Invoking GCC
  203. Specifying Hardware Models and Configurations
  204. =============================================
  205.    Earlier we discussed the standard option `-b' which chooses among
  206. different installed compilers for completely different target machines,
  207. such as Vax vs. 68000 vs. 80386.
  208.    In addition, each of these target machine types can have its own
  209. special options, starting with `-m', to choose among various hardware
  210. models or configurations--for example, 68010 vs 68020, floating
  211. coprocessor or none.  A single installed version of the compiler can
  212. compile for any model or configuration, according to the options
  213. specified.
  214.    Some configurations of the compiler also support additional special
  215. options, usually for compatibility with other compilers on the same
  216. platform.
  217.    These options are defined by the macro `TARGET_SWITCHES' in the
  218. machine description.  The default for the options is also defined by
  219. that macro, which enables you to change the defaults.
  220. * Menu:
  221. * M680x0 Options::
  222. * VAX Options::
  223. * SPARC Options::
  224. * Convex Options::
  225. * AMD29K Options::
  226. * M88K Options::
  227. * RS/6000 Options::
  228. * RT Options::
  229. * MIPS Options::
  230. * i386 Options::
  231. * HPPA Options::
  232. * Intel 960 Options::
  233. * DEC Alpha Options::
  234. * System V Options::
  235. File: gcc.info,  Node: M680x0 Options,  Next: VAX Options,  Up: Submodel Options
  236. M680x0 Options
  237. --------------
  238.    These are the `-m' options defined for the 68000 series.  The default
  239. values for these options depends on which style of 68000 was selected
  240. when the compiler was configured; the defaults for the most common
  241. choices are given below.
  242. `-m68000'
  243. `-mc68000'
  244.      Generate output for a 68000.  This is the default when the
  245.      compiler is configured for 68000-based systems.
  246. `-m68020'
  247. `-mc68020'
  248.      Generate output for a 68020.  This is the default when the
  249.      compiler is configured for 68020-based systems.
  250. `-m68881'
  251.      Generate output containing 68881 instructions for floating point.
  252.      This is the default for most 68020 systems unless `-nfp' was
  253.      specified when the compiler was configured.
  254. `-m68030'
  255.      Generate output for a 68030.  This is the default when the
  256.      compiler is configured for 68030-based systems.
  257. `-m68040'
  258.      Generate output for a 68040.  This is the default when the
  259.      compiler is configured for 68040-based systems.
  260. `-m68020-40'
  261.      Generate output for a 68040, without using any of the new
  262.      instructions. This results in code which can run relatively
  263.      efficiently on either a 68020/68881 or a 68030 or a 68040.
  264. `-mfpa'
  265.      Generate output containing Sun FPA instructions for floating point.
  266. `-msoft-float'
  267.      Generate output containing library calls for floating point.
  268.      *Warning:* the requisite libraries are not part of GNU CC.
  269.      Normally the facilities of the machine's usual C compiler are
  270.      used, but this can't be done directly in cross-compilation.  You
  271.      must make your own arrangements to provide suitable library
  272.      functions for cross-compilation.
  273. `-mshort'
  274.      Consider type `int' to be 16 bits wide, like `short int'.
  275. `-mnobitfield'
  276.      Do not use the bit-field instructions.  `-m68000' implies
  277.      `-mnobitfield'.
  278. `-mbitfield'
  279.      Do use the bit-field instructions.  `-m68020' implies
  280.      `-mbitfield'.  This is the default if you use the unmodified
  281.      sources configured for a 68020.
  282. `-mrtd'
  283.      Use a different function-calling convention, in which functions
  284.      that take a fixed number of arguments return with the `rtd'
  285.      instruction, which pops their arguments while returning.  This
  286.      saves one instruction in the caller since there is no need to pop
  287.      the arguments there.
  288.      This calling convention is incompatible with the one normally used
  289.      on Unix, so you cannot use it if you need to call libraries
  290.      compiled with the Unix compiler.
  291.      Also, you must provide function prototypes for all functions that
  292.      take variable numbers of arguments (including `printf'); otherwise
  293.      incorrect code will be generated for calls to those functions.
  294.      In addition, seriously incorrect code will result if you call a
  295.      function with too many arguments.  (Normally, extra arguments are
  296.      harmlessly ignored.)
  297.      The `rtd' instruction is supported by the 68010 and 68020
  298.      processors, but not by the 68000.
  299. File: gcc.info,  Node: VAX Options,  Next: SPARC Options,  Prev: M680x0 Options,  Up: Submodel Options
  300. VAX Options
  301. -----------
  302.    These `-m' options are defined for the Vax:
  303. `-munix'
  304.      Do not output certain jump instructions (`aobleq' and so on) that
  305.      the Unix assembler for the Vax cannot handle across long ranges.
  306. `-mgnu'
  307.      Do output those jump instructions, on the assumption that you will
  308.      assemble with the GNU assembler.
  309. `-mg'
  310.      Output code for g-format floating point numbers instead of
  311.      d-format.
  312. File: gcc.info,  Node: Sparc Options,  Next: Convex Options,  Prev: VAX Options,  Up: Submodel Options
  313. SPARC Options
  314. -------------
  315.    These `-m' switches are supported on the Sparc:
  316. `-mforce-align'
  317.      Make sure all objects of type `double' are 8-byte aligned in memory
  318.      and use double-word instructions to reference them.
  319. `-mno-epilogue'
  320.      Generate separate return instructions for `return' statements.
  321.      This has both advantages and disadvantages; I don't recall what
  322.      they are.
  323. File: gcc.info,  Node: Convex Options,  Next: AMD29K Options,  Prev: SPARC Options,  Up: Submodel Options
  324. Convex Options
  325. --------------
  326.    These `-m' options are defined for the Convex:
  327. `-mc1'
  328.      Generate output for a C1.  This is the default when the compiler is
  329.      configured for a C1.
  330. `-mc2'
  331.      Generate output for a C2.  This is the default when the compiler is
  332.      configured for a C2.
  333. `-margcount'
  334.      Generate code which puts an argument count in the word preceding
  335.      each argument list.  Some nonportable Convex and Vax programs need
  336.      this word. (Debuggers don't, except for functions with
  337.      variable-length argument lists; this info is in the symbol table.)
  338. `-mnoargcount'
  339.      Omit the argument count word.  This is the default if you use the
  340.      unmodified sources.
  341. File: gcc.info,  Node: AMD29K Options,  Next: M88K Options,  Prev: Convex Options,  Up: Submodel Options
  342. AMD29K Options
  343. --------------
  344.    These `-m' options are defined for the AMD Am29000:
  345. `-mdw'
  346.      Generate code that assumes the `DW' bit is set, i.e., that byte and
  347.      halfword operations are directly supported by the hardware.  This
  348.      is the default.
  349. `-mnodw'
  350.      Generate code that assumes the `DW' bit is not set.
  351. `-mbw'
  352.      Generate code that assumes the system supports byte and halfword
  353.      write operations.  This is the default.
  354. `-mnbw'
  355.      Generate code that assumes the systems does not support byte and
  356.      halfword write operations.  `-mnbw' implies `-mnodw'.
  357. `-msmall'
  358.      Use a small memory model that assumes that all function addresses
  359.      are either within a single 256 KB segment or at an absolute
  360.      address of less than 256K.  This allows the `call' instruction to
  361.      be used instead of a `const', `consth', `calli' sequence.
  362. `-mlarge'
  363.      Do not assume that the `call' instruction can be used; this is the
  364.      default.
  365. `-m29050'
  366.      Generate code for the Am29050.
  367. `-m29000'
  368.      Generate code for the Am29000.  This is the default.
  369. `-mkernel-registers'
  370.      Generate references to registers `gr64-gr95' instead of
  371.      `gr96-gr127'.  This option can be used when compiling kernel code
  372.      that wants a set of global registers disjoint from that used by
  373.      user-mode code.
  374.      Note that when this option is used, register names in `-f' flags
  375.      must use the normal, user-mode, names.
  376. `-muser-registers'
  377.      Use the normal set of global registers, `gr96-gr127'.  This is the
  378.      default.
  379. `-mstack-check'
  380.      Insert a call to `__msp_check' after each stack adjustment.  This
  381.      is often used for kernel code.
  382. File: gcc.info,  Node: M88K Options,  Next: RS/6000 Options,  Prev: AMD29K Options,  Up: Submodel Options
  383. M88K Options
  384. ------------
  385.    These `-m' options are defined for Motorola 88K architectures:
  386. `-m88000'
  387.      Generate code that works well on both the m88100 and the m88110.
  388. `-m88100'
  389.      Generate code that works best for the m88100, but that also runs
  390.      on the m88110.
  391. `-m88110'
  392.      Generate code that works best for the m88110, and may not run on
  393.      the m88100.
  394. `-midentify-revision'
  395.      Include an `ident' directive in the assembler output recording the
  396.      source file name, compiler name and version, timestamp, and
  397.      compilation flags used.
  398. `-mno-underscores'
  399.      In assembler output, emit symbol names without adding an underscore
  400.      character at the beginning of each name.  The default is to use an
  401.      underscore as prefix on each name.
  402. `-mocs-debug-info'
  403. `-mno-ocs-debug-info'
  404.      Include (or omit) additional debugging information (about
  405.      registers used in each stack frame) as specified in the 88open
  406.      Object Compatibility Standard, "OCS".  This extra information
  407.      allows debugging of code that has had the frame pointer
  408.      eliminated.  The default for DG/UX, SVr4, and Delta 88 SVr3.2 is
  409.      to include this information; other 88k configurations omit this
  410.      information by default.
  411. `-mocs-frame-position'
  412.      When emitting COFF debugging information for automatic variables
  413.      and parameters stored on the stack, use the offset from the
  414.      canonical frame address, which is the stack pointer (register 31)
  415.      on entry to the function.  The DG/UX, SVr4, Delta88 SVr3.2, and
  416.      BCS configurations use `-mocs-frame-position'; other 88k
  417.      configurations have the default `-mno-ocs-frame-position'.
  418. `-mno-ocs-frame-position'
  419.      When emitting COFF debugging information for automatic variables
  420.      and parameters stored on the stack, use the offset from the frame
  421.      pointer register (register 30).  When this option is in effect,
  422.      the frame pointer is not eliminated when debugging information is
  423.      selected by the -g switch.
  424. `-moptimize-arg-area'
  425. `-mno-optimize-arg-area'
  426.      Control how to store function arguments in stack frames.
  427.      `-moptimize-arg-area' saves space, but conflicts with the 88open
  428.      specifications.  `-mno-optimize-arg-area' conforms to the 88open
  429.      standards.  By default GNU CC does not optimize the argument area.
  430. `-mshort-data-NUM'
  431.      Generate smaller data references by making them relative to `r0',
  432.      which allows loading a value using a single instruction (rather
  433.      than the usual two).  You control which data references are
  434.      affected by specifying NUM with this option.  For example, if you
  435.      specify `-mshort-data-512', then the data references affected are
  436.      those involving displacements of less than 512 bytes.
  437.      `-mshort-data-NUM' is not effective for NUM greater than 64K.
  438. `-mserialize-volatile'
  439. `-mno-serialize-volatile'
  440.      Do, or don't, generate code to guarantee sequential consistency of
  441.      volatile memory references.
  442.      GNU CC always guarantees consistency by default, for the preferred
  443.      processor submodel.  How this is done depends on the submodel.
  444.      The m88100 processor does not reorder memory references and so
  445.      always provides sequential consistency.  If you use `-m88100', GNU
  446.      CC does not generate any special instructions for sequential
  447.      consistency.
  448.      The order of memory references made by the m88110 processor does
  449.      not always match the order of the instructions requesting those
  450.      references. In particular, a load instruction may execute before a
  451.      preceding store instruction.  Such reordering violates sequential
  452.      consistency of volatile memory references, when there are multiple
  453.      processors.  When you use `-m88000' or `-m88110', GNU CC generates
  454.      special instructions when appropriate, to force execution in the
  455.      proper order.
  456.      The extra code generated to guarantee consistency may affect the
  457.      performance of your application.  If you know that you can safely
  458.      forgo this guarantee, you may use `-mno-serialize-volatile'.
  459.      If you use `-m88100' but require sequential consistency when
  460.      running on the m88110 processor, you should use
  461.      `-mserialize-volatile'.
  462. `-msvr4'
  463. `-msvr3'
  464.      Turn on (`-msvr4') or off (`-msvr3') compiler extensions related
  465.      to System V release 4 (SVr4).  This controls the following:
  466.        1. Which variant of the assembler syntax to emit (which you can
  467.           select independently using `-mversion-03.00').
  468.        2. `-msvr4' makes the C preprocessor recognize `#pragma weak'
  469.           that is used on System V release 4.
  470.        3. `-msvr4' makes GNU CC issue additional declaration directives
  471.           used in SVr4.
  472.      `-msvr3' is the default for all m88K configurations except the
  473.      SVr4 configuration.
  474. `-mversion-03.00'
  475.      In the DG/UX configuration, there are two flavors of SVr4.  This
  476.      option modifies `-msvr4' to select whether the hybrid-COFF or
  477.      real-ELF flavor is used.  All other configurations ignore this
  478.      option.
  479. `-mno-check-zero-division'
  480. `-mcheck-zero-division'
  481.      Early models of the 88K architecture had problems with division by
  482.      zero; in particular, many of them didn't trap.  Use these options
  483.      to avoid including (or to include explicitly) additional code to
  484.      detect division by zero and signal an exception.  All GNU CC
  485.      configurations for the 88K use `-mcheck-zero-division' by default.
  486. `-muse-div-instruction'
  487.      Do not emit code to check both the divisor and dividend when doing
  488.      signed integer division to see if either is negative, and adjust
  489.      the signs so the divide is done using non-negative numbers. 
  490.      Instead, rely on the operating system to calculate the correct
  491.      value when the `div' instruction traps.  This results in different
  492.      behavior when the most negative number is divided by -1, but is
  493.      useful when most or all signed integer divisions are done with
  494.      positive numbers.
  495. `-mtrap-large-shift'
  496. `-mhandle-large-shift'
  497.      Include code to detect bit-shifts of more than 31 bits;
  498.      respectively, trap such shifts or emit code to handle them
  499.      properly.  By default GNU CC makes no special provision for large
  500.      bit shifts.
  501. `-mwarn-passed-structs'
  502.      Warn when a function passes a struct as an argument or result.
  503.      Structure-passing conventions have changed during the evolution of
  504.      the C language, and are often the source of portability problems. 
  505.      By default, GNU CC issues no such warning.
  506. File: gcc.info,  Node: RS/6000 Options,  Next: RT Options,  Prev: M88K Options,  Up: Submodel Options
  507. IBM RS/6000 Options
  508. -------------------
  509.    Only one pair of `-m' options is defined for the IBM RS/6000:
  510. `-mfp-in-toc'
  511. `-mno-fp-in-toc'
  512.      Control whether or not floating-point constants go in the Table of
  513.      Contents (TOC), a table of all global variable and function
  514.      addresses.  By default GNU CC puts floating-point constants there;
  515.      if the TOC overflows, `-mno-fp-in-toc' will reduce the size of the
  516.      TOC, which may avoid the overflow.
  517. File: gcc.info,  Node: RT Options,  Next: MIPS Options,  Prev: RS/6000 Options,  Up: Submodel Options
  518. IBM RT Options
  519. --------------
  520.    These `-m' options are defined for the IBM RT PC:
  521. `-min-line-mul'
  522.      Use an in-line code sequence for integer multiplies.  This is the
  523.      default.
  524. `-mcall-lib-mul'
  525.      Call `lmul$$' for integer multiples.
  526. `-mfull-fp-blocks'
  527.      Generate full-size floating point data blocks, including the
  528.      minimum amount of scratch space recommended by IBM.  This is the
  529.      default.
  530. `-mminimum-fp-blocks'
  531.      Do not include extra scratch space in floating point data blocks. 
  532.      This results in smaller code, but slower execution, since scratch
  533.      space must be allocated dynamically.
  534. `-mfp-arg-in-fpregs'
  535.      Use a calling sequence incompatible with the IBM calling
  536.      convention in which floating point arguments are passed in
  537.      floating point registers. Note that `varargs.h' and `stdargs.h'
  538.      will not work with floating point operands if this option is
  539.      specified.
  540. `-mfp-arg-in-gregs'
  541.      Use the normal calling convention for floating point arguments. 
  542.      This is the default.
  543. `-mhc-struct-return'
  544.      Return structures of more than one word in memory, rather than in a
  545.      register.  This provides compatibility with the MetaWare HighC (hc)
  546.      compiler.  Use `-fpcc-struct-return' for compatibility with the
  547.      Portable C Compiler (pcc).
  548. `-mnohc-struct-return'
  549.      Return some structures of more than one word in registers, when
  550.      convenient.  This is the default.  For compatibility with the
  551.      IBM-supplied compilers, use either `-fpcc-struct-return' or
  552.      `-mhc-struct-return'.
  553. File: gcc.info,  Node: MIPS Options,  Next: i386 Options,  Prev: RT Options,  Up: Submodel Options
  554. MIPS Options
  555. ------------
  556.    These `-m' options are defined for the MIPS family of computers:
  557. `-mcpu=CPU TYPE'
  558.      Assume the defaults for the machine type CPU TYPE when scheduling
  559.      instructions.  The default CPU TYPE is `default', which picks the
  560.      longest cycles times for any of the machines, in order that the
  561.      code run at reasonable rates on all MIPS cpu's.  Other choices for
  562.      CPU TYPE are `r2000', `r3000', `r4000', and `r6000'.  While
  563.      picking a specific CPU TYPE will schedule things appropriately for
  564.      that particular chip, the compiler will not generate any code that
  565.      does not meet level 1 of the MIPS ISA (instruction set
  566.      architecture) without the `-mips2' or `-mips3' switches being used.
  567. `-mips2'
  568.      Issue instructions from level 2 of the MIPS ISA (branch likely,
  569.      square root instructions).  The `-mcpu=r4000' or `-mcpu=r6000'
  570.      switch must be used in conjunction with `-mips2'.
  571. `-mips3'
  572.      Issue instructions from level 3 of the MIPS ISA (64 bit
  573.      instructions). You must use the `-mcpu=r4000' switch along with
  574.      `-mips3'.
  575. `-mint64'
  576. `-mlong64'
  577. `-mlonglong128'
  578.      These options don't work at present.
  579. `-mmips-as'
  580.      Generate code for the MIPS assembler, and invoke `mips-tfile' to
  581.      add normal debug information.  This is the default for all
  582.      platforms except for the OSF/1 reference platform, using the
  583.      OSF/rose object format.  If the either of the `-gstabs' or
  584.      `-gstabs+' switches are used, the `mips-tfile' program will
  585.      encapsulate the stabs within MIPS ECOFF.
  586. `-mgas'
  587.      Generate code for the GNU assembler.  This is the default on the
  588.      OSF/1 reference platform, using the OSF/rose object format.
  589. `-mrnames'
  590. `-mno-rnames'
  591.      The `-mrnames' switch says to output code using the MIPS software
  592.      names for the registers, instead of the hardware names (ie, A0
  593.      instead of $4).  The GNU assembler does not support the `-mrnames'
  594.      switch, and the MIPS assembler will be instructed to run the MIPS
  595.      C preprocessor over the source file.  The `-mno-rnames' switch is
  596.      default.
  597. `-mgpopt'
  598. `-mno-gpopt'
  599.      The `-mgpopt' switch says to write all of the data declarations
  600.      before the instructions in the text section, this allows the MIPS
  601.      assembler to generate one word memory references instead of using
  602.      two words for short global or static data items.  This is on by
  603.      default if optimization is selected.
  604. `-mstats'
  605. `-mno-stats'
  606.      For each non-inline function processed, the `-mstats' switch
  607.      causes the compiler to emit one line to the standard error file to
  608.      print statistics about the program (number of registers saved,
  609.      stack size, etc.).
  610. `-mmemcpy'
  611. `-mno-memcpy'
  612.      The `-mmemcpy' switch makes all block moves call the appropriate
  613.      string function (`memcpy' or `bcopy') instead of possibly
  614.      generating inline code.
  615. `-mmips-tfile'
  616. `-mno-mips-tfile'
  617.      The `-mno-mips-tfile' switch causes the compiler not postprocess
  618.      the object file with the `mips-tfile' program, after the MIPS
  619.      assembler has generated it to add debug support.  If `mips-tfile'
  620.      is not run, then no local variables will be available to the
  621.      debugger.  In addition, `stage2' and `stage3' objects will have
  622.      the temporary file names passed to the assembler embedded in the
  623.      object file, which means the objects will not compare the same. 
  624.      The `-mno-mips-tfile' switch should only be used when there are
  625.      bugs in the `mips-tfile' program that prevents compilation.
  626. `-msoft-float'
  627.      Generate output containing library calls for floating point.
  628.      *Warning:* the requisite libraries are not part of GNU CC.
  629.      Normally the facilities of the machine's usual C compiler are
  630.      used, but this can't be done directly in cross-compilation.  You
  631.      must make your own arrangements to provide suitable library
  632.      functions for cross-compilation.
  633. `-mhard-float'
  634.      Generate output containing floating point instructions.  This is
  635.      the default if you use the unmodified sources.
  636. `-mfp64'
  637.      Assume that the FR bit in the status word is on, and that there
  638.      are 32 64-bit floating point registers, instead of 32 32-bit
  639.      floating point registers.  You must also specify the `-mcpu=r4000'
  640.      and `-mips3' switches.
  641. `-mfp32'
  642.      Assume that there are 32 32-bit floating point registers.  This is
  643.      the default.
  644. `-mabicalls'
  645. `-mno-abicalls'
  646.      Emit the `.abicalls', `.cpload', and `.cprestore' pseudo
  647.      operations that some System V.4 ports use for position independent
  648.      code.
  649. `-mhalf-pic'
  650. `-mno-half-pic'
  651.      Put pointers to extern references into the data section and load
  652.      them up, rather than put the references in the text section. 
  653.      These options do not work at present.
  654. `-G NUM'
  655.      Put global and static items less than or equal to NUM bytes into
  656.      the small data or bss sections instead of the normal data or bss
  657.      section.  This allows the assembler to emit one word memory
  658.      reference instructions based on the global pointer (GP or $28),
  659.      instead of the normal two words used.  By default, NUM is 8 when
  660.      the MIPS assembler is used, and 0 when the GNU assembler is used. 
  661.      The `-G NUM' switch is also passed to the assembler and linker.
  662.      All modules should be compiled with the same `-G NUM' value.
  663. `-nocpp'
  664.      Tell the MIPS assembler to not run it's preprocessor over user
  665.      assembler files (with a `.s' suffix) when assembling them.
  666.    These options are defined by the macro `TARGET_SWITCHES' in the
  667. machine description.  The default for the options is also defined by
  668. that macro, which enables you to change the defaults.
  669. File: gcc.info,  Node: i386 Options,  Next: HPPA Options,  Prev: MIPS Options,  Up: Submodel Options
  670. Intel 386 Options
  671. -----------------
  672.    These `-m' options are defined for the i386 family of computers:
  673. `-m486'
  674. `-mno-486'
  675.      Control whether or not code is optimized for a 486 instead of an
  676.      386.  Code generated for an 486 will run on a 386 and vice versa.
  677. `-msoft-float'
  678.      Generate output containing library calls for floating point.
  679.      *Warning:* the requisite libraries are not part of GNU CC.
  680.      Normally the facilities of the machine's usual C compiler are
  681.      used, but this can't be done directly in cross-compilation.  You
  682.      must make your own arrangements to provide suitable library
  683.      functions for cross-compilation.
  684.      On machines where a function returns floating point results in the
  685.      80387 register stack, some floating point opcodes may be emitted
  686.      even if `-msoft-float' is used.
  687. `-mno-fp-ret-in-387'
  688.      Don't use the FPU registers for return values of functions.
  689.      The usual calling convention has functions return values of types
  690.      `float' and `double' in an FPU register, even if there is no FPU. 
  691.      The idea is that the operating system should emulate an FPU.
  692.      The option `-mno-fp-ret-in-387' causes such values to be returned
  693.      in ordinary CPU registers instead.
  694. File: gcc.info,  Node: HPPA Options,  Next: Intel 960 Options,  Prev: i386 Options,  Up: Submodel Options
  695. HPPA Options
  696. ------------
  697.    This `-m' option is defined for the HPPA family of computers:
  698. `-mno-bss'
  699.      Disable the use of the BSS section.  This may be necessary with
  700.      older versions of pa-gas.   It is highly recommended that you pick
  701.      up a new version of pa-gas from `jaguar.cs.utah.edu'.
  702. `-mpa-risc-1-0'
  703.      Generate code for a PA 1.0 processor.
  704. `-mpa-risc-1-1'
  705.      Generate code for a PA 1.1 processor.
  706. `-mkernel'
  707.      Generate code which is suitable for use in kernels.  Specifically,
  708.      avoid `add' instructions in which one of the arguments is the DP
  709.      register; generate `addil' instructions instead.  This avoids a
  710.      rather serious bug in the HP-UX linker.
  711. `-mshared-libs'
  712.      Generate code that can be linked against HP-UX shared libraries.
  713.      This is the default in HP-UX 8.0.
  714. `-mno-shared-libs'
  715.      Don't generate code that will be linked against shared libraries.
  716.      This may be necessary if the emitted object files will be linked
  717.      on a system older than HP-UX 8.0.
  718. `-mlong-calls'
  719.      Generate code which allows calls to functions greater than 256K
  720.      away from the caller when the caller and callee are in the same
  721.      source file.  Do not turn this option on unless code refuses to
  722.      link with "branch out of range errors" from the linker.
  723. File: gcc.info,  Node: Intel 960 Options,  Next: DEC Alpha Options,  Prev: HPPA Options,  Up: Submodel Options
  724. Intel 960 Options
  725. -----------------
  726.    These `-m' options are defined for the Intel 960 implementations:
  727. `-mCPU TYPE'
  728.      Assume the defaults for the machine type CPU TYPE for some of the
  729.      other options, including instruction scheduling, floating point
  730.      support, and addressing modes.  The choices for CPU TYPE are `ka',
  731.      `kb', `mc', `ca', `cf', `sa', and `sb'. The default is `kb'.
  732. `-mnumerics'
  733. `-msoft-float'
  734.      The `-mnumerics' option indicates that the processor does support
  735.      floating-point instructions.  The `-msoft-float' option indicates
  736.      that floating-point support should not be assumed.
  737. `-mleaf-procedures'
  738. `-mno-leaf-procedures'
  739.      Do (or do not) attempt to alter leaf procedures to be callable
  740.      with the `bal' instruction as well as `call'.  This will result in
  741.      more efficient code for explicit calls when the `bal' instruction
  742.      can be substituted by the assembler or linker, but less efficient
  743.      code in other cases, such as calls via function pointers, or using
  744.      a linker that doesn't support this optimization.
  745. `-mtail-call'
  746. `-mno-tail-call'
  747.      Do (or do not) make additional attempts (beyond those of the
  748.      machine-independent portions of the compiler) to optimize
  749.      tail-recursive calls into branches.  You may not want to do this
  750.      because the detection of cases where this is not valid is not
  751.      totally complete.  The default is `-mno-tail-call'.
  752. `-mcomplex-addr'
  753. `-mno-complex-addr'
  754.      Assume (or do not assume) that the use of a complex addressing
  755.      mode is a win on this implementation of the i960.  Complex
  756.      addressing modes may not be worthwhile on the K-series, but they
  757.      definitely are on the C-series. The default is currently
  758.      `-mcomplex-addr' for all processors except the CB and CC.
  759. `-mcode-align'
  760. `-mno-code-align'
  761.      Align code to 8-byte boundaries for faster fetching (or don't
  762.      bother). Currently turned on by default for C-series
  763.      implementations only.
  764. `-mic-compat'
  765. `-mic2.0-compat'
  766. `-mic3.0-compat'
  767.      Enable compatibility with iC960 v2.0 or v3.0.
  768. `-masm-compat'
  769. `-mintel-asm'
  770.      Enable compatibility with the iC960 assembler.
  771. `-mstrict-align'
  772. `-mno-strict-align'
  773.      Do not permit (do permit) unaligned accesses.
  774. `-mold-align'
  775.      Enable structure-alignment compatibility with Intel's gcc release
  776.      version 1.3 (based on gcc 1.37).  Currently this is buggy in that
  777.      `#pragma align 1' is always assumed as well, and cannot be turned
  778.      off.
  779. File: gcc.info,  Node: DEC Alpha Options,  Next: System V Options,  Prev: Intel 960 Options,  Up: Submodel Options
  780. DEC Alpha Options
  781. -----------------
  782.    These `-m' options are defined for the DEC Alpha implementations:
  783. `-mno-soft-float'
  784. `-msoft-float'
  785.      Use (do not use) the hardware floating-point instructions for
  786.      floating-point operations.  When `-msoft-float' is specified,
  787.      functions in `libgcc1.c' will be used to perform floating-point
  788.      operations.  Unless they are replaced by routines that emulate the
  789.      floating-point operations, or compiled in such a way as to call
  790.      such emulations routines, these routines will issue floating-point
  791.      operations.   If you are compiling for an Alpha without
  792.      floating-point operations, you must ensure that the library is
  793.      built so as not to call them.
  794.      Note that Alpha implementations without floating-point operations
  795.      are required to have floating-point registers.
  796. `-mfp-reg'
  797. `-mno-fp-regs'
  798.      Generate code that uses (does not use) the floating-point register
  799.      set. `-mno-fp-regs' implies `-msoft-float'.  If the floating-point
  800.      register set is not used, floating point operands are passed in
  801.      integer registers as if they were integers and floating-point
  802.      results are passed in $0 instead of $f0.  This is a non-standard
  803.      calling sequence, so any function with a floating-point argument
  804.      or return value called by code compiled with `-mno-fp-regs' must
  805.      also be compiled with that option.
  806.      A typical use of this option is building a kernel that does not
  807.      use, and hence need not save and restore, any floating-point
  808.      registers.
  809. File: gcc.info,  Node: System V Options,  Prev: DEC Alpha Options,  Up: Submodel Options
  810. Options for System V
  811. --------------------
  812.    These additional options are available on System V Release 4 for
  813. compatibility with other compilers on those systems:
  814. `-Qy'
  815.      Identify the versions of each tool used by the compiler, in a
  816.      `.ident' assembler directive in the output.
  817. `-Qn'
  818.      Refrain from adding `.ident' directives to the output file (this is
  819.      the default).
  820. `-YP,DIRS'
  821.      Search the directories DIRS, and no others, for libraries
  822.      specified with `-l'.
  823. `-Ym,DIR'
  824.      Look in the directory DIR to find the M4 preprocessor. The
  825.      assembler uses this option.
  826. File: gcc.info,  Node: Code Gen Options,  Next: Environment Variables,  Prev: Submodel Options,  Up: Invoking GCC
  827. Options for Code Generation Conventions
  828. =======================================
  829.    These machine-independent options control the interface conventions
  830. used in code generation.
  831.    Most of them have both positive and negative forms; the negative form
  832. of `-ffoo' would be `-fno-foo'.  In the table below, only one of the
  833. forms is listed--the one which is not the default.  You can figure out
  834. the other form by either removing `no-' or adding it.
  835. `-fpcc-struct-return'
  836.      Use the same convention for returning `struct' and `union' values
  837.      that is used by the usual C compiler on your system.  This
  838.      convention is less efficient for small structures, and on many
  839.      machines it fails to be reentrant; but it has the advantage of
  840.      allowing intercallability between GNU CC-compiled code and
  841.      PCC-compiled code.
  842. `-fshort-enums'
  843.      Allocate to an `enum' type only as many bytes as it needs for the
  844.      declared range of possible values.  Specifically, the `enum' type
  845.      will be equivalent to the smallest integer type which has enough
  846.      room.
  847. `-fshort-double'
  848.      Use the same size for `double' as for `float'.
  849. `-fshared-data'
  850.      Requests that the data and non-`const' variables of this
  851.      compilation be shared data rather than private data.  The
  852.      distinction makes sense only on certain operating systems, where
  853.      shared data is shared between processes running the same program,
  854.      while private data exists in one copy per process.
  855. `-fno-common'
  856.      Allocate even uninitialized global variables in the bss section of
  857.      the object file, rather than generating them as common blocks. 
  858.      This has the effect that if the same variable is declared (without
  859.      `extern') in two different compilations, you will get an error
  860.      when you link them. The only reason this might be useful is if you
  861.      wish to verify that the program will work on other systems which
  862.      always work this way.
  863. `-fno-ident'
  864.      Ignore the `#ident' directive.
  865. `-fno-gnu-linker'
  866.      Don't output global initializations such as C++ constructors and
  867.      destructors in the form used by the GNU linker (on systems where
  868.      the GNU linker is the standard method of handling them).  Use this
  869.      option when you want to use a "collect" program and a non-GNU
  870.      linker.
  871. `-finhibit-size-directive'
  872.      Don't output a `.size' assembler directive, or anything else that
  873.      would cause trouble if the function is split in the middle, and the
  874.      two halves are placed at locations far apart in memory.  This
  875.      option is used when compiling `crtstuff.c'; you should not need to
  876.      use it for anything else.
  877. `-fnonnull-objects'
  878.      Assume that objects reached through references are not null (C++
  879.      only).
  880.      Normally, GNU C++ makes conservative assumptions about objects
  881.      reached through references.  For example, the compiler must check
  882.      that `a' is not null in code like the following:
  883.           obj &a = g ();
  884.           a.f (2);
  885.      Checking that references of this sort have non-null values requires
  886.      extra code, however, and it is unnecessary for many programs.  You
  887.      can use `-fnonnull-objects' to omit the checks for null, if your
  888.      program doesn't require checking.
  889. `-fverbose-asm'
  890.      Put extra commentary information in the generated assembly code to
  891.      make it more readable.  This option is generally only of use to
  892.      those who actually need to read the generated assembly code
  893.      (perhaps while debugging the compiler itself).
  894. `-fvolatile'
  895.      Consider all memory references through pointers to be volatile.
  896. `-fpic'
  897.      If supported for the target machine, generate position-independent
  898.      code (PIC) suitable for use in a shared library.  All addresses
  899.      will be accessed through a global offset table (GOT).  If the GOT
  900.      size for the linked executable exceeds a machine-specific maximum
  901.      size, you will get an error message from the linker indicating
  902.      that `-fpic' does not work; recompile with `-fPIC' instead. 
  903.      (These maximums are 16k on the m88k, 8k on the Sparc, and 32k on
  904.      the m68k and RS/6000.  The 386 has no such limit.)
  905.      Position-independent code requires special support, and therefore
  906.      works only on certain machines.  For the 386, GNU CC supports PIC
  907.      for System V but not for the Sun 386i.  Code generated for the IBM
  908.      RS/6000 is always position-independent.
  909.      The GNU assembler does not fully support PIC.  Currently, you must
  910.      use some other assembler in order for PIC to work.  We would
  911.      welcome volunteers to upgrade GAS to handle this; the first part
  912.      of the job is to figure out what the assembler must do differently.
  913. `-fPIC'
  914.      If supported for the target machine, emit position-independent
  915.      code, suitable for dynamic linking and avoiding any limit on the
  916.      size of the global offset table.  This option makes a difference
  917.      on the m68k, m88k and the Sparc.
  918.      Position-independent code requires special support, and therefore
  919.      works only on certain machines.
  920. `-ffixed-REG'
  921.      Treat the register named REG as a fixed register; generated code
  922.      should never refer to it (except perhaps as a stack pointer, frame
  923.      pointer or in some other fixed role).
  924.      REG must be the name of a register.  The register names accepted
  925.      are machine-specific and are defined in the `REGISTER_NAMES' macro
  926.      in the machine description macro file.
  927.      This flag does not have a negative form, because it specifies a
  928.      three-way choice.
  929. `-fcall-used-REG'
  930.      Treat the register named REG as an allocatable register that is
  931.      clobbered by function calls.  It may be allocated for temporaries
  932.      or variables that do not live across a call.  Functions compiled
  933.      this way will not save and restore the register REG.
  934.      Use of this flag for a register that has a fixed pervasive role in
  935.      the machine's execution model, such as the stack pointer or frame
  936.      pointer, will produce disastrous results.
  937.      This flag does not have a negative form, because it specifies a
  938.      three-way choice.
  939. `-fcall-saved-REG'
  940.      Treat the register named REG as an allocatable register saved by
  941.      functions.  It may be allocated even for temporaries or variables
  942.      that live across a call.  Functions compiled this way will save
  943.      and restore the register REG if they use it.
  944.      Use of this flag for a register that has a fixed pervasive role in
  945.      the machine's execution model, such as the stack pointer or frame
  946.      pointer, will produce disastrous results.
  947.      A different sort of disaster will result from the use of this flag
  948.      for a register in which function values may be returned.
  949.      This flag does not have a negative form, because it specifies a
  950.      three-way choice.
  951.