libstdc++-v3/docs/html/install.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
   2 <html>
   3 <head>
   4    <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
   5    <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++">
   6    <meta name="DESCRIPTION" content="README for the GNU libstdc++ effort.">
   7    <meta name="GENERATOR" content="vi and eight fingers">
   8    <title>libstdc++-v3 Installation Instructions</title>
   9 <link rel="StyleSheet" href="lib3styles.css">
  10 </head>
  11 <body>
  12
  13 <h1 class="centered"><a name="top">libstdc++-v3 INSTALL</a></h1>
  14
  15 <p>The latest version of this document is always available at
  16    <a href="http://gcc.gnu.org/onlinedocs/libstdc++/install.html">
  17    http://gcc.gnu.org/onlinedocs/libstdc++/install.html</a>.
  18 </p>
  19
  20 <p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
  21
  22
  23 <!-- ####################################################### -->
  24 <hr>
  25 <h2>Contents</h2>
  26 <ul>
  27    <li><a href="#prereqs">Tools you will need beforehand</a>
  28    <li><a href="#srcsetup">Setting up the source directories</a>
  29    <li><a href="#config">Configuring</a>
  30    <li><a href="#install">Building and installing the library</a>
  31    <li><a href="#postinstall">Post-installation</a>
  32    <li><a href="#usage">Using the library</a>
  33 </ul>
  34
  35 <hr>
  36
  37 <!-- ####################################################### -->
  38
  39 <h2><a name="prereqs">Tools you will need beforehand</a></h2>
  40    <p>You will need a recent version of g++ to compile the snapshot of
  41       libstdc++, such as one of the GCC 3.x snapshots (insert standard
  42       caveat about using snapshots rather than formal releases).  You will
  43       need the full source distribution to whatever compiler release you are
  44       using.  The GCC snapshots can be had from one of the sites on their
  45       <a href="http://gcc.gnu.org/mirrors.html">mirror list</a>.  If you are
  46       using a 2.x compiler, see
  47       <a href="http://gcc.gnu.org/libstdc++/status.html">the status page</a>
  48       first.
  49    </p>
  50
  51    <p>In addition, if you plan to modify the makefiles or regenerate the
  52       configure scripts you'll need recent versions of the GNU Autotools:
  53       autoconf (version 2.50 or later),
  54       automake (version 1.4 or later),    <!-- special version? -->
  55       and libtool (multilanguage, version 1.4 or later),  <!-- really? -->
  56       in order to rebuild the files.
  57       These tools are all required to be installed in the same location
  58       (most linux distributions install these tools by default, so no
  59       worries as long as the versions are correct).
  60    </p>
  61
  62    <p>To test your build, you will need either DejaGNU 1.4 (to run
  63       <code>'make check'</code> like
  64       <a href="http://gcc.gnu.org/install/test.html">the rest of GCC</a>),
  65       or Bash 2.x (to run <code>'make check-script'</code>).
  66    </p>
  67
  68    <p>As of June 19, 2000, libstdc++ attempts to use tricky and
  69       space-saving features of the GNU toolchain, enabled with
  70       <code>-ffunction-sections -fdata-sections -Wl,--gc-sections</code>.
  71       To obtain maximum benefit from this, binutils after this date
  72       should also be used (bugs were fixed with C++ exception handling
  73       related to this change in libstdc++-v3).  The version of these
  74       tools should be <code>2.10.90</code>, and you can get snapshots (as
  75       well as releases) of binutils
  76       <a href="ftp://sources.redhat.com/pub/binutils">here</a>.
  77    </p>
  78
  79    <p>If you are using a 3.1-series libstdc++ snapshot, then the
  80       requirements are slightly more stringent:  the compiler sources must
  81       also be 3.1 or later (for both technical and licensing reasons), and
  82       your binutils must be 2.11.95 or later if you want to use symbol
  83       versioning in shared libraries.
  84    </p>
  85
  86  <!-- Commented until some system-specific requirements appear.
  87    <p>Finally, a few system-specific requirements:
  88       <dl>
  89         <dt>Cygwin
  90         <dd>If you are using Cygwin to compile libstdc++-v3 on Win32, you'll
  91             [snip]
  92
  93       </dl>
  94    </p>
  95 -->
  96
  97 <hr>
  98
  99 <h2><a name="srcsetup">Setting up the source directories</a></h2>
 100    <p>The following definitions will be used throughout the rest of this
 101       document:
 102       <ul>
 103          <li><em>gccsrcdir</em>:  The directory holding the source of the
 104                  compiler.  It should have several subdirectories like
 105                  <em>gccsrcdir</em>/libio and <em>gccsrcdir</em>/gcc.
 106          <li><em>libsrcdir</em>:  The directory holding the source of the
 107                  C++ library.
 108          <li><em>gccbuilddir</em>:  The build directory for the compiler
 109                  in <em>gccsrcdir</em>.  GCC requires that it be built in
 110                  a different directory than its sources.
 111          <li><em>libbuilddir</em>:  The build directory for libstdc++.
 112          <li><em>destdir</em>:  The eventual installation directory for
 113                  the compiler/libraries, set with the --prefix option to
 114                  the configure script.
 115       </ul>
 116       Note:
 117       <ol>
 118          <li>The 3.0 version and following are intended to replace the
 119              library that comes with the compiler, so <em>libsrcdir</em>
 120              and <em>libbuilddir</em> must be contained under
 121              <em>gccsrcdir</em> and <em>gccbuilddir</em>, respectively.
 122          <li>The source, build, and installation directories should
 123              not be parents of one another; i.e., these should all be
 124              separate directories. Please don't build out of the
 125              source directory.
 126       </ol>
 127    </p>
 128
 129    <p>Check out or download the GCC sources: the resulting source directory
 130       (<code>gcc</code> or <code>gcc-3.0.3</code>, for example) is
 131       <em>gccsrcdir</em>.
 132       Once in <em>gccsrcdir</em>, you'll need to rename or delete the
 133       libstdc++-v3 directory which comes with that snapshot:
 134       <pre>
 135    mv libstdc++-v3 libstdc++-v3-previous  <strong>[OR]</strong>
 136    rm -r libstdc++-v3</pre>
 137    </p>
 138    <p>Next, unpack the libstdc++-v3 library tarball into this
 139       <em>gccsrcdir</em> directory; it will create a
 140       <em>libsrcdir</em> called <code>libstdc++-<em>version</em></code>:
 141       <pre>
 142    gzip -dc libstdc++-version.tar.gz | tar xf -</pre>
 143    </p>
 144    <p>Finally, rename <em>libsrcdir</em> to <code>libstdc++-v3</code> so that
 145       gcc's configure flags will be able to deal with the new library.
 146       <pre>
 147    mv <em>libsrcdir</em> libstdc++-v3</pre>
 148    </p>
 149
 150
 151 <hr>
 152 <h2><a name="config">Configuring</a></h2>
 153    <p>If you have never done this before, you should read the basic
 154       <a href="http://gcc.gnu.org/install/">GCC Installation
 155       Instructions</a> first.  Read <em>all of them</em>.
 156       <strong>Twice.</strong>
 157    </p>
 158    <p>When building libstdc++-v3 you'll have to configure
 159       the entire <em>gccsrcdir</em> directory.  The full list of libstdc++-v3
 160       specific configuration options, not dependent on the specific compiler
 161       release being used, can be found <a href="configopts.html">here</a>.
 162    </p>
 163    <p>Consider possibly using --enable-languages=c++ to save time by only
 164       building the C++ language parts.
 165    </p>
 166
 167    <p><pre>
 168    cd <em>gccbuilddir</em>
 169    <em>gccsrcdir</em>/configure --prefix=<em>destdir</em> --other-opts...</pre>
 170    </p>
 171
 172
 173 <hr>
 174 <h2><a name="install">Building and installing the library</a></h2>
 175    <p>Now you have a few options:</p>
 176    <h3>[re]building <em>everything</em></h3>
 177    <p>If you're building GCC from scratch, you can do the usual
 178       <code> 'make bootstrap' </code> here, and libstdc++-v3 will be built
 179       as its default C++ library.  The generated g++ will magically
 180       use the correct headers, link against the correct library
 181       binary, and in general using libstdc++-v3 will be a piece of
 182       cake.  You're done; run <code>'make install'</code> (see the GCC
 183       installation instructions) to put the new compiler and libraries
 184       into place.
 185    </p>
 186
 187    <h3>[re]building only libstdc++</h3>
 188    <p>To rebuild just libstdc++, use:
 189       <pre>
 190    make all-target-<em>libstdc++-v3</em></pre>
 191       This will configure and build the C++ library in the
 192       <em>gccbuilddir/cpu-vendor-os/</em>libstdc++ directory.
 193    </p>
 194    <p>If you are rebuilding from a previous build [attempt], some
 195       information is kept in a cache file.  This is stored in
 196       <em>gccbuilddir/cpu-vendor-os/</em> if you are building with
 197       multilibs (the default), or in
 198       <em>gccbuilddir/cpu-vendor-os/</em>libstdc++-v3 if you have
 199       multilibs disabled.  The filename is config.cache; if previous
 200       information is causing problems, you can delete it entirely, or
 201       simply edit it and remove lines.
 202    </p>
 203    <p>You're done.  Now install the rebuilt pieces with
 204       <pre>
 205    make install</pre>
 206       or
 207       <pre>
 208    make install-gcc
 209    make install-target-libstdc++-v3</pre>
 210    </p>
 211
 212
 213 <hr>
 214 <h2><a name="postinstall">Post-installation</a></h2>
 215    <p>Installation will create the <em>destdir</em> directory and
 216       populate it with subdirectories:
 217       <pre>
 218    lib/
 219    include/g++-v3/
 220       backward/
 221       bits/
 222       <em>cpu-vendor-os</em>/bits/
 223       ext/</pre>
 224    </p>
 225    <p>If you used the version-specific-libs configure option, then most of
 226       the headers and library files will be moved under
 227       <code>lib/gcc-lib/</code> instead.
 228    </p>
 229    <p>You can check the status of the build without installing it using
 230       <pre>
 231    make check</pre>
 232       or you can check the status of the installed library using
 233       <pre>
 234    make check-install</pre>
 235       in the <em>libbuilddir</em> directory.
 236       These commands will create a 'testsuite' directory underneath
 237       <em>libbuilddir</em> containing the results of the tests.  We are
 238       interested in any strange failures of the testsuite; please see
 239       <a href="faq/index.html#2_4">FAQ 2.4</a> for which files to examine.
 240    </p>
 241
 242
 243 <hr>
 244 <h2><a name="usage">Using the library</a></h2>
 245    <li><B>Find the new library at runtime (shared linking only)</B>
 246        <p>If you only built a static library (libstdc++.a), or if you
 247           specified static linking, you don't have to worry about this.
 248           But if you built a shared library (libstdc++.so) and linked
 249           against it, then you will need to find that library when you
 250           run the executable.
 251        </p>
 252        <p>Methods vary for different platforms and different styles, but
 253           the usual ones are printed to the screen during installation.
 254           They include:
 255           <ul>
 256           <li>At runtime set LD_LIBRARY_PATH in your environment correctly,
 257               so that the shared library for libstdc++ can be found and
 258               loaded.  Be certain that you understand all of the other
 259               implications and behavior of LD_LIBRARY_PATH first (few
 260               people do, and they get into trouble).
 261           <li>Compile the path to find the library at runtime into the
 262               program.  This can be done by passing certain options to g++,
 263               which will in turn pass them on to the linker.  The exact
 264               format of the options is dependent on which linker you use:
 265               <ul>
 266   <li>GNU ld (default on Linux):<code>  -Wl,--rpath,<em>destdir</em>/lib</code>
 267   <li>IRIX ld:<code>  -Wl,-rpath,<em>destdir</em>/lib</code>
 268   <li>Solaris ld:<code>  -Wl,-R<em>destdir</em>/lib</code>
 269   <li>More...?  Let us know!
 270               </ul>
 271           </ul>
 272        </p>
 273        <p>Use the <code>ldd(1)</code> utility to show which library the system
 274           thinks it will get at runtime.
 275        </p>
 276        <p>A libstdc++.la file is also installed, for use with Libtool.  If
 277           you use Libtool to create your executables, these details are
 278           taken care of for you.
 279        </p>
 280    </ol>
 281    </p>
 282
 283
 284 <!--
 285 <hr>
 286 <h2><a name=""></a></h2>
 287    <p>
 288    </p>
 289
 290 -->
 291
 292 <!-- ####################################################### -->
 293
 294 <hr>
 295 <p class="fineprint"><em>
 296 See <a href="17_intro/license.html">license.html</a> for copying conditions.
 297 Comments and suggestions are welcome, and may be sent to
 298 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
 299 </em></p>
 300
 301
 302 </body>
 303 </html>
 304