| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> |
| <html> |
| <head> |
| <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> |
| <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++"> |
| <meta name="DESCRIPTION" content="README for the GNU libstdc++ effort."> |
| <meta name="GENERATOR" content="vi and eight fingers"> |
| <title>libstdc++-v3 Installation Instructions</title> |
| <link rel="StyleSheet" href="lib3styles.css"> |
| </head> |
| <body> |
| |
| <h1 class="centered"><a name="top">libstdc++-v3 INSTALL</a></h1> |
| |
| <p>The latest version of this document is always available at |
| <a href="http://gcc.gnu.org/onlinedocs/libstdc++/install.html"> |
| http://gcc.gnu.org/onlinedocs/libstdc++/install.html</a>. |
| </p> |
| |
| <p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>. |
| |
| |
| <!-- ####################################################### --> |
| <hr> |
| <h2>Contents</h2> |
| <ul> |
| <li><a href="#prereqs">Tools you will need beforehand</a> |
| <li><a href="#srcsetup">Setting up the source directories</a> |
| <li><a href="#config">Configuring</a> |
| <li><a href="#install">Building and installing the library</a> |
| <li><a href="#postinstall">Post-installation</a> |
| <li><a href="#usage">Using the library</a> |
| </ul> |
| |
| <hr> |
| |
| <!-- ####################################################### --> |
| |
| <h2><a name="prereqs">Tools you will need beforehand</a></h2> |
| <p>You will need a recent version of g++ to compile the snapshot of |
| libstdc++, such as one of the GCC 3.x snapshots (insert standard |
| caveat about using snapshots rather than formal releases). You |
| will need the full source |
| distribution to whatever compiler release you are using. The |
| GCC snapshots can be had from one of the sites on their |
| <a href="http://gcc.gnu.org/mirrors.html">mirror list</a>. |
| </p> |
| |
| <p>In addition, if you plan to modify the makefiles or regenerate the |
| configure scripts you'll need recent versions of the GNU Autotools: |
| autoconf (version 2.50 or later), |
| automake (version 1.4 or later), <!-- special version? --> |
| and libtool (multilanguage, version 1.4 or later), <!-- really? --> |
| in order to rebuild the files. |
| These tools are all required to be installed in the same location |
| (most linux distributions install these tools by default, so no |
| worries as long as the versions are correct). |
| </p> |
| |
| <p>GNU Make is the only 'make' that will parse the makefiles correctly. |
| </p> |
| |
| <p>To test your build, you will need either DejaGNU 1.4 (to run |
| <code>'make check'</code> like |
| <a href="http://gcc.gnu.org/install/test.html">the rest of GCC</a>), |
| or Bash 2.x (to run <code>'make check-script'</code>). |
| </p> |
| |
| <p>As of June 19, 2000, libstdc++ attempts to use tricky and |
| space-saving features of the GNU toolchain, enabled with |
| <code>-ffunction-sections -fdata-sections -Wl,--gc-sections</code>. |
| To obtain maximum benefit from this, binutils after this date |
| should also be used (bugs were fixed with C++ exception handling |
| related to this change in libstdc++-v3). The version of these |
| tools should be <code>2.10.90</code>, and you can get snapshots (as |
| well as releases) of binutils |
| <a href="ftp://sources.redhat.com/pub/binutils">here</a>. |
| </p> |
| |
| <!-- Commented until some system-specific requirements appear. |
| <p>Finally, a few system-specific requirements: |
| <dl> |
| <dt>Cygwin |
| <dd>If you are using Cygwin to compile libstdc++-v3 on Win32, you'll |
| [snip] |
| |
| </dl> |
| </p> |
| --> |
| |
| <hr> |
| |
| <h2><a name="srcsetup">Setting up the source directories</a></h2> |
| <p>The following definitions will be used throughout the rest of this |
| document: |
| <ul> |
| <li><em>gccsrcdir</em>: The directory holding the source of the |
| compiler. It should have several subdirectories like |
| <em>gccsrcdir</em>/libio and <em>gccsrcdir</em>/gcc. |
| <li><em>libsrcdir</em>: The directory holding the source of the |
| C++ library. |
| <li><em>gccbuilddir</em>: The build directory for the compiler |
| in <em>gccsrcdir</em>. GCC requires that it be built in |
| a different directory than its sources. |
| <li><em>libbuilddir</em>: The build directory for libstdc++. |
| <li><em>destdir</em>: The eventual installation directory for |
| the compiler/libraries, set with the --prefix option to |
| the configure script. |
| </ul> |
| Note: |
| <ol> |
| <li>The 3.0 version and following are intended to replace the |
| library that comes with the compiler, so <em>libsrcdir</em> |
| and <em>libbuilddir</em> must be contained under |
| <em>gccsrcdir</em> and <em>gccbuilddir</em>, respectively. |
| <li>The source, build, and installation directories should |
| not be parents of one another; i.e., these should all be |
| separate directories. Please don't build out of the |
| source directory. |
| </ol> |
| </p> |
| |
| <p>Check out or download the gcc sources: the resulting source directory |
| (<code>gcc</code> or <code>gcc-3.0</code>, for example) is <em>gccsrcdir</em>. |
| Once in <em>gccsrcdir</em>, you'll need to rename or delete the |
| libstdc++-v3 directory which comes with that snapshot: |
| <pre> |
| mv libstdc++-v3 libstdc++-v3-previous <strong>[OR]</strong> |
| rm -r libstdc++-v3</pre> |
| </p> |
| <p>Next, unpack the libstdc++-v3 library tarball into this |
| <em>gccsrcdir</em> directory; it will create a |
| <em>libsrcdir</em> called <code>libstdc++-<em>version</em></code>: |
| <pre> |
| gzip -dc libstdc++-version.tar.gz | tar xf -</pre> |
| </p> |
| <p>Finally, rename <em>libsrcdir</em> to <code>libstdc++-v3</code> so that |
| gcc's configure flags will be able to deal with the new library. |
| <pre> |
| mv <em>libsrcdir</em> libstdc++-v3</pre> |
| </p> |
| |
| |
| <hr> |
| <h2><a name="config">Configuring</a></h2> |
| <p>If you have never done this before, you should read the basic |
| <a href="http://gcc.gnu.org/install/">GCC Installation |
| Instructions</a> first. |
| </p> |
| <p>When building libstdc++-v3 you'll have to configure |
| the entire <em>gccsrcdir</em> directory. The full list of libstdc++-v3 |
| specific configuration options, not dependent on the specific compiler |
| release being used, can be found <a href="configopts.html">here</a>. |
| </p> |
| <p>Consider possibly using --enable-languages=c++ to save time by only |
| building the C++ language parts. |
| </p> |
| |
| <p><pre> |
| cd <em>gccbuilddir</em> |
| <em>gccsrcdir</em>/configure --prefix=<em>destdir</em> --other-opts...</pre> |
| </p> |
| |
| |
| <hr> |
| <h2><a name="install">Building and installing the library</a></h2> |
| <p>Now you have a few options:</p> |
| <h3>[re]building <em>everything</em></h3> |
| <p>If you're building GCC from scratch, you can do the usual |
| <code> 'make bootstrap' </code> here, and libstdc++-v3 will be built |
| as its default C++ library. The generated g++ will magically |
| use the correct headers, link against the correct library |
| binary, and in general using libstdc++-v3 will be a piece of |
| cake. You're done; run <code>'make install'</code> (see the GCC |
| installation instructions) to put the new compiler and libraries |
| into place. |
| </p> |
| |
| <h3>[re]building only libstdc++</h3> |
| <p>To rebuild just libstdc++, use: |
| <pre> |
| make all-target-<em>libstdc++-v3</em></pre> |
| This will configure and build the C++ library in the |
| <em>gccbuilddir/cpu-vendor-os/</em>libstdc++ directory. |
| </p> |
| <p>If you are rebuilding from a previous build [attempt], some |
| information is kept in a cache file. This is stored in |
| <em>gccbuilddir/cpu-vendor-os/</em> if you are building with |
| multilibs (the default), or in |
| <em>gccbuilddir/cpu-vendor-os/</em>libstdc++-v3 if you have |
| multilibs disabled. The filename is config.cache; if previous |
| information is causing problems, you can delete it entirely, or |
| simply edit it and remove lines. |
| </p> |
| <p>You're done. Now install the rebuilt pieces with |
| <pre> |
| make install</pre> |
| or |
| <pre> |
| make install-gcc |
| make install-target-libstdc++-v3</pre> |
| </p> |
| |
| |
| <hr> |
| <h2><a name="postinstall">Post-installation</a></h2> |
| <p>Installation will create the <em>destdir</em> directory and |
| populate it with subdirectories: |
| <pre> |
| lib/ |
| include/g++-v3/ |
| backward/ |
| bits/ |
| <em>cpu-vendor-os</em>/bits/ |
| ext/</pre> |
| </p> |
| <p>You can check the status of the build without installing it using |
| <pre> |
| make check</pre> |
| or you can check the status of the installed library using |
| <pre> |
| make check-install</pre> |
| in the <em>libbuilddir</em> directory. |
| These commands will create a 'testsuite' directory underneath |
| <em>libbuilddir</em> containing the results of the tests. We are |
| interested in any strange failures of the testsuite; please see |
| <a href="faq/index.html#2_4">FAQ 2.4</a> for which files to examine. |
| </p> |
| |
| |
| <hr> |
| <h2><a name="usage">Using the library</a></h2> |
| <li><B>Find the new library at runtime (shared linking only)</B> |
| <p>If you only built a static library (libstdc++.a), or if you |
| specified static linking, you don't have to worry about this. |
| But if you built a shared library (libstdc++.so) and linked |
| against it, then you will need to find that library when you |
| run the executable. |
| </p> |
| <p>Methods vary for different platforms and different styles, but |
| the usual ones are printed to the screen during installation. |
| They include: |
| <ul> |
| <li>At runtime set LD_LIBRARY_PATH in your environment correctly, |
| so that the shared library for libstdc++ can be found and |
| loaded. Be certain that you understand all of the other |
| implications and behavior of LD_LIBRARY_PATH first (few |
| people do, and they get into trouble). |
| <li>Compile the path to find the library at runtime into the |
| program. This can be done by passing certain options to g++, |
| which will in turn pass them on to the linker. The exact |
| format of the options is dependent on which linker you use: |
| <ul> |
| <li>GNU ld (default on Linux):<code> -Wl,--rpath,<em>destdir</em>/lib</code> |
| <li>IRIX ld:<code> -Wl,-rpath,<em>destdir</em>/lib</code> |
| <li>Solaris ld:<code> -Wl,-R<em>destdir</em>/lib</code> |
| <li>More...? |
| </ul> |
| </ul> |
| </p> |
| <p>Use the <code>ldd(1)</code> utility to show which library the system |
| thinks it will get at runtime. |
| </p> |
| <p>A libstdc++.la file is also installed, for use with Libtool. If |
| you use Libtool to create your executables, these details are |
| taken care of for you. |
| </p> |
| </ol> |
| </p> |
| |
| |
| <!-- |
| <hr> |
| <h2><a name=""></a></h2> |
| <p> |
| </p> |
| |
| --> |
| |
| <!-- ####################################################### --> |
| |
| <hr> |
| <p class="fineprint"><em> |
| See <a href="17_intro/license.html">license.html</a> for copying conditions. |
| Comments and suggestions are welcome, and may be sent to |
| <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>. |
| </em></p> |
| |
| |
| </body> |
| </html> |
| |
