readme

POSIX Multithraed library for windows

build your application using the same __CLEANUP_* define as was
used for the version of the library that you link with, so that the
correct parts of pthread.h are included. That is, the possible
defines require the following library versions:

	__CLEANUP_SEH	pthreadVSE.dll
	__CLEANUP_CXX	pthreadVCE.dll or pthreadGCE.dll
	__CLEANUP_C	pthreadVC.dll or pthreadGC.dll

It is recommended that you let pthread.h use it's default __CLEANUP_C
for both library and application builds. That is, don't define any of
the above, and then link with pthreadVC.lib (MSVC or MSVC++) and
libpthreadGC.a (MinGW GCC or G++). The reason is explained below, but
another reason is that the prebuilt pthreadVCE.dll is currently broken.
Versions built with MSVC++ later than version 6 may not be broken, but I
can't verify this yet.

WHY ARE WE MAKING THE DEFAULT STYLE LESS EXCEPTION-FRIENDLY?
Because no commercial Unix POSIX threads implementation allows you to
choose to have stack unwinding. Therefore, providing it in pthread-win32
as a default is dangerous. We still provide the choice but unless
you consciously choose to do otherwise, your pthreads applications will
now run or crash in similar ways irrespective of the pthreads platform
you use. Or at least this is the hope.


Building under VC++ using C++ EH, Structured EH, or just C
----------------------------------------------------------

From the source directory run nmake without any arguments to list
help information. E.g.

$ nmake

Microsoft (R) Program Maintenance Utility   Version 6.00.8168.0
Copyright (C) Microsoft Corp 1988-1998. All rights reserved.

Run one of the following command lines:
nmake clean VCE (to build the MSVC dll with C++ exception handling)
nmake clean VSE (to build the MSVC dll with structured exception handling)
nmake clean VC (to build the MSVC dll with C cleanup code)
nmake clean VCE-inlined (to build the MSVC inlined dll with C++ exception handling)
nmake clean VSE-inlined (to build the MSVC inlined dll with structured exception handling)
nmake clean VC-inlined (to build the MSVC inlined dll with C cleanup code)
nmake clean VC-static (to build the MSVC static lib with C cleanup code)
nmake clean VCE-debug (to build the debug MSVC dll with C++ exception handling)
nmake clean VSE-debug (to build the debug MSVC dll with structured exception handling)
nmake clean VC-debug (to build the debug MSVC dll with C cleanup code)
nmake clean VCE-inlined-debug (to build the debug MSVC inlined dll with C++ exception handling)
nmake clean VSE-inlined-debug (to build the debug MSVC inlined dll with structured exception handling)
nmake clean VC-inlined-debug (to build the debug MSVC inlined dll with C cleanup code)
nmake clean VC-static-debug (to build the debug MSVC static lib with C cleanup code)


The pre-built dlls are normally built using the *-inlined targets.

You can run the testsuite by changing to the "tests" directory and
running nmake. E.g.:

$ cd tests
$ nmake

Microsoft (R) Program Maintenance Utility   Version 6.00.8168.0
Copyright (C) Microsoft Corp 1988-1998. All rights reserved.

Run one of the following command lines:
nmake clean VC (to test using VC dll with VC (no EH) applications)
nmake clean VCX (to test using VC dll with VC++ (EH) applications)
nmake clean VCE (to test using the VCE dll with VC++ EH applications)
nmake clean VSE (to test using VSE dll with VC (SEH) applications)
nmake clean VC-bench (to benchtest using VC dll with C bench app)
nmake clean VCX-bench (to benchtest using VC dll with C++ bench app)
nmake clean VCE-bench (to benchtest using VCE dll with C++ bench app)
nmake clean VSE-bench (to benchtest using VSE dll with SEH bench app)
nmake clean VC-static (to test using VC static lib with VC (no EH) applications)


Building under Mingw32
----------------------

The dll can be built easily with recent versions of Mingw32.
(The distributed versions are built using Mingw32 and MsysDTK
from www.mingw32.org.)

From the source directory, run make for help information. E.g.:

$ make
Run one of the following command lines:
make clean GC            (to build the GNU C dll with C cleanup code)
make clean GCE           (to build the GNU C dll with C++ exception handling)
make clean GC-inlined    (to build the GNU C inlined dll with C cleanup code)
make clean GCE-inlined   (to build the GNU C inlined dll with C++ exception handling)
make clean GC-static     (to build the GNU C inlined static lib with C cleanup code)
make clean GC-debug      (to build the GNU C debug dll with C cleanup code)
make clean GCE-debug     (to build the GNU C debug dll with C++ exception handling)
make clean GC-inlined-debug    (to build the GNU C inlined debug dll with C cleanup code)
make clean GCE-inlined-debug   (to build the GNU C inlined debug dll with C++ exception handling)
make clean GC-static-debug     (to build the GNU C inlined static debug lib with C cleanup code)


The pre-built dlls are normally built using the *-inlined targets.

You can run the testsuite by changing to the "tests" directory and
running make for help information. E.g.:

$ cd tests
$ make
Run one of the following command lines:
make clean GC    (to test using GC dll with C (no EH) applications)
make clean GCX   (to test using GC dll with C++ (EH) applications)
make clean GCE   (to test using GCE dll with C++ (EH) applications)
make clean GC-bench       (to benchtest using GNU C dll with C cleanup code)
make clean GCE-bench   (to benchtest using GNU C dll with C++ exception handling)
make clean GC-static   (to test using GC static lib with C (no EH) applications)


Building under Linux using the Mingw32 cross development tools
--------------------------------------------------------------

You can build the library without leaving Linux by using the Mingw32 cross
development toolchain. See http://www.libsdl.org/extras/win32/cross/ for
tools and info. The GNUmakefile contains some support for this, for example:

make CROSS=i386-mingw32msvc- clean GC-inlined

will build pthreadGCn.dll and libpthreadGCn.a (n=version#), provided your
cross-tools/bin directory is in your PATH (or use the cross-make.sh script
at the URL above).


Building the library as a statically linkable library
-----------------------------------------------------

General: PTW32_STATIC_LIB must be defined for both the library build and the
application build. The makefiles supplied and used by the following 'make'
command lines will define this for you.

MSVC (creates pthreadVCn.lib as a static link lib):

nmake clean VC-static


MinGW32 (creates libpthreadGCn.a as a static link lib):

make clean GC-static


Define PTW32_STATIC_LIB when building your application. Also, your
application must call a two non-portable routines to initialise the
some state on startup and cleanup before exit. One other routine needs
to be called to cleanup after any Win32 threads have called POSIX API
routines. See README.NONPORTABLE or the html reference manual pages for
details on these routines:

BOOL pthread_win32_process_attach_np (void);
BOOL pthread_win32_process_detach_np (void);
BOOL pthread_win32_thread_attach_np (void); // Currently a no-op
BOOL pthread_win32_thread_detach_np (void);


The tests makefiles have the same targets but only check that the
static library is statically linkable. They don't run the full
testsuite. To run the full testsuite, build the dlls and run the
dll test targets.


Building the library under Cygwin
---------------------------------

Cygwin is implementing it's own POSIX threads routines and these
will be the ones to use if you develop using Cygwin.


Ready to run binaries
---------------------

For convenience, the following ready-to-run files can be downloaded
from the FTP site (see under "Availability" below):

	pthread.h
	semaphore.h
	sched.h
	pthreadVC.dll	- built with MSVC compiler using C setjmp/longjmp
	pthreadVC.lib
	pthreadVCE.dll	- built with MSVC++ compiler using C++ EH
	pthreadVCE.lib
	pthreadVSE.dll	- built with MSVC compiler using SEH
	pthreadVSE.lib
	pthreadGC.dll	- built with Mingw32 GCC
	libpthreadGC.a	- derived from pthreadGC.dll
	pthreadGCE.dll	- built with Mingw32 G++
	libpthreadGCE.a	- derived from pthreadGCE.dll

As of August 2003 pthreads-win32 pthreadG* versions are built and tested
using the MinGW + MsysDTK environment current as of that date or later.
The following file MAY be needed for older MinGW environments.

	gcc.dll 	- needed to build and run applications that use
			  pthreadGCE.dll.


Building applications with GNU compilers
----------------------------------------

If you're using pthreadGC.dll:

With the three header files, pthreadGC.dll and libpthreadGC.a in the
same directory as your application myapp.c, you could compile, link
and run myapp.c under Mingw32 as follows:

	gcc -o myapp.exe myapp.c -I. -L. -lpthreadGC
	myapp

Or put pthreadGC.dll in an appropriate directory in your PATH,
put libpthreadGC.a in your system lib directory, and
put the three header files in your system include directory,
then use:

	gcc -o myapp.exe myapp.c -lpthreadGC
	myapp


If you're using pthreadGCE.dll:

With the three header files, pthreadGCE.dll, gcc.dll and libpthreadGCE.a
in the same directory as your application myapp.c, you could compile,
link and run myapp.c under Mingw32 as follows:

	gcc -x c++ -o myapp.exe myapp.c -I. -L. -lpthreadGCE
	myapp

Or put pthreadGCE.dll and gcc.dll in an appropriate directory in
your PATH, put libpthreadGCE.a in your system lib directory, and
put the three header files in your system include directory,
then use:

	gcc -x c++ -o myapp.exe myapp.c -lpthreadGCE
	myapp


Availability
------------

The complete source code in either unbundled, self-extracting
Zip file, or tar/gzipped format can be found at:

	ftp://sources.redhat.com/pub/pthreads-win32

The pre-built DLL, export libraries and matching pthread.h can
be found at:

	ftp://sources.redhat.com/pub/pthreads-win32/dll-latest

Home page:

	http://sources.redhat.com/pthreads-win32/


Mailing list
------------

There is a mailing list for discussing pthreads on Win32.
To join, send email to:

	[e-mail]

Unsubscribe by sending mail to:

	[e-mail]


Acknowledgements
----------------

See the ANNOUNCE file for acknowledgements.
See the 'CONTRIBUTORS' file for the list of contributors.

As much as possible, the ChangeLog file attributes
contributions and patches that have been incorporated
in the library to the individuals responsible.

Finally, thanks to all those who work on and contribute to the
POSIX and Single Unix Specification standards. The maturity of an
industry can be measured by it's open standards.

----
Ross Johnson
<[e-mail]>