/[pcre]/code/trunk/README
ViewVC logotype

Diff of /code/trunk/README

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

revision 429 by ph10, Tue Sep 1 16:10:16 2009 UTC revision 672 by ph10, Tue Aug 23 16:45:55 2011 UTC
# Line 24  The contents of this README file are: Line 24  The contents of this README file are:
24    Shared libraries on Unix-like systems    Shared libraries on Unix-like systems
25    Cross-compiling on Unix-like systems    Cross-compiling on Unix-like systems
26    Using HP's ANSI C++ compiler (aCC)    Using HP's ANSI C++ compiler (aCC)
27      Using PCRE from MySQL
28    Making new tarballs    Making new tarballs
29    Testing PCRE    Testing PCRE
30    Character tables    Character tables
# Line 111  Building PCRE on non-Unix systems Line 112  Building PCRE on non-Unix systems
112  For a non-Unix system, please read the comments in the file NON-UNIX-USE,  For a non-Unix system, please read the comments in the file NON-UNIX-USE,
113  though if your system supports the use of "configure" and "make" you may be  though if your system supports the use of "configure" and "make" you may be
114  able to build PCRE in the same way as for Unix-like systems. PCRE can also be  able to build PCRE in the same way as for Unix-like systems. PCRE can also be
115  configured in many platform environments using the GUI facility of CMake's  configured in many platform environments using the GUI facility provided by
116  CMakeSetup. It creates Makefiles, solution files, etc.  CMake's cmake-gui command. This creates Makefiles, solution files, etc.
117    
118  PCRE has been compiled on many different operating systems. It should be  PCRE has been compiled on many different operating systems. It should be
119  straightforward to build PCRE on any system that has a Standard C compiler and  straightforward to build PCRE on any system that has a Standard C compiler and
# Line 158  possible to build it as a C++ library, t Line 159  possible to build it as a C++ library, t
159  does not have any features to support this.  does not have any features to support this.
160    
161  There are some optional features that can be included or omitted from the PCRE  There are some optional features that can be included or omitted from the PCRE
162  library. You can read more about them in the pcrebuild man page.  library. They are also documented in the pcrebuild man page.
163    
164    . By default, both shared and static libraries are built. You can change this
165      by adding one of these options to the "configure" command:
166    
167      --disable-shared
168      --disable-static
169    
170      (See also "Shared libraries on Unix-like systems" below.)
171    
172  . If you want to suppress the building of the C++ wrapper library, you can add  . If you want to suppress the building of the C++ wrapper library, you can add
173    --disable-cpp to the "configure" command. Otherwise, when "configure" is run,    --disable-cpp to the "configure" command. Otherwise, when "configure" is run,
174    it will try to find a C++ compiler and C++ header files, and if it succeeds,    it will try to find a C++ compiler and C++ header files, and if it succeeds,
175    it will try to build the C++ wrapper.    it will try to build the C++ wrapper.
176    
177    . If you want to include support for just-in-time compiling, which can give
178      large performance improvements on certain platforms, add --enable-jit to the
179      "configure" command.
180    
181  . If you want to make use of the support for UTF-8 Unicode character strings in  . If you want to make use of the support for UTF-8 Unicode character strings in
182    PCRE, you must add --enable-utf8 to the "configure" command. Without it, the    PCRE, you must add --enable-utf8 to the "configure" command. Without it, the
# Line 246  library. You can read more about them in Line 259  library. You can read more about them in
259    
260    on the "configure" command. PCRE runs more slowly in this mode, but it may be    on the "configure" command. PCRE runs more slowly in this mode, but it may be
261    necessary in environments with limited stack sizes. This applies only to the    necessary in environments with limited stack sizes. This applies only to the
262    pcre_exec() function; it does not apply to pcre_dfa_exec(), which does not    normal execution of the pcre_exec() function; if JIT support is being
263    use deeply nested recursion. There is a discussion about stack sizes in the    successfully used, it is not relevant. Equally, it does not apply to
264    pcrestack man page.    pcre_dfa_exec(), which does not use deeply nested recursion. There is a
265      discussion about stack sizes in the pcrestack man page.
266    
267  . For speed, PCRE uses four tables for manipulating and identifying characters  . For speed, PCRE uses four tables for manipulating and identifying characters
268    whose code point values are less than 256. By default, it uses a set of    whose code point values are less than 256. By default, it uses a set of
# Line 278  library. You can read more about them in Line 292  library. You can read more about them in
292    
293    Of course, the relevant libraries must be installed on your system.    Of course, the relevant libraries must be installed on your system.
294    
295    . The default size of internal buffer used by pcregrep can be set by, for
296      example:
297    
298      --with-pcregrep-bufsize=50K
299    
300      The default value is 20K.
301    
302  . It is possible to compile pcretest so that it links with the libreadline  . It is possible to compile pcretest so that it links with the libreadline
303    library, by specifying    library, by specifying
304    
# Line 301  library. You can read more about them in Line 322  library. You can read more about them in
322    
323  The "configure" script builds the following files for the basic C library:  The "configure" script builds the following files for the basic C library:
324    
325  . Makefile is the makefile that builds the library  . Makefile             the makefile that builds the library
326  . config.h contains build-time configuration options for the library  . config.h             build-time configuration options for the library
327  . pcre.h is the public PCRE header file  . pcre.h               the public PCRE header file
328  . pcre-config is a script that shows the settings of "configure" options  . pcre-config          script that shows the building settings such as CFLAGS
329  . libpcre.pc is data for the pkg-config command                           that were set for "configure"
330  . libtool is a script that builds shared and/or static libraries  . libpcre.pc         ) data for the pkg-config command
331  . RunTest is a script for running tests on the basic C library  . libpcreposix.pc    )
332  . RunGrepTest is a script for running tests on the pcregrep command  . libtool              script that builds shared and/or static libraries
333    . RunTest              script for running tests on the basic C library
334  Versions of config.h and pcre.h are distributed in the PCRE tarballs under  . RunGrepTest          script for running tests on the pcregrep command
335  the names config.h.generic and pcre.h.generic. These are provided for the  
336  benefit of those who have to built PCRE without the benefit of "configure". If  Versions of config.h and pcre.h are distributed in the PCRE tarballs under the
337  you use "configure", the .generic versions are not used.  names config.h.generic and pcre.h.generic. These are provided for those who
338    have to built PCRE without using "configure" or CMake. If you use "configure"
339    or CMake, the .generic versions are not used.
340    
341  If a C++ compiler is found, the following files are also built:  If a C++ compiler is found, the following files are also built:
342    
343  . libpcrecpp.pc is data for the pkg-config command  . libpcrecpp.pc        data for the pkg-config command
344  . pcrecpparg.h is a header file for programs that call PCRE via the C++ wrapper  . pcrecpparg.h         header file for calling PCRE via the C++ wrapper
345  . pcre_stringpiece.h is the header for the C++ "stringpiece" functions  . pcre_stringpiece.h   header for the C++ "stringpiece" functions
346    
347  The "configure" script also creates config.status, which is an executable  The "configure" script also creates config.status, which is an executable
348  script that can be run to recreate the configuration, and config.log, which  script that can be run to recreate the configuration, and config.log, which
# Line 327  contains compiler output from tests that Line 350  contains compiler output from tests that
350    
351  Once "configure" has run, you can run "make". It builds two libraries, called  Once "configure" has run, you can run "make". It builds two libraries, called
352  libpcre and libpcreposix, a test program called pcretest, and the pcregrep  libpcre and libpcreposix, a test program called pcretest, and the pcregrep
353  command. If a C++ compiler was found on your system, "make" also builds the C++  command. If a C++ compiler was found on your system, and you did not disable it
354  wrapper library, which is called libpcrecpp, and some test programs called  with --disable-cpp, "make" also builds the C++ wrapper library, which is called
355  pcrecpp_unittest, pcre_scanner_unittest, and pcre_stringpiece_unittest.  libpcrecpp, and some test programs called pcrecpp_unittest,
356  Building the C++ wrapper can be disabled by adding --disable-cpp to the  pcre_scanner_unittest, and pcre_stringpiece_unittest. If you enabled JIT
357  "configure" command.  support with --enable-jit, a test program called pcre_jit_test is also built.
358    
359  The command "make check" runs all the appropriate tests. Details of the PCRE  The command "make check" runs all the appropriate tests. Details of the PCRE
360  tests are given below in a separate section of this document.  tests are given below in a separate section of this document.
# Line 352  system. The following are installed (fil Line 375  system. The following are installed (fil
375    
376    Configuration information (lib/pkgconfig):    Configuration information (lib/pkgconfig):
377      libpcre.pc      libpcre.pc
378        libpcreposix.pc
379      libpcrecpp.pc (if C++ support is enabled)      libpcrecpp.pc (if C++ support is enabled)
380    
381    Header files (include):    Header files (include):
# Line 365  system. The following are installed (fil Line 389  system. The following are installed (fil
389    Man pages (share/man/man{1,3}):    Man pages (share/man/man{1,3}):
390      pcregrep.1      pcregrep.1
391      pcretest.1      pcretest.1
392        pcre-config.1
393      pcre.3      pcre.3
394      pcre*.3 (lots more pages, all starting "pcre")      pcre*.3 (lots more pages, all starting "pcre")
395    
# Line 379  system. The following are installed (fil Line 404  system. The following are installed (fil
404      LICENCE      LICENCE
405      NEWS      NEWS
406      README      README
407      pcre.txt       (a concatenation of the man(3) pages)      pcre.txt         (a concatenation of the man(3) pages)
408      pcretest.txt   the pcretest man page      pcretest.txt     the pcretest man page
409      pcregrep.txt   the pcregrep man page      pcregrep.txt     the pcregrep man page
410        pcre-config.txt  the pcre-config man page
411    
412  If you want to remove PCRE from your system, you can run "make uninstall".  If you want to remove PCRE from your system, you can run "make uninstall".
413  This removes all the files that "make install" installed. However, it does not  This removes all the files that "make install" installed. However, it does not
# Line 478  running the "configure" script: Line 504  running the "configure" script:
504    CXXLDFLAGS="-lstd_v2 -lCsup_v2"    CXXLDFLAGS="-lstd_v2 -lCsup_v2"
505    
506    
507    Using Sun's compilers for Solaris
508    ---------------------------------
509    
510    A user reports that the following configurations work on Solaris 9 sparcv9 and
511    Solaris 9 x86 (32-bit):
512    
513      Solaris 9 sparcv9: ./configure --disable-cpp CC=/bin/cc CFLAGS="-m64 -g"
514      Solaris 9 x86:     ./configure --disable-cpp CC=/bin/cc CFLAGS="-g"
515    
516    
517    Using PCRE from MySQL
518    ---------------------
519    
520    On systems where both PCRE and MySQL are installed, it is possible to make use
521    of PCRE from within MySQL, as an alternative to the built-in pattern matching.
522    There is a web page that tells you how to do this:
523    
524      http://www.mysqludf.org/lib_mysqludf_preg/index.php
525    
526    
527  Making new tarballs  Making new tarballs
528  -------------------  -------------------
529    
# Line 497  To test the basic PCRE library on a Unix Line 543  To test the basic PCRE library on a Unix
543  created by the configuring process. There is also a script called RunGrepTest  created by the configuring process. There is also a script called RunGrepTest
544  that tests the options of the pcregrep command. If the C++ wrapper library is  that tests the options of the pcregrep command. If the C++ wrapper library is
545  built, three test programs called pcrecpp_unittest, pcre_scanner_unittest, and  built, three test programs called pcrecpp_unittest, pcre_scanner_unittest, and
546  pcre_stringpiece_unittest are also built.  pcre_stringpiece_unittest are also built. When JIT support is enabled, another
547    test program called pcre_jit_test is built.
548    
549  Both the scripts and all the program tests are run if you obey "make check" or  Both the scripts and all the program tests are run if you obey "make check" or
550  "make test". For other systems, see the instructions in NON-UNIX-USE.  "make test". For other systems, see the instructions in NON-UNIX-USE.
551    
552  The RunTest script runs the pcretest test program (which is documented in its  The RunTest script runs the pcretest test program (which is documented in its
553  own man page) on each of the testinput files in the testdata directory in  own man page) on each of the relevant testinput files in the testdata
554  turn, and compares the output with the contents of the corresponding testoutput  directory, and compares the output with the contents of the corresponding
555  files. A file called testtry is used to hold the main output from pcretest  testoutput files. Some tests are relevant only when certain build-time options
556    were selected. For example, the tests for UTF-8 support are run only if
557    --enable-utf8 was used. RunTest outputs a comment when it skips a test.
558    
559    Many of the tests that are not skipped are run up to three times. The second
560    run forces pcre_study() to be called for all patterns except for a few in some
561    tests that are marked "never study" (see the pcretest program for how this is
562    done). If JIT support is available, the non-DFA tests are run a third time,
563    this time with a forced pcre_study() with the PCRE_STUDY_JIT_COMPILE option.
564    
565    RunTest uses a file called testtry to hold the main output from pcretest
566  (testsavedregex is also used as a working file). To run pcretest on just one of  (testsavedregex is also used as a working file). To run pcretest on just one of
567  the test files, give its number as an argument to RunTest, for example:  the test files, give its number as an argument to RunTest, for example:
568    
569    RunTest 2    RunTest 2
570    
571  The first test file can also be fed directly into the perltest.pl script to  The first test file can be fed directly into the perltest.pl script to check
572  check that Perl gives the same results. The only difference you should see is  that Perl gives the same results. The only difference you should see is in the
573  in the first few lines, where the Perl version is given instead of the PCRE  first few lines, where the Perl version is given instead of the PCRE version.
 version.  
574    
575  The second set of tests check pcre_fullinfo(), pcre_info(), pcre_study(),  The second set of tests check pcre_fullinfo(), pcre_info(), pcre_study(),
576  pcre_copy_substring(), pcre_get_substring(), pcre_get_substring_list(), error  pcre_copy_substring(), pcre_get_substring(), pcre_get_substring_list(), error
# Line 551  RunTest.bat. The version of RunTest.bat Line 607  RunTest.bat. The version of RunTest.bat
607  Windows versions of test 2. More info on using RunTest.bat is included in the  Windows versions of test 2. More info on using RunTest.bat is included in the
608  document entitled NON-UNIX-USE.]  document entitled NON-UNIX-USE.]
609    
610  The fourth test checks the UTF-8 support. It is not run automatically unless  The fourth test checks the UTF-8 support. This file can be also fed directly to
611  PCRE is built with UTF-8 support. To do this you must set --enable-utf8 when  the perltest.pl script, provided you are running Perl 5.8 or higher.
 running "configure". This file can be also fed directly to the perltest script,  
 provided you are running Perl 5.8 or higher. (For Perl 5.6, a small patch,  
 commented in the script, can be be used.)  
612    
613  The fifth test checks error handling with UTF-8 encoding, and internal UTF-8  The fifth test checks error handling with UTF-8 encoding, and internal UTF-8
614  features of PCRE that are not relevant to Perl.  features of PCRE that are not relevant to Perl.
615    
616  The sixth test checks the support for Unicode character properties. It it not  The sixth test (which is Perl-5.10 compatible) checks the support for Unicode
617  run automatically unless PCRE is built with Unicode property support. To to  character properties. This file can be also fed directly to the perltest.pl
618  this you must set --enable-unicode-properties when running "configure".  script, provided you are running Perl 5.10 or higher.
619    
620  The seventh, eighth, and ninth tests check the pcre_dfa_exec() alternative  The seventh, eighth, and ninth tests check the pcre_dfa_exec() alternative
621  matching function, in non-UTF-8 mode, UTF-8 mode, and UTF-8 mode with Unicode  matching function, in non-UTF-8 mode, UTF-8 mode, and UTF-8 mode with Unicode
622  property support, respectively. The eighth and ninth tests are not run  property support, respectively.
623  automatically unless PCRE is build with the relevant support.  
624    The tenth test checks some internal offsets and code size features; it is run
625    only when the default "link size" of 2 is set (in other cases the sizes
626    change) and when Unicode property support is enabled.
627    
628    The eleventh and twelfth tests check out features that are new in Perl 5.10,
629    without and with UTF-8 support, respectively. This file can be also fed
630    directly to the perltest.pl script, provided you are running Perl 5.10 or
631    higher.
632    
633    The thirteenth test checks a number internals and non-Perl features concerned
634    with Unicode property support.
635    
636    The fourteenth test is run only when JIT support is available, and the
637    fifteenth test is run only when JIT support is not available. They test some
638    JIT-specific features such as information output from pcretest about JIT
639    compilation.
640    
641    
642  Character tables  Character tables
# Line 647  The distribution should contain the foll Line 716  The distribution should contain the foll
716    pcre_get.c              ) sources for the functions in the library,    pcre_get.c              ) sources for the functions in the library,
717    pcre_globals.c          )   and some internal functions that they use    pcre_globals.c          )   and some internal functions that they use
718    pcre_info.c             )    pcre_info.c             )
719      pcre_jit_compile.c      )
720    pcre_maketables.c       )    pcre_maketables.c       )
721    pcre_newline.c          )    pcre_newline.c          )
722    pcre_ord2utf8.c         )    pcre_ord2utf8.c         )
# Line 663  The distribution should contain the foll Line 733  The distribution should contain the foll
733    pcre.h.in               template for pcre.h when built by "configure"    pcre.h.in               template for pcre.h when built by "configure"
734    pcreposix.h             header for the external POSIX wrapper API    pcreposix.h             header for the external POSIX wrapper API
735    pcre_internal.h         header for internal use    pcre_internal.h         header for internal use
736      sljit/*                 16 files that make up the JIT compiler
737    ucp.h                   header for Unicode property handling    ucp.h                   header for Unicode property handling
738    
739    config.h.in             template for config.h, which is built by "configure"    config.h.in             template for config.h, which is built by "configure"
# Line 721  The distribution should contain the foll Line 792  The distribution should contain the foll
792    doc/perltest.txt        plain text documentation of Perl test program    doc/perltest.txt        plain text documentation of Perl test program
793    install-sh              a shell script for installing files    install-sh              a shell script for installing files
794    libpcre.pc.in           template for libpcre.pc for pkg-config    libpcre.pc.in           template for libpcre.pc for pkg-config
795    libpcreposix.pc.in      template for libpcreposix.pc for pkg-config    libpcreposix.pc.in      template for libpcreposix.pc for pkg-config
796    libpcrecpp.pc.in        template for libpcrecpp.pc for pkg-config    libpcrecpp.pc.in        template for libpcrecpp.pc for pkg-config
797    ltmain.sh               file used to build a libtool script    ltmain.sh               file used to build a libtool script
798    missing                 ) common stub for a few missing GNU programs while    missing                 ) common stub for a few missing GNU programs while
# Line 729  The distribution should contain the foll Line 800  The distribution should contain the foll
800    mkinstalldirs           script for making install directories    mkinstalldirs           script for making install directories
801    perltest.pl             Perl test program    perltest.pl             Perl test program
802    pcre-config.in          source of script which retains PCRE information    pcre-config.in          source of script which retains PCRE information
803      pcre_jit_test.c         test program for the JIT compiler
804    pcrecpp_unittest.cc          )    pcrecpp_unittest.cc          )
805    pcre_scanner_unittest.cc     ) test programs for the C++ wrapper    pcre_scanner_unittest.cc     ) test programs for the C++ wrapper
806    pcre_stringpiece_unittest.cc )    pcre_stringpiece_unittest.cc )
# Line 765  The distribution should contain the foll Line 837  The distribution should contain the foll
837  Philip Hazel  Philip Hazel
838  Email local part: ph10  Email local part: ph10
839  Email domain: cam.ac.uk  Email domain: cam.ac.uk
840  Last updated: 01 September 2009  Last updated: 23 August 2011

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

webmaster@exim.org
ViewVC Help
Powered by ViewVC 1.1.12