OSDN Git Service

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