gcc: Overall Options
1
1 3.2 Options Controlling the Kind of Output
1 ==========================================
1
1 Compilation can involve up to four stages: preprocessing, compilation
1 proper, assembly and linking, always in that order. GCC is capable of
1 preprocessing and compiling several files either into several assembler
1 input files, or into one assembler input file; then each assembler input
1 file produces an object file, and linking combines all the object files
1 (those newly compiled, and those specified as input) into an executable
1 file.
1
1 For any given input file, the file name suffix determines what kind of
1 compilation is done:
1
1 'FILE.c'
1 C source code that must be preprocessed.
1
1 'FILE.i'
1 C source code that should not be preprocessed.
1
1 'FILE.ii'
1 C++ source code that should not be preprocessed.
1
1 'FILE.m'
1 Objective-C source code. Note that you must link with the
1 'libobjc' library to make an Objective-C program work.
1
1 'FILE.mi'
1 Objective-C source code that should not be preprocessed.
1
1 'FILE.mm'
1 'FILE.M'
1 Objective-C++ source code. Note that you must link with the
1 'libobjc' library to make an Objective-C++ program work. Note that
1 '.M' refers to a literal capital M.
1
1 'FILE.mii'
1 Objective-C++ source code that should not be preprocessed.
1
1 'FILE.h'
1 C, C++, Objective-C or Objective-C++ header file to be turned into
1 a precompiled header (default), or C, C++ header file to be turned
1 into an Ada spec (via the '-fdump-ada-spec' switch).
1
1 'FILE.cc'
1 'FILE.cp'
1 'FILE.cxx'
1 'FILE.cpp'
1 'FILE.CPP'
1 'FILE.c++'
1 'FILE.C'
1 C++ source code that must be preprocessed. Note that in '.cxx',
1 the last two letters must both be literally 'x'. Likewise, '.C'
1 refers to a literal capital C.
1
1 'FILE.mm'
1 'FILE.M'
1 Objective-C++ source code that must be preprocessed.
1
1 'FILE.mii'
1 Objective-C++ source code that should not be preprocessed.
1
1 'FILE.hh'
1 'FILE.H'
1 'FILE.hp'
1 'FILE.hxx'
1 'FILE.hpp'
1 'FILE.HPP'
1 'FILE.h++'
1 'FILE.tcc'
1 C++ header file to be turned into a precompiled header or Ada spec.
1
1 'FILE.f'
1 'FILE.for'
1 'FILE.ftn'
1 Fixed form Fortran source code that should not be preprocessed.
1
1 'FILE.F'
1 'FILE.FOR'
1 'FILE.fpp'
1 'FILE.FPP'
1 'FILE.FTN'
1 Fixed form Fortran source code that must be preprocessed (with the
1 traditional preprocessor).
1
1 'FILE.f90'
1 'FILE.f95'
1 'FILE.f03'
1 'FILE.f08'
1 Free form Fortran source code that should not be preprocessed.
1
1 'FILE.F90'
1 'FILE.F95'
1 'FILE.F03'
1 'FILE.F08'
1 Free form Fortran source code that must be preprocessed (with the
1 traditional preprocessor).
1
1 'FILE.go'
1 Go source code.
1
1 'FILE.brig'
1 BRIG files (binary representation of HSAIL).
1
1 'FILE.ads'
1 Ada source code file that contains a library unit declaration (a
1 declaration of a package, subprogram, or generic, or a generic
1 instantiation), or a library unit renaming declaration (a package,
1 generic, or subprogram renaming declaration). Such files are also
1 called "specs".
1
1 'FILE.adb'
1 Ada source code file containing a library unit body (a subprogram
1 or package body). Such files are also called "bodies".
1
1 'FILE.s'
1 Assembler code.
1
1 'FILE.S'
1 'FILE.sx'
1 Assembler code that must be preprocessed.
1
1 'OTHER'
1 An object file to be fed straight into linking. Any file name with
1 no recognized suffix is treated this way.
1
1 You can specify the input language explicitly with the '-x' option:
1
1 '-x LANGUAGE'
1 Specify explicitly the LANGUAGE for the following input files
1 (rather than letting the compiler choose a default based on the
1 file name suffix). This option applies to all following input
1 files until the next '-x' option. Possible values for LANGUAGE
1 are:
1 c c-header cpp-output
1 c++ c++-header c++-cpp-output
1 objective-c objective-c-header objective-c-cpp-output
1 objective-c++ objective-c++-header objective-c++-cpp-output
1 assembler assembler-with-cpp
1 ada
1 f77 f77-cpp-input f95 f95-cpp-input
1 go
1 brig
1
1 '-x none'
1 Turn off any specification of a language, so that subsequent files
1 are handled according to their file name suffixes (as they are if
1 '-x' has not been used at all).
1
1 If you only want some of the stages of compilation, you can use '-x'
1 (or filename suffixes) to tell 'gcc' where to start, and one of the
1 options '-c', '-S', or '-E' to say where 'gcc' is to stop. Note that
1 some combinations (for example, '-x cpp-output -E') instruct 'gcc' to do
1 nothing at all.
1
1 '-c'
1 Compile or assemble the source files, but do not link. The linking
1 stage simply is not done. The ultimate output is in the form of an
1 object file for each source file.
1
1 By default, the object file name for a source file is made by
1 replacing the suffix '.c', '.i', '.s', etc., with '.o'.
1
1 Unrecognized input files, not requiring compilation or assembly,
1 are ignored.
1
1 '-S'
1 Stop after the stage of compilation proper; do not assemble. The
1 output is in the form of an assembler code file for each
1 non-assembler input file specified.
1
1 By default, the assembler file name for a source file is made by
1 replacing the suffix '.c', '.i', etc., with '.s'.
1
1 Input files that don't require compilation are ignored.
1
1 '-E'
1 Stop after the preprocessing stage; do not run the compiler proper.
1 The output is in the form of preprocessed source code, which is
1 sent to the standard output.
1
1 Input files that don't require preprocessing are ignored.
1
1 '-o FILE'
1 Place output in file FILE. This applies to whatever sort of output
1 is being produced, whether it be an executable file, an object
1 file, an assembler file or preprocessed C code.
1
1 If '-o' is not specified, the default is to put an executable file
1 in 'a.out', the object file for 'SOURCE.SUFFIX' in 'SOURCE.o', its
1 assembler file in 'SOURCE.s', a precompiled header file in
1 'SOURCE.SUFFIX.gch', and all preprocessed C source on standard
1 output.
1
1 '-v'
1 Print (on standard error output) the commands executed to run the
1 stages of compilation. Also print the version number of the
1 compiler driver program and of the preprocessor and the compiler
1 proper.
1
1 '-###'
1 Like '-v' except the commands are not executed and arguments are
1 quoted unless they contain only alphanumeric characters or './-_'.
1 This is useful for shell scripts to capture the driver-generated
1 command lines.
1
1 '--help'
1 Print (on the standard output) a description of the command-line
1 options understood by 'gcc'. If the '-v' option is also specified
1 then '--help' is also passed on to the various processes invoked by
1 'gcc', so that they can display the command-line options they
1 accept. If the '-Wextra' option has also been specified (prior to
1 the '--help' option), then command-line options that have no
1 documentation associated with them are also displayed.
1
1 '--target-help'
1 Print (on the standard output) a description of target-specific
1 command-line options for each tool. For some targets extra
1 target-specific information may also be printed.
1
1 '--help={CLASS|[^]QUALIFIER}[,...]'
1 Print (on the standard output) a description of the command-line
1 options understood by the compiler that fit into all specified
1 classes and qualifiers. These are the supported classes:
1
1 'optimizers'
1 Display all of the optimization options supported by the
1 compiler.
1
1 'warnings'
1 Display all of the options controlling warning messages
1 produced by the compiler.
1
1 'target'
1 Display target-specific options. Unlike the '--target-help'
1 option however, target-specific options of the linker and
1 assembler are not displayed. This is because those tools do
1 not currently support the extended '--help=' syntax.
1
1 'params'
1 Display the values recognized by the '--param' option.
1
1 LANGUAGE
1 Display the options supported for LANGUAGE, where LANGUAGE is
1 the name of one of the languages supported in this version of
1 GCC.
1
1 'common'
1 Display the options that are common to all languages.
1
1 These are the supported qualifiers:
1
1 'undocumented'
1 Display only those options that are undocumented.
1
1 'joined'
1 Display options taking an argument that appears after an equal
1 sign in the same continuous piece of text, such as:
1 '--help=target'.
1
1 'separate'
1 Display options taking an argument that appears as a separate
1 word following the original option, such as: '-o output-file'.
1
1 Thus for example to display all the undocumented target-specific
1 switches supported by the compiler, use:
1
1 --help=target,undocumented
1
1 The sense of a qualifier can be inverted by prefixing it with the
1 '^' character, so for example to display all binary warning options
1 (i.e., ones that are either on or off and that do not take an
1 argument) that have a description, use:
1
1 --help=warnings,^joined,^undocumented
1
1 The argument to '--help=' should not consist solely of inverted
1 qualifiers.
1
1 Combining several classes is possible, although this usually
1 restricts the output so much that there is nothing to display. One
1 case where it does work, however, is when one of the classes is
1 TARGET. For example, to display all the target-specific
1 optimization options, use:
1
1 --help=target,optimizers
1
1 The '--help=' option can be repeated on the command line. Each
1 successive use displays its requested class of options, skipping
1 those that have already been displayed.
1
1 If the '-Q' option appears on the command line before the '--help='
1 option, then the descriptive text displayed by '--help=' is
1 changed. Instead of describing the displayed options, an
1 indication is given as to whether the option is enabled, disabled
1 or set to a specific value (assuming that the compiler knows this
1 at the point where the '--help=' option is used).
1
1 Here is a truncated example from the ARM port of 'gcc':
1
1 % gcc -Q -mabi=2 --help=target -c
1 The following options are target specific:
1 -mabi= 2
1 -mabort-on-noreturn [disabled]
1 -mapcs [disabled]
1
1 The output is sensitive to the effects of previous command-line
1 options, so for example it is possible to find out which
1 optimizations are enabled at '-O2' by using:
1
1 -Q -O2 --help=optimizers
1
1 Alternatively you can discover which binary optimizations are
1 enabled by '-O3' by using:
1
1 gcc -c -Q -O3 --help=optimizers > /tmp/O3-opts
1 gcc -c -Q -O2 --help=optimizers > /tmp/O2-opts
1 diff /tmp/O2-opts /tmp/O3-opts | grep enabled
1
1 '--version'
1 Display the version number and copyrights of the invoked GCC.
1
1 '-pass-exit-codes'
1 Normally the 'gcc' program exits with the code of 1 if any phase of
1 the compiler returns a non-success return code. If you specify
1 '-pass-exit-codes', the 'gcc' program instead returns with the
1 numerically highest error produced by any phase returning an error
1 indication. The C, C++, and Fortran front ends return 4 if an
1 internal compiler error is encountered.
1
1 '-pipe'
1 Use pipes rather than temporary files for communication between the
1 various stages of compilation. This fails to work on some systems
1 where the assembler is unable to read from a pipe; but the GNU
1 assembler has no trouble.
1
1 '-specs=FILE'
1 Process FILE after the compiler reads in the standard 'specs' file,
1 in order to override the defaults which the 'gcc' driver program
1 uses when determining what switches to pass to 'cc1', 'cc1plus',
1 'as', 'ld', etc. More than one '-specs=FILE' can be specified on
1 the command line, and they are processed in order, from left to
1 right. ⇒Spec Files, for information about the format of the
1 FILE.
1
1 '-wrapper'
1 Invoke all subcommands under a wrapper program. The name of the
1 wrapper program and its parameters are passed as a comma separated
1 list.
1
1 gcc -c t.c -wrapper gdb,--args
1
1 This invokes all subprograms of 'gcc' under 'gdb --args', thus the
1 invocation of 'cc1' is 'gdb --args cc1 ...'.
1
1 '-ffile-prefix-map=OLD=NEW'
1 When compiling files residing in directory 'OLD', record any
1 references to them in the result of the compilation as if the files
1 resided in directory 'NEW' instead. Specifying this option is
1 equivalent to specifying all the individual '-f*-prefix-map'
1 options. This can be used to make reproducible builds that are
1 location independent. See also '-fmacro-prefix-map' and
1 '-fdebug-prefix-map'.
1
1 '-fplugin=NAME.so'
1 Load the plugin code in file NAME.so, assumed to be a shared object
1 to be dlopen'd by the compiler. The base name of the shared object
1 file is used to identify the plugin for the purposes of argument
1 parsing (See '-fplugin-arg-NAME-KEY=VALUE' below). Each plugin
1 should define the callback functions specified in the Plugins API.
1
1 '-fplugin-arg-NAME-KEY=VALUE'
1 Define an argument called KEY with a value of VALUE for the plugin
1 called NAME.
1
1 '-fdump-ada-spec[-slim]'
1 For C and C++ source and include files, generate corresponding Ada
11 specs. ⇒(gnat_ugn)Generating Ada Bindings for C and C++
headers, which provides detailed documentation on this feature.
1
1 '-fada-spec-parent=UNIT'
1 In conjunction with '-fdump-ada-spec[-slim]' above, generate Ada
1 specs as child units of parent UNIT.
1
1 '-fdump-go-spec=FILE'
1 For input files in any language, generate corresponding Go
1 declarations in FILE. This generates Go 'const', 'type', 'var',
1 and 'func' declarations which may be a useful way to start writing
1 a Go interface to code written in some other language.
1
1 '@FILE'
1 Read command-line options from FILE. The options read are inserted
1 in place of the original @FILE option. If FILE does not exist, or
1 cannot be read, then the option will be treated literally, and not
1 removed.
1
1 Options in FILE are separated by whitespace. A whitespace
1 character may be included in an option by surrounding the entire
1 option in either single or double quotes. Any character (including
1 a backslash) may be included by prefixing the character to be
1 included with a backslash. The FILE may itself contain additional
1 @FILE options; any such options will be processed recursively.
1