invoke.texi

早期freebsd实现

@c Copyright (C) 1988, 1989, 1992 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.

@node Invoking GCC
@chapter GNU CC Command Options
@cindex GNU CC command options
@cindex command options
@cindex options, GNU CC command

When you invoke GNU CC, it normally does preprocessing, compilation,
assembly and linking.  The ``overall options'' allow you to stop this
process at an intermediate stage.  For example, the @samp{-c} option
says not to run the linker.  Then the output consists of object files
output by the assembler.

Other options are passed on to one stage of processing.  Some options
control the preprocessor and others the compiler itself.  Yet other
options control the assembler and linker; most of these are not
documented here, since you rarely need to use any of them.

@cindex grouping options
@cindex options, grouping
The @code{gcc} program accepts options and file names as operands.  Many
options have multiletter names; therefore multiple single-letter options
may @emph{not} be grouped: @samp{-dr} is very different from @w{@samp{-d
-r}}.

@cindex order of options
@cindex options, order
You can mix options and other arguments.  For the most part, the order
you use doesn't matter.  Order does matter when you use several options
of the same kind; for example, if you specify @samp{-L} more than once,
the directories are searched in the order specified.

Many options have long names starting with @samp{-f} or with
@samp{-W}---for example, @samp{-fforce-mem},
@samp{-fstrength-reduce}, @samp{-Wformat} and so on.  Most of
these have both positive and negative forms; the negative form of
@samp{-ffoo} would be @samp{-fno-foo}.  This manual documents
only one of these two forms, whichever one is not the default.

@menu
* Option Summary::	Brief list of all options, without explanations.
* Overall Options::     Controlling the kind of output:
                        an executable, object files, assembler files,
                        or preprocessed source.
* Dialect Options::     Controlling the variant of C language compiled.
* Warning Options::     How picky should the compiler be?
* Debugging Options::   Symbol tables, measurements, and debugging dumps.
* Optimize Options::    How much optimization?
* Preprocessor Options:: Controlling header files and macro definitions.
                         Also, getting dependency information for Make.
* Assembler Options::   Passing options to the assembler.
* Link Options::        Specifying libraries and so on.
* Directory Options::   Where to find header files and libraries.
                        Where to find the compiler executable files.
* Target Options::      Running a cross-compiler, or an old version of GNU CC.
* Submodel Options::    Specifying minor hardware or convention variations,
                        such as 68010 vs 68020.
* Code Gen Options::    Specifying conventions for function calls, data layout
                        and register usage.
* Environment Variables:: Env vars that affect GNU CC.
* Running Protoize::    Automatically adding or removing function prototypes.
@end menu

@node Option Summary
@section Option Summary

Here is a summary of all the options, grouped by type.  Explanations are
in the following sections.

@table @emph
@item Overall Options
@xref{Overall Options,,Options Controlling the Kind of Output}.
@example
-c  -S  -E  -o @var{file}  -pipe  -v  -x @var{language}
@end example

@item Language Options
@xref{Dialect Options,,Options Controlling Dialect}.
@example
-ansi  -fcond-mismatch  -fno-asm  -fno-builtin
-fsigned-bitfields  -fsigned-char 
-funsigned-bitfields  -funsigned-char  -fwritable-strings
-traditional  -traditional-cpp  -trigraphs
-fall-virtual  -fdollars-in-identifiers  -fenum-int-equiv
-fno-strict-prototype  -fthis-is-variable
@end example

@item Warning Options
@xref{Warning Options,,Options to Request or Suppress Warnings}.
@example
-fsyntax-only  -pedantic  -pedantic-errors
-w  -W  -Wall  -Waggregate-return 
-Wcast-align  -Wcast-qual  -Wcomment  -Wconversion  -Werror
-Wformat  -Wid-clash-@var{len}  -Wenum-clash  -Wimplicit  -Wimport
-Winline -Wmissing-prototypes  -Wnested-externs  -Wparentheses
-Wpointer-arith  -Wredundant-decls  -Wreturn-type  -Wshadow
-Wstrict-prototypes  -Wswitch  -Wtraditional  -Wtrigraphs
-Wuninitialized  -Wunused  -Wwrite-strings  -Wchar-subscripts
@end example

@item Debugging Options
@xref{Debugging Options,,Options for Debugging Your Program or GCC}.
@example
-a  -d@var{letters}  -fpretend-float 
-g  -g@var{level} -ggdb  -gdwarf -gdwarf+
-gstabs  -gstabs+  -gcoff -gxcoff -gxcoff+
-p  -pg  -save-temps
@end example

@item Optimization Options
@xref{Optimize Options,,Options that Control Optimization}.
@example
-fcaller-saves  -fcse-follow-jumps  -fcse-skip-blocks
-fdelayed-branch   -fexpensive-optimizations  -ffast-math 
-ffloat-store  -fforce-addr  -fforce-mem
-finline-functions  -fkeep-inline-functions  -fno-defer-pop
-fno-function-cse  -fno-inline  -fno-peephole  -fomit-frame-pointer
-frerun-cse-after-loop  -fschedule-insns  -fschedule-insns2
-fstrength-reduce  -fthread-jumps
-funroll-all-loops  -funroll-loops 
-felide-constructors  -fmemoize-lookups  -fno-default-inline
-O  -O2
@end example

@item Preprocessor Options
@xref{Preprocessor Options,,Options Controlling the Preprocessor}.
@example
-A@var{assertion}  -C  -dD  -dM  -dN
-D@var{macro}@r{[}=@var{defn}@r{]}  -E  -H
-include @var{file}  -imacros @var{file}
-M  -MD  -MM  -MMD  -nostdinc  -P  -trigraphs  -U@var{macro}
@end example

@item Assembler Option
@xref{Assembler Options,,Passing Options to the Assembler}.
@example
-Wa,@var{option}
@end example

@item Linker Options
@xref{Link Options,,Options for Linking}.
@example
@var{object-file-name}
-l@var{library}  -nostdlib  
-static  -shared  -symbolic  
-Xlinker @var{option}
-u @var{symbol}
@end example

@item Directory Options
@xref{Directory Options,,Options for Directory Search}.
@example
-B@var{prefix}  -I@var{dir}  -I-  -L@var{dir}
@end example

@item Target Options
@xref{Target Options,,Target Machine and Compiler Version}.
@example
-b @var{machine}  -V @var{version}
@end example

@item Machine Dependent Options
@xref{Submodel Options,,Hardware Models and Configurations}.
@example
@emph{M680x0 Options}
-m68000 -m68020 -m68020-40 -m68030 -m68040 -m68881 -mbitfield
-mc68000 -mc68020 -mfpa -mnobitfield -mrtd -mshort -msoft-float

@emph{VAX Options}
-mg -mgnu -munix

@emph{SPARC Options}
-mforce-align  -mno-epilogue
@c -mfpu turned off below w/@ignore for some reason.

@emph{Convex Options}
-margcount -mc1 -mc2 -mnoargcount

@emph{AMD29K Options}
-m29000 -m29050 -mbw -mdw -mkernel-registers -mlarge 
-mnbw -mnodw -msmall -mstack-check -muser-registers

@emph{M88K Options}
-m88000 -m88100 -m88110 -mbig-pic -mcheck-zero-division
-mhandle-large-shift -midentify-revision
-mno-check-zero-division -mno-ocs-debug-info
-mno-ocs-frame-position -mno-optimize-arg-area -mno-underscores
-mocs-debug-info -mocs-frame-position -moptimize-arg-area
-mshort-data-@var{num} -msvr3 -msvr4 -mtrap-large-shift
-muse-div-instruction -mversion-03.00 -mwarn-passed-structs

@emph{RS/6000 Options}
-mfp-in-toc -mno-fop-in-toc

@emph{RT Options}
-mcall-lib-mul -mfp-arg-in-fpregs -mfp-arg-in-gregs
-mfull-fp-blocks -mhc-struct-return -min-line-mul
-mminimum-fp-blocks -mnohc-struct-return

@emph{MIPS Options}
-mcpu=@var{cpu type} -mips2 -mips3 -mint64 -mlong64 -mlonglong128
-mmips-as -mgas -mrnames -mno-rnames -mgpopt -mno-gpopt -mstats
-mno-stats -mmemcpy -mno-memcpy -mno-mips-tfile -mmips-tfile
-msoft-float -mhard-float -mabicalls -mno-abicalls -mhalf-pic
-mno-half-pic -G @var{num} -nocpp

@emph{i386 Options}
-m486 -mno-486 -msoft-float -msvr3-shlib -mieee-fp
-mno-fp-ret-in-387

@emph{HPPA Options}
-mno-bss
-mpa-risc-1-0
-mpa-risc-1-1
-mkernel
-mshared-libs
-mno-shared-libs
-mlong-calls

@emph{Intel 960 Options}
-m@var{cpu type}
-mnumerics -msoft-float
-mcode-align -mno-code-align
-mleaf-procedures -mno-leaf-procedures
-mtail-call -mno-tail-call
-mcomplex-addr -mno-complex-addr
-mclean-linkage -mno-clean-linkage
-mic-compat -mic2.0-compat -mic3.0-compat
-masm-compat -mintel-asm
-mstrict-align -mno-strict-align
-mold-align -mno-old-align

@emph{DEC Alpha Options}
-mfp-regs -mno-fp-regs -mno-soft-float -msoft-float 

@emph{System V Options}
-G  -Qy  -Qn  -YP,@var{paths}  -Ym,@var{dir}
@end example

@item Code Generation Options
@xref{Code Gen Options,,Options for Code Generation Conventions}.
@example
-fcall-saved-@var{reg}  -fcall-used-@var{reg}  -ffixed-@var{reg}
-finhibit-size-directive  -fnonnull-objects  -fno-common
-fno-ident  -fno-gnu-linker  -fpcc-struct-return  -fpic  -fPIC
-fshared-data  -fshort-enums  -fshort-double  -fvolatile
-fverbose-asm
@end example
@end table

@menu
* Overall Options::     Controlling the kind of output:
                        an executable, object files, assembler files,
                        or preprocessed source.
* Dialect Options::     Controlling the variant of C language compiled.
* Warning Options::     How picky should the compiler be?
* Debugging Options::   Symbol tables, measurements, and debugging dumps.
* Optimize Options::    How much optimization?
* Preprocessor Options:: Controlling header files and macro definitions.
                         Also, getting dependency information for Make.
* Assembler Options::   Passing options to the assembler.
* Link Options::        Specifying libraries and so on.
* Directory Options::   Where to find header files and libraries.
                        Where to find the compiler executable files.
* Target Options::      Running a cross-compiler, or an old version of GNU CC.
@end menu

@node Overall Options
@section Options Controlling the Kind of Output

Compilation can involve up to four stages: preprocessing, compilation
proper, assembly and linking, always in that order.  The first three
stages apply to an individual source file, and end by producing an
object file; linking combines all the object files (those newly
compiled, and those specified as input) into an executable file.

@cindex file name suffix
For any given input file, the file name suffix determines what kind of
compilation is done:

@table @code
@item @var{file}.c
C source code which must be preprocessed.

@item @var{file}.i
C source code which should not be preprocessed.

@item @var{file}.ii
C++ source code which should not be preprocessed.

@item @var{file}.m
Objective-C source code.  Note that you must link with the library
@file{libobjc.a} to make an Objective-C program work.

@item @var{file}.h
C header file (not to be compiled or linked).

@item @var{file}.cc
@itemx @var{file}.cxx
@itemx @var{file}.C
C++ source code which must be preprocessed.

@item @var{file}.s 
Assembler code.

@item @var{file}.S
Assembler code which must be preprocessed.

@item @var{other}
An object file to be fed straight into linking.
Any file name with no recognized suffix is treated this way.
@end table

You can specify the input language explicitly with the @samp{-x} option:

@table @code
@item -x @var{language}
Specify explicitly the @var{language} for the following input files
(rather than choosing a default based on the file name suffix).
This option applies to all following input files until
the next @samp{-x} option.  Possible values of @var{language} are
@samp{c}, @samp{objective-c}, @samp{c-header}, @samp{c++},
@samp{cpp-output}, @samp{assembler}, and @samp{assembler-with-cpp}.

@item -x none
Turn off any specification of a language, so that subsequent files are
handled according to their file name suffixes (as they are if @samp{-x}
has not been used at all).
@end table

If you only want some of the stages of compilation, you can use
@samp{-x} (or filename suffixes) to tell @code{gcc} where to start, and
one of the options @samp{-c}, @samp{-S}, or @samp{-E} to say where
@code{gcc} is to stop.  Note that some combinations (for example,
@samp{-x cpp-output -E} instruct @code{gcc} to do nothing at all.

@table @code
@item -c
Compile or assemble the source files, but do not link.  The linking
stage simply is not done.  The ultimate output is in the form of an
object file for each source file.

By default, the object file name for a source file is made by replacing