libstdc++-v3 INSTALL

The latest version of this document is always available at

To the libstdc++-v3 homepage.


Tools you will need beforehand

You will need a recent version of g++ to compile the snapshot of libstdc++: gcc-2.95.2 works well. You will need the full source distribution to whatever compiler release you are using.

In addition, if you plan to modify the makefiles or regenerate the configure scripts: automake (version 1.4 from Cygnus, not the one on the net. It's available here and autoconf (version 2.13 and higher), which is available here.

If you don't have bash, and want to run 'make check' to test your build, you'll need to get bash 2.x. Also recommended is GNU Make, since it is the only 'make' that will parse these makefiles correctly.

Finally, if you are using cygwin to compile libstdc++-v3 on win32, you'll have to get a version of the cygwin.dll that is dated on or after February 1, 2000. This is necessary to successfully run the script "mknumeric_limits" which probes the floating-point environment of the host in question--before this date, Cygwin would freeze when running this script. In addition, you may want to get a current version of libtool (say libtool-1.3.4 and above) as earlier versions supposedly had problems creating shared libraries.

Configuring the library

How you configure the library depends on whether you want namespace std:: to be enabled:

Building and Installing the library

As the libstdc++-v3 sources and the core GCC sources move towards convergence, more and more effort goes to building the library as the default version to be shipped with g++. With the 2.90.8 snapshot, this is treated as the usual scenario. If you want to build the library all by itself, you will need to explicitly disable certain features (like namespaces) since the core GCC library, libgcc.a, will not be rebuilt with those same features.

Go into the source distribution for the compiler. For instance, gcc-2.95.2 is a valid name. This directory will be referred to as gccsrcdir in the rest of this document. Once in gccsrcdir, you'll need to rename the directories called libstdc++ and libio like so:

      mv libstdc++ libstdc++-v2
      mv libio libio-v2

Next, unpack the library tarball into this directory; it will create a directory called libstdc++-version. This directory will be referred to as libsrcdir in the rest of this document:

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

Finally, make a soft link between libsrcdir and libstdc++ so that libstdc++-v3 will be the default C++ library used.

   ln -s libsrcdir libstdc++
This complexity of having two completely separate libstdc++ libraries is necessary so that you can unlink libsrcdir and update the compiler sources. If you're not this adventurous, or would not like to switch between different C++ standard libraries, this extra effort is probably wasted; just remove the v2 sources.

Now you have two options:

[re]building everything

If you're building GCC from scratch, you can do the usual 'make boostrap' 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.

[re]building only the libraries

If you already have g++ installed and just want the new libraries , the rest of this page is for you.

You must have a recent snapshot release of gcc built (tested with gcc-2.95.2), and massaged your PATH variable so that it is used for the building of the library. To check your PATH, you can run 'which g++' (for csh-family shells) or 'type g++' (for ksh or bash). To check the exact version of the compiler, run 'g++ --version'.

Now, on to building! It's recommended that you create a separate build directory apart from the source directory for the building of the library; this will be assumed for the rest of the instructions. This build directory will be called bld-libstdc++ in the rest of this document. Create and 'cd' into this directory.

It is also recommended that libsrcdir should not be the parent directory of bld-libstdc++, nor vice versa, i.e., the closest they should be is sibling directories. This will be assumed for the rest of this document.

If you're rebuilding the GCC library along with libstdc++, you can go into your GCC builddir and run "make all" (a subset of "make bootstrap"). This will build a whole bunch of other things that you probably didn't want, but will also configure and compile the library, under the gccbuilddir/cpu-vendor-OS/libstdc++ directory. The core libgcc.a will also be rebuilt.

If you're not rebuilding the GCC library, or you just have it located in a different place, then you can run the configure script out of the libsrcdir directory. You can pass many options to configure that will affect its behavior; for the more interesting ones, run 'configure --help' and see the section Interesting configure options below. At minimum, you should specify where to install the library using the --prefix option:

   libsrcdir/configure --prefix=$HOME/new_libstdc++_install
The installation directory will be referred to as destdir in the rest of this document.

Installing the library is simple. Go into your bld-libstdc++ directory, and run:

   make install

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


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
These commands will create a 'testsuite' directory underneath bld-libstdc++ 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.

Return to the top of the README or to the homepage.

Building and Installing the library (without GCC sources)

This method will soon be unsupported, and after that it will be actively discouraged. If you keep trying to build the library by itself, doing so will get harder and harder, and if you persist, right-thinking people everywhere will shun your company, and small children will fear you.

First you'll need to supply configuration infrastructure files that would normally be supplied by GCC: install-sh, mkinstalldirs, missing, ltconfig,, config.guess, and config.sub.

You should read over the "normal" installation instrutions above to get a feel for the procedure. You will need to use a build directory that is separate from the source directory, but if you're attempting this step, we assume that you already know these things.

You must pass at least these two options when you run the 'configure' script:

   --disable-namespaces  --disable-libgcc-rebuild
You cannot rebuild the GCC library since you don't have the sources, and you cannot build a std::-supporting library because doing so currently requires that you rebuild the GCC library.

After that, 'make' and 'make install' should function as any other GNU-type package. You can now go to the section about using the library below.

Return to the top of the README or to the homepage.

Using the library

Assuming that just the library was built (ie the directions for [re]building only the libraries), you'll have to do three things to use the library:

  1. Pick up the new include files at compile time

    Add -Idestdir/include/g++-v3 to the command line for each file you compile. This will pick up the new editions of <string> and so forth.

    If you want the SGI extensions (like hash tables), you can add -Idestdir/include/g++-v3/ext and/or -Idestdir/include/g++-v3/backward.

  2. Link against the new library at link time

    Add -Ldestdir/lib to the command line when you produce an executable. The g++ driver already links against libstdc++.a; this will just make it find the new one.

  3. 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 ( 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:

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

Return to the top of the README or to the homepage.

This README was originally put together by Nicolai M. Josuttis, who deserves thanks for all his volunteer efforts!
Comments and suggestions are welcome, and may be sent to Phil Edwards or Gabriel Dos Reis.
$Id: install.html,v 1.7 2000/03/23 20:58:37 pme Exp $