GNU C++ RUNTIME LIBRARY TESTSUITE
=================================

This package contains the GNU C++ Runtime Library Testsuite for
version 3.4.3 of the GNU Compiler Collection.  The tests contained in
this package are the same tests distributed with the GNU Compiler
Collection.  The QMTest extension modules included in this package was
developed by CodeSourcery, LLC under contract from the Free Standards
Group.

For assistance with this software, please contact:

  support@codesourcery.com

For general information about QMTest, the software used to run these
tests, please visit:

  http://www.qmtest.com

You can also send mail to the QMTest mailing list:

  qmtest@codesourcery.com

if you have questions about QMTest.

PREREQUISITES
=============

- Python 2.2 (or later)

  Python binary packages are available for all popular GNU/Linux
  distributions and for many other operating systems.  If you do not
  already have Python, visit http://www.python.org.

- QMTest 2.2 (or later)

  QMTest 2.2 is available from http://www.codesourcery.com/qmtest/download.html
  The source tarball will configure and build easily.

  For binary RPMs for use for LSB testing (seven architectures), see 
  http://www.linuxbase.org/download.  These binary RPMs will also
  require a matching version of Python, for portability purposes the
  LSB Application Battery version of Python (lsb-python) is used.
  This is available from the same download page and is a prerequisite
  for installing the qm package.

- Locales
 
  The tests will access the following locales, which must be installed
  on the runtime system for correct behavior (these would normally
  come from the gcc source tree for a compile test):

    en_US, en_HK, de_DE, de_DE@euro, fr_FR, fr_FR@euro, en_PH, es_MX

- GNU Compiler Collection

  In order to test the GNU C++ Runtime Library, you must install
  the GNU C++ Compiler (G++) and its associated Runtime Library.

INSTALLATION
============

There are two installation methods for the Testsuite, depending on
which package format you select.  Both package formats contain
identical files; which package format you select is purely a matter of
preference.

GNU Zip Tape Archive
--------------------

Download the file:

  qmtest_libstdcpp_3.4.3-1.0.tar.gz

Then, unpack the file with the following command:

  $ tar xzf qmtest_libstdcpp_3.4.3-1.0.tar.gz

And then build the testsuite by running:

  $ cd qmtest_libstdcpp_3.4.3
  $ ./build_binary_testsuite

Before doing this, make sure that you have a canonical version of g++ in
your "PATH", and a canonical version of libstdc++ in your
"LD_LIBRARY_PATH"; the resulting testsuite will specifically test other
libraries for compatibility with this compiler and library.  The command
will generate copious log output; you may wish to use it to verify that
the proper compiler was used.

You must also ensure that a recent version of "qmtest" is in your path.

Red Hat Package Manager
-----------------------

A prebuilt version of the test suite for i386, compiled using the GNU
3.3.3 release of g++ and libstdc++, is packaged in RPM format.  To
install it, first download the file:

  qmtest_libstdcpp_3.4.3-1.0-1.i386.rpm

Then, install the file with the following command, which must be run
as "root":

  $ rpm -i qmtest_libstdcpp_3.4.3-1.0-1.i386.rpm

The package will be installed in the directories:

  /usr/share/qmtest_libstdcpp_3.4.3
  /usr/lib/qmtest_libstdcpp_3.4.3
  
USAGE
=====

The following examples all assume that you are using the Bourne shell.
If you are using an alternative shell, you may have to make minor
changes to the commands.  Furthermore, these commands assume that the
environment variable "PKGROOT" is the path to the directory in which
you installed the Testsuite.  For example, if you used the RPM
installation, "PKGROOT" should be set to
"/usr/share/qmtest_libstdcpp_3.4.3".  They also assume that
the environment variable "EXECROOT" is the path in which the
pre-generated test executables are stored.  If you used the RPM
installation, "EXECROOT" should be set to
"/usr/lib/qmtest_libstdcpp_3.4.3".  If you used the TAR
archive installation, "EXECROOT" should be set to
"$PKGROOT/qm-executables".

These examples assume that "qmtest" is in your path.  You must also
ensure that the "LD_LIBRARY_PATH" environment variable includes the
directory in which the GNU C++ Runtime Library has been installed.  If
your "g++" is in "/path/to/bin/g++", then your "LD_LIBRARY_PATH" should
include "/path/to/lib".

There are four steps required to run the testsuite:

1. Tell QMTest where to find the extension classes required for the
   Testsuite:

     $ QMTEST_CLASS_PATH=$PKGROOT/qm-classes/qmtc:$PKGROOT/qm-classes/qmtest_gcc
     $ export QMTEST_CLASS_PATH

2. Create a test database.

     $ qmtest -D v3db create-tdb -c v3_database.V3Database \
                                 -a srcdir=$PKGROOT/testsuite

3. Create a context file.
 
   The file should be named "v3db/context" and should contain contents
   similar to:

     CompilerTable.languages=
     V3Test.have_compiler=no
     V3Test.scratch_dir=scratch
     V3Test.compiler_output_dir=$EXECROOT
     DejaGNUTest.target=i686-pc-linux-gnu

  WARNING: You must replace $EXECROOT in the above with the actual path
  to your executables; QMTest will not perform environment variable
  expansion on this file.

  You should also adjust the "DejaGNUTest.target" line to indicate the
  GNU triplet for your operating system.

4. Run the tests:

     $ cd v3db
     $ qmtest run

   QMTest will display the results on the standard error stream.

   All released versions of G++ fail some of these tests.  Therefore,
   you should not be surprised to see some failures.

   If you would like the results in the TET output format, use the
   following command:

     $ qmtest run \
         --result-stream="tet_stream.TETStream(filename='results.tet')"

   This command will write the results into the file "results.tet"
   using TET output format.

   If you would like to compare the results with the benchmark results
   obtained with the canonical compiler/library used to build the
   testsuite on your architecture, use the following command.

     $ qmtest run -O $PKGROOT/qm-baselines/<arch>.qmr

  For example, if you are running QMTest on Linux running on the Intel
  x86 architecture, use:
  
     $ qmtest run -O $PKGROOT/qm-baselines/i686-pc-linux-gnu.qmr

  QMTest supports a variety of more complex usage scenarios.  For more
  information see the QMTest manual, available at:

    http://www.codesourcery.com/public/qmtest/qm-2.1.2/manual.html

BASELINE FILES
==============

In the interests of insuring binary compatibility, the libstdc++
testsuite compares the symbols exported by the libstdc++ under test to
those exported by some canonical baseline version.  Unfortunately, these
baseline versions are different for each architecture, and so this
package may not contain a baseline file for your architecture.  If this
happens, the test "v3_abi_test" will return an ERROR, and complain that
its baseline file does not exist.

The solution is to create a baseline file.  To do so, download the
source for GCC version 3.4.3, and build it normally.  Say that
the GCC source tree is $SRC, and you have built it in $BUILD.  Now, do
the following:
  $ cd $BUILD/<your architecture>/libstdc++-v3/testsuite
  $ make new-abi-baseline
This will generate a new baseline directory called
  $SRC/libstdc++/config/abi/<your architecture>
Drop this directory in $PKGROOT/config/abi/, and the test suite should
now work.

To build an RPM package with the new baseline included, start with the
.tar.gz distribution, unpack it, follow the above instructions, then
repack it and run
  $ rpm -tb <the new .tar.gz file>
as you would to build any other RPM.

