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@sources.redhat.com (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 <!-- $Id: install.html,v 1.12 2000/12/03 23:47:47 jsm28 Exp $ -->
  11 </HEAD>
  12 <BODY>
  13
  14 <H1 CLASS="centered"><A NAME="top">libstdc++-v3 INSTALL</A></H1>
  15
  16 <P>The latest version of this document is always available at
  17    <A HREF="http://gcc.gnu.org/onlinedocs/libstdc++/install.html">
  18    http://gcc.gnu.org/onlinedocs/libstdc++/install.html</A>.
  19 </P>
  20
  21 <P>To the <A HREF="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</A>.
  22
  23
  24 <!-- ####################################################### -->
  25 <HR>
  26 <H2>Contents</H2>
  27 <UL>
  28    <LI><A HREF="#prereqs">Tools you will need beforehand</A>
  29    <LI><A HREF="#srcsetup">Setting up the source directories</A>
  30    <LI><A HREF="#config">Configuring</A>
  31    <LI><A HREF="#install">Building and installing the library</A>
  32    <LI><A HREF="#postinstall">Post-installation</A>
  33    <LI><A HREF="#usage">Using the library</A>
  34 </UL>
  35
  36 <HR>
  37
  38 <!-- ####################################################### -->
  39
  40 <H2><A NAME="prereqs">Tools you will need beforehand</A></H2>
  41    <P>You will need a recent version of g++ to compile the snapshot of
  42       libstdc++:  gcc-2.95.2 works well, or one of the post-2.95.2 GCC
  43       snapshots (insert standard caveat about using snapshots rather
  44       than formal releases).  You will need the full source
  45       distribution to whatever compiler release you are using.  The
  46       GCC snapshots can be had from one of the sites on their
  47       <A HREF="http://gcc.gnu.org/mirrors.html">mirror list</A>.
  48    </P>
  49
  50    <P>In addition, if you plan to modify the makefiles or regenerate
  51       the configure scripts you'll need the nuevo automake, libtool
  52       and autoconf to regenerate the Makefiles and configure
  53       scripts. These tools are all required to be installed in the
  54       same location (most linux distributions install these tools by
  55       default, so no worries.)
  56    </P>
  57
  58    <P>If you don't have bash, and want to run <TT>'make check'</TT> to
  59       test your build, you'll need to get bash 2.x.  Also recommended
  60       is GNU Make, since it is the only 'make' that will parse these
  61       makefiles correctly.
  62    </P>
  63
  64    <P>As of June 19, 2000, libstdc++ attempts to use tricky and
  65       space-saving features of the GNU toolchain, enabled with
  66       <TT>-ffunction-sections -fdata-sections -Wl,--gc-sections</TT>.
  67       To obtain maximum benefit from this, binutils after this date
  68       should also be used (bugs were fixed with C++ exception handling
  69       related to this change in libstdc++-v3).  The version of these
  70       tools should be <TT>2.10.90</TT>, and you can get snapshots (as
  71       well as releases) of binutils
  72       <A HREF="ftp://sources.redhat.com/pub/binutils">here</A>.
  73    </P>
  74
  75    <P>Finally, a few system-specific requirements:
  76       <DL>
  77         <DT>Cygwin
  78         <DD>If you are using Cygwin to compile libstdc++-v3 on Win32, you'll
  79             have to get a version of the cygwin1.dll that is dated on or
  80             after February 1, 2000.  This is necessary to successfully run
  81             the script &quot;mknumeric_limits&quot; which probes the
  82             floating-point
  83             environment of the host in question -- before this date, Cygwin
  84             would freeze when running this script.  In addition, you may
  85             want to get a current version of libtool (say libtool-1.3.4
  86             and above) as earlier versions supposedly had problems creating
  87             shared libraries.
  88
  89         <DT>Solaris
  90         <DD>We recommend installing the <TT>SUNWxcu4</TT> package from the
  91             Solaris CD before configuring the library.  You can check for
  92             this package as a non-privileged user with the command
  93             &quot;pkginfo SUNWxcu4&quot;.
  94       </DL>
  95    </P>
  96
  97 <HR>
  98
  99 <H2><A NAME="srcsetup">Setting up the source directories</A></H2>
 100    <P><EM>As the libstdc++-v3 sources and the core GCC sources have
 101       converged, more and more effort goes to building the
 102       library as the default version to be shipped with g++.  With the
 103       2.90.8 snapshot, and especially for CVS versions after this
 104       release, this is treated as the usual scenario.  If you want to
 105       build the library all by itself, you will need to explicitly
 106       disable certain features (like namespaces) since the core GCC
 107       library, libgcc.a, will not be rebuilt with those same features.
 108    </EM>
 109    </P>
 110
 111    <P>By default, all configurations of libstdc++-v3 now have namespaces
 112       enabled.  Being able to select/de-select this option was a complex task
 113       that had hopelessly confused many otherwise intelligent people, and
 114       provided an endless stream of silent cursing and cries for help.
 115       Because of this, gcc sources are required, and are no longer optional.
 116    </P>
 117
 118    <P>The following definitions will be used throughout the rest of this
 119       document:
 120       <UL>
 121          <LI><EM>gccsrcdir</EM>:  The directory holding the source of the
 122                  compiler.  It should have several subdirectories like
 123                  <EM>gccsrcdir</EM>/libio and <EM>gccsrcdir</EM>/gcc.
 124          <LI><EM>libsrcdir</EM>:  The directory holding the source of the
 125                  C++ library.
 126          <LI><EM>gccbuilddir</EM>:  The build directory for the compiler
 127                  in <EM>gccsrcdir</EM>.  GCC requires that it be built in
 128                  a different directory than its sources.
 129          <LI><EM>libbuilddir</EM>:  The build directory for libstdc++.
 130          <LI><EM>destdir</EM>:  The eventual installation directory for
 131                  the compiler/libraries, set with the --prefix option to
 132                  the configure script.
 133       </UL>
 134       Note:
 135       <OL>
 136          <LI>The .8 snapshot and following are intended to replace the
 137              library that comes with the compiler, so <EM>libsrcdir</EM>
 138              and <EM>libbuilddir</EM> must be contained under
 139              <EM>gccsrcdir</EM> and <EM>gccbuilddir</EM>, respectively.
 140          <LI>The source, build, and installation directories should
 141              not be parents of one another; i.e., these should all be
 142              separate directories. Please don't build out of the
 143              source directory.
 144       </OL>
 145    </P>
 146
 147    <P>Since the release of libstdc++-2.90.8, configuration patches have gone
 148       into CVS gcc that make the management of the various libstdc++ source
 149       trees a bit easier.  Because of this, both libstdc++-v2 and
 150       libstdc++-v3 and live together more or less in peace, without the need
 151       for soft linking.  If a CVS gcc source directory after April 5, 2000 is
 152       being used, then the directions are slightly different:  please pick
 153       which of the following two scenarios best represents your particular
 154       situation.
 155    </P>
 156
 157    <P><B>...with gcc-2.95.2</B>
 158       <P>Unpack the <EM>gccsrcdir</EM> and go into that directory.  For
 159          instance, <TT>gcc-2.95.2</TT> is a valid <EM>gccsrcdir</EM>.
 160          Once in <EM>gccsrcdir</EM>, you'll need to rename the directories
 161          called <TT> libstdc++ </TT> and <TT> libio </TT> like so:
 162          <PRE>
 163    mv libstdc++ libstdc++-v2
 164    mv libio libio-v2</PRE>
 165       </P>
 166       <P>Next, unpack the libstdc++-v3 library tarball into the
 167          <EM>gccsrcdir</EM> directory; it will create a
 168          <EM>libsrcdir</EM> called <TT>libstdc++-<EM>version</EM></TT>:
 169          <PRE>
 170    gzip -dc libstdc++-version.tar.gz | tar xf -</PRE>
 171       </P>
 172       <P>Finally, make a soft link between <EM>libsrcdir</EM> and
 173          <TT>libstdc++</TT> so that libstdc++-v3 will be the default C++
 174          library used.
 175          <PRE>
 176    ln -s <EM>libsrcdir</EM> libstdc++</PRE>
 177          This complexity of having two completely separate libstdc++
 178          libraries is necessary so that you can unlink <EM>libsrcdir</EM>
 179          and update the compiler sources.  If you're not this adventurous, or
 180          would not like to switch between different C++ standard libraries,
 181          this extra effort is probably wasted; just remove the v2 sources.
 182       </P>
 183    </P>
 184
 185    <P><B>...with CVS gcc</B>
 186       <P>Check out or download the gcc sources: the resulting source
 187          directory is <EM>gccsrcdir</EM>.
 188       </P>
 189       <P>Next, unpack the libstdc++-v3 library tarball into this
 190          <EM>gccsrcdir</EM> directory; it will create a
 191          <EM>libsrcdir</EM> called <TT>libstdc++-<EM>version</EM></TT>:
 192          <PRE>
 193    gzip -dc libstdc++-version.tar.gz | tar xf -</PRE>
 194       </P>
 195
 196       <P>If CVS libstdc++-v3 is being used instead of a snapshot's tarball,
 197          then move the source directory from the CVS checkout into the
 198          <EM>gccsrcdir</EM> directory.
 199
 200       <P>Finally, rename <EM>libsrcdir</EM> to <TT>libstdc++-v3</TT> so that
 201          gcc's configure flags will be able to deal with the new library.
 202          <PRE>
 203    mv <EM>libsrcdir</EM> libstdc++-v3</PRE>
 204       </P>
 205    </P>
 206
 207
 208 <HR>
 209 <H2><A NAME="config">Configuring</A></H2>
 210    <P>Due to namespaces, when building libstdc++-v3 you'll have to configure
 211       the entire <EM>gccsrcdir</EM> directory.  The full list of libstdc++-v3
 212       specific configuration options, not dependent on the specific compiler
 213       release being used, can be found <A HREF="configopts.html">here</A>.
 214    </P>
 215    <P>Consider possibly using --enable-languages=c++ to save time by only
 216       building the C++ language parts.
 217    </P>
 218
 219    <P><B>...with gcc-2.95.2</B>
 220       <PRE>
 221    <EM>gccsrcdir</EM>/configure --prefix=<EM>destdir</EM></PRE>
 222    </P>
 223
 224    <P><B>...with CVS gcc</B>
 225       <PRE>
 226    <EM>gccsrcdir</EM>/configure --prefix=<EM>destdir</EM> --enable-libstdcxx-v3</PRE>
 227    </P>
 228
 229    <P>Adding <TT>--enable-libstdcxx-v3</TT> automatically selects libstdc++-v3
 230       as the C++ library to be used alongside the C++ compiler being built,
 231       and also enables -fhonor-std by default.  This option is not available
 232       with gcc-2.95.2.
 233    </P>
 234
 235
 236 <HR>
 237 <H2><A NAME="install">Building and installing the library</A></H2>
 238    <P>Now you have a few options:</P>
 239    <H3>[re]building <EM>everything</EM></H3>
 240    <P>If you're building GCC from scratch, you can do the usual
 241       <TT> 'make bootstrap' </TT> here, and libstdc++-v3 will be built
 242       as its default C++ library.  The generated g++ will magically
 243       use the correct headers, link against the correct library
 244       binary, and in general using libstdc++-v3 will be a piece of
 245       cake.  You're done; run <TT>'make install'</TT> (the GCC
 246       Installation instructions) to put the new compiler and libraries
 247       into place.
 248    </P>
 249
 250    <H3>[re]building only libstdc++</H3>
 251    <P>Due to differences in the configure process, the resulting Makefiles
 252       in the<EM>gccbuilddir</EM> will have different rules depending on
 253       the source base being used.
 254    </P>
 255
 256    <P><B>...with gcc-2.95.2</B>
 257       <BLOCKQUOTE>
 258       <EM>libstdc++-rule</EM> is <TT>libstdc++</TT>
 259       </BLOCKQUOTE>
 260    </P>
 261
 262    <P><B>...with CVS gcc</B>
 263       <BLOCKQUOTE>
 264       <EM>libstdc++-rule</EM> is <TT>libstdc++-v3</TT>
 265       </BLOCKQUOTE>
 266    </P>
 267
 268    <P>To rebuild just libstdc++, use:
 269       <PRE>
 270    make all-target-<EM>libstdc++-rule</EM></PRE>
 271       This will configure and build the C++ library in the
 272       <EM>gccbuilddir/cpu-vendor-OS/</EM>libstdc++ directory.
 273       As en example, for CVS gcc this would be
 274       <TT>make all-target-libstdc++-v3</TT>, and for gcc-2.95.2 it would be
 275       <TT>make all-target-libstdc++</TT>
 276    </P>
 277    <P>If the build fails with a &quot;warning: can't inline call&quot;
 278       message when compiling stringMAIN.cc, see <A HREF="#Werror">the
 279       resolution at the end of this document</A>.
 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
 291       <PRE>
 292    make install</PRE>
 293       or
 294       <PRE>
 295    make install-gcc
 296    make install-target-<EM>libstdc++-rule</EM></PRE>
 297    </P>
 298
 299
 300 <HR>
 301 <H2><A NAME="postinstall">Post-installation</A></H2>
 302    <P>Installation will create the <EM>destdir</EM> directory and
 303       populate it with subdirectories:
 304       <PRE>
 305    lib/
 306    include/g++-v3/
 307       bits/
 308       backward/
 309       ext/</PRE>
 310    </P>
 311    <P>You can check the status of the build without installing it using
 312       <PRE>
 313    make check</PRE>
 314       or you can check the status of the installed library using
 315       <PRE>
 316    make check-target-<EM>libstdc++-rule</EM></PRE>
 317       These commands will create a 'testsuite' directory underneath
 318       <EM>libbuilddir</EM> containing the results of the tests.  We are
 319       interested in any strange failures of the testsuite; please see
 320       <A HREF="faq/index.html#2_4">FAQ 2.4</A> for which files to examine.
 321    </P>
 322
 323
 324 <HR>
 325 <H2><A NAME="usage">Using the library</A></H2>
 326    <LI><B>Find the new library at runtime (shared linking only)</B>
 327        <P>If you only built a static library (libstdc++.a), or if you
 328           specified static linking, you don't have to worry about this.
 329           But if you built a shared library (libstdc++.so) and linked
 330           against it, then you will need to find that library when you
 331           run the executable.
 332        </P>
 333        <P>Methods vary for different platforms and different styles, but
 334           the usual ones are printed to the screen during installation.
 335           They include:
 336           <UL>
 337           <LI>At runtime set LD_LIBRARY_PATH in your environment correctly,
 338               so that the shared library for libstdc++ can be found and
 339               loaded.  Be certain that you understand all of the other
 340               implications and behavior of LD_LIBRARY_PATH first (few
 341               people do, and they get into trouble).
 342           <LI>Compile the path to find the library at runtime into the
 343               program.  This can be done by passing certain options to g++,
 344               which will in turn pass them on to the linker.  The exact
 345               format of the options is dependent on which linker you use:
 346               <UL>
 347   <LI>GNU ld (default on Linux):<TT>  -Wl,--rpath -Wl,<EM>destdir</EM>/lib</TT>
 348   <LI>IRIX ld:<TT>  -Wl,-rpath -Wl,<EM>destdir</EM>/lib</TT>
 349   <LI>Solaris ld:<TT>  -Wl,-R<EM>destdir</EM>/lib</TT>
 350   <LI>More...?
 351               </UL>
 352           </UL>
 353        </P>
 354        <P>Use the <TT>ldd(1)</TT> utility to show which library the system
 355           thinks it will get at runtime.
 356        </P>
 357    </OL>
 358    </P>
 359
 360
 361 <HR>
 362 <H3><A NAME="Werror"><TT>warning: can't inline call to</TT>...</A></H3>
 363    <P>When building the .8 snapshot with g++ 2.95.2, compilation may halt
 364       with this warning message.  The &quot;problem&quot; is the -Werror
 365       flag being passed to the compiler, which says to treat warnings as
 366       errors.  (This plus a high warning level makes us track down bugs
 367       <EM>quickly</EM>.)  The compiler can't inline a certain call, prints
 368       a warning, and dies.
 369    </P>
 370    <P>The workaround is to edit either <EM>libsrcdir</EM>/src/Makefile.in
 371       (before configuring) or <EM>bld-libstdc++</EM>/src/Makefile
 372       (after configuring).  There's one line that reads
 373       <PRE>
 374    WERROR = -Werror</PRE>
 375       Delete the flag itself, so that the line reads
 376       <PRE>
 377    WERROR =</PRE>
 378       Then the compiler will still print a warning, but it won't die.
 379    </P>
 380    <P>For the curious, this &quot;problem&quot; is actually a symptom
 381       of something else.  The compiler in CVS could inline more than what
 382       2.95.2 does, and the libstdc++ changes were made with that
 383       compiler.  One of the libstdc++ maintainers explains this
 384 <A HREF="http://gcc.gnu.org/ml/libstdc++/2000-q1/msg00420.html">here</A>.
 385    </P>
 386    <P>This has been patched in current CVS sources.
 387    </P>
 388
 389
 390 <!--
 391 <HR>
 392 <H2><A NAME=""></A></H2>
 393    <P>
 394    </P>
 395
 396 -->
 397
 398 <!-- ####################################################### -->
 399
 400 <HR>
 401 <P CLASS="fineprint"><EM>
 402 Comments and suggestions are welcome, and may be sent to
 403 <A HREF="mailto:pme@sources.redhat.com">Phil Edwards</A> or
 404 <A HREF="mailto:gdr@gcc.gnu.org">Gabriel Dos Reis</A>.
 405 <BR> $Id: install.html,v 1.12 2000/12/03 23:47:47 jsm28 Exp $
 406 </EM></P>
 407
 408
 409 </BODY>
 410 </HTML>
 411