You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
319 lines
23 KiB
HTML
319 lines
23 KiB
HTML
<html lang="en">
|
|
<head>
|
|
<title>Link Options - Using the GNU Compiler Collection (GCC)</title>
|
|
<meta http-equiv="Content-Type" content="text/html">
|
|
<meta name="description" content="Using the GNU Compiler Collection (GCC)">
|
|
<meta name="generator" content="makeinfo 4.13">
|
|
<link title="Top" rel="start" href="index.html#Top">
|
|
<link rel="up" href="Invoking-GCC.html#Invoking-GCC" title="Invoking GCC">
|
|
<link rel="prev" href="Assembler-Options.html#Assembler-Options" title="Assembler Options">
|
|
<link rel="next" href="Directory-Options.html#Directory-Options" title="Directory Options">
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
|
<!--
|
|
Copyright (C) 1988-2015 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with the
|
|
Invariant Sections being ``Funding Free Software'', the Front-Cover
|
|
Texts being (a) (see below), and with the Back-Cover Texts being (b)
|
|
(see below). A copy of the license is included in the section entitled
|
|
``GNU Free Documentation License''.
|
|
|
|
(a) The FSF's Front-Cover Text is:
|
|
|
|
A GNU Manual
|
|
|
|
(b) The FSF's Back-Cover Text is:
|
|
|
|
You have freedom to copy and modify this GNU Manual, like GNU
|
|
software. Copies published by the Free Software Foundation raise
|
|
funds for GNU development.-->
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
|
<style type="text/css"><!--
|
|
pre.display { font-family:inherit }
|
|
pre.format { font-family:inherit }
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
|
pre.smallexample { font-size:smaller }
|
|
pre.smalllisp { font-size:smaller }
|
|
span.sc { font-variant:small-caps }
|
|
span.roman { font-family:serif; font-weight:normal; }
|
|
span.sansserif { font-family:sans-serif; font-weight:normal; }
|
|
--></style>
|
|
</head>
|
|
<body>
|
|
<div class="node">
|
|
<a name="Link-Options"></a>
|
|
<p>
|
|
Next: <a rel="next" accesskey="n" href="Directory-Options.html#Directory-Options">Directory Options</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="Assembler-Options.html#Assembler-Options">Assembler Options</a>,
|
|
Up: <a rel="up" accesskey="u" href="Invoking-GCC.html#Invoking-GCC">Invoking GCC</a>
|
|
<hr>
|
|
</div>
|
|
|
|
<h3 class="section">3.13 Options for Linking</h3>
|
|
|
|
<p><a name="index-link-options-1202"></a><a name="index-options_002c-linking-1203"></a>
|
|
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.
|
|
|
|
|
|
<a name="index-file-names-1204"></a>
|
|
<dl><dt><var>object-file-name</var><dd>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.
|
|
|
|
<br><dt><code>-c</code><dt><code>-S</code><dt><code>-E</code><dd><a name="index-c-1205"></a><a name="index-S-1206"></a><a name="index-E-1207"></a>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 href="Overall-Options.html#Overall-Options">Overall Options</a>.
|
|
|
|
<br><dt><code>-fuse-ld=bfd</code><dd><a name="index-fuse_002dld_003dbfd-1208"></a>Use the <samp><span class="command">bfd</span></samp> linker instead of the default linker.
|
|
|
|
<br><dt><code>-fuse-ld=gold</code><dd><a name="index-fuse_002dld_003dgold-1209"></a>Use the <samp><span class="command">gold</span></samp> linker instead of the default linker.
|
|
|
|
<p><a name="index-Libraries-1210"></a><br><dt><code>-l</code><var>library</var><dt><code>-l </code><var>library</var><dd><a name="index-l-1211"></a>Search the library named <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>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><span class="samp">foo.o -lz bar.o</span></samp>’ searches library ‘<samp><span class="samp">z</span></samp>’
|
|
after 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
|
|
to functions in ‘<samp><span class="samp">z</span></samp>’, those functions may not be loaded.
|
|
|
|
<p>The linker searches a standard list of directories for the library,
|
|
which is actually a file named <samp><span class="file">lib</span><var>library</var><span class="file">.a</span></samp>. The linker
|
|
then uses this file as if it had been specified precisely by name.
|
|
|
|
<p>The directories searched include several standard system directories
|
|
plus any that you specify with <samp><span class="option">-L</span></samp>.
|
|
|
|
<p>Normally the files found this way are library files—archive files
|
|
whose members are object files. The linker handles an archive file by
|
|
scanning through it for members which define symbols that have so far
|
|
been referenced but not defined. But if the file that is found is an
|
|
ordinary object file, it is linked in the usual fashion. The only
|
|
difference between using an <samp><span class="option">-l</span></samp> option and specifying a file name
|
|
is 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>’
|
|
and searches several directories.
|
|
|
|
<br><dt><code>-lobjc</code><dd><a name="index-lobjc-1212"></a>You need this special case of the <samp><span class="option">-l</span></samp> option in order to
|
|
link an Objective-C or Objective-C++ program.
|
|
|
|
<br><dt><code>-nostartfiles</code><dd><a name="index-nostartfiles-1213"></a>Do not use the standard system startup files when linking.
|
|
The standard system libraries are used normally, unless <samp><span class="option">-nostdlib</span></samp>
|
|
or <samp><span class="option">-nodefaultlibs</span></samp> is used.
|
|
|
|
<br><dt><code>-nodefaultlibs</code><dd><a name="index-nodefaultlibs-1214"></a>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><span class="option">-static-libgcc</span></samp>
|
|
or <samp><span class="option">-shared-libgcc</span></samp>, are ignored.
|
|
The standard startup files are used normally, unless <samp><span class="option">-nostartfiles</span></samp>
|
|
is used.
|
|
|
|
<p>The compiler may generate calls to <code>memcmp</code>,
|
|
<code>memset</code>, <code>memcpy</code> and <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.
|
|
|
|
<br><dt><code>-nostdlib</code><dd><a name="index-nostdlib-1215"></a>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><span class="option">-static-libgcc</span></samp> or <samp><span class="option">-shared-libgcc</span></samp>, are ignored.
|
|
|
|
<p>The compiler may generate calls to <code>memcmp</code>, <code>memset</code>,
|
|
<code>memcpy</code> and <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><a name="index-g_t_0040option_007b_002dlgcc_007d_002c-use-with-_0040option_007b_002dnostdlib_007d-1216"></a><a name="index-g_t_0040option_007b_002dnostdlib_007d-and-unresolved-references-1217"></a><a name="index-unresolved-references-and-_0040option_007b_002dnostdlib_007d-1218"></a><a name="index-g_t_0040option_007b_002dlgcc_007d_002c-use-with-_0040option_007b_002dnodefaultlibs_007d-1219"></a><a name="index-g_t_0040option_007b_002dnodefaultlibs_007d-and-unresolved-references-1220"></a><a name="index-unresolved-references-and-_0040option_007b_002dnodefaultlibs_007d-1221"></a>One of the standard libraries bypassed by <samp><span class="option">-nostdlib</span></samp> and
|
|
<samp><span class="option">-nodefaultlibs</span></samp> is <samp><span class="file">libgcc.a</span></samp>, a library of internal subroutines
|
|
which GCC uses to overcome shortcomings of particular machines, or special
|
|
needs for some languages.
|
|
(See <a href="../gccint/Interface.html#Interface">Interfacing to GCC Output</a>,
|
|
for more discussion of <samp><span class="file">libgcc.a</span></samp>.)
|
|
In most cases, you need <samp><span class="file">libgcc.a</span></samp> even when you want to avoid
|
|
other standard libraries. In other words, when you specify <samp><span class="option">-nostdlib</span></samp>
|
|
or <samp><span class="option">-nodefaultlibs</span></samp> you should usually specify <samp><span class="option">-lgcc</span></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>__main</code>, used to ensure C++
|
|
constructors are called; see <a href="../gccint/Collect2.html#Collect2"><code>collect2</code></a>.)
|
|
|
|
<br><dt><code>-pie</code><dd><a name="index-pie-1222"></a>Produce a position independent executable on targets that support it.
|
|
For predictable results, you must also specify the same set of options
|
|
used for compilation (<samp><span class="option">-fpie</span></samp>, <samp><span class="option">-fPIE</span></samp>,
|
|
or model suboptions) when you specify this linker option.
|
|
|
|
<br><dt><code>-rdynamic</code><dd><a name="index-rdynamic-1223"></a>Pass the flag <samp><span class="option">-export-dynamic</span></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>dlopen</code> or to allow obtaining backtraces
|
|
from within a program.
|
|
|
|
<br><dt><code>-s</code><dd><a name="index-s-1224"></a>Remove all symbol table and relocation information from the executable.
|
|
|
|
<br><dt><code>-static</code><dd><a name="index-static-1225"></a>On systems that support dynamic linking, this prevents linking with the shared
|
|
libraries. On other systems, this option has no effect.
|
|
|
|
<br><dt><code>-shared</code><dd><a name="index-shared-1226"></a>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><span class="option">-fpic</span></samp>, <samp><span class="option">-fPIC</span></samp>, or model suboptions) when
|
|
you specify this linker option.<a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a>
|
|
|
|
<br><dt><code>-shared-libgcc</code><dt><code>-static-libgcc</code><dd><a name="index-shared_002dlibgcc-1227"></a><a name="index-static_002dlibgcc-1228"></a>On systems that provide <samp><span class="file">libgcc</span></samp> as a shared library, these options
|
|
force the use of either the shared or static version, respectively.
|
|
If no shared version of <samp><span class="file">libgcc</span></samp> was built when the compiler was
|
|
configured, these options have no effect.
|
|
|
|
<p>There are several situations in which an application should use the
|
|
shared <samp><span class="file">libgcc</span></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><span class="file">libgcc</span></samp>.
|
|
|
|
<p>Therefore, the G++ and GCJ drivers automatically add
|
|
<samp><span class="option">-shared-libgcc</span></samp> whenever you build a shared library or a main
|
|
executable, because C++ and Java programs typically use exceptions, so
|
|
this is the right thing to do.
|
|
|
|
<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><span class="file">libgcc</span></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><span class="option">--eh-frame-hdr</span></samp>,
|
|
it links the shared version of <samp><span class="file">libgcc</span></samp> into shared libraries
|
|
by default. Otherwise, it takes advantage of the linker and optimizes
|
|
away the linking with the shared version of <samp><span class="file">libgcc</span></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>However, if a library or main executable is supposed to throw or catch
|
|
exceptions, you must link it using the G++ or GCJ driver, as appropriate
|
|
for the languages used in the program, or using the option
|
|
<samp><span class="option">-shared-libgcc</span></samp>, such that it is linked with the shared
|
|
<samp><span class="file">libgcc</span></samp>.
|
|
|
|
<br><dt><code>-static-libasan</code><dd><a name="index-static_002dlibasan-1229"></a>When the <samp><span class="option">-fsanitize=address</span></samp> option is used to link a program,
|
|
the GCC driver automatically links against <samp><span class="option">libasan</span></samp>. If
|
|
<samp><span class="file">libasan</span></samp> is available as a shared library, and the <samp><span class="option">-static</span></samp>
|
|
option is not used, then this links against the shared version of
|
|
<samp><span class="file">libasan</span></samp>. The <samp><span class="option">-static-libasan</span></samp> option directs the GCC
|
|
driver to link <samp><span class="file">libasan</span></samp> statically, without necessarily linking
|
|
other libraries statically.
|
|
|
|
<br><dt><code>-static-libtsan</code><dd><a name="index-static_002dlibtsan-1230"></a>When the <samp><span class="option">-fsanitize=thread</span></samp> option is used to link a program,
|
|
the GCC driver automatically links against <samp><span class="option">libtsan</span></samp>. If
|
|
<samp><span class="file">libtsan</span></samp> is available as a shared library, and the <samp><span class="option">-static</span></samp>
|
|
option is not used, then this links against the shared version of
|
|
<samp><span class="file">libtsan</span></samp>. The <samp><span class="option">-static-libtsan</span></samp> option directs the GCC
|
|
driver to link <samp><span class="file">libtsan</span></samp> statically, without necessarily linking
|
|
other libraries statically.
|
|
|
|
<br><dt><code>-static-liblsan</code><dd><a name="index-static_002dliblsan-1231"></a>When the <samp><span class="option">-fsanitize=leak</span></samp> option is used to link a program,
|
|
the GCC driver automatically links against <samp><span class="option">liblsan</span></samp>. If
|
|
<samp><span class="file">liblsan</span></samp> is available as a shared library, and the <samp><span class="option">-static</span></samp>
|
|
option is not used, then this links against the shared version of
|
|
<samp><span class="file">liblsan</span></samp>. The <samp><span class="option">-static-liblsan</span></samp> option directs the GCC
|
|
driver to link <samp><span class="file">liblsan</span></samp> statically, without necessarily linking
|
|
other libraries statically.
|
|
|
|
<br><dt><code>-static-libubsan</code><dd><a name="index-static_002dlibubsan-1232"></a>When the <samp><span class="option">-fsanitize=undefined</span></samp> option is used to link a program,
|
|
the GCC driver automatically links against <samp><span class="option">libubsan</span></samp>. If
|
|
<samp><span class="file">libubsan</span></samp> is available as a shared library, and the <samp><span class="option">-static</span></samp>
|
|
option is not used, then this links against the shared version of
|
|
<samp><span class="file">libubsan</span></samp>. The <samp><span class="option">-static-libubsan</span></samp> option directs the GCC
|
|
driver to link <samp><span class="file">libubsan</span></samp> statically, without necessarily linking
|
|
other libraries statically.
|
|
|
|
<br><dt><code>-static-libmpx</code><dd><a name="index-static_002dlibmpx-1233"></a>When the <samp><span class="option">-fcheck-pointer bounds</span></samp> and <samp><span class="option">-mmpx</span></samp> options are
|
|
used to link a program, the GCC driver automatically links against
|
|
<samp><span class="file">libmpx</span></samp>. If <samp><span class="file">libmpx</span></samp> is available as a shared library,
|
|
and the <samp><span class="option">-static</span></samp> option is not used, then this links against
|
|
the shared version of <samp><span class="file">libmpx</span></samp>. The <samp><span class="option">-static-libmpx</span></samp>
|
|
option directs the GCC driver to link <samp><span class="file">libmpx</span></samp> statically,
|
|
without necessarily linking other libraries statically.
|
|
|
|
<br><dt><code>-static-libmpxwrappers</code><dd><a name="index-static_002dlibmpxwrappers-1234"></a>When the <samp><span class="option">-fcheck-pointer bounds</span></samp> and <samp><span class="option">-mmpx</span></samp> options are used
|
|
to link a program without also using <samp><span class="option">-fno-chkp-use-wrappers</span></samp>, the
|
|
GCC driver automatically links against <samp><span class="file">libmpxwrappers</span></samp>. If
|
|
<samp><span class="file">libmpxwrappers</span></samp> is available as a shared library, and the
|
|
<samp><span class="option">-static</span></samp> option is not used, then this links against the shared
|
|
version of <samp><span class="file">libmpxwrappers</span></samp>. The <samp><span class="option">-static-libmpxwrappers</span></samp>
|
|
option directs the GCC driver to link <samp><span class="file">libmpxwrappers</span></samp> statically,
|
|
without necessarily linking other libraries statically.
|
|
|
|
<br><dt><code>-static-libstdc++</code><dd><a name="index-static_002dlibstdc_002b_002b-1235"></a>When the <samp><span class="command">g++</span></samp> program is used to link a C++ program, it
|
|
normally automatically links against <samp><span class="option">libstdc++</span></samp>. If
|
|
<samp><span class="file">libstdc++</span></samp> is available as a shared library, and the
|
|
<samp><span class="option">-static</span></samp> option is not used, then this links against the
|
|
shared version of <samp><span class="file">libstdc++</span></samp>. That is normally fine. However, it
|
|
is sometimes useful to freeze the version of <samp><span class="file">libstdc++</span></samp> used by
|
|
the program without going all the way to a fully static link. The
|
|
<samp><span class="option">-static-libstdc++</span></samp> option directs the <samp><span class="command">g++</span></samp> driver to
|
|
link <samp><span class="file">libstdc++</span></samp> statically, without necessarily linking other
|
|
libraries statically.
|
|
|
|
<br><dt><code>-symbolic</code><dd><a name="index-symbolic-1236"></a>Bind references to global symbols when building a shared object. Warn
|
|
about any unresolved references (unless overridden by the link editor
|
|
option <samp><span class="option">-Xlinker -z -Xlinker defs</span></samp>). Only a few systems support
|
|
this option.
|
|
|
|
<br><dt><code>-T </code><var>script</var><dd><a name="index-T-1237"></a><a name="index-linker-script-1238"></a>Use <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><span class="option">-T</span></samp> option may be required
|
|
when linking to avoid references to undefined symbols.
|
|
|
|
<br><dt><code>-Xlinker </code><var>option</var><dd><a name="index-Xlinker-1239"></a>Pass <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>If you want to pass an option that takes a separate argument, you must use
|
|
<samp><span class="option">-Xlinker</span></samp> twice, once for the option and once for the argument.
|
|
For example, to pass <samp><span class="option">-assert definitions</span></samp>, you must write
|
|
<samp><span class="option">-Xlinker -assert -Xlinker definitions</span></samp>. It does not work to write
|
|
<samp><span class="option">-Xlinker "-assert definitions"</span></samp>, because this passes the entire
|
|
string as a single argument, which is not what the linker expects.
|
|
|
|
<p>When using the GNU linker, it is usually more convenient to pass
|
|
arguments to linker options using the <samp><var>option</var><span class="option">=</span><var>value</var></samp>
|
|
syntax than as separate arguments. For example, you can specify
|
|
<samp><span class="option">-Xlinker -Map=output.map</span></samp> rather than
|
|
<samp><span class="option">-Xlinker -Map -Xlinker output.map</span></samp>. Other linkers may not support
|
|
this syntax for command-line options.
|
|
|
|
<br><dt><code>-Wl,</code><var>option</var><dd><a name="index-Wl-1240"></a>Pass <var>option</var> as an option to the linker. If <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><span class="option">-Wl,-Map,output.map</span></samp> passes <samp><span class="option">-Map output.map</span></samp> to the
|
|
linker. When using the GNU linker, you can also get the same effect with
|
|
<samp><span class="option">-Wl,-Map=output.map</span></samp>.
|
|
|
|
<br><dt><code>-u </code><var>symbol</var><dd><a name="index-u-1241"></a>Pretend the symbol <var>symbol</var> is undefined, to force linking of
|
|
library modules to define it. You can use <samp><span class="option">-u</span></samp> multiple times with
|
|
different symbols to force loading of additional library modules.
|
|
|
|
<br><dt><code>-z </code><var>keyword</var><dd><a name="index-z-1242"></a><samp><span class="option">-z</span></samp> is passed directly on to the linker along with the keyword
|
|
<var>keyword</var>. See the section in the documentation of your linker for
|
|
permitted values and their meanings.
|
|
</dl>
|
|
|
|
<div class="footnote">
|
|
<hr>
|
|
<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>’
|
|
needs to build supplementary stub code for constructors to work. On
|
|
multi-libbed systems, ‘<samp><span class="samp">gcc -shared</span></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.</p>
|
|
|
|
<hr></div>
|
|
|
|
</body></html>
|
|
|