path: root/devdocs/gcc~13/link-options.html

<div class="section-level-extent" id="Link-Options"> <div class="nav-panel"> <p> Next: <a href="directory-options" accesskey="n" rel="next">Options for Directory Search</a>, Previous: <a href="assembler-options" accesskey="p" rel="prev">Passing Options to the Assembler</a>, Up: <a href="invoking-gcc" accesskey="u" rel="up">GCC Command Options</a> [<a href="index#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="indices" title="Index" rel="index">Index</a>]</p> </div>  <h1 class="section" id="Options-for-Linking"><span>3.15 Options for Linking<a class="copiable-link" href="#Options-for-Linking"> ¶</a></span></h1>   <p>These options come into play when the compiler links object files into an executable output file. They are meaningless if the compiler is not doing a link step. </p> <dl class="table"> <dt>
<span><code class="code"><var class="var">object-file-name</var></code><a class="copiable-link" href="#index-file-names"> ¶</a></span>
</dt> <dd>
<p>A file name that does not end in a special recognized suffix is considered to name an object file or library. (Object files are distinguished from libraries by the linker according to the file contents.) If linking is done, these object files are used as input to the linker. </p> </dd> <dt>
  <span><code class="code">-c</code><a class="copiable-link" href="#index-c-1"> ¶</a></span>
</dt> <dt><code class="code">-S</code></dt> <dt><code class="code">-E</code></dt> <dd>
<p>If any of these options is used, then the linker is not run, and object file names should not be used as arguments. See <a class="xref" href="overall-options">Options Controlling the Kind of Output</a>. </p> </dd> <dt>
<span><code class="code">-flinker-output=<var class="var">type</var></code><a class="copiable-link" href="#index-flinker-output"> ¶</a></span>
</dt> <dd>
<p>This option controls code generation of the link-time optimizer. By default the linker output is automatically determined by the linker plugin. For debugging the compiler and if incremental linking with a non-LTO object file is desired, it may be useful to control the type manually. </p> <p>If <var class="var">type</var> is ‘<samp class="samp">exec</samp>’, code generation produces a static binary. In this case <samp class="option">-fpic</samp> and <samp class="option">-fpie</samp> are both disabled. </p> <p>If <var class="var">type</var> is ‘<samp class="samp">dyn</samp>’, code generation produces a shared library. In this case <samp class="option">-fpic</samp> or <samp class="option">-fPIC</samp> is preserved, but not enabled automatically. This allows to build shared libraries without position-independent code on architectures where this is possible, i.e. on x86. </p> <p>If <var class="var">type</var> is ‘<samp class="samp">pie</samp>’, code generation produces an <samp class="option">-fpie</samp> executable. This results in similar optimizations as ‘<samp class="samp">exec</samp>’ except that <samp class="option">-fpie</samp> is not disabled if specified at compilation time. </p> <p>If <var class="var">type</var> is ‘<samp class="samp">rel</samp>’, the compiler assumes that incremental linking is done. The sections containing intermediate code for link-time optimization are merged, pre-optimized, and output to the resulting object file. In addition, if <samp class="option">-ffat-lto-objects</samp> is specified, binary code is produced for future non-LTO linking. The object file produced by incremental linking is smaller than a static library produced from the same object files. At link time the result of incremental linking also loads faster than a static library assuming that the majority of objects in the library are used. </p> <p>Finally ‘<samp class="samp">nolto-rel</samp>’ configures the compiler for incremental linking where code generation is forced, a final binary is produced, and the intermediate code for later link-time optimization is stripped. When multiple object files are linked together the resulting code is better optimized than with link-time optimizations disabled (for example, cross-module inlining happens), but most of benefits of whole program optimizations are lost. </p> <p>During the incremental link (by <samp class="option">-r</samp>) the linker plugin defaults to <samp class="option">rel</samp>. With current interfaces to GNU Binutils it is however not possible to incrementally link LTO objects and non-LTO objects into a single mixed object file. If any of object files in incremental link cannot be used for link-time optimization, the linker plugin issues a warning and uses ‘<samp class="samp">nolto-rel</samp>’. To maintain whole program optimization, it is recommended to link such objects into static library instead. Alternatively it is possible to use H.J. Lu’s binutils with support for mixed objects. </p> </dd> <dt>
<span><code class="code">-fuse-ld=bfd</code><a class="copiable-link" href="#index-fuse-ld_003dbfd"> ¶</a></span>
</dt> <dd>
<p>Use the <code class="command">bfd</code> linker instead of the default linker. </p> </dd> <dt>
<span><code class="code">-fuse-ld=gold</code><a class="copiable-link" href="#index-fuse-ld_003dgold"> ¶</a></span>
</dt> <dd>
<p>Use the <code class="command">gold</code> linker instead of the default linker. </p> </dd> <dt>
<span><code class="code">-fuse-ld=lld</code><a class="copiable-link" href="#index-fuse-ld_003dlld"> ¶</a></span>
</dt> <dd>
<p>Use the LLVM <code class="command">lld</code> linker instead of the default linker. </p> </dd> <dt>
<span><code class="code">-fuse-ld=mold</code><a class="copiable-link" href="#index-fuse-ld_003dmold"> ¶</a></span>
</dt> <dd>
<p>Use the Modern Linker (<code class="command">mold</code>) instead of the default linker. </p> </dd> <dt>
 <span><code class="code">-l<var class="var">library</var></code><a class="copiable-link" href="#index-Libraries"> ¶</a></span>
</dt> <dt><code class="code">-l <var class="var">library</var></code></dt> <dd>
<p>Search the library named <var class="var">library</var> when linking. (The second alternative with the library as a separate argument is only for POSIX compliance and is not recommended.) </p> <p>The <samp class="option">-l</samp> option is passed directly to the linker by GCC. Refer to your linker documentation for exact details. The general description below applies to the GNU linker. </p> <p>The linker searches a standard list of directories for the library. The directories searched include several standard system directories plus any that you specify with <samp class="option">-L</samp>. </p> <p>Static libraries are archives of object files, and have file names like <samp class="file">lib<var class="var">library</var>.a</samp>. Some targets also support shared libraries, which typically have names like <samp class="file">lib<var class="var">library</var>.so</samp>. If both static and shared libraries are found, the linker gives preference to linking with the shared library unless the <samp class="option">-static</samp> option is used. </p> <p>It makes a difference where in the command you write this option; the linker searches and processes libraries and object files in the order they are specified. Thus, ‘<samp class="samp">foo.o -lz bar.o</samp>’ searches library ‘<samp class="samp">z</samp>’ after file <samp class="file">foo.o</samp> but before <samp class="file">bar.o</samp>. If <samp class="file">bar.o</samp> refers to functions in ‘<samp class="samp">z</samp>’, those functions may not be loaded. </p> </dd> <dt>
<span><code class="code">-lobjc</code><a class="copiable-link" href="#index-lobjc"> ¶</a></span>
</dt> <dd>
<p>You need this special case of the <samp class="option">-l</samp> option in order to link an Objective-C or Objective-C++ program. </p> </dd> <dt>
<span><code class="code">-nostartfiles</code><a class="copiable-link" href="#index-nostartfiles"> ¶</a></span>
</dt> <dd>
<p>Do not use the standard system startup files when linking. The standard system libraries are used normally, unless <samp class="option">-nostdlib</samp>, <samp class="option">-nolibc</samp>, or <samp class="option">-nodefaultlibs</samp> is used. </p> </dd> <dt>
<span><code class="code">-nodefaultlibs</code><a class="copiable-link" href="#index-nodefaultlibs"> ¶</a></span>
</dt> <dd>
<p>Do not use the standard system libraries when linking. Only the libraries you specify are passed to the linker, and options specifying linkage of the system libraries, such as <samp class="option">-static-libgcc</samp> or <samp class="option">-shared-libgcc</samp>, are ignored. The standard startup files are used normally, unless <samp class="option">-nostartfiles</samp> is used. </p> <p>The compiler may generate calls to <code class="code">memcmp</code>, <code class="code">memset</code>, <code class="code">memcpy</code> and <code class="code">memmove</code>. These entries are usually resolved by entries in libc. These entry points should be supplied through some other mechanism when this option is specified. </p> </dd> <dt>
<span><code class="code">-nolibc</code><a class="copiable-link" href="#index-nolibc"> ¶</a></span>
</dt> <dd>
<p>Do not use the C library or system libraries tightly coupled with it when linking. Still link with the startup files, <samp class="file">libgcc</samp> or toolchain provided language support libraries such as <samp class="file">libgnat</samp>, <samp class="file">libgfortran</samp> or <samp class="file">libstdc++</samp> unless options preventing their inclusion are used as well. This typically removes <samp class="option">-lc</samp> from the link command line, as well as system libraries that normally go with it and become meaningless when absence of a C library is assumed, for example <samp class="option">-lpthread</samp> or <samp class="option">-lm</samp> in some configurations. This is intended for bare-board targets when there is indeed no C library available. </p> </dd> <dt>
<span><code class="code">-nostdlib</code><a class="copiable-link" href="#index-nostdlib"> ¶</a></span>
</dt> <dd>
<p>Do not use the standard system startup files or libraries when linking. No startup files and only the libraries you specify are passed to the linker, and options specifying linkage of the system libraries, such as <samp class="option">-static-libgcc</samp> or <samp class="option">-shared-libgcc</samp>, are ignored. </p> <p>The compiler may generate calls to <code class="code">memcmp</code>, <code class="code">memset</code>, <code class="code">memcpy</code> and <code class="code">memmove</code>. These entries are usually resolved by entries in libc. These entry points should be supplied through some other mechanism when this option is specified. </p>       <p>One of the standard libraries bypassed by <samp class="option">-nostdlib</samp> and <samp class="option">-nodefaultlibs</samp> is <samp class="file">libgcc.a</samp>, a library of internal subroutines which GCC uses to overcome shortcomings of particular machines, or special needs for some languages. (See <a data-manual="gccint" href="https://gcc.gnu.org/onlinedocs/gccint/Interface.html#Interface">Interfacing to GCC Output</a> in GNU Compiler Collection (GCC) Internals, for more discussion of <samp class="file">libgcc.a</samp>.) In most cases, you need <samp class="file">libgcc.a</samp> even when you want to avoid other standard libraries. In other words, when you specify <samp class="option">-nostdlib</samp> or <samp class="option">-nodefaultlibs</samp> you should usually specify <samp class="option">-lgcc</samp> as well. This ensures that you have no unresolved references to internal GCC library subroutines. (An example of such an internal subroutine is <code class="code">__main</code>, used to ensure C++ constructors are called; see <a data-manual="gccint" href="https://gcc.gnu.org/onlinedocs/gccint/Collect2.html#Collect2"><code class="code">collect2</code></a> in GNU Compiler Collection (GCC) Internals.) </p> </dd> <dt>
<span><code class="code">-nostdlib++</code><a class="copiable-link" href="#index-nostdlib_002b_002b"> ¶</a></span>
</dt> <dd>
<p>Do not implicitly link with standard C++ libraries. </p> </dd> <dt>
 <span><code class="code">-e <var class="var">entry</var></code><a class="copiable-link" href="#index-e"> ¶</a></span>
</dt> <dt><code class="code">--entry=<var class="var">entry</var></code></dt> <dd> <p>Specify that the program entry point is <var class="var">entry</var>. The argument is interpreted by the linker; the GNU linker accepts either a symbol name or an address. </p> </dd> <dt>
<span><code class="code">-pie</code><a class="copiable-link" href="#index-pie"> ¶</a></span>
</dt> <dd>
<p>Produce a dynamically linked position independent executable on targets that support it. For predictable results, you must also specify the same set of options used for compilation (<samp class="option">-fpie</samp>, <samp class="option">-fPIE</samp>, or model suboptions) when you specify this linker option. </p> </dd> <dt>
<span><code class="code">-no-pie</code><a class="copiable-link" href="#index-no-pie"> ¶</a></span>
</dt> <dd>
<p>Don’t produce a dynamically linked position independent executable. </p> </dd> <dt>
<span><code class="code">-static-pie</code><a class="copiable-link" href="#index-static-pie"> ¶</a></span>
</dt> <dd>
<p>Produce a static position independent executable on targets that support it. A static position independent executable is similar to a static executable, but can be loaded at any address without a dynamic linker. For predictable results, you must also specify the same set of options used for compilation (<samp class="option">-fpie</samp>, <samp class="option">-fPIE</samp>, or model suboptions) when you specify this linker option. </p> </dd> <dt>
<span><code class="code">-pthread</code><a class="copiable-link" href="#index-pthread-1"> ¶</a></span>
</dt> <dd>
<p>Link with the POSIX threads library. This option is supported on GNU/Linux targets, most other Unix derivatives, and also on x86 Cygwin and MinGW targets. On some targets this option also sets flags for the preprocessor, so it should be used consistently for both compilation and linking. </p> </dd> <dt>
<span><code class="code">-r</code><a class="copiable-link" href="#index-r"> ¶</a></span>
</dt> <dd>
<p>Produce a relocatable object as output. This is also known as partial linking. </p> </dd> <dt>
<span><code class="code">-rdynamic</code><a class="copiable-link" href="#index-rdynamic"> ¶</a></span>
</dt> <dd>
<p>Pass the flag <samp class="option">-export-dynamic</samp> to the ELF linker, on targets that support it. This instructs the linker to add all symbols, not only used ones, to the dynamic symbol table. This option is needed for some uses of <code class="code">dlopen</code> or to allow obtaining backtraces from within a program. </p> </dd> <dt>
<span><code class="code">-s</code><a class="copiable-link" href="#index-s"> ¶</a></span>
</dt> <dd>
<p>Remove all symbol table and relocation information from the executable. </p> </dd> <dt>
<span><code class="code">-static</code><a class="copiable-link" href="#index-static"> ¶</a></span>
</dt> <dd>
<p>On systems that support dynamic linking, this overrides <samp class="option">-pie</samp> and prevents linking with the shared libraries. On other systems, this option has no effect. </p> </dd> <dt>
<span><code class="code">-shared</code><a class="copiable-link" href="#index-shared"> ¶</a></span>
</dt> <dd>
<p>Produce a shared object which can then be linked with other objects to form an executable. Not all systems support this option. For predictable results, you must also specify the same set of options used for compilation (<samp class="option">-fpic</samp>, <samp class="option">-fPIC</samp>, or model suboptions) when you specify this linker option.<a class="footnote" id="DOCF1" href="#FOOT1"><sup>1</sup></a> </p> </dd> <dt>
 <span><code class="code">-shared-libgcc</code><a class="copiable-link" href="#index-shared-libgcc"> ¶</a></span>
</dt> <dt><code class="code">-static-libgcc</code></dt> <dd>
<p>On systems that provide <samp class="file">libgcc</samp> as a shared library, these options force the use of either the shared or static version, respectively. If no shared version of <samp class="file">libgcc</samp> was built when the compiler was configured, these options have no effect. </p> <p>There are several situations in which an application should use the shared <samp class="file">libgcc</samp> instead of the static version. The most common of these is when the application wishes to throw and catch exceptions across different shared libraries. In that case, each of the libraries as well as the application itself should use the shared <samp class="file">libgcc</samp>. </p> <p>Therefore, the G++ driver automatically adds <samp class="option">-shared-libgcc</samp> whenever you build a shared library or a main executable, because C++ programs typically use exceptions, so this is the right thing to do. </p> <p>If, instead, you use the GCC driver to create shared libraries, you may find that they are not always linked with the shared <samp class="file">libgcc</samp>. If GCC finds, at its configuration time, that you have a non-GNU linker or a GNU linker that does not support option <samp class="option">--eh-frame-hdr</samp>, it links the shared version of <samp class="file">libgcc</samp> into shared libraries by default. Otherwise, it takes advantage of the linker and optimizes away the linking with the shared version of <samp class="file">libgcc</samp>, linking with the static version of libgcc by default. This allows exceptions to propagate through such shared libraries, without incurring relocation costs at library load time. </p> <p>However, if a library or main executable is supposed to throw or catch exceptions, you must link it using the G++ driver, or using the option <samp class="option">-shared-libgcc</samp>, such that it is linked with the shared <samp class="file">libgcc</samp>. </p> </dd> <dt>
<span><code class="code">-static-libasan</code><a class="copiable-link" href="#index-static-libasan"> ¶</a></span>
</dt> <dd>
<p>When the <samp class="option">-fsanitize=address</samp> option is used to link a program, the GCC driver automatically links against <samp class="option">libasan</samp>. If <samp class="file">libasan</samp> is available as a shared library, and the <samp class="option">-static</samp> option is not used, then this links against the shared version of <samp class="file">libasan</samp>. The <samp class="option">-static-libasan</samp> option directs the GCC driver to link <samp class="file">libasan</samp> statically, without necessarily linking other libraries statically. </p> </dd> <dt>
<span><code class="code">-static-libtsan</code><a class="copiable-link" href="#index-static-libtsan"> ¶</a></span>
</dt> <dd>
<p>When the <samp class="option">-fsanitize=thread</samp> option is used to link a program, the GCC driver automatically links against <samp class="option">libtsan</samp>. If <samp class="file">libtsan</samp> is available as a shared library, and the <samp class="option">-static</samp> option is not used, then this links against the shared version of <samp class="file">libtsan</samp>. The <samp class="option">-static-libtsan</samp> option directs the GCC driver to link <samp class="file">libtsan</samp> statically, without necessarily linking other libraries statically. </p> </dd> <dt>
<span><code class="code">-static-liblsan</code><a class="copiable-link" href="#index-static-liblsan"> ¶</a></span>
</dt> <dd>
<p>When the <samp class="option">-fsanitize=leak</samp> option is used to link a program, the GCC driver automatically links against <samp class="option">liblsan</samp>. If <samp class="file">liblsan</samp> is available as a shared library, and the <samp class="option">-static</samp> option is not used, then this links against the shared version of <samp class="file">liblsan</samp>. The <samp class="option">-static-liblsan</samp> option directs the GCC driver to link <samp class="file">liblsan</samp> statically, without necessarily linking other libraries statically. </p> </dd> <dt>
<span><code class="code">-static-libubsan</code><a class="copiable-link" href="#index-static-libubsan"> ¶</a></span>
</dt> <dd>
<p>When the <samp class="option">-fsanitize=undefined</samp> option is used to link a program, the GCC driver automatically links against <samp class="option">libubsan</samp>. If <samp class="file">libubsan</samp> is available as a shared library, and the <samp class="option">-static</samp> option is not used, then this links against the shared version of <samp class="file">libubsan</samp>. The <samp class="option">-static-libubsan</samp> option directs the GCC driver to link <samp class="file">libubsan</samp> statically, without necessarily linking other libraries statically. </p> </dd> <dt>
<span><code class="code">-static-libstdc++</code><a class="copiable-link" href="#index-static-libstdc_002b_002b"> ¶</a></span>
</dt> <dd>
<p>When the <code class="command">g++</code> program is used to link a C++ program, it normally automatically links against <samp class="option">libstdc++</samp>. If <samp class="file">libstdc++</samp> is available as a shared library, and the <samp class="option">-static</samp> option is not used, then this links against the shared version of <samp class="file">libstdc++</samp>. That is normally fine. However, it is sometimes useful to freeze the version of <samp class="file">libstdc++</samp> used by the program without going all the way to a fully static link. The <samp class="option">-static-libstdc++</samp> option directs the <code class="command">g++</code> driver to link <samp class="file">libstdc++</samp> statically, without necessarily linking other libraries statically. </p> </dd> <dt>
<span><code class="code">-symbolic</code><a class="copiable-link" href="#index-symbolic"> ¶</a></span>
</dt> <dd>
<p>Bind references to global symbols when building a shared object. Warn about any unresolved references (unless overridden by the link editor option <samp class="option">-Xlinker -z -Xlinker defs</samp>). Only a few systems support this option. </p> </dd> <dt>
 <span><code class="code">-T <var class="var">script</var></code><a class="copiable-link" href="#index-T"> ¶</a></span>
</dt> <dd>
<p>Use <var class="var">script</var> as the linker script. This option is supported by most systems using the GNU linker. On some targets, such as bare-board targets without an operating system, the <samp class="option">-T</samp> option may be required when linking to avoid references to undefined symbols. </p> </dd> <dt>
<span><code class="code">-Xlinker <var class="var">option</var></code><a class="copiable-link" href="#index-Xlinker"> ¶</a></span>
</dt> <dd>
<p>Pass <var class="var">option</var> as an option to the linker. You can use this to supply system-specific linker options that GCC does not recognize. </p> <p>If you want to pass an option that takes a separate argument, you must use <samp class="option">-Xlinker</samp> twice, once for the option and once for the argument. For example, to pass <samp class="option">-assert definitions</samp>, you must write <samp class="option">-Xlinker -assert -Xlinker definitions</samp>. It does not work to write <samp class="option">-Xlinker "-assert definitions"</samp>, because this passes the entire string as a single argument, which is not what the linker expects. </p> <p>When using the GNU linker, it is usually more convenient to pass arguments to linker options using the <samp class="option"><var class="var">option</var>=<var class="var">value</var></samp> syntax than as separate arguments. For example, you can specify <samp class="option">-Xlinker -Map=output.map</samp> rather than <samp class="option">-Xlinker -Map -Xlinker output.map</samp>. Other linkers may not support this syntax for command-line options. </p> </dd> <dt>
<span><code class="code">-Wl,<var class="var">option</var></code><a class="copiable-link" href="#index-Wl"> ¶</a></span>
</dt> <dd>
<p>Pass <var class="var">option</var> as an option to the linker. If <var class="var">option</var> contains commas, it is split into multiple options at the commas. You can use this syntax to pass an argument to the option. For example, <samp class="option">-Wl,-Map,output.map</samp> passes <samp class="option">-Map output.map</samp> to the linker. When using the GNU linker, you can also get the same effect with <samp class="option">-Wl,-Map=output.map</samp>. </p> </dd> <dt>
<span><code class="code">-u <var class="var">symbol</var></code><a class="copiable-link" href="#index-u"> ¶</a></span>
</dt> <dd>
<p>Pretend the symbol <var class="var">symbol</var> is undefined, to force linking of library modules to define it. You can use <samp class="option">-u</samp> multiple times with different symbols to force loading of additional library modules. </p> </dd> <dt>
<span><code class="code">-z <var class="var">keyword</var></code><a class="copiable-link" href="#index-z"> ¶</a></span>
</dt> <dd><p><samp class="option">-z</samp> is passed directly on to the linker along with the keyword <var class="var">keyword</var>. See the section in the documentation of your linker for permitted values and their meanings. </p></dd> </dl> </div> <div class="footnotes-segment">  <h2 class="footnotes-heading">Footnotes</h2> <h3 class="footnote-body-heading"><a id="FOOT1" href="#DOCF1">(1)</a></h3> <p>On some systems, ‘<samp class="samp">gcc -shared</samp>’ needs to build supplementary stub code for constructors to work. On multi-libbed systems, ‘<samp class="samp">gcc -shared</samp>’ must select the correct support libraries to link against. Failing to supply the correct flags may lead to subtle defects. Supplying them in cases where they are not necessary is innocuous. <samp class="option">-shared</samp> suppresses the addition of startup code to alter the floating-point environment as done with <samp class="option">-ffast-math</samp>, <samp class="option">-Ofast</samp> or <samp class="option">-funsafe-math-optimizations</samp> on some targets.</p> </div>  <div class="nav-panel"> <p> Next: <a href="directory-options">Options for Directory Search</a>, Previous: <a href="assembler-options">Passing Options to the Assembler</a>, Up: <a href="invoking-gcc">GCC Command Options</a> [<a href="index#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="indices" title="Index" rel="index">Index</a>]</p> </div><div class="_attribution">
  <p class="_attribution-p">
    &copy; Free Software Foundation<br>Licensed under the GNU Free Documentation License, Version 1.3.<br>
    <a href="https://gcc.gnu.org/onlinedocs/gcc-13.1.0/gcc/Link-Options.html" class="_attribution-link">https://gcc.gnu.org/onlinedocs/gcc-13.1.0/gcc/Link-Options.html</a>
  </p>
</div>