/[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 691 by ph10, Sun Sep 11 14:31:21 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    . When JIT support is enabled, pcregrep automatically makes use of it, unless
184      you add --disable-pcregrep-jit to the "configure" command.
185    
186  . 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
187    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
188    code for handling UTF-8 is not included in the library. Even when included,    code for handling UTF-8 is not included in the library. Even when included,
# Line 242  library. You can read more about them in Line 264  library. You can read more about them in
264    
265    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
266    necessary in environments with limited stack sizes. This applies only to the    necessary in environments with limited stack sizes. This applies only to the
267    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
268    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
269    pcrestack man page.    pcre_dfa_exec(), which does not use deeply nested recursion. There is a
270      discussion about stack sizes in the pcrestack man page.
271    
272  . For speed, PCRE uses four tables for manipulating and identifying characters  . For speed, PCRE uses four tables for manipulating and identifying characters
273    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 297  library. You can read more about them in
297    
298    Of course, the relevant libraries must be installed on your system.    Of course, the relevant libraries must be installed on your system.
299    
300    . The default size of internal buffer used by pcregrep can be set by, for
301      example:
302    
303      --with-pcregrep-bufsize=50K
304    
305      The default value is 20K.
306    
307  . 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
308    library, by specifying    library, by specifying
309    
# Line 297  library. You can read more about them in Line 327  library. You can read more about them in
327    
328  The "configure" script builds the following files for the basic C library:  The "configure" script builds the following files for the basic C library:
329    
330  . Makefile is the makefile that builds the library  . Makefile             the makefile that builds the library
331  . config.h contains build-time configuration options for the library  . config.h             build-time configuration options for the library
332  . pcre.h is the public PCRE header file  . pcre.h               the public PCRE header file
333  . pcre-config is a script that shows the settings of "configure" options  . pcre-config          script that shows the building settings such as CFLAGS
334  . libpcre.pc is data for the pkg-config command                           that were set for "configure"
335  . libtool is a script that builds shared and/or static libraries  . libpcre.pc         ) data for the pkg-config command
336  . RunTest is a script for running tests on the basic C library  . libpcreposix.pc    )
337  . RunGrepTest is a script for running tests on the pcregrep command  . libtool              script that builds shared and/or static libraries
338    . RunTest              script for running tests on the basic C library
339  Versions of config.h and pcre.h are distributed in the PCRE tarballs under  . RunGrepTest          script for running tests on the pcregrep command
340  the names config.h.generic and pcre.h.generic. These are provided for the  
341  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
342  you use "configure", the .generic versions are not used.  names config.h.generic and pcre.h.generic. These are provided for those who
343    have to built PCRE without using "configure" or CMake. If you use "configure"
344    or CMake, the .generic versions are not used.
345    
346  If a C++ compiler is found, the following files are also built:  If a C++ compiler is found, the following files are also built:
347    
348  . libpcrecpp.pc is data for the pkg-config command  . libpcrecpp.pc        data for the pkg-config command
349  . 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
350  . pcre_stringpiece.h is the header for the C++ "stringpiece" functions  . pcre_stringpiece.h   header for the C++ "stringpiece" functions
351    
352  The "configure" script also creates config.status, which is an executable  The "configure" script also creates config.status, which is an executable
353  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 355  contains compiler output from tests that
355    
356  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
357  libpcre and libpcreposix, a test program called pcretest, and the pcregrep  libpcre and libpcreposix, a test program called pcretest, and the pcregrep
358  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
359  wrapper library, which is called libpcrecpp, and some test programs called  with --disable-cpp, "make" also builds the C++ wrapper library, which is called
360  pcrecpp_unittest, pcre_scanner_unittest, and pcre_stringpiece_unittest.  libpcrecpp, and some test programs called pcrecpp_unittest,
361  Building the C++ wrapper can be disabled by adding --disable-cpp to the  pcre_scanner_unittest, and pcre_stringpiece_unittest. If you enabled JIT
362  "configure" command.  support with --enable-jit, a test program called pcre_jit_test is also built.
363    
364  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
365  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 380  system. The following are installed (fil
380    
381    Configuration information (lib/pkgconfig):    Configuration information (lib/pkgconfig):
382      libpcre.pc      libpcre.pc
383        libpcreposix.pc
384      libpcrecpp.pc (if C++ support is enabled)      libpcrecpp.pc (if C++ support is enabled)
385    
386    Header files (include):    Header files (include):
# Line 361  system. The following are installed (fil Line 394  system. The following are installed (fil
394    Man pages (share/man/man{1,3}):    Man pages (share/man/man{1,3}):
395      pcregrep.1      pcregrep.1
396      pcretest.1      pcretest.1
397        pcre-config.1
398      pcre.3      pcre.3
399      pcre*.3 (lots more pages, all starting "pcre")      pcre*.3 (lots more pages, all starting "pcre")
400    
# Line 375  system. The following are installed (fil Line 409  system. The following are installed (fil
409      LICENCE      LICENCE
410      NEWS      NEWS
411      README      README
412      pcre.txt       (a concatenation of the man(3) pages)      pcre.txt         (a concatenation of the man(3) pages)
413      pcretest.txt   the pcretest man page      pcretest.txt     the pcretest man page
414      pcregrep.txt   the pcregrep man page      pcregrep.txt     the pcregrep man page
415        pcre-config.txt  the pcre-config man page
416    
417  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".
418  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 509  running the "configure" script:
509    CXXLDFLAGS="-lstd_v2 -lCsup_v2"    CXXLDFLAGS="-lstd_v2 -lCsup_v2"
510    
511    
512    Using Sun's compilers for Solaris
513    ---------------------------------
514    
515    A user reports that the following configurations work on Solaris 9 sparcv9 and
516    Solaris 9 x86 (32-bit):
517    
518      Solaris 9 sparcv9: ./configure --disable-cpp CC=/bin/cc CFLAGS="-m64 -g"
519      Solaris 9 x86:     ./configure --disable-cpp CC=/bin/cc CFLAGS="-g"
520    
521    
522    Using PCRE from MySQL
523    ---------------------
524    
525    On systems where both PCRE and MySQL are installed, it is possible to make use
526    of PCRE from within MySQL, as an alternative to the built-in pattern matching.
527    There is a web page that tells you how to do this:
528    
529      http://www.mysqludf.org/lib_mysqludf_preg/index.php
530    
531    
532  Making new tarballs  Making new tarballs
533  -------------------  -------------------
534    
# Line 493  To test the basic PCRE library on a Unix Line 548  To test the basic PCRE library on a Unix
548  created by the configuring process. There is also a script called RunGrepTest  created by the configuring process. There is also a script called RunGrepTest
549  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
550  built, three test programs called pcrecpp_unittest, pcre_scanner_unittest, and  built, three test programs called pcrecpp_unittest, pcre_scanner_unittest, and
551  pcre_stringpiece_unittest are also built.  pcre_stringpiece_unittest are also built. When JIT support is enabled, another
552    test program called pcre_jit_test is built.
553    
554  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
555  "make test". For other systems, see the instructions in NON-UNIX-USE.  "make test". For other systems, see the instructions in NON-UNIX-USE.
556    
557  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
558  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
559  turn, and compares the output with the contents of the corresponding testoutput  directory, and compares the output with the contents of the corresponding
560  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
561    were selected. For example, the tests for UTF-8 support are run only if
562    --enable-utf8 was used. RunTest outputs a comment when it skips a test.
563    
564    Many of the tests that are not skipped are run up to three times. The second
565    run forces pcre_study() to be called for all patterns except for a few in some
566    tests that are marked "never study" (see the pcretest program for how this is
567    done). If JIT support is available, the non-DFA tests are run a third time,
568    this time with a forced pcre_study() with the PCRE_STUDY_JIT_COMPILE option.
569    
570    RunTest uses a file called testtry to hold the main output from pcretest
571  (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
572  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:
573    
574    RunTest 2    RunTest 2
575    
576  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
577  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
578  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.  
579    
580  The second set of tests check pcre_fullinfo(), pcre_info(), pcre_study(),  The second set of tests check pcre_fullinfo(), pcre_info(), pcre_study(),
581  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 612  RunTest.bat. The version of RunTest.bat
612  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
613  document entitled NON-UNIX-USE.]  document entitled NON-UNIX-USE.]
614    
615  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
616  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.)  
617    
618  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
619  features of PCRE that are not relevant to Perl.  features of PCRE that are not relevant to Perl.
620    
621  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
622  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
623  this you must set --enable-unicode-properties when running "configure".  script, provided you are running Perl 5.10 or higher.
624    
625  The seventh, eighth, and ninth tests check the pcre_dfa_exec() alternative  The seventh, eighth, and ninth tests check the pcre_dfa_exec() alternative
626  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
627  property support, respectively. The eighth and ninth tests are not run  property support, respectively.
628  automatically unless PCRE is build with the relevant support.  
629    The tenth test checks some internal offsets and code size features; it is run
630    only when the default "link size" of 2 is set (in other cases the sizes
631    change) and when Unicode property support is enabled.
632    
633    The eleventh and twelfth tests check out features that are new in Perl 5.10,
634    without and with UTF-8 support, respectively. This file can be also fed
635    directly to the perltest.pl script, provided you are running Perl 5.10 or
636    higher.
637    
638    The thirteenth test checks a number internals and non-Perl features concerned
639    with Unicode property support.
640    
641    The fourteenth test is run only when JIT support is available, and the
642    fifteenth test is run only when JIT support is not available. They test some
643    JIT-specific features such as information output from pcretest about JIT
644    compilation.
645    
646    
647  Character tables  Character tables
# Line 643  The distribution should contain the foll Line 721  The distribution should contain the foll
721    pcre_get.c              ) sources for the functions in the library,    pcre_get.c              ) sources for the functions in the library,
722    pcre_globals.c          )   and some internal functions that they use    pcre_globals.c          )   and some internal functions that they use
723    pcre_info.c             )    pcre_info.c             )
724      pcre_jit_compile.c      )
725    pcre_maketables.c       )    pcre_maketables.c       )
726    pcre_newline.c          )    pcre_newline.c          )
727    pcre_ord2utf8.c         )    pcre_ord2utf8.c         )
# Line 659  The distribution should contain the foll Line 738  The distribution should contain the foll
738    pcre.h.in               template for pcre.h when built by "configure"    pcre.h.in               template for pcre.h when built by "configure"
739    pcreposix.h             header for the external POSIX wrapper API    pcreposix.h             header for the external POSIX wrapper API
740    pcre_internal.h         header for internal use    pcre_internal.h         header for internal use
741      sljit/*                 16 files that make up the JIT compiler
742    ucp.h                   header for Unicode property handling    ucp.h                   header for Unicode property handling
743    
744    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 788  The distribution should contain the foll
788                            )   "configure" and config.h                            )   "configure" and config.h
789    depcomp                 ) script to find program dependencies, generated by    depcomp                 ) script to find program dependencies, generated by
790                            )   automake                            )   automake
791    doc/*.3                 man page sources for the PCRE functions    doc/*.3                 man page sources for PCRE
792    doc/*.1                 man page sources for pcregrep and pcretest    doc/*.1                 man page sources for pcregrep and pcretest
793    doc/index.html.src      the base HTML page    doc/index.html.src      the base HTML page
794    doc/html/*              HTML documentation    doc/html/*              HTML documentation
# Line 717  The distribution should contain the foll Line 797  The distribution should contain the foll
797    doc/perltest.txt        plain text documentation of Perl test program    doc/perltest.txt        plain text documentation of Perl test program
798    install-sh              a shell script for installing files    install-sh              a shell script for installing files
799    libpcre.pc.in           template for libpcre.pc for pkg-config    libpcre.pc.in           template for libpcre.pc for pkg-config
800      libpcreposix.pc.in      template for libpcreposix.pc for pkg-config
801    libpcrecpp.pc.in        template for libpcrecpp.pc for pkg-config    libpcrecpp.pc.in        template for libpcrecpp.pc for pkg-config
802    ltmain.sh               file used to build a libtool script    ltmain.sh               file used to build a libtool script
803    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 805  The distribution should contain the foll
805    mkinstalldirs           script for making install directories    mkinstalldirs           script for making install directories
806    perltest.pl             Perl test program    perltest.pl             Perl test program
807    pcre-config.in          source of script which retains PCRE information    pcre-config.in          source of script which retains PCRE information
808      pcre_jit_test.c         test program for the JIT compiler
809    pcrecpp_unittest.cc          )    pcrecpp_unittest.cc          )
810    pcre_scanner_unittest.cc     ) test programs for the C++ wrapper    pcre_scanner_unittest.cc     ) test programs for the C++ wrapper
811    pcre_stringpiece_unittest.cc )    pcre_stringpiece_unittest.cc )
# Line 760  The distribution should contain the foll Line 842  The distribution should contain the foll
842  Philip Hazel  Philip Hazel
843  Email local part: ph10  Email local part: ph10
844  Email domain: cam.ac.uk  Email domain: cam.ac.uk
845  Last updated: 17 March 2009  Last updated: 06 September 2011
Legend:
Removed from v.392  
changed lines
  Added in v.691
webmaster@exim.org
 ViewVC Help
Powered by ViewVC 1.1.12