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

Contents of /code/trunk/README

Parent Directory Parent Directory | Revision Log Revision Log


Revision 43 - (show annotations) (download)
Sat Feb 24 21:39:21 2007 UTC (7 years, 6 months ago) by nigel
File size: 10752 byte(s)
Load pcre-3.0 into code/trunk.

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

webmaster@exim.org
ViewVC Help
Powered by ViewVC 1.1.12