ViewVC logotype

Contents of /code/trunk/README

Parent Directory Parent Directory | Revision Log Revision Log

Revision 41 - (show annotations) (download)
Sat Feb 24 21:39:17 2007 UTC (7 years, 1 month ago) by nigel
File size: 9899 byte(s)
Load pcre-2.08a into code/trunk.

1 README file for PCRE (Perl-compatible regular expression library)
2 -----------------------------------------------------------------
4 Please read the NEWS file if you are upgrading from a previous release.
7 Building PCRE on a Unix system
8 ------------------------------
10 To build PCRE on a Unix system, run the "configure" command in the PCRE
11 distribution directory. This is a standard GNU "autoconf" configuration script,
12 for which generic instructions are supplied in INSTALL. On many systems just
13 running "./configure" is sufficient, but the usual methods of changing standard
14 defaults are available. For example
16 CFLAGS='-O2 -Wall' ./configure --prefix=/opt/local
18 specifies that the C compiler should be run with the flags '-O2 -Wall' instead
19 of the default, and that "make install" should install PCRE under /opt/local
20 instead of the default /usr/local. The "configure" script builds two files:
22 . Makefile is built by copying Makefile.in and making certain substitutions.
23 . config.h is built by copying config.in and making certain substitutions.
25 Once "configure" has run, you can run "make". It builds two libraries called
26 libpcre.a and libpcreposix.a, a test program called pcretest, and the pgrep
27 command. You can use "make install" to copy these, and the public header file
28 pcre.h, to appropriate live directories on your system, in the normal way.
31 Shared libraries on Unix systems
32 --------------------------------
34 The default distribution builds static libraries. It is also possible to build
35 PCRE as two shared libraries. This support is new and experimental and may not
36 work on all systems. It relies on the "libtool" scripts - these are distributed
37 with PCRE. To build PCRE using shared libraries you must use --enable-shared
38 when configuring it. For example
40 ./configure --prefix=/usr/gnu --enable-shared
42 Then run "make" in the usual way. It should build a "libtool" script and use
43 this to compile and link shared libraries, which are placed in a subdirectory
44 called .libs. The programs pcretest and pgrep are built to use these
45 uninstalled libraries by means of wrapper scripts. When you use "make install"
46 to install shared libraries, pgrep is automatically re-built to use the newly
47 installed library before it itself is installed.
50 Building on non-Unix systems
51 ----------------------------
53 For a non-Unix system, read the comments in the file NON-UNIX-USE. PCRE has
54 been compiled on Windows systems and on Macintoshes, but I don't know the
55 details because I don't use those systems. It should be straightforward to
56 build PCRE on any system that has a Standard C compiler, because it uses only
57 Standard C functions.
60 Testing PCRE
61 ------------
63 To test PCRE on a Unix system, run the RunTest script in the pcre directory.
64 (This can also be run by "make runtest" or "make check".) For other systems,
65 see the instruction in NON-UNIX-USE.
67 The script runs the pcretest test program (which is documented in
68 doc/pcretest.txt) on each of the testinput files (in the testdata directory) in
69 turn, and compares the output with the contents of the corresponding testoutput
70 file. A file called testtry is used to hold the output from pcretest. To run
71 pcretest on just one of the test files, give its number as an argument to
72 RunTest, for example:
74 RunTest 3
76 The first and third test files can also be fed directly into the perltest
77 script to check that Perl gives the same results. The third file requires the
78 additional features of release 5.005, which is why it is kept separate from the
79 main test input, which needs only Perl 5.004. In the long run, when 5.005 is
80 widespread, these two test files may get amalgamated.
82 The second set of tests check pcre_info(), pcre_study(), pcre_copy_substring(),
83 pcre_get_substring(), pcre_get_substring_list(), error detection and run-time
84 flags that are specific to PCRE, as well as the POSIX wrapper API.
86 The fourth set of tests checks pcre_maketables(), the facility for building a
87 set of character tables for a specific locale and using them instead of the
88 default tables. The tests make use of the "fr" (French) locale. Before running
89 the test, the script checks for the presence of this locale by running the
90 "locale" command. If that command fails, or if it doesn't include "fr" in the
91 list of available locales, the fourth test cannot be run, and a comment is
92 output to say why. If running this test produces instances of the error
94 ** Failed to set locale "fr"
96 in the comparison output, it means that locale is not available on your system,
97 despite being listed by "locale". This does not mean that PCRE is broken.
99 PCRE has its own native API, but a set of "wrapper" functions that are based on
100 the POSIX API are also supplied in the library libpcreposix.a. Note that this
101 just provides a POSIX calling interface to PCRE: the regular expressions
102 themselves still follow Perl syntax and semantics. The header file
103 for the POSIX-style functions is called pcreposix.h. The official POSIX name is
104 regex.h, but I didn't want to risk possible problems with existing files of
105 that name by distributing it that way. To use it with an existing program that
106 uses the POSIX API, it will have to be renamed or pointed at by a link.
109 Character tables
110 ----------------
112 PCRE uses four tables for manipulating and identifying characters. The final
113 argument of the pcre_compile() function is a pointer to a block of memory
114 containing the concatenated tables. A call to pcre_maketables() can be used to
115 generate a set of tables in the current locale. If the final argument for
116 pcre_compile() is passed as NULL, a set of default tables that is built into
117 the binary is used.
119 The source file called chartables.c contains the default set of tables. This is
120 not supplied in the distribution, but is built by the program dftables
121 (compiled from dftables.c), which uses the ANSI C character handling functions
122 such as isalnum(), isalpha(), isupper(), islower(), etc. to build the table
123 sources. This means that the default C locale which is set for your system will
124 control the contents of these default tables. You can change the default tables
125 by editing chartables.c and then re-building PCRE. If you do this, you should
126 probably also edit Makefile to ensure that the file doesn't ever get
127 re-generated.
129 The first two 256-byte tables provide lower casing and case flipping functions,
130 respectively. The next table consists of three 32-byte bit maps which identify
131 digits, "word" characters, and white space, respectively. These are used when
132 building 32-byte bit maps that represent character classes.
134 The final 256-byte table has bits indicating various character types, as
135 follows:
137 1 white space character
138 2 letter
139 4 decimal digit
140 8 hexadecimal digit
141 16 alphanumeric or '_'
142 128 regular expression metacharacter or binary zero
144 You should not alter the set of characters that contain the 128 bit, as that
145 will cause PCRE to malfunction.
148 Manifest
149 --------
151 The distribution should contain the following files:
153 (A) The actual source files of the PCRE library functions and their
154 headers:
156 dftables.c auxiliary program for building chartables.c
157 get.c )
158 maketables.c )
159 study.c ) source of
160 pcre.c ) the functions
161 pcreposix.c )
162 pcre.h header for the external API
163 pcreposix.h header for the external POSIX wrapper API
164 internal.h header for internal use
165 config.in template for config.h, which is built by configure
167 (B) Auxiliary files:
169 AUTHORS information about the author of PCRE
170 ChangeLog log of changes to the code
171 INSTALL generic installation instructions
172 LICENCE conditions for the use of PCRE
173 Makefile.in template for Unix Makefile, which is built by configure
174 NEWS important changes in this release
175 NON-UNIX-USE notes on building PCRE on non-Unix systems
176 README this file
177 RunTest a Unix shell script for running tests
178 config.guess ) files used by libtool,
179 config.sub ) used only when building a shared library
180 configure a configuring shell script (built by autoconf)
181 configure.in the autoconf input used to build configure
182 doc/Tech.Notes notes on the encoding
183 doc/pcre.3 man page source for the PCRE functions
184 doc/pcre.html HTML version
185 doc/pcre.txt plain text version
186 doc/pcreposix.3 man page source for the POSIX wrapper API
187 doc/pcreposix.html HTML version
188 doc/pcreposix.txt plain text version
189 doc/pcretest.txt documentation of test program
190 doc/perltest.txt documentation of Perl test program
191 doc/pgrep.1 man page source for the pgrep utility
192 doc/pgrep.html HTML version
193 doc/pgrep.txt plain text version
194 install-sh a shell script for installing files
195 ltconfig ) files used to build "libtool",
196 ltmain.sh ) used only when building a shared library
197 pcretest.c test program
198 perltest Perl test program
199 pgrep.c source of a grep utility that uses PCRE
200 testdata/testinput1 test data, compatible with Perl 5.004 and 5.005
201 testdata/testinput2 test data for error messages and non-Perl things
202 testdata/testinput3 test data, compatible with Perl 5.005
203 testdata/testinput4 test data for locale-specific tests
204 testdata/testoutput1 test results corresponding to testinput1
205 testdata/testoutput2 test results corresponding to testinput2
206 testdata/testoutput3 test results corresponding to testinput3
207 testdata/testoutput4 test results corresponding to testinput4
209 (C) Auxiliary files for Win32 DLL
211 dll.mk
212 pcre.def
214 Philip Hazel <ph10@cam.ac.uk>
215 January 2000

ViewVC Help
Powered by ViewVC 1.1.12