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

Contents of /code/trunk/README

Parent Directory Parent Directory | Revision Log Revision Log


Revision 75 - (hide annotations) (download)
Sat Feb 24 21:40:37 2007 UTC (7 years, 9 months ago) by nigel
File size: 19589 byte(s)
Load pcre-5.0 into code/trunk.

1 nigel 41 README file for PCRE (Perl-compatible regular expression library)
2     -----------------------------------------------------------------
3 nigel 3
4 nigel 43 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 nigel 41 Please read the NEWS file if you are upgrading from a previous release.
9 nigel 23
10 nigel 49 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 nigel 35
19 nigel 73 If you are using the POSIX interface to PCRE and there is already a POSIX regex
20     library installed on your system, you must take care when linking programs to
21     ensure that they link with PCRE's libpcreposix library. Otherwise they may pick
22     up the "real" POSIX functions of the same name.
23 nigel 49
24 nigel 73
25 nigel 75 Documentation for PCRE
26     ----------------------
27    
28     If you install PCRE in the normal way, you will end up with an installed set of
29     man pages whose names all start with "pcre". The one that is called "pcre"
30     lists all the others. In addition to these man pages, the PCRE documentation is
31     supplied in two other forms; however, as there is no standard place to install
32     them, they are left in the doc directory of the unpacked source distribution.
33     These forms are:
34    
35     1. Files called doc/pcre.txt, doc/pcregrep.txt, and doc/pcretest.txt. The
36     first of these is a concatenation of the text forms of all the section 3
37     man pages except those that summarize individual functions. The other two
38     are the text forms of the section 1 man pages for the pcregrep and
39     pcretest commands. Text forms are provided for ease of scanning with text
40     editors or similar tools.
41    
42     2. A subdirectory called doc/html contains all the documentation in HTML
43     form, hyperlinked in various ways, and rooted in a file called
44     doc/index.html.
45    
46    
47 nigel 53 Contributions by users of PCRE
48     ------------------------------
49    
50     You can find contributions from PCRE users in the directory
51    
52     ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/Contrib
53    
54     where there is also a README file giving brief descriptions of what they are.
55     Several of them provide support for compiling PCRE on various flavours of
56     Windows systems (I myself do not use Windows). Some are complete in themselves;
57     others are pointers to URLs containing relevant files.
58    
59    
60 nigel 63 Building PCRE on a Unix-like system
61     -----------------------------------
62 nigel 3
63 nigel 63 To build PCRE on a Unix-like system, first run the "configure" command from the
64     PCRE distribution directory, with your current directory set to the directory
65     where you want the files to be created. This command is a standard GNU
66     "autoconf" configuration script, for which generic instructions are supplied in
67     INSTALL.
68 nigel 3
69 nigel 53 Most commonly, people build PCRE within its own distribution directory, and in
70     this case, on many systems, just running "./configure" is sufficient, but the
71 nigel 75 usual methods of changing standard defaults are available. For example:
72 nigel 53
73 nigel 41 CFLAGS='-O2 -Wall' ./configure --prefix=/opt/local
74    
75     specifies that the C compiler should be run with the flags '-O2 -Wall' instead
76     of the default, and that "make install" should install PCRE under /opt/local
77 nigel 49 instead of the default /usr/local.
78 nigel 41
79 nigel 53 If you want to build in a different directory, just run "configure" with that
80     directory as current. For example, suppose you have unpacked the PCRE source
81     into /source/pcre/pcre-xxx, but you want to build it in /build/pcre/pcre-xxx:
82    
83     cd /build/pcre/pcre-xxx
84     /source/pcre/pcre-xxx/configure
85    
86 nigel 63 There are some optional features that can be included or omitted from the PCRE
87     library. You can read more about them in the pcrebuild man page.
88 nigel 49
89 nigel 63 . If you want to make use of the support for UTF-8 character strings in PCRE,
90     you must add --enable-utf8 to the "configure" command. Without it, the code
91     for handling UTF-8 is not included in the library. (Even when included, it
92     still has to be enabled by an option at run time.)
93    
94 nigel 75 . If, in addition to support for UTF-8 character strings, you want to include
95     support for the \P, \p, and \X sequences that recognize Unicode character
96     properties, you must add --enable-unicode-properties to the "configure"
97     command. This adds about 90K to the size of the library (in the form of a
98     property table); only the basic two-letter properties such as Lu are
99     supported.
100    
101 nigel 63 . You can build PCRE to recognized CR or NL as the newline character, instead
102     of whatever your compiler uses for "\n", by adding --newline-is-cr or
103     --newline-is-nl to the "configure" command, respectively. Only do this if you
104     really understand what you are doing. On traditional Unix-like systems, the
105     newline character is NL.
106    
107     . When called via the POSIX interface, PCRE uses malloc() to get additional
108     storage for processing capturing parentheses if there are more than 10 of
109     them. You can increase this threshold by setting, for example,
110    
111     --with-posix-malloc-threshold=20
112    
113     on the "configure" command.
114    
115     . PCRE has a counter which can be set to limit the amount of resources it uses.
116     If the limit is exceeded during a match, the match fails. The default is ten
117     million. You can change the default by setting, for example,
118    
119     --with-match-limit=500000
120    
121     on the "configure" command. This is just the default; individual calls to
122     pcre_exec() can supply their own value. There is discussion on the pcreapi
123     man page.
124    
125     . The default maximum compiled pattern size is around 64K. You can increase
126     this by adding --with-link-size=3 to the "configure" command. You can
127     increase it even more by setting --with-link-size=4, but this is unlikely
128     ever to be necessary. If you build PCRE with an increased link size, test 2
129     (and 5 if you are using UTF-8) will fail. Part of the output of these tests
130     is a representation of the compiled pattern, and this changes with the link
131     size.
132    
133 nigel 73 . You can build PCRE so that its match() function does not call itself
134     recursively. Instead, it uses blocks of data from the heap via special
135     functions pcre_stack_malloc() and pcre_stack_free() to save data that would
136     otherwise be saved on the stack. To build PCRE like this, use
137    
138     --disable-stack-for-recursion
139    
140     on the "configure" command. PCRE runs more slowly in this mode, but it may be
141     necessary in environments with limited stack sizes.
142    
143 nigel 75 The "configure" script builds seven files:
144 nigel 49
145 nigel 75 . pcre.h is build by copying pcre.in and making substitutions
146 nigel 43 . Makefile is built by copying Makefile.in and making substitutions.
147     . config.h is built by copying config.in and making substitutions.
148     . pcre-config is built by copying pcre-config.in and making substitutions.
149 nigel 75 . libpcre.pc is data for the pkg-config command, built from libpcre.pc.in
150     . libtool is a script that builds shared and/or static libraries
151 nigel 49 . RunTest is a script for running tests
152 nigel 41
153     Once "configure" has run, you can run "make". It builds two libraries called
154 nigel 49 libpcre and libpcreposix, a test program called pcretest, and the pcregrep
155 nigel 53 command. You can use "make install" to copy these, the public header files
156     pcre.h and pcreposix.h, and the man pages to appropriate live directories on
157     your system, in the normal way.
158 nigel 3
159 nigel 75
160     Retrieving configuration information on Unix-like systems
161     ---------------------------------------------------------
162    
163 nigel 43 Running "make install" also installs the command pcre-config, which can be used
164     to recall information about the PCRE configuration and installation. For
165 nigel 75 example:
166 nigel 37
167 nigel 43 pcre-config --version
168    
169     prints the version number, and
170    
171 nigel 75 pcre-config --libs
172 nigel 43
173     outputs information about where the library is installed. This command can be
174     included in makefiles for programs that use PCRE, saving the programmer from
175     having to remember too many details.
176    
177 nigel 75 The pkg-config command is another system for saving and retrieving information
178     about installed libraries. Instead of separate commands for each library, a
179     single command is used. For example:
180 nigel 43
181 nigel 75 pkg-config --cflags pcre
182    
183     The data is held in *.pc files that are installed in a directory called
184     pkgconfig.
185    
186    
187 nigel 63 Shared libraries on Unix-like systems
188     -------------------------------------
189 nigel 53
190     The default distribution builds PCRE as two shared libraries and two static
191     libraries, as long as the operating system supports shared libraries. Shared
192     library support relies on the "libtool" script which is built as part of the
193     "configure" process.
194 nigel 39
195 nigel 53 The libtool script is used to compile and link both shared and static
196     libraries. They are placed in a subdirectory called .libs when they are newly
197     built. The programs pcretest and pcregrep are built to use these uninstalled
198     libraries (by means of wrapper scripts in the case of shared libraries). When
199     you use "make install" to install shared libraries, pcregrep and pcretest are
200     automatically re-built to use the newly installed shared libraries before being
201     installed themselves. However, the versions left in the source directory still
202     use the uninstalled libraries.
203    
204     To build PCRE using static libraries only you must use --disable-shared when
205 nigel 75 configuring it. For example:
206 nigel 3
207 nigel 43 ./configure --prefix=/usr/gnu --disable-shared
208 nigel 41
209 nigel 53 Then run "make" in the usual way. Similarly, you can use --disable-static to
210     build only shared libraries.
211 nigel 41
212 nigel 43
213 nigel 63 Cross-compiling on a Unix-like system
214     -------------------------------------
215    
216     You can specify CC and CFLAGS in the normal way to the "configure" command, in
217     order to cross-compile PCRE for some other host. However, during the building
218     process, the dftables.c source file is compiled *and run* on the local host, in
219     order to generate the default character tables (the chartables.c file). It
220     therefore needs to be compiled with the local compiler, not the cross compiler.
221 nigel 73 You can do this by specifying CC_FOR_BUILD (and if necessary CFLAGS_FOR_BUILD)
222     when calling the "configure" command. If they are not specified, they default
223     to the values of CC and CFLAGS.
224 nigel 63
225    
226 nigel 41 Building on non-Unix systems
227     ----------------------------
228    
229 nigel 73 For a non-Unix system, read the comments in the file NON-UNIX-USE, though if
230     the system supports the use of "configure" and "make" you may be able to build
231     PCRE in the same way as for Unix systems.
232    
233     PCRE has been compiled on Windows systems and on Macintoshes, but I don't know
234     the details because I don't use those systems. It should be straightforward to
235 nigel 41 build PCRE on any system that has a Standard C compiler, because it uses only
236     Standard C functions.
237    
238    
239     Testing PCRE
240     ------------
241    
242 nigel 53 To test PCRE on a Unix system, run the RunTest script that is created by the
243     configuring process. (This can also be run by "make runtest", "make check", or
244 nigel 73 "make test".) For other systems, see the instructions in NON-UNIX-USE.
245 nigel 41
246 nigel 63 The script runs the pcretest test program (which is documented in its own man
247     page) on each of the testinput files (in the testdata directory) in turn,
248 nigel 53 and compares the output with the contents of the corresponding testoutput file.
249 nigel 75 A file called testtry is used to hold the main output from pcretest
250     (testsavedregex is also used as a working file). To run pcretest on just one of
251     the test files, give its number as an argument to RunTest, for example:
252 nigel 41
253 nigel 63 RunTest 2
254 nigel 3
255 nigel 63 The first file can also be fed directly into the perltest script to check that
256     Perl gives the same results. The only difference you should see is in the first
257     few lines, where the Perl version is given instead of the PCRE version.
258 nigel 3
259 nigel 49 The second set of tests check pcre_fullinfo(), pcre_info(), pcre_study(),
260     pcre_copy_substring(), pcre_get_substring(), pcre_get_substring_list(), error
261     detection, and run-time flags that are specific to PCRE, as well as the POSIX
262     wrapper API. It also uses the debugging flag to check some of the internals of
263     pcre_compile().
264 nigel 7
265 nigel 49 If you build PCRE with a locale setting that is not the standard C locale, the
266     character tables may be different (see next paragraph). In some cases, this may
267     cause failures in the second set of tests. For example, in a locale where the
268     isprint() function yields TRUE for characters in the range 128-255, the use of
269     [:isascii:] inside a character class defines a different set of characters, and
270     this shows up in this test as a difference in the compiled code, which is being
271     listed for checking. Where the comparison test output contains [\x00-\x7f] the
272     test will contain [\x00-\xff], and similarly in some other cases. This is not a
273     bug in PCRE.
274    
275 nigel 63 The third set of tests checks pcre_maketables(), the facility for building a
276 nigel 25 set of character tables for a specific locale and using them instead of the
277 nigel 73 default tables. The tests make use of the "fr_FR" (French) locale. Before
278     running the test, the script checks for the presence of this locale by running
279     the "locale" command. If that command fails, or if it doesn't include "fr_FR"
280     in the list of available locales, the third test cannot be run, and a comment
281     is output to say why. If running this test produces instances of the error
282 nigel 25
283 nigel 73 ** Failed to set locale "fr_FR"
284 nigel 25
285     in the comparison output, it means that locale is not available on your system,
286     despite being listed by "locale". This does not mean that PCRE is broken.
287    
288 nigel 63 The fourth test checks the UTF-8 support. It is not run automatically unless
289     PCRE is built with UTF-8 support. To do this you must set --enable-utf8 when
290     running "configure". This file can be also fed directly to the perltest script,
291     provided you are running Perl 5.8 or higher. (For Perl 5.6, a small patch,
292     commented in the script, can be be used.)
293 nigel 3
294 nigel 75 The fifth test checks error handling with UTF-8 encoding, and internal UTF-8
295     features of PCRE that are not relevant to Perl.
296 nigel 3
297 nigel 75 The sixth and final test checks the support for Unicode character properties.
298     It it not run automatically unless PCRE is built with Unicode property support.
299     To to this you must set --enable-unicode-properties when running "configure".
300 nigel 63
301 nigel 75
302 nigel 3 Character tables
303     ----------------
304    
305 nigel 75 PCRE uses four tables for manipulating and identifying characters whose values
306     are less than 256. The final argument of the pcre_compile() function is a
307     pointer to a block of memory containing the concatenated tables. A call to
308     pcre_maketables() can be used to generate a set of tables in the current
309     locale. If the final argument for pcre_compile() is passed as NULL, a set of
310     default tables that is built into the binary is used.
311 nigel 3
312 nigel 25 The source file called chartables.c contains the default set of tables. This is
313 nigel 27 not supplied in the distribution, but is built by the program dftables
314     (compiled from dftables.c), which uses the ANSI C character handling functions
315 nigel 25 such as isalnum(), isalpha(), isupper(), islower(), etc. to build the table
316 nigel 35 sources. This means that the default C locale which is set for your system will
317     control the contents of these default tables. You can change the default tables
318     by editing chartables.c and then re-building PCRE. If you do this, you should
319     probably also edit Makefile to ensure that the file doesn't ever get
320     re-generated.
321 nigel 3
322 nigel 25 The first two 256-byte tables provide lower casing and case flipping functions,
323     respectively. The next table consists of three 32-byte bit maps which identify
324     digits, "word" characters, and white space, respectively. These are used when
325     building 32-byte bit maps that represent character classes.
326    
327     The final 256-byte table has bits indicating various character types, as
328 nigel 3 follows:
329    
330     1 white space character
331     2 letter
332     4 decimal digit
333     8 hexadecimal digit
334     16 alphanumeric or '_'
335     128 regular expression metacharacter or binary zero
336    
337     You should not alter the set of characters that contain the 128 bit, as that
338     will cause PCRE to malfunction.
339    
340    
341 nigel 41 Manifest
342     --------
343 nigel 3
344 nigel 41 The distribution should contain the following files:
345 nigel 3
346 nigel 41 (A) The actual source files of the PCRE library functions and their
347     headers:
348 nigel 3
349 nigel 41 dftables.c auxiliary program for building chartables.c
350 nigel 75
351 nigel 41 get.c )
352     maketables.c )
353 nigel 75 study.c ) source of the functions
354     pcre.c ) in the library
355 nigel 41 pcreposix.c )
356 nigel 63 printint.c )
357 nigel 75
358     ucp.c )
359     ucp.h ) source for the code that is used for
360     ucpinternal.h ) Unicode property handling
361     ucptable.c )
362     ucptypetable.c )
363    
364 nigel 43 pcre.in "source" for the header for the external API; pcre.h
365     is built from this by "configure"
366 nigel 41 pcreposix.h header for the external POSIX wrapper API
367     internal.h header for internal use
368     config.in template for config.h, which is built by configure
369 nigel 3
370 nigel 41 (B) Auxiliary files:
371 nigel 3
372 nigel 41 AUTHORS information about the author of PCRE
373     ChangeLog log of changes to the code
374     INSTALL generic installation instructions
375     LICENCE conditions for the use of PCRE
376 nigel 43 COPYING the same, using GNU's standard name
377 nigel 41 Makefile.in template for Unix Makefile, which is built by configure
378     NEWS important changes in this release
379     NON-UNIX-USE notes on building PCRE on non-Unix systems
380     README this file
381 nigel 49 RunTest.in template for a Unix shell script for running tests
382 nigel 41 config.guess ) files used by libtool,
383     config.sub ) used only when building a shared library
384     configure a configuring shell script (built by autoconf)
385     configure.in the autoconf input used to build configure
386     doc/Tech.Notes notes on the encoding
387 nigel 63 doc/*.3 man page sources for the PCRE functions
388     doc/*.1 man page sources for pcregrep and pcretest
389     doc/html/* HTML documentation
390     doc/pcre.txt plain text version of the man pages
391     doc/pcretest.txt plain text documentation of test program
392     doc/perltest.txt plain text documentation of Perl test program
393 nigel 41 install-sh a shell script for installing files
394 nigel 75 libpcre.pc.in "source" for libpcre.pc for pkg-config
395 nigel 53 ltmain.sh file used to build a libtool script
396 nigel 75 mkinstalldirs script for making install directories
397 nigel 53 pcretest.c comprehensive test program
398     pcredemo.c simple demonstration of coding calls to PCRE
399 nigel 41 perltest Perl test program
400 nigel 49 pcregrep.c source of a grep utility that uses PCRE
401 nigel 43 pcre-config.in source of script which retains PCRE information
402 nigel 63 testdata/testinput1 test data, compatible with Perl
403 nigel 41 testdata/testinput2 test data for error messages and non-Perl things
404 nigel 63 testdata/testinput3 test data for locale-specific tests
405     testdata/testinput4 test data for UTF-8 tests compatible with Perl
406     testdata/testinput5 test data for other UTF-8 tests
407 nigel 75 testdata/testinput6 test data for Unicode property support tests
408 nigel 41 testdata/testoutput1 test results corresponding to testinput1
409     testdata/testoutput2 test results corresponding to testinput2
410     testdata/testoutput3 test results corresponding to testinput3
411     testdata/testoutput4 test results corresponding to testinput4
412 nigel 49 testdata/testoutput5 test results corresponding to testinput5
413 nigel 75 testdata/testoutput6 test results corresponding to testinput6
414 nigel 3
415 nigel 41 (C) Auxiliary files for Win32 DLL
416 nigel 29
417 nigel 41 dll.mk
418 nigel 75 libpcre.def
419     libpcreposix.def
420 nigel 41 pcre.def
421 nigel 29
422 nigel 63 (D) Auxiliary file for VPASCAL
423    
424     makevp.bat
425    
426 nigel 3 Philip Hazel <ph10@cam.ac.uk>
427 nigel 75 September 2004

webmaster@exim.org
ViewVC Help
Powered by ViewVC 1.1.12