About
-----------------------------------------------------
The package "lsb-test-cpp-t2c" contains a test suite for libstdcxx library 

Prerequisites
-----------------------------------------------------
The following components are required to build and run the tests:

1. LSB Software Development Kit (SDK). It can be found here:
       http://www.linux-foundation.org/en/Downloads

Also /lib/ld-lsb.so.3 should be found in your system after installation.
If it is not, you should create a symbolic link with a command
ln -s /lib/ld-linux.so.2 /lib/ld-lsb.so.3
   
2. GNU C/C++ Compiler 3.4.6 or later.

3. TET 3 Lite (Test Environment Toolkit). Official web page: 
http://tetworks.opengroup.org/tet/). 

LSB version of TET can be found here:
ftp://ftp.linux-foundation.org/pub/lsb/snapshots/tet-harness/
"lsb-tet3-lite" package is required for running the tests. You also need 
"lsb-tet3-lite-devel" package if you want to build the tests from source.

If TET root directory is not /opt/lsb-tet3-lite, this directory should be
specified in the TET_ROOT environment variable.

Package Structure
-----------------------------------------------------
Main suite directory is "cpp-t2c". It contains the following files and 
directories:
    README
        This file.
    
    LICENSE 
        License information.        

    run_tests.sh
        This script runs the tests.

    libstdcxx-t2c/
        Tests for libstdcxx library.

	tetexec.cfg
        Test execution parameters for TET.

    tet_code
        Definition of a "TIME EXPIRED" TET result code.

There are also the following files and subdirs in the main suite directory 
in the binary distribution:
    - tet_scen - main TET scenario file.

In the binary distribution the "*-t2c" directories contain the following:
    - scenarios/ - TET scenario files;
    - tests/     - the executables of the tests;
    - testdata/ (if present) - data used for testing;
    - reqs/      - requirement catalogue.

There are also the following files and dirs in the source distribution:
    - t2c_framework/ - tools from the T2C Framework required to prepare and build the tests:
            t2c/ - The T2C (stands for "Template-to-C", "Template-to-Code") 
              test code generator. T2C is used to generate 
              TET-compliant tests in C as well as the makefiles and TET scenarios 
              from the tests in special format (t2c-files).
              t2c/src/ and t2c/include subdirectories contain T2C source code and header 
              files for the generated C files, respectively.
    - cpp-t2c/
        - build_all.sh
          This script is used to build the tests from source.
        - gen_code.sh
          This script is used to generate the C code of the tests but it does not 
          build them.
        - clean_all.sh
          This script removes all executables, generated C files, object files, 
          and temporaries from cpp-t2c and its subdirs.
        - tools/

In the source distribution the "cpp-t2c/*-t2c" directories contain the following:
    - a config file (*.cfg) for the T2C code generator;
    - gen_tests - test generation script;
    - clean - clean up script;
    - src/ - sources of the tests (in T2C format) for the respective library.
    - include/  (if present) - header files for the tests;
    - reqs/      - requirement catalogue;
    - testdata/ (if present) - data used for testing (along with the sources 
      and makefiles if the data needs to be built).   


Building the Test Suite from Source
-----------------------------------------------------
1. Unpack the source tarball to some directory, say, /tmp/tests.
Change current directory to /tmp/tests/lsb-test-cpp-t2c-X.Y 
(X.Y is a version number).

2. Build T2C code generator first by executing t2c_framework/t2c/build.sh. Then
set T2C_ROOT environment variable so that it contained the path to the main
directory of the T2C Framework:
    export T2C_ROOT=/tmp/tests/lsb-test-cpp-t2c-X.Y/t2c_framework/
This variable will be used during the build process of the tests.

3. Change current directory to cpp-t2c and execute the "build_all.sh" script
to prepare and build the tests:
    cd /tmp/tests/lsb-test-cpp-t2c-X.Y/cpp-t2c
    ./build_all.sh

During the build, the T2C code generator is invoked to create C++ code from t2c 
files. Generated C++-files can be found in subdirectories of 
"libstdcxx-t2c/tests/".

These C++ sources are then compiled and linked using the makefiles that are 
also generated by T2C.

The TET scenario file (tet_scen) is placed to the main suite directory 
("cpp-t2c").

4. Install custom locales required, for example, by the tests for "Localization Library" from libstdcxx. You may need superuser privilleges to do this. 
To install the locales, execute the following script:
	/tmp/tests/lsb-test-cpp-t2c-X.Y/cpp-t2c/locales/install_locale.sh

If you later want to uninstall these custom locales, you can do it this way:
	/tmp/tests/lsb-test-cpp-t2c-X.Y/cpp-t2c/locales/uninstall_locale.sh
This may not work on the systems that do not use locale archives.


Running the Tests
-----------------------------------------------------

To run all the tests, execute the "run_tests.sh" script from the directory 
where you have the cpp-t2c suite installed (usually /opt/lsb/test/cpp-t2c)
directory. 

The tests should be run as an "ordinary" user rather than root. Some of these 
may fail if executed with root privileges.

Viewing the Test Results
-----------------------------------------------------
The test results (journals) can be found in the TET journal - 
cpp-t2c/results/XXXXe/journal, where XXXX is a number. The latest results 
correspond to the highest XXXX number.

You can use the "vres" script included in the "contrib" part of TET distribution 
to display a summary of the results.

Example:
$TET_ROOT/contrib/usltools/vres  cpp-t2c/results/0001e/journal


Bug Reporting
-----------------------------------------------------
If you have found a bug, please send us an e-mail to <linux@ispras.ru>. 


-----------------------------------------------------
Copyright (C) 2007-2008 The Linux Foundation.
The T2C system and the tests were developed by ISPRAS <linux@ispras.ru> 
for The Linux Foundation.
