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

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

Parent Directory | Revision Log | View Patch Patch

-revision 441 by ph10,
Wed Sep  9 10:37:29 2009 UTC
+revision 727 by ph10,
Mon Oct 10 10:35:50 2011 UTC
 Line 12 
 This document contains the following sec
    Comments about Win32 builds
    Building PCRE on Windows with CMake
    Use of relative paths with CMake on Windows
-   Testing with runtest.bat
+   Testing with RunTest.bat
    Building under Windows with BCC5.5
    Building PCRE on OpenVMS
    Building PCRE on Stratus OpenVOS
  GENERAL
 Line 37 
 wrapper functions are a separate issue (
  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
+ for CMake, which some users prefer, especially in Windows environments. See
- environments. There are some instructions for CMake under Windows in the
+ the instructions for CMake under Windows in the section entitled "Building
- section entitled "Building PCRE with CMake" below. CMake can also be used to
+ PCRE with CMake" below. CMake can also be used to build PCRE in Unix-like
- build PCRE in Unix-like systems.
+ systems.
  GENERIC INSTRUCTIONS FOR THE PCRE C LIBRARY
- 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
+ hand":
   (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.
-Line 122 
 The following are generic comments about
+Line 123 
 The following are generic comments about
       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
+  (7) If you have defined SUPPORT_JIT in config.h, you must also compile
+        pcre_jit_compile.c
+      This file #includes sources from the sljit subdirectory, where there
+      should be 16 files, all of whose names begin with "sljit".
+  (8) 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)
+  (9) Similarly, if you want to build the POSIX wrapper functions, ensure that
-      and link the result (on its own) as the pcreposix library.
+      you have the pcreposix.h file and then compile pcreposix.c (remembering
+      -DHAVE_CONFIG_H if necessary). Link the result (on its own) as the
+      pcreposix library.
+ (10) Compile the test program pcretest.c (again, don't forget -DHAVE_CONFIG_H).
+      This needs the functions in the PCRE library when linking. It also needs
+      the pcreposix wrapper functions unless you compile it with -DNOPOSIX. The
+      pcretest.c program also needs the pcre_printint.src source file, which it
+      #includes.
+ (11) Run pcretest on the testinput files in the testdata directory, and check
+      that the output matches the corresponding testoutput files. Some tests are
+      relevant only when certain build-time options are selected. For example,
+      test 4 is for UTF-8 support, and will not run if you have build PCRE
+      without it. See the comments at the start of each testinput file. If you
+      have a suitable Unix-like shell, the RunTest script will run the
+      appropriate tests for you.
+      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.
+ (12) If you have built PCRE with SUPPORT_JIT, the JIT features will be tested
+      by the testdata files. However, you might also like to build and run
+      the JIT test program, pcre_jit_test.c.
-  (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
       uses only the basic PCRE library (it does not need the pcreposix library).
-Line 184 
 significantly slower when this is done.
+Line 207 
 significantly slower when this is done.
  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,
+ a non-dll .a file, you must define PCRE_STATIC before including pcre.h or
- otherwise the pcre_malloc() and pcre_free() exported functions will be declared
+ pcrecpp.h, otherwise the pcre_malloc() and pcre_free() exported functions will
- __declspec(dllimport), with unwanted results.
+ be declared __declspec(dllimport), with unwanted results.
  CALLING CONVENTIONS IN WINDOWS ENVIRONMENTS
-Line 206 
 There are two ways of building PCRE usin
+Line 229 
 There are two ways of building PCRE usin
  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
+ way of building PCRE under Windows.
- automatically when CMake is used.
  The MinGW home page (http://www.mingw.org/) says this:
-Line 234 
 On both MinGW and Cygwin, PCRE should bu
+Line 256 
 On both MinGW and Cygwin, PCRE should bu
  This should create two libraries called libpcre and libpcreposix, and, if you
  have enabled building the C++ wrapper, a third one called libpcrecpp. These are
- independent libraries: when you like with libpcreposix or libpcrecpp you must
+ independent libraries: when you link with libpcreposix or libpcrecpp you must
  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.)
-Line 271 
 gcc and MinGW's gcc). So, a user can:
+Line 293 
 gcc and MinGW's gcc). So, a user can:
  . Build binaries that depend on cygwin1.dll by using Cygwin with the normal
    compiler flags.
- 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
- characters as line terminators. It may be necessary to change the line
+ characters as line terminators. Unless your PCRE library uses a default newline
- terminators in order to get some of the tests to work. We hope to improve
+ option that includes LF as a valid newline, it may be necessary to change the
- things in this area in future.
+ line terminators in the test files to get some of the tests to work.
  BUILDING PCRE ON WINDOWS WITH CMAKE
  CMake is an alternative configuration facility that can be used instead of the
  traditional Unix "configure". CMake creates project files (make files, solution
  files, etc.) tailored to numerous development environments, including Visual
- Studio, Borland, Msys, MinGW, NMake, and Unix. The following instructions
+ Studio, Borland, Msys, MinGW, NMake, and Unix.  If possible, use short paths
- were contributed by a PCRE user.
+ with no spaces in the names for your CMake installation and your pcre
+ source and build directories.
+ The following instructions were contributed by a PCRE user.
 .  Install the latest CMake version available from http://www.cmake.org/, 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.
+     directory such as C:\pcre. You should ensure your local date and time
+     is not earlier than the file dates in your source dir if the release is
+     very new.
-.  Create a new, empty build directory, for example C:\pcre\build\
+.  Create a new, empty build directory, preferably a subdirectory of the
+     source dir. For example, C:\pcre\pcre-xx\build.
 .  Run cmake-gui from the Shell envirornment of your build tool, for example,
      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
+.  Enter C:\pcre\pcre-xx and C:\pcre\pcre-xx\build for the source and build
      directories, respectively.
 .  Hit the "Configure" button.
-Line 304 
 were contributed by a PCRE user.
+Line 331 
 were contributed by a PCRE user.
 .  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 or other PCRE optional features.
 .  Hit "Configure" again. The adjacent "Generate" button should now be
      active.
 . Hit "Generate".
-Line 315 
 were contributed by a PCRE user.
+Line 342 
 were contributed by a PCRE user.
 . The build directory should now contain a usable build system, be it a
      solution file for Visual Studio, makefiles for MinGW, etc. Exit from
      cmake-gui and use the generated build system with your compiler or IDE.
+     E.g., for MinGW you can run "make", or for Visual Studio, open the PCRE
+     solution, select the desired configuration (Debug, or Release, etc.) and
+     build the ALL_BUILD project.
+. If during configuration with cmake-gui you've elected to build the test
+     programs, you can execute them by building the test project. E.g., for
+     MinGW: "make test"; for Visual Studio build the RUN_TESTS project. The
+     most recent build configuration is targeted by the tests. A summary of
+     test results is presented. Complete test output is subsequently
+     available for review in Testing\Temporary under your build dir.
  USE OF RELATIVE PATHS WITH CMAKE ON WINDOWS
-Line 347 
 RelativePath="pcre_chartables.c.rule">
+Line 383 
 RelativePath="pcre_chartables.c.rule">
  TESTING WITH RUNTEST.BAT
-. Copy RunTest.bat into the directory where pcretest.exe has been created.
+ If configured with CMake, building the test project ("make test" or building
+ ALL_TESTS in Visual Studio) creates (and runs) pcre_test.bat (and depending
+ on your configuration options, possibly other test programs) in the build
+ directory. Pcre_test.bat runs RunTest.Bat with correct source and exe paths.
+ For manual testing with RunTest.bat, provided the build dir is a subdirectory
+ of the source directory: Open command shell window. Chdir to the location
+ of your pcretest.exe and pcregrep.exe programs. Call RunTest.bat with
+ "..\RunTest.Bat" or "..\..\RunTest.bat" as appropriate.
+ To run only a particular test with RunTest.Bat provide a test number argument.
-. Edit RunTest.bat and insert a line that indentifies the relative location of
+ Otherwise:
-    the pcre source, e.g.:
-    set srcdir=..\pcre-7.4-RC3
+. Copy RunTest.bat into the directory where pcretest.exe and pcregrep.exe
+    have been created.
-. Run RunTest.bat from a command shell environment. Test outputs will
+. Edit RunTest.bat to indentify the full or relative location of
-    automatically be compared to expected results, and discrepancies will
+    the pcre source (wherein which the testdata folder resides), e.g.:
-    identified in the console output.
-. To test pcrecpp, run pcrecpp_unittest.exe, pcre_stringpiece_unittest.exe and
+    set srcdir=C:\pcre\pcre-8.20
-    pcre_scanner_unittest.exe.
+. In a Windows command environment, chdir to the location of your bat and
+ exe programs.
+. Run RunTest.bat. Test outputs will automatically be compared to expected
+ results, and discrepancies will be identified in the console output.
+ To independently test the just-in-time compiler, run pcre_jit_test.exe.
+ To test pcrecpp, run pcrecpp_unittest.exe, pcre_stringpiece_unittest.exe and
+ pcre_scanner_unittest.exe.
  BUILDING UNDER WINDOWS WITH BCC5.5
-Line 460 
 I built pcre on OpenVOS Release 17.0.1at
+Line 513 
 I built pcre on OpenVOS Release 17.0.1at
  problems. I used the following packages to build PCRE:
    ftp://ftp.stratus.com/pub/vos/posix/ga/posix.save.evf.gz
  Please read and follow the instructions that come with these packages. To start
  the build of pcre, from the root of the package type:
-Line 487 
 optional component I chose to disable it
+Line 540 
 optional component I chose to disable it
 . Known Problems
- I ran a the test suite, but you will have to be your own judge of whether this
+ I ran the test suite, but you will have to be your own judge of whether this
  command, and this port, suits your purposes. If you find any problems that
  appear to be related to the port itself, please let me know. Please see the
  build.log file in the root of the package also.
  =========================
- Last Updated: 09 September 2009
+ Last Updated: 9 October 2011
  ****

 Legend:



Removed from v.441
 


changed lines


 
Added in v.727
 Legend:



Removed from v.441
 


changed lines


 
Added in v.727
-Removed from v.441
+Added in v.727

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12