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

Diff of /code/trunk/README

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

revision 392 by ph10, Tue Mar 17 21:30:30 2009 UTC revision 678 by ph10, Sun Aug 28 15:23:03 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 85  documentation is supplied in two other f Line 86  documentation is supplied in two other f
86       in various ways, and rooted in a file called index.html, is distributed in       in various ways, and rooted in a file called index.html, is distributed in
87       doc/html and installed in <prefix>/share/doc/pcre/html.       doc/html and installed in <prefix>/share/doc/pcre/html.
88    
89    Users of PCRE have contributed files containing the documentation for various
90    releases in CHM format. These can be found in the Contrib directory of the FTP
91    site (see next section).
92    
93    
94  Contributions by users of PCRE  Contributions by users of PCRE
95  ------------------------------  ------------------------------
# Line 107  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 154  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. This support is available only for certain hardware
180      architectures. If you try to enable it on an unsupported architecture, there
181      will be a compile time error.
182    
183  . 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
184    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 242  library. You can read more about them in Line 261  library. You can read more about them in
261    
262    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
263    necessary in environments with limited stack sizes. This applies only to the    necessary in environments with limited stack sizes. This applies only to the
264    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
265    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
266    pcrestack man page.    pcre_dfa_exec(), which does not use deeply nested recursion. There is a
267      discussion about stack sizes in the pcrestack man page.
268    
269  . For speed, PCRE uses four tables for manipulating and identifying characters  . For speed, PCRE uses four tables for manipulating and identifying characters
270    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 274  library. You can read more about them in Line 294  library. You can read more about them in
294    
295    Of course, the relevant libraries must be installed on your system.    Of course, the relevant libraries must be installed on your system.
296    
297    . The default size of internal buffer used by pcregrep can be set by, for
298      example:
299    
300      --with-pcregrep-bufsize=50K
301    
302      The default value is 20K.
303    
304  . 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
305    library, by specifying    library, by specifying
306    
# Line 297  library. You can read more about them in Line 324  library. You can read more about them in
324    
325  The "configure" script builds the following files for the basic C library:  The "configure" script builds the following files for the basic C library:
326    
327  . Makefile is the makefile that builds the library  . Makefile             the makefile that builds the library
328  . config.h contains build-time configuration options for the library  . config.h             build-time configuration options for the library
329  . pcre.h is the public PCRE header file  . pcre.h               the public PCRE header file
330  . pcre-config is a script that shows the settings of "configure" options  . pcre-config          script that shows the building settings such as CFLAGS
331  . libpcre.pc is data for the pkg-config command                           that were set for "configure"
332  . libtool is a script that builds shared and/or static libraries  . libpcre.pc         ) data for the pkg-config command
333  . RunTest is a script for running tests on the basic C library  . libpcreposix.pc    )
334  . RunGrepTest is a script for running tests on the pcregrep command  . libtool              script that builds shared and/or static libraries
335    . RunTest              script for running tests on the basic C library
336  Versions of config.h and pcre.h are distributed in the PCRE tarballs under  . RunGrepTest          script for running tests on the pcregrep command
337  the names config.h.generic and pcre.h.generic. These are provided for the  
338  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
339  you use "configure", the .generic versions are not used.  names config.h.generic and pcre.h.generic. These are provided for those who
340    have to built PCRE without using "configure" or CMake. If you use "configure"
341    or CMake, the .generic versions are not used.
342    
343  If a C++ compiler is found, the following files are also built:  If a C++ compiler is found, the following files are also built:
344    
345  . libpcrecpp.pc is data for the pkg-config command  . libpcrecpp.pc        data for the pkg-config command
346  . 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
347  . pcre_stringpiece.h is the header for the C++ "stringpiece" functions  . pcre_stringpiece.h   header for the C++ "stringpiece" functions
348    
349  The "configure" script also creates config.status, which is an executable  The "configure" script also creates config.status, which is an executable
350  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 323  contains compiler output from tests that Line 352  contains compiler output from tests that
352    
353  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
354  libpcre and libpcreposix, a test program called pcretest, and the pcregrep  libpcre and libpcreposix, a test program called pcretest, and the pcregrep
355  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
356  wrapper library, which is called libpcrecpp, and some test programs called  with --disable-cpp, "make" also builds the C++ wrapper library, which is called
357  pcrecpp_unittest, pcre_scanner_unittest, and pcre_stringpiece_unittest.  libpcrecpp, and some test programs called pcrecpp_unittest,
358  Building the C++ wrapper can be disabled by adding --disable-cpp to the  pcre_scanner_unittest, and pcre_stringpiece_unittest. If you enabled JIT
359  "configure" command.  support with --enable-jit, a test program called pcre_jit_test is also built.
360    
361  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
362  tests are given below in a separate section of this document.  tests are given below in a separate section of this document.
# Line 348  system. The following are installed (fil Line 377  system. The following are installed (fil
377    
378    Configuration information (lib/pkgconfig):    Configuration information (lib/pkgconfig):
379      libpcre.pc      libpcre.pc
380        libpcreposix.pc
381      libpcrecpp.pc (if C++ support is enabled)      libpcrecpp.pc (if C++ support is enabled)
382    
383    Header files (include):    Header files (include):
# Line 361  system. The following are installed (fil Line 391  system. The following are installed (fil
391    Man pages (share/man/man{1,3}):    Man pages (share/man/man{1,3}):
392      pcregrep.1      pcregrep.1
393      pcretest.1      pcretest.1
394        pcre-config.1
395      pcre.3      pcre.3
396      pcre*.3 (lots more pages, all starting "pcre")      pcre*.3 (lots more pages, all starting "pcre")
397    
# Line 375  system. The following are installed (fil Line 406  system. The following are installed (fil
406      LICENCE      LICENCE
407      NEWS      NEWS
408      README      README
409      pcre.txt       (a concatenation of the man(3) pages)      pcre.txt         (a concatenation of the man(3) pages)
410      pcretest.txt   the pcretest man page      pcretest.txt     the pcretest man page
411      pcregrep.txt   the pcregrep man page      pcregrep.txt     the pcregrep man page
412        pcre-config.txt  the pcre-config man page
413    
414  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".
415  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 474  running the "configure" script: Line 506  running the "configure" script:
506    CXXLDFLAGS="-lstd_v2 -lCsup_v2"    CXXLDFLAGS="-lstd_v2 -lCsup_v2"
507    
508    
509    Using Sun's compilers for Solaris
510    ---------------------------------
511    
512    A user reports that the following configurations work on Solaris 9 sparcv9 and
513    Solaris 9 x86 (32-bit):
514    
515      Solaris 9 sparcv9: ./configure --disable-cpp CC=/bin/cc CFLAGS="-m64 -g"
516      Solaris 9 x86:     ./configure --disable-cpp CC=/bin/cc CFLAGS="-g"
517    
518    
519    Using PCRE from MySQL
520    ---------------------
521    
522    On systems where both PCRE and MySQL are installed, it is possible to make use
523    of PCRE from within MySQL, as an alternative to the built-in pattern matching.
524    There is a web page that tells you how to do this:
525    
526      http://www.mysqludf.org/lib_mysqludf_preg/index.php
527    
528    
529  Making new tarballs  Making new tarballs
530  -------------------  -------------------
531    
# Line 493  To test the basic PCRE library on a Unix Line 545  To test the basic PCRE library on a Unix
545  created by the configuring process. There is also a script called RunGrepTest  created by the configuring process. There is also a script called RunGrepTest
546  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
547  built, three test programs called pcrecpp_unittest, pcre_scanner_unittest, and  built, three test programs called pcrecpp_unittest, pcre_scanner_unittest, and
548  pcre_stringpiece_unittest are also built.  pcre_stringpiece_unittest are also built. When JIT support is enabled, another
549    test program called pcre_jit_test is built.
550    
551  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
552  "make test". For other systems, see the instructions in NON-UNIX-USE.  "make test". For other systems, see the instructions in NON-UNIX-USE.
553    
554  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
555  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
556  turn, and compares the output with the contents of the corresponding testoutput  directory, and compares the output with the contents of the corresponding
557  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
558    were selected. For example, the tests for UTF-8 support are run only if
559    --enable-utf8 was used. RunTest outputs a comment when it skips a test.
560    
561    Many of the tests that are not skipped are run up to three times. The second
562    run forces pcre_study() to be called for all patterns except for a few in some
563    tests that are marked "never study" (see the pcretest program for how this is
564    done). If JIT support is available, the non-DFA tests are run a third time,
565    this time with a forced pcre_study() with the PCRE_STUDY_JIT_COMPILE option.
566    
567    RunTest uses a file called testtry to hold the main output from pcretest
568  (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
569  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:
570    
571    RunTest 2    RunTest 2
572    
573  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
574  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
575  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.  
576    
577  The second set of tests check pcre_fullinfo(), pcre_info(), pcre_study(),  The second set of tests check pcre_fullinfo(), pcre_info(), pcre_study(),
578  pcre_copy_substring(), pcre_get_substring(), pcre_get_substring_list(), error  pcre_copy_substring(), pcre_get_substring(), pcre_get_substring_list(), error
# Line 547  RunTest.bat. The version of RunTest.bat Line 609  RunTest.bat. The version of RunTest.bat
609  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
610  document entitled NON-UNIX-USE.]  document entitled NON-UNIX-USE.]
611    
612  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
613  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.)  
614    
615  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
616  features of PCRE that are not relevant to Perl.  features of PCRE that are not relevant to Perl.
617    
618  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
619  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
620  this you must set --enable-unicode-properties when running "configure".  script, provided you are running Perl 5.10 or higher.
621    
622  The seventh, eighth, and ninth tests check the pcre_dfa_exec() alternative  The seventh, eighth, and ninth tests check the pcre_dfa_exec() alternative
623  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
624  property support, respectively. The eighth and ninth tests are not run  property support, respectively.
625  automatically unless PCRE is build with the relevant support.  
626    The tenth test checks some internal offsets and code size features; it is run
627    only when the default "link size" of 2 is set (in other cases the sizes
628    change) and when Unicode property support is enabled.
629    
630    The eleventh and twelfth tests check out features that are new in Perl 5.10,
631    without and with UTF-8 support, respectively. This file can be also fed
632    directly to the perltest.pl script, provided you are running Perl 5.10 or
633    higher.
634    
635    The thirteenth test checks a number internals and non-Perl features concerned
636    with Unicode property support.
637    
638    The fourteenth test is run only when JIT support is available, and the
639    fifteenth test is run only when JIT support is not available. They test some
640    JIT-specific features such as information output from pcretest about JIT
641    compilation.
642    
643    
644  Character tables  Character tables
# Line 643  The distribution should contain the foll Line 718  The distribution should contain the foll
718    pcre_get.c              ) sources for the functions in the library,    pcre_get.c              ) sources for the functions in the library,
719    pcre_globals.c          )   and some internal functions that they use    pcre_globals.c          )   and some internal functions that they use
720    pcre_info.c             )    pcre_info.c             )
721      pcre_jit_compile.c      )
722    pcre_maketables.c       )    pcre_maketables.c       )
723    pcre_newline.c          )    pcre_newline.c          )
724    pcre_ord2utf8.c         )    pcre_ord2utf8.c         )
# Line 659  The distribution should contain the foll Line 735  The distribution should contain the foll
735    pcre.h.in               template for pcre.h when built by "configure"    pcre.h.in               template for pcre.h when built by "configure"
736    pcreposix.h             header for the external POSIX wrapper API    pcreposix.h             header for the external POSIX wrapper API
737    pcre_internal.h         header for internal use    pcre_internal.h         header for internal use
738      sljit/*                 16 files that make up the JIT compiler
739    ucp.h                   header for Unicode property handling    ucp.h                   header for Unicode property handling
740    
741    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 708  The distribution should contain the foll Line 785  The distribution should contain the foll
785                            )   "configure" and config.h                            )   "configure" and config.h
786    depcomp                 ) script to find program dependencies, generated by    depcomp                 ) script to find program dependencies, generated by
787                            )   automake                            )   automake
788    doc/*.3                 man page sources for the PCRE functions    doc/*.3                 man page sources for PCRE
789    doc/*.1                 man page sources for pcregrep and pcretest    doc/*.1                 man page sources for pcregrep and pcretest
790    doc/index.html.src      the base HTML page    doc/index.html.src      the base HTML page
791    doc/html/*              HTML documentation    doc/html/*              HTML documentation
# Line 717  The distribution should contain the foll Line 794  The distribution should contain the foll
794    doc/perltest.txt        plain text documentation of Perl test program    doc/perltest.txt        plain text documentation of Perl test program
795    install-sh              a shell script for installing files    install-sh              a shell script for installing files
796    libpcre.pc.in           template for libpcre.pc for pkg-config    libpcre.pc.in           template for libpcre.pc for pkg-config
797      libpcreposix.pc.in      template for libpcreposix.pc for pkg-config
798    libpcrecpp.pc.in        template for libpcrecpp.pc for pkg-config    libpcrecpp.pc.in        template for libpcrecpp.pc for pkg-config
799    ltmain.sh               file used to build a libtool script    ltmain.sh               file used to build a libtool script
800    missing                 ) common stub for a few missing GNU programs while    missing                 ) common stub for a few missing GNU programs while
# Line 724  The distribution should contain the foll Line 802  The distribution should contain the foll
802    mkinstalldirs           script for making install directories    mkinstalldirs           script for making install directories
803    perltest.pl             Perl test program    perltest.pl             Perl test program
804    pcre-config.in          source of script which retains PCRE information    pcre-config.in          source of script which retains PCRE information
805      pcre_jit_test.c         test program for the JIT compiler
806    pcrecpp_unittest.cc          )    pcrecpp_unittest.cc          )
807    pcre_scanner_unittest.cc     ) test programs for the C++ wrapper    pcre_scanner_unittest.cc     ) test programs for the C++ wrapper
808    pcre_stringpiece_unittest.cc )    pcre_stringpiece_unittest.cc )
# Line 760  The distribution should contain the foll Line 839  The distribution should contain the foll
839  Philip Hazel  Philip Hazel
840  Email local part: ph10  Email local part: ph10
841  Email domain: cam.ac.uk  Email domain: cam.ac.uk
842  Last updated: 17 March 2009  Last updated: 27 August 2011

Legend:
Removed from v.392  
changed lines
  Added in v.678

webmaster@exim.org
ViewVC Help
Powered by ViewVC 1.1.12