source: trunk/src/gcc/libstdc++-v3/docs/html/install.html@ 1392

Last change on this file since 1392 was 1392, checked in by bird, 22 years ago

This commit was generated by cvs2svn to compensate for changes in r1391,
which included commits to RCS files with non-trunk default branches.
  • Property cvs2svn:cvs-rev set to 1.1.1.2
  • Property svn:eol-style set to native
  • Property svn:executable set to *
File size: 14.4 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE html
3 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
6<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
7<head>
8 <meta name="AUTHOR" content="[email protected] (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" />
14</head>
15<body>
16
17<h1 class="centered"><a name="top">Getting started: configure, build, install</a></h1>
18
19<p class="fineprint"><em>
20 The latest version of this document is always available at
21 <a href="http://gcc.gnu.org/onlinedocs/libstdc++/install.html">
22 http://gcc.gnu.org/onlinedocs/libstdc++/install.html</a>.
23</em></p>
24
25<p><em>
26 To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
27</em></p>
28
29
30<!-- ####################################################### -->
31<hr />
32<h2>Contents</h2>
33<ul>
34 <li><a href="#prereqs">Tools you will need beforehand</a></li>
35 <li><a href="#srcsetup">Setting up the source directories</a></li>
36 <li><a href="#config">Configuring</a></li>
37 <li><a href="#install">Building and installing the library</a></li>
38 <li><a href="#postinstall">Post-installation</a></li>
39 <li><a href="#usage">Using the library</a></li>
40</ul>
41
42<hr />
43
44<!-- ####################################################### -->
45
46<h2><a name="prereqs">Tools you will need beforehand</a></h2>
47 <p>You will need a recent version of g++ to compile the snapshot of
48 libstdc++, such as one of the GCC 3.x snapshots (insert standard
49 caveat about using snapshots rather than formal releases). You will
50 need the full source distribution to whatever compiler release you are
51 using. The GCC snapshots can be had from one of the sites on their
52 <a href="http://gcc.gnu.org/mirrors.html">mirror list</a>. If you are
53 using a 2.x compiler, see
54 <a href="http://gcc.gnu.org/libstdc++/status.html">the status page</a>
55 first.
56 </p>
57
58 <p>In addition, if you plan to modify the makefiles or regenerate the
59 configure scripts you'll need recent versions of the GNU Autotools:
60 autoconf (version 2.50 or later),
61 automake (version 1.4 or later), <!-- special version? -->
62 and libtool (multilanguage, version 1.4 or later), <!-- really? -->
63 in order to rebuild the files.
64 These tools are all required to be installed in the same location
65 (most linux distributions install these tools by default, so no
66 worries as long as the versions are correct).
67 </p>
68
69 <p>To test your build, you will need either DejaGNU 1.4 (to run
70 <code>'make check'</code> like
71 <a href="http://gcc.gnu.org/install/test.html">the rest of GCC</a>),
72 or Bash 2.x (to run <code>'make check-script'</code>).
73 </p>
74
75 <p>As of June 19, 2000, libstdc++ attempts to use tricky and
76 space-saving features of the GNU toolchain, enabled with
77 <code>-ffunction-sections -fdata-sections
78 -Wl,--gc-sections</code>. To obtain maximum benefit from this,
79 binutils after this date should also be used (bugs were fixed
80 with C++ exception handling related to this change in
81 libstdc++-v3). The version of these tools should be
82 <code>2.10.90</code>, or later, and you can get snapshots (as
83 well as releases) of binutils
84 <a href="ftp://sources.redhat.com/pub/binutils">here</a>. The
85 configure process will automatically detect and use these
86 features if the underlying support is present.
87 </p>
88
89 <p>If you are using a 3.1-series libstdc++ snapshot, then the
90 requirements are slightly more stringent: the compiler sources
91 must also be 3.1 or later (for both technical and licensing
92 reasons), and your binutils must be 2.11.95 or later if you want
93 to use symbol versioning in shared libraries. Again, the
94 configure process will automatically detect and use these
95 features if the underlying support is present.
96 </p>
97
98 <p>Finally, a few system-specific requirements: </p>
99 <dl>
100 <dt> linux </dt>
101
102 <dd>If gcc 3.1.0 or later on is being used on linux, an attempt
103 will be made to use "C" library functionality necessary for C++
104 named locale support. For gcc 3.2.1 and later, this means that
105 glibc 2.2.5 or later is required.
106
107 <p>
108 The configure option --enable-clocale can be used force a
109 particular behavior.
110 </p>
111
112 <p>
113 If the 'gnu' locale model is being used, the following locales
114 are used and tested in the libstdc++ testsuites. The first column
115 is the name of the locale, the second is the character set it is
116 expected to use.
117 </p>
118<pre>
119de_DE ISO-8859-1
120de_DE@euro ISO-8859-15
121en_HK ISO-8859-1
122en_PH ISO-8859-1
123en_US ISO-8859-1
124en_US.ISO-8859-1 ISO-8859-1
125en_US.ISO-8859-15 ISO-8859-15
126en_US.UTF-8 UTF-8
127es_MX ISO-8859-1
128fr_FR ISO-8859-1
129fr_FR@euro ISO-8859-15
130it_IT ISO-8859-1
131ja_JP.eucjp EUC-JP
132se_NO.UTF-8 UTF-8
133</pre>
134 <p>Failure to have the underlying "C" library locale
135 information installed will mean that C++ named locales for the
136 above regions will not work: because of this, the libstdc++
137 testsuite will not pass the named locale tests. If this isn't an
138 issue, don't worry about it. If named locales are needed, the
139 underlying locale information must be installed. Note that
140 rebuilding libstdc++ after the "C" locales are installed is not
141 necessary.
142 </p>
143
144 <p>To install support for locales, do only one of the following:
145 </p>
146
147 <ul>
148 <li> install all locales
149 <ul>
150 <li>with RedHat Linux:
151 <p> <code> export LC_ALL=C </code> </p>
152 <p> <code> rpm -e glibc-common --nodeps </code> </p>
153 <p> <code> rpm -i --define "_install_langs all"
154 glibc-common-2.2.5-34.i386.rpm </code> </p>
155 </li>
156 <li> (instructions for other operating systems solicited) </li>
157 </ul>
158 </li>
159 <li> install just the necessary locales
160 <ul>
161 <li>with Debian Linux:
162 <p> Add the above list, as shown, to the file
163 <code>/etc/locale.gen</code> </p>
164 <p> run <code>/usr/sbin/locale-gen</code> </p>
165 </li>
166 <li> on most Unix-like operating systems:
167 <p> <code> localedef -i de_DE -f ISO-8859-1 de_DE </code> </p>
168 <p> (repeat for each entry in the above list) </p>
169 </li>
170 <li> (instructions for other operating systems solicited) </li>
171 </ul>
172 </li>
173 </ul>
174 </dd>
175 </dl>
176
177<hr />
178
179<h2><a name="srcsetup">Setting up the source directories</a></h2>
180 <p>The following definitions will be used throughout the rest of this
181 document:
182 </p>
183 <ul>
184 <li><em>gccsrcdir</em>: The directory holding the source of the
185 compiler. It should have several subdirectories like
186 <em>gccsrcdir</em>/libiberty and <em>gccsrcdir</em>/gcc.
187 </li>
188 <li><em>libsrcdir</em>: The directory holding the source of the
189 C++ library.
190 </li>
191 <li><em>gccbuilddir</em>: The build directory for the compiler
192 in <em>gccsrcdir</em>. GCC requires that it be built in
193 a different directory than its sources.
194 </li>
195 <li><em>libbuilddir</em>: The build directory for libstdc++.
196 </li>
197 <li><em>destdir</em>: The eventual installation directory for
198 the compiler/libraries, set with the --prefix option to
199 the configure script.
200 </li>
201 </ul>
202 <p> Note: </p>
203 <ol>
204 <li>The 3.0 version and following are intended to replace the
205 library that comes with the compiler, so <em>libsrcdir</em>
206 and <em>libbuilddir</em> must be contained under
207 <em>gccsrcdir</em> and <em>gccbuilddir</em>, respectively.
208 </li>
209 <li>The source, build, and installation directories should
210 not be parents of one another; i.e., these should all be
211 separate directories. Please don't build out of the
212 source directory.
213 </li>
214 </ol>
215
216 <p>Check out or download the GCC sources: the resulting source directory
217 (<code>gcc</code> or <code>gcc-3.0.3</code>, for example) is
218 <em>gccsrcdir</em>.
219 Once in <em>gccsrcdir</em>, you'll need to rename or delete the
220 libstdc++-v3 directory which comes with that snapshot:
221 </p>
222 <pre>
223 mv libstdc++-v3 libstdc++-v3-previous <strong>[OR]</strong>
224 rm -r libstdc++-v3</pre>
225 <p>Next, unpack the libstdc++-v3 library tarball into this
226 <em>gccsrcdir</em> directory; it will create a
227 <em>libsrcdir</em> called <code>libstdc++-<em>version</em></code>:
228 </p>
229 <pre>
230 gzip -dc libstdc++-version.tar.gz | tar xf -</pre>
231 <p>Finally, rename <em>libsrcdir</em> to <code>libstdc++-v3</code> so that
232 gcc's configure flags will be able to deal with the new library.
233 </p>
234 <pre>
235 mv <em>libsrcdir</em> libstdc++-v3</pre>
236
237
238<hr />
239<h2><a name="config">Configuring</a></h2>
240 <p>If you have never done this before, you should read the basic
241 <a href="http://gcc.gnu.org/install/">GCC Installation
242 Instructions</a> first. Read <em>all of them</em>.
243 <strong>Twice.</strong>
244 </p>
245 <p>When building libstdc++-v3 you'll have to configure
246 the entire <em>gccsrcdir</em> directory. The full list of libstdc++-v3
247 specific configuration options, not dependent on the specific compiler
248 release being used, can be found <a href="configopts.html">here</a>.
249 </p>
250 <p>Consider possibly using --enable-languages=c++ to save time by only
251 building the C++ language parts.
252 </p>
253
254 <pre>
255 cd <em>gccbuilddir</em>
256 <em>gccsrcdir</em>/configure --prefix=<em>destdir</em> --other-opts...</pre>
257
258
259<hr />
260<h2><a name="install">Building and installing the library</a></h2>
261 <p>Now you have a few options:</p>
262 <h3>[re]building <em>everything</em></h3>
263 <p>If you're building GCC from scratch, you can do the usual
264 <code> 'make bootstrap' </code> here, and libstdc++-v3 will be built
265 as its default C++ library. The generated g++ will magically
266 use the correct headers, link against the correct library
267 binary, and in general using libstdc++-v3 will be a piece of
268 cake. You're done; run <code>'make install'</code> (see the GCC
269 installation instructions) to put the new compiler and libraries
270 into place.
271 </p>
272
273 <h3>[re]building only libstdc++</h3>
274 <p>To rebuild just libstdc++, use: </p>
275 <pre>
276 make all-target-libstdc++-v3</pre>
277 <p>
278 This will configure and build the C++ library in the
279 <em>gccbuilddir/cpu-vendor-os/</em>libstdc++ directory.
280 </p>
281 <p>If you are rebuilding from a previous build [attempt], some
282 information is kept in a cache file. This is stored in
283 <em>gccbuilddir/cpu-vendor-os/</em> if you are building with
284 multilibs (the default), or in
285 <em>gccbuilddir/cpu-vendor-os/</em>libstdc++-v3 if you have
286 multilibs disabled. The filename is config.cache; if previous
287 information is causing problems, you can delete it entirely, or
288 simply edit it and remove lines.
289 </p>
290 <p>You're done. Now install the rebuilt pieces with</p>
291 <pre>
292 make install</pre>
293 <p>or</p>
294 <pre>
295 make install-gcc
296 make install-target-libstdc++-v3</pre>
297
298
299<hr />
300<h2><a name="postinstall">Post-installation</a></h2>
301 <p>Installation will create the <em>destdir</em> directory and
302 populate it with subdirectories:
303 </p>
304 <pre>
305 lib/
306 include/c++/<em>gcc-version</em>
307 backward/
308 bits/
309 <em>cpu-vendor-os</em>/bits/
310 ext/</pre>
311 <p>If you used the version-specific-libs configure option, then most of
312 the headers and library files will be moved under
313 <code>lib/gcc-lib/</code> instead.
314 </p>
315
316<hr />
317<h2><a name="usage">Using the library</a></h2>
318 <h3>Find the new library at runtime (shared linking only)</h3>
319 <p>If you only built a static library (libstdc++.a), or if you
320 specified static linking, you don't have to worry about this.
321 But if you built a shared library (libstdc++.so) and linked
322 against it, then you will need to find that library when you
323 run the executable.
324 </p>
325 <p>Methods vary for different platforms and different styles, but
326 the usual ones are printed to the screen during installation.
327 They include:
328 </p>
329 <ul>
330 <li>At runtime set LD_LIBRARY_PATH in your environment correctly,
331 so that the shared library for libstdc++ can be found and
332 loaded. Be certain that you understand all of the other
333 implications and behavior of LD_LIBRARY_PATH first (few
334 people do, and they get into trouble).
335 </li>
336 <li>Compile the path to find the library at runtime into the
337 program. This can be done by passing certain options to g++,
338 which will in turn pass them on to the linker. The exact
339 format of the options is dependent on which linker you use:
340 <ul>
341 <li>GNU ld (default on Linux):<code> -Wl,--rpath,<em>destdir</em>/lib</code></li>
342 <li>IRIX ld:<code> -Wl,-rpath,<em>destdir</em>/lib</code></li>
343 <li>Solaris ld:<code> -Wl,-R<em>destdir</em>/lib</code></li>
344 <li>More...? Let us know!</li>
345 </ul>
346 </li>
347 </ul>
348 <p>Use the <code>ldd(1)</code> utility to show which library the system
349 thinks it will get at runtime.
350 </p>
351 <p>A libstdc++.la file is also installed, for use with Libtool. If
352 you use Libtool to create your executables, these details are
353 taken care of for you.
354 </p>
355
356
357<!--
358<hr />
359<h2><a name=""></a></h2>
360 <p>
361 </p>
362
363-->
364
365<!-- ####################################################### -->
366
367<hr />
368<p class="fineprint"><em>
369See <a href="17_intro/license.html">license.html</a> for copying conditions.
370Comments and suggestions are welcome, and may be sent to
371<a href="mailto:[email protected]">the libstdc++ mailing list</a>.
372</em></p>
373
374
375</body>
376</html>
377
Note: See TracBrowser for help on using the repository browser.