1<html lang="en"> 2<head> 3<title>Link 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="Assembler-Options.html#Assembler-Options" title="Assembler Options"> 10<link rel="next" href="Directory-Options.html#Directory-Options" title="Directory Options"> 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="Link-Options"></a> 51<p> 52Next: <a rel="next" accesskey="n" href="Directory-Options.html#Directory-Options">Directory Options</a>, 53Previous: <a rel="previous" accesskey="p" href="Assembler-Options.html#Assembler-Options">Assembler Options</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.13 Options for Linking</h3> 59 60<p><a name="index-link-options-967"></a><a name="index-options_002c-linking-968"></a> 61These options come into play when the compiler links object files into 62an executable output file. They are meaningless if the compiler is 63not doing a link step. 64 65 66<a name="index-file-names-969"></a> 67<dl><dt><var>object-file-name</var><dd>A file name that does not end in a special recognized suffix is 68considered to name an object file or library. (Object files are 69distinguished from libraries by the linker according to the file 70contents.) If linking is done, these object files are used as input 71to the linker. 72 73 <br><dt><code>-c</code><dt><code>-S</code><dt><code>-E</code><dd><a name="index-c-970"></a><a name="index-S-971"></a><a name="index-E-972"></a>If any of these options is used, then the linker is not run, and 74object file names should not be used as arguments. See <a href="Overall-Options.html#Overall-Options">Overall Options</a>. 75 76 <p><a name="index-Libraries-973"></a><br><dt><code>-l</code><var>library</var><dt><code>-l </code><var>library</var><dd><a name="index-l-974"></a>Search the library named <var>library</var> when linking. (The second 77alternative with the library as a separate argument is only for 78POSIX compliance and is not recommended.) 79 80 <p>It makes a difference where in the command you write this option; the 81linker searches and processes libraries and object files in the order they 82are specified. Thus, ‘<samp><span class="samp">foo.o -lz bar.o</span></samp>’ searches library ‘<samp><span class="samp">z</span></samp>’ 83after file <samp><span class="file">foo.o</span></samp> but before <samp><span class="file">bar.o</span></samp>. If <samp><span class="file">bar.o</span></samp> refers 84to functions in ‘<samp><span class="samp">z</span></samp>’, those functions may not be loaded. 85 86 <p>The linker searches a standard list of directories for the library, 87which is actually a file named <samp><span class="file">lib</span><var>library</var><span class="file">.a</span></samp>. The linker 88then uses this file as if it had been specified precisely by name. 89 90 <p>The directories searched include several standard system directories 91plus any that you specify with <samp><span class="option">-L</span></samp>. 92 93 <p>Normally the files found this way are library files—archive files 94whose members are object files. The linker handles an archive file by 95scanning through it for members which define symbols that have so far 96been referenced but not defined. But if the file that is found is an 97ordinary object file, it is linked in the usual fashion. The only 98difference between using an <samp><span class="option">-l</span></samp> option and specifying a file name 99is that <samp><span class="option">-l</span></samp> surrounds <var>library</var> with ‘<samp><span class="samp">lib</span></samp>’ and ‘<samp><span class="samp">.a</span></samp>’ 100and searches several directories. 101 102 <br><dt><code>-lobjc</code><dd><a name="index-lobjc-975"></a>You need this special case of the <samp><span class="option">-l</span></samp> option in order to 103link an Objective-C or Objective-C++ program. 104 105 <br><dt><code>-nostartfiles</code><dd><a name="index-nostartfiles-976"></a>Do not use the standard system startup files when linking. 106The standard system libraries are used normally, unless <samp><span class="option">-nostdlib</span></samp> 107or <samp><span class="option">-nodefaultlibs</span></samp> is used. 108 109 <br><dt><code>-nodefaultlibs</code><dd><a name="index-nodefaultlibs-977"></a>Do not use the standard system libraries when linking. 110Only the libraries you specify will be passed to the linker, options 111specifying linkage of the system libraries, such as <code>-static-libgcc</code> 112or <code>-shared-libgcc</code>, will be ignored. 113The standard startup files are used normally, unless <samp><span class="option">-nostartfiles</span></samp> 114is used. The compiler may generate calls to <code>memcmp</code>, 115<code>memset</code>, <code>memcpy</code> and <code>memmove</code>. 116These entries are usually resolved by entries in 117libc. These entry points should be supplied through some other 118mechanism when this option is specified. 119 120 <br><dt><code>-nostdlib</code><dd><a name="index-nostdlib-978"></a>Do not use the standard system startup files or libraries when linking. 121No startup files and only the libraries you specify will be passed to 122the linker, options specifying linkage of the system libraries, such as 123<code>-static-libgcc</code> or <code>-shared-libgcc</code>, will be ignored. 124The compiler may generate calls to <code>memcmp</code>, <code>memset</code>, 125<code>memcpy</code> and <code>memmove</code>. 126These entries are usually resolved by entries in 127libc. These entry points should be supplied through some other 128mechanism when this option is specified. 129 130 <p><a name="index-g_t_0040option_007b_002dlgcc_007d_002c-use-with-_0040option_007b_002dnostdlib_007d-979"></a><a name="index-g_t_0040option_007b_002dnostdlib_007d-and-unresolved-references-980"></a><a name="index-unresolved-references-and-_0040option_007b_002dnostdlib_007d-981"></a><a name="index-g_t_0040option_007b_002dlgcc_007d_002c-use-with-_0040option_007b_002dnodefaultlibs_007d-982"></a><a name="index-g_t_0040option_007b_002dnodefaultlibs_007d-and-unresolved-references-983"></a><a name="index-unresolved-references-and-_0040option_007b_002dnodefaultlibs_007d-984"></a>One of the standard libraries bypassed by <samp><span class="option">-nostdlib</span></samp> and 131<samp><span class="option">-nodefaultlibs</span></samp> is <samp><span class="file">libgcc.a</span></samp>, a library of internal subroutines 132that GCC uses to overcome shortcomings of particular machines, or special 133needs for some languages. 134(See <a href="../gccint/Interface.html#Interface">Interfacing to GCC Output</a>, 135for more discussion of <samp><span class="file">libgcc.a</span></samp>.) 136In most cases, you need <samp><span class="file">libgcc.a</span></samp> even when you want to avoid 137other standard libraries. In other words, when you specify <samp><span class="option">-nostdlib</span></samp> 138or <samp><span class="option">-nodefaultlibs</span></samp> you should usually specify <samp><span class="option">-lgcc</span></samp> as well. 139This ensures that you have no unresolved references to internal GCC 140library subroutines. (For example, ‘<samp><span class="samp">__main</span></samp>’, used to ensure C++ 141constructors will be called; see <a href="../gccint/Collect2.html#Collect2"><code>collect2</code></a>.) 142 143 <br><dt><code>-pie</code><dd><a name="index-pie-985"></a>Produce a position independent executable on targets which support it. 144For predictable results, you must also specify the same set of options 145that were used to generate code (<samp><span class="option">-fpie</span></samp>, <samp><span class="option">-fPIE</span></samp>, 146or model suboptions) when you specify this option. 147 148 <br><dt><code>-rdynamic</code><dd><a name="index-rdynamic-986"></a>Pass the flag <samp><span class="option">-export-dynamic</span></samp> to the ELF linker, on targets 149that support it. This instructs the linker to add all symbols, not 150only used ones, to the dynamic symbol table. This option is needed 151for some uses of <code>dlopen</code> or to allow obtaining backtraces 152from within a program. 153 154 <br><dt><code>-s</code><dd><a name="index-s-987"></a>Remove all symbol table and relocation information from the executable. 155 156 <br><dt><code>-static</code><dd><a name="index-static-988"></a>On systems that support dynamic linking, this prevents linking with the shared 157libraries. On other systems, this option has no effect. 158 159 <br><dt><code>-shared</code><dd><a name="index-shared-989"></a>Produce a shared object which can then be linked with other objects to 160form an executable. Not all systems support this option. For predictable 161results, you must also specify the same set of options that were used to 162generate code (<samp><span class="option">-fpic</span></samp>, <samp><span class="option">-fPIC</span></samp>, or model suboptions) 163when you specify this option.<a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a> 164 165 <br><dt><code>-shared-libgcc</code><dt><code>-static-libgcc</code><dd><a name="index-shared_002dlibgcc-990"></a><a name="index-static_002dlibgcc-991"></a>On systems that provide <samp><span class="file">libgcc</span></samp> as a shared library, these options 166force the use of either the shared or static version respectively. 167If no shared version of <samp><span class="file">libgcc</span></samp> was built when the compiler was 168configured, these options have no effect. 169 170 <p>There are several situations in which an application should use the 171shared <samp><span class="file">libgcc</span></samp> instead of the static version. The most common 172of these is when the application wishes to throw and catch exceptions 173across different shared libraries. In that case, each of the libraries 174as well as the application itself should use the shared <samp><span class="file">libgcc</span></samp>. 175 176 <p>Therefore, the G++ and GCJ drivers automatically add 177<samp><span class="option">-shared-libgcc</span></samp> whenever you build a shared library or a main 178executable, because C++ and Java programs typically use exceptions, so 179this is the right thing to do. 180 181 <p>If, instead, you use the GCC driver to create shared libraries, you may 182find that they will not always be linked with the shared <samp><span class="file">libgcc</span></samp>. 183If GCC finds, at its configuration time, that you have a non-GNU linker 184or a GNU linker that does not support option <samp><span class="option">--eh-frame-hdr</span></samp>, 185it will link the shared version of <samp><span class="file">libgcc</span></samp> into shared libraries 186by default. Otherwise, it will take advantage of the linker and optimize 187away the linking with the shared version of <samp><span class="file">libgcc</span></samp>, linking with 188the static version of libgcc by default. This allows exceptions to 189propagate through such shared libraries, without incurring relocation 190costs at library load time. 191 192 <p>However, if a library or main executable is supposed to throw or catch 193exceptions, you must link it using the G++ or GCJ driver, as appropriate 194for the languages used in the program, or using the option 195<samp><span class="option">-shared-libgcc</span></samp>, such that it is linked with the shared 196<samp><span class="file">libgcc</span></samp>. 197 198 <br><dt><code>-static-libstdc++</code><dd>When the <samp><span class="command">g++</span></samp> program is used to link a C++ program, it will 199normally automatically link against <samp><span class="option">libstdc++</span></samp>. If 200<samp><span class="file">libstdc++</span></samp> is available as a shared library, and the 201<samp><span class="option">-static</span></samp> option is not used, then this will link against the 202shared version of <samp><span class="file">libstdc++</span></samp>. That is normally fine. However, it 203is sometimes useful to freeze the version of <samp><span class="file">libstdc++</span></samp> used by 204the program without going all the way to a fully static link. The 205<samp><span class="option">-static-libstdc++</span></samp> option directs the <samp><span class="command">g++</span></samp> driver to 206link <samp><span class="file">libstdc++</span></samp> statically, without necessarily linking other 207libraries statically. 208 209 <br><dt><code>-symbolic</code><dd><a name="index-symbolic-992"></a>Bind references to global symbols when building a shared object. Warn 210about any unresolved references (unless overridden by the link editor 211option ‘<samp><span class="samp">-Xlinker -z -Xlinker defs</span></samp>’). Only a few systems support 212this option. 213 214 <br><dt><code>-T </code><var>script</var><dd><a name="index-T-993"></a><a name="index-linker-script-994"></a>Use <var>script</var> as the linker script. This option is supported by most 215systems using the GNU linker. On some targets, such as bare-board 216targets without an operating system, the <samp><span class="option">-T</span></samp> option may be required 217when linking to avoid references to undefined symbols. 218 219 <br><dt><code>-Xlinker </code><var>option</var><dd><a name="index-Xlinker-995"></a>Pass <var>option</var> as an option to the linker. You can use this to 220supply system-specific linker options which GCC does not know how to 221recognize. 222 223 <p>If you want to pass an option that takes a separate argument, you must use 224<samp><span class="option">-Xlinker</span></samp> twice, once for the option and once for the argument. 225For example, to pass <samp><span class="option">-assert definitions</span></samp>, you must write 226‘<samp><span class="samp">-Xlinker -assert -Xlinker definitions</span></samp>’. It does not work to write 227<samp><span class="option">-Xlinker "-assert definitions"</span></samp>, because this passes the entire 228string as a single argument, which is not what the linker expects. 229 230 <p>When using the GNU linker, it is usually more convenient to pass 231arguments to linker options using the <samp><var>option</var><span class="option">=</span><var>value</var></samp> 232syntax than as separate arguments. For example, you can specify 233‘<samp><span class="samp">-Xlinker -Map=output.map</span></samp>’ rather than 234‘<samp><span class="samp">-Xlinker -Map -Xlinker output.map</span></samp>’. Other linkers may not support 235this syntax for command-line options. 236 237 <br><dt><code>-Wl,</code><var>option</var><dd><a name="index-Wl-996"></a>Pass <var>option</var> as an option to the linker. If <var>option</var> contains 238commas, it is split into multiple options at the commas. You can use this 239syntax to pass an argument to the option. 240For example, ‘<samp><span class="samp">-Wl,-Map,output.map</span></samp>’ passes ‘<samp><span class="samp">-Map output.map</span></samp>’ to the 241linker. When using the GNU linker, you can also get the same effect with 242‘<samp><span class="samp">-Wl,-Map=output.map</span></samp>’. 243 244 <br><dt><code>-u </code><var>symbol</var><dd><a name="index-u-997"></a>Pretend the symbol <var>symbol</var> is undefined, to force linking of 245library modules to define it. You can use <samp><span class="option">-u</span></samp> multiple times with 246different symbols to force loading of additional library modules. 247</dl> 248 249 <div class="footnote"> 250<hr> 251<h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> On some systems, ‘<samp><span class="samp">gcc -shared</span></samp>’ 252needs to build supplementary stub code for constructors to work. On 253multi-libbed systems, ‘<samp><span class="samp">gcc -shared</span></samp>’ must select the correct support 254libraries to link against. Failing to supply the correct flags may lead 255to subtle defects. Supplying them in cases where they are not necessary 256is innocuous.</p> 257 258 <hr></div> 259 260 </body></html> 261 262