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