1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
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.5 2001/04/03 00:26:54 pme Exp $ -->
14 <H1 CLASS="centered"><A NAME="top">libstdc++-v3 INSTALL</A></H1>
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>.
21 <P>To the <A HREF="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</A>.
24 <!-- ####################################################### -->
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>
38 <!-- ####################################################### -->
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++, such as one of the GCC 3.x snapshots (insert standard
43 caveat about using snapshots rather than formal releases). You
44 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>.
50 <P>In addition, if you plan to modify the makefiles or regenerate the
51 configure scripts you'll need recent versions of the GNU Autotools:
52 autoconf (version 2.50 or later),
53 automake (version 1.4 or later), <!-- special version? -->
54 and libtool (multilanguage, version 1.4 or later), <!-- really? -->
55 in order to rebuild the files.
56 These tools are all required to be installed in the same location
57 (most linux distributions install these tools by default, so no
58 worries as long as the versions are correct).
61 <P>GNU Make is the only 'make' that will parse the makefiles correctly.
64 <P>To test your build, you will need either DejaGNU 1.4 (to run
65 <TT>'make check'</TT> like
66 <A HREF="http://gcc.gnu.org/install/test.html">the rest of GCC</A>),
67 or Bash 2.x (to run <TT>'make check-script'</TT>).
70 <P>As of June 19, 2000, libstdc++ attempts to use tricky and
71 space-saving features of the GNU toolchain, enabled with
72 <TT>-ffunction-sections -fdata-sections -Wl,--gc-sections</TT>.
73 To obtain maximum benefit from this, binutils after this date
74 should also be used (bugs were fixed with C++ exception handling
75 related to this change in libstdc++-v3). The version of these
76 tools should be <TT>2.10.90</TT>, and you can get snapshots (as
77 well as releases) of binutils
78 <A HREF="ftp://sources.redhat.com/pub/binutils">here</A>.
81 <!-- Commented until some system-specific requirements appear.
82 <P>Finally, a few system-specific requirements:
85 <DD>If you are using Cygwin to compile libstdc++-v3 on Win32, you'll
94 <H2><A NAME="srcsetup">Setting up the source directories</A></H2>
95 <P>The following definitions will be used throughout the rest of this
98 <LI><EM>gccsrcdir</EM>: The directory holding the source of the
99 compiler. It should have several subdirectories like
100 <EM>gccsrcdir</EM>/libio and <EM>gccsrcdir</EM>/gcc.
101 <LI><EM>libsrcdir</EM>: The directory holding the source of the
103 <LI><EM>gccbuilddir</EM>: The build directory for the compiler
104 in <EM>gccsrcdir</EM>. GCC requires that it be built in
105 a different directory than its sources.
106 <LI><EM>libbuilddir</EM>: The build directory for libstdc++.
107 <LI><EM>destdir</EM>: The eventual installation directory for
108 the compiler/libraries, set with the --prefix option to
109 the configure script.
113 <LI>The 3.0 version and following are intended to replace the
114 library that comes with the compiler, so <EM>libsrcdir</EM>
115 and <EM>libbuilddir</EM> must be contained under
116 <EM>gccsrcdir</EM> and <EM>gccbuilddir</EM>, respectively.
117 <LI>The source, build, and installation directories should
118 not be parents of one another; i.e., these should all be
119 separate directories. Please don't build out of the
124 <P>Check out or download the gcc sources: the resulting source directory
125 (<TT>gcc</TT> or <TT>gcc-3.0</TT>, for example) is <EM>gccsrcdir</EM>.
126 Once in <EM>gccsrcdir</EM>, you'll need to rename or delete the
127 libstdc++-v3 directory which comes with that snapshot:
129 mv libstdc++-v3 libstdc++-v3-previous <STRONG>[OR]</STRONG>
130 rm -r libstdc++-v3</PRE>
132 <P>Next, unpack the libstdc++-v3 library tarball into this
133 <EM>gccsrcdir</EM> directory; it will create a
134 <EM>libsrcdir</EM> called <TT>libstdc++-<EM>version</EM></TT>:
136 gzip -dc libstdc++-version.tar.gz | tar xf -</PRE>
138 <P>Finally, rename <EM>libsrcdir</EM> to <TT>libstdc++-v3</TT> so that
139 gcc's configure flags will be able to deal with the new library.
141 mv <EM>libsrcdir</EM> libstdc++-v3</PRE>
146 <H2><A NAME="config">Configuring</A></H2>
147 <P>If you have never done this before, you should read the basic
148 <A HREF="http://gcc.gnu.org/install/">GCC Installation
149 Instructions</A> first.
151 <P>When building libstdc++-v3 you'll have to configure
152 the entire <EM>gccsrcdir</EM> directory. The full list of libstdc++-v3
153 specific configuration options, not dependent on the specific compiler
154 release being used, can be found <A HREF="configopts.html">here</A>.
156 <P>Consider possibly using --enable-languages=c++ to save time by only
157 building the C++ language parts.
161 cd <EM>gccbuilddir</EM>
162 <EM>gccsrcdir</EM>/configure --prefix=<EM>destdir</EM> --other-opts...</PRE>
167 <H2><A NAME="install">Building and installing the library</A></H2>
168 <P>Now you have a few options:</P>
169 <H3>[re]building <EM>everything</EM></H3>
170 <P>If you're building GCC from scratch, you can do the usual
171 <TT> 'make bootstrap' </TT> here, and libstdc++-v3 will be built
172 as its default C++ library. The generated g++ will magically
173 use the correct headers, link against the correct library
174 binary, and in general using libstdc++-v3 will be a piece of
175 cake. You're done; run <TT>'make install'</TT> (see the GCC
176 installation instructions) to put the new compiler and libraries
180 <H3>[re]building only libstdc++</H3>
181 <P>To rebuild just libstdc++, use:
183 make all-target-<EM>libstdc++-v3</EM></PRE>
184 This will configure and build the C++ library in the
185 <EM>gccbuilddir/cpu-vendor-os/</EM>libstdc++ directory.
187 <P>If you are rebuilding from a previous build [attempt], some
188 information is kept in a cache file. This is stored in
189 <EM>gccbuilddir/cpu-vendor-os/</EM> if you are building with
190 multilibs (the default), or in
191 <EM>gccbuilddir/cpu-vendor-os/</EM>libstdc++-v3 if you have
192 multilibs disabled. The filename is config.cache; if previous
193 information is causing problems, you can delete it entirely, or
194 simply edit it and remove lines.
196 <P>You're done. Now install the rebuilt pieces with
202 make install-target-libstdc++-v3</PRE>
207 <H2><A NAME="postinstall">Post-installation</A></H2>
208 <P>Installation will create the <EM>destdir</EM> directory and
209 populate it with subdirectories:
215 <EM>cpu-vendor-os</EM>/bits/
218 <P>You can check the status of the build without installing it using
221 or you can check the status of the installed library using
223 make check-install</PRE>
224 in the <EM>libbuilddir</EM> directory.
225 These commands will create a 'testsuite' directory underneath
226 <EM>libbuilddir</EM> containing the results of the tests. We are
227 interested in any strange failures of the testsuite; please see
228 <A HREF="faq/index.html#2_4">FAQ 2.4</A> for which files to examine.
233 <H2><A NAME="usage">Using the library</A></H2>
234 <LI><B>Find the new library at runtime (shared linking only)</B>
235 <P>If you only built a static library (libstdc++.a), or if you
236 specified static linking, you don't have to worry about this.
237 But if you built a shared library (libstdc++.so) and linked
238 against it, then you will need to find that library when you
241 <P>Methods vary for different platforms and different styles, but
242 the usual ones are printed to the screen during installation.
245 <LI>At runtime set LD_LIBRARY_PATH in your environment correctly,
246 so that the shared library for libstdc++ can be found and
247 loaded. Be certain that you understand all of the other
248 implications and behavior of LD_LIBRARY_PATH first (few
249 people do, and they get into trouble).
250 <LI>Compile the path to find the library at runtime into the
251 program. This can be done by passing certain options to g++,
252 which will in turn pass them on to the linker. The exact
253 format of the options is dependent on which linker you use:
255 <LI>GNU ld (default on Linux):<TT> -Wl,--rpath,<EM>destdir</EM>/lib</TT>
256 <LI>IRIX ld:<TT> -Wl,-rpath,<EM>destdir</EM>/lib</TT>
257 <LI>Solaris ld:<TT> -Wl,-R<EM>destdir</EM>/lib</TT>
262 <P>Use the <TT>ldd(1)</TT> utility to show which library the system
263 thinks it will get at runtime.
265 <P>A libstdc++.la file is also installed, for use with Libtool. If
266 you use Libtool to create your executables, these details are
267 taken care of for you.
275 <H2><A NAME=""></A></H2>
281 <!-- ####################################################### -->
284 <P CLASS="fineprint"><EM>
285 Comments and suggestions are welcome, and may be sent to
286 <A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>.
287 <BR> $Id: install.html,v 1.5 2001/04/03 00:26:54 pme Exp $