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.3 2001/01/23 17:02:26 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.  We are moving to DejaGNU, so you'll
  62       probably want to get that.
  63    </P>
  64
  65    <P>As of June 19, 2000, libstdc++ attempts to use tricky and
  66       space-saving features of the GNU toolchain, enabled with
  67       <TT>-ffunction-sections -fdata-sections -Wl,--gc-sections</TT>.
  68       To obtain maximum benefit from this, binutils after this date
  69       should also be used (bugs were fixed with C++ exception handling
  70       related to this change in libstdc++-v3).  The version of these
  71       tools should be <TT>2.10.90</TT>, and you can get snapshots (as
  72       well as releases) of binutils
  73       <A HREF="ftp://sources.redhat.com/pub/binutils">here</A>.
  74    </P>
  75
  76    <P>Finally, a few system-specific requirements:
  77       <DL>
  78         <DT>Cygwin
  79         <DD>If you are using Cygwin to compile libstdc++-v3 on Win32, you'll
  80             have to get a version of the cygwin1.dll that is dated on or
  81             after February 1, 2000.  This is necessary to successfully run
  82             the script &quot;mknumeric_limits&quot; which probes the
  83             floating-point
  84             environment of the host in question -- before this date, Cygwin
  85             would freeze when running this script.  In addition, you may
  86             want to get a current version of libtool (say libtool-1.3.4
  87             and above) as earlier versions supposedly had problems creating
  88             shared libraries.
  89
  90       </DL>
  91    </P>
  92
  93 <HR>
  94
  95 <H2><A NAME="srcsetup">Setting up the source directories</A></H2>
  96    <P><EM>As the libstdc++-v3 sources and the core GCC sources have
  97       converged, more and more effort goes to building the
  98       library as the default version to be shipped with g++.  With the
  99       2.90.8 snapshot, and especially for CVS versions after this
 100       release, this is treated as the usual scenario.  If you want to
 101       build the library all by itself, you will need to explicitly
 102       disable certain features (like namespaces) since the core GCC
 103       library, libgcc.a, will not be rebuilt with those same features.
 104    </EM>
 105    </P>
 106
 107    <P>By default, all configurations of libstdc++-v3 now have namespaces
 108       enabled.  Being able to select/de-select this option was a complex task
 109       that had hopelessly confused many otherwise intelligent people, and
 110       provided an endless stream of silent cursing and cries for help.
 111       Because of this, gcc sources are required, and are no longer optional.
 112    </P>
 113
 114    <P>The following definitions will be used throughout the rest of this
 115       document:
 116       <UL>
 117          <LI><EM>gccsrcdir</EM>:  The directory holding the source of the
 118                  compiler.  It should have several subdirectories like
 119                  <EM>gccsrcdir</EM>/libio and <EM>gccsrcdir</EM>/gcc.
 120          <LI><EM>libsrcdir</EM>:  The directory holding the source of the
 121                  C++ library.
 122          <LI><EM>gccbuilddir</EM>:  The build directory for the compiler
 123                  in <EM>gccsrcdir</EM>.  GCC requires that it be built in
 124                  a different directory than its sources.
 125          <LI><EM>libbuilddir</EM>:  The build directory for libstdc++.
 126          <LI><EM>destdir</EM>:  The eventual installation directory for
 127                  the compiler/libraries, set with the --prefix option to
 128                  the configure script.
 129       </UL>
 130       Note:
 131       <OL>
 132          <LI>The .91 snapshot and following are intended to replace the
 133              library that comes with the compiler, so <EM>libsrcdir</EM>
 134              and <EM>libbuilddir</EM> must be contained under
 135              <EM>gccsrcdir</EM> and <EM>gccbuilddir</EM>, respectively.
 136          <LI>The source, build, and installation directories should
 137              not be parents of one another; i.e., these should all be
 138              separate directories. Please don't build out of the
 139              source directory.
 140       </OL>
 141    </P>
 142
 143    <P>Since the release of libstdc++-2.90.8, configuration patches have gone
 144       into CVS gcc that make the management of the various libstdc++ source
 145       trees a bit easier.  Because of this, both libstdc++-v2 and
 146       libstdc++-v3 and live together in peace, without the need
 147       for soft linking.  The setup instructions are slightly different,
 148       depending on whether you want to use CVS gcc or a snapshot.  Please
 149       choose the appropriate scenario:
 150    </P>
 151
 152    <P><B>...with a gcc-2.9[67] snapshot</B>
 153       <P>Unpack the <EM>gccsrcdir</EM> and go into that directory.  For
 154          instance, <TT>gcc-2.95.2</TT> is a valid <EM>gccsrcdir</EM>.
 155          Once in <EM>gccsrcdir</EM>, you'll need to rename or delete
 156          the libstdc++-v3 directory which comes with that snapshot:
 157          <PRE>
 158    mv libstdc++-v3 libstdc++-v3-previous  <STRONG>[OR]</STRONG>
 159    rm -r libstdc++-v3</PRE>
 160       </P>
 161       <P>Next, unpack the libstdc++-v3 library tarball into the
 162          <EM>gccsrcdir</EM> directory; it will create a
 163          <EM>libsrcdir</EM> called <TT>libstdc++-<EM>version</EM></TT>:
 164          <PRE>
 165    gzip -dc libstdc++-version.tar.gz | tar xf -</PRE>
 166       </P>
 167       <P>Finally, make a soft link between <EM>libsrcdir</EM> and
 168          <TT>libstdc++-v3</TT> so that libstdc++-v3 will be the default C++
 169          library used.
 170          <PRE>
 171    ln -s <EM>libsrcdir</EM> libstdc++-v3</PRE>
 172       </P>
 173    </P>
 174
 175    <P><B>...with CVS gcc</B>
 176       <P>Check out or download the gcc sources: the resulting source
 177          directory is <EM>gccsrcdir</EM>.  Once in <EM>gccsrcdir</EM>,
 178          you'll need to rename or delete the libstdc++-v3 directory
 179          which comes with that snapshot:
 180          <PRE>
 181    mv libstdc++-v3 libstdc++-v3-previous  <STRONG>[OR]</STRONG>
 182    rm -r libstdc++-v3</PRE>
 183       </P>
 184       <P>Next, unpack the libstdc++-v3 library tarball into this
 185          <EM>gccsrcdir</EM> directory; it will create a
 186          <EM>libsrcdir</EM> called <TT>libstdc++-<EM>version</EM></TT>:
 187          <PRE>
 188    gzip -dc libstdc++-version.tar.gz | tar xf -</PRE>
 189       </P>
 190       <P>Finally, rename <EM>libsrcdir</EM> to <TT>libstdc++-v3</TT> so that
 191          gcc's configure flags will be able to deal with the new library.
 192          <PRE>
 193    mv <EM>libsrcdir</EM> libstdc++-v3</PRE>
 194       </P>
 195    </P>
 196
 197
 198 <HR>
 199 <H2><A NAME="config">Configuring</A></H2>
 200    <P>If you have never done this before, you should read the basic
 201       <A HREF="http://gcc.gnu.org/install/">GCC Installation
 202       Instructions</A> first.
 203    </P>
 204    <P>Due to namespaces, when building libstdc++-v3 you'll have to configure
 205       the entire <EM>gccsrcdir</EM> directory.  The full list of libstdc++-v3
 206       specific configuration options, not dependent on the specific compiler
 207       release being used, can be found <A HREF="configopts.html">here</A>.
 208    </P>
 209    <P>Consider possibly using --enable-languages=c++ to save time by only
 210       building the C++ language parts.
 211    </P>
 212
 213    <P><PRE>
 214    cd <EM>gccbuilddir</EM>
 215    <EM>gccsrcdir</EM>/configure --prefix=<EM>destdir</EM> --other-opts...</PRE>
 216    </P>
 217
 218
 219 <HR>
 220 <H2><A NAME="install">Building and installing the library</A></H2>
 221    <P>Now you have a few options:</P>
 222    <H3>[re]building <EM>everything</EM></H3>
 223    <P>If you're building GCC from scratch, you can do the usual
 224       <TT> 'make bootstrap' </TT> here, and libstdc++-v3 will be built
 225       as its default C++ library.  The generated g++ will magically
 226       use the correct headers, link against the correct library
 227       binary, and in general using libstdc++-v3 will be a piece of
 228       cake.  You're done; run <TT>'make install'</TT> (see the GCC
 229       installation instructions) to put the new compiler and libraries
 230       into place.
 231    </P>
 232
 233    <H3>[re]building only libstdc++</H3>
 234    <P>To rebuild just libstdc++, use:
 235       <PRE>
 236    make all-target-<EM>libstdc++-v3</EM></PRE>
 237       This will configure and build the C++ library in the
 238       <EM>gccbuilddir/cpu-vendor-OS/</EM>libstdc++ directory.
 239    </P>
 240    <P>If you are rebuilding from a previous build [attempt], some
 241       information is kept in a cache file.  This is stored in
 242       <EM>gccbuilddir/cpu-vendor-OS/</EM> if you are building with
 243       multilibs (the default), or in
 244       <EM>gccbuilddir/cpu-vendor-OS/</EM>libstdc++-v3 if you have
 245       multilibs disabled.  The filename is config.cache; if previous
 246       information is causing problems, you can delete it entirely, or
 247       simply edit it and remove lines.
 248    </P>
 249    <P>You're done.  Now install the rebuilt pieces with
 250       <PRE>
 251    make install</PRE>
 252       or
 253       <PRE>
 254    make install-gcc
 255    make install-target-libstdc++-v3</PRE>
 256    </P>
 257
 258
 259 <HR>
 260 <H2><A NAME="postinstall">Post-installation</A></H2>
 261    <P>Installation will create the <EM>destdir</EM> directory and
 262       populate it with subdirectories:
 263       <PRE>
 264    lib/
 265    include/g++-v3/
 266       bits/
 267       ext/
 268    CPU-vendor-OS/include/g++-v3/
 269       bits/
 270       ext/</PRE>
 271    </P>
 272    <P>You can check the status of the build without installing it using
 273       <PRE>
 274    make check</PRE>
 275       or you can check the status of the installed library using
 276       <PRE>
 277    make check-install</PRE>
 278       in the <EM>libbuilddir</EM> directory.
 279       These commands will create a 'testsuite' directory underneath
 280       <EM>libbuilddir</EM> containing the results of the tests.  We are
 281       interested in any strange failures of the testsuite; please see
 282       <A HREF="faq/index.html#2_4">FAQ 2.4</A> for which files to examine.
 283    </P>
 284
 285
 286 <HR>
 287 <H2><A NAME="usage">Using the library</A></H2>
 288    <LI><B>Find the new library at runtime (shared linking only)</B>
 289        <P>If you only built a static library (libstdc++.a), or if you
 290           specified static linking, you don't have to worry about this.
 291           But if you built a shared library (libstdc++.so) and linked
 292           against it, then you will need to find that library when you
 293           run the executable.
 294        </P>
 295        <P>Methods vary for different platforms and different styles, but
 296           the usual ones are printed to the screen during installation.
 297           They include:
 298           <UL>
 299           <LI>At runtime set LD_LIBRARY_PATH in your environment correctly,
 300               so that the shared library for libstdc++ can be found and
 301               loaded.  Be certain that you understand all of the other
 302               implications and behavior of LD_LIBRARY_PATH first (few
 303               people do, and they get into trouble).
 304           <LI>Compile the path to find the library at runtime into the
 305               program.  This can be done by passing certain options to g++,
 306               which will in turn pass them on to the linker.  The exact
 307               format of the options is dependent on which linker you use:
 308               <UL>
 309   <LI>GNU ld (default on Linux):<TT>  -Wl,--rpath,<EM>destdir</EM>/lib</TT>
 310   <LI>IRIX ld:<TT>  -Wl,-rpath,<EM>destdir</EM>/lib</TT>
 311   <LI>Solaris ld:<TT>  -Wl,-R<EM>destdir</EM>/lib</TT>
 312   <LI>More...?
 313               </UL>
 314           </UL>
 315        </P>
 316        <P>Use the <TT>ldd(1)</TT> utility to show which library the system
 317           thinks it will get at runtime.
 318        </P>
 319    </OL>
 320    </P>
 321
 322
 323 <!--
 324 <HR>
 325 <H2><A NAME=""></A></H2>
 326    <P>
 327    </P>
 328
 329 -->
 330
 331 <!-- ####################################################### -->
 332
 333 <HR>
 334 <P CLASS="fineprint"><EM>
 335 Comments and suggestions are welcome, and may be sent to
 336 <A HREF="mailto:pme@sources.redhat.com">Phil Edwards</A> or
 337 <A HREF="mailto:gdr@gcc.gnu.org">Gabriel Dos Reis</A>.
 338 <BR> $Id: install.html,v 1.3 2001/01/23 17:02:26 pme Exp $
 339 </EM></P>
 340
 341
 342 </BODY>
 343 </HTML>
 344