/[pcre]/code/trunk/NON-UNIX-USE
ViewVC logotype

Diff of /code/trunk/NON-UNIX-USE

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 96 by nigel, Fri Mar 2 13:10:43 2007 UTC revision 200 by ph10, Wed Aug 1 09:10:40 2007 UTC
# Line 1  Line 1 
1  Compiling PCRE on non-Unix systems  Compiling PCRE on non-Unix systems
2  ----------------------------------  ----------------------------------
3    
4  See below for comments on Cygwin or MinGW and OpenVMS usage. I (Philip Hazel)  This document contains the following sections:
 have no knowledge of Windows or VMS sytems and how their libraries work. The  
 items in the PCRE Makefile that relate to anything other than Unix-like systems  
 have been contributed by PCRE users. There are some other comments and files in  
 the Contrib directory on the ftp site that you may find useful. See  
5    
6    ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/Contrib    General
7      Generic instructions for the PCRE C library
8      The C++ wrapper functions
9      Building for virtual Pascal
10      Stack size in Windows environments
11      Comments about Win32 builds
12      Building under Windows with BCC5.5
13      Building PCRE on OpenVMS
14    
15    
16    GENERAL
17    
18    I (Philip Hazel) have no experience of Windows or VMS sytems and how their
19    libraries work. The items in the PCRE distribution and Makefile that relate to
20    anything other than Unix-like systems are untested by me.
21    
22    There are some other comments and files in the Contrib directory on the ftp
23    site that you may find useful. See
24    
25  If you want to compile PCRE for a non-Unix system (or perhaps, more strictly,    ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/Contrib
 for a system that does not support "configure" and "make" files), note that  
 the basic PCRE library consists entirely of code written in Standard C, and so  
 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  
   
 The following are generic comments about building PCRE. The interspersed  
 indented commands are suggestions from Mark Tetrode as to which commands you  
 might use on a Windows system to build a static library.  
   
 (1) Copy or rename the file config.h.in as config.h, and change the macros that  
 define HAVE_STRERROR and HAVE_MEMMOVE to define them as 1 rather than 0.  
 Unfortunately, because of the way Unix autoconf works, the default setting has  
 to be 0. You may also want to make changes to other macros in config.h. In  
 particular, if you want to force a specific value for newline, you can define  
 the NEWLINE macro. The default is to use '\n', thereby using whatever value  
 your compiler gives to '\n'.  
   
   rem Mark Tetrode's commands  
   copy config.h.in config.h  
   rem Use write, because notepad cannot handle UNIX files. Change values.  
   write config.h  
   
 (2) Compile dftables.c as a stand-alone program, and then run it with  
 the single argument "pcre_chartables.c". This generates a set of standard  
 character tables and writes them to that file.  
   
   rem Mark Tetrode's commands  
   rem Compile & run  
   cl -DSUPPORT_UTF8 -DSUPPORT_UCP dftables.c  
   dftables.exe pcre_chartables.c  
   
 (3) Compile the following source files:  
   
   pcre_chartables.c  
   pcre_compile.c  
   pcre_config.c  
   pcre_dfa_exec.c  
   pcre_exec.c  
   pcre_fullinfo.c  
   pcre_get.c  
   pcre_globals.c  
   pcre_info.c  
   pcre_maketables.c  
   pcre_newline.c  
   pcre_ord2utf8.c  
   pcre_refcount.c  
   pcre_study.c  
   pcre_tables.c  
   pcre_try_flipped.c  
   pcre_ucp_searchfuncs.c  
   pcre_valid_utf8.c  
   pcre_version.c  
   pcre_xclass.c  
   
 and link them all together into an object library in whichever form your system  
 keeps such libraries. This is the pcre C library. If your system has static and  
 shared libraries, you may have to do this once for each type.  
   
   rem These comments are out-of-date, referring to a previous release which  
   rem had fewer source files. Replace with the file names from above.  
   rem Mark Tetrode's commands, for a static library  
   rem Compile & lib  
   cl -DSUPPORT_UTF8 -DSUPPORT_UCP -DPOSIX_MALLOC_THRESHOLD=10 /c maketables.c get.c study.c pcre.c  
   lib /OUT:pcre.lib maketables.obj get.obj study.obj pcre.obj  
   
 (4) Similarly, compile pcreposix.c and link it (on its own) as the pcreposix  
 library.  
   
   rem Mark Tetrode's commands, for a static library  
   rem Compile & lib  
   cl -DSUPPORT_UTF8 -DSUPPORT_UCP -DPOSIX_MALLOC_THRESHOLD=10 /c pcreposix.c  
   lib /OUT:pcreposix.lib pcreposix.obj  
   
 (5) Compile the test program pcretest.c. This needs the functions in the  
 pcre and pcreposix libraries when linking.  
   
   rem Mark Tetrode's commands  
   rem compile & link  
   cl /F0x400000 pcretest.c pcre.lib pcreposix.lib  
   
 (6) Run pcretest on the testinput files in the testdata directory, and check  
 that the output matches the corresponding testoutput files. Note that the  
 supplied files are in Unix format, with just LF characters as line terminators.  
 You may need to edit them to change this if your system uses a different  
 convention.  
   
   rem Mark Tetrode's commands  
   pcretest testdata\testinput1 testdata\myoutput1  
   windiff testdata\testoutput1 testdata\myoutput1  
   pcretest -i testdata\testinput2 testdata\myoutput2  
   windiff testdata\testoutput2 testdata\myoutput2  
   pcretest testdata\testinput3 testdata\myoutput3  
   windiff testdata\testoutput3 testdata\myoutput3  
   pcretest testdata\testinput4 testdata\myoutput4  
   windiff testdata\testoutput4 testdata\myoutput4  
   pcretest testdata\testinput5 testdata\myoutput5  
   windiff testdata\testoutput5 testdata\myoutput5  
   pcretest testdata\testinput6 testdata\myoutput6  
   windiff testdata\testoutput6 testdata\myoutput6  
26    
27  Note that there are now three more tests (7, 8, 9) that did not exist when Mark  If you want to compile PCRE for a non-Unix system (especially for a system that
28  wrote those comments. The test the new pcre_dfa_exec() function.  does not support "configure" and "make" files), note that the basic PCRE
29    library consists entirely of code written in Standard C, and so should compile
30    successfully on any system that has a Standard C compiler and library. The C++
31    wrapper functions are a separate issue (see below).
32    
33    The PCRE distribution contains some experimental support for "cmake", but this
34    is incomplete and not documented. However if you are a "cmake" user you might
35    like to try building with "cmake".
36    
37    
38    GENERIC INSTRUCTIONS FOR THE PCRE C LIBRARY
39    
40    The following are generic comments about building the PCRE C library "by hand".
41    
42     (1) Copy or rename the file config.h.generic as config.h, and edit the macro
43         settings that it contains to whatever is appropriate for your environment.
44         In particular, if you want to force a specific value for newline, you can
45         define the NEWLINE macro.
46    
47         An alternative approach is not to edit config.h, but to use -D on the
48         compiler command line to make any changes that you need.
49    
50         NOTE: There have been occasions when the way in which certain parameters
51         in config.h are used has changed between releases. (In the configure/make
52         world, this is handled automatically.) When upgrading to a new release,
53         you are strongly advised to review config.h.generic before re-using what
54         you had previously.
55    
56     (2) Copy or rename the file pcre.h.generic as pcre.h.
57    
58     (3) EITHER:
59           Copy or rename file pcre_chartables.c.dist as pcre_chartables.c.
60    
61         OR:
62           Compile dftables.c as a stand-alone program, and then run it with the
63           single argument "pcre_chartables.c". This generates a set of standard
64           character tables and writes them to that file. The tables are generated
65           using the default C locale for your system. If you want to use a locale
66           that is specified by LC_xxx environment variables, add the -L option to
67           the dftables command. You must use this method if you are building on
68           a system that uses EBCDIC code.
69    
70         The tables in pcre_chartables.c are defaults. The caller of PCRE can
71         specify alternative tables at run time.
72    
73     (4) Ensure that you have the following header files:
74    
75           pcre_internal.h
76           ucp.h
77           ucpinternal.h
78           ucptable.h
79    
80     (5) Also ensure that you have the following file, which is #included as source
81         when building a debugging version of PCRE and is also used by pcretest.
82    
83           pcre_printint.src
84    
85     (6) Compile the following source files:
86    
87           pcre_chartables.c
88           pcre_compile.c
89           pcre_config.c
90           pcre_dfa_exec.c
91           pcre_exec.c
92           pcre_fullinfo.c
93           pcre_get.c
94           pcre_globals.c
95           pcre_info.c
96           pcre_maketables.c
97           pcre_newline.c
98           pcre_ord2utf8.c
99           pcre_refcount.c
100           pcre_study.c
101           pcre_tables.c
102           pcre_try_flipped.c
103           pcre_ucp_searchfuncs.c
104           pcre_valid_utf8.c
105           pcre_version.c
106           pcre_xclass.c
107    
108         Make sure that you include -I. in the compiler command (or equivalent for
109         an unusual compiler) so that all included PCRE header files are first
110         sought in the current directory. Otherwise you run the risk of picking up
111         a previously-installed file from somewhere else.
112    
113     (7) Now link all the compiled code into an object library in whichever form
114         your system keeps such libraries. This is the basic PCRE C library. If
115         your system has static and shared libraries, you may have to do this once
116         for each type.
117    
118     (8) Similarly, compile pcreposix.c and link the result (on its own) as the
119         pcreposix library.
120    
121     (9) Compile the test program pcretest.c. This needs the functions in the
122         pcre and pcreposix libraries when linking. It also needs the
123         pcre_printint.src source file, which it #includes.
124    
125    (10) Run pcretest on the testinput files in the testdata directory, and check
126         that the output matches the corresponding testoutput files. Note that the
127         supplied files are in Unix format, with just LF characters as line
128         terminators. You may need to edit them to change this if your system uses
129         a different convention.
130    
131  (7) If you want to use the pcregrep command, compile and link pcregrep.c; it  (11) If you want to use the pcregrep command, compile and link pcregrep.c; it
132  uses only the basic PCRE library.       uses only the basic PCRE library (it does not need the pcreposix library).
133    
134    
135  THE C++ WRAPPER FUNCTIONS  THE C++ WRAPPER FUNCTIONS
136    
137  The PCRE distribution now contains some C++ wrapper functions and tests,  The PCRE distribution also contains some C++ wrapper functions and tests,
138  contributed by Google Inc. On a system that can use "configure" and "make",  contributed by Google Inc. On a system that can use "configure" and "make",
139  the functions are automatically built into a library called pcrecpp. It should  the functions are automatically built into a library called pcrecpp. It should
140  be straightforward to compile the .cc files manually on other systems. The  be straightforward to compile the .cc files manually on other systems. The
# Line 130  files called xxx_unittest.cc are test pr Line 142  files called xxx_unittest.cc are test pr
142  xxx.cc files.  xxx.cc files.
143    
144    
145  FURTHER REMARKS  BUILDING FOR VIRTUAL PASCAL
146    
147  If you have a system without "configure" but where you can use a Makefile, edit  A script for building PCRE using Borland's C++ compiler for use with VPASCAL
148  Makefile.in to create Makefile, substituting suitable values for the variables  was contributed by Alexander Tokarev. Stefan Weber updated the script and added
149  at the head of the file.  additional files. The following files in the distribution are for building PCRE
150    for use with VP/Borland: makevp_c.txt, makevp_l.txt, makevp.bat, pcregexp.pas.
151    
 Michael Roy sent these comments about building PCRE under Windows with BCC5.5:  
152    
153    Some of the core BCC libraries have a version of PCRE from 1998 built in,  STACK SIZE IN WINDOWS ENVIRONMENTS
   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:  
154    
155    When linking a project with BCC5.5, pcre.lib must be included before any of  The default processor stack size of 1Mb in some Windows environments is too
156    the libraries cw32.lib, cw32i.lib, cw32mt.lib, and cw32mti.lib on the command  small for matching patterns that need much recursion. In particular, test 2 may
157    line.  fail because of this. Normally, running out of stack causes a crash, but there
158    have been cases where the test program has just died silently. See your linker
159    documentation for how to increase stack size if you experience problems. The
160    Linux default of 8Mb is a reasonable choice for the stack, though even that can
161    be too small for some pattern/subject combinations. There is more about stack
162    usage in the "pcrestack" documentation.
163    
 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:  
   
   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).  
   
 Changes to do MinGW with autoconf 2.50 were supplied by Fred Cox  
 <sailorFred@yahoo.com>, who comments as follows:  
   
   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.  
   
   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 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.  
164    
165  A script for building PCRE using Borland's C++ compiler for use with VPASCAL  COMMENTS ABOUT WIN32 BUILDS
 was contributed by Alexander Tokarev. It is called makevp.bat.  
166    
167  These are some further comments about Win32 builds from Mark Evans. They  There are two ways of building PCRE using the "configure, make, make install"
168  were contributed before Fred Cox's changes were made, so it is possible that  paradigm on Windows systems: using MinGW or using Cygwin. These are not at all
169  they may no longer be relevant.  the same thing; they are completely different from each other. There is also
170    some experimental, undocumented support for building using "cmake", which you
171  "The documentation for Win32 builds is a bit shy.  Under MSVC6 I  might like to try if you are familiar with "cmake". However, at the present
172  followed their instructions to the letter, but there were still  time, the "cmake" process builds only a static library (not a dll), and the
173  some things missing.  tests are not automatically run.
   
 (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.  
   
 (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.)"  
174    
175  =========================  The MinGW home page (http://www.mingw.org/) says this:
 #ifdef _WIN32  
 #include <malloc.h>  
176    
177  void* malloc_stub(size_t N)    MinGW: A collection of freely available and freely distributable Windows
178  { return malloc(N); }    specific header files and import libraries combined with GNU toolsets that
179  void free_stub(void* p)    allow one to produce native Windows programs that do not rely on any
180  { free(p); }    3rd-party C runtime DLLs.
 void *(*pcre_malloc)(size_t) = &malloc_stub;  
 void  (*pcre_free)(void *) = &free_stub;  
181    
182  #else  The Cygwin home page (http://www.cygwin.com/) says this:
183    
184  void *(*pcre_malloc)(size_t) = malloc;    Cygwin is a Linux-like environment for Windows. It consists of two parts:
 void  (*pcre_free)(void *) = free;  
185    
186  #endif    . A DLL (cygwin1.dll) which acts as a Linux API emulation layer providing
187  =========================      substantial Linux API functionality
188    
189      . A collection of tools which provide Linux look and feel.
190    
191      The Cygwin DLL currently works with all recent, commercially released x86 32
192      bit and 64 bit versions of Windows, with the exception of Windows CE.
193    
194    On both MinGW and Cygwin, PCRE should build correctly using:
195    
196      ./configure && make && make install
197    
198    This should create two libraries called libpcre and libpcreposix, and, if you
199    have enabled building the C++ wrapper, a third one called libpcrecpp. These are
200    independent libraries: when you like with libpcreposix or libpcrecpp you must
201    also link with libpcre, which contains the basic functions. (Some earlier
202    releases of PCRE included the basic libpcre functions in libpcreposix. This no
203    longer happens.)
204    
205    If you want to statically link your program against a non-dll .a file, you must
206    define PCRE_STATIC before including pcre.h, otherwise the pcre_malloc() and
207    pcre_free() exported functions will be declared __declspec(dllimport), with
208    unwanted results.
209    
210    Using Cygwin's compiler generates libraries and executables that depend on
211    cygwin1.dll. If a library that is generated this way is distributed,
212    cygwin1.dll has to be distributed as well. Since cygwin1.dll is under the GPL
213    licence, this forces not only PCRE to be under the GPL, but also the entire
214    application. A distributor who wants to keep their own code proprietary must
215    purchase an appropriate Cygwin licence.
216    
217    MinGW has no such restrictions. The MinGW compiler generates a library or
218    executable that can run standalone on Windows without any third party dll or
219    licensing issues.
220    
221    But there is more complication:
222    
223    If a Cygwin user uses the -mno-cygwin Cygwin gcc flag, what that really does is
224    to tell Cygwin's gcc to use the MinGW gcc. Cygwin's gcc is only acting as a
225    front end to MinGW's gcc (if you install Cygwin's gcc, you get both Cygwin's
226    gcc and MinGW's gcc). So, a user can:
227    
228    . Build native binaries by using MinGW or by getting Cygwin and using
229      -mno-cygwin.
230    
231    . Build binaries that depend on cygwin1.dll by using Cygwin with the normal
232      compiler flags.
233    
234    The test files that are supplied with PCRE are in Unix format, with LF
235    characters as line terminators. It may be necessary to change the line
236    terminators in order to get some of the tests to work. We hope to improve
237    things in this area in future.
238    
239    
240    BUILDING UNDER WINDOWS WITH BCC5.5
241    
242    Michael Roy sent these comments about building PCRE under Windows with BCC5.5:
243    
244      Some of the core BCC libraries have a version of PCRE from 1998 built in,
245      which can lead to pcre_exec() giving an erroneous PCRE_ERROR_NULL from a
246      version mismatch. I'm including an easy workaround below, if you'd like to
247      include it in the non-unix instructions:
248    
249      When linking a project with BCC5.5, pcre.lib must be included before any of
250      the libraries cw32.lib, cw32i.lib, cw32mt.lib, and cw32mti.lib on the command
251      line.
252    
253    
254  BUILDING PCRE ON OPENVMS  BUILDING PCRE ON OPENVMS
# Line 278  $! Locale could not be set to fr Line 315  $! Locale could not be set to fr
315  $!  $!
316  =========================  =========================
317    
318    Last Updated: 01 August 2007
319  ****  ****
Legend:
Removed from v.96  
changed lines
  Added in v.200
webmaster@exim.org
 ViewVC Help
Powered by ViewVC 1.1.12