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

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