1<html lang="en"> 2<head> 3<title>Overall Options - Using the GNU Compiler Collection (GCC)</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Using the GNU Compiler Collection (GCC)"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Invoking-GCC.html#Invoking-GCC" title="Invoking GCC"> 9<link rel="prev" href="Option-Summary.html#Option-Summary" title="Option Summary"> 10<link rel="next" href="Invoking-G_002b_002b.html#Invoking-G_002b_002b" title="Invoking G++"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 141998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 152010 Free Software Foundation, Inc. 16 17Permission is granted to copy, distribute and/or modify this document 18under the terms of the GNU Free Documentation License, Version 1.3 or 19any later version published by the Free Software Foundation; with the 20Invariant Sections being ``Funding Free Software'', the Front-Cover 21Texts being (a) (see below), and with the Back-Cover Texts being (b) 22(see below). A copy of the license is included in the section entitled 23``GNU Free Documentation License''. 24 25(a) The FSF's Front-Cover Text is: 26 27 A GNU Manual 28 29(b) The FSF's Back-Cover Text is: 30 31 You have freedom to copy and modify this GNU Manual, like GNU 32 software. Copies published by the Free Software Foundation raise 33 funds for GNU development.--> 34<meta http-equiv="Content-Style-Type" content="text/css"> 35<style type="text/css"><!-- 36 pre.display { font-family:inherit } 37 pre.format { font-family:inherit } 38 pre.smalldisplay { font-family:inherit; font-size:smaller } 39 pre.smallformat { font-family:inherit; font-size:smaller } 40 pre.smallexample { font-size:smaller } 41 pre.smalllisp { font-size:smaller } 42 span.sc { font-variant:small-caps } 43 span.roman { font-family:serif; font-weight:normal; } 44 span.sansserif { font-family:sans-serif; font-weight:normal; } 45--></style> 46<link rel="stylesheet" type="text/css" href="../cs.css"> 47</head> 48<body> 49<div class="node"> 50<a name="Overall-Options"></a> 51<p> 52Next: <a rel="next" accesskey="n" href="Invoking-G_002b_002b.html#Invoking-G_002b_002b">Invoking G++</a>, 53Previous: <a rel="previous" accesskey="p" href="Option-Summary.html#Option-Summary">Option Summary</a>, 54Up: <a rel="up" accesskey="u" href="Invoking-GCC.html#Invoking-GCC">Invoking GCC</a> 55<hr> 56</div> 57 58<h3 class="section">3.2 Options Controlling the Kind of Output</h3> 59 60<p>Compilation can involve up to four stages: preprocessing, compilation 61proper, assembly and linking, always in that order. GCC is capable of 62preprocessing and compiling several files either into several 63assembler input files, or into one assembler input file; then each 64assembler input file produces an object file, and linking combines all 65the object files (those newly compiled, and those specified as input) 66into an executable file. 67 68 <p><a name="index-file-name-suffix-74"></a>For any given input file, the file name suffix determines what kind of 69compilation is done: 70 71 <dl> 72<dt><var>file</var><code>.c</code><dd>C source code which must be preprocessed. 73 74 <br><dt><var>file</var><code>.i</code><dd>C source code which should not be preprocessed. 75 76 <br><dt><var>file</var><code>.ii</code><dd>C++ source code which should not be preprocessed. 77 78 <br><dt><var>file</var><code>.m</code><dd>Objective-C source code. Note that you must link with the <samp><span class="file">libobjc</span></samp> 79library to make an Objective-C program work. 80 81 <br><dt><var>file</var><code>.mi</code><dd>Objective-C source code which should not be preprocessed. 82 83 <br><dt><var>file</var><code>.mm</code><dt><var>file</var><code>.M</code><dd>Objective-C++ source code. Note that you must link with the <samp><span class="file">libobjc</span></samp> 84library to make an Objective-C++ program work. Note that ‘<samp><span class="samp">.M</span></samp>’ refers 85to a literal capital M. 86 87 <br><dt><var>file</var><code>.mii</code><dd>Objective-C++ source code which should not be preprocessed. 88 89 <br><dt><var>file</var><code>.h</code><dd>C, C++, Objective-C or Objective-C++ header file to be turned into a 90precompiled header (default), or C, C++ header file to be turned into an 91Ada spec (via the <samp><span class="option">-fdump-ada-spec</span></samp> switch). 92 93 <br><dt><var>file</var><code>.cc</code><dt><var>file</var><code>.cp</code><dt><var>file</var><code>.cxx</code><dt><var>file</var><code>.cpp</code><dt><var>file</var><code>.CPP</code><dt><var>file</var><code>.c++</code><dt><var>file</var><code>.C</code><dd>C++ source code which must be preprocessed. Note that in ‘<samp><span class="samp">.cxx</span></samp>’, 94the last two letters must both be literally ‘<samp><span class="samp">x</span></samp>’. Likewise, 95‘<samp><span class="samp">.C</span></samp>’ refers to a literal capital C. 96 97 <br><dt><var>file</var><code>.mm</code><dt><var>file</var><code>.M</code><dd>Objective-C++ source code which must be preprocessed. 98 99 <br><dt><var>file</var><code>.mii</code><dd>Objective-C++ source code which should not be preprocessed. 100 101 <br><dt><var>file</var><code>.hh</code><dt><var>file</var><code>.H</code><dt><var>file</var><code>.hp</code><dt><var>file</var><code>.hxx</code><dt><var>file</var><code>.hpp</code><dt><var>file</var><code>.HPP</code><dt><var>file</var><code>.h++</code><dt><var>file</var><code>.tcc</code><dd>C++ header file to be turned into a precompiled header or Ada spec. 102 103 <br><dt><var>file</var><code>.f</code><dt><var>file</var><code>.for</code><dt><var>file</var><code>.ftn</code><dd>Fixed form Fortran source code which should not be preprocessed. 104 105 <br><dt><var>file</var><code>.F</code><dt><var>file</var><code>.FOR</code><dt><var>file</var><code>.fpp</code><dt><var>file</var><code>.FPP</code><dt><var>file</var><code>.FTN</code><dd>Fixed form Fortran source code which must be preprocessed (with the traditional 106preprocessor). 107 108 <br><dt><var>file</var><code>.f90</code><dt><var>file</var><code>.f95</code><dt><var>file</var><code>.f03</code><dt><var>file</var><code>.f08</code><dd>Free form Fortran source code which should not be preprocessed. 109 110 <br><dt><var>file</var><code>.F90</code><dt><var>file</var><code>.F95</code><dt><var>file</var><code>.F03</code><dt><var>file</var><code>.F08</code><dd>Free form Fortran source code which must be preprocessed (with the 111traditional preprocessor). 112 113 <br><dt><var>file</var><code>.go</code><dd>Go source code. 114 115 <!-- FIXME: Descriptions of Java file types. --> 116 <!-- @var{file}.java --> 117 <!-- @var{file}.class --> 118 <!-- @var{file}.zip --> 119 <!-- @var{file}.jar --> 120 <br><dt><var>file</var><code>.ads</code><dd>Ada source code file which contains a library unit declaration (a 121declaration of a package, subprogram, or generic, or a generic 122instantiation), or a library unit renaming declaration (a package, 123generic, or subprogram renaming declaration). Such files are also 124called <dfn>specs</dfn>. 125 126 <br><dt><var>file</var><code>.adb</code><dd>Ada source code file containing a library unit body (a subprogram or 127package body). Such files are also called <dfn>bodies</dfn>. 128 129 <!-- GCC also knows about some suffixes for languages not yet included: --> 130 <!-- Pascal: --> 131 <!-- @var{file}.p --> 132 <!-- @var{file}.pas --> 133 <!-- Ratfor: --> 134 <!-- @var{file}.r --> 135 <br><dt><var>file</var><code>.s</code><dd>Assembler code. 136 137 <br><dt><var>file</var><code>.S</code><dt><var>file</var><code>.sx</code><dd>Assembler code which must be preprocessed. 138 139 <br><dt><var>other</var><dd>An object file to be fed straight into linking. 140Any file name with no recognized suffix is treated this way. 141</dl> 142 143 <p><a name="index-x-75"></a>You can specify the input language explicitly with the <samp><span class="option">-x</span></samp> option: 144 145 <dl> 146<dt><code>-x </code><var>language</var><dd>Specify explicitly the <var>language</var> for the following input files 147(rather than letting the compiler choose a default based on the file 148name suffix). This option applies to all following input files until 149the next <samp><span class="option">-x</span></samp> option. Possible values for <var>language</var> are: 150 <pre class="smallexample"> c c-header cpp-output 151 c++ c++-header c++-cpp-output 152 objective-c objective-c-header objective-c-cpp-output 153 objective-c++ objective-c++-header objective-c++-cpp-output 154 assembler assembler-with-cpp 155 ada 156 f77 f77-cpp-input f95 f95-cpp-input 157 go 158 java 159</pre> 160 <br><dt><code>-x none</code><dd>Turn off any specification of a language, so that subsequent files are 161handled according to their file name suffixes (as they are if <samp><span class="option">-x</span></samp> 162has not been used at all). 163 164 <br><dt><code>-pass-exit-codes</code><dd><a name="index-pass_002dexit_002dcodes-76"></a>Normally the <samp><span class="command">gcc</span></samp> program will exit with the code of 1 if any 165phase of the compiler returns a non-success return code. If you specify 166<samp><span class="option">-pass-exit-codes</span></samp>, the <samp><span class="command">gcc</span></samp> program will instead return with 167numerically highest error produced by any phase that returned an error 168indication. The C, C++, and Fortran frontends return 4, if an internal 169compiler error is encountered. 170</dl> 171 172 <p>If you only want some of the stages of compilation, you can use 173<samp><span class="option">-x</span></samp> (or filename suffixes) to tell <samp><span class="command">gcc</span></samp> where to start, and 174one of the options <samp><span class="option">-c</span></samp>, <samp><span class="option">-S</span></samp>, or <samp><span class="option">-E</span></samp> to say where 175<samp><span class="command">gcc</span></samp> is to stop. Note that some combinations (for example, 176‘<samp><span class="samp">-x cpp-output -E</span></samp>’) instruct <samp><span class="command">gcc</span></samp> to do nothing at all. 177 178 <dl> 179<dt><code>-c</code><dd><a name="index-c-77"></a>Compile or assemble the source files, but do not link. The linking 180stage simply is not done. The ultimate output is in the form of an 181object file for each source file. 182 183 <p>By default, the object file name for a source file is made by replacing 184the suffix ‘<samp><span class="samp">.c</span></samp>’, ‘<samp><span class="samp">.i</span></samp>’, ‘<samp><span class="samp">.s</span></samp>’, etc., with ‘<samp><span class="samp">.o</span></samp>’. 185 186 <p>Unrecognized input files, not requiring compilation or assembly, are 187ignored. 188 189 <br><dt><code>-S</code><dd><a name="index-S-78"></a>Stop after the stage of compilation proper; do not assemble. The output 190is in the form of an assembler code file for each non-assembler input 191file specified. 192 193 <p>By default, the assembler file name for a source file is made by 194replacing the suffix ‘<samp><span class="samp">.c</span></samp>’, ‘<samp><span class="samp">.i</span></samp>’, etc., with ‘<samp><span class="samp">.s</span></samp>’. 195 196 <p>Input files that don't require compilation are ignored. 197 198 <br><dt><code>-E</code><dd><a name="index-E-79"></a>Stop after the preprocessing stage; do not run the compiler proper. The 199output is in the form of preprocessed source code, which is sent to the 200standard output. 201 202 <p>Input files which don't require preprocessing are ignored. 203 204 <p><a name="index-output-file-option-80"></a><br><dt><code>-o </code><var>file</var><dd><a name="index-o-81"></a>Place output in file <var>file</var>. This applies regardless to whatever 205sort of output is being produced, whether it be an executable file, 206an object file, an assembler file or preprocessed C code. 207 208 <p>If <samp><span class="option">-o</span></samp> is not specified, the default is to put an executable 209file in <samp><span class="file">a.out</span></samp>, the object file for 210<samp><var>source</var><span class="file">.</span><var>suffix</var></samp> in <samp><var>source</var><span class="file">.o</span></samp>, its 211assembler file in <samp><var>source</var><span class="file">.s</span></samp>, a precompiled header file in 212<samp><var>source</var><span class="file">.</span><var>suffix</var><span class="file">.gch</span></samp>, and all preprocessed C source on 213standard output. 214 215 <br><dt><code>-v</code><dd><a name="index-v-82"></a>Print (on standard error output) the commands executed to run the stages 216of compilation. Also print the version number of the compiler driver 217program and of the preprocessor and the compiler proper. 218 219 <br><dt><code>-###</code><dd><a name="index-g_t_0023_0023_0023-83"></a>Like <samp><span class="option">-v</span></samp> except the commands are not executed and arguments 220are quoted unless they contain only alphanumeric characters or <code>./-_</code>. 221This is useful for shell scripts to capture the driver-generated command lines. 222 223 <br><dt><code>-pipe</code><dd><a name="index-pipe-84"></a>Use pipes rather than temporary files for communication between the 224various stages of compilation. This fails to work on some systems where 225the assembler is unable to read from a pipe; but the GNU assembler has 226no trouble. 227 228 <br><dt><code>--help</code><dd><a name="index-help-85"></a>Print (on the standard output) a description of the command line options 229understood by <samp><span class="command">gcc</span></samp>. If the <samp><span class="option">-v</span></samp> option is also specified 230then <samp><span class="option">--help</span></samp> will also be passed on to the various processes 231invoked by <samp><span class="command">gcc</span></samp>, so that they can display the command line options 232they accept. If the <samp><span class="option">-Wextra</span></samp> option has also been specified 233(prior to the <samp><span class="option">--help</span></samp> option), then command line options which 234have no documentation associated with them will also be displayed. 235 236 <br><dt><code>--target-help</code><dd><a name="index-target_002dhelp-86"></a>Print (on the standard output) a description of target-specific command 237line options for each tool. For some targets extra target-specific 238information may also be printed. 239 240 <br><dt><code>--help={</code><var>class</var><span class="roman">|[</span><code>^</code><span class="roman">]</span><var>qualifier</var><code>}</code><span class="roman">[</span><code>,...</code><span class="roman">]</span><dd>Print (on the standard output) a description of the command line 241options understood by the compiler that fit into all specified classes 242and qualifiers. These are the supported classes: 243 244 <dl> 245<dt>‘<samp><span class="samp">optimizers</span></samp>’<dd>This will display all of the optimization options supported by the 246compiler. 247 248 <br><dt>‘<samp><span class="samp">warnings</span></samp>’<dd>This will display all of the options controlling warning messages 249produced by the compiler. 250 251 <br><dt>‘<samp><span class="samp">target</span></samp>’<dd>This will display target-specific options. Unlike the 252<samp><span class="option">--target-help</span></samp> option however, target-specific options of the 253linker and assembler will not be displayed. This is because those 254tools do not currently support the extended <samp><span class="option">--help=</span></samp> syntax. 255 256 <br><dt>‘<samp><span class="samp">params</span></samp>’<dd>This will display the values recognized by the <samp><span class="option">--param</span></samp> 257option. 258 259 <br><dt><var>language</var><dd>This will display the options supported for <var>language</var>, where 260<var>language</var> is the name of one of the languages supported in this 261version of GCC. 262 263 <br><dt>‘<samp><span class="samp">common</span></samp>’<dd>This will display the options that are common to all languages. 264</dl> 265 266 <p>These are the supported qualifiers: 267 268 <dl> 269<dt>‘<samp><span class="samp">undocumented</span></samp>’<dd>Display only those options which are undocumented. 270 271 <br><dt>‘<samp><span class="samp">joined</span></samp>’<dd>Display options which take an argument that appears after an equal 272sign in the same continuous piece of text, such as: 273‘<samp><span class="samp">--help=target</span></samp>’. 274 275 <br><dt>‘<samp><span class="samp">separate</span></samp>’<dd>Display options which take an argument that appears as a separate word 276following the original option, such as: ‘<samp><span class="samp">-o output-file</span></samp>’. 277</dl> 278 279 <p>Thus for example to display all the undocumented target-specific 280switches supported by the compiler the following can be used: 281 282 <pre class="smallexample"> --help=target,undocumented 283</pre> 284 <p>The sense of a qualifier can be inverted by prefixing it with the 285‘<samp><span class="samp">^</span></samp>’ character, so for example to display all binary warning 286options (i.e., ones that are either on or off and that do not take an 287argument), which have a description the following can be used: 288 289 <pre class="smallexample"> --help=warnings,^joined,^undocumented 290</pre> 291 <p>The argument to <samp><span class="option">--help=</span></samp> should not consist solely of inverted 292qualifiers. 293 294 <p>Combining several classes is possible, although this usually 295restricts the output by so much that there is nothing to display. One 296case where it does work however is when one of the classes is 297<var>target</var>. So for example to display all the target-specific 298optimization options the following can be used: 299 300 <pre class="smallexample"> --help=target,optimizers 301</pre> 302 <p>The <samp><span class="option">--help=</span></samp> option can be repeated on the command line. Each 303successive use will display its requested class of options, skipping 304those that have already been displayed. 305 306 <p>If the <samp><span class="option">-Q</span></samp> option appears on the command line before the 307<samp><span class="option">--help=</span></samp> option, then the descriptive text displayed by 308<samp><span class="option">--help=</span></samp> is changed. Instead of describing the displayed 309options, an indication is given as to whether the option is enabled, 310disabled or set to a specific value (assuming that the compiler 311knows this at the point where the <samp><span class="option">--help=</span></samp> option is used). 312 313 <p>Here is a truncated example from the ARM port of <samp><span class="command">gcc</span></samp>: 314 315 <pre class="smallexample"> % gcc -Q -mabi=2 --help=target -c 316 The following options are target specific: 317 -mabi= 2 318 -mabort-on-noreturn [disabled] 319 -mapcs [disabled] 320</pre> 321 <p>The output is sensitive to the effects of previous command line 322options, so for example it is possible to find out which optimizations 323are enabled at <samp><span class="option">-O2</span></samp> by using: 324 325 <pre class="smallexample"> -Q -O2 --help=optimizers 326</pre> 327 <p>Alternatively you can discover which binary optimizations are enabled 328by <samp><span class="option">-O3</span></samp> by using: 329 330 <pre class="smallexample"> gcc -c -Q -O3 --help=optimizers > /tmp/O3-opts 331 gcc -c -Q -O2 --help=optimizers > /tmp/O2-opts 332 diff /tmp/O2-opts /tmp/O3-opts | grep enabled 333</pre> 334 <br><dt><code>-no-canonical-prefixes</code><dd><a name="index-no_002dcanonical_002dprefixes-87"></a>Do not expand any symbolic links, resolve references to ‘<samp><span class="samp">/../</span></samp>’ 335or ‘<samp><span class="samp">/./</span></samp>’, or make the path absolute when generating a relative 336prefix. 337 338 <br><dt><code>--version</code><dd><a name="index-version-88"></a>Display the version number and copyrights of the invoked GCC. 339 340 <br><dt><code>-wrapper</code><dd><a name="index-wrapper-89"></a>Invoke all subcommands under a wrapper program. The name of the 341wrapper program and its parameters are passed as a comma separated 342list. 343 344 <pre class="smallexample"> gcc -c t.c -wrapper gdb,--args 345</pre> 346 <p>This will invoke all subprograms of <samp><span class="command">gcc</span></samp> under 347‘<samp><span class="samp">gdb --args</span></samp>’, thus the invocation of <samp><span class="command">cc1</span></samp> will be 348‘<samp><span class="samp">gdb --args cc1 ...</span></samp>’. 349 350 <br><dt><code>-fplugin=</code><var>name</var><code>.so</code><dd>Load the plugin code in file <var>name</var>.so, assumed to be a 351shared object to be dlopen'd by the compiler. The base name of 352the shared object file is used to identify the plugin for the 353purposes of argument parsing (See 354<samp><span class="option">-fplugin-arg-</span><var>name</var><span class="option">-</span><var>key</var><span class="option">=</span><var>value</var></samp> below). 355Each plugin should define the callback functions specified in the 356Plugins API. 357 358 <br><dt><code>-fplugin-arg-</code><var>name</var><code>-</code><var>key</var><code>=</code><var>value</var><dd>Define an argument called <var>key</var> with a value of <var>value</var> 359for the plugin called <var>name</var>. 360 361 <br><dt><code>-fdump-ada-spec</code><span class="roman">[</span><code>-slim</code><span class="roman">]</span><dd>For C and C++ source and include files, generate corresponding Ada 362specs. See <a href="../gnat_ugn/Generating-Ada-Bindings-for-C-and-C_002b_002b-headers.html#Generating-Ada-Bindings-for-C-and-C_002b_002b-headers">Generating Ada Bindings for C and C++ headers</a>, which provides detailed documentation on this feature. 363 364 <br><dt><code>-fdump-go-spec=</code><var>file</var><dd>For input files in any language, generate corresponding Go 365declarations in <var>file</var>. This generates Go <code>const</code>, 366<code>type</code>, <code>var</code>, and <code>func</code> declarations which may be a 367useful way to start writing a Go interface to code written in some 368other language. 369 370 <!-- This file is designed to be included in manuals that use --> 371 <!-- expandargv. --> 372 <br><dt><code>@</code><var>file</var><dd>Read command-line options from <var>file</var>. The options read are 373inserted in place of the original @<var>file</var> option. If <var>file</var> 374does not exist, or cannot be read, then the option will be treated 375literally, and not removed. 376 377 <p>Options in <var>file</var> are separated by whitespace. A whitespace 378character may be included in an option by surrounding the entire 379option in either single or double quotes. Any character (including a 380backslash) may be included by prefixing the character to be included 381with a backslash. The <var>file</var> may itself contain additional 382@<var>file</var> options; any such options will be processed recursively. 383</dl> 384 385 </body></html> 386 387