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
35<p>Because libstdc++-v3 is part of GCC, the primary source for
36   installation instructions is
37   <a href="http://gcc.gnu.org/install/">the GCC install page</a>.
38   Additional data is given here only where it applies to libstdc++-v3.
39</p>
40
41<ul>
42   <li><a href="#prereqs">Tools you will need beforehand</a></li>
43   <li><a href="#config">Configuring</a></li>
44   <li><a href="#usage">Using the library</a></li>
45</ul>
46
47<hr />
48
49<!-- ####################################################### -->
50
51<h2><a name="prereqs">Tools you will need beforehand</a></h2>
52   <p>The list of software needed to build the library is kept with the
53      rest of the compiler, at
54      <a href="http://gcc.gnu.org/install/prerequisites.html">
55      http://gcc.gnu.org/install/prerequisites.html</a>.  The same page
56      also lists the tools you will need if you wish to modify the source.
57   </p>
58
59   <p>As of June 19, 2000, libstdc++ attempts to use tricky and
60      space-saving features of the GNU toolchain, enabled with
61      <code>-ffunction-sections -fdata-sections -Wl,--gc-sections</code>.
62      To obtain maximum benefit from this, binutils after this date should
63      also be used (bugs were fixed with C++ exception handling related
64      to this change in libstdc++-v3).  The version of these tools should
65      be <code>2.10.90</code>, or later, and you can get snapshots (as
66      well as releases) of binutils
67      <a href="ftp://sources.redhat.com/pub/binutils">here</a>. The
68      configure process will automatically detect and use these features
69      if the underlying support is present.
70   </p>
71
72   <p>Finally, a few system-specific requirements: </p>
73   <dl>
74      <dt> linux </dt>
75
76      <dd>If gcc 3.1.0 or later on is being used on linux, an attempt
77      will be made to use "C" library functionality necessary for C++
78      named locale support.  For gcc 3.2.1 and later, this means that
79      glibc 2.2.5 or later is required and the "C" library de_DE locale
80      information must be installed.
81
82      <p>
83      Note however that the sanity checks involving the de_DE locale are
84      skipped when an explicit --enable-clocale=gnu configure option is
85      used: only the basic checks are carried out, defending against
86      misconfigurations.
87      </p>
88
89      <p>
90      If the 'gnu' locale model is being used, the following locales
91      are used and tested in the libstdc++ testsuites.  The first column
92      is the name of the locale, the second is the character set it is
93      expected to use.
94      </p>
95<pre>
96de_DE               ISO-8859-1
97de_DE@euro          ISO-8859-15
98en_HK               ISO-8859-1
99en_PH               ISO-8859-1
100en_US               ISO-8859-1
101en_US.ISO-8859-1    ISO-8859-1
102en_US.ISO-8859-15   ISO-8859-15
103en_US.UTF-8         UTF-8
104es_ES               ISO-8859-1
105es_MX               ISO-8859-1
106fr_FR               ISO-8859-1
107fr_FR@euro          ISO-8859-15
108is_IS               UTF-8
109it_IT               ISO-8859-1
110ja_JP.eucjp         EUC-JP
111se_NO.UTF-8         UTF-8
112ta_IN               UTF-8
113zh_TW               BIG5
114</pre>
115      <p>Failure to have the underlying "C" library locale
116      information installed will mean that C++ named locales for the
117      above regions will not work: because of this, the libstdc++
118      testsuite will skip the named locale tests. If this isn't an
119      issue, don't worry about it. If named locales are needed, the
120      underlying locale information must be installed. Note that
121      rebuilding libstdc++ after the "C" locales are installed is not
122      necessary.
123      </p>
124
125      <p>To install support for locales, do only one of the following:
126      </p>
127
128      <ul>
129        <li> install all locales
130          <ul>
131            <li>with RedHat Linux:
132        <p> <code> export LC_ALL=C </code> </p>
133        <p> <code> rpm -e glibc-common --nodeps </code> </p>
134        <p> <code> rpm -i --define "_install_langs all"
135                   glibc-common-2.2.5-34.i386.rpm </code> </p>
136             </li>
137             <li> (instructions for other operating systems solicited) </li>
138          </ul>
139        </li>
140        <li> install just the necessary locales
141          <ul>
142            <li>with Debian Linux:
143        <p> Add the above list, as shown, to the file
144            <code>/etc/locale.gen</code> </p>
145        <p> run <code>/usr/sbin/locale-gen</code> </p>
146            </li>
147            <li> on most Unix-like operating systems:
148        <p> <code> localedef -i de_DE -f ISO-8859-1 de_DE </code> </p>
149        <p> (repeat for each entry in the above list) </p>
150            </li>
151            <li> (instructions for other operating systems solicited) </li>
152          </ul>
153        </li>
154      </ul>
155      </dd>
156   </dl>
157
158<hr />
159
160<h2><a name="config">Configuring</a></h2>
161   <p>If you have never done this before, you should read the basic
162      <a href="http://gcc.gnu.org/install/">GCC Installation
163      Instructions</a> first.  Read <em>all of them</em>.
164      <strong>Twice.</strong>
165   </p>
166   <p>When building libstdc++-v3 you'll have to configure
167      the entire <em>gccsrcdir</em> directory.  The full list of libstdc++-v3
168      specific configuration options, not dependent on the specific compiler
169      release being used, can be found <a href="configopts.html">here</a>.
170   </p>
171   <p>Consider possibly using --enable-languages=c++ to save time by only
172      building the C++ language parts.
173   </p>
174
175   <pre>
176   cd <em>gccbuilddir</em>
177   <em>gccsrcdir</em>/configure --prefix=<em>destdir</em> --other-opts...</pre>
178
179
180<hr />
181<h2><a name="usage">Using the library</a></h2>
182   <h3>Find the new library at runtime (shared linking only)</h3>
183       <p>If you only built a static library (libstdc++.a), or if you
184          specified static linking, you don't have to worry about this.
185          But if you built a shared library (libstdc++.so) and linked
186          against it, then you will need to find that library when you
187          run the executable.
188       </p>
189       <p>Methods vary for different platforms and different styles, but
190          the usual ones are printed to the screen during installation.
191          They include:
192       </p>
193       <ul>
194          <li>At runtime set LD_LIBRARY_PATH in your environment correctly,
195              so that the shared library for libstdc++ can be found and
196              loaded.  Be certain that you understand all of the other
197              implications and behavior of LD_LIBRARY_PATH first (few
198              people do, and they get into trouble).
199          </li>
200          <li>Compile the path to find the library at runtime into the
201              program.  This can be done by passing certain options to g++,
202              which will in turn pass them on to the linker.  The exact
203              format of the options is dependent on which linker you use:
204              <ul>
205  <li>GNU ld (default on Linux):<code>  -Wl,--rpath,<em>destdir</em>/lib</code></li>
206  <li>IRIX ld:<code>  -Wl,-rpath,<em>destdir</em>/lib</code></li>
207  <li>Solaris ld:<code>  -Wl,-R<em>destdir</em>/lib</code></li>
208  <li>More...?  Let us know!</li>
209              </ul>
210          </li>
211       </ul>
212       <p>Use the <code>ldd(1)</code> utility to show which library the system
213          thinks it will get at runtime.
214       </p>
215       <p>A libstdc++.la file is also installed, for use with Libtool.  If
216          you use Libtool to create your executables, these details are
217          taken care of for you.
218       </p>
219
220
221<!--
222<hr />
223<h2><a name=""></a></h2>
224   <p>
225   </p>
226
227-->
228
229<!-- ####################################################### -->
230
231<hr />
232<p class="fineprint"><em>
233See <a href="17_intro/license.html">license.html</a> for copying conditions.
234Comments and suggestions are welcome, and may be sent to
235<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
236</em></p>
237
238
239</body>
240</html>
241
242