#
# This file and its contents are supplied under the terms of the
# Common Development and Distribution License ("CDDL"), version 1.0.
# You may only use this file in accordance with the terms of version
# 1.0 of the CDDL.
#
# A full copy of the text of the CDDL should have accompanied this
# source.  A copy of the CDDL is also available via the Internet at
# http://www.illumos.org/license/CDDL.
#

#
# Copyright 2014 Garrett D'Amore <garrett@damore.org>
# Copyright (c) 2012 by Delphix. All rights reserved.
#

Header Test Suite README

1. What this Header Test Suite tests
2. Building and installing this Header Test Suite
3. Running this Header Test Suite
4. Test results
5. Package layout

--------------------------------------------------------------------------------

1. What this Header Test Suite tests

This Header Test Suite is for testing standards compliance of various
system header files.

2. Building and installing this Header Test Suite

This Test Suite runs under the testrunner framework (which can be installed
as pkg:/system/test/testrunner). To build both this Header Test Suite and the
testrunner without running a full nightly:

	build_machine$ bldenv [-d] <your_env_file>
	build_machine$ cd $SRC/test
	build_machine$ dmake install
	build_machine$ cd $SRC/pkg
	build_machine$ dmake install

Then set the publisher on the test machine to point to your repository and
install the Utils Header Test Suite.

	test_machine# pkg install pkg:/system/test/headertest

Note, the framework will be installed automatically, as this test suite
depends on it.

C and C++ compilers are also required on the test system.

3. Running this Header Test Suite

The pre-requisites for running the this Header Test Suite are:
	- GCC or Clang C and C++ compilers installed.

Once the pre-requisites are satisfied, simply run the headertest script:

	test_machine$ /opt/header-tests/bin/headertest

The number of parallel compile jobs defaults to 4. This can be overridden
by setting the SYMBOL_TEST_JOBS environment variable, or per-invocation
with the -j option to the symbol_test program.

4. Test results

While the Header Test Suite is running, one informational line is printed at
the end of each test, and a results summary is printed at the end of the run.
The results summary includes the location of the complete logs, which is of the
form /var/tmp/test_results/<ISO 8601 date>.

5. Package layout

The installed package under /opt/header-tests contains:

  bin/         - test runner script
  doc/         - this file
  runfiles/    - testrunner runfile

  cfg/         - compilation environment definitions and test configs
    c-symbols-env.cfg
    cxx-symbols-env.cfg
    c-symbols/   - test config files for C symbol tests
    cxx-symbols/ - test config files for C++ symbol tests

  tests/
    common/    - shared test programs
    c-symbols/ - per-header test scripts and setup
    cxx-symbols/ - per-header test scripts and setup

You can run all tests via: bin/headertest
or run individual tests like: tests/c-symbols/math_h