18 |
The PCRE APIs |
The PCRE APIs |
19 |
Documentation for PCRE |
Documentation for PCRE |
20 |
Contributions by users of PCRE |
Contributions by users of PCRE |
21 |
Building PCRE on non-Unix systems |
Building PCRE on non-Unix-like systems |
22 |
Building PCRE on Unix-like systems |
Building PCRE without using autotools |
23 |
Retrieving configuration information on Unix-like systems |
Building PCRE using autotools |
24 |
Shared libraries on Unix-like systems |
Retrieving configuration information |
25 |
Cross-compiling on Unix-like systems |
Shared libraries |
26 |
|
Cross-compiling using autotools |
27 |
Using HP's ANSI C++ compiler (aCC) |
Using HP's ANSI C++ compiler (aCC) |
28 |
Using PCRE from MySQL |
Using PCRE from MySQL |
29 |
Making new tarballs |
Making new tarballs |
35 |
The PCRE APIs |
The PCRE APIs |
36 |
------------- |
------------- |
37 |
|
|
38 |
PCRE is written in C, and it has its own API. The distribution also includes a |
PCRE is written in C, and it has its own API. There are three sets of functions, |
39 |
set of C++ wrapper functions (see the pcrecpp man page for details), courtesy |
one for the 8-bit library, which processes strings of bytes, one for the |
40 |
of Google Inc. |
16-bit library, which processes strings of 16-bit values, and one for the 32-bit |
41 |
|
library, which processes strings of 32-bit values. The distribution also |
42 |
In addition, there is a set of C wrapper functions that are based on the POSIX |
includes a set of C++ wrapper functions (see the pcrecpp man page for details), |
43 |
regular expression API (see the pcreposix man page). These end up in the |
courtesy of Google Inc., which can be used to call the 8-bit PCRE library from |
44 |
library called libpcreposix. Note that this just provides a POSIX calling |
C++. |
45 |
interface to PCRE; the regular expressions themselves still follow Perl syntax |
|
46 |
and semantics. The POSIX API is restricted, and does not give full access to |
In addition, there is a set of C wrapper functions (again, just for the 8-bit |
47 |
all of PCRE's facilities. |
library) that are based on the POSIX regular expression API (see the pcreposix |
48 |
|
man page). These end up in the library called libpcreposix. Note that this just |
49 |
|
provides a POSIX calling interface to PCRE; the regular expressions themselves |
50 |
|
still follow Perl syntax and semantics. The POSIX API is restricted, and does |
51 |
|
not give full access to all of PCRE's facilities. |
52 |
|
|
53 |
The header file for the POSIX-style functions is called pcreposix.h. The |
The header file for the POSIX-style functions is called pcreposix.h. The |
54 |
official POSIX name is regex.h, but I did not want to risk possible problems |
official POSIX name is regex.h, but I did not want to risk possible problems |
111 |
in the standard distribution, so these contibutions have been archived. |
in the standard distribution, so these contibutions have been archived. |
112 |
|
|
113 |
|
|
114 |
Building PCRE on non-Unix systems |
Building PCRE on non-Unix-like systems |
115 |
--------------------------------- |
-------------------------------------- |
116 |
|
|
117 |
For a non-Unix system, please read the comments in the file NON-UNIX-USE, |
For a non-Unix-like system, please read the comments in the file |
118 |
though if your system supports the use of "configure" and "make" you may be |
NON-AUTOTOOLS-BUILD, though if your system supports the use of "configure" and |
119 |
able to build PCRE in the same way as for Unix-like systems. PCRE can also be |
"make" you may be able to build PCRE using autotools in the same way as for |
120 |
configured in many platform environments using the GUI facility provided by |
many Unix-like systems. |
121 |
CMake's cmake-gui command. This creates Makefiles, solution files, etc. |
|
122 |
|
PCRE can also be configured using the GUI facility provided by CMake's |
123 |
|
cmake-gui command. This creates Makefiles, solution files, etc. The file |
124 |
|
NON-AUTOTOOLS-BUILD has information about CMake. |
125 |
|
|
126 |
PCRE has been compiled on many different operating systems. It should be |
PCRE has been compiled on many different operating systems. It should be |
127 |
straightforward to build PCRE on any system that has a Standard C compiler and |
straightforward to build PCRE on any system that has a Standard C compiler and |
128 |
library, because it uses only Standard C functions. |
library, because it uses only Standard C functions. |
129 |
|
|
130 |
|
|
131 |
Building PCRE on Unix-like systems |
Building PCRE without using autotools |
132 |
---------------------------------- |
------------------------------------- |
133 |
|
|
134 |
|
The use of autotools (in particular, libtool) is problematic in some |
135 |
|
environments, even some that are Unix or Unix-like. See the NON-AUTOTOOLS-BUILD |
136 |
|
file for ways of building PCRE without using autotools. |
137 |
|
|
138 |
|
|
139 |
|
Building PCRE using autotools |
140 |
|
----------------------------- |
141 |
|
|
142 |
If you are using HP's ANSI C++ compiler (aCC), please see the special note |
If you are using HP's ANSI C++ compiler (aCC), please see the special note |
143 |
in the section entitled "Using HP's ANSI C++ compiler (aCC)" below. |
in the section entitled "Using HP's ANSI C++ compiler (aCC)" below. |
144 |
|
|
145 |
The following instructions assume the use of the widely used "configure, make, |
The following instructions assume the use of the widely used "configure; make; |
146 |
make install" process. There is also support for CMake in the PCRE |
make install" (autotools) process. |
147 |
distribution; there are some comments about using CMake in the NON-UNIX-USE |
|
148 |
file, though it can also be used in Unix-like systems. |
To build PCRE on system that supports autotools, first run the "configure" |
149 |
|
command from the PCRE distribution directory, with your current directory set |
150 |
To build PCRE on a Unix-like system, first run the "configure" command from the |
to the directory where you want the files to be created. This command is a |
151 |
PCRE distribution directory, with your current directory set to the directory |
standard GNU "autoconf" configuration script, for which generic instructions |
152 |
where you want the files to be created. This command is a standard GNU |
are supplied in the file INSTALL. |
|
"autoconf" configuration script, for which generic instructions are supplied in |
|
|
the file INSTALL. |
|
153 |
|
|
154 |
Most commonly, people build PCRE within its own distribution directory, and in |
Most commonly, people build PCRE within its own distribution directory, and in |
155 |
this case, on many systems, just running "./configure" is sufficient. However, |
this case, on many systems, just running "./configure" is sufficient. However, |
157 |
|
|
158 |
CFLAGS='-O2 -Wall' ./configure --prefix=/opt/local |
CFLAGS='-O2 -Wall' ./configure --prefix=/opt/local |
159 |
|
|
160 |
specifies that the C compiler should be run with the flags '-O2 -Wall' instead |
This command specifies that the C compiler should be run with the flags '-O2 |
161 |
of the default, and that "make install" should install PCRE under /opt/local |
-Wall' instead of the default, and that "make install" should install PCRE |
162 |
instead of the default /usr/local. |
under /opt/local instead of the default /usr/local. |
163 |
|
|
164 |
If you want to build in a different directory, just run "configure" with that |
If you want to build in a different directory, just run "configure" with that |
165 |
directory as current. For example, suppose you have unpacked the PCRE source |
directory as current. For example, suppose you have unpacked the PCRE source |
183 |
|
|
184 |
(See also "Shared libraries on Unix-like systems" below.) |
(See also "Shared libraries on Unix-like systems" below.) |
185 |
|
|
186 |
. If you want to suppress the building of the C++ wrapper library, you can add |
. By default, only the 8-bit library is built. If you add --enable-pcre16 to |
187 |
--disable-cpp to the "configure" command. Otherwise, when "configure" is run, |
the "configure" command, the 16-bit library is also built. If you add |
188 |
it will try to find a C++ compiler and C++ header files, and if it succeeds, |
--enable-pcre32 to the "configure" command, the 32-bit library is also built. |
189 |
it will try to build the C++ wrapper. |
If you want only the 16-bit or 32-bit library, use --disable-pcre8 to disable |
190 |
|
building the 8-bit library. |
191 |
|
|
192 |
|
. If you are building the 8-bit library and want to suppress the building of |
193 |
|
the C++ wrapper library, you can add --disable-cpp to the "configure" |
194 |
|
command. Otherwise, when "configure" is run without --disable-pcre8, it will |
195 |
|
try to find a C++ compiler and C++ header files, and if it succeeds, it will |
196 |
|
try to build the C++ wrapper. |
197 |
|
|
198 |
. If you want to include support for just-in-time compiling, which can give |
. If you want to include support for just-in-time compiling, which can give |
199 |
large performance improvements on certain platforms, add --enable-jit to the |
large performance improvements on certain platforms, add --enable-jit to the |
205 |
you add --disable-pcregrep-jit to the "configure" command. |
you add --disable-pcregrep-jit to the "configure" command. |
206 |
|
|
207 |
. If you want to make use of the support for UTF-8 Unicode character strings in |
. If you want to make use of the support for UTF-8 Unicode character strings in |
208 |
PCRE, you must add --enable-utf8 to the "configure" command. Without it, the |
the 8-bit library, or UTF-16 Unicode character strings in the 16-bit library, |
209 |
code for handling UTF-8 is not included in the library. Even when included, |
or UTF-32 Unicode character strings in the 32-bit library, you must add |
210 |
it still has to be enabled by an option at run time. When PCRE is compiled |
--enable-utf to the "configure" command. Without it, the code for handling |
211 |
with this option, its input can only either be ASCII or UTF-8, even when |
UTF-8, UTF-16 and UTF-8 is not included in the relevant library. Even |
212 |
running on EBCDIC platforms. It is not possible to use both --enable-utf8 and |
when --enable-utf is included, the use of a UTF encoding still has to be |
213 |
--enable-ebcdic at the same time. |
enabled by an option at run time. When PCRE is compiled with this option, its |
214 |
|
input can only either be ASCII or UTF-8/16/32, even when running on EBCDIC |
215 |
. If, in addition to support for UTF-8 character strings, you want to include |
platforms. It is not possible to use both --enable-utf and --enable-ebcdic at |
216 |
support for the \P, \p, and \X sequences that recognize Unicode character |
the same time. |
217 |
properties, you must add --enable-unicode-properties to the "configure" |
|
218 |
command. This adds about 30K to the size of the library (in the form of a |
. There are no separate options for enabling UTF-8, UTF-16 and UTF-32 |
219 |
property table); only the basic two-letter properties such as Lu are |
independently because that would allow ridiculous settings such as requesting |
220 |
supported. |
UTF-16 support while building only the 8-bit library. However, the option |
221 |
|
--enable-utf8 is retained for backwards compatibility with earlier releases |
222 |
|
that did not support 16-bit or 32-bit character strings. It is synonymous with |
223 |
|
--enable-utf. It is not possible to configure one library with UTF support |
224 |
|
and the other without in the same configuration. |
225 |
|
|
226 |
|
. If, in addition to support for UTF-8/16/32 character strings, you want to |
227 |
|
include support for the \P, \p, and \X sequences that recognize Unicode |
228 |
|
character properties, you must add --enable-unicode-properties to the |
229 |
|
"configure" command. This adds about 30K to the size of the library (in the |
230 |
|
form of a property table); only the basic two-letter properties such as Lu |
231 |
|
are supported. |
232 |
|
|
233 |
. You can build PCRE to recognize either CR or LF or the sequence CRLF or any |
. You can build PCRE to recognize either CR or LF or the sequence CRLF or any |
234 |
of the preceding, or any of the Unicode newline sequences as indicating the |
of the preceding, or any of the Unicode newline sequences as indicating the |
281 |
sizes in the pcrestack man page. |
sizes in the pcrestack man page. |
282 |
|
|
283 |
. The default maximum compiled pattern size is around 64K. You can increase |
. The default maximum compiled pattern size is around 64K. You can increase |
284 |
this by adding --with-link-size=3 to the "configure" command. You can |
this by adding --with-link-size=3 to the "configure" command. In the 8-bit |
285 |
increase it even more by setting --with-link-size=4, but this is unlikely |
library, PCRE then uses three bytes instead of two for offsets to different |
286 |
ever to be necessary. Increasing the internal link size will reduce |
parts of the compiled pattern. In the 16-bit library, --with-link-size=3 is |
287 |
performance. |
the same as --with-link-size=4, which (in both libraries) uses four-byte |
288 |
|
offsets. Increasing the internal link size reduces performance. In the 32-bit |
289 |
|
library, the only supported link size is 4. |
290 |
|
|
291 |
. You can build PCRE so that its internal match() function that is called from |
. You can build PCRE so that its internal match() function that is called from |
292 |
pcre_exec() does not call itself recursively. Instead, it uses memory blocks |
pcre_exec() does not call itself recursively. Instead, it uses memory blocks |
315 |
pcre_chartables.c.dist. See "Character tables" below for further information. |
pcre_chartables.c.dist. See "Character tables" below for further information. |
316 |
|
|
317 |
. It is possible to compile PCRE for use on systems that use EBCDIC as their |
. It is possible to compile PCRE for use on systems that use EBCDIC as their |
318 |
character code (as opposed to ASCII) by specifying |
character code (as opposed to ASCII/Unicode) by specifying |
319 |
|
|
320 |
--enable-ebcdic |
--enable-ebcdic |
321 |
|
|
322 |
This automatically implies --enable-rebuild-chartables (see above). However, |
This automatically implies --enable-rebuild-chartables (see above). However, |
323 |
when PCRE is built this way, it always operates in EBCDIC. It cannot support |
when PCRE is built this way, it always operates in EBCDIC. It cannot support |
324 |
both EBCDIC and UTF-8. |
both EBCDIC and UTF-8/16/32. There is a second option, --enable-ebcdic-nl25, |
325 |
|
which specifies that the code value for the EBCDIC NL character is 0x25 |
326 |
|
instead of the default 0x15. |
327 |
|
|
328 |
|
. In environments where valgrind is installed, if you specify |
329 |
|
|
330 |
|
--enable-valgrind |
331 |
|
|
332 |
|
PCRE will use valgrind annotations to mark certain memory regions as |
333 |
|
unaddressable. This allows it to detect invalid memory accesses, and is |
334 |
|
mostly useful for debugging PCRE itself. |
335 |
|
|
336 |
|
. In environments where the gcc compiler is used and lcov version 1.6 or above |
337 |
|
is installed, if you specify |
338 |
|
|
339 |
|
--enable-coverage |
340 |
|
|
341 |
. It is possible to compile pcregrep to use libz and/or libbz2, in order to |
the build process implements a code coverage report for the test suite. The |
342 |
read .gz and .bz2 files (respectively), by specifying one or both of |
report is generated by running "make coverage". If ccache is installed on |
343 |
|
your system, it must be disabled when building PCRE for coverage reporting. |
344 |
|
You can do this by setting the environment variable CCACHE_DISABLE=1 before |
345 |
|
running "make" to build PCRE. |
346 |
|
|
347 |
|
. The pcregrep program currently supports only 8-bit data files, and so |
348 |
|
requires the 8-bit PCRE library. It is possible to compile pcregrep to use |
349 |
|
libz and/or libbz2, in order to read .gz and .bz2 files (respectively), by |
350 |
|
specifying one or both of |
351 |
|
|
352 |
--enable-pcregrep-libz |
--enable-pcregrep-libz |
353 |
--enable-pcregrep-libbz2 |
--enable-pcregrep-libbz2 |
362 |
The default value is 20K. |
The default value is 20K. |
363 |
|
|
364 |
. It is possible to compile pcretest so that it links with the libreadline |
. It is possible to compile pcretest so that it links with the libreadline |
365 |
library, by specifying |
or libedit libraries, by specifying, respectively, |
366 |
|
|
367 |
--enable-pcretest-libreadline |
--enable-pcretest-libreadline or --enable-pcretest-libedit |
368 |
|
|
369 |
If this is done, when pcretest's input is from a terminal, it reads it using |
If this is done, when pcretest's input is from a terminal, it reads it using |
370 |
the readline() function. This provides line-editing and history facilities. |
the readline() function. This provides line-editing and history facilities. |
371 |
Note that libreadline is GPL-licenced, so if you distribute a binary of |
Note that libreadline is GPL-licenced, so if you distribute a binary of |
372 |
pcretest linked in this way, there may be licensing issues. |
pcretest linked in this way, there may be licensing issues. These can be |
373 |
|
avoided by linking with libedit (which has a BSD licence) instead. |
374 |
|
|
375 |
Setting this option causes the -lreadline option to be added to the pcretest |
Enabling libreadline causes the -lreadline option to be added to the pcretest |
376 |
build. In many operating environments with a sytem-installed readline |
build. In many operating environments with a sytem-installed readline |
377 |
library this is sufficient. However, in some environments (e.g. if an |
library this is sufficient. However, in some environments (e.g. if an |
378 |
unmodified distribution version of readline is in use), it may be necessary |
unmodified distribution version of readline is in use), it may be necessary |
391 |
. pcre-config script that shows the building settings such as CFLAGS |
. pcre-config script that shows the building settings such as CFLAGS |
392 |
that were set for "configure" |
that were set for "configure" |
393 |
. libpcre.pc ) data for the pkg-config command |
. libpcre.pc ) data for the pkg-config command |
394 |
|
. libpcre16.pc ) |
395 |
|
. libpcre32.pc ) |
396 |
. libpcreposix.pc ) |
. libpcreposix.pc ) |
397 |
. libtool script that builds shared and/or static libraries |
. libtool script that builds shared and/or static libraries |
|
. RunTest script for running tests on the basic C library |
|
|
. RunGrepTest script for running tests on the pcregrep command |
|
398 |
|
|
399 |
Versions of config.h and pcre.h are distributed in the PCRE tarballs under the |
Versions of config.h and pcre.h are distributed in the PCRE tarballs under the |
400 |
names config.h.generic and pcre.h.generic. These are provided for those who |
names config.h.generic and pcre.h.generic. These are provided for those who |
401 |
have to built PCRE without using "configure" or CMake. If you use "configure" |
have to built PCRE without using "configure" or CMake. If you use "configure" |
402 |
or CMake, the .generic versions are not used. |
or CMake, the .generic versions are not used. |
403 |
|
|
404 |
If a C++ compiler is found, the following files are also built: |
When building the 8-bit library, if a C++ compiler is found, the following |
405 |
|
files are also built: |
406 |
|
|
407 |
. libpcrecpp.pc data for the pkg-config command |
. libpcrecpp.pc data for the pkg-config command |
408 |
. pcrecpparg.h header file for calling PCRE via the C++ wrapper |
. pcrecpparg.h header file for calling PCRE via the C++ wrapper |
412 |
script that can be run to recreate the configuration, and config.log, which |
script that can be run to recreate the configuration, and config.log, which |
413 |
contains compiler output from tests that "configure" runs. |
contains compiler output from tests that "configure" runs. |
414 |
|
|
415 |
Once "configure" has run, you can run "make". It builds two libraries, called |
Once "configure" has run, you can run "make". This builds the the libraries |
416 |
libpcre and libpcreposix, a test program called pcretest, and the pcregrep |
libpcre, libpcre16 and/or libpcre32, and a test program called pcretest. If you |
417 |
command. If a C++ compiler was found on your system, and you did not disable it |
enabled JIT support with --enable-jit, a test program called pcre_jit_test is |
418 |
with --disable-cpp, "make" also builds the C++ wrapper library, which is called |
built as well. |
419 |
libpcrecpp, and some test programs called pcrecpp_unittest, |
|
420 |
pcre_scanner_unittest, and pcre_stringpiece_unittest. If you enabled JIT |
If the 8-bit library is built, libpcreposix and the pcregrep command are also |
421 |
support with --enable-jit, a test program called pcre_jit_test is also built. |
built, and if a C++ compiler was found on your system, and you did not disable |
422 |
|
it with --disable-cpp, "make" builds the C++ wrapper library, which is called |
423 |
|
libpcrecpp, as well as some test programs called pcrecpp_unittest, |
424 |
|
pcre_scanner_unittest, and pcre_stringpiece_unittest. |
425 |
|
|
426 |
The command "make check" runs all the appropriate tests. Details of the PCRE |
The command "make check" runs all the appropriate tests. Details of the PCRE |
427 |
tests are given below in a separate section of this document. |
tests are given below in a separate section of this document. |
432 |
|
|
433 |
Commands (bin): |
Commands (bin): |
434 |
pcretest |
pcretest |
435 |
pcregrep |
pcregrep (if 8-bit support is enabled) |
436 |
pcre-config |
pcre-config |
437 |
|
|
438 |
Libraries (lib): |
Libraries (lib): |
439 |
libpcre |
libpcre16 (if 16-bit support is enabled) |
440 |
libpcreposix |
libpcre32 (if 32-bit support is enabled) |
441 |
libpcrecpp (if C++ support is enabled) |
libpcre (if 8-bit support is enabled) |
442 |
|
libpcreposix (if 8-bit support is enabled) |
443 |
|
libpcrecpp (if 8-bit and C++ support is enabled) |
444 |
|
|
445 |
Configuration information (lib/pkgconfig): |
Configuration information (lib/pkgconfig): |
446 |
|
libpcre16.pc |
447 |
|
libpcre32.pc |
448 |
libpcre.pc |
libpcre.pc |
449 |
libpcreposix.pc |
libpcreposix.pc |
450 |
libpcrecpp.pc (if C++ support is enabled) |
libpcrecpp.pc (if C++ support is enabled) |
485 |
remove any directories, because these are often shared with other programs. |
remove any directories, because these are often shared with other programs. |
486 |
|
|
487 |
|
|
488 |
Retrieving configuration information on Unix-like systems |
Retrieving configuration information |
489 |
--------------------------------------------------------- |
------------------------------------ |
490 |
|
|
491 |
Running "make install" installs the command pcre-config, which can be used to |
Running "make install" installs the command pcre-config, which can be used to |
492 |
recall information about the PCRE configuration and installation. For example: |
recall information about the PCRE configuration and installation. For example: |
511 |
<prefix>/lib/pkgconfig. |
<prefix>/lib/pkgconfig. |
512 |
|
|
513 |
|
|
514 |
Shared libraries on Unix-like systems |
Shared libraries |
515 |
------------------------------------- |
---------------- |
516 |
|
|
517 |
The default distribution builds PCRE as shared libraries and static libraries, |
The default distribution builds PCRE as shared libraries and static libraries, |
518 |
as long as the operating system supports shared libraries. Shared library |
as long as the operating system supports shared libraries. Shared library |
537 |
build only shared libraries. |
build only shared libraries. |
538 |
|
|
539 |
|
|
540 |
Cross-compiling on Unix-like systems |
Cross-compiling using autotools |
541 |
------------------------------------ |
------------------------------- |
542 |
|
|
543 |
You can specify CC and CFLAGS in the normal way to the "configure" command, in |
You can specify CC and CFLAGS in the normal way to the "configure" command, in |
544 |
order to cross-compile PCRE for some other host. However, you should NOT |
order to cross-compile PCRE for some other host. However, you should NOT |
610 |
Testing PCRE |
Testing PCRE |
611 |
------------ |
------------ |
612 |
|
|
613 |
To test the basic PCRE library on a Unix system, run the RunTest script that is |
To test the basic PCRE library on a Unix-like system, run the RunTest script. |
614 |
created by the configuring process. There is also a script called RunGrepTest |
There is another script called RunGrepTest that tests the options of the |
615 |
that tests the options of the pcregrep command. If the C++ wrapper library is |
pcregrep command. If the C++ wrapper library is built, three test programs |
616 |
built, three test programs called pcrecpp_unittest, pcre_scanner_unittest, and |
called pcrecpp_unittest, pcre_scanner_unittest, and pcre_stringpiece_unittest |
617 |
pcre_stringpiece_unittest are also built. When JIT support is enabled, another |
are also built. When JIT support is enabled, another test program called |
618 |
test program called pcre_jit_test is built. |
pcre_jit_test is built. |
619 |
|
|
620 |
Both the scripts and all the program tests are run if you obey "make check" or |
Both the scripts and all the program tests are run if you obey "make check" or |
621 |
"make test". For other systems, see the instructions in NON-UNIX-USE. |
"make test". For other environments, see the instructions in |
622 |
|
NON-AUTOTOOLS-BUILD. |
623 |
|
|
624 |
The RunTest script runs the pcretest test program (which is documented in its |
The RunTest script runs the pcretest test program (which is documented in its |
625 |
own man page) on each of the relevant testinput files in the testdata |
own man page) on each of the relevant testinput files in the testdata |
626 |
directory, and compares the output with the contents of the corresponding |
directory, and compares the output with the contents of the corresponding |
627 |
testoutput files. Some tests are relevant only when certain build-time options |
testoutput files. Some tests are relevant only when certain build-time options |
628 |
were selected. For example, the tests for UTF-8 support are run only if |
were selected. For example, the tests for UTF-8/16/32 support are run only if |
629 |
--enable-utf8 was used. RunTest outputs a comment when it skips a test. |
--enable-utf was used. RunTest outputs a comment when it skips a test. |
630 |
|
|
631 |
Many of the tests that are not skipped are run up to three times. The second |
Many of the tests that are not skipped are run up to three times. The second |
632 |
run forces pcre_study() to be called for all patterns except for a few in some |
run forces pcre_study() to be called for all patterns except for a few in some |
633 |
tests that are marked "never study" (see the pcretest program for how this is |
tests that are marked "never study" (see the pcretest program for how this is |
634 |
done). If JIT support is available, the non-DFA tests are run a third time, |
done). If JIT support is available, the non-DFA tests are run a third time, |
635 |
this time with a forced pcre_study() with the PCRE_STUDY_JIT_COMPILE option. |
this time with a forced pcre_study() with the PCRE_STUDY_JIT_COMPILE option. |
636 |
|
This testing can be suppressed by putting "nojit" on the RunTest command line. |
637 |
|
|
638 |
|
The entire set of tests is run once for each of the 8-bit, 16-bit and 32-bit |
639 |
|
libraries that are enabled. If you want to run just one set of tests, call |
640 |
|
RunTest with either the -8, -16 or -32 option. |
641 |
|
|
642 |
RunTest uses a file called testtry to hold the main output from pcretest |
If valgrind is installed, you can run the tests under it by putting "valgrind" |
643 |
(testsavedregex is also used as a working file). To run pcretest on just one of |
on the RunTest command line. |
|
the test files, give its number as an argument to RunTest, for example: |
|
644 |
|
|
645 |
RunTest 2 |
RunTest uses a file called testtry to hold the main output from pcretest. |
646 |
|
Other files whose names begin with "test" are used as working files in some |
647 |
|
tests. To run pcretest on just one or more specific test files, give their |
648 |
|
numbers as arguments to RunTest, for example: |
649 |
|
|
650 |
|
RunTest 2 7 11 |
651 |
|
|
652 |
|
You can also call RunTest with the single argument "list" to cause it to output |
653 |
|
a list of tests. |
654 |
|
|
655 |
The first test file can be fed directly into the perltest.pl script to check |
The first test file can be fed directly into the perltest.pl script to check |
656 |
that Perl gives the same results. The only difference you should see is in the |
that Perl gives the same results. The only difference you should see is in the |
657 |
first few lines, where the Perl version is given instead of the PCRE version. |
first few lines, where the Perl version is given instead of the PCRE version. |
658 |
|
|
659 |
The second set of tests check pcre_fullinfo(), pcre_info(), pcre_study(), |
The second set of tests check pcre_fullinfo(), pcre_study(), |
660 |
pcre_copy_substring(), pcre_get_substring(), pcre_get_substring_list(), error |
pcre_copy_substring(), pcre_get_substring(), pcre_get_substring_list(), error |
661 |
detection, and run-time flags that are specific to PCRE, as well as the POSIX |
detection, and run-time flags that are specific to PCRE, as well as the POSIX |
662 |
wrapper API. It also uses the debugging flags to check some of the internals of |
wrapper API. It also uses the debugging flags to check some of the internals of |
691 |
Windows versions of test 2. More info on using RunTest.bat is included in the |
Windows versions of test 2. More info on using RunTest.bat is included in the |
692 |
document entitled NON-UNIX-USE.] |
document entitled NON-UNIX-USE.] |
693 |
|
|
694 |
The fourth test checks the UTF-8 support. This file can be also fed directly to |
The fourth and fifth tests check the UTF-8/16/32 support and error handling and |
695 |
the perltest.pl script, provided you are running Perl 5.8 or higher. |
internal UTF features of PCRE that are not relevant to Perl, respectively. The |
696 |
|
sixth and seventh tests do the same for Unicode character properties support. |
697 |
|
|
698 |
|
The eighth, ninth, and tenth tests check the pcre_dfa_exec() alternative |
699 |
|
matching function, in non-UTF-8/16/32 mode, UTF-8/16/32 mode, and UTF-8/16/32 |
700 |
|
mode with Unicode property support, respectively. |
701 |
|
|
702 |
The fifth test checks error handling with UTF-8 encoding, and internal UTF-8 |
The eleventh test checks some internal offsets and code size features; it is |
703 |
features of PCRE that are not relevant to Perl. |
run only when the default "link size" of 2 is set (in other cases the sizes |
704 |
|
change) and when Unicode property support is enabled. |
705 |
|
|
706 |
The sixth test (which is Perl-5.10 compatible) checks the support for Unicode |
The twelfth test is run only when JIT support is available, and the thirteenth |
707 |
character properties. This file can be also fed directly to the perltest.pl |
test is run only when JIT support is not available. They test some JIT-specific |
708 |
script, provided you are running Perl 5.10 or higher. |
features such as information output from pcretest about JIT compilation. |
709 |
|
|
710 |
The seventh, eighth, and ninth tests check the pcre_dfa_exec() alternative |
The fourteenth, fifteenth, and sixteenth tests are run only in 8-bit mode, and |
711 |
matching function, in non-UTF-8 mode, UTF-8 mode, and UTF-8 mode with Unicode |
the seventeenth, eighteenth, and nineteenth tests are run only in 16/32-bit mode. |
712 |
property support, respectively. |
These are tests that generate different output in the two modes. They are for |
713 |
|
general cases, UTF-8/16/32 support, and Unicode property support, respectively. |
714 |
|
|
715 |
|
The twentieth test is run only in 16/32-bit mode. It tests some specific |
716 |
|
16/32-bit features of the DFA matching engine. |
717 |
|
|
718 |
The tenth test checks some internal offsets and code size features; it is run |
The twenty-first and twenty-second tests are run only in 16/32-bit mode, when the |
719 |
only when the default "link size" of 2 is set (in other cases the sizes |
link size is set to 2 for the 16-bit library. They test reloading pre-compiled patterns. |
|
change) and when Unicode property support is enabled. |
|
720 |
|
|
721 |
The eleventh and twelfth tests check out features that are new in Perl 5.10, |
The twenty-third and twenty-fourth tests are run only in 16-bit mode. They are for |
722 |
without and with UTF-8 support, respectively. This file can be also fed |
general cases, and UTF-16 support, respectively. |
|
directly to the perltest.pl script, provided you are running Perl 5.10 or |
|
|
higher. |
|
|
|
|
|
The thirteenth test checks a number internals and non-Perl features concerned |
|
|
with Unicode property support. |
|
|
|
|
|
The fourteenth test is run only when JIT support is available, and the |
|
|
fifteenth test is run only when JIT support is not available. They test some |
|
|
JIT-specific features such as information output from pcretest about JIT |
|
|
compilation. |
|
723 |
|
|
724 |
|
The twenty-fifth and twenty-sixth tests are run only in 32-bit mode. They are for |
725 |
|
general cases, and UTF-32 support, respectively. |
726 |
|
|
727 |
Character tables |
Character tables |
728 |
---------------- |
---------------- |
781 |
File manifest |
File manifest |
782 |
------------- |
------------- |
783 |
|
|
784 |
The distribution should contain the following files: |
The distribution should contain the files listed below. Where a file name is |
785 |
|
given as pcre[16|32]_xxx it means that there are three files, one with the name |
786 |
|
pcre_xxx, one with the name pcre16_xx, and a third with the name pcre32_xxx. |
787 |
|
|
788 |
(A) Source files of the PCRE library functions and their headers: |
(A) Source files of the PCRE library functions and their headers: |
789 |
|
|
792 |
|
|
793 |
pcre_chartables.c.dist a default set of character tables that assume ASCII |
pcre_chartables.c.dist a default set of character tables that assume ASCII |
794 |
coding; used, unless --enable-rebuild-chartables is |
coding; used, unless --enable-rebuild-chartables is |
795 |
specified, by copying to pcre_chartables.c |
specified, by copying to pcre[16]_chartables.c |
796 |
|
|
797 |
|
pcreposix.c ) |
798 |
|
pcre[16|32]_byte_order.c ) |
799 |
|
pcre[16|32]_compile.c ) |
800 |
|
pcre[16|32]_config.c ) |
801 |
|
pcre[16|32]_dfa_exec.c ) |
802 |
|
pcre[16|32]_exec.c ) |
803 |
|
pcre[16|32]_fullinfo.c ) |
804 |
|
pcre[16|32]_get.c ) sources for the functions in the library, |
805 |
|
pcre[16|32]_globals.c ) and some internal functions that they use |
806 |
|
pcre[16|32]_jit_compile.c ) |
807 |
|
pcre[16|32]_maketables.c ) |
808 |
|
pcre[16|32]_newline.c ) |
809 |
|
pcre[16|32]_refcount.c ) |
810 |
|
pcre[16|32]_string_utils.c ) |
811 |
|
pcre[16|32]_study.c ) |
812 |
|
pcre[16|32]_tables.c ) |
813 |
|
pcre[16|32]_ucd.c ) |
814 |
|
pcre[16|32]_version.c ) |
815 |
|
pcre[16|32]_xclass.c ) |
816 |
|
pcre_ord2utf8.c ) |
817 |
|
pcre_valid_utf8.c ) |
818 |
|
pcre16_ord2utf16.c ) |
819 |
|
pcre16_utf16_utils.c ) |
820 |
|
pcre16_valid_utf16.c ) |
821 |
|
pcre32_utf32_utils.c ) |
822 |
|
pcre32_valid_utf32.c ) |
823 |
|
|
824 |
|
pcre[16|32]_printint.c ) debugging function that is used by pcretest, |
825 |
|
) and can also be #included in pcre_compile() |
826 |
|
|
|
pcreposix.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_jit_compile.c ) |
|
|
pcre_maketables.c ) |
|
|
pcre_newline.c ) |
|
|
pcre_ord2utf8.c ) |
|
|
pcre_refcount.c ) |
|
|
pcre_study.c ) |
|
|
pcre_tables.c ) |
|
|
pcre_try_flipped.c ) |
|
|
pcre_ucd.c ) |
|
|
pcre_valid_utf8.c ) |
|
|
pcre_version.c ) |
|
|
pcre_xclass.c ) |
|
|
pcre_printint.src ) debugging function that is #included in pcretest, |
|
|
) and can also be #included in pcre_compile() |
|
827 |
pcre.h.in template for pcre.h when built by "configure" |
pcre.h.in template for pcre.h when built by "configure" |
828 |
pcreposix.h header for the external POSIX wrapper API |
pcreposix.h header for the external POSIX wrapper API |
829 |
pcre_internal.h header for internal use |
pcre_internal.h header for internal use |
864 |
Makefile.am ) the automake input that was used to create |
Makefile.am ) the automake input that was used to create |
865 |
) Makefile.in |
) Makefile.in |
866 |
NEWS important changes in this release |
NEWS important changes in this release |
867 |
NON-UNIX-USE notes on building PCRE on non-Unix systems |
NON-UNIX-USE the previous name for NON-AUTOTOOLS-BUILD |
868 |
|
NON-AUTOTOOLS-BUILD notes on building PCRE without using autotools |
869 |
PrepareRelease script to make preparations for "make dist" |
PrepareRelease script to make preparations for "make dist" |
870 |
README this file |
README this file |
871 |
RunTest a Unix shell script for running tests |
RunTest a Unix shell script for running tests |
886 |
doc/pcretest.txt plain text documentation of test program |
doc/pcretest.txt plain text documentation of test program |
887 |
doc/perltest.txt plain text documentation of Perl test program |
doc/perltest.txt plain text documentation of Perl test program |
888 |
install-sh a shell script for installing files |
install-sh a shell script for installing files |
889 |
|
libpcre16.pc.in template for libpcre16.pc for pkg-config |
890 |
|
libpcre32.pc.in template for libpcre32.pc for pkg-config |
891 |
libpcre.pc.in template for libpcre.pc for pkg-config |
libpcre.pc.in template for libpcre.pc for pkg-config |
892 |
libpcreposix.pc.in template for libpcreposix.pc for pkg-config |
libpcreposix.pc.in template for libpcreposix.pc for pkg-config |
893 |
libpcrecpp.pc.in template for libpcrecpp.pc for pkg-config |
libpcrecpp.pc.in template for libpcrecpp.pc for pkg-config |
904 |
testdata/testinput* test data for main library tests |
testdata/testinput* test data for main library tests |
905 |
testdata/testoutput* expected test results |
testdata/testoutput* expected test results |
906 |
testdata/grep* input and output for pcregrep tests |
testdata/grep* input and output for pcregrep tests |
907 |
|
testdata/* other supporting test files |
908 |
|
|
909 |
(D) Auxiliary files for cmake support |
(D) Auxiliary files for cmake support |
910 |
|
|
911 |
cmake/COPYING-CMAKE-SCRIPTS |
cmake/COPYING-CMAKE-SCRIPTS |
912 |
cmake/FindPackageHandleStandardArgs.cmake |
cmake/FindPackageHandleStandardArgs.cmake |
913 |
|
cmake/FindEditline.cmake |
914 |
cmake/FindReadline.cmake |
cmake/FindReadline.cmake |
915 |
CMakeLists.txt |
CMakeLists.txt |
916 |
config-cmake.h.in |
config-cmake.h.in |
936 |
Philip Hazel |
Philip Hazel |
937 |
Email local part: ph10 |
Email local part: ph10 |
938 |
Email domain: cam.ac.uk |
Email domain: cam.ac.uk |
939 |
Last updated: 06 September 2011 |
Last updated: 20 February 2013 |