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

Diff of /code/trunk/README

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

revision 654 by ph10, Tue Aug 2 11:00:40 2011 UTC revision 672 by ph10, Tue Aug 23 16:45:55 2011 UTC
# Line 173  library. They are also documented in the Line 173  library. They are also documented in the
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 255  library. They are also documented in the Line 259  library. They are also documented in the
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 317  library. They are also documented in the Line 322  library. They are also documented in the
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    . RunGrepTest          script for running tests on the pcregrep command
335    
336  Versions of config.h and pcre.h are distributed in the PCRE tarballs under the  Versions of config.h and pcre.h are distributed in the PCRE tarballs under the
337  names config.h.generic and pcre.h.generic. These are provided for those who  names config.h.generic and pcre.h.generic. These are provided for those who
# Line 333  or CMake, the .generic versions are not Line 340  or CMake, the .generic versions are not
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 343  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 368  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 381  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 395  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 533  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 587  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.pl  
 script, provided you are running Perl 5.8 or higher.  
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 (which is Perl-5.10 compatible) checks the support for Unicode  The sixth test (which is Perl-5.10 compatible) checks the support for Unicode
617  character properties. It it not run automatically unless PCRE is built with  character properties. This file can be also fed directly to the perltest.pl
618  Unicode property support. To to this you must set --enable-unicode-properties  script, provided you are running Perl 5.10 or higher.
 when running "configure".  
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.
 automatically unless PCRE is build with the relevant support.  
623    
624  The tenth test checks some internal offsets and code size features; it is run  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  only when the default "link size" of 2 is set (in other cases the sizes
626  change).  change) and when Unicode property support is enabled.
627    
628  The eleventh test checks out features that are new in Perl 5.10, and the  The eleventh and twelfth tests check out features that are new in Perl 5.10,
629  twelfth test checks a number internals and non-Perl features concerned with  without and with UTF-8 support, respectively. This file can be also fed
630  Unicode property support. It it not run automatically unless PCRE is built with  directly to the perltest.pl script, provided you are running Perl 5.10 or
631  Unicode property support. To to this you must set --enable-unicode-properties  higher.
632  when running "configure".  
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 693  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 709  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 775  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 811  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: 02 August 2011  Last updated: 23 August 2011

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

  ViewVC Help
Powered by ViewVC 1.1.5