414 lines
17 KiB
HTML
414 lines
17 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
|
|
<META NAME="AUTHOR" CONTENT="pme@sources.redhat.com (Phil Edwards)">
|
|
<META NAME="KEYWORDS" CONTENT="libstdc++, libstdc++-v3, GCC, g++">
|
|
<META NAME="DESCRIPTION" CONTENT="README for the GNU libstdc++ effort.">
|
|
<META NAME="GENERATOR" CONTENT="vi and eight fingers">
|
|
<TITLE>libstdc++-v3 Installation Instructions</TITLE>
|
|
<LINK REL="home" HREF="http://sources.redhat.com/libstdc++/">
|
|
<LINK REL=StyleSheet HREF="lib3styles.css">
|
|
<!-- $Id: install.html,v 1.9 2000/10/21 00:51:49 jsm28 Exp $ -->
|
|
</HEAD>
|
|
<BODY>
|
|
|
|
<H1 CLASS="centered"><A NAME="top">libstdc++-v3 INSTALL</A></H1>
|
|
|
|
<P>The latest version of this document is always available at
|
|
<A HREF="http://sources.redhat.com/libstdc++/install.html">
|
|
http://sources.redhat.com/libstdc++/install.html</A>.
|
|
</P>
|
|
|
|
<P>To the <A HREF="index.html">libstdc++-v3 homepage</A>.
|
|
|
|
|
|
<!-- ####################################################### -->
|
|
<HR>
|
|
<H2>Contents</H2>
|
|
<UL>
|
|
<LI><A HREF="#prereqs">Tools you will need beforehand</A>
|
|
<LI><A HREF="#srcsetup">Setting up the source directories</A>
|
|
<LI><A HREF="#config">Configuring</A>
|
|
<LI><A HREF="#install">Building and installing the library</A>
|
|
<LI><A HREF="#postinstall">Post-installation</A>
|
|
<LI><A HREF="#usage">Using the library</A>
|
|
</UL>
|
|
|
|
<HR>
|
|
|
|
<!-- ####################################################### -->
|
|
|
|
<H2><A NAME="prereqs">Tools you will need beforehand</A></H2>
|
|
<P>You will need a recent version of g++ to compile the snapshot of
|
|
libstdc++: gcc-2.95.2 works well, or one of the post-2.95.2 GCC
|
|
snapshots (insert standard caveat about using snapshots rather
|
|
than formal releases). You will need the full source
|
|
distribution to whatever compiler release you are using. The
|
|
GCC snapshots can be had from one of the sites on their
|
|
<A HREF="http://gcc.gnu.org/mirrors.html">mirror list</A>.
|
|
</P>
|
|
|
|
<P>In addition, if you plan to modify the makefiles or regenerate
|
|
the configure scripts you'll need the nuevo automake, libtool
|
|
and autoconf to regenerate the Makefiles and configure
|
|
scripts. These tools are all required to be installed in the
|
|
same location (most linux distributions install these tools by
|
|
default, so no worries.)
|
|
</P>
|
|
|
|
<P>If you don't have bash, and want to run <TT>'make check'</TT> to
|
|
test your build, you'll need to get bash 2.x. Also recommended
|
|
is GNU Make, since it is the only 'make' that will parse these
|
|
makefiles correctly.
|
|
</P>
|
|
|
|
<P>As of June 19, 2000, libstdc++ attempts to use tricky and
|
|
space-saving features of the GNU toolchain, enabled with
|
|
<TT>-ffunction-sections -fdata-sections -Wl,--gc-sections</TT>.
|
|
To obtain maximum benefit from this, binutils after this date
|
|
should also be used (bugs were fixed with C++ exception handling
|
|
related to this change in libstdc++-v3). The version of these
|
|
tools should be <TT>2.10.90</TT>, and you can get snapshots (as
|
|
well as releases) of binutils
|
|
<A HREF="ftp://sources.redhat.com/pub/binutils">here</A>.
|
|
</P>
|
|
|
|
<P>Finally, a few system-specific requirements:
|
|
<DL>
|
|
<DT>Cygwin
|
|
<DD>If you are using Cygwin to compile libstdc++-v3 on Win32, you'll
|
|
have to get a version of the cygwin1.dll that is dated on or
|
|
after February 1, 2000. This is necessary to successfully run
|
|
the script "mknumeric_limits" which probes the
|
|
floating-point
|
|
environment of the host in question -- before this date, Cygwin
|
|
would freeze when running this script. In addition, you may
|
|
want to get a current version of libtool (say libtool-1.3.4
|
|
and above) as earlier versions supposedly had problems creating
|
|
shared libraries.
|
|
|
|
<DT>Solaris
|
|
<DD>We recommend installing the <TT>SUNWxcu4</TT> package from the
|
|
Solaris CD before configuring the library. You can check for
|
|
this package as a non-privileged user with the command
|
|
"pkginfo SUNWxcu4".
|
|
</DL>
|
|
</P>
|
|
|
|
<HR>
|
|
|
|
<H2><A NAME="srcsetup">Setting up the source directories</A></H2>
|
|
<P><EM>As the libstdc++-v3 sources and the core GCC sources have
|
|
converged, more and more effort goes to building the
|
|
library as the default version to be shipped with g++. With the
|
|
2.90.8 snapshot, and especially for CVS versions after this
|
|
release, this is treated as the usual scenario. If you want to
|
|
build the library all by itself, you will need to explicitly
|
|
disable certain features (like namespaces) since the core GCC
|
|
library, libgcc.a, will not be rebuilt with those same features.
|
|
</EM>
|
|
</P>
|
|
|
|
<P>By default, all configurations of libstdc++-v3 now have namespaces
|
|
enabled. Being able to select/de-select this option was a complex task
|
|
that had hopelessly confused many otherwise intelligent people, and
|
|
provided an endless stream of silent cursing and cries for help.
|
|
Because of this, gcc sources are required, and are no longer optional.
|
|
</P>
|
|
|
|
<P>The following definitions will be used throughout the rest of this
|
|
document:
|
|
<UL>
|
|
<LI><EM>gccsrcdir</EM>: The directory holding the source of the
|
|
compiler. It should have several subdirectories like
|
|
<EM>gccsrcdir</EM>/libio and <EM>gccsrcdir</EM>/gcc.
|
|
<LI><EM>libsrcdir</EM>: The directory holding the source of the
|
|
C++ library.
|
|
<LI><EM>gccbuilddir</EM>: The build directory for the compiler
|
|
in <EM>gccsrcdir</EM>. GCC requires that it be built in
|
|
a different directory than its sources.
|
|
<LI><EM>libbuilddir</EM>: The build directory for libstdc++.
|
|
<LI><EM>destdir</EM>: The eventual installation directory for
|
|
the compiler/libraries, set with the --prefix option to
|
|
the configure script.
|
|
</UL>
|
|
Note:
|
|
<OL>
|
|
<LI>The .8 snapshot and following are intended to replace the
|
|
library that comes with the compiler, so <EM>libsrcdir</EM>
|
|
and <EM>libbuilddir</EM> must be contained under
|
|
<EM>gccsrcdir</EM> and <EM>gccbuilddir</EM>, respectively.
|
|
<LI>The source, build, and installation directories should
|
|
not be parents of one another; i.e., these should all be
|
|
separate directories. Please don't build out of the
|
|
source directory.
|
|
</OL>
|
|
</P>
|
|
|
|
<P>Since the release of libstdc++-2.90.8, configuration patches have gone
|
|
into CVS gcc that make the management of the various libstdc++ source
|
|
trees a bit easier. Because of this, both libstdc++-v2 and
|
|
libstdc++-v3 and live together more or less in peace, without the need
|
|
for soft linking. If a CVS gcc source directory after April 5, 2000 is
|
|
being used, then the directions are slightly different: please pick
|
|
which of the following two scenarios best represents your particular
|
|
situation.
|
|
</P>
|
|
|
|
<P><B>...with gcc-2.95.2</B>
|
|
<P>Unpack the <EM>gccsrcdir</EM> and go into that directory. For
|
|
instance, <TT>gcc-2.95.2</TT> is a valid <EM>gccsrcdir</EM>.
|
|
Once in <EM>gccsrcdir</EM>, you'll need to rename the directories
|
|
called <TT> libstdc++ </TT> and <TT> libio </TT> like so:
|
|
<PRE>
|
|
mv libstdc++ libstdc++-v2
|
|
mv libio libio-v2</PRE>
|
|
</P>
|
|
<P>Next, unpack the libstdc++-v3 library tarball into the
|
|
<EM>gccsrcdir</EM> directory; it will create a
|
|
<EM>libsrcdir</EM> called <TT>libstdc++-<EM>version</EM></TT>:
|
|
<PRE>
|
|
gzip -dc libstdc++-version.tar.gz | tar xf -</PRE>
|
|
</P>
|
|
<P>Finally, make a soft link between <EM>libsrcdir</EM> and
|
|
<TT>libstdc++</TT> so that libstdc++-v3 will be the default C++
|
|
library used.
|
|
<PRE>
|
|
ln -s <EM>libsrcdir</EM> libstdc++</PRE>
|
|
This complexity of having two completely separate libstdc++
|
|
libraries is necessary so that you can unlink <EM>libsrcdir</EM>
|
|
and update the compiler sources. If you're not this adventurous, or
|
|
would not like to switch between different C++ standard libraries,
|
|
this extra effort is probably wasted; just remove the v2 sources.
|
|
</P>
|
|
</P>
|
|
|
|
<P><B>...with CVS gcc</B>
|
|
<P>Check out or download the gcc sources: the resulting source
|
|
directory is <EM>gccsrcdir</EM>.
|
|
</P>
|
|
<P>Next, unpack the libstdc++-v3 library tarball into this
|
|
<EM>gccsrcdir</EM> directory; it will create a
|
|
<EM>libsrcdir</EM> called <TT>libstdc++-<EM>version</EM></TT>:
|
|
<PRE>
|
|
gzip -dc libstdc++-version.tar.gz | tar xf -</PRE>
|
|
</P>
|
|
|
|
<P>If CVS libstdc++-v3 is being used instead of a snapshot's tarball,
|
|
then move the source directory from the CVS checkout into the
|
|
<EM>gccsrcdir</EM> directory.
|
|
|
|
<P>Finally, rename <EM>libsrcdir</EM> to <TT>libstdc++-v3</TT> so that
|
|
gcc's configure flags will be able to deal with the new library.
|
|
<PRE>
|
|
mv <EM>libsrcdir</EM> libstdc++-v3</PRE>
|
|
</P>
|
|
</P>
|
|
|
|
|
|
<HR>
|
|
<H2><A NAME="config">Configuring</A></H2>
|
|
<P>Due to namespaces, when building libstdc++-v3 you'll have to configure
|
|
the entire <EM>gccsrcdir</EM> directory. The full list of libstdc++-v3
|
|
specific configuration options, not dependent on the specific compiler
|
|
release being used, can be found <A HREF="configopts.html">here</A>.
|
|
</P>
|
|
<P>Consider possibly using --enable-languages=c++ to save time by only
|
|
building the C++ language parts.
|
|
</P>
|
|
|
|
<P><B>...with gcc-2.95.2</B>
|
|
<PRE>
|
|
<EM>gccsrcdir</EM>/configure --prefix=<EM>destdir</EM></PRE>
|
|
</P>
|
|
|
|
<P><B>...with CVS gcc</B>
|
|
<PRE>
|
|
<EM>gccsrcdir</EM>/configure --prefix=<EM>destdir</EM> --enable-libstdcxx-v3</PRE>
|
|
</P>
|
|
|
|
<P>Adding <TT>--enable-libstdcxx-v3</TT> automatically selects libstdc++-v3
|
|
as the C++ library to be used alongside the C++ compiler being built,
|
|
and also enables -fhonor-std by default. This option is not available
|
|
with gcc-2.95.2.
|
|
</P>
|
|
|
|
|
|
<HR>
|
|
<H2><A NAME="install">Building and installing the library</A></H2>
|
|
<P>Now you have a few options:</P>
|
|
<H3>[re]building <EM>everything</EM></H3>
|
|
<P>If you're building GCC from scratch, you can do the usual
|
|
<TT> 'make bootstrap' </TT> here, and libstdc++-v3 will be built
|
|
as its default C++ library. The generated g++ will magically
|
|
use the correct headers, link against the correct library
|
|
binary, and in general using libstdc++-v3 will be a piece of
|
|
cake. You're done; run <TT>'make install'</TT> (the GCC
|
|
Installation instructions) to put the new compiler and libraries
|
|
into place.
|
|
</P>
|
|
|
|
<H3>[re]building only libstdc++</H3>
|
|
<P>Due to differences in the configure process, the resulting Makefiles
|
|
in the<EM>gccbuilddir</EM> will have different rules depending on
|
|
the source base being used.
|
|
</P>
|
|
|
|
<P><B>...with gcc-2.95.2</B>
|
|
<BLOCKQUOTE>
|
|
<EM>libstdc++-rule</EM> is <TT>libstdc++</TT>
|
|
</BLOCKQUOTE>
|
|
</P>
|
|
|
|
<P><B>...with CVS gcc</B>
|
|
<BLOCKQUOTE>
|
|
<EM>libstdc++-rule</EM> is <TT>libstdc++-v3</TT>
|
|
</BLOCKQUOTE>
|
|
</P>
|
|
|
|
<P>To rebuild just libstdc++, use:
|
|
<PRE>
|
|
make all-target-<EM>libstdc++-rule</EM></PRE>
|
|
This will configure and build the C++ library in the
|
|
<EM>gccbuilddir/cpu-vendor-OS/</EM>libstdc++ directory.
|
|
As en example, for CVS gcc this would be
|
|
<TT>make all-target-libstdc++-v3</TT>, and for gcc-2.95.2 it would be
|
|
<TT>make all-target-libstdc++</TT>
|
|
</P>
|
|
<P>If the build fails with a "warning: can't inline call"
|
|
message when compiling stringMAIN.cc, see <A HREF="#Werror">the
|
|
resolution at the end of this document</A>.
|
|
</P>
|
|
<P>If you are rebuilding from a previous build [attempt], some
|
|
information is kept in a cache file. This is stored in
|
|
<EM>gccbuilddir/cpu-vendor-OS/</EM> if you are building with
|
|
multilibs (the default), or in
|
|
<EM>gccbuilddir/cpu-vendor-OS/</EM>libstdc++-v3 if you have
|
|
multilibs disabled. The filename is config.cache; if previous
|
|
information is causing problems, you can delete it entirely, or
|
|
simply edit it and remove lines.
|
|
</P>
|
|
<P>You're done. Now install the rebuilt pieces with
|
|
<PRE>
|
|
make install</PRE>
|
|
or
|
|
<PRE>
|
|
make install-gcc
|
|
make install-target-<EM>libstdc++-rule</EM></PRE>
|
|
</P>
|
|
|
|
|
|
<HR>
|
|
<H2><A NAME="postinstall">Post-installation</A></H2>
|
|
<P>Installation will create the <EM>destdir</EM> directory and
|
|
populate it with subdirectories:
|
|
<PRE>
|
|
lib/
|
|
include/g++-v3/
|
|
bits/
|
|
backward/
|
|
ext/</PRE>
|
|
</P>
|
|
<P>You can check the status of the build without installing it using
|
|
<PRE>
|
|
make check</PRE>
|
|
or you can check the status of the installed library using
|
|
<PRE>
|
|
make check-target-<EM>libstdc++-rule</EM></PRE>
|
|
These commands will create a 'testsuite' directory underneath
|
|
<EM>libbuilddir</EM> containing the results of the tests. We are
|
|
interested in any strange failures of the testsuite; please see
|
|
<A HREF="faq/index.html#2_4">FAQ 2.4</A> for which files to examine.
|
|
</P>
|
|
|
|
|
|
<HR>
|
|
<H2><A NAME="usage">Using the library</A></H2>
|
|
<LI><B>Find the new library at runtime (shared linking only)</B>
|
|
<P>If you only built a static library (libstdc++.a), or if you
|
|
specified static linking, you don't have to worry about this.
|
|
But if you built a shared library (libstdc++.so) and linked
|
|
against it, then you will need to find that library when you
|
|
run the executable.
|
|
</P>
|
|
<P>Methods vary for different platforms and different styles, but
|
|
the usual ones are printed to the screen during installation.
|
|
They include:
|
|
<UL>
|
|
<LI>At runtime set LD_LIBRARY_PATH in your environment correctly,
|
|
so that the shared library for libstdc++ can be found and
|
|
loaded. Be certain that you understand all of the other
|
|
implications and behavior of LD_LIBRARY_PATH first (few
|
|
people do, and they get into trouble).
|
|
<LI>Compile the path to find the library at runtime into the
|
|
program. This can be done by passing certain options to g++,
|
|
which will in turn pass them on to the linker. The exact
|
|
format of the options is dependent on which linker you use:
|
|
<UL>
|
|
<LI>GNU ld (default on Linux):<TT> -Wl,--rpath -Wl,<EM>destdir</EM>/lib</TT>
|
|
<LI>IRIX ld:<TT> -Wl,-rpath -Wl,<EM>destdir</EM>/lib</TT>
|
|
<LI>Solaris ld:<TT> -Wl,-R<EM>destdir</EM>/lib</TT>
|
|
<LI>More...?
|
|
</UL>
|
|
</UL>
|
|
</P>
|
|
<P>Use the <TT>ldd(1)</TT> utility to show which library the system
|
|
thinks it will get at runtime.
|
|
</P>
|
|
</OL>
|
|
</P>
|
|
|
|
|
|
<HR>
|
|
<H3><A NAME="Werror"><TT>warning: can't inline call to</TT>...</A></H3>
|
|
<P>When building the .8 snapshot with g++ 2.95.2, compilation may halt
|
|
with this warning message. The "problem" is the -Werror
|
|
flag being passed to the compiler, which says to treat warnings as
|
|
errors. (This plus a high warning level makes us track down bugs
|
|
<EM>quickly</EM>.) The compiler can't inline a certain call, prints
|
|
a warning, and dies.
|
|
</P>
|
|
<P>The workaround is to edit either <EM>libsrcdir</EM>/src/Makefile.in
|
|
(before configuring) or <EM>bld-libstdc++</EM>/src/Makefile
|
|
(after configuring). There's one line that reads
|
|
<PRE>
|
|
WERROR = -Werror</PRE>
|
|
Delete the flag itself, so that the line reads
|
|
<PRE>
|
|
WERROR =</PRE>
|
|
Then the compiler will still print a warning, but it won't die.
|
|
</P>
|
|
<P>For the curious, this "problem" is actually a symptom
|
|
of something else. The compiler in CVS could inline more than what
|
|
2.95.2 does, and the libstdc++ changes were made with that
|
|
compiler. One of the libstdc++ maintainers explains this
|
|
<A HREF="http://sources.redhat.com/ml/libstdc++/2000-q1/msg00420.html">here</A>.
|
|
</P>
|
|
<P>This has been patched in current CVS sources.
|
|
</P>
|
|
|
|
|
|
<!--
|
|
<HR>
|
|
<H2><A NAME=""></A></H2>
|
|
<P>
|
|
</P>
|
|
|
|
-->
|
|
|
|
<!-- ####################################################### -->
|
|
|
|
<HR>
|
|
<P CLASS="fineprint"><EM>
|
|
Comments and suggestions are welcome, and may be sent to
|
|
<A HREF="mailto:pme@sources.redhat.com">Phil Edwards</A> or
|
|
<A HREF="mailto:gdr@gcc.gnu.org">Gabriel Dos Reis</A>.
|
|
<BR> $Id: install.html,v 1.9 2000/10/21 00:51:49 jsm28 Exp $
|
|
</EM></P>
|
|
|
|
|
|
</BODY>
|
|
</HTML>
|
|
|