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