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