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
  71       -Wl,--gc-sections</code>.  To obtain maximum benefit from this,
  72       binutils after this date should also be used (bugs were fixed
  73       with C++ exception handling related to this change in
  74       libstdc++-v3).  The version of these tools should be
  75       <code>2.10.90</code>, or later, and you can get snapshots (as
  76       well as releases) of binutils
  77       <a href="ftp://sources.redhat.com/pub/binutils">here</a>. The
  78       configure process will automatically detect and use these
  79       features if the underlying support is present.
  80    </p>
  81
  82    <p>If you are using a 3.1-series libstdc++ snapshot, then the
  83       requirements are slightly more stringent: the compiler sources
  84       must also be 3.1 or later (for both technical and licensing
  85       reasons), and your binutils must be 2.11.95 or later if you want
  86       to use symbol versioning in shared libraries. Again, the
  87       configure process will automatically detect and use these
  88       features if the underlying support is present.
  89    </p>
  90
  91     <p>Finally, a few system-specific requirements:
  92       <dl>
  93         <dt> linux
  94
  95         <dd>If you are using gcc 3.1 or later on linux, and are using
  96         the gnu locale model (enabled by default for sufficient
  97         versions of glibc), the following locales are used and tested
  98         in the libstdc++ testsuites: en_HK, en_US, fr_FR, fr_FR@euro,
  99         de_DE, de_DE@euro, ja_JP.eucjp, and it_IT. Failure to have the
 100         underlying "C" library locale information installed will mean
 101         that C++ named locales for the above regions will not work:
 102         because of this, the libstdc++ testsuite will not pass the
 103         named locale tests. If this isn't an issue, don't worry about
 104         it. If named locales are needed, the underlying locale
 105         information must be installed. Note that rebuilding libstdc++
 106         after locales are installed is not necessary.
 107
 108         <p> To install
 109         support for locales, do only one of the following: </p>
 110         <p>
 111           <li> install all locales
 112           <p> <code> export LC_ALL=C </code> </p>
 113           <p> <code> rpm -e glibc-common --nodeps </code> </p>
 114           <p> <code> rpm -i --define "_install_langs all"
 115           glibc-common-2.2.5-34.i386.rpm </code> </p>
 116           <li> install just the necessary locales
 117           <p> <code> localedef -i de_DE -f ISO-8859-1 de_DE </code> </p>
 118          </p>
 119       </dl>
 120    </p>
 121
 122 <hr>
 123
 124 <h2><a name="srcsetup">Setting up the source directories</a></h2>
 125    <p>The following definitions will be used throughout the rest of this
 126       document:
 127       <ul>
 128          <li><em>gccsrcdir</em>:  The directory holding the source of the
 129                  compiler.  It should have several subdirectories like
 130                  <em>gccsrcdir</em>/libio and <em>gccsrcdir</em>/gcc.
 131          <li><em>libsrcdir</em>:  The directory holding the source of the
 132                  C++ library.
 133          <li><em>gccbuilddir</em>:  The build directory for the compiler
 134                  in <em>gccsrcdir</em>.  GCC requires that it be built in
 135                  a different directory than its sources.
 136          <li><em>libbuilddir</em>:  The build directory for libstdc++.
 137          <li><em>destdir</em>:  The eventual installation directory for
 138                  the compiler/libraries, set with the --prefix option to
 139                  the configure script.
 140       </ul>
 141       Note:
 142       <ol>
 143          <li>The 3.0 version and following are intended to replace the
 144              library that comes with the compiler, so <em>libsrcdir</em>
 145              and <em>libbuilddir</em> must be contained under
 146              <em>gccsrcdir</em> and <em>gccbuilddir</em>, respectively.
 147          <li>The source, build, and installation directories should
 148              not be parents of one another; i.e., these should all be
 149              separate directories. Please don't build out of the
 150              source directory.
 151       </ol>
 152    </p>
 153
 154    <p>Check out or download the GCC sources: the resulting source directory
 155       (<code>gcc</code> or <code>gcc-3.0.3</code>, for example) is
 156       <em>gccsrcdir</em>.
 157       Once in <em>gccsrcdir</em>, you'll need to rename or delete the
 158       libstdc++-v3 directory which comes with that snapshot:
 159       <pre>
 160    mv libstdc++-v3 libstdc++-v3-previous  <strong>[OR]</strong>
 161    rm -r libstdc++-v3</pre>
 162    </p>
 163    <p>Next, unpack the libstdc++-v3 library tarball into this
 164       <em>gccsrcdir</em> directory; it will create a
 165       <em>libsrcdir</em> called <code>libstdc++-<em>version</em></code>:
 166       <pre>
 167    gzip -dc libstdc++-version.tar.gz | tar xf -</pre>
 168    </p>
 169    <p>Finally, rename <em>libsrcdir</em> to <code>libstdc++-v3</code> so that
 170       gcc's configure flags will be able to deal with the new library.
 171       <pre>
 172    mv <em>libsrcdir</em> libstdc++-v3</pre>
 173    </p>
 174
 175
 176 <hr>
 177 <h2><a name="config">Configuring</a></h2>
 178    <p>If you have never done this before, you should read the basic
 179       <a href="http://gcc.gnu.org/install/">GCC Installation
 180       Instructions</a> first.  Read <em>all of them</em>.
 181       <strong>Twice.</strong>
 182    </p>
 183    <p>When building libstdc++-v3 you'll have to configure
 184       the entire <em>gccsrcdir</em> directory.  The full list of libstdc++-v3
 185       specific configuration options, not dependent on the specific compiler
 186       release being used, can be found <a href="configopts.html">here</a>.
 187    </p>
 188    <p>Consider possibly using --enable-languages=c++ to save time by only
 189       building the C++ language parts.
 190    </p>
 191
 192    <p><pre>
 193    cd <em>gccbuilddir</em>
 194    <em>gccsrcdir</em>/configure --prefix=<em>destdir</em> --other-opts...</pre>
 195    </p>
 196
 197
 198 <hr>
 199 <h2><a name="install">Building and installing the library</a></h2>
 200    <p>Now you have a few options:</p>
 201    <h3>[re]building <em>everything</em></h3>
 202    <p>If you're building GCC from scratch, you can do the usual
 203       <code> 'make bootstrap' </code> here, and libstdc++-v3 will be built
 204       as its default C++ library.  The generated g++ will magically
 205       use the correct headers, link against the correct library
 206       binary, and in general using libstdc++-v3 will be a piece of
 207       cake.  You're done; run <code>'make install'</code> (see the GCC
 208       installation instructions) to put the new compiler and libraries
 209       into place.
 210    </p>
 211
 212    <h3>[re]building only libstdc++</h3>
 213    <p>To rebuild just libstdc++, use:
 214       <pre>
 215    make all-target-<em>libstdc++-v3</em></pre>
 216       This will configure and build the C++ library in the
 217       <em>gccbuilddir/cpu-vendor-os/</em>libstdc++ directory.
 218    </p>
 219    <p>If you are rebuilding from a previous build [attempt], some
 220       information is kept in a cache file.  This is stored in
 221       <em>gccbuilddir/cpu-vendor-os/</em> if you are building with
 222       multilibs (the default), or in
 223       <em>gccbuilddir/cpu-vendor-os/</em>libstdc++-v3 if you have
 224       multilibs disabled.  The filename is config.cache; if previous
 225       information is causing problems, you can delete it entirely, or
 226       simply edit it and remove lines.
 227    </p>
 228    <p>You're done.  Now install the rebuilt pieces with
 229       <pre>
 230    make install</pre>
 231       or
 232       <pre>
 233    make install-gcc
 234    make install-target-libstdc++-v3</pre>
 235    </p>
 236
 237
 238 <hr>
 239 <h2><a name="postinstall">Post-installation</a></h2>
 240    <p>Installation will create the <em>destdir</em> directory and
 241       populate it with subdirectories:
 242       <pre>
 243    lib/
 244    include/g++-v3/
 245       backward/
 246       bits/
 247       <em>cpu-vendor-os</em>/bits/
 248       ext/</pre>
 249    </p>
 250    <p>If you used the version-specific-libs configure option, then most of
 251       the headers and library files will be moved under
 252       <code>lib/gcc-lib/</code> instead.
 253    </p>
 254    <p>You can check the status of the build without installing it using
 255       <pre>
 256    make check</pre>
 257       or you can check the status of the installed library using
 258       <pre>
 259    make check-install</pre>
 260       in the <em>libbuilddir</em> directory.
 261       These commands will create a 'testsuite' directory underneath
 262       <em>libbuilddir</em> containing the results of the tests.  We are
 263       interested in any strange failures of the testsuite; please see
 264       <a href="faq/index.html#2_4">FAQ 2.4</a> for which files to examine.
 265    </p>
 266
 267
 268 <hr>
 269 <h2><a name="usage">Using the library</a></h2>
 270    <li><B>Find the new library at runtime (shared linking only)</B>
 271        <p>If you only built a static library (libstdc++.a), or if you
 272           specified static linking, you don't have to worry about this.
 273           But if you built a shared library (libstdc++.so) and linked
 274           against it, then you will need to find that library when you
 275           run the executable.
 276        </p>
 277        <p>Methods vary for different platforms and different styles, but
 278           the usual ones are printed to the screen during installation.
 279           They include:
 280           <ul>
 281           <li>At runtime set LD_LIBRARY_PATH in your environment correctly,
 282               so that the shared library for libstdc++ can be found and
 283               loaded.  Be certain that you understand all of the other
 284               implications and behavior of LD_LIBRARY_PATH first (few
 285               people do, and they get into trouble).
 286           <li>Compile the path to find the library at runtime into the
 287               program.  This can be done by passing certain options to g++,
 288               which will in turn pass them on to the linker.  The exact
 289               format of the options is dependent on which linker you use:
 290               <ul>
 291   <li>GNU ld (default on Linux):<code>  -Wl,--rpath,<em>destdir</em>/lib</code>
 292   <li>IRIX ld:<code>  -Wl,-rpath,<em>destdir</em>/lib</code>
 293   <li>Solaris ld:<code>  -Wl,-R<em>destdir</em>/lib</code>
 294   <li>More...?  Let us know!
 295               </ul>
 296           </ul>
 297        </p>
 298        <p>Use the <code>ldd(1)</code> utility to show which library the system
 299           thinks it will get at runtime.
 300        </p>
 301        <p>A libstdc++.la file is also installed, for use with Libtool.  If
 302           you use Libtool to create your executables, these details are
 303           taken care of for you.
 304        </p>
 305    </ol>
 306    </p>
 307
 308
 309 <!--
 310 <hr>
 311 <h2><a name=""></a></h2>
 312    <p>
 313    </p>
 314
 315 -->
 316
 317 <!-- ####################################################### -->
 318
 319 <hr>
 320 <p class="fineprint"><em>
 321 See <a href="17_intro/license.html">license.html</a> for copying conditions.
 322 Comments and suggestions are welcome, and may be sent to
 323 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
 324 </em></p>
 325
 326
 327 </body>
 328 </html>
 329