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.2 2001/01/21 09:36:09 pme 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++, 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       </DL>
  90    </P>
  91
  92 <HR>
  93
  94 <H2><A NAME="srcsetup">Setting up the source directories</A></H2>
  95    <P><EM>As the libstdc++-v3 sources and the core GCC sources have
  96       converged, more and more effort goes to building the
  97       library as the default version to be shipped with g++.  With the
  98       2.90.8 snapshot, and especially for CVS versions after this
  99       release, this is treated as the usual scenario.  If you want to
 100       build the library all by itself, you will need to explicitly
 101       disable certain features (like namespaces) since the core GCC
 102       library, libgcc.a, will not be rebuilt with those same features.
 103    </EM>
 104    </P>
 105
 106    <P>By default, all configurations of libstdc++-v3 now have namespaces
 107       enabled.  Being able to select/de-select this option was a complex task
 108       that had hopelessly confused many otherwise intelligent people, and
 109       provided an endless stream of silent cursing and cries for help.
 110       Because of this, gcc sources are required, and are no longer optional.
 111    </P>
 112
 113    <P>The following definitions will be used throughout the rest of this
 114       document:
 115       <UL>
 116          <LI><EM>gccsrcdir</EM>:  The directory holding the source of the
 117                  compiler.  It should have several subdirectories like
 118                  <EM>gccsrcdir</EM>/libio and <EM>gccsrcdir</EM>/gcc.
 119          <LI><EM>libsrcdir</EM>:  The directory holding the source of the
 120                  C++ library.
 121          <LI><EM>gccbuilddir</EM>:  The build directory for the compiler
 122                  in <EM>gccsrcdir</EM>.  GCC requires that it be built in
 123                  a different directory than its sources.
 124          <LI><EM>libbuilddir</EM>:  The build directory for libstdc++.
 125          <LI><EM>destdir</EM>:  The eventual installation directory for
 126                  the compiler/libraries, set with the --prefix option to
 127                  the configure script.
 128       </UL>
 129       Note:
 130       <OL>
 131          <LI>The .91 snapshot and following are intended to replace the
 132              library that comes with the compiler, so <EM>libsrcdir</EM>
 133              and <EM>libbuilddir</EM> must be contained under
 134              <EM>gccsrcdir</EM> and <EM>gccbuilddir</EM>, respectively.
 135          <LI>The source, build, and installation directories should
 136              not be parents of one another; i.e., these should all be
 137              separate directories. Please don't build out of the
 138              source directory.
 139       </OL>
 140    </P>
 141
 142    <P>Since the release of libstdc++-2.90.8, configuration patches have gone
 143       into CVS gcc that make the management of the various libstdc++ source
 144       trees a bit easier.  Because of this, both libstdc++-v2 and
 145       libstdc++-v3 and live together in peace, without the need
 146       for soft linking.  The setup instructions are slightly different,
 147       depending on whether you want to use CVS gcc or a snapshot.  Please
 148       choose the appropriate scenario:
 149    </P>
 150
 151    <P><B>...with a gcc-2.9[67] snapshot</B>
 152       <P>Unpack the <EM>gccsrcdir</EM> and go into that directory.  For
 153          instance, <TT>gcc-2.95.2</TT> is a valid <EM>gccsrcdir</EM>.
 154          Once in <EM>gccsrcdir</EM>, you'll need to rename the libstdc++-v3
 155          directory which comes with that snapshot:
 156          <PRE>
 157    mv libstdc++-v3 libstdc++-v3-previous</PRE>
 158       </P>
 159       <P>Next, unpack the libstdc++-v3 library tarball into the
 160          <EM>gccsrcdir</EM> directory; it will create a
 161          <EM>libsrcdir</EM> called <TT>libstdc++-<EM>version</EM></TT>:
 162          <PRE>
 163    gzip -dc libstdc++-version.tar.gz | tar xf -</PRE>
 164       </P>
 165       <P>Finally, make a soft link between <EM>libsrcdir</EM> and
 166          <TT>libstdc++-v3</TT> so that libstdc++-v3 will be the default C++
 167          library used.
 168          <PRE>
 169    ln -s <EM>libsrcdir</EM> libstdc++-v3</PRE>
 170       </P>
 171    </P>
 172
 173    <P><B>...with CVS gcc</B>
 174       <P>Check out or download the gcc sources: the resulting source
 175          directory is <EM>gccsrcdir</EM>.  Once in <EM>gccsrcdir</EM>,
 176          you'll need to rename the libstdc++-v3 directory which comes
 177          with that snapshot:
 178    mv libstdc++-v3 libstdc++-v3-previous</PRE>
 179       </P>
 180       <P>Next, unpack the libstdc++-v3 library tarball into this
 181          <EM>gccsrcdir</EM> directory; it will create a
 182          <EM>libsrcdir</EM> called <TT>libstdc++-<EM>version</EM></TT>:
 183          <PRE>
 184    gzip -dc libstdc++-version.tar.gz | tar xf -</PRE>
 185       </P>
 186       <P>Finally, rename <EM>libsrcdir</EM> to <TT>libstdc++-v3</TT> so that
 187          gcc's configure flags will be able to deal with the new library.
 188          <PRE>
 189    mv <EM>libsrcdir</EM> libstdc++-v3</PRE>
 190       </P>
 191    </P>
 192
 193
 194 <HR>
 195 <H2><A NAME="config">Configuring</A></H2>
 196    <P>If you have never done this before, you should read the basic
 197       <A HREF="http://gcc.gnu.org/install/">GCC Installation
 198       Instructions</A> first.
 199    </P>
 200    <P>Due to namespaces, when building libstdc++-v3 you'll have to configure
 201       the entire <EM>gccsrcdir</EM> directory.  The full list of libstdc++-v3
 202       specific configuration options, not dependent on the specific compiler
 203       release being used, can be found <A HREF="configopts.html">here</A>.
 204    </P>
 205    <P>Consider possibly using --enable-languages=c++ to save time by only
 206       building the C++ language parts.
 207    </P>
 208
 209    <P><PRE>
 210    cd <EM>gccbuilddir</EM>
 211    <EM>gccsrcdir</EM>/configure --prefix=<EM>destdir</EM> --enable-libstdcxx-v3</PRE>
 212    </P>
 213
 214    <P>Adding <TT>--enable-libstdcxx-v3</TT> automatically selects libstdc++-v3
 215       as the C++ library to be used alongside the C++ compiler being built,
 216       and also enables -fhonor-std by default.  This option is not available
 217       with gcc-2.95.2.
 218    </P>
 219
 220
 221 <HR>
 222 <H2><A NAME="install">Building and installing the library</A></H2>
 223    <P>Now you have a few options:</P>
 224    <H3>[re]building <EM>everything</EM></H3>
 225    <P>If you're building GCC from scratch, you can do the usual
 226       <TT> 'make bootstrap' </TT> here, and libstdc++-v3 will be built
 227       as its default C++ library.  The generated g++ will magically
 228       use the correct headers, link against the correct library
 229       binary, and in general using libstdc++-v3 will be a piece of
 230       cake.  You're done; run <TT>'make install'</TT> (see the GCC
 231       installation instructions) to put the new compiler and libraries
 232       into place.
 233    </P>
 234
 235    <H3>[re]building only libstdc++</H3>
 236    <P>To rebuild just libstdc++, use:
 237       <PRE>
 238    make all-target-<EM>libstdc++-v3</EM></PRE>
 239       This will configure and build the C++ library in the
 240       <EM>gccbuilddir/cpu-vendor-OS/</EM>libstdc++ directory.
 241    </P>
 242    <P>If the build fails with a &quot;warning: can't inline call&quot;
 243       message when compiling stringMAIN.cc, see <A HREF="#Werror">the
 244       resolution at the end of this document</A>.
 245    </P>
 246    <P>If you are rebuilding from a previous build [attempt], some
 247       information is kept in a cache file.  This is stored in
 248       <EM>gccbuilddir/cpu-vendor-OS/</EM> if you are building with
 249       multilibs (the default), or in
 250       <EM>gccbuilddir/cpu-vendor-OS/</EM>libstdc++-v3 if you have
 251       multilibs disabled.  The filename is config.cache; if previous
 252       information is causing problems, you can delete it entirely, or
 253       simply edit it and remove lines.
 254    </P>
 255    <P>You're done.  Now install the rebuilt pieces with
 256       <PRE>
 257    make install</PRE>
 258       or
 259       <PRE>
 260    make install-gcc
 261    make install-target-<EM>libstdc++-rule</EM></PRE>
 262    </P>
 263
 264
 265 <HR>
 266 <H2><A NAME="postinstall">Post-installation</A></H2>
 267    <P>Installation will create the <EM>destdir</EM> directory and
 268       populate it with subdirectories:
 269       <PRE>
 270    lib/
 271    include/g++-v3/
 272       bits/
 273       ext/
 274    cpu-vendor-OS/include/g++-v3/
 275       bits/
 276       ext/</PRE>
 277    </P>
 278    <P>You can check the status of the build without installing it using
 279       <PRE>
 280    make check</PRE>
 281       or you can check the status of the installed library using
 282       <PRE>
 283    make check-install</PRE>
 284       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
 292 <HR>
 293 <H2><A NAME="usage">Using the library</A></H2>
 294    <LI><B>Find the new library at runtime (shared linking only)</B>
 295        <P>If you only built a static library (libstdc++.a), or if you
 296           specified static linking, you don't have to worry about this.
 297           But if you built a shared library (libstdc++.so) and linked
 298           against it, then you will need to find that library when you
 299           run the executable.
 300        </P>
 301        <P>Methods vary for different platforms and different styles, but
 302           the usual ones are printed to the screen during installation.
 303           They include:
 304           <UL>
 305           <LI>At runtime set LD_LIBRARY_PATH in your environment correctly,
 306               so that the shared library for libstdc++ can be found and
 307               loaded.  Be certain that you understand all of the other
 308               implications and behavior of LD_LIBRARY_PATH first (few
 309               people do, and they get into trouble).
 310           <LI>Compile the path to find the library at runtime into the
 311               program.  This can be done by passing certain options to g++,
 312               which will in turn pass them on to the linker.  The exact
 313               format of the options is dependent on which linker you use:
 314               <UL>
 315   <LI>GNU ld (default on Linux):<TT>  -Wl,--rpath,<EM>destdir</EM>/lib</TT>
 316   <LI>IRIX ld:<TT>  -Wl,-rpath,<EM>destdir</EM>/lib</TT>
 317   <LI>Solaris ld:<TT>  -Wl,-R<EM>destdir</EM>/lib</TT>
 318   <LI>More...?
 319               </UL>
 320           </UL>
 321        </P>
 322        <P>Use the <TT>ldd(1)</TT> utility to show which library the system
 323           thinks it will get at runtime.
 324        </P>
 325    </OL>
 326    </P>
 327
 328
 329 <HR>
 330 <H3><A NAME="Werror"><TT>warning: can't inline call to</TT>...</A></H3>
 331    <P>When building the .8 snapshot with g++ 2.95.2, compilation may halt
 332       with this warning message.  The &quot;problem&quot; is the -Werror
 333       flag being passed to the compiler, which says to treat warnings as
 334       errors.  (This plus a high warning level makes us track down bugs
 335       <EM>quickly</EM>.)  The compiler can't inline a certain call, prints
 336       a warning, and dies.
 337    </P>
 338    <P>The workaround is to edit either <EM>libsrcdir</EM>/src/Makefile.in
 339       (before configuring) or <EM>bld-libstdc++</EM>/src/Makefile
 340       (after configuring).  There's one line that reads
 341       <PRE>
 342    WERROR = -Werror</PRE>
 343       Delete the flag itself, so that the line reads
 344       <PRE>
 345    WERROR =</PRE>
 346       Then the compiler will still print a warning, but it won't die.
 347    </P>
 348    <P>For the curious, this &quot;problem&quot; is actually a symptom
 349       of something else.  The compiler in CVS could inline more than what
 350       2.95.2 does, and the libstdc++ changes were made with that
 351       compiler.  One of the libstdc++ maintainers explains this
 352 <A HREF="http://gcc.gnu.org/ml/libstdc++/2000-q1/msg00420.html">here</A>.
 353    </P>
 354    <P>This has been patched in current CVS sources.
 355    </P>
 356
 357
 358 <!--
 359 <HR>
 360 <H2><A NAME=""></A></H2>
 361    <P>
 362    </P>
 363
 364 -->
 365
 366 <!-- ####################################################### -->
 367
 368 <HR>
 369 <P CLASS="fineprint"><EM>
 370 Comments and suggestions are welcome, and may be sent to
 371 <A HREF="mailto:pme@sources.redhat.com">Phil Edwards</A> or
 372 <A HREF="mailto:gdr@gcc.gnu.org">Gabriel Dos Reis</A>.
 373 <BR> $Id: install.html,v 1.2 2001/01/21 09:36:09 pme Exp $
 374 </EM></P>
 375
 376
 377 </BODY>
 378 </HTML>
 379