From 16cb1bf22f72db0ac47080e364ffbc79a3ec174a Mon Sep 17 00:00:00 2001 From: rpj Date: Mon, 14 Aug 2000 03:43:09 +0000 Subject: 2000-08-13 Ross Johnson * errno.c: Add _MD precompile condition; thus far had no effect when using /MD compile option but I thnk it should be there. * exit.c: Add __cplusplus to various #if lines; was compiling SEH code even when VC++ had C++ compile options. * private.c: ditto. * create.c (pthread_create): Add PT_STDCALL macro to function pointer arg in _beginthread(). * pthread.h: PT_STDCALL really does need to be defined in both this and impliment.h; don't set it to __cdecl - this macro is only used to extend function pointer casting for functions that will be passed as parameters. (~PThreadCleanup): add cast and group expression. (_errno): Add _MD compile conditional. (PtW32NoCatchWarn): Change pragma message. * implement.h: Move and change PT_STDCALL define. * need_errno.h: Add _MD to compilation conditional. * GNUmakefile: Substantial rewrite for new naming convention; set for nil optimisation (turn it up when we have a working library build; add target "fake.a" to build a libpthreadw32.a from the VC++ built DLL pthreadVCE.dll. * pthread.def (LIBRARY): Don't specify in the .def file - it is specified on the linker command line since we now use the same .def file for variously named .dlls. * Makefile: Substantial rewrite for new naming convention; default nmake target only issues a help message; run nmake with specific target corresponding to the EH scheme being used. * README: Update information; add naming convention explanation. * ANNOUNCE: Update information. 2000-08-12 Ross Johnson * pthread.h: Add compile-time message when using MSC_VER compiler and C++ EH to warn application programmers to use PtW32Catch instead of catch(...) if they want cancelation and pthread_exit to work. * implement.h: Remove #include ; we use our own local semaphore.h. tests/ChangeLog: 2000-08-13 Ross Johnson * condvar3.c: Minor change to eliminate compiler warning. * condvar4.c: ditto. * condvar5.c: ditto. * condvar6.c: ditto. * condvar7.c: ditto. * condvar8.c: ditto. * condvar9.c: ditto. * exit1.c: Function needed return statement. * cleanup1.c: Remove unnecessary printf arg. * cleanup2.c: Fix cast. * rwlock6.c: Fix casts. * exception1.c (PtW32CatchAll): Had the wrong name; fix casts. * cancel3.c: Remove unused waitLock variable. * GNUmakefile: Change library/dll naming; add new tests; general minor changes. * Makefile: Change library/dll naming; add targets for testing each of the two VC++ EH scheme versions; default target now issues help message; compile warnings now interpreted as errors to stop the make; add new tests; restructure to remove prerequisites needed otherwise. * README: Updated. --- README | 191 ++++++++++++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 143 insertions(+), 48 deletions(-) (limited to 'README') diff --git a/README b/README index af3e421..76c4dd6 100644 --- a/README +++ b/README @@ -5,27 +5,48 @@ Pthreads-win32 is free software, distributed under the GNU Library General Public License (LGPL). See the file 'COPYING.LIB' for terms and conditions. -Mailing list ------------- -There is a mailing list for discussing pthreads on Win32. To join, send email -to: +What is it? +----------- - pthreads-win32-subscribe@sources.redhat.com +Pthreads-win32 is an Open Source Software (OSS) implementation of the +Threads component of the POSIX 1003.1c 1995 Standard for Microsoft's +Win32 environment. Some functions from POSIX 1003.1b are also +supported including semaphores. Other related functions include +the set of read-write lock functions. -Unsubscribe by sending mail to: +See the file "ANNOUNCE" for more information including standards +conformance details and list of supported routines. - pthreads-win32-unsubscribe@sources.redhat.com +Library naming +-------------- -Acknowledgements ----------------- +Because the library is being built using various exception +handling schemes and compilers - and because the library +will not work reliably if these are mixed in an application, +each different version of the library has it's own name. -Pthreads-win32 is based substantially on a Win32 Pthreads implementation -contributed by John E. Bossom . Many others -have contributed important new code and bug fixes. +In general: + pthread[VG][SC]E.dll + pthread[VG][SC]E.lib -See the 'CONTRIBUTORS' file for the list of contributors. +where: + [VG] indicates the compiler + V - MS VC++ + G - GNU G++ + + [SC] indicates the exception handling scheme + S - Structured EH + C - C++ EH + +For example: + pthreadVSE.dll (VC++/SEH) + pthreadGCE.dll (G++/C++ EH) + +The GNU library archive file name has changed to: + + libpthreadw32.a (the "32" is now "w32") Known bugs in this snapshot @@ -37,16 +58,15 @@ page access) exception. The fault appears to be in the assembler code emmitted by the compiler [to handle exception contexts] at the end of the try block in _pthread_threadStart(). -2. There are problems with using the libpthread32.a file derived -from the VC++ SEH version of pthread.dll. You may have to wait until -bug(1.) is fixed. +2. There are problems using the libpthreadw32.a stub archive derived +from either of pthreadVSE.dll or pthreadVCE.dll. The cleanup1.c test +fails. + -3. I have not been able to build with VC++ using C++ EH. This is a -maintainer problem who doesn't know how to do it. Consequently -there may also be basic parser errors and warnings to be cleaned -up in the code. +Caveats +------- -4. Due to what is believed to be C++ compliance error in VC++, +1. Due to what is believed to be C++ compliance error in VC++, if your application contains catch(...) blocks in your POSIX threads then you will need to replace the "catch(...)" with the macro "PtW32Catch", eg. @@ -65,59 +85,111 @@ Otherwise neither pthreads cancelation nor pthread_exit() will work reliably. +Building under VC++ using either C++ EH or Structured EH +-------------------------------------------------------- + +From the source directory run one of the following: + +nmake clean VCE (builds the VC++ C++ EH version pthreadVCE.dll) + +or: + +nmake clean VSE (builds the VC++ structured EH version pthreadVSE.dll) + +You can run the testsuite by changing to the "tests" directory and +running the target corresponding to the DLL version you built: + +nmake clean VCE + +or: + +nmake clean VSE + + Building under Mingw32 ---------------------- pthread.dll can be built with the current development version of mingw32. Run "make" in the soruce directory (uses GNUmakefile). This builds -pthread.dll and libpthread32.a. +pthreadGCE.dll and libpthreadw32.a. + +To generate the libpthreadw32.a file from pthreadVCE.dll rather than +building the library with G++, run "make fake.a". (You must have +pthreadVCE.dll already built - see above.) +Please note that VC++ and GNU exception handling is implemented +completely differently and so automatic cleanup of objects and +the propagation of exceptions themselves between the two schemes is not +going to happen. You can run the testsuite by changing to the "tests" directory and running "make clean" and then "make". See the "Known bugs" section above. -Building under VC++ using SEH ------------------------------ +Building the library under Cygwin +--------------------------------- -From the source directory run "nmake". This builds pthread.dll and -pthread.lib. - -You can run the testsuite by changing to the "tests" directory and -running "nmake clean" and then "nmake". +Not tested by me although I think some people have done this. +Not sure how successfully though. +Cygwin is implementing it's own POSIX threads routines and these +will be the ones to use if you develop using Cygwin. -Why you cannot build the library with Cygwin yet ------------------------------------------------- -The DLL pthread.dll still cannot be built using g++ due to non thread-safe -exception handling in g++. Thanks to Kevin Ruland for researching this -one. See the FAQ Question 2 for more information. +Ready to run binaries +--------------------- -However, you can use the export library libpthread32.a built under -Mingw32 (not tested under Cygwin) together with the pthread.dll built -with MSVC. Thanks to Anders Norlander for pointing this out. - -For convenience, the following pre-built files can be downloaded from -the FTP site (see under "Availability" below): +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 - pthread.dll - built with MSVC cl compiler - pthread.lib - built with MSVC cl compiler - libpthread32.a - built with Mingw32 (use with MSVC pthread.dll) + pthread.def + pthreadVCE.dll - built with MSVC++ compiler using C++ EH + pthreadVCE.lib + pthreadVSE.dll - built with MSVC++ compiler using SEH + pthreadVSE.lib + pthreadGCE.dll - currently a copy of pthreadVCE.dll + libpthreadw32.a - derived from pthreadGCE.dll + + +Building applications with the library +-------------------------------------- + +Use the appropriate DLL and LIB files to match the exception handing +that you use in your application, or specifically, in your POSIX +threads. Don't mix them or neither thread cancelation nor +pthread_exit() will work reliably if at all. + + +Building applications with GNU compilers +---------------------------------------- + +[Please see the section on Known Bugs above and the section +dealing with building the library with Mingw32 before +you build applications using the GNU compilers. Please also +note that the pre-built pthreadGCE.dll is currently only +a copy of the dll built by MSVC++. Note that VC++ and +GNU exception handling is implemented completely differently +and so automatic cleanup of objects and the propagation of +exceptions themselves between the two schemes is not +going to happen. You'll need to wait for the version of +pthreadGCE.dll built be G++ itself which still has problems.] + +Use gcc-2.95.2 or later. -With these files in the same directory as your application myapp.c, -you could compile, link and run myapp.c under Mingw32 as follows: +With pthreadGCE.dll and libpthreadw32.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. -lpthread32 + gcc -x c++ -o myapp.exe myapp.c -I. -L. -lpthreadw32 myapp -Or put pthread.dll in an appropriate directory in your PATH, +Or put pthreadGCE.dll in an appropriate directory in your PATH, put libpthread32.a in MINGW_ROOT\i386-mingw32\lib, and put pthread.h in MINGW_ROOT\i386-mingw32\include, then use: - gcc -o myapp.exe myapp.c -lpthread32 + gcc -x c++ -o myapp.exe myapp.c -lpthreadw32 myapp @@ -137,6 +209,29 @@ 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: + + pthreads-win32-subscribe@sources.redhat.com + +Unsubscribe by sending mail to: + + pthreads-win32-unsubscribe@sources.redhat.com + + +Acknowledgements +---------------- + +Pthreads-win32 is based substantially on a Win32 Pthreads implementation +contributed by John E. Bossom . Many others +have contributed important new code and bug fixes. + +See the 'CONTRIBUTORS' file for the list of contributors. + ---- Ross Johnson -- cgit v1.2.3