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

Diff of /code/trunk/README

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

revision 43 by nigel, Sat Feb 24 21:39:21 2007 UTC revision 49 by nigel, Sat Feb 24 21:39:33 2007 UTC
# Line 7  The latest release of PCRE is always ava Line 7  The latest release of PCRE is always ava
7    
8  Please read the NEWS file if you are upgrading from a previous release.  Please read the NEWS file if you are upgrading from a previous release.
9    
10    PCRE has its own native API, but a set of "wrapper" functions that are based on
11    the POSIX API are also supplied in the library libpcreposix. Note that this
12    just provides a POSIX calling interface to PCRE: the regular expressions
13    themselves still follow Perl syntax and semantics. The header file
14    for the POSIX-style functions is called pcreposix.h. The official POSIX name is
15    regex.h, but I didn't want to risk possible problems with existing files of
16    that name by distributing it that way. To use it with an existing program that
17    uses the POSIX API, it will have to be renamed or pointed at by a link.
18    
19    
20  Building PCRE on a Unix system  Building PCRE on a Unix system
21  ------------------------------  ------------------------------
# Line 15  To build PCRE on a Unix system, run the Line 24  To build PCRE on a Unix system, run the
24  distribution directory. This is a standard GNU "autoconf" configuration script,  distribution directory. This is a standard GNU "autoconf" configuration script,
25  for which generic instructions are supplied in INSTALL. On many systems just  for which generic instructions are supplied in INSTALL. On many systems just
26  running "./configure" is sufficient, but the usual methods of changing standard  running "./configure" is sufficient, but the usual methods of changing standard
27  defaults are available. For example  defaults are available. For example,
28    
29  CFLAGS='-O2 -Wall' ./configure --prefix=/opt/local  CFLAGS='-O2 -Wall' ./configure --prefix=/opt/local
30    
31  specifies that the C compiler should be run with the flags '-O2 -Wall' instead  specifies that the C compiler should be run with the flags '-O2 -Wall' instead
32  of the default, and that "make install" should install PCRE under /opt/local  of the default, and that "make install" should install PCRE under /opt/local
33  instead of the default /usr/local. The "configure" script builds thre files:  instead of the default /usr/local.
34    
35    If you want to make use of the experimential, incomplete support for UTF-8
36    character strings in PCRE, you must add --enable-utf8 to the "configure"
37    command. Without it, the code for handling UTF-8 is not included in the
38    library. (Even when included, it still has to be enabled by an option at run
39    time.)
40    
41    The "configure" script builds four files:
42    
43  . Makefile is built by copying Makefile.in and making substitutions.  . Makefile is built by copying Makefile.in and making substitutions.
44  . config.h is built by copying config.in and making substitutions.  . config.h is built by copying config.in and making substitutions.
45  . pcre-config is built by copying pcre-config.in and making substitutions.  . pcre-config is built by copying pcre-config.in and making substitutions.
46    . RunTest is a script for running tests
47    
48  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
49  libpcre and libpcreposix, a test program called pcretest, and the pgrep  libpcre and libpcreposix, a test program called pcretest, and the pcregrep
50  command. You can use "make install" to copy these, and the public header file  command. You can use "make install" to copy these, and the public header file
51  pcre.h, to appropriate live directories on your system, in the normal way.  pcre.h, to appropriate live directories on your system, in the normal way.
52    
# Line 54  The default distribution builds PCRE as Line 72  The default distribution builds PCRE as
72  new and experimental and may not work on all systems. It relies on the  new and experimental and may not work on all systems. It relies on the
73  "libtool" scripts - these are distributed with PCRE. It should build a  "libtool" scripts - these are distributed with PCRE. It should build a
74  "libtool" script and use this to compile and link shared libraries, which are  "libtool" script and use this to compile and link shared libraries, which are
75  placed in a subdirectory called .libs. The programs pcretest and pgrep are  placed in a subdirectory called .libs. The programs pcretest and pcregrep are
76  built to use these uninstalled libraries by means of wrapper scripts. When you  built to use these uninstalled libraries by means of wrapper scripts. When you
77  use "make install" to install shared libraries, pgrep and pcretest are  use "make install" to install shared libraries, pcregrep and pcretest are
78  automatically re-built to use the newly installed libraries. However, only  automatically re-built to use the newly installed libraries. However, only
79  pgrep is installed, as pcretest is really just a test program.  pcregrep is installed, as pcretest is really just a test program.
80    
81  To build PCRE using static libraries you must use --disable-shared when  To build PCRE using static libraries you must use --disable-shared when
82  configuring it. For example  configuring it. For example
# Line 82  Testing PCRE Line 100  Testing PCRE
100  ------------  ------------
101    
102  To test PCRE on a Unix system, run the RunTest script in the pcre directory.  To test PCRE on a Unix system, run the RunTest script in the pcre directory.
103  (This can also be run by "make runtest" or "make check".) For other systems,  (This can also be run by "make runtest", "make check", or "make test".) For
104  see the instruction in NON-UNIX-USE.  other systems, see the instruction in NON-UNIX-USE.
105    
106  The script runs the pcretest test program (which is documented in  The script runs the pcretest test program (which is documented in
107  doc/pcretest.txt) on each of the testinput files (in the testdata directory) in  doc/pcretest.txt) on each of the testinput files (in the testdata directory) in
# Line 97  RunTest, for example: Line 115  RunTest, for example:
115  The first and third test files can also be fed directly into the perltest  The first and third test files can also be fed directly into the perltest
116  script to check that Perl gives the same results. The third file requires the  script to check that Perl gives the same results. The third file requires the
117  additional features of release 5.005, which is why it is kept separate from the  additional features of release 5.005, which is why it is kept separate from the
118  main test input, which needs only Perl 5.004. In the long run, when 5.005 is  main test input, which needs only Perl 5.004. In the long run, when 5.005 (or
119  widespread, these two test files may get amalgamated.  higher) is widespread, these two test files may get amalgamated.
120    
121  The second set of tests check pcre_info(), pcre_study(), pcre_copy_substring(),  The second set of tests check pcre_fullinfo(), pcre_info(), pcre_study(),
122  pcre_get_substring(), pcre_get_substring_list(), error detection and run-time  pcre_copy_substring(), pcre_get_substring(), pcre_get_substring_list(), error
123  flags that are specific to PCRE, as well as the POSIX wrapper API.  detection, and run-time flags that are specific to PCRE, as well as the POSIX
124    wrapper API. It also uses the debugging flag to check some of the internals of
125    pcre_compile().
126    
127    If you build PCRE with a locale setting that is not the standard C locale, the
128    character tables may be different (see next paragraph). In some cases, this may
129    cause failures in the second set of tests. For example, in a locale where the
130    isprint() function yields TRUE for characters in the range 128-255, the use of
131    [:isascii:] inside a character class defines a different set of characters, and
132    this shows up in this test as a difference in the compiled code, which is being
133    listed for checking. Where the comparison test output contains [\x00-\x7f] the
134    test will contain [\x00-\xff], and similarly in some other cases. This is not a
135    bug in PCRE.
136    
137  The fourth set of tests checks pcre_maketables(), the facility for building a  The fourth set of tests checks pcre_maketables(), the facility for building a
138  set of character tables for a specific locale and using them instead of the  set of character tables for a specific locale and using them instead of the
# Line 117  output to say why. If running this test Line 147  output to say why. If running this test
147  in the comparison output, it means that locale is not available on your system,  in the comparison output, it means that locale is not available on your system,
148  despite being listed by "locale". This does not mean that PCRE is broken.  despite being listed by "locale". This does not mean that PCRE is broken.
149    
150  PCRE has its own native API, but a set of "wrapper" functions that are based on  The fifth test checks the experimental, incomplete UTF-8 support. It is not run
151  the POSIX API are also supplied in the library libpcreposix.a. Note that this  automatically unless PCRE is built with UTF-8 support. This file can be fed
152  just provides a POSIX calling interface to PCRE: the regular expressions  directly to the perltest8 script, which requires Perl 5.6 or higher. The sixth
153  themselves still follow Perl syntax and semantics. The header file  file tests internal UTF-8 features of PCRE that are not relevant to Perl.
 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.  
154    
155    
156  Character tables  Character tables
# Line 197  The distribution should contain the foll Line 223  The distribution should contain the foll
223    NEWS                  important changes in this release    NEWS                  important changes in this release
224    NON-UNIX-USE          notes on building PCRE on non-Unix systems    NON-UNIX-USE          notes on building PCRE on non-Unix systems
225    README                this file    README                this file
226    RunTest               a Unix shell script for running tests    RunTest.in            template for a Unix shell script for running tests
227    config.guess          ) files used by libtool,    config.guess          ) files used by libtool,
228    config.sub            )   used only when building a shared library    config.sub            )   used only when building a shared library
229    configure             a configuring shell script (built by autoconf)    configure             a configuring shell script (built by autoconf)
# Line 211  The distribution should contain the foll Line 237  The distribution should contain the foll
237    doc/pcreposix.txt     plain text version    doc/pcreposix.txt     plain text version
238    doc/pcretest.txt      documentation of test program    doc/pcretest.txt      documentation of test program
239    doc/perltest.txt      documentation of Perl test program    doc/perltest.txt      documentation of Perl test program
240    doc/pgrep.1           man page source for the pgrep utility    doc/pcregrep.1        man page source for the pcregrep utility
241    doc/pgrep.html        HTML version    doc/pcregrep.html     HTML version
242    doc/pgrep.txt         plain text version    doc/pcregrep.txt      plain text version
243    install-sh            a shell script for installing files    install-sh            a shell script for installing files
244    ltconfig              ) files used to build "libtool",    ltconfig              ) files used to build "libtool",
245    ltmain.sh             )   used only when building a shared library    ltmain.sh             )   used only when building a shared library
246    pcretest.c            test program    pcretest.c            test program
247    perltest              Perl test program    perltest              Perl test program
248    pgrep.c               source of a grep utility that uses PCRE    perltest8             Perl test program for UTF-8 tests
249      pcregrep.c            source of a grep utility that uses PCRE
250    pcre-config.in        source of script which retains PCRE information    pcre-config.in        source of script which retains PCRE information
251    testdata/testinput1   test data, compatible with Perl 5.004 and 5.005    testdata/testinput1   test data, compatible with Perl 5.004 and 5.005
252    testdata/testinput2   test data for error messages and non-Perl things    testdata/testinput2   test data for error messages and non-Perl things
253    testdata/testinput3   test data, compatible with Perl 5.005    testdata/testinput3   test data, compatible with Perl 5.005
254    testdata/testinput4   test data for locale-specific tests    testdata/testinput4   test data for locale-specific tests
255      testdata/testinput5   test data for UTF-8 tests compatible with Perl 5.6
256      testdata/testinput6   test data for other UTF-8 tests
257    testdata/testoutput1  test results corresponding to testinput1    testdata/testoutput1  test results corresponding to testinput1
258    testdata/testoutput2  test results corresponding to testinput2    testdata/testoutput2  test results corresponding to testinput2
259    testdata/testoutput3  test results corresponding to testinput3    testdata/testoutput3  test results corresponding to testinput3
260    testdata/testoutput4  test results corresponding to testinput4    testdata/testoutput4  test results corresponding to testinput4
261      testdata/testoutput5  test results corresponding to testinput5
262      testdata/testoutput6  test results corresponding to testinput6
263    
264  (C) Auxiliary files for Win32 DLL  (C) Auxiliary files for Win32 DLL
265    
# Line 236  The distribution should contain the foll Line 267  The distribution should contain the foll
267    pcre.def    pcre.def
268    
269  Philip Hazel <ph10@cam.ac.uk>  Philip Hazel <ph10@cam.ac.uk>
270  February 2000  August 2000
Legend:
Removed from v.43  
changed lines
  Added in v.49
  ViewVC Help
Powered by ViewVC 1.1.5