/[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 260 by ph10, Thu Sep 20 10:19:16 2007 UTC revision 672 by ph10, Tue Aug 23 16:45:55 2011 UTC
# Line 8  This document contains the following sec Line 8  This document contains the following sec
8    The C++ wrapper functions    The C++ wrapper functions
9    Building for virtual Pascal    Building for virtual Pascal
10    Stack size in Windows environments    Stack size in Windows environments
11      Linking programs in Windows environments
12    Comments about Win32 builds    Comments about Win32 builds
13    Building PCRE with CMake    Building PCRE on Windows with CMake
14      Use of relative paths with CMake on Windows
15      Testing with RunTest.bat
16    Building under Windows with BCC5.5    Building under Windows with BCC5.5
17    Building PCRE on OpenVMS    Building PCRE on OpenVMS
18      Building PCRE on Stratus OpenVOS
19    
20    
21  GENERAL  GENERAL
# Line 20  I (Philip Hazel) have no experience of W Line 24  I (Philip Hazel) have no experience of W
24  libraries work. The items in the PCRE distribution and Makefile that relate to  libraries work. The items in the PCRE distribution and Makefile that relate to
25  anything other than Unix-like systems are untested by me.  anything other than Unix-like systems are untested by me.
26    
27  There are some other comments and files in the Contrib directory on the ftp  There are some other comments and files (including some documentation in CHM
28  site that you may find useful. See  format) in the Contrib directory on the FTP site:
29    
30    ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/Contrib    ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/Contrib
31    
# Line 31  library consists entirely of code writte Line 35  library consists entirely of code writte
35  successfully on any system that has a Standard C compiler and library. The C++  successfully on any system that has a Standard C compiler and library. The C++
36  wrapper functions are a separate issue (see below).  wrapper functions are a separate issue (see below).
37    
38  The PCRE distribution includes support for CMake. This support is relatively  The PCRE distribution includes a "configure" file for use by the Configure/Make
39  new, but has already been used successfully to build PCRE in multiple build  build system, as found in many Unix-like environments. There is also support
40  environments on Windows. There are some instructions in the section entitled  for CMake, which some users prefer, especially in Windows environments. There
41  "Building PCRE with CMake" below.  are some instructions for CMake under Windows in the section entitled "Building
42    PCRE with CMake" below. CMake can also be used to build PCRE in Unix-like
43    systems.
44    
45    
46  GENERIC INSTRUCTIONS FOR THE PCRE C LIBRARY  GENERIC INSTRUCTIONS FOR THE PCRE C LIBRARY
47    
48  The following are generic comments about building the PCRE C library "by hand".  The following are generic instructions for building the PCRE C library "by
49    hand":
50    
51   (1) Copy or rename the file config.h.generic as config.h, and edit the macro   (1) Copy or rename the file config.h.generic as config.h, and edit the macro
52       settings that it contains to whatever is appropriate for your environment.       settings that it contains to whatever is appropriate for your environment.
# Line 80  The following are generic comments about Line 87  The following are generic comments about
87    
88         pcre_internal.h         pcre_internal.h
89         ucp.h         ucp.h
        ucpinternal.h  
        ucptable.h  
90    
91   (5) Also ensure that you have the following file, which is #included as source   (5) Also ensure that you have the following file, which is #included as source
92       when building a debugging version of PCRE and is also used by pcretest.       when building a debugging version of PCRE, and is also used by pcretest.
93    
94         pcre_printint.src         pcre_printint.src
95    
# Line 108  The following are generic comments about Line 113  The following are generic comments about
113         pcre_study.c         pcre_study.c
114         pcre_tables.c         pcre_tables.c
115         pcre_try_flipped.c         pcre_try_flipped.c
116         pcre_ucp_searchfuncs.c         pcre_ucd.c
117         pcre_valid_utf8.c         pcre_valid_utf8.c
118         pcre_version.c         pcre_version.c
119         pcre_xclass.c         pcre_xclass.c
# Line 117  The following are generic comments about Line 122  The following are generic comments about
122       an unusual compiler) so that all included PCRE header files are first       an unusual compiler) so that all included PCRE header files are first
123       sought in the current directory. Otherwise you run the risk of picking up       sought in the current directory. Otherwise you run the risk of picking up
124       a previously-installed file from somewhere else.       a previously-installed file from somewhere else.
125    
126     (7) If you have defined SUPPORT_JIT in config.h, you must also compile
127    
128           pcre_jit_compile.c
129    
130         This file #includes sources from the sljit subdirectory, where there
131         should be 16 files, all of whose names begin with "sljit".
132    
133   (7) Now link all the compiled code into an object library in whichever form   (8) Now link all the compiled code into an object library in whichever form
134       your system keeps such libraries. This is the basic PCRE C library. If       your system keeps such libraries. This is the basic PCRE C library. If
135       your system has static and shared libraries, you may have to do this once       your system has static and shared libraries, you may have to do this once
136       for each type.       for each type.
137    
138   (8) Similarly, compile pcreposix.c (remembering -DHAVE_CONFIG_H if necessary)   (9) Similarly, if you want to build the POSIX wrapper functions, ensure that
139       and link the result (on its own) as the pcreposix library.       you have the pcreposix.h file and then compile pcreposix.c (remembering
140         -DHAVE_CONFIG_H if necessary). Link the result (on its own) as the
141         pcreposix library.
142    
143    (10) Compile the test program pcretest.c (again, don't forget -DHAVE_CONFIG_H).
144         This needs the functions in the PCRE library when linking. It also needs
145         the pcreposix wrapper functions unless you compile it with -DNOPOSIX. The
146         pcretest.c program also needs the pcre_printint.src source file, which it
147         #includes.
148    
149    (11) Run pcretest on the testinput files in the testdata directory, and check
150         that the output matches the corresponding testoutput files. Some tests are
151         relevant only when certain build-time options are selected. For example,
152         test 4 is for UTF-8 support, and will not run if you have build PCRE
153         without it. See the comments at the start of each testinput file. If you
154         have a suitable Unix-like shell, the RunTest script will run the
155         appropriate tests for you.
156    
157         Note that the supplied files are in Unix format, with just LF characters
158         as line terminators. You may need to edit them to change this if your
159         system uses a different convention. If you are using Windows, you probably
160         should use the wintestinput3 file instead of testinput3 (and the
161         corresponding output file). This is a locale test; wintestinput3 sets the
162         locale to "french" rather than "fr_FR", and there some minor output
163         differences.
164    
165    (12) If you have built PCRE with SUPPORT_JIT, the JIT features will be tested
166         by the testdata files. However, you might also like to build and run
167         the JIT test program, pcre_jit_test.c.
168    
169   (9) Compile the test program pcretest.c (again, don't forget -DHAVE_CONFIG_H).  (13) If you want to use the pcregrep command, compile and link pcregrep.c; it
      This needs the functions in the pcre and pcreposix libraries when linking.  
      It also needs the pcre_printint.src source file, which it #includes.  
   
 (10) 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. If you are using Windows, you probably should use  
      the wintestinput3 file instead of testinput3 (and the corresponding output  
      file). This is a locale test; wintestinput3 sets the locale to "french"  
      rather than "fr_FR", and there some minor output differences.  
   
 (11) If you want to use the pcregrep command, compile and link pcregrep.c; it  
170       uses only the basic PCRE library (it does not need the pcreposix library).       uses only the basic PCRE library (it does not need the pcreposix library).
171    
172    
# Line 169  fail because of this. Normally, running Line 196  fail because of this. Normally, running
196  have been cases where the test program has just died silently. See your linker  have been cases where the test program has just died silently. See your linker
197  documentation for how to increase stack size if you experience problems. The  documentation for how to increase stack size if you experience problems. The
198  Linux default of 8Mb is a reasonable choice for the stack, though even that can  Linux default of 8Mb is a reasonable choice for the stack, though even that can
199  be too small for some pattern/subject combinations.  be too small for some pattern/subject combinations.
200    
201  PCRE has a compile configuration option to disable the use of stack for  PCRE has a compile configuration option to disable the use of stack for
202  recursion so that heap is used instead. However, pattern matching is  recursion so that heap is used instead. However, pattern matching is
# Line 177  significantly slower when this is done. Line 204  significantly slower when this is done.
204  "pcrestack" documentation.  "pcrestack" documentation.
205    
206    
207    LINKING PROGRAMS IN WINDOWS ENVIRONMENTS
208    
209    If you want to statically link a program against a PCRE library in the form of
210    a non-dll .a file, you must define PCRE_STATIC before including pcre.h or
211    pcrecpp.h, otherwise the pcre_malloc() and pcre_free() exported functions will
212    be declared __declspec(dllimport), with unwanted results.
213    
214    
215    CALLING CONVENTIONS IN WINDOWS ENVIRONMENTS
216    
217    It is possible to compile programs to use different calling conventions using
218    MSVC. Search the web for "calling conventions" for more information. To make it
219    easier to change the calling convention for the exported functions in the
220    PCRE library, the macro PCRE_CALL_CONVENTION is present in all the external
221    definitions. It can be set externally when compiling (e.g. in CFLAGS). If it is
222    not set, it defaults to empty; the default calling convention is then used
223    (which is what is wanted most of the time).
224    
225    
226  COMMENTS ABOUT WIN32 BUILDS (see also "BUILDING PCRE WITH CMAKE" below)  COMMENTS ABOUT WIN32 BUILDS (see also "BUILDING PCRE WITH CMAKE" below)
227    
228  There are two ways of building PCRE using the "configure, make, make install"  There are two ways of building PCRE using the "configure, make, make install"
229  paradigm on Windows systems: using MinGW or using Cygwin. These are not at all  paradigm on Windows systems: using MinGW or using Cygwin. These are not at all
230  the same thing; they are completely different from each other. There is also  the same thing; they are completely different from each other. There is also
231  some experimental, undocumented support for building using "cmake", which you  support for building using CMake, which some users find a more straightforward
232  might like to try if you are familiar with "cmake". However, at the present  way of building PCRE under Windows. However, the tests are not run
233  time, the "cmake" process builds only a static library (not a dll), and the  automatically when CMake is used.
 tests are not automatically run.  
234    
235  The MinGW home page (http://www.mingw.org/) says this:  The MinGW home page (http://www.mingw.org/) says this:
236    
# Line 212  On both MinGW and Cygwin, PCRE should bu Line 257  On both MinGW and Cygwin, PCRE should bu
257    
258  This should create two libraries called libpcre and libpcreposix, and, if you  This should create two libraries called libpcre and libpcreposix, and, if you
259  have enabled building the C++ wrapper, a third one called libpcrecpp. These are  have enabled building the C++ wrapper, a third one called libpcrecpp. These are
260  independent libraries: when you like with libpcreposix or libpcrecpp you must  independent libraries: when you link with libpcreposix or libpcrecpp you must
261  also link with libpcre, which contains the basic functions. (Some earlier  also link with libpcre, which contains the basic functions. (Some earlier
262  releases of PCRE included the basic libpcre functions in libpcreposix. This no  releases of PCRE included the basic libpcre functions in libpcreposix. This no
263  longer happens.)  longer happens.)
264    
265  If you want to statically link your program against a non-dll .a file, you must  A user submitted a special-purpose patch that makes it easy to create
266  define PCRE_STATIC before including pcre.h, otherwise the pcre_malloc() and  "pcre.dll" under mingw32 using the "msys" environment. It provides "pcre.dll"
267  pcre_free() exported functions will be declared __declspec(dllimport), with  as a special target. If you use this target, no other files are built, and in
268  unwanted results.  particular, the pcretest and pcregrep programs are not built. An example of how
269    this might be used is:
270    
271      ./configure --enable-utf --disable-cpp CFLAGS="-03 -s"; make pcre.dll
272    
273  Using Cygwin's compiler generates libraries and executables that depend on  Using Cygwin's compiler generates libraries and executables that depend on
274  cygwin1.dll. If a library that is generated this way is distributed,  cygwin1.dll. If a library that is generated this way is distributed,
# Line 248  gcc and MinGW's gcc). So, a user can: Line 296  gcc and MinGW's gcc). So, a user can:
296    
297  The test files that are supplied with PCRE are in Unix format, with LF  The test files that are supplied with PCRE are in Unix format, with LF
298  characters as line terminators. It may be necessary to change the line  characters as line terminators. It may be necessary to change the line
299  terminators in order to get some of the tests to work. We hope to improve  terminators in order to get some of the tests to work.
 things in this area in future.  
300    
301    
302  BUILDING PCRE WITH CMAKE  BUILDING PCRE ON WINDOWS WITH CMAKE
303    
304  CMake is an alternative build facility that can be used instead of the  CMake is an alternative configuration facility that can be used instead of the
305  traditional Unix "configure". CMake version 2.4.7 supports Borland makefiles,  traditional Unix "configure". CMake creates project files (make files, solution
306  MinGW makefiles, MSYS makefiles, NMake makefiles, UNIX makefiles, Visual Studio  files, etc.) tailored to numerous development environments, including Visual
307  6, Visual Studio 7, Visual Studio 8, and Watcom W8. The following instructions  Studio, Borland, Msys, MinGW, NMake, and Unix. The following instructions
308  were contributed by a PCRE user.  were contributed by a PCRE user.
309    
310  1. Download CMake 2.4.7 or above from http://www.cmake.org/, install and ensure  1.  Install the latest CMake version available from http://www.cmake.org/, and
311     that cmake\bin is on your path.      ensure that cmake\bin is on your path.
312    
313  2. Unzip (retaining folder structure) the PCRE source tree into a source  2.  Unzip (retaining folder structure) the PCRE source tree into a source
314     directory such as C:\pcre.      directory such as C:\pcre.
315    
316  3. Create a new, empty build directory: C:\pcre\build\  3.  Create a new, empty build directory, for example C:\pcre\build\
317    
318  4. Run CMakeSetup from the Shell envirornment of your build tool, e.g., Msys  4.  Run cmake-gui from the Shell envirornment of your build tool, for example,
319     for Msys/MinGW or Visual Studio Command Prompt for VC/VC++      Msys for Msys/MinGW or Visual Studio Command Prompt for VC/VC++.
320    
321  5. Enter C:\pcre\pcre-xx and C:\pcre\build for the source and build  5.  Enter C:\pcre\pcre-xx and C:\pcre\build for the source and build
322     directories, respectively      directories, respectively.
323    
324  6. Hit the "Configure" button.  6.  Hit the "Configure" button.
325    
326  7. Select the particular IDE / build tool that you are using (Visual Studio,  7.  Select the particular IDE / build tool that you are using (Visual
327     MSYS makefiles, MinGW makefiles, etc.)      Studio, MSYS makefiles, MinGW makefiles, etc.)
328    
329  8. The GUI will then list several configuration options. This is where you can  8.  The GUI will then list several configuration options. This is where
330     enable UTF-8 support, etc.      you can enable UTF-8 support or other PCRE optional features.
331    
332  9. Hit "Configure" again. The adjacent "OK" button should now be active.  9.  Hit "Configure" again. The adjacent "Generate" button should now be
333        active.
334    
335  10. Hit "OK".  10. Hit "Generate".
336    
337  11. The build directory should now contain a usable build system, be it a  11. The build directory should now contain a usable build system, be it a
338      solution file for Visual Studio, makefiles for MinGW, etc.      solution file for Visual Studio, makefiles for MinGW, etc. Exit from
339        cmake-gui and use the generated build system with your compiler or IDE.
340    
341    
342    USE OF RELATIVE PATHS WITH CMAKE ON WINDOWS
343    
344    A PCRE user comments as follows:
345    
346    I thought that others may want to know the current state of
347    CMAKE_USE_RELATIVE_PATHS support on Windows.
348    
349  Testing with RunTest.bat  Here it is:
350    -- AdditionalIncludeDirectories is only partially modified (only the
351    first path - see below)
352    -- Only some of the contained file paths are modified - shown below for
353    pcre.vcproj
354    -- It properly modifies
355    
356    I am sure CMake people can fix that if they want to. Until then one will
357    need to replace existing absolute paths in project files with relative
358    paths manually (e.g. from VS) - relative to project file location. I did
359    just that before being told to try CMAKE_USE_RELATIVE_PATHS. Not a big
360    deal.
361    
362    AdditionalIncludeDirectories="E:\builds\pcre\build;E:\builds\pcre\pcre-7.5;"
363    AdditionalIncludeDirectories=".;E:\builds\pcre\pcre-7.5;"
364    
365    RelativePath="pcre.h">
366    RelativePath="pcre_chartables.c">
367    RelativePath="pcre_chartables.c.rule">
368    
369    
370    TESTING WITH RUNTEST.BAT
371    
372  1. Copy RunTest.bat into the directory where pcretest.exe has been created.  1. Copy RunTest.bat into the directory where pcretest.exe has been created.
373    
# Line 320  Michael Roy sent these comments about bu Line 398  Michael Roy sent these comments about bu
398    line.    line.
399    
400    
401    BUILDING UNDER WINDOWS CE WITH VISUAL STUDIO 200x
402    
403    Vincent Richomme sent a zip archive of files to help with this process. They
404    can be found in the file "pcre-vsbuild.zip" in the Contrib directory of the FTP
405    site.
406    
407    
408  BUILDING PCRE ON OPENVMS  BUILDING PCRE ON OPENVMS
409    
410  Dan Mooney sent the following comments about building PCRE on OpenVMS. They  Dan Mooney sent the following comments about building PCRE on OpenVMS. They
# Line 384  $!   Locale could not be set to fr Line 469  $!   Locale could not be set to fr
469  $!  $!
470  =========================  =========================
471    
472  Last Updated: 21 September 2007  
473    BUILDING PCRE ON STRATUS OPENVOS
474    
475    These notes on the port of PCRE to VOS (lightly edited) were supplied by
476    Ashutosh Warikoo, whose email address has the local part awarikoo and the
477    domain nse.co.in. The port was for version 7.9 in August 2009.
478    
479    1.   Building PCRE
480    
481    I built pcre on OpenVOS Release 17.0.1at using GNU Tools 3.4a without any
482    problems. I used the following packages to build PCRE:
483    
484      ftp://ftp.stratus.com/pub/vos/posix/ga/posix.save.evf.gz
485    
486    Please read and follow the instructions that come with these packages. To start
487    the build of pcre, from the root of the package type:
488    
489      ./build.sh
490    
491    2. Installing PCRE
492    
493    Once you have successfully built PCRE, login to the SysAdmin group, switch to
494    the root user, and type
495    
496      [ !create_dir (master_disk)>usr   --if needed ]
497      [ !create_dir (master_disk)>usr>local   --if needed ]
498        !gmake install
499    
500    This installs PCRE and its man pages into /usr/local. You can add
501    (master_disk)>usr>local>bin to your command search paths, or if you are in
502    BASH, add /usr/local/bin to the PATH environment variable.
503    
504    4. Restrictions
505    
506    This port requires readline library optionally. However during the build I
507    faced some yet unexplored errors while linking with readline. As it was an
508    optional component I chose to disable it.
509    
510    5. Known Problems
511    
512    I ran a the test suite, but you will have to be your own judge of whether this
513    command, and this port, suits your purposes. If you find any problems that
514    appear to be related to the port itself, please let me know. Please see the
515    build.log file in the root of the package also.
516    
517    
518    =========================
519    Last Updated: 23 August 2011
520  ****  ****

Legend:
Removed from v.260  
changed lines
  Added in v.672

  ViewVC Help
Powered by ViewVC 1.1.5