1 <?xml version="1.0" encoding="ISO-8859-1"?>
3 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
8 <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
9 <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++" />
10 <meta name="DESCRIPTION" content="README for the GNU libstdc++ effort." />
11 <meta name="GENERATOR" content="vi and eight fingers" />
12 <title>libstdc++-v3 Installation Instructions</title>
13 <link rel="StyleSheet" href="lib3styles.css" />
17 <h1 class="centered"><a name="top">libstdc++-v3 INSTALL</a></h1>
19 <p>The latest version of this document is always available at
20 <a href="http://gcc.gnu.org/onlinedocs/libstdc++/install.html">
21 http://gcc.gnu.org/onlinedocs/libstdc++/install.html</a>.
24 <p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
28 <!-- ####################################################### -->
32 <li><a href="#prereqs">Tools you will need beforehand</a></li>
33 <li><a href="#srcsetup">Setting up the source directories</a></li>
34 <li><a href="#config">Configuring</a></li>
35 <li><a href="#install">Building and installing the library</a></li>
36 <li><a href="#postinstall">Post-installation</a></li>
37 <li><a href="#usage">Using the library</a></li>
42 <!-- ####################################################### -->
44 <h2><a name="prereqs">Tools you will need beforehand</a></h2>
45 <p>You will need a recent version of g++ to compile the snapshot of
46 libstdc++, such as one of the GCC 3.x snapshots (insert standard
47 caveat about using snapshots rather than formal releases). You will
48 need the full source distribution to whatever compiler release you are
49 using. The GCC snapshots can be had from one of the sites on their
50 <a href="http://gcc.gnu.org/mirrors.html">mirror list</a>. If you are
51 using a 2.x compiler, see
52 <a href="http://gcc.gnu.org/libstdc++/status.html">the status page</a>
56 <p>In addition, if you plan to modify the makefiles or regenerate the
57 configure scripts you'll need recent versions of the GNU Autotools:
58 autoconf (version 2.50 or later),
59 automake (version 1.4 or later), <!-- special version? -->
60 and libtool (multilanguage, version 1.4 or later), <!-- really? -->
61 in order to rebuild the files.
62 These tools are all required to be installed in the same location
63 (most linux distributions install these tools by default, so no
64 worries as long as the versions are correct).
67 <p>To test your build, you will need either DejaGNU 1.4 (to run
68 <code>'make check'</code> like
69 <a href="http://gcc.gnu.org/install/test.html">the rest of GCC</a>),
70 or Bash 2.x (to run <code>'make check-script'</code>).
73 <p>As of June 19, 2000, libstdc++ attempts to use tricky and
74 space-saving features of the GNU toolchain, enabled with
75 <code>-ffunction-sections -fdata-sections
76 -Wl,--gc-sections</code>. To obtain maximum benefit from this,
77 binutils after this date should also be used (bugs were fixed
78 with C++ exception handling related to this change in
79 libstdc++-v3). The version of these tools should be
80 <code>2.10.90</code>, or later, and you can get snapshots (as
81 well as releases) of binutils
82 <a href="ftp://sources.redhat.com/pub/binutils">here</a>. The
83 configure process will automatically detect and use these
84 features if the underlying support is present.
87 <p>If you are using a 3.1-series libstdc++ snapshot, then the
88 requirements are slightly more stringent: the compiler sources
89 must also be 3.1 or later (for both technical and licensing
90 reasons), and your binutils must be 2.11.95 or later if you want
91 to use symbol versioning in shared libraries. Again, the
92 configure process will automatically detect and use these
93 features if the underlying support is present.
96 <p>Finally, a few system-specific requirements: </p>
100 <dd>If gcc 3.1.0 or later on is being used on linux, an attempt
101 will be made to use "C" library functionality necessary for C++
102 named locale support. For gcc 3.2.1 and later, this means that
103 glibc 2.2.5 or later is required.
106 The configure option --enable-clocale can be used force a
111 If the 'gnu' locale model is being used, the following locales
112 are used and tested in the libstdc++ testsuites: en_HK, en_US,
113 fr_FR, fr_FR@euro, de_DE, de_DE@euro, ja_JP.eucjp, es_MX, en_PH,
114 and it_IT. Failure to have the underlying "C" library locale
115 information installed will mean that C++ named locales for the
116 above regions will not work: because of this, the libstdc++
117 testsuite will not pass the named locale tests. If this isn't an
118 issue, don't worry about it. If named locales are needed, the
119 underlying locale information must be installed. Note that
120 rebuilding libstdc++ after the "C" locales are installed is not
125 support for locales, do only one of the following: </p>
127 <li> install all locales
128 <p> <code> export LC_ALL=C </code> </p>
129 <p> <code> rpm -e glibc-common --nodeps </code> </p>
130 <p> <code> rpm -i --define "_install_langs all"
131 glibc-common-2.2.5-34.i386.rpm </code> </p>
133 <li> install just the necessary locales
134 <p> <code> localedef -i de_DE -f ISO-8859-1 de_DE </code> </p>
142 <h2><a name="srcsetup">Setting up the source directories</a></h2>
143 <p>The following definitions will be used throughout the rest of this
147 <li><em>gccsrcdir</em>: The directory holding the source of the
148 compiler. It should have several subdirectories like
149 <em>gccsrcdir</em>/libiberty and <em>gccsrcdir</em>/gcc.
151 <li><em>libsrcdir</em>: The directory holding the source of the
154 <li><em>gccbuilddir</em>: The build directory for the compiler
155 in <em>gccsrcdir</em>. GCC requires that it be built in
156 a different directory than its sources.
158 <li><em>libbuilddir</em>: The build directory for libstdc++.
160 <li><em>destdir</em>: The eventual installation directory for
161 the compiler/libraries, set with the --prefix option to
162 the configure script.
167 <li>The 3.0 version and following are intended to replace the
168 library that comes with the compiler, so <em>libsrcdir</em>
169 and <em>libbuilddir</em> must be contained under
170 <em>gccsrcdir</em> and <em>gccbuilddir</em>, respectively.
172 <li>The source, build, and installation directories should
173 not be parents of one another; i.e., these should all be
174 separate directories. Please don't build out of the
179 <p>Check out or download the GCC sources: the resulting source directory
180 (<code>gcc</code> or <code>gcc-3.0.3</code>, for example) is
182 Once in <em>gccsrcdir</em>, you'll need to rename or delete the
183 libstdc++-v3 directory which comes with that snapshot:
186 mv libstdc++-v3 libstdc++-v3-previous <strong>[OR]</strong>
187 rm -r libstdc++-v3</pre>
188 <p>Next, unpack the libstdc++-v3 library tarball into this
189 <em>gccsrcdir</em> directory; it will create a
190 <em>libsrcdir</em> called <code>libstdc++-<em>version</em></code>:
193 gzip -dc libstdc++-version.tar.gz | tar xf -</pre>
194 <p>Finally, rename <em>libsrcdir</em> to <code>libstdc++-v3</code> so that
195 gcc's configure flags will be able to deal with the new library.
198 mv <em>libsrcdir</em> libstdc++-v3</pre>
202 <h2><a name="config">Configuring</a></h2>
203 <p>If you have never done this before, you should read the basic
204 <a href="http://gcc.gnu.org/install/">GCC Installation
205 Instructions</a> first. Read <em>all of them</em>.
206 <strong>Twice.</strong>
208 <p>When building libstdc++-v3 you'll have to configure
209 the entire <em>gccsrcdir</em> directory. The full list of libstdc++-v3
210 specific configuration options, not dependent on the specific compiler
211 release being used, can be found <a href="configopts.html">here</a>.
213 <p>Consider possibly using --enable-languages=c++ to save time by only
214 building the C++ language parts.
218 cd <em>gccbuilddir</em>
219 <em>gccsrcdir</em>/configure --prefix=<em>destdir</em> --other-opts...</pre>
223 <h2><a name="install">Building and installing the library</a></h2>
224 <p>Now you have a few options:</p>
225 <h3>[re]building <em>everything</em></h3>
226 <p>If you're building GCC from scratch, you can do the usual
227 <code> 'make bootstrap' </code> here, and libstdc++-v3 will be built
228 as its default C++ library. The generated g++ will magically
229 use the correct headers, link against the correct library
230 binary, and in general using libstdc++-v3 will be a piece of
231 cake. You're done; run <code>'make install'</code> (see the GCC
232 installation instructions) to put the new compiler and libraries
236 <h3>[re]building only libstdc++</h3>
237 <p>To rebuild just libstdc++, use: </p>
239 make all-target-libstdc++-v3</pre>
241 This will configure and build the C++ library in the
242 <em>gccbuilddir/cpu-vendor-os/</em>libstdc++ directory.
244 <p>If you are rebuilding from a previous build [attempt], some
245 information is kept in a cache file. This is stored in
246 <em>gccbuilddir/cpu-vendor-os/</em> if you are building with
247 multilibs (the default), or in
248 <em>gccbuilddir/cpu-vendor-os/</em>libstdc++-v3 if you have
249 multilibs disabled. The filename is config.cache; if previous
250 information is causing problems, you can delete it entirely, or
251 simply edit it and remove lines.
253 <p>You're done. Now install the rebuilt pieces with</p>
259 make install-target-libstdc++-v3</pre>
263 <h2><a name="postinstall">Post-installation</a></h2>
264 <p>Installation will create the <em>destdir</em> directory and
265 populate it with subdirectories:
269 include/c++/<em>gcc-version</em>
272 <em>cpu-vendor-os</em>/bits/
274 <p>If you used the version-specific-libs configure option, then most of
275 the headers and library files will be moved under
276 <code>lib/gcc-lib/</code> instead.
278 <p>You can check the status of the build without installing it using</p>
281 <p>or you can check the status of the installed library using</p>
283 make check-install</pre>
284 <p>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.
291 <p> In addition, there are some testing options that are mostly of
292 interest to library maintainers and system integrators. As such,
293 these tests may not work on all cpu and host combinations. These
294 options include, but are not necessarily limited to, the following:
297 <p>The library ABI can be tested using</p>
301 <p>The library can also be tested using a bash script, instead of
302 the default dejagnu test harness</p>
304 make check-script</pre>
307 make check-script-install</pre>
310 <h2><a name="usage">Using the library</a></h2>
311 <h3>Find the new library at runtime (shared linking only)</h3>
312 <p>If you only built a static library (libstdc++.a), or if you
313 specified static linking, you don't have to worry about this.
314 But if you built a shared library (libstdc++.so) and linked
315 against it, then you will need to find that library when you
318 <p>Methods vary for different platforms and different styles, but
319 the usual ones are printed to the screen during installation.
323 <li>At runtime set LD_LIBRARY_PATH in your environment correctly,
324 so that the shared library for libstdc++ can be found and
325 loaded. Be certain that you understand all of the other
326 implications and behavior of LD_LIBRARY_PATH first (few
327 people do, and they get into trouble).
329 <li>Compile the path to find the library at runtime into the
330 program. This can be done by passing certain options to g++,
331 which will in turn pass them on to the linker. The exact
332 format of the options is dependent on which linker you use:
334 <li>GNU ld (default on Linux):<code> -Wl,--rpath,<em>destdir</em>/lib</code></li>
335 <li>IRIX ld:<code> -Wl,-rpath,<em>destdir</em>/lib</code></li>
336 <li>Solaris ld:<code> -Wl,-R<em>destdir</em>/lib</code></li>
337 <li>More...? Let us know!</li>
341 <p>Use the <code>ldd(1)</code> utility to show which library the system
342 thinks it will get at runtime.
344 <p>A libstdc++.la file is also installed, for use with Libtool. If
345 you use Libtool to create your executables, these details are
346 taken care of for you.
352 <h2><a name=""></a></h2>
358 <!-- ####################################################### -->
361 <p class="fineprint"><em>
362 See <a href="17_intro/license.html">license.html</a> for copying conditions.
363 Comments and suggestions are welcome, and may be sent to
364 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.