1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta name="AUTHOR" content="pme@gcc.gnu.org (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="StyleSheet" href="lib3styles.css" />
</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://gcc.gnu.org/onlinedocs/libstdc++/install.html">
http://gcc.gnu.org/onlinedocs/libstdc++/install.html</a>.
</p>
<p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
</p>
<!-- ####################################################### -->
<hr />
<h2>Contents</h2>
<ul>
<li><a href="#prereqs">Tools you will need beforehand</a></li>
<li><a href="#srcsetup">Setting up the source directories</a></li>
<li><a href="#config">Configuring</a></li>
<li><a href="#install">Building and installing the library</a></li>
<li><a href="#postinstall">Post-installation</a></li>
<li><a href="#usage">Using the library</a></li>
</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++, such as one of the GCC 3.x 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>. If you are
using a 2.x compiler, see
<a href="http://gcc.gnu.org/libstdc++/status.html">the status page</a>
first.
</p>
<p>In addition, if you plan to modify the makefiles or regenerate the
configure scripts you'll need recent versions of the GNU Autotools:
autoconf (version 2.50 or later),
automake (version 1.4 or later), <!-- special version? -->
and libtool (multilanguage, version 1.4 or later), <!-- really? -->
in order to rebuild the files.
These tools are all required to be installed in the same location
(most linux distributions install these tools by default, so no
worries as long as the versions are correct).
</p>
<p>To test your build, you will need either DejaGNU 1.4 (to run
<code>'make check'</code> like
<a href="http://gcc.gnu.org/install/test.html">the rest of GCC</a>),
or Bash 2.x (to run <code>'make check-script'</code>).
</p>
<p>As of June 19, 2000, libstdc++ attempts to use tricky and
space-saving features of the GNU toolchain, enabled with
<code>-ffunction-sections -fdata-sections
-Wl,--gc-sections</code>. 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
<code>2.10.90</code>, or later, and you can get snapshots (as
well as releases) of binutils
<a href="ftp://sources.redhat.com/pub/binutils">here</a>. The
configure process will automatically detect and use these
features if the underlying support is present.
</p>
<p>If you are using a 3.1-series libstdc++ snapshot, then the
requirements are slightly more stringent: the compiler sources
must also be 3.1 or later (for both technical and licensing
reasons), and your binutils must be 2.11.95 or later if you want
to use symbol versioning in shared libraries. Again, the
configure process will automatically detect and use these
features if the underlying support is present.
</p>
<p>Finally, a few system-specific requirements: </p>
<dl>
<dt> linux </dt>
<dd>If gcc 3.1.0 or later on is being used on linux, an attempt
will be made to use "C" library functionality necessary for C++
named locale support.
<p>
The configure option --enable-clocale can be used force a
particular behavior.
</p>
<p>
If the 'gnu' locale model is being used, the following locales
are used and tested in the libstdc++ testsuites: en_HK, en_US,
fr_FR, fr_FR@euro, de_DE, de_DE@euro, ja_JP.eucjp, es_MX, en_PH,
and it_IT. Failure to have the underlying "C" library locale
information installed will mean that C++ named locales for the
above regions will not work: because of this, the libstdc++
testsuite will not pass the named locale tests. If this isn't an
issue, don't worry about it. If named locales are needed, the
underlying locale information must be installed. Note that
rebuilding libstdc++ after the "C" locales are installed is not
necessary.
</p>
<p> To install
support for locales, do only one of the following: </p>
<ul>
<li> install all locales
<p> <code> export LC_ALL=C </code> </p>
<p> <code> rpm -e glibc-common --nodeps </code> </p>
<p> <code> rpm -i --define "_install_langs all"
glibc-common-2.2.5-34.i386.rpm </code> </p>
</li>
<li> install just the necessary locales
<p> <code> localedef -i de_DE -f ISO-8859-1 de_DE </code> </p>
</li>
</ul>
</dd>
</dl>
<hr />
<h2><a name="srcsetup">Setting up the source directories</a></h2>
<p>The following definitions will be used throughout the rest of this
document:
</p>
<ul>
<li><em>gccsrcdir</em>: The directory holding the source of the
compiler. It should have several subdirectories like
<em>gccsrcdir</em>/libiberty and <em>gccsrcdir</em>/gcc.
</li>
<li><em>libsrcdir</em>: The directory holding the source of the
C++ library.
</li>
<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>
<li><em>libbuilddir</em>: The build directory for libstdc++.
</li>
<li><em>destdir</em>: The eventual installation directory for
the compiler/libraries, set with the --prefix option to
the configure script.
</li>
</ul>
<p> Note: </p>
<ol>
<li>The 3.0 version 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>
<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.
</li>
</ol>
<p>Check out or download the GCC sources: the resulting source directory
(<code>gcc</code> or <code>gcc-3.0.3</code>, for example) is
<em>gccsrcdir</em>.
Once in <em>gccsrcdir</em>, you'll need to rename or delete the
libstdc++-v3 directory which comes with that snapshot:
</p>
<pre>
mv libstdc++-v3 libstdc++-v3-previous <strong>[OR]</strong>
rm -r libstdc++-v3</pre>
<p>Next, unpack the libstdc++-v3 library tarball into this
<em>gccsrcdir</em> directory; it will create a
<em>libsrcdir</em> called <code>libstdc++-<em>version</em></code>:
</p>
<pre>
gzip -dc libstdc++-version.tar.gz | tar xf -</pre>
<p>Finally, rename <em>libsrcdir</em> to <code>libstdc++-v3</code> so that
gcc's configure flags will be able to deal with the new library.
</p>
<pre>
mv <em>libsrcdir</em> libstdc++-v3</pre>
<hr />
<h2><a name="config">Configuring</a></h2>
<p>If you have never done this before, you should read the basic
<a href="http://gcc.gnu.org/install/">GCC Installation
Instructions</a> first. Read <em>all of them</em>.
<strong>Twice.</strong>
</p>
<p>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>
<pre>
cd <em>gccbuilddir</em>
<em>gccsrcdir</em>/configure --prefix=<em>destdir</em> --other-opts...</pre>
<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
<code> 'make bootstrap' </code> 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 <code>'make install'</code> (see the GCC
installation instructions) to put the new compiler and libraries
into place.
</p>
<h3>[re]building only libstdc++</h3>
<p>To rebuild just libstdc++, use: </p>
<pre>
make all-target-libstdc++-v3</pre>
<p>
This will configure and build the C++ library in the
<em>gccbuilddir/cpu-vendor-os/</em>libstdc++ directory.
</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</p>
<pre>
make install</pre>
<p>or</p>
<pre>
make install-gcc
make install-target-libstdc++-v3</pre>
<hr />
<h2><a name="postinstall">Post-installation</a></h2>
<p>Installation will create the <em>destdir</em> directory and
populate it with subdirectories:
</p>
<pre>
lib/
include/c++/<em>gcc-version</em>
backward/
bits/
<em>cpu-vendor-os</em>/bits/
ext/</pre>
<p>If you used the version-specific-libs configure option, then most of
the headers and library files will be moved under
<code>lib/gcc-lib/</code> instead.
</p>
<p>You can check the status of the build without installing it using</p>
<pre>
make check</pre>
<p>or you can check the status of the installed library using</p>
<pre>
make check-install</pre>
<p>in the <em>libbuilddir</em> directory.
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>
<p> In addition, there are some testing options that are mostly of
interest to library maintainers and system integrators. As such,
these tests may not work on all cpu and host combinations. These
options include, but are not necessarily limited to, the following:
</p>
<p>The library ABI can be tested using</p>
<pre>
make check-abi</pre>
<p>The library can also be tested using a bash script, instead of
the default dejagnu test harness</p>
<pre>
make check-script</pre>
<p>or</p>
<pre>
make check-script-install</pre>
<hr />
<h2><a name="usage">Using the library</a></h2>
<h3>Find the new library at runtime (shared linking only)</h3>
<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:
</p>
<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>
<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):<code> -Wl,--rpath,<em>destdir</em>/lib</code></li>
<li>IRIX ld:<code> -Wl,-rpath,<em>destdir</em>/lib</code></li>
<li>Solaris ld:<code> -Wl,-R<em>destdir</em>/lib</code></li>
<li>More...? Let us know!</li>
</ul>
</li>
</ul>
<p>Use the <code>ldd(1)</code> utility to show which library the system
thinks it will get at runtime.
</p>
<p>A libstdc++.la file is also installed, for use with Libtool. If
you use Libtool to create your executables, these details are
taken care of for you.
</p>
<!--
<hr />
<h2><a name=""></a></h2>
<p>
</p>
-->
<!-- ####################################################### -->
<hr />
<p class="fineprint"><em>
See <a href="17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to
<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
</em></p>
</body>
</html>
|
