/[pcre]/code/branches/pcre16/NON-UNIX-USE

Diff of /code/branches/pcre16/NON-UNIX-USE

Parent Directory | Revision Log | View Patch Patch

-revision 135 by ph10,
Thu Mar 29 09:09:33 2007 UTC
+revision 374 by ph10,
Fri Sep  5 16:42:28 2008 UTC
 Line 7 
 This document contains the following sec
    Generic instructions for the PCRE C library
    The C++ wrapper functions
    Building for virtual Pascal
+   Stack size in Windows environments
+   Linking programs in Windows environments
    Comments about Win32 builds
+   Building PCRE on Windows with CMake
+   Use of relative paths with CMake on Windows
+   Testing with runtest.bat
    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
+ I (Philip Hazel) have no experience 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.
-Line 23 
 site that you may find useful. See
+Line 28 
 site that you may find useful. See
    ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/Contrib
- If you want to compile PCRE for a non-Unix system (or perhaps, more strictly,
+ If you want to compile PCRE for a non-Unix system (especially for a system that
- for a system that does not support "configure" and "make" files), note that
+ does not support "configure" and "make" files), note that the basic PCRE
- the basic PCRE library consists entirely of code written in Standard C, and so
+ library consists entirely of code written in Standard C, and so should compile
- should compile successfully on any system that has a Standard C compiler and
+ successfully on any system that has a Standard C compiler and library. The C++
- library. The C++ wrapper functions are a separate issue (see below).
+ wrapper functions are a separate issue (see below).
+ The PCRE distribution includes a "configure" file for use by the Configure/Make
+ build system, as found in many Unix-like environments. There is also support
+ support for CMake, which some users prefer, in particular in Windows
+ environments. There are some instructions for CMake under Windows in the
+ section entitled "Building PCRE with CMake" below. CMake can also be used to
+ build PCRE in Unix-like systems.
  GENERIC INSTRUCTIONS FOR THE PCRE C LIBRARY
  The following are generic comments about building the PCRE C library "by hand".
- (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
-     settings that it contains to whatever is appropriate for your environment.
+      settings that it contains to whatever is appropriate for your environment.
-     In particular, if you want to force a specific value for newline, you can
+      In particular, if you want to force a specific value for newline, you can
-     define the NEWLINE macro.
+      define the NEWLINE macro. When you compile any of the PCRE modules, you
+      must specify -DHAVE_CONFIG_H to your compiler so that config.h is included
-     An alternative approach is not to edit config.h, but to use -D on the
+      in the sources.
-     compiler command line to make any changes that you need.
+      An alternative approach is not to edit config.h, but to use -D on the
- (2) Copy or rename the file pcre.h.generic as pcre.h.
+      compiler command line to make any changes that you need to the
+      configuration options. In this case -DHAVE_CONFIG_H must not be set.
- (3) EITHER:
-       Copy or rename file pcre_chartables.c.dist as pcre_chartables.c.
+      NOTE: There have been occasions when the way in which certain parameters
+      in config.h are used has changed between releases. (In the configure/make
-     OR:
+      world, this is handled automatically.) When upgrading to a new release,
-       Compile dftables.c as a stand-alone program, and then run it with the
+      you are strongly advised to review config.h.generic before re-using what
-       single argument "pcre_chartables.c". This generates a set of standard
+      you had previously.
-       character tables and writes them to that file. The tables are generated
-       using the default C locale for your system. If you want to use a locale
+  (2) Copy or rename the file pcre.h.generic as pcre.h.
-       that is specified by LC_xxx environment variables, add the -L option to
-       the dftables command. You must use this method if you are building on
+  (3) EITHER:
-       a system that uses EBCDIC code.
+        Copy or rename file pcre_chartables.c.dist as pcre_chartables.c.
-     The tables in pcre_chartables.c are defaults. The caller of PCRE can
+      OR:
-     specify alternative tables at run time.
+        Compile dftables.c as a stand-alone program (using -DHAVE_CONFIG_H if
+        you have set up config.h), and then run it with the single argument
- (4) Compile the following source files:
+        "pcre_chartables.c". This generates a set of standard character tables
+        and writes them to that file. The tables are generated using the default
-       pcre_chartables.c
+        C locale for your system. If you want to use a locale that is specified
-       pcre_compile.c
+        by LC_xxx environment variables, add the -L option to the dftables
-       pcre_config.c
+        command. You must use this method if you are building on a system that
-       pcre_dfa_exec.c
+        uses EBCDIC code.
-       pcre_exec.c
-       pcre_fullinfo.c
+      The tables in pcre_chartables.c are defaults. The caller of PCRE can
-       pcre_get.c
+      specify alternative tables at run time.
-       pcre_globals.c
-       pcre_info.c
+  (4) Ensure that you have the following header files:
-       pcre_maketables.c
-       pcre_newline.c
+        pcre_internal.h
-       pcre_ord2utf8.c
+        ucp.h
-       pcre_refcount.c
-       pcre_study.c
+  (5) Also ensure that you have the following file, which is #included as source
-       pcre_tables.c
+      when building a debugging version of PCRE, and is also used by pcretest.
-       pcre_try_flipped.c
-       pcre_ucp_searchfuncs.c
+        pcre_printint.src
-       pcre_valid_utf8.c
-       pcre_version.c
+  (6) Compile the following source files, setting -DHAVE_CONFIG_H as a compiler
-       pcre_xclass.c
+      option if you have set up config.h with your configuration, or else use
+      other -D settings to change the configuration as required.
-     Now link them all together into an object library in whichever form your
-     system keeps such libraries. This is the basic PCRE C library. If your
+        pcre_chartables.c
-     system has static and shared libraries, you may have to do this once for
+        pcre_compile.c
-     each type.
+        pcre_config.c
+        pcre_dfa_exec.c
- (5) Similarly, compile pcreposix.c and link it (on its own) as the pcreposix
+        pcre_exec.c
-     library.
+        pcre_fullinfo.c
+        pcre_get.c
- (6) Compile the test program pcretest.c. This needs the functions in the
+        pcre_globals.c
-     pcre and pcreposix libraries when linking.
+        pcre_info.c
+        pcre_maketables.c
- (7) Run pcretest on the testinput files in the testdata directory, and check
+        pcre_newline.c
-     that the output matches the corresponding testoutput files. Note that the
+        pcre_ord2utf8.c
-     supplied files are in Unix format, with just LF characters as line
+        pcre_refcount.c
-     terminators. You may need to edit them to change this if your system uses a
+        pcre_study.c
-     different convention.
+        pcre_tables.c
+        pcre_try_flipped.c
+        pcre_ucd.c
+        pcre_valid_utf8.c
+        pcre_version.c
+        pcre_xclass.c
+      Make sure that you include -I. in the compiler command (or equivalent for
+      an unusual compiler) so that all included PCRE header files are first
+      sought in the current directory. Otherwise you run the risk of picking up
+      a previously-installed file from somewhere else.
+  (7) Now link all the compiled code into an object library in whichever form
+      your system keeps such libraries. This is the basic PCRE C library. If
+      your system has static and shared libraries, you may have to do this once
+      for each type.
+  (8) Similarly, compile pcreposix.c (remembering -DHAVE_CONFIG_H if necessary)
+      and link the result (on its own) as the pcreposix library.
+  (9) Compile the test program pcretest.c (again, don't forget -DHAVE_CONFIG_H).
+      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.
- (8) 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
-     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).
  THE C++ WRAPPER FUNCTIONS
-Line 121 
 additional files. The following files in
+Line 164 
 additional files. The following files in
  for use with VP/Borland: makevp_c.txt, makevp_l.txt, makevp.bat, pcregexp.pas.
- COMMENTS ABOUT WIN32 BUILDS
+ STACK SIZE IN WINDOWS ENVIRONMENTS
- There are two ways of building PCRE on Windows systems: using MinGW or using
+ The default processor stack size of 1Mb in some Windows environments is too
- Cygwin. These are not at all the same thing, and are completely different from
+ small for matching patterns that need much recursion. In particular, test 2 may
- each other.
+ fail because of this. Normally, running out of stack causes a crash, but there
+ have been cases where the test program has just died silently. See your linker
+ documentation for how to increase stack size if you experience problems. The
+ Linux default of 8Mb is a reasonable choice for the stack, though even that can
+ be too small for some pattern/subject combinations.
+ PCRE has a compile configuration option to disable the use of stack for
+ recursion so that heap is used instead. However, pattern matching is
+ significantly slower when this is done. There is more about stack usage in the
+ "pcrestack" documentation.
+ LINKING PROGRAMS IN WINDOWS ENVIRONMENTS
+ If you want to statically link a program against a PCRE library in the form of
+ a non-dll .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.
+ CALLING CONVENTIONS IN WINDOWS ENVIRONMENTS
+ It is possible to compile programs to use different calling conventions using
+ MSVC. Search the web for "calling conventions" for more information. To make it
+ easier to change the calling convention for the exported functions in the
+ PCRE library, the macro PCRE_CALL_CONVENTION is present in all the external
+ definitions. It can be set externally when compiling (e.g. in CFLAGS). If it is
+ not set, it defaults to empty; the default calling convention is then used
+ (which is what is wanted most of the time).
+ COMMENTS ABOUT WIN32 BUILDS (see also "BUILDING PCRE WITH CMAKE" below)
+ There are two ways of building PCRE using the "configure, make, make install"
+ paradigm on Windows systems: using MinGW or using Cygwin. These are not at all
+ the same thing; they are completely different from each other. There is also
+ support for building using CMake, which some users find a more straightforward
+ way of building PCRE under Windows. However, the tests are not run
+ automatically when CMake is used.
  The MinGW home page (http://www.mingw.org/) says this:
-Line 150 
 On both MinGW and Cygwin, PCRE should bu
+Line 231 
 On both MinGW and Cygwin, PCRE should bu
    ./configure && make && make install
- However, if you want to statically link your program against the .a file, you
+ This should create two libraries called libpcre and libpcreposix, and, if you
- must define PCRE_STATIC before including pcre.h, otherwise the pcre_malloc()
+ have enabled building the C++ wrapper, a third one called libpcrecpp. These are
- and pcre_free() exported functions will be declared __declspec(dllimport), with
+ independent libraries: when you like with libpcreposix or libpcrecpp you must
- unwanted results.
+ also link with libpcre, which contains the basic functions. (Some earlier
+ releases of PCRE included the basic libpcre functions in libpcreposix. This no
+ longer happens.)
+ A user submitted a special-purpose patch that makes it easy to create
+ "pcre.dll" under mingw32 using the "msys" environment. It provides "pcre.dll"
+ as a special target. If you use this target, no other files are built, and in
+ particular, the pcretest and pcregrep programs are not built. An example of how
+ this might be used is:
+   ./configure --enable-utf --disable-cpp CFLAGS="-03 -s"; make pcre.dll
  Using Cygwin's compiler generates libraries and executables that depend on
  cygwin1.dll. If a library that is generated this way is distributed,
-Line 181 
 gcc and MinGW's gcc). So, a user can:
+Line 272 
 gcc and MinGW's gcc). So, a user can:
  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
+ terminators in order to get some of the tests to work. We hope to improve
  things in this area in future.
+ BUILDING PCRE ON WINDOWS WITH CMAKE
+ CMake is an alternative build facility that can be used instead of the
+ traditional Unix "configure". CMake version 2.4.7 supports Borland makefiles,
+ MinGW makefiles, MSYS makefiles, NMake makefiles, UNIX makefiles, Visual Studio
+, Visual Studio 7, Visual Studio 8, and Watcom W8. The following instructions
+ were contributed by a PCRE user.
+.  Download CMake 2.4.7 or above from http://www.cmake.org/, install and ensure
+     that cmake\bin is on your path.
+.  Unzip (retaining folder structure) the PCRE source tree into a source
+     directory such as C:\pcre.
+.  Create a new, empty build directory: C:\pcre\build\
+.  Run CMakeSetup from the Shell envirornment of your build tool, e.g., Msys
+     for Msys/MinGW or Visual Studio Command Prompt for VC/VC++
+.  Enter C:\pcre\pcre-xx and C:\pcre\build for the source and build
+     directories, respectively
+.  Hit the "Configure" button.
+.  Select the particular IDE / build tool that you are using (Visual Studio,
+     MSYS makefiles, MinGW makefiles, etc.)
+.  The GUI will then list several configuration options. This is where you can
+     enable UTF-8 support, etc.
+.  Hit "Configure" again. The adjacent "OK" button should now be active.
+. Hit "OK".
+. The build directory should now contain a usable build system, be it a
+     solution file for Visual Studio, makefiles for MinGW, etc.
+ USE OF RELATIVE PATHS WITH CMAKE ON WINDOWS
+ A PCRE user comments as follows:
+ I thought that others may want to know the current state of
+ CMAKE_USE_RELATIVE_PATHS support on Windows.
+ Here it is:
+ -- AdditionalIncludeDirectories is only partially modified (only the
+ first path - see below)
+ -- Only some of the contained file paths are modified - shown below for
+ pcre.vcproj
+ -- It properly modifies
+ I am sure CMake people can fix that if they want to. Until then one will
+ need to replace existing absolute paths in project files with relative
+ paths manually (e.g. from VS) - relative to project file location. I did
+ just that before being told to try CMAKE_USE_RELATIVE_PATHS. Not a big
+ deal.
+ AdditionalIncludeDirectories="E:\builds\pcre\build;E:\builds\pcre\pcre-7.5;"
+ AdditionalIncludeDirectories=".;E:\builds\pcre\pcre-7.5;"
+ RelativePath="pcre.h">
+ RelativePath="pcre_chartables.c">
+ RelativePath="pcre_chartables.c.rule">
+ TESTING WITH RUNTEST.BAT
+. Copy RunTest.bat into the directory where pcretest.exe has been created.
+. Edit RunTest.bat and insert a line that indentifies the relative location of
+    the pcre source, e.g.:
+    set srcdir=..\pcre-7.4-RC3
+. Run RunTest.bat from a command shell environment. Test outputs will
+    automatically be compared to expected results, and discrepancies will
+    identified in the console output.
+. To test pcrecpp, run pcrecpp_unittest.exe, pcre_stringpiece_unittest.exe and
+    pcre_scanner_unittest.exe.
  BUILDING UNDER WINDOWS WITH BCC5.5
  Michael Roy sent these comments about building PCRE under Windows with BCC5.5:
-Line 263 
 $!   Locale could not be set to fr
+Line 437 
 $!   Locale could not be set to fr
  $!
  =========================
- Last Updated: 26 March 2007
+ Last Updated: 05 September 2008
  ****

 Legend:



Removed from v.135
 


changed lines


 
Added in v.374
 Legend:



Removed from v.135
 


changed lines


 
Added in v.374
-Removed from v.135
+Added in v.374

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12