libstdc++-v3 Installation Instructions
Author: pme@gcc.gnu.org (Phil Edwards)
Description: README for the GNU libstdc++ effort.
Keywords: libstdc++, libstdc++-v3, GCC, g++

# libstdc++-v3 INSTALL

The latest version of this document is always available at http://gcc.gnu.org/onlinedocs/libstdc++/install.html.

To the libstdc++-v3 homepage.

## Contents

- Tools you will need beforehand
- Setting up the source directories
- Configuring
- Building and installing the library
- Post-installation
- Using the library

## Tools you will need beforehand

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 mirror list. If you are using a 2.x compiler, see the status page first.

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), and libtool (multilanguage, version 1.4 or later), 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).

To test your build, you will need either DejaGNU 1.4 (to run `'make check'` like the rest of GCC), or Bash 2.x (to run `'make check-script'`).

As of June 19, 2000, libstdc++ attempts to use tricky and space-saving features of the GNU toolchain, enabled with `-ffunction-sections -fdata-sections -Wl,--gc-sections`. 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 `2.10.90`, or later, and you can get snapshots (as well as releases) of binutils here. The configure process will automatically detect and use these features if the underlying support is present.

If you are using a 3.1-series libstdc++ snapshot, then the requirements are slightly more stringent: the compiler sources must also be 3.1 or later (for both technical and licensing reasons), and your binutils must be 2.11.95 or later if you want to use symbol versioning in shared libraries. Again, the configure process will automatically detect and use these features if the underlying support is present.

Finally, a few system-specific requirements:

linux
  If gcc 3.1.0 or later on is being used on linux, an attempt will be made to use "C" library functionality necessary for C++ named locale support.

  The configure option --enable-clocale can be used force a particular behavior.

  If the 'gnu' locale model is being used, the following locales are used and tested in the libstdc++ testsuites: en_HK, en_US, fr_FR, fr_FR@euro, de_DE, de_DE@euro, ja_JP.eucjp, es_MX, en_PH, and it_IT. Failure to have the underlying "C" library locale information installed will mean that C++ named locales for the above regions will not work: because of this, the libstdc++ testsuite will not pass the named locale tests. If this isn't an issue, don't worry about it. If named locales are needed, the underlying locale information must be installed. Note that rebuilding libstdc++ after the "C" locales are installed is not necessary.

  To install support for locales, do only one of the following:

  - install all locales

    `export LC_ALL=C`

    `rpm -e glibc-common --nodeps`

    `rpm -i --define "_install_langs all" glibc-common-2.2.5-34.i386.rpm`

  - install just the necessary locales

    `localedef -i de_DE -f ISO-8859-1 de_DE`

## Setting up the source directories

The following definitions will be used throughout the rest of this document:

- gccsrcdir: The directory holding the source of the compiler. It should have several subdirectories like gccsrcdir/libiberty and gccsrcdir/gcc.
- libsrcdir: The directory holding the source of the C++ library.
- gccbuilddir: The build directory for the compiler in gccsrcdir. GCC requires that it be built in a different directory than its sources.
- libbuilddir: The build directory for libstdc++.
- destdir: The eventual installation directory for the compiler/libraries, set with the --prefix option to the configure script.

Note:

1. The 3.0 version and following are intended to replace the library that comes with the compiler, so libsrcdir and libbuilddir must be contained under gccsrcdir and gccbuilddir, respectively.
2. 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.

Check out or download the GCC sources: the resulting source directory (`gcc` or `gcc-3.0.3`, for example) is gccsrcdir. Once in gccsrcdir, you'll need to rename or delete the libstdc++-v3 directory which comes with that snapshot:

       mv libstdc++-v3 libstdc++-v3-previous  [OR]
       rm -r libstdc++-v3

Next, unpack the libstdc++-v3 library tarball into this gccsrcdir directory; it will create a libsrcdir called `libstdc++-version`:

       gzip -dc libstdc++-version.tar.gz | tar xf -

Finally, rename libsrcdir to `libstdc++-v3` so that gcc's configure flags will be able to deal with the new library.

       mv libsrcdir libstdc++-v3

## Configuring

If you have never done this before, you should read the basic GCC Installation Instructions first. Read all of them. Twice.

When building libstdc++-v3 you'll have to configure the entire gccsrcdir directory. The full list of libstdc++-v3 specific configuration options, not dependent on the specific compiler release being used, can be found here.

Consider possibly using --enable-languages=c++ to save time by only building the C++ language parts.

       cd gccbuilddir
       gccsrcdir/configure --prefix=destdir --other-opts...

## Building and installing the library

Now you have a few options:

### [re]building everything

If you're building GCC from scratch, you can do the usual `'make bootstrap'` 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 `'make install'` (see the GCC installation instructions) to put the new compiler and libraries into place.

### [re]building only libstdc++

To rebuild just libstdc++, use:

       make all-target-libstdc++-v3

This will configure and build the C++ library in the gccbuilddir/cpu-vendor-os/libstdc++ directory.

If you are rebuilding from a previous build [attempt], some information is kept in a cache file. This is stored in gccbuilddir/cpu-vendor-os/ if you are building with multilibs (the default), or in gccbuilddir/cpu-vendor-os/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.

You're done. Now install the rebuilt pieces with

       make install

or

       make install-gcc
       make install-target-libstdc++-v3

## Post-installation

Installation will create the destdir directory and populate it with subdirectories:

       lib/
       include/c++/gcc-version
          backward/
          bits/
          cpu-vendor-os/bits/
          ext/

If you used the version-specific-libs configure option, then most of the headers and library files will be moved under `lib/gcc-lib/` instead.

You can check the status of the build without installing it using

       make check

or you can check the status of the installed library using

       make check-install

in the libbuilddir directory. These commands will create a 'testsuite' directory underneath libbuilddir containing the results of the tests. We are interested in any strange failures of the testsuite; please see FAQ 2.4 for which files to examine.

In addition, there are some testing options that are mostly of interest to library maintainers and system integrators. As such, these tests may not work on all cpu and host combinations. These options include, but are not necessarily limited to, the following:

The library ABI can be tested using

       make check-abi

The library can also be tested using a bash script, instead of the default dejagnu test harness

       make check-script

or

       make check-script-install

## Using the library

### Find the new library at runtime (shared linking only)

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.

Methods vary for different platforms and different styles, but the usual ones are printed to the screen during installation. They include:

- 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).
- 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:
  - GNU ld (default on Linux):`-Wl,--rpath,destdir/lib`
  - IRIX ld:`-Wl,-rpath,destdir/lib`
  - Solaris ld:`-Wl,-Rdestdir/lib`
  - More...? Let us know!

Use the `ldd(1)` utility to show which library the system thinks it will get at runtime.

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.

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to the libstdc++ mailing list.