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
  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       The configure option --enable-clocale can be used force a
  84       particular behavior.
  85       </p>
  86
  87       <p>
  88       If the 'gnu' locale model is being used, the following locales
  89       are used and tested in the libstdc++ testsuites.  The first column
  90       is the name of the locale, the second is the character set it is
  91       expected to use.
  92       </p>
  93 <pre>
  94 de_DE               ISO-8859-1
  95 de_DE@euro          ISO-8859-15
  96 en_HK               ISO-8859-1
  97 en_PH               ISO-8859-1
  98 en_US               ISO-8859-1
  99 en_US.ISO-8859-1    ISO-8859-1
 100 en_US.ISO-8859-15   ISO-8859-15
 101 en_US.UTF-8         UTF-8
 102 es_ES               ISO-8859-1
 103 es_MX               ISO-8859-1
 104 fr_FR               ISO-8859-1
 105 fr_FR@euro          ISO-8859-15
 106 is_IS               UTF-8
 107 it_IT               ISO-8859-1
 108 ja_JP.eucjp         EUC-JP
 109 se_NO.UTF-8         UTF-8
 110 ta_IN               UTF-8
 111 zh_TW               BIG5
 112 </pre>
 113       <p>Failure to have the underlying "C" library locale
 114       information installed will mean that C++ named locales for the
 115       above regions will not work: because of this, the libstdc++
 116       testsuite will skip the named locale tests. If this isn't an
 117       issue, don't worry about it. If named locales are needed, the
 118       underlying locale information must be installed. Note that
 119       rebuilding libstdc++ after the "C" locales are installed is not
 120       necessary.
 121       </p>
 122
 123       <p>To install support for locales, do only one of the following:
 124       </p>
 125
 126       <ul>
 127         <li> install all locales
 128           <ul>
 129             <li>with RedHat Linux:
 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> (instructions for other operating systems solicited) </li>
 136           </ul>
 137         </li>
 138         <li> install just the necessary locales
 139           <ul>
 140             <li>with Debian Linux:
 141         <p> Add the above list, as shown, to the file
 142             <code>/etc/locale.gen</code> </p>
 143         <p> run <code>/usr/sbin/locale-gen</code> </p>
 144             </li>
 145             <li> on most Unix-like operating systems:
 146         <p> <code> localedef -i de_DE -f ISO-8859-1 de_DE </code> </p>
 147         <p> (repeat for each entry in the above list) </p>
 148             </li>
 149             <li> (instructions for other operating systems solicited) </li>
 150           </ul>
 151         </li>
 152       </ul>
 153       </dd>
 154    </dl>
 155
 156 <hr />
 157
 158 <h2><a name="config">Configuring</a></h2>
 159    <p>If you have never done this before, you should read the basic
 160       <a href="http://gcc.gnu.org/install/">GCC Installation
 161       Instructions</a> first.  Read <em>all of them</em>.
 162       <strong>Twice.</strong>
 163    </p>
 164    <p>When building libstdc++-v3 you'll have to configure
 165       the entire <em>gccsrcdir</em> directory.  The full list of libstdc++-v3
 166       specific configuration options, not dependent on the specific compiler
 167       release being used, can be found <a href="configopts.html">here</a>.
 168    </p>
 169    <p>Consider possibly using --enable-languages=c++ to save time by only
 170       building the C++ language parts.
 171    </p>
 172
 173    <pre>
 174    cd <em>gccbuilddir</em>
 175    <em>gccsrcdir</em>/configure --prefix=<em>destdir</em> --other-opts...</pre>
 176
 177
 178 <hr />
 179 <h2><a name="usage">Using the library</a></h2>
 180    <h3>Find the new library at runtime (shared linking only)</h3>
 181        <p>If you only built a static library (libstdc++.a), or if you
 182           specified static linking, you don't have to worry about this.
 183           But if you built a shared library (libstdc++.so) and linked
 184           against it, then you will need to find that library when you
 185           run the executable.
 186        </p>
 187        <p>Methods vary for different platforms and different styles, but
 188           the usual ones are printed to the screen during installation.
 189           They include:
 190        </p>
 191        <ul>
 192           <li>At runtime set LD_LIBRARY_PATH in your environment correctly,
 193               so that the shared library for libstdc++ can be found and
 194               loaded.  Be certain that you understand all of the other
 195               implications and behavior of LD_LIBRARY_PATH first (few
 196               people do, and they get into trouble).
 197           </li>
 198           <li>Compile the path to find the library at runtime into the
 199               program.  This can be done by passing certain options to g++,
 200               which will in turn pass them on to the linker.  The exact
 201               format of the options is dependent on which linker you use:
 202               <ul>
 203   <li>GNU ld (default on Linux):<code>  -Wl,--rpath,<em>destdir</em>/lib</code></li>
 204   <li>IRIX ld:<code>  -Wl,-rpath,<em>destdir</em>/lib</code></li>
 205   <li>Solaris ld:<code>  -Wl,-R<em>destdir</em>/lib</code></li>
 206   <li>More...?  Let us know!</li>
 207               </ul>
 208           </li>
 209        </ul>
 210        <p>Use the <code>ldd(1)</code> utility to show which library the system
 211           thinks it will get at runtime.
 212        </p>
 213        <p>A libstdc++.la file is also installed, for use with Libtool.  If
 214           you use Libtool to create your executables, these details are
 215           taken care of for you.
 216        </p>
 217
 218
 219 <!--
 220 <hr />
 221 <h2><a name=""></a></h2>
 222    <p>
 223    </p>
 224
 225 -->
 226
 227 <!-- ####################################################### -->
 228
 229 <hr />
 230 <p class="fineprint"><em>
 231 See <a href="17_intro/license.html">license.html</a> for copying conditions.
 232 Comments and suggestions are welcome, and may be sent to
 233 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
 234 </em></p>
 235
 236
 237 </body>
 238 </html>
 239