Running test cases in this directory
------------------------------------

These make scripts expect to be able to copy the dll, library
and header files from this directory's parent directory,
which should be the pthreads-win32 source directory.

MS VC nmake
-------------

Run the target corresponding to the DLL version being tested:

nmake clean VC

or:

nmake clean VS


GNU GCC make
------------

Run "make clean" and then "make". See the "Known bugs" section
in ..\README.


Writing Test Cases
------------------

Tests written in this test suite should behave in the following manner:

	* If a test fails, leave main() with a result of 1.

	* If a test succeeds, leave main() with a result of 0.

	* No diagnostic output should appear when the test is succeeding.
	  Diagnostic output may be emitted if something in the test
	  fails, to help determine the cause of the test failure.

Notes:
------

Many test cases use knowledge of implementation internals which are supposed
to be opaque to portable applications.

------------
Benchmarking
------------
There is a set a benchmarking programs in the
"tests" directory. These should be runnable using the
following command-lines corresponding to each of the possible
library builds:

MSVC:
nmake clean VC-bench
nmake clean VCE-bench
nmake clean VSE-bench

Mingw32:
make clean GC-bench
make clean GCE-bench

UWIN:
The benchtests are run as part of the testsuite.


Mutex benchtests
----------------

benchtest1 - Lock plus unlock on an unlocked mutex.
benchtest2 - Lock plus unlock on a locked mutex.
benchtest3 - Trylock on a locked mutex.
benchtest4 - Trylock plus unlock on an unlocked mutex.


Each test times up to three alternate synchronisation
implementations as a reference, and then times each of
the four mutex types provided by the library. Each is
described below:

Simple Critical Section
- uses a simple Win32 critical section. There is no
additional overhead for this case as there is in the
remaining cases.

POSIX mutex implemented using a Critical Section
- The old implementation which uses runtime adaptation
depending on the Windows variant being run on. When
the pthreads DLL was run on WinNT or higher then
POSIX mutexes would use Win32 Critical Sections.

POSIX mutex implemented using a Win32 Mutex
- The old implementation which uses runtime adaptation
depending on the Windows variant being run on. When
the pthreads DLL was run on Win9x then POSIX mutexes
would use Win32 Mutexes (because TryEnterCriticalSection
is not implemented on Win9x).

PTHREAD_MUTEX_DEFAULT
PTHREAD_MUTEX_NORMAL
PTHREAD_MUTEX_ERRORCHECK
PTHREAD_MUTEX_RECURSIVE
- The current implementation supports these mutex types.
The underlying basis of POSIX mutexes is now the same
irrespective of the Windows variant, and should therefore
have consistent performance.


Semaphore benchtests
--------------------

benchtest5 - Timing for various uncontended cases.


In all benchtests, the operation is repeated a large
number of times and an average is calculated. Loop
overhead is measured and subtracted from all test times.

-------------------------------------
Using the test suite for winpthreads
-------------------------------------

This test suite is originally designed for testing compliance: it just says when the tests pass without any further information.
Because this is inconvenient for work in progress, the behaviour has been modified to show more information for debugging while keeping the changes minimal
(for syncing purposes)

Procedure:
----------

1. Enter the winpthreads dir:
   $ cd winpthreads
2. Build the winpthreads lib
   $ make
3. Make a copy for the test-suite:
   $ cp libpthread.a libpthreadGC2.a
4. Enter the test-suite dir:
   $ cd tests
5. (optional) Clean:
   $ make clean
6. Build the suite. This will also run the tests. A few might crash so you have to click a dialog away.
   The tool "runall.exe" will also be built.
   $ make GC-static
   To log both the compile results and the asserts:
   $ make GC-static 2> compile-errors.log
7. Now you have a bunch of .exe and maybe some .pass files. Remove the .pass files. They don't contain much useful yet.
   $ rm *.pass
8. Re-run the tests in debugging mode. Again some crash dialogs maybe.
   runall will skip files with already an .pass or .fail output.
   $ runall .
9. Now 3 types of files will be generated for each source (.c) file (runall excludes itself):
   The stderr output with the asserts will be logged to corresponding .fail
   and .pass files.
   - .pass : the test has passed (exited with 0).
   - .fail : the test has failed (exited with != 0).
   - .x : no .exe found. Probably the compile has failed.
   Note that when a test crashes, a .fail output will be generated, even without failed asserts.

Module testing:
---------------

Sometimes you want to test, debug and modify a single test, say once2.c:
1. Copy test.h to the debug test dir:
   $ cp test.h ../test
2. Copy the file to the debug test dir:
   $ cp once2.c ../test
3. Enter the debug test dir:
   $ cd ../test
4. Build and run it:
   $ make once2.exe
   $ ./once2.exe

Benchtests:
-----------

These work, but you have to compile them by hand like this:
$ make benchlib.o
$ make benchtest1.exe
$ make benchtest2.exe
$ make benchtest3.exe
$ make benchtest4.exe
$ make benchtest5.exe