| 24 |
Shared libraries on Unix-like systems |
Shared libraries on Unix-like systems |
| 25 |
Cross-compiling on Unix-like systems |
Cross-compiling on Unix-like systems |
| 26 |
Using HP's ANSI C++ compiler (aCC) |
Using HP's ANSI C++ compiler (aCC) |
| 27 |
|
Using PCRE from MySQL |
| 28 |
Making new tarballs |
Making new tarballs |
| 29 |
Testing PCRE |
Testing PCRE |
| 30 |
Character tables |
Character tables |
| 34 |
The PCRE APIs |
The PCRE APIs |
| 35 |
------------- |
------------- |
| 36 |
|
|
| 37 |
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 two sets of functions, |
| 38 |
set of C++ wrapper functions (see the pcrecpp man page for details), courtesy |
one for the 8-bit library, which processes strings of bytes, and one for the |
| 39 |
of Google Inc. |
16-bit library, which processes strings of 16-bit values. The distribution also |
| 40 |
|
includes a set of C++ wrapper functions (see the pcrecpp man page for details), |
| 41 |
In addition, there is a set of C wrapper functions that are based on the POSIX |
courtesy of Google Inc., which can be used to call the 8-bit PCRE library from |
| 42 |
regular expression API (see the pcreposix man page). These end up in the |
C++. |
| 43 |
library called libpcreposix. Note that this just provides a POSIX calling |
|
| 44 |
interface to PCRE; the regular expressions themselves still follow Perl syntax |
In addition, there is a set of C wrapper functions (again, just for the 8-bit |
| 45 |
and semantics. The POSIX API is restricted, and does not give full access to |
library) that are based on the POSIX regular expression API (see the pcreposix |
| 46 |
all of PCRE's facilities. |
man page). These end up in the library called libpcreposix. Note that this just |
| 47 |
|
provides a POSIX calling interface to PCRE; the regular expressions themselves |
| 48 |
|
still follow Perl syntax and semantics. The POSIX API is restricted, and does |
| 49 |
|
not give full access to all of PCRE's facilities. |
| 50 |
|
|
| 51 |
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 |
| 52 |
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 |
| 89 |
in various ways, and rooted in a file called index.html, is distributed in |
in various ways, and rooted in a file called index.html, is distributed in |
| 90 |
doc/html and installed in <prefix>/share/doc/pcre/html. |
doc/html and installed in <prefix>/share/doc/pcre/html. |
| 91 |
|
|
| 92 |
|
Users of PCRE have contributed files containing the documentation for various |
| 93 |
|
releases in CHM format. These can be found in the Contrib directory of the FTP |
| 94 |
|
site (see next section). |
| 95 |
|
|
| 96 |
|
|
| 97 |
Contributions by users of PCRE |
Contributions by users of PCRE |
| 98 |
------------------------------ |
------------------------------ |
| 115 |
For a non-Unix system, please read the comments in the file NON-UNIX-USE, |
For a non-Unix system, please read the comments in the file NON-UNIX-USE, |
| 116 |
though if your system supports the use of "configure" and "make" you may be |
though if your system supports the use of "configure" and "make" you may be |
| 117 |
able to build PCRE in the same way as for Unix-like systems. PCRE can also be |
able to build PCRE in the same way as for Unix-like systems. PCRE can also be |
| 118 |
configured in many platform environments using the GUI facility of CMake's |
configured in many platform environments using the GUI facility provided by |
| 119 |
CMakeSetup. It creates Makefiles, solution files, etc. |
CMake's cmake-gui command. This creates Makefiles, solution files, etc. |
| 120 |
|
|
| 121 |
PCRE has been compiled on many different operating systems. It should be |
PCRE has been compiled on many different operating systems. It should be |
| 122 |
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 |
| 146 |
|
|
| 147 |
CFLAGS='-O2 -Wall' ./configure --prefix=/opt/local |
CFLAGS='-O2 -Wall' ./configure --prefix=/opt/local |
| 148 |
|
|
| 149 |
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 |
| 150 |
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 |
| 151 |
instead of the default /usr/local. |
under /opt/local instead of the default /usr/local. |
| 152 |
|
|
| 153 |
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 |
| 154 |
directory as current. For example, suppose you have unpacked the PCRE source |
directory as current. For example, suppose you have unpacked the PCRE source |
| 162 |
does not have any features to support this. |
does not have any features to support this. |
| 163 |
|
|
| 164 |
There are some optional features that can be included or omitted from the PCRE |
There are some optional features that can be included or omitted from the PCRE |
| 165 |
library. You can read more about them in the pcrebuild man page. |
library. They are also documented in the pcrebuild man page. |
| 166 |
|
|
| 167 |
|
. By default, both shared and static libraries are built. You can change this |
| 168 |
|
by adding one of these options to the "configure" command: |
| 169 |
|
|
| 170 |
|
--disable-shared |
| 171 |
|
--disable-static |
| 172 |
|
|
| 173 |
. If you want to suppress the building of the C++ wrapper library, you can add |
(See also "Shared libraries on Unix-like systems" below.) |
| 174 |
--disable-cpp to the "configure" command. Otherwise, when "configure" is run, |
|
| 175 |
it will try to find a C++ compiler and C++ header files, and if it succeeds, |
. By default, only the 8-bit library is built. If you add --enable-pcre16 to |
| 176 |
it will try to build the C++ wrapper. |
the "configure" command, the 16-bit library is also built. If you want only |
| 177 |
|
the 16-bit library, use "./configure --enable-pcre16 --disable-pcre8". |
| 178 |
|
|
| 179 |
|
. If you are building the 8-bit library and want to suppress the building of |
| 180 |
|
the C++ wrapper library, you can add --disable-cpp to the "configure" |
| 181 |
|
command. Otherwise, when "configure" is run without --disable-pcre8, it will |
| 182 |
|
try to find a C++ compiler and C++ header files, and if it succeeds, it will |
| 183 |
|
try to build the C++ wrapper. |
| 184 |
|
|
| 185 |
|
. If you want to include support for just-in-time compiling, which can give |
| 186 |
|
large performance improvements on certain platforms, add --enable-jit to the |
| 187 |
|
"configure" command. This support is available only for certain hardware |
| 188 |
|
architectures. If you try to enable it on an unsupported architecture, there |
| 189 |
|
will be a compile time error. |
| 190 |
|
|
| 191 |
|
. When JIT support is enabled, pcregrep automatically makes use of it, unless |
| 192 |
|
you add --disable-pcregrep-jit to the "configure" command. |
| 193 |
|
|
| 194 |
. 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 |
| 195 |
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, |
| 196 |
code for handling UTF-8 is not included in the library. Even when included, |
you must add --enable-utf to the "configure" command. Without it, the code |
| 197 |
it still has to be enabled by an option at run time. When PCRE is compiled |
for handling UTF-8 and UTF-16 is not included in the relevant library. Even |
| 198 |
with this option, its input can only either be ASCII or UTF-8, even when |
when --enable-utf is included, the use of a UTF encoding still has to be |
| 199 |
running on EBCDIC platforms. It is not possible to use both --enable-utf8 and |
enabled by an option at run time. When PCRE is compiled with this option, its |
| 200 |
--enable-ebcdic at the same time. |
input can only either be ASCII or UTF-8/16, even when running on EBCDIC |
| 201 |
|
platforms. It is not possible to use both --enable-utf and --enable-ebcdic at |
| 202 |
. If, in addition to support for UTF-8 character strings, you want to include |
the same time. |
| 203 |
support for the \P, \p, and \X sequences that recognize Unicode character |
|
| 204 |
properties, you must add --enable-unicode-properties to the "configure" |
. There are no separate options for enabling UTF-8 and UTF-16 independently |
| 205 |
command. This adds about 30K to the size of the library (in the form of a |
because that would allow ridiculous settings such as requesting UTF-16 |
| 206 |
property table); only the basic two-letter properties such as Lu are |
support while building only the 8-bit library. However, the option |
| 207 |
supported. |
--enable-utf8 is retained for backwards compatibility with earlier releases |
| 208 |
|
that did not support 16-bit character strings. It is synonymous with |
| 209 |
|
--enable-utf. It is not possible to configure one library with UTF support |
| 210 |
|
and the other without in the same configuration. |
| 211 |
|
|
| 212 |
|
. If, in addition to support for UTF-8/16 character strings, you want to |
| 213 |
|
include support for the \P, \p, and \X sequences that recognize Unicode |
| 214 |
|
character properties, you must add --enable-unicode-properties to the |
| 215 |
|
"configure" command. This adds about 30K to the size of the library (in the |
| 216 |
|
form of a property table); only the basic two-letter properties such as Lu |
| 217 |
|
are supported. |
| 218 |
|
|
| 219 |
. 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 |
| 220 |
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 |
| 267 |
sizes in the pcrestack man page. |
sizes in the pcrestack man page. |
| 268 |
|
|
| 269 |
. The default maximum compiled pattern size is around 64K. You can increase |
. The default maximum compiled pattern size is around 64K. You can increase |
| 270 |
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 |
| 271 |
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 |
| 272 |
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 |
| 273 |
performance. |
the same as --with-link-size=4, which (in both libraries) uses four-byte |
| 274 |
|
offsets. Increasing the internal link size reduces performance. |
| 275 |
|
|
| 276 |
. 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 |
| 277 |
pcre_exec() does not call itself recursively. Instead, it uses memory blocks |
pcre_exec() does not call itself recursively. Instead, it uses memory blocks |
| 283 |
|
|
| 284 |
on the "configure" command. PCRE runs more slowly in this mode, but it may be |
on the "configure" command. PCRE runs more slowly in this mode, but it may be |
| 285 |
necessary in environments with limited stack sizes. This applies only to the |
necessary in environments with limited stack sizes. This applies only to the |
| 286 |
pcre_exec() function; it does not apply to pcre_dfa_exec(), which does not |
normal execution of the pcre_exec() function; if JIT support is being |
| 287 |
use deeply nested recursion. There is a discussion about stack sizes in the |
successfully used, it is not relevant. Equally, it does not apply to |
| 288 |
pcrestack man page. |
pcre_dfa_exec(), which does not use deeply nested recursion. There is a |
| 289 |
|
discussion about stack sizes in the pcrestack man page. |
| 290 |
|
|
| 291 |
. For speed, PCRE uses four tables for manipulating and identifying characters |
. For speed, PCRE uses four tables for manipulating and identifying characters |
| 292 |
whose code point values are less than 256. By default, it uses a set of |
whose code point values are less than 256. By default, it uses a set of |
| 304 |
|
|
| 305 |
--enable-ebcdic |
--enable-ebcdic |
| 306 |
|
|
| 307 |
This automatically implies --enable-rebuild-chartables (see above). However, |
This automatically implies --enable-rebuild-chartables (see above). However, |
| 308 |
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 |
| 309 |
both EBCDIC and UTF-8. |
both EBCDIC and UTF-8/16. |
| 310 |
|
|
| 311 |
. It is possible to compile pcregrep to use libz and/or libbz2, in order to |
. The pcregrep program currently supports only 8-bit data files, and so |
| 312 |
read .gz and .bz2 files (respectively), by specifying one or both of |
requires the 8-bit PCRE library. It is possible to compile pcregrep to use |
| 313 |
|
libz and/or libbz2, in order to read .gz and .bz2 files (respectively), by |
| 314 |
|
specifying one or both of |
| 315 |
|
|
| 316 |
--enable-pcregrep-libz |
--enable-pcregrep-libz |
| 317 |
--enable-pcregrep-libbz2 |
--enable-pcregrep-libbz2 |
| 318 |
|
|
| 319 |
Of course, the relevant libraries must be installed on your system. |
Of course, the relevant libraries must be installed on your system. |
| 320 |
|
|
| 321 |
|
. The default size of internal buffer used by pcregrep can be set by, for |
| 322 |
|
example: |
| 323 |
|
|
| 324 |
|
--with-pcregrep-bufsize=50K |
| 325 |
|
|
| 326 |
|
The default value is 20K. |
| 327 |
|
|
| 328 |
. 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 |
| 329 |
library, by specifying |
or libedit libraries, by specifying, respectively, |
| 330 |
|
|
| 331 |
--enable-pcretest-libreadline |
--enable-pcretest-libreadline or --enable-pcretest-libedit |
| 332 |
|
|
| 333 |
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 |
| 334 |
the readline() function. This provides line-editing and history facilities. |
the readline() function. This provides line-editing and history facilities. |
| 335 |
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 |
| 336 |
pcretest linked in this way, there may be licensing issues. |
pcretest linked in this way, there may be licensing issues. These can be |
| 337 |
|
avoided by linking with libedit (which has a BSD licence) instead. |
| 338 |
|
|
| 339 |
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 |
| 340 |
build. In many operating environments with a sytem-installed readline |
build. In many operating environments with a sytem-installed readline |
| 341 |
library this is sufficient. However, in some environments (e.g. if an |
library this is sufficient. However, in some environments (e.g. if an |
| 342 |
unmodified distribution version of readline is in use), it may be necessary |
unmodified distribution version of readline is in use), it may be necessary |
| 343 |
to specify something like LIBS="-lncurses" as well. This is because, to quote |
to specify something like LIBS="-lncurses" as well. This is because, to quote |
| 344 |
the readline INSTALL, "Readline uses the termcap functions, but does not link |
the readline INSTALL, "Readline uses the termcap functions, but does not link |
| 345 |
with the termcap or curses library itself, allowing applications which link |
with the termcap or curses library itself, allowing applications which link |
| 346 |
with readline the to choose an appropriate library." If you get error |
with readline the to choose an appropriate library." If you get error |
| 347 |
messages about missing functions tgetstr, tgetent, tputs, tgetflag, or tgoto, |
messages about missing functions tgetstr, tgetent, tputs, tgetflag, or tgoto, |
| 348 |
this is the problem, and linking with the ncurses library should fix it. |
this is the problem, and linking with the ncurses library should fix it. |
| 349 |
|
|
| 350 |
The "configure" script builds the following files for the basic C library: |
The "configure" script builds the following files for the basic C library: |
| 351 |
|
|
| 352 |
. Makefile is the makefile that builds the library |
. Makefile the makefile that builds the library |
| 353 |
. config.h contains build-time configuration options for the library |
. config.h build-time configuration options for the library |
| 354 |
. pcre.h is the public PCRE header file |
. pcre.h the public PCRE header file |
| 355 |
. pcre-config is a script that shows the settings of "configure" options |
. pcre-config script that shows the building settings such as CFLAGS |
| 356 |
. libpcre.pc is data for the pkg-config command |
that were set for "configure" |
| 357 |
. libtool is a script that builds shared and/or static libraries |
. libpcre.pc ) data for the pkg-config command |
| 358 |
. RunTest is a script for running tests on the basic C library |
. libpcre16.pc ) |
| 359 |
. RunGrepTest is a script for running tests on the pcregrep command |
. libpcreposix.pc ) |
| 360 |
|
. libtool script that builds shared and/or static libraries |
| 361 |
Versions of config.h and pcre.h are distributed in the PCRE tarballs under |
. RunTest script for running tests on the basic C library |
| 362 |
the names config.h.generic and pcre.h.generic. These are provided for the |
. RunGrepTest script for running tests on the pcregrep command |
| 363 |
benefit of those who have to built PCRE without the benefit of "configure". If |
|
| 364 |
you use "configure", the .generic versions are not used. |
Versions of config.h and pcre.h are distributed in the PCRE tarballs under the |
| 365 |
|
names config.h.generic and pcre.h.generic. These are provided for those who |
| 366 |
If a C++ compiler is found, the following files are also built: |
have to built PCRE without using "configure" or CMake. If you use "configure" |
| 367 |
|
or CMake, the .generic versions are not used. |
| 368 |
. libpcrecpp.pc is data for the pkg-config command |
|
| 369 |
. pcrecpparg.h is a header file for programs that call PCRE via the C++ wrapper |
When building the 8-bit library, if a C++ compiler is found, the following |
| 370 |
. pcre_stringpiece.h is the header for the C++ "stringpiece" functions |
files are also built: |
| 371 |
|
|
| 372 |
|
. libpcrecpp.pc data for the pkg-config command |
| 373 |
|
. pcrecpparg.h header file for calling PCRE via the C++ wrapper |
| 374 |
|
. pcre_stringpiece.h header for the C++ "stringpiece" functions |
| 375 |
|
|
| 376 |
The "configure" script also creates config.status, which is an executable |
The "configure" script also creates config.status, which is an executable |
| 377 |
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 |
| 378 |
contains compiler output from tests that "configure" runs. |
contains compiler output from tests that "configure" runs. |
| 379 |
|
|
| 380 |
Once "configure" has run, you can run "make". It builds two libraries, called |
Once "configure" has run, you can run "make". This builds either or both of the |
| 381 |
libpcre and libpcreposix, a test program called pcretest, and the pcregrep |
libraries libpcre and libpcre16, and a test program called pcretest. If you |
| 382 |
command. If a C++ compiler was found on your system, "make" also builds the C++ |
enabled JIT support with --enable-jit, a test program called pcre_jit_test is |
| 383 |
wrapper library, which is called libpcrecpp, and some test programs called |
built as well. |
| 384 |
pcrecpp_unittest, pcre_scanner_unittest, and pcre_stringpiece_unittest. |
|
| 385 |
Building the C++ wrapper can be disabled by adding --disable-cpp to the |
If the 8-bit library is built, libpcreposix and the pcregrep command are also |
| 386 |
"configure" command. |
built, and if a C++ compiler was found on your system, and you did not disable |
| 387 |
|
it with --disable-cpp, "make" builds the C++ wrapper library, which is called |
| 388 |
|
libpcrecpp, as well as some test programs called pcrecpp_unittest, |
| 389 |
|
pcre_scanner_unittest, and pcre_stringpiece_unittest. |
| 390 |
|
|
| 391 |
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 |
| 392 |
tests are given below in a separate section of this document. |
tests are given below in a separate section of this document. |
| 397 |
|
|
| 398 |
Commands (bin): |
Commands (bin): |
| 399 |
pcretest |
pcretest |
| 400 |
pcregrep |
pcregrep (if 8-bit support is enabled) |
| 401 |
pcre-config |
pcre-config |
| 402 |
|
|
| 403 |
Libraries (lib): |
Libraries (lib): |
| 404 |
libpcre |
libpcre16 (if 16-bit support is enabled) |
| 405 |
libpcreposix |
libpcre (if 8-bit support is enabled) |
| 406 |
libpcrecpp (if C++ support is enabled) |
libpcreposix (if 8-bit support is enabled) |
| 407 |
|
libpcrecpp (if 8-bit and C++ support is enabled) |
| 408 |
|
|
| 409 |
Configuration information (lib/pkgconfig): |
Configuration information (lib/pkgconfig): |
| 410 |
|
libpcre16.pc |
| 411 |
libpcre.pc |
libpcre.pc |
| 412 |
|
libpcreposix.pc |
| 413 |
libpcrecpp.pc (if C++ support is enabled) |
libpcrecpp.pc (if C++ support is enabled) |
| 414 |
|
|
| 415 |
Header files (include): |
Header files (include): |
| 423 |
Man pages (share/man/man{1,3}): |
Man pages (share/man/man{1,3}): |
| 424 |
pcregrep.1 |
pcregrep.1 |
| 425 |
pcretest.1 |
pcretest.1 |
| 426 |
|
pcre-config.1 |
| 427 |
pcre.3 |
pcre.3 |
| 428 |
pcre*.3 (lots more pages, all starting "pcre") |
pcre*.3 (lots more pages, all starting "pcre") |
| 429 |
|
|
| 438 |
LICENCE |
LICENCE |
| 439 |
NEWS |
NEWS |
| 440 |
README |
README |
| 441 |
pcre.txt (a concatenation of the man(3) pages) |
pcre.txt (a concatenation of the man(3) pages) |
| 442 |
pcretest.txt the pcretest man page |
pcretest.txt the pcretest man page |
| 443 |
pcregrep.txt the pcregrep man page |
pcregrep.txt the pcregrep man page |
| 444 |
|
pcre-config.txt the pcre-config man page |
| 445 |
|
|
| 446 |
If you want to remove PCRE from your system, you can run "make uninstall". |
If you want to remove PCRE from your system, you can run "make uninstall". |
| 447 |
This removes all the files that "make install" installed. However, it does not |
This removes all the files that "make install" installed. However, it does not |
| 538 |
CXXLDFLAGS="-lstd_v2 -lCsup_v2" |
CXXLDFLAGS="-lstd_v2 -lCsup_v2" |
| 539 |
|
|
| 540 |
|
|
| 541 |
|
Using Sun's compilers for Solaris |
| 542 |
|
--------------------------------- |
| 543 |
|
|
| 544 |
|
A user reports that the following configurations work on Solaris 9 sparcv9 and |
| 545 |
|
Solaris 9 x86 (32-bit): |
| 546 |
|
|
| 547 |
|
Solaris 9 sparcv9: ./configure --disable-cpp CC=/bin/cc CFLAGS="-m64 -g" |
| 548 |
|
Solaris 9 x86: ./configure --disable-cpp CC=/bin/cc CFLAGS="-g" |
| 549 |
|
|
| 550 |
|
|
| 551 |
|
Using PCRE from MySQL |
| 552 |
|
--------------------- |
| 553 |
|
|
| 554 |
|
On systems where both PCRE and MySQL are installed, it is possible to make use |
| 555 |
|
of PCRE from within MySQL, as an alternative to the built-in pattern matching. |
| 556 |
|
There is a web page that tells you how to do this: |
| 557 |
|
|
| 558 |
|
http://www.mysqludf.org/lib_mysqludf_preg/index.php |
| 559 |
|
|
| 560 |
|
|
| 561 |
Making new tarballs |
Making new tarballs |
| 562 |
------------------- |
------------------- |
| 563 |
|
|
| 577 |
created by the configuring process. There is also a script called RunGrepTest |
created by the configuring process. There is also a script called RunGrepTest |
| 578 |
that tests the options of the pcregrep command. If the C++ wrapper library is |
that tests the options of the pcregrep command. If the C++ wrapper library is |
| 579 |
built, three test programs called pcrecpp_unittest, pcre_scanner_unittest, and |
built, three test programs called pcrecpp_unittest, pcre_scanner_unittest, and |
| 580 |
pcre_stringpiece_unittest are also built. |
pcre_stringpiece_unittest are also built. When JIT support is enabled, another |
| 581 |
|
test program called pcre_jit_test is built. |
| 582 |
|
|
| 583 |
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 |
| 584 |
"make test". For other systems, see the instructions in NON-UNIX-USE. |
"make test". For other systems, see the instructions in NON-UNIX-USE. |
| 585 |
|
|
| 586 |
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 |
| 587 |
own man page) on each of the testinput files in the testdata directory in |
own man page) on each of the relevant testinput files in the testdata |
| 588 |
turn, and compares the output with the contents of the corresponding testoutput |
directory, and compares the output with the contents of the corresponding |
| 589 |
files. A file called testtry is used to hold the main output from pcretest |
testoutput files. Some tests are relevant only when certain build-time options |
| 590 |
(testsavedregex is also used as a working file). To run pcretest on just one of |
were selected. For example, the tests for UTF-8/16 support are run only if |
| 591 |
the test files, give its number as an argument to RunTest, for example: |
--enable-utf was used. RunTest outputs a comment when it skips a test. |
| 592 |
|
|
| 593 |
RunTest 2 |
Many of the tests that are not skipped are run up to three times. The second |
| 594 |
|
run forces pcre_study() to be called for all patterns except for a few in some |
| 595 |
The first test file can also be fed directly into the perltest.pl script to |
tests that are marked "never study" (see the pcretest program for how this is |
| 596 |
check that Perl gives the same results. The only difference you should see is |
done). If JIT support is available, the non-DFA tests are run a third time, |
| 597 |
in the first few lines, where the Perl version is given instead of the PCRE |
this time with a forced pcre_study() with the PCRE_STUDY_JIT_COMPILE option. |
| 598 |
version. |
|
| 599 |
|
When both 8-bit and 16-bit support is enabled, the entire set of tests is run |
| 600 |
|
twice, once for each library. If you want to run just one set of tests, call |
| 601 |
|
RunTest with either the -8 or -16 option. |
| 602 |
|
|
| 603 |
|
RunTest uses a file called testtry to hold the main output from pcretest. |
| 604 |
|
Other files whose names begin with "test" are used as working files in some |
| 605 |
|
tests. To run pcretest on just one or more specific test files, give their |
| 606 |
|
numbers as arguments to RunTest, for example: |
| 607 |
|
|
| 608 |
|
RunTest 2 7 11 |
| 609 |
|
|
| 610 |
|
The first test file can be fed directly into the perltest.pl script to check |
| 611 |
|
that Perl gives the same results. The only difference you should see is in the |
| 612 |
|
first few lines, where the Perl version is given instead of the PCRE version. |
| 613 |
|
|
| 614 |
The second set of tests check pcre_fullinfo(), pcre_info(), pcre_study(), |
The second set of tests check pcre_fullinfo(), pcre_study(), |
| 615 |
pcre_copy_substring(), pcre_get_substring(), pcre_get_substring_list(), error |
pcre_copy_substring(), pcre_get_substring(), pcre_get_substring_list(), error |
| 616 |
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 |
| 617 |
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 |
| 646 |
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 |
| 647 |
document entitled NON-UNIX-USE.] |
document entitled NON-UNIX-USE.] |
| 648 |
|
|
| 649 |
The fourth test checks the UTF-8 support. It is not run automatically unless |
The fourth and fifth tests check the UTF-8/16 support and error handling and |
| 650 |
PCRE is built with UTF-8 support. To do this you must set --enable-utf8 when |
internal UTF features of PCRE that are not relevant to Perl, respectively. The |
| 651 |
running "configure". This file can be also fed directly to the perltest script, |
sixth and seventh tests do the same for Unicode character properties support. |
| 652 |
provided you are running Perl 5.8 or higher. (For Perl 5.6, a small patch, |
|
| 653 |
commented in the script, can be be used.) |
The eighth, ninth, and tenth tests check the pcre_dfa_exec() alternative |
| 654 |
|
matching function, in non-UTF-8/16 mode, UTF-8/16 mode, and UTF-8/16 mode with |
| 655 |
The fifth test checks error handling with UTF-8 encoding, and internal UTF-8 |
Unicode property support, respectively. |
| 656 |
features of PCRE that are not relevant to Perl. |
|
| 657 |
|
The eleventh test checks some internal offsets and code size features; it is |
| 658 |
The sixth test checks the support for Unicode character properties. It it not |
run only when the default "link size" of 2 is set (in other cases the sizes |
| 659 |
run automatically unless PCRE is built with Unicode property support. To to |
change) and when Unicode property support is enabled. |
| 660 |
this you must set --enable-unicode-properties when running "configure". |
|
| 661 |
|
The twelfth test is run only when JIT support is available, and the thirteenth |
| 662 |
The seventh, eighth, and ninth tests check the pcre_dfa_exec() alternative |
test is run only when JIT support is not available. They test some JIT-specific |
| 663 |
matching function, in non-UTF-8 mode, UTF-8 mode, and UTF-8 mode with Unicode |
features such as information output from pcretest about JIT compilation. |
| 664 |
property support, respectively. The eighth and ninth tests are not run |
|
| 665 |
automatically unless PCRE is build with the relevant support. |
The fourteenth, fifteenth, and sixteenth tests are run only in 8-bit mode, and |
| 666 |
|
the seventeenth, eighteenth, and nineteenth tests are run only in 16-bit mode. |
| 667 |
|
These are tests that generate different output in the two modes. They are for |
| 668 |
|
general cases, UTF-8/16 support, and Unicode property support, respectively. |
| 669 |
|
|
| 670 |
|
The twentieth test is run only in 16-bit mode. It tests some specific 16-bit |
| 671 |
|
features of the DFA matching engine. |
| 672 |
|
|
| 673 |
|
The twenty-first and twenty-second tests are run only in 16-bit mode, when the |
| 674 |
|
link size is set to 2. They test reloading pre-compiled patterns. |
| 675 |
|
|
| 676 |
|
|
| 677 |
Character tables |
Character tables |
| 731 |
File manifest |
File manifest |
| 732 |
------------- |
------------- |
| 733 |
|
|
| 734 |
The distribution should contain the following files: |
The distribution should contain the files listed below. Where a file name is |
| 735 |
|
given as pcre[16]_xxx it means that there are two files, one with the name |
| 736 |
|
pcre_xxx and the other with the name pcre16_xxx. |
| 737 |
|
|
| 738 |
(A) Source files of the PCRE library functions and their headers: |
(A) Source files of the PCRE library functions and their headers: |
| 739 |
|
|
| 742 |
|
|
| 743 |
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 |
| 744 |
coding; used, unless --enable-rebuild-chartables is |
coding; used, unless --enable-rebuild-chartables is |
| 745 |
specified, by copying to pcre_chartables.c |
specified, by copying to pcre[16]_chartables.c |
| 746 |
|
|
| 747 |
pcreposix.c ) |
pcreposix.c ) |
| 748 |
pcre_compile.c ) |
pcre[16]_byte_order.c ) |
| 749 |
pcre_config.c ) |
pcre[16]_compile.c ) |
| 750 |
pcre_dfa_exec.c ) |
pcre[16]_config.c ) |
| 751 |
pcre_exec.c ) |
pcre[16]_dfa_exec.c ) |
| 752 |
pcre_fullinfo.c ) |
pcre[16]_exec.c ) |
| 753 |
pcre_get.c ) sources for the functions in the library, |
pcre[16]_fullinfo.c ) |
| 754 |
pcre_globals.c ) and some internal functions that they use |
pcre[16]_get.c ) sources for the functions in the library, |
| 755 |
pcre_info.c ) |
pcre[16]_globals.c ) and some internal functions that they use |
| 756 |
pcre_maketables.c ) |
pcre[16]_jit_compile.c ) |
| 757 |
pcre_newline.c ) |
pcre[16]_maketables.c ) |
| 758 |
|
pcre[16]_newline.c ) |
| 759 |
|
pcre[16]_refcount.c ) |
| 760 |
|
pcre[16]_string_utils.c ) |
| 761 |
|
pcre[16]_study.c ) |
| 762 |
|
pcre[16]_tables.c ) |
| 763 |
|
pcre[16]_ucd.c ) |
| 764 |
|
pcre[16]_version.c ) |
| 765 |
|
pcre[16]_xclass.c ) |
| 766 |
pcre_ord2utf8.c ) |
pcre_ord2utf8.c ) |
|
pcre_refcount.c ) |
|
|
pcre_study.c ) |
|
|
pcre_tables.c ) |
|
|
pcre_try_flipped.c ) |
|
|
pcre_ucd.c ) |
|
| 767 |
pcre_valid_utf8.c ) |
pcre_valid_utf8.c ) |
| 768 |
pcre_version.c ) |
pcre16_ord2utf16.c ) |
| 769 |
pcre_xclass.c ) |
pcre16_utf16_utils.c ) |
| 770 |
pcre_printint.src ) debugging function that is #included in pcretest, |
pcre16_valid_utf16.c ) |
| 771 |
|
|
| 772 |
|
pcre[16]_printint.c ) debugging function that is used by pcretest, |
| 773 |
) and can also be #included in pcre_compile() |
) and can also be #included in pcre_compile() |
| 774 |
|
|
| 775 |
pcre.h.in template for pcre.h when built by "configure" |
pcre.h.in template for pcre.h when built by "configure" |
| 776 |
pcreposix.h header for the external POSIX wrapper API |
pcreposix.h header for the external POSIX wrapper API |
| 777 |
pcre_internal.h header for internal use |
pcre_internal.h header for internal use |
| 778 |
|
sljit/* 16 files that make up the JIT compiler |
| 779 |
ucp.h header for Unicode property handling |
ucp.h header for Unicode property handling |
| 780 |
|
|
| 781 |
config.h.in template for config.h, which is built by "configure" |
config.h.in template for config.h, which is built by "configure" |
| 825 |
) "configure" and config.h |
) "configure" and config.h |
| 826 |
depcomp ) script to find program dependencies, generated by |
depcomp ) script to find program dependencies, generated by |
| 827 |
) automake |
) automake |
| 828 |
doc/*.3 man page sources for the PCRE functions |
doc/*.3 man page sources for PCRE |
| 829 |
doc/*.1 man page sources for pcregrep and pcretest |
doc/*.1 man page sources for pcregrep and pcretest |
| 830 |
doc/index.html.src the base HTML page |
doc/index.html.src the base HTML page |
| 831 |
doc/html/* HTML documentation |
doc/html/* HTML documentation |
| 833 |
doc/pcretest.txt plain text documentation of test program |
doc/pcretest.txt plain text documentation of test program |
| 834 |
doc/perltest.txt plain text documentation of Perl test program |
doc/perltest.txt plain text documentation of Perl test program |
| 835 |
install-sh a shell script for installing files |
install-sh a shell script for installing files |
| 836 |
|
libpcre16.pc.in template for libpcre16.pc for pkg-config |
| 837 |
libpcre.pc.in template for libpcre.pc for pkg-config |
libpcre.pc.in template for libpcre.pc for pkg-config |
| 838 |
|
libpcreposix.pc.in template for libpcreposix.pc for pkg-config |
| 839 |
libpcrecpp.pc.in template for libpcrecpp.pc for pkg-config |
libpcrecpp.pc.in template for libpcrecpp.pc for pkg-config |
| 840 |
ltmain.sh file used to build a libtool script |
ltmain.sh file used to build a libtool script |
| 841 |
missing ) common stub for a few missing GNU programs while |
missing ) common stub for a few missing GNU programs while |
| 843 |
mkinstalldirs script for making install directories |
mkinstalldirs script for making install directories |
| 844 |
perltest.pl Perl test program |
perltest.pl Perl test program |
| 845 |
pcre-config.in source of script which retains PCRE information |
pcre-config.in source of script which retains PCRE information |
| 846 |
|
pcre_jit_test.c test program for the JIT compiler |
| 847 |
pcrecpp_unittest.cc ) |
pcrecpp_unittest.cc ) |
| 848 |
pcre_scanner_unittest.cc ) test programs for the C++ wrapper |
pcre_scanner_unittest.cc ) test programs for the C++ wrapper |
| 849 |
pcre_stringpiece_unittest.cc ) |
pcre_stringpiece_unittest.cc ) |
| 850 |
testdata/testinput* test data for main library tests |
testdata/testinput* test data for main library tests |
| 851 |
testdata/testoutput* expected test results |
testdata/testoutput* expected test results |
| 852 |
testdata/grep* input and output for pcregrep tests |
testdata/grep* input and output for pcregrep tests |
| 853 |
|
testdata/* other supporting test files |
| 854 |
|
|
| 855 |
(D) Auxiliary files for cmake support |
(D) Auxiliary files for cmake support |
| 856 |
|
|
| 857 |
cmake/COPYING-CMAKE-SCRIPTS |
cmake/COPYING-CMAKE-SCRIPTS |
| 858 |
cmake/FindPackageHandleStandardArgs.cmake |
cmake/FindPackageHandleStandardArgs.cmake |
| 859 |
|
cmake/FindEditline.cmake |
| 860 |
cmake/FindReadline.cmake |
cmake/FindReadline.cmake |
| 861 |
CMakeLists.txt |
CMakeLists.txt |
| 862 |
config-cmake.h.in |
config-cmake.h.in |
| 882 |
Philip Hazel |
Philip Hazel |
| 883 |
Email local part: ph10 |
Email local part: ph10 |
| 884 |
Email domain: cam.ac.uk |
Email domain: cam.ac.uk |
| 885 |
Last updated: 17 March 2009 |
Last updated: 26 February 2012 |