/[pcre]/code/trunk/README

Diff of /code/trunk/README

Parent Directory | Revision Log | View Patch Patch

-revision 75 by nigel,
Sat Feb 24 21:40:37 2007 UTC
+revision 77 by nigel,
Sat Feb 24 21:40:45 2007 UTC
 Line 7 
 The latest release of PCRE is always ava
  Please read the NEWS file if you are upgrading from a previous release.
- PCRE has its own native API, but a set of "wrapper" functions that are based on
- the POSIX API are also supplied in the library libpcreposix. Note that this
+ The PCRE APIs
- just provides a POSIX calling interface to PCRE: the regular expressions
+ -------------
- themselves still follow Perl syntax and semantics. The header file
- for the POSIX-style functions is called pcreposix.h. The official POSIX name is
+ PCRE is written in C, and it has its own API. The distribution now includes a
- regex.h, but I didn't want to risk possible problems with existing files of
+ set of C++ wrapper functions, courtesy of Google Inc. (see the pcrecpp man page
- that name by distributing it that way. To use it with an existing program that
+ for details).
- uses the POSIX API, it will have to be renamed or pointed at by a link.
+ Also included are a set of C wrapper functions that are based on the POSIX
+ API. These end up in the library called libpcreposix. Note that this just
+ provides a POSIX calling interface to PCRE: the regular expressions themselves
+ still follow Perl syntax and semantics. The header file for the POSIX-style
+ functions is called pcreposix.h. The official POSIX name is regex.h, but I
+ didn't want to risk possible problems with existing files of that name by
+ distributing it that way. To use it with an existing program that uses the
+ POSIX API, it will have to be renamed or pointed at by a link.
  If you are using the POSIX interface to PCRE and there is already a POSIX regex
  library installed on your system, you must take care when linking programs to
-Line 112 
 library. You can read more about them in
+Line 120 
 library. You can read more about them in
    on the "configure" command.
- . PCRE has a counter which can be set to limit the amount of resources it uses.
+ . PCRE has a counter that can be set to limit the amount of resources it uses.
    If the limit is exceeded during a match, the match fails. The default is ten
    million. You can change the default by setting, for example,
-Line 130 
 library. You can read more about them in
+Line 138 
 library. You can read more about them in
    is a representation of the compiled pattern, and this changes with the link
    size.
- . You can build PCRE so that its match() function does not call itself
+ . You can build PCRE so that its internal match() function that is called from
-   recursively. Instead, it uses blocks of data from the heap via special
+   pcre_exec() does not call itself recursively. Instead, it uses blocks of data
-   functions pcre_stack_malloc() and pcre_stack_free() to save data that would
+   from the heap via special functions pcre_stack_malloc() and pcre_stack_free()
-   otherwise be saved on the stack. To build PCRE like this, use
+   to save data that would otherwise be saved on the stack. To build PCRE like
+   this, use
    --disable-stack-for-recursion
    on the "configure" command. PCRE runs more slowly in this mode, but it may be
-   necessary in environments with limited stack sizes.
+   necessary in environments with limited stack sizes. This applies only to the
+   pcre_exec() function; it does not apply to pcre_dfa_exec(), which does not
+   use deeply nested recursion.
+ The "configure" script builds eight files for the basic C library:
+ . pcre.h is the header file for C programs that call PCRE
+ . Makefile is the makefile that builds the library
+ . config.h contains build-time configuration options for the library
+ . pcre-config is a script that shows the settings of "configure" options
+ . libpcre.pc is data for the pkg-config command
+ . libtool is a script that builds shared and/or static libraries
+ . RunTest is a script for running tests on the library
+ . RunGrepTest is a script for running tests on the pcregrep command
- The "configure" script builds seven files:
+ In addition, if a C++ compiler is found, the following are also built:
- . pcre.h is build by copying pcre.in and making substitutions
+ . pcrecpp.h is the header file for programs that call PCRE via the C++ wrapper
- . Makefile is built by copying Makefile.in and making substitutions.
+ . pcre_stringpiece.h is the header for the C++ "stringpiece" functions
- . config.h is built by copying config.in and making substitutions.
- . pcre-config is built by copying pcre-config.in and making substitutions.
- . libpcre.pc is data for the pkg-config command, built from libpcre.pc.in
- . libtool is a script that builds shared and/or static libraries
- . RunTest is a script for running tests
- Once "configure" has run, you can run "make". It builds two libraries called
+ The "configure" script also creates config.status, which is an executable
+ script that can be run to recreate the configuration, and config.log, which
+ contains compiler output from tests that "configure" runs.
+ Once "configure" has run, you can run "make". It builds two libraries, called
  libpcre and libpcreposix, a test program called pcretest, and the pcregrep
- command. You can use "make install" to copy these, the public header files
+ command. If a C++ compiler was found on your system, it also builds the C++
- pcre.h and pcreposix.h, and the man pages to appropriate live directories on
+ wrapper library, which is called libpcrecpp, and some test programs called
- your system, in the normal way.
+ pcrecpp_unittest, pcre_scanner_unittest, and pcre_stringpiece_unittest.
+ The command "make test" runs all the appropriate tests. Details of the PCRE
+ tests are given in a separate section of this document, below.
+ You can use "make install" to copy the libraries, the public header files
+ pcre.h, pcreposix.h, pcrecpp.h, and pcre_stringpiece.h (the last two only if
+ the C++ wrapper was built), and the man pages to appropriate live directories
+ on your system, in the normal way.
+ If you want to remove PCRE from your system, you can run "make uninstall".
+ This removes all the files that "make install" installed. However, it does not
+ remove any directories, because these are often shared with other programs.
  Retrieving configuration information on Unix-like systems
-Line 187 
 pkgconfig.
+Line 220 
 pkgconfig.
  Shared libraries on Unix-like systems
  -------------------------------------
- The default distribution builds PCRE as two shared libraries and two static
+ The default distribution builds PCRE as shared libraries and static libraries,
- libraries, as long as the operating system supports shared libraries. Shared
+ as long as the operating system supports shared libraries. Shared library
- library support relies on the "libtool" script which is built as part of the
+ support relies on the "libtool" script which is built as part of the
  "configure" process.
  The libtool script is used to compile and link both shared and static
-Line 218 
 order to cross-compile PCRE for some oth
+Line 251 
 order to cross-compile PCRE for some oth
  process, the dftables.c source file is compiled *and run* on the local host, in
  order to generate the default character tables (the chartables.c file). It
  therefore needs to be compiled with the local compiler, not the cross compiler.
- You can do this by specifying CC_FOR_BUILD (and if necessary CFLAGS_FOR_BUILD)
+ You can do this by specifying CC_FOR_BUILD (and if necessary CFLAGS_FOR_BUILD;
+ there are also CXX_FOR_BUILD and CXXFLAGS_FOR_BUILD for the C++ wrapper)
  when calling the "configure" command. If they are not specified, they default
  to the values of CC and CFLAGS.
-Line 240 
 Testing PCRE
+Line 274 
 Testing PCRE
  ------------
  To test PCRE on a Unix system, run the RunTest script that is created by the
- configuring process. (This can also be run by "make runtest", "make check", or
+ configuring process. There is also a script called RunGrepTest that tests the
- "make test".) For other systems, see the instructions in NON-UNIX-USE.
+ options of the pcregrep command. If the C++ wrapper library is build, three
+ test programs called pcrecpp_unittest, pcre_scanner_unittest, and
- The script runs the pcretest test program (which is documented in its own man
+ pcre_stringpiece_unittest are provided.
- page) on each of the testinput files (in the testdata directory) in turn,
- and compares the output with the contents of the corresponding testoutput file.
+ Both the scripts and all the program tests are run if you obey "make runtest",
- A file called testtry is used to hold the main output from pcretest
+ "make check", or "make test". For other systems, see the instructions in
+ NON-UNIX-USE.
+ The RunTest script runs the pcretest test program (which is documented in its
+ own man page) on each of the testinput files (in the testdata directory) in
+ turn, and compares the output with the contents of the corresponding testoutput
+ file. A file called testtry is used to hold the main output from pcretest
  (testsavedregex is also used as a working file). To run pcretest on just one of
  the test files, give its number as an argument to RunTest, for example:
-Line 294 
 commented in the script, can be be used.
+Line 334 
 commented in the script, can be be used.
  The fifth test checks error handling with UTF-8 encoding, and internal UTF-8
  features of PCRE that are not relevant to Perl.
- The sixth and final test checks the support for Unicode character properties.
+ The sixth and test checks the support for Unicode character properties. It it
- It it not run automatically unless PCRE is built with Unicode property support.
+ not run automatically unless PCRE is built with Unicode property support. To to
- To to this you must set --enable-unicode-properties when running "configure".
+ this you must set --enable-unicode-properties when running "configure".
+ The seventh, eighth, and ninth tests check the pcre_dfa_exec() alternative
+ matching function, in non-UTF-8 mode, UTF-8 mode, and UTF-8 mode with Unicode
+ property support, respectively. The eighth and ninth tests are not run
+ automatically unless PCRE is build with the relevant support.
  Character tables
-Line 348 
 The distribution should contain the foll
+Line 393 
 The distribution should contain the foll
    dftables.c            auxiliary program for building chartables.c
-   get.c                 )
-   maketables.c          )
-   study.c               ) source of the functions
-   pcre.c                )   in the library
    pcreposix.c           )
-   printint.c            )
+   pcre_compile.c        )
+   pcre_config.c         )
+   pcre_dfa_exec.c       )
+   pcre_exec.c           )
+   pcre_fullinfo.c       )
+   pcre_get.c            ) sources for the functions in the library,
+   pcre_globals.c        )   and some internal functions that they use
+   pcre_info.c           )
+   pcre_maketables.c     )
+   pcre_ord2utf8.c       )
+   pcre_printint.c       )
+   pcre_study.c          )
+   pcre_tables.c         )
+   pcre_try_flipped.c    )
+   pcre_ucp_findchar.c   )
+   pcre_valid_utf8.c     )
+   pcre_version.c        )
+   pcre_xclass.c         )
-   ucp.c                 )
+   ucp_findchar.c        )
    ucp.h                 ) source for the code that is used for
    ucpinternal.h         )   Unicode property handling
    ucptable.c            )
-Line 364 
 The distribution should contain the foll
+Line 422 
 The distribution should contain the foll
    pcre.in               "source" for the header for the external API; pcre.h
                            is built from this by "configure"
    pcreposix.h           header for the external POSIX wrapper API
-   internal.h            header for internal use
+   pcre_internal.h       header for internal use
    config.in             template for config.h, which is built by configure
+   pcrecpp.h.in          "source" for the header file for the C++ wrapper
+   pcrecpp.cc            )
+   pcre_scanner.cc       ) source for the C++ wrapper library
+   pcre_stringpiece.h.in "source" for pcre_stringpiece.h, the header for the
+                           C++ stringpiece functions
+   pcre_stringpiece.cc   source for the C++ stringpiece functions
  (B) Auxiliary files:
    AUTHORS               information about the author of PCRE
-Line 379 
 The distribution should contain the foll
+Line 445 
 The distribution should contain the foll
    NON-UNIX-USE          notes on building PCRE on non-Unix systems
    README                this file
    RunTest.in            template for a Unix shell script for running tests
+   RunGrepTest.in        template for a Unix shell script for pcregrep tests
    config.guess          ) files used by libtool,
    config.sub            )   used only when building a shared library
    configure             a configuring shell script (built by autoconf)
-Line 399 
 The distribution should contain the foll
+Line 466 
 The distribution should contain the foll
    perltest              Perl test program
    pcregrep.c            source of a grep utility that uses PCRE
    pcre-config.in        source of script which retains PCRE information
-   testdata/testinput1   test data, compatible with Perl
+   pcrecpp_unittest.c           )
-   testdata/testinput2   test data for error messages and non-Perl things
+   pcre_scanner_unittest.c      ) test programs for the C++ wrapper
-   testdata/testinput3   test data for locale-specific tests
+   pcre_stringpiece_unittest.c  )
-   testdata/testinput4   test data for UTF-8 tests compatible with Perl
+   testdata/testinput*   test data for main library tests
-   testdata/testinput5   test data for other UTF-8 tests
+   testdata/testoutput*  expected test results
-   testdata/testinput6   test data for Unicode property support tests
+   testdata/grep*        input and output for pcregrep tests
-   testdata/testoutput1  test results corresponding to testinput1
-   testdata/testoutput2  test results corresponding to testinput2
-   testdata/testoutput3  test results corresponding to testinput3
-   testdata/testoutput4  test results corresponding to testinput4
-   testdata/testoutput5  test results corresponding to testinput5
-   testdata/testoutput6  test results corresponding to testinput6
  (C) Auxiliary files for Win32 DLL
-   dll.mk
    libpcre.def
    libpcreposix.def
    pcre.def
-Line 423 
 The distribution should contain the foll
+Line 483 
 The distribution should contain the foll
    makevp.bat
- Philip Hazel <ph10@cam.ac.uk>
+ Philip Hazel
- September 2004
+ Email local part: ph10
+ Email domain: cam.ac.uk
+ June 2005

 Legend:



Removed from v.75
 


changed lines


 
Added in v.77
 Legend:



Removed from v.75
 


changed lines


 
Added in v.77
-Removed from v.75
+Added in v.77

	ViewVC Help
Powered by ViewVC 1.1.5