OSDN Git Service

2003-03-13 Jonathan Wakely <redi@gcc.gnu.org>
[pf3gnuchains/gcc-fork.git] / libstdc++-v3 / docs / html / install.html
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="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" />
14 </head>
15 <body>
16
17 <h1 class="centered"><a name="top">libstdc++-v3 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: en_HK, en_US,
115       fr_FR, fr_FR@euro, de_DE, de_DE@euro, ja_JP.eucjp, es_MX, en_PH,
116       and it_IT. Failure to have the underlying "C" library locale
117       information installed will mean that C++ named locales for the
118       above regions will not work: because of this, the libstdc++
119       testsuite will not pass the named locale tests. If this isn't an
120       issue, don't worry about it. If named locales are needed, the
121       underlying locale information must be installed. Note that
122       rebuilding libstdc++ after the "C" locales are installed is not
123       necessary.
124       </p>
125
126       <p> To install
127       support for locales, do only one of the following: </p>
128       <ul>
129         <li> install all locales
130         <p> <code> export LC_ALL=C </code> </p>
131         <p> <code> rpm -e glibc-common --nodeps </code> </p>
132         <p> <code> rpm -i --define "_install_langs all"
133                    glibc-common-2.2.5-34.i386.rpm </code> </p>
134         </li>
135         <li> install just the necessary locales
136         <p> <code> localedef -i de_DE -f ISO-8859-1 de_DE </code> </p>
137         </li>
138       </ul>
139       </dd>
140    </dl>
141
142 <hr />
143
144 <h2><a name="srcsetup">Setting up the source directories</a></h2>
145    <p>The following definitions will be used throughout the rest of this
146       document:
147    </p>
148       <ul>
149          <li><em>gccsrcdir</em>:  The directory holding the source of the
150                  compiler.  It should have several subdirectories like
151                  <em>gccsrcdir</em>/libiberty and <em>gccsrcdir</em>/gcc.
152          </li>
153          <li><em>libsrcdir</em>:  The directory holding the source of the
154                  C++ library.
155          </li>
156          <li><em>gccbuilddir</em>:  The build directory for the compiler
157                  in <em>gccsrcdir</em>.  GCC requires that it be built in
158                  a different directory than its sources.
159          </li>
160          <li><em>libbuilddir</em>:  The build directory for libstdc++.
161          </li>
162          <li><em>destdir</em>:  The eventual installation directory for
163                  the compiler/libraries, set with the --prefix option to
164                  the configure script.
165          </li>
166       </ul>
167       <p> Note: </p>
168       <ol>
169          <li>The 3.0 version and following are intended to replace the
170              library that comes with the compiler, so <em>libsrcdir</em>
171              and <em>libbuilddir</em> must be contained under
172              <em>gccsrcdir</em> and <em>gccbuilddir</em>, respectively.
173          </li>
174          <li>The source, build, and installation directories should
175              not be parents of one another; i.e., these should all be
176              separate directories. Please don't build out of the
177              source directory.
178          </li>
179       </ol>
180
181    <p>Check out or download the GCC sources: the resulting source directory
182       (<code>gcc</code> or <code>gcc-3.0.3</code>, for example) is
183       <em>gccsrcdir</em>.
184       Once in <em>gccsrcdir</em>, you'll need to rename or delete the
185       libstdc++-v3 directory which comes with that snapshot:
186    </p>
187    <pre>
188    mv libstdc++-v3 libstdc++-v3-previous  <strong>[OR]</strong>
189    rm -r libstdc++-v3</pre>
190    <p>Next, unpack the libstdc++-v3 library tarball into this
191       <em>gccsrcdir</em> directory; it will create a
192       <em>libsrcdir</em> called <code>libstdc++-<em>version</em></code>:
193    </p>
194    <pre>
195    gzip -dc libstdc++-version.tar.gz | tar xf -</pre>
196    <p>Finally, rename <em>libsrcdir</em> to <code>libstdc++-v3</code> so that
197       gcc's configure flags will be able to deal with the new library.
198    </p>
199    <pre>
200    mv <em>libsrcdir</em> libstdc++-v3</pre>
201
202
203 <hr />
204 <h2><a name="config">Configuring</a></h2>
205    <p>If you have never done this before, you should read the basic
206       <a href="http://gcc.gnu.org/install/">GCC Installation
207       Instructions</a> first.  Read <em>all of them</em>.
208       <strong>Twice.</strong>
209    </p>
210    <p>When building libstdc++-v3 you'll have to configure
211       the entire <em>gccsrcdir</em> directory.  The full list of libstdc++-v3
212       specific configuration options, not dependent on the specific compiler
213       release being used, can be found <a href="configopts.html">here</a>.
214    </p>
215    <p>Consider possibly using --enable-languages=c++ to save time by only
216       building the C++ language parts.
217    </p>
218
219    <pre>
220    cd <em>gccbuilddir</em>
221    <em>gccsrcdir</em>/configure --prefix=<em>destdir</em> --other-opts...</pre>
222
223
224 <hr />
225 <h2><a name="install">Building and installing the library</a></h2>
226    <p>Now you have a few options:</p>
227    <h3>[re]building <em>everything</em></h3>
228    <p>If you're building GCC from scratch, you can do the usual
229       <code> 'make bootstrap' </code> here, and libstdc++-v3 will be built
230       as its default C++ library.  The generated g++ will magically
231       use the correct headers, link against the correct library
232       binary, and in general using libstdc++-v3 will be a piece of
233       cake.  You're done; run <code>'make install'</code> (see the GCC
234       installation instructions) to put the new compiler and libraries
235       into place.
236    </p>
237
238    <h3>[re]building only libstdc++</h3>
239    <p>To rebuild just libstdc++, use: </p>
240    <pre>
241    make all-target-libstdc++-v3</pre>
242    <p>
243       This will configure and build the C++ library in the
244       <em>gccbuilddir/cpu-vendor-os/</em>libstdc++ directory.
245    </p>
246    <p>If you are rebuilding from a previous build [attempt], some
247       information is kept in a cache file.  This is stored in
248       <em>gccbuilddir/cpu-vendor-os/</em> if you are building with
249       multilibs (the default), or in
250       <em>gccbuilddir/cpu-vendor-os/</em>libstdc++-v3 if you have
251       multilibs disabled.  The filename is config.cache; if previous
252       information is causing problems, you can delete it entirely, or
253       simply edit it and remove lines.
254    </p>
255    <p>You're done.  Now install the rebuilt pieces with</p>
256    <pre>
257    make install</pre>
258    <p>or</p>
259    <pre>
260    make install-gcc
261    make install-target-libstdc++-v3</pre>
262
263
264 <hr />
265 <h2><a name="postinstall">Post-installation</a></h2>
266    <p>Installation will create the <em>destdir</em> directory and
267       populate it with subdirectories:
268    </p>
269    <pre>
270    lib/
271    include/c++/<em>gcc-version</em>
272       backward/
273       bits/
274       <em>cpu-vendor-os</em>/bits/
275       ext/</pre>
276    <p>If you used the version-specific-libs configure option, then most of
277       the headers and library files will be moved under
278       <code>lib/gcc-lib/</code> instead.
279    </p>
280    <p>You can check the status of the build without installing it using</p>
281    <pre>
282    make check</pre>
283    <p>or you can check the status of the installed library using</p>
284    <pre>
285    make check-install</pre>
286    <p>in the <em>libbuilddir</em> directory.
287       These commands will create a 'testsuite' directory underneath
288       <em>libbuilddir</em> containing the results of the tests.  We are
289       interested in any strange failures of the testsuite; please see
290       <a href="faq/index.html#2_4">FAQ 2.4</a> for which files to examine.
291    </p>
292
293    <p> In addition, there are some testing options that are mostly of
294    interest to library maintainers and system integrators. As such,
295    these tests may not work on all cpu and host combinations. These
296    options include, but are not necessarily limited to, the following:
297    </p>
298
299    <p>The library ABI can be tested using</p>
300    <pre>
301    make check-abi</pre>
302
303    <p>The library can also be tested using a bash script, instead of
304    the default dejagnu test harness</p>
305    <pre>
306    make check-script</pre>
307    <p>or</p>
308    <pre>
309    make check-script-install</pre>
310
311 <hr />
312 <h2><a name="usage">Using the library</a></h2>
313    <h3>Find the new library at runtime (shared linking only)</h3>
314        <p>If you only built a static library (libstdc++.a), or if you
315           specified static linking, you don't have to worry about this.
316           But if you built a shared library (libstdc++.so) and linked
317           against it, then you will need to find that library when you
318           run the executable.
319        </p>
320        <p>Methods vary for different platforms and different styles, but
321           the usual ones are printed to the screen during installation.
322           They include:
323        </p>
324        <ul>
325           <li>At runtime set LD_LIBRARY_PATH in your environment correctly,
326               so that the shared library for libstdc++ can be found and
327               loaded.  Be certain that you understand all of the other
328               implications and behavior of LD_LIBRARY_PATH first (few
329               people do, and they get into trouble).
330           </li>
331           <li>Compile the path to find the library at runtime into the
332               program.  This can be done by passing certain options to g++,
333               which will in turn pass them on to the linker.  The exact
334               format of the options is dependent on which linker you use:
335               <ul>
336   <li>GNU ld (default on Linux):<code>  -Wl,--rpath,<em>destdir</em>/lib</code></li>
337   <li>IRIX ld:<code>  -Wl,-rpath,<em>destdir</em>/lib</code></li>
338   <li>Solaris ld:<code>  -Wl,-R<em>destdir</em>/lib</code></li>
339   <li>More...?  Let us know!</li>
340               </ul>
341           </li>
342        </ul>
343        <p>Use the <code>ldd(1)</code> utility to show which library the system
344           thinks it will get at runtime.
345        </p>
346        <p>A libstdc++.la file is also installed, for use with Libtool.  If
347           you use Libtool to create your executables, these details are
348           taken care of for you.
349        </p>
350
351
352 <!--
353 <hr />
354 <h2><a name=""></a></h2>
355    <p>
356    </p>
357
358 -->
359
360 <!-- ####################################################### -->
361
362 <hr />
363 <p class="fineprint"><em>
364 See <a href="17_intro/license.html">license.html</a> for copying conditions.
365 Comments and suggestions are welcome, and may be sent to
366 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
367 </em></p>
368
369
370 </body>
371 </html>
372