libstdc++-v3/doc/html/manual/using_dynamic_or_shared.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Linking</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_namespaces.html" title="Namespaces" /><link rel="next" href="using_concurrency.html" title="Concurrency" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Linking</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using_namespaces.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="using_concurrency.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.linkage"></a>Linking</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.linkage.freestanding"></a>Almost Nothing</h3></div></div></div><p>
   3         Or as close as it gets: freestanding. This is a minimal
   4         configuration, with only partial support for the standard
   5         library. Assume only the following header files can be used:
   6       </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
   7             <code class="filename">cstdarg</code>
   8           </p></li><li class="listitem"><p>
   9           <code class="filename">cstddef</code>
  10           </p></li><li class="listitem"><p>
  11           <code class="filename">cstdlib</code>
  12           </p></li><li class="listitem"><p>
  13           <code class="filename">exception</code>
  14           </p></li><li class="listitem"><p>
  15           <code class="filename">limits</code>
  16           </p></li><li class="listitem"><p>
  17           <code class="filename">new</code>
  18           </p></li><li class="listitem"><p>
  19           <code class="filename">exception</code>
  20           </p></li><li class="listitem"><p>
  21           <code class="filename">typeinfo</code>
  22           </p></li></ul></div><p>
  23         In addition, throw in
  24       </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
  25           <code class="filename">cxxabi.h</code>.
  26           </p></li></ul></div><p>
  27         In the
  28         C++11 <a class="link" href="using.html#manual.intro.using.flags" title="Command Options">dialect</a> add
  29       </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
  30           <code class="filename">initializer_list</code>
  31           </p></li><li class="listitem"><p>
  32           <code class="filename">type_traits</code>
  33           </p></li></ul></div><p>
  34         As of GCC 13, libstdc++ implements P1642, which brings in many more
  35         headers, as well a quite a few ones not covered by the paper.
  36
  37         In general, if a feature does not require traditionally libc-provided
  38         facilities, or dynamic memory allocation, it's enabled in the
  39         freestanding subset.  In addition, if only a subset of a header
  40         requires such features, it is partially included.  Some examples
  41         include:
  42       </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
  43           <code class="filename">string_view</code>
  44           </p></li><li class="listitem"><p>
  45           <code class="filename">tuple</code>
  46           </p></li><li class="listitem"><p>
  47           <code class="filename">bitset</code>
  48           </p></li></ul></div><p>
  49         Currently, this subset includes all of the iterator APIs (including the
  50         ranges APIs) that do not involve streams, the entire C++ algorithms
  51         library, excluding parallel algorithms, and a large part of the
  52         utilities library.  This is on top of the headers included in the lists
  53         above.
  54       </p><p>
  55         If you're using a libstdc++ configured for hosted environments, and
  56         would like to not involve the libraries libstdc++ would depend on in
  57         your programs, you will need to use <span class="command"><strong>gcc</strong></span> to link your
  58         application with only <code class="filename">libsupc++.a</code>,
  59         like so:
  60       </p><p>
  61         <span class="command"><strong>gcc -ffreestanding foo.cc -lsupc++</strong></span>
  62       </p><p>
  63         If you configured libstdc++ with
  64         <code class="code">--disable-hosted-libstdcxx</code>, however, you can use the
  65         normal <span class="command"><strong>g++</strong></span> command to link, as this configuration
  66         provides a (nearly) empty <code class="filename">libstdc++.a</code>.
  67       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.linkage.dynamic"></a>Finding Dynamic or Shared Libraries</h3></div></div></div><p>
  68       If the only library built is the static library
  69       (<code class="filename">libstdc++.a</code>), or if
  70       specifying static linking, this section is can be skipped.  But
  71       if building or using a shared library
  72       (<code class="filename">libstdc++.so</code>), then
  73       additional location information will need to be provided.
  74     </p><p>
  75       But how?
  76     </p><p>
  77 A quick read of the relevant part of the GCC
  78       manual, <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Invoking-G_002b_002b.html#Invoking-G_002b_002b" target="_top">Compiling
  79       C++ Programs</a>, specifies linking against a C++
  80       library. More details from the
  81       GCC <a class="link" href="http://gcc.gnu.org/faq.html#rpath" target="_top">FAQ</a>,
  82       which states <span class="emphasis"><em>GCC does not, by default, specify a
  83       location so that the dynamic linker can find dynamic libraries at
  84       runtime.</em></span>
  85     </p><p>
  86       Users will have to provide this information.
  87     </p><p>
  88       Methods vary for different platforms and different styles, and
  89       are printed to the screen during installation. To summarize:
  90     </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
  91           At runtime set <code class="literal">LD_LIBRARY_PATH</code> in your
  92           environment correctly, so that the shared library for
  93           libstdc++ can be found and loaded.  Be certain that you
  94           understand all of the other implications and behavior
  95           of <code class="literal">LD_LIBRARY_PATH</code> first.
  96         </p></li><li class="listitem"><p>
  97           Compile the path to find the library at runtime into the
  98           program.  This can be done by passing certain options to
  99           <span class="command"><strong>g++</strong></span>, which will in turn pass them on to
 100           the linker.  The exact format of the options is dependent on
 101           which linker you use:
 102         </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
 103               GNU ld (default on GNU/Linux):
 104               <code class="literal">-Wl,-rpath,</code><code class="filename">destdir/lib</code>
 105             </p></li><li class="listitem"><p>
 106             Solaris ld:
 107             <code class="literal">-Wl,-R</code><code class="filename">destdir/lib</code>
 108           </p></li></ul></div></li><li class="listitem"><p>
 109           Some linkers allow you to specify the path to the library by
 110           setting <code class="literal">LD_RUN_PATH</code> in your environment
 111           when linking.
 112         </p></li><li class="listitem"><p>
 113           On some platforms the system administrator can configure the
 114           dynamic linker to always look for libraries in
 115           <code class="filename">destdir/lib</code>, for example
 116           by using the <span class="command"><strong>ldconfig</strong></span> utility on GNU/Linux
 117           or the <span class="command"><strong>crle</strong></span> utility on Solaris. This is a
 118           system-wide change which can make the system unusable so if you
 119           are unsure then use one of the other methods described above.
 120         </p></li></ul></div><p>
 121       Use the <span class="command"><strong>ldd</strong></span> utility on the linked executable
 122       to show
 123       which <code class="filename">libstdc++.so</code>
 124       library the system will get at runtime.
 125     </p><p>
 126       A <code class="filename">libstdc++.la</code> file is
 127       also installed, for use with Libtool.  If you use Libtool to
 128       create your executables, these details are taken care of for
 129       you.
 130     </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.linkage.experimental"></a>Experimental Library Extensions</h3></div></div></div><p>
 131       GCC 5.3 includes an implementation of the Filesystem library defined
 132       by the technical specification ISO/IEC TS 18822:2015. Because this is
 133       an experimental library extension, not part of the C++ standard, it
 134       is implemented in a separate library,
 135       <code class="filename">libstdc++fs.a</code>, and there is
 136       no shared library for it. To use the library you should include
 137       <code class="filename">&lt;experimental/filesystem&gt;</code>
 138       and link with <code class="option">-lstdc++fs</code>. The library implementation
 139       is incomplete on non-POSIX platforms, specifically Windows is only
 140       partially supported.
 141       Since GCC 14, <code class="filename">libstdc++exp.a</code>
 142       also contains the definitions for this library,
 143       so <code class="option">-lstdc++exp</code> can be used instead of
 144       <code class="option">-lstdc++fs</code>.
 145     </p><p>
 146       GCC 13 includes an implementation of the C++ Contracts library defined by
 147       <a class="link" href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1429r3.pdf" target="_top">P1429R3</a>.
 148       Because this is an experimental extension, not part of the C++ standard,
 149       it is implemented in a separate library,
 150       <code class="filename">libstdc++exp.a</code>, and there is
 151       no shared library for it. To use the library you should include
 152       <code class="filename">&lt;experimental/contract&gt;</code>
 153       and link with <code class="option">-lstdc++exp</code>.
 154     </p><p>
 155       Due to the experimental nature of these libraries the usual
 156       guarantees about ABI stability and backwards compatibility do not apply
 157       to them. There is no guarantee that the components in any
 158       <code class="filename">&lt;experimental/xxx&gt;</code>
 159       header will remain compatible between different GCC releases.
 160     </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_namespaces.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using_concurrency.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Namespaces </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Concurrency</td></tr></table></div></body></html>