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++, one of the post-2.95.2 GCC 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.

In addition, if you plan to modify the makefiles or regenerate the configure scripts you'll need the nuevo automake, libtool and autoconf to regenerate the Makefiles and configure scripts. These tools are all required to be installed in the same location (most linux distributions install these tools by default, so no worries.)

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. We are moving to DejaGNU, so you'll probably want to get that.

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, and you can get snapshots (as well as releases) of binutils here.

Finally, a few system-specific requirements:

Cygwin

If you are using Cygwin to compile libstdc++-v3 on Win32, you'll have to get a version of the cygwin1.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.

Setting up the source directories

As the libstdc++-v3 sources and the core GCC sources have converged, more and more effort goes to building the library as the default version to be shipped with g++. With the 2.90.8 snapshot, and especially for CVS versions after this release, 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.

By default, all configurations of libstdc++-v3 now have namespaces enabled. Being able to select/de-select this option was a complex task that had hopelessly confused many otherwise intelligent people, and provided an endless stream of silent cursing and cries for help. Because of this, gcc sources are required, and are no longer optional.

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/libio 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.

1. The .91 snapshot 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.

Since the release of libstdc++-2.90.8, configuration patches have gone into CVS gcc that make the management of the various libstdc++ source trees a bit easier. Because of this, both libstdc++-v2 and libstdc++-v3 and live together in peace, without the need for soft linking. The setup instructions are slightly different, depending on whether you want to use CVS gcc or a snapshot. Please choose the appropriate scenario:

...with a gcc-2.9[67] snapshot

Unpack the gccsrcdir and go into that directory. For instance, gcc-2.95.2 is a valid 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 the gccsrcdir directory; it will create a libsrcdir called libstdc++-version:

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

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

   ln -s libsrcdir libstdc++-v3

...with CVS gcc

Check out or download the gcc sources: the resulting source directory 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.

Due to namespaces, 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

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

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

Post-installation

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

   lib/
   include/g++-v3/
      bits/
      ext/
   CPU-vendor-OS/include/g++-v3/
      bits/
      ext/

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

   make check

   make check-install

Using the library