Various new tidies.

git-svn-id: svn://vcs.exim.org/pcre/code/trunk@131 2f5784b3-3f2a-0410-8824-cb99058d5e15

1 files changed, 72 insertions, 64 deletions

diff --git a/NON-UNIX-USE b/NON-UNIX-USE
index a20d85b..5144751 100644
--- a/NON-UNIX-USE
+++ b/NON-UNIX-USE
@@ -1,6 +1,19 @@
 Compiling PCRE on non-Unix systems
 ----------------------------------
 
+This document contains the following sections:
+
+  General
+  Generic instructions for the PCRE C library 
+  The C++ wrapper functions
+  Building for virtual Pascal
+  Comments about Win32 builds    
+  Building under Windows with BCC5.5
+  Building PCRE on OpenVMS 
+
+
+GENERAL
+
 I (Philip Hazel) have no knowledge of Windows or VMS sytems and how their
 libraries work. The items in the PCRE distribution and Makefile that relate to
 anything other than Unix-like systems are untested by me.
@@ -17,7 +30,7 @@ should compile successfully on any system that has a Standard C compiler and
 library. The C++ wrapper functions are a separate issue (see below).
 
 
-GENERIC INSTRUCTIONS FOR THE C LIBRARY
+GENERIC INSTRUCTIONS FOR THE PCRE C LIBRARY
 
 The following are generic comments about building the PCRE C library "by hand".
 
@@ -105,90 +118,85 @@ BUILDING FOR VIRTUAL PASCAL
 A script for building PCRE using Borland's C++ compiler for use with VPASCAL
 was contributed by Alexander Tokarev. Stefan Weber updated the script and added
 additional files. The following files in the distribution are for building PCRE
-for use with VP/Borland: makevp-compile.txt, makevp-linklib.txt, makevp.bat,
-pcregexp.pas.
+for use with VP/Borland: makevp-c.txt, makevp-l.txt, makevp.bat, pcregexp.pas.
 
 
-BUILDING UNDER WINDOWS WITH BCC5.5
+COMMENTS ABOUT WIN32 BUILDS
 
-Michael Roy sent these comments about building PCRE under Windows with BCC5.5:
+There are two ways of building PCRE on Windows systems: using MinGW or using
+Cygwin. These are not at all the same thing, and are completely different from
+each other. 
 
-  Some of the core BCC libraries have a version of PCRE from 1998 built in,
-  which can lead to pcre_exec() giving an erroneous PCRE_ERROR_NULL from a
-  version mismatch. I'm including an easy workaround below, if you'd like to
-  include it in the non-unix instructions:
+The MinGW home page (http://www.mingw.org/) says this:
 
-  When linking a project with BCC5.5, pcre.lib must be included before any of
-  the libraries cw32.lib, cw32i.lib, cw32mt.lib, and cw32mti.lib on the command
-  line.
+  MinGW: A collection of freely available and freely distributable Windows
+  specific header files and import libraries combined with GNU toolsets that
+  allow one to produce native Windows programs that do not rely on any
+  3rd-party C runtime DLLs.
 
+The Cygwin home page (http://www.cygwin.com/) says this:
 
-OUT-OF-DATE COMMENTS ABOUT WIN32 BUILDS
+  Cygwin is a Linux-like environment for Windows. It consists of two parts: 
+   
+  . A DLL (cygwin1.dll) which acts as a Linux API emulation layer providing 
+    substantial Linux API functionality
+     
+  . A collection of tools which provide Linux look and feel.
 
-[These comments need looking at by someone who knows about Windows.]
+  The Cygwin DLL currently works with all recent, commercially released x86 32 
+  bit and 64 bit versions of Windows, with the exception of Windows CE.
 
-Some help in building a Win32 DLL of PCRE in GnuWin32 environments was
-contributed by Paul Sokolovsky. These environments are Mingw32
-(http://www.xraylith.wisc.edu/~khan/software/gnu-win32/) and CygWin
-(http://sourceware.cygnus.com/cygwin/). Paul comments:
+On both MinGW and Cygwin, PCRE should build correctly using:
 
-  For CygWin, set CFLAGS=-mno-cygwin, and do 'make dll'. You'll get
-  pcre.dll (containing pcreposix also), libpcre.dll.a, and dynamically
-  linked pgrep and pcretest. If you have /bin/sh, run RunTest (three
-  main test go ok, locale not supported).
+  ./configure && make && make install 
+  
+However, if you want to statically link your program against the .a file, you
+must define PCRE_STATIC before including pcre.h, otherwise the pcre_malloc()
+and pcre_free() exported functions will be declared __declspec(dllimport), with
+unwanted results.
 
-Changes to do MinGW with autoconf 2.50 were supplied by Fred Cox
-<sailorFred@yahoo.com>, who comments as follows:
+Using Cygwin's compiler generates libraries and executables that depend on
+cygwin1.dll. If a library that is generated this way is distributed,
+cygwin1.dll has to be distributed as well. Since cygwin1.dll is under the GPL
+licence, this forces not only PCRE to be under the GPL, but also the entire
+application. A distributor who wants to keep their own code proprietary must
+purchase an appropriate Cygwin licence.
 
-  If you are using the PCRE DLL, the normal Unix style configure && make &&
-  make check && make install should just work[*]. If you want to statically
-  link against the .a file, you must define PCRE_STATIC before including
-  pcre.h, otherwise the pcre_malloc and pcre_free exported functions will be
-  declared __declspec(dllimport), with hilarious results.  See the configure.in
-  and pcretest.c for how it is done for the static test.
+MinGW has no such restrictions. The MinGW compiler generates a library or
+executable that can run standalone on Windows without any third party dll or
+licensing issues.
 
-  Also, there will only be a libpcre.la, not a libpcreposix.la, as you
-  would expect from the Unix version. The single DLL includes the pcreposix
-  interface.
+But there is more complication:
 
-[*] But note that the supplied test files are in Unix format, with just LF
-characters as line terminators. You will have to edit them to change to CR LF
-terminators.
+If a Cygwin user uses the -mno-cygwin Cygwin gcc flag, what that really does is
+to tell Cygwin's gcc to use the MinGW gcc. Cygwin's gcc is only acting as a
+front end to MinGW's gcc (if you install Cygwin's gcc, you get both Cygwin's
+gcc and MinGW's gcc). So, a user can:
 
-These are some further comments about Win32 builds from Mark Evans. They
-were contributed before Fred Cox's changes were made, so it is possible that
-they may no longer be relevant.
+. Build native binaries by using MinGW or by getting Cygwin and using 
+  -mno-cygwin.
 
-"The documentation for Win32 builds is a bit shy.  Under MSVC6 I
-followed their instructions to the letter, but there were still
-some things missing.
+. Build binaries that depend on cygwin1.dll by using Cygwin with the normal 
+  compiler flags.
 
-(1) Must #define STATIC for entire project if linking statically.
-    (I see no reason to use DLLs for code this compact.)  This of
-    course is a project setting in MSVC under Preprocessor.
+The test files that are supplied with PCRE are in Unix format, with LF 
+characters as line terminators. It may be necessary to change the line 
+terminators in order to get some of the tests to work. We hope to improves 
+things in this area in future.
 
-(2) Missing some #ifdefs relating to the function pointers
-    pcre_malloc and pcre_free.  See my solution below.  (The stubs
-    may not be mandatory but they made me feel better.)"
 
-=========================
-#ifdef _WIN32
-#include <malloc.h>
-
-void* malloc_stub(size_t N)
-{ return malloc(N); }
-void free_stub(void* p)
-{ free(p); }
-void *(*pcre_malloc)(size_t) = &malloc_stub;
-void  (*pcre_free)(void *) = &free_stub;
+BUILDING UNDER WINDOWS WITH BCC5.5
 
-#else
+Michael Roy sent these comments about building PCRE under Windows with BCC5.5:
 
-void *(*pcre_malloc)(size_t) = malloc;
-void  (*pcre_free)(void *) = free;
+  Some of the core BCC libraries have a version of PCRE from 1998 built in,
+  which can lead to pcre_exec() giving an erroneous PCRE_ERROR_NULL from a
+  version mismatch. I'm including an easy workaround below, if you'd like to
+  include it in the non-unix instructions:
 
-#endif
-=========================
+  When linking a project with BCC5.5, pcre.lib must be included before any of
+  the libraries cw32.lib, cw32i.lib, cw32mt.lib, and cw32mti.lib on the command
+  line.
 
 
 BUILDING PCRE ON OPENVMS
@@ -255,5 +263,5 @@ $!   Locale could not be set to fr
 $!
 =========================
 
-Last Updated: 20 March 2007
+Last Updated: 26 March 2007
 ****