version 1.1.1.1, 2012/02/21 23:05:51
|
version 1.1.1.4, 2013/07/22 08:25:55
|
Line 18 The contents of this README file are:
|
Line 18 The contents of this README file are:
|
The PCRE APIs |
The PCRE APIs |
Documentation for PCRE |
Documentation for PCRE |
Contributions by users of PCRE |
Contributions by users of PCRE |
Building PCRE on non-Unix systems | Building PCRE on non-Unix-like systems |
Building PCRE on Unix-like systems | Building PCRE without using autotools |
Retrieving configuration information on Unix-like systems | Building PCRE using autotools |
Shared libraries on Unix-like systems | Retrieving configuration information |
Cross-compiling on Unix-like systems | Shared libraries |
| Cross-compiling using autotools |
Using HP's ANSI C++ compiler (aCC) |
Using HP's ANSI C++ compiler (aCC) |
|
Compiling in Tru64 using native compilers |
|
Using Sun's compilers for Solaris |
Using PCRE from MySQL |
Using PCRE from MySQL |
Making new tarballs |
Making new tarballs |
Testing PCRE |
Testing PCRE |
Line 34 The contents of this README file are:
|
Line 37 The contents of this README file are:
|
The PCRE APIs |
The PCRE APIs |
------------- |
------------- |
|
|
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 |
set of C++ wrapper functions (see the pcrecpp man page for details), courtesy | functions, one for the 8-bit library, which processes strings of bytes, one for |
of Google Inc. | the 16-bit library, which processes strings of 16-bit values, and one for the |
| 32-bit library, which processes strings of 32-bit values. The distribution also |
| includes a set of C++ wrapper functions (see the pcrecpp man page for details), |
| courtesy of Google Inc., which can be used to call the 8-bit PCRE library from |
| C++. |
|
|
In addition, there is a set of C wrapper functions that are based on the POSIX | In addition, there is a set of C wrapper functions (again, just for the 8-bit |
regular expression API (see the pcreposix man page). These end up in the | library) that are based on the POSIX regular expression API (see the pcreposix |
library called libpcreposix. Note that this just provides a POSIX calling | man page). These end up in the library called libpcreposix. Note that this just |
interface to PCRE; the regular expressions themselves still follow Perl syntax | provides a POSIX calling interface to PCRE; the regular expressions themselves |
and semantics. The POSIX API is restricted, and does not give full access to | still follow Perl syntax and semantics. The POSIX API is restricted, and does |
all of PCRE's facilities. | not give full access to all of PCRE's facilities. |
|
|
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 |
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 |
Line 106 Windows (I myself do not use Windows). Nowadays there
|
Line 113 Windows (I myself do not use Windows). Nowadays there
|
in the standard distribution, so these contibutions have been archived. |
in the standard distribution, so these contibutions have been archived. |
|
|
|
|
Building PCRE on non-Unix systems | Building PCRE on non-Unix-like systems |
--------------------------------- | -------------------------------------- |
|
|
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 |
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 |
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 |
configured in many platform environments using the GUI facility provided by | many Unix-like systems. |
CMake's cmake-gui command. This creates Makefiles, solution files, etc. | |
|
|
|
PCRE can also be configured using the GUI facility provided by CMake's |
|
cmake-gui command. This creates Makefiles, solution files, etc. The file |
|
NON-AUTOTOOLS-BUILD has information about CMake. |
|
|
PCRE has been compiled on many different operating systems. It should be |
PCRE has been compiled on many different operating systems. It should be |
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 |
library, because it uses only Standard C functions. |
library, because it uses only Standard C functions. |
|
|
|
|
Building PCRE on Unix-like systems | Building PCRE without using autotools |
---------------------------------- | ------------------------------------- |
|
|
|
The use of autotools (in particular, libtool) is problematic in some |
|
environments, even some that are Unix or Unix-like. See the NON-AUTOTOOLS-BUILD |
|
file for ways of building PCRE without using autotools. |
|
|
|
|
|
Building PCRE using autotools |
|
----------------------------- |
|
|
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 |
in the section entitled "Using HP's ANSI C++ compiler (aCC)" below. |
in the section entitled "Using HP's ANSI C++ compiler (aCC)" below. |
|
|
The following instructions assume the use of the widely used "configure, make, | The following instructions assume the use of the widely used "configure; make; |
make install" process. There is also support for CMake in the PCRE | make install" (autotools) process. |
distribution; there are some comments about using CMake in the NON-UNIX-USE | |
file, though it can also be used in Unix-like systems. | |
|
|
To build PCRE on a Unix-like system, first run the "configure" command from the | To build PCRE on system that supports autotools, first run the "configure" |
PCRE distribution directory, with your current directory set to the directory | command from the PCRE distribution directory, with your current directory set |
where you want the files to be created. This command is a standard GNU | to the directory where you want the files to be created. This command is a |
"autoconf" configuration script, for which generic instructions are supplied in | standard GNU "autoconf" configuration script, for which generic instructions |
the file INSTALL. | are supplied in the file INSTALL. |
|
|
Most commonly, people build PCRE within its own distribution directory, and in |
Most commonly, people build PCRE within its own distribution directory, and in |
this case, on many systems, just running "./configure" is sufficient. However, |
this case, on many systems, just running "./configure" is sufficient. However, |
Line 143 the usual methods of changing standard defaults are av
|
Line 159 the usual methods of changing standard defaults are av
|
|
|
CFLAGS='-O2 -Wall' ./configure --prefix=/opt/local |
CFLAGS='-O2 -Wall' ./configure --prefix=/opt/local |
|
|
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 |
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 |
instead of the default /usr/local. | under /opt/local instead of the default /usr/local. |
|
|
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 |
directory as current. For example, suppose you have unpacked the PCRE source |
directory as current. For example, suppose you have unpacked the PCRE source |
Line 169 library. They are also documented in the pcrebuild man
|
Line 185 library. They are also documented in the pcrebuild man
|
|
|
(See also "Shared libraries on Unix-like systems" below.) |
(See also "Shared libraries on Unix-like systems" below.) |
|
|
. 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 |
--disable-cpp to the "configure" command. Otherwise, when "configure" is run, | the "configure" command, the 16-bit library is also built. If you add |
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. |
it will try to build the C++ wrapper. | If you want only the 16-bit or 32-bit library, use --disable-pcre8 to disable |
| building the 8-bit library. |
|
|
|
. If you are building the 8-bit library and want to suppress the building of |
|
the C++ wrapper library, you can add --disable-cpp to the "configure" |
|
command. Otherwise, when "configure" is run without --disable-pcre8, it will |
|
try to find a C++ compiler and C++ header files, and if it succeeds, it will |
|
try to build the C++ wrapper. |
|
|
. 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 |
large performance improvements on certain platforms, add --enable-jit to the |
large performance improvements on certain platforms, add --enable-jit to the |
"configure" command. This support is available only for certain hardware |
"configure" command. This support is available only for certain hardware |
Line 184 library. They are also documented in the pcrebuild man
|
Line 207 library. They are also documented in the pcrebuild man
|
you add --disable-pcregrep-jit to the "configure" command. |
you add --disable-pcregrep-jit to the "configure" command. |
|
|
. 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 |
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, |
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 |
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 |
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 |
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 |
--enable-ebcdic at the same time. | enabled by an option at run time. When PCRE is compiled with this option, its |
| input can only either be ASCII or UTF-8/16/32, even when running on EBCDIC |
| platforms. It is not possible to use both --enable-utf and --enable-ebcdic at |
| the same time. |
|
|
. If, in addition to support for UTF-8 character strings, you want to include | . There are no separate options for enabling UTF-8, UTF-16 and UTF-32 |
support for the \P, \p, and \X sequences that recognize Unicode character | independently because that would allow ridiculous settings such as requesting |
properties, you must add --enable-unicode-properties to the "configure" | UTF-16 support while building only the 8-bit library. However, the option |
command. This adds about 30K to the size of the library (in the form of a | --enable-utf8 is retained for backwards compatibility with earlier releases |
property table); only the basic two-letter properties such as Lu are | that did not support 16-bit or 32-bit character strings. It is synonymous with |
supported. | --enable-utf. It is not possible to configure one library with UTF support |
| and the other without in the same configuration. |
|
|
|
. If, in addition to support for UTF-8/16/32 character strings, you want to |
|
include support for the \P, \p, and \X sequences that recognize Unicode |
|
character properties, you must add --enable-unicode-properties to the |
|
"configure" command. This adds about 30K to the size of the library (in the |
|
form of a property table); only the basic two-letter properties such as Lu |
|
are supported. |
|
|
. 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 |
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 |
end of a line. Whatever you specify at build time is the default; the caller |
end of a line. Whatever you specify at build time is the default; the caller |
Line 249 library. They are also documented in the pcrebuild man
|
Line 283 library. They are also documented in the pcrebuild man
|
sizes in the pcrestack man page. |
sizes in the pcrestack man page. |
|
|
. The default maximum compiled pattern size is around 64K. You can increase |
. The default maximum compiled pattern size is around 64K. You can increase |
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 |
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 |
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 |
performance. | the same as --with-link-size=4, which (in both libraries) uses four-byte |
| offsets. Increasing the internal link size reduces performance. In the 32-bit |
| library, the only supported link size is 4. |
|
|
. 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 |
pcre_exec() does not call itself recursively. Instead, it uses memory blocks |
pcre_exec() does not call itself recursively. Instead, it uses memory blocks |
Line 281 library. They are also documented in the pcrebuild man
|
Line 317 library. They are also documented in the pcrebuild man
|
pcre_chartables.c.dist. See "Character tables" below for further information. |
pcre_chartables.c.dist. See "Character tables" below for further information. |
|
|
. 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 |
character code (as opposed to ASCII) by specifying | character code (as opposed to ASCII/Unicode) by specifying |
|
|
--enable-ebcdic |
--enable-ebcdic |
|
|
This automatically implies --enable-rebuild-chartables (see above). However, |
This automatically implies --enable-rebuild-chartables (see above). However, |
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 |
both EBCDIC and UTF-8. | both EBCDIC and UTF-8/16/32. There is a second option, --enable-ebcdic-nl25, |
| which specifies that the code value for the EBCDIC NL character is 0x25 |
| instead of the default 0x15. |
|
|
. It is possible to compile pcregrep to use libz and/or libbz2, in order to | . In environments where valgrind is installed, if you specify |
read .gz and .bz2 files (respectively), by specifying one or both of | |
|
|
|
--enable-valgrind |
|
|
|
PCRE will use valgrind annotations to mark certain memory regions as |
|
unaddressable. This allows it to detect invalid memory accesses, and is |
|
mostly useful for debugging PCRE itself. |
|
|
|
. In environments where the gcc compiler is used and lcov version 1.6 or above |
|
is installed, if you specify |
|
|
|
--enable-coverage |
|
|
|
the build process implements a code coverage report for the test suite. The |
|
report is generated by running "make coverage". If ccache is installed on |
|
your system, it must be disabled when building PCRE for coverage reporting. |
|
You can do this by setting the environment variable CCACHE_DISABLE=1 before |
|
running "make" to build PCRE. |
|
|
|
. The pcregrep program currently supports only 8-bit data files, and so |
|
requires the 8-bit PCRE library. It is possible to compile pcregrep to use |
|
libz and/or libbz2, in order to read .gz and .bz2 files (respectively), by |
|
specifying one or both of |
|
|
--enable-pcregrep-libz |
--enable-pcregrep-libz |
--enable-pcregrep-libbz2 |
--enable-pcregrep-libbz2 |
|
|
Line 305 library. They are also documented in the pcrebuild man
|
Line 364 library. They are also documented in the pcrebuild man
|
The default value is 20K. |
The default value is 20K. |
|
|
. 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 |
library, by specifying | or libedit libraries, by specifying, respectively, |
|
|
--enable-pcretest-libreadline | --enable-pcretest-libreadline or --enable-pcretest-libedit |
|
|
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 |
the readline() function. This provides line-editing and history facilities. |
the readline() function. This provides line-editing and history facilities. |
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 |
pcretest linked in this way, there may be licensing issues. | pcretest linked in this way, there may be licensing issues. These can be |
| avoided by linking with libedit (which has a BSD licence) instead. |
|
|
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 |
build. In many operating environments with a sytem-installed readline |
build. In many operating environments with a sytem-installed readline |
library this is sufficient. However, in some environments (e.g. if an |
library this is sufficient. However, in some environments (e.g. if an |
unmodified distribution version of readline is in use), it may be necessary |
unmodified distribution version of readline is in use), it may be necessary |
Line 333 The "configure" script builds the following files for
|
Line 393 The "configure" script builds the following files for
|
. pcre-config script that shows the building settings such as CFLAGS |
. pcre-config script that shows the building settings such as CFLAGS |
that were set for "configure" |
that were set for "configure" |
. libpcre.pc ) data for the pkg-config command |
. libpcre.pc ) data for the pkg-config command |
|
. libpcre16.pc ) |
|
. libpcre32.pc ) |
. libpcreposix.pc ) |
. libpcreposix.pc ) |
. 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 |
|
|
|
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 |
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 |
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" |
or CMake, the .generic versions are not used. |
or CMake, the .generic versions are not used. |
|
|
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 |
| files are also built: |
|
|
. libpcrecpp.pc data for the pkg-config command |
. libpcrecpp.pc data for the pkg-config command |
. pcrecpparg.h header file for calling PCRE via the C++ wrapper |
. pcrecpparg.h header file for calling PCRE via the C++ wrapper |
Line 353 The "configure" script also creates config.status, whi
|
Line 414 The "configure" script also creates config.status, whi
|
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 |
contains compiler output from tests that "configure" runs. |
contains compiler output from tests that "configure" runs. |
|
|
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 |
libpcre and libpcreposix, a test program called pcretest, and the pcregrep | libpcre, libpcre16 and/or libpcre32, and a test program called pcretest. If you |
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 |
with --disable-cpp, "make" also builds the C++ wrapper library, which is called | built as well. |
libpcrecpp, and some test programs called pcrecpp_unittest, | |
pcre_scanner_unittest, and pcre_stringpiece_unittest. If you enabled JIT | |
support with --enable-jit, a test program called pcre_jit_test is also built. | |
|
|
|
If the 8-bit library is built, libpcreposix and the pcregrep command are also |
|
built, and if a C++ compiler was found on your system, and you did not disable |
|
it with --disable-cpp, "make" builds the C++ wrapper library, which is called |
|
libpcrecpp, as well as some test programs called pcrecpp_unittest, |
|
pcre_scanner_unittest, and pcre_stringpiece_unittest. |
|
|
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 |
tests are given below in a separate section of this document. |
tests are given below in a separate section of this document. |
|
|
Line 370 system. The following are installed (file names are al
|
Line 434 system. The following are installed (file names are al
|
|
|
Commands (bin): |
Commands (bin): |
pcretest |
pcretest |
pcregrep | pcregrep (if 8-bit support is enabled) |
pcre-config |
pcre-config |
|
|
Libraries (lib): |
Libraries (lib): |
libpcre | libpcre16 (if 16-bit support is enabled) |
libpcreposix | libpcre32 (if 32-bit support is enabled) |
libpcrecpp (if C++ support is enabled) | libpcre (if 8-bit support is enabled) |
| libpcreposix (if 8-bit support is enabled) |
| libpcrecpp (if 8-bit and C++ support is enabled) |
|
|
Configuration information (lib/pkgconfig): |
Configuration information (lib/pkgconfig): |
|
libpcre16.pc |
|
libpcre32.pc |
libpcre.pc |
libpcre.pc |
libpcreposix.pc |
libpcreposix.pc |
libpcrecpp.pc (if C++ support is enabled) |
libpcrecpp.pc (if C++ support is enabled) |
Line 419 This removes all the files that "make install" install
|
Line 487 This removes all the files that "make install" install
|
remove any directories, because these are often shared with other programs. |
remove any directories, because these are often shared with other programs. |
|
|
|
|
Retrieving configuration information on Unix-like systems | Retrieving configuration information |
--------------------------------------------------------- | ------------------------------------ |
|
|
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 |
recall information about the PCRE configuration and installation. For example: |
recall information about the PCRE configuration and installation. For example: |
Line 445 The data is held in *.pc files that are installed in a
|
Line 513 The data is held in *.pc files that are installed in a
|
<prefix>/lib/pkgconfig. |
<prefix>/lib/pkgconfig. |
|
|
|
|
Shared libraries on Unix-like systems | Shared libraries |
------------------------------------- | ---------------- |
|
|
The default distribution builds PCRE as shared libraries and static libraries, |
The default distribution builds PCRE as shared libraries and static libraries, |
as long as the operating system supports shared libraries. Shared library |
as long as the operating system supports shared libraries. Shared library |
Line 471 Then run "make" in the usual way. Similarly, you can u
|
Line 539 Then run "make" in the usual way. Similarly, you can u
|
build only shared libraries. |
build only shared libraries. |
|
|
|
|
Cross-compiling on Unix-like systems | Cross-compiling using autotools |
------------------------------------ | ------------------------------- |
|
|
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 |
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 |
Line 509 running the "configure" script:
|
Line 577 running the "configure" script:
|
CXXLDFLAGS="-lstd_v2 -lCsup_v2" |
CXXLDFLAGS="-lstd_v2 -lCsup_v2" |
|
|
|
|
|
Compiling in Tru64 using native compilers |
|
----------------------------------------- |
|
|
|
The following error may occur when compiling with native compilers in the Tru64 |
|
operating system: |
|
|
|
CXX libpcrecpp_la-pcrecpp.lo |
|
cxx: Error: /usr/lib/cmplrs/cxx/V7.1-006/include/cxx/iosfwd, line 58: #error |
|
directive: "cannot include iosfwd -- define __USE_STD_IOSTREAM to |
|
override default - see section 7.1.2 of the C++ Using Guide" |
|
#error "cannot include iosfwd -- define __USE_STD_IOSTREAM to override default |
|
- see section 7.1.2 of the C++ Using Guide" |
|
|
|
This may be followed by other errors, complaining that 'namespace "std" has no |
|
member'. The solution to this is to add the line |
|
|
|
#define __USE_STD_IOSTREAM 1 |
|
|
|
to the config.h file. |
|
|
|
|
Using Sun's compilers for Solaris |
Using Sun's compilers for Solaris |
--------------------------------- |
--------------------------------- |
|
|
Line 544 script creates the .txt and HTML forms of the document
|
Line 633 script creates the .txt and HTML forms of the document
|
Testing PCRE |
Testing PCRE |
------------ |
------------ |
|
|
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. |
created by the configuring process. There is also a script called RunGrepTest | There is another script called RunGrepTest that tests the options of the |
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 |
built, three test programs called pcrecpp_unittest, pcre_scanner_unittest, and | called pcrecpp_unittest, pcre_scanner_unittest, and pcre_stringpiece_unittest |
pcre_stringpiece_unittest are also built. When JIT support is enabled, another | are also built. When JIT support is enabled, another test program called |
test program called pcre_jit_test is built. | pcre_jit_test is built. |
|
|
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 |
"make test". For other systems, see the instructions in NON-UNIX-USE. | "make test". For other environments, see the instructions in |
| NON-AUTOTOOLS-BUILD. |
|
|
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 |
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 |
directory, and compares the output with the contents of the corresponding |
directory, and compares the output with the contents of the corresponding |
testoutput files. Some tests are relevant only when certain build-time options | testoutput files. RunTest uses a file called testtry to hold the main output |
were selected. For example, the tests for UTF-8 support are run only if | from pcretest. Other files whose names begin with "test" are used as working |
--enable-utf8 was used. RunTest outputs a comment when it skips a test. | files in some tests. |
|
|
|
Some tests are relevant only when certain build-time options were selected. For |
|
example, the tests for UTF-8/16/32 support are run only if --enable-utf was |
|
used. RunTest outputs a comment when it skips a test. |
|
|
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 |
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 |
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 |
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, |
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. |
|
This testing can be suppressed by putting "nojit" on the RunTest command line. |
|
|
RunTest uses a file called testtry to hold the main output from pcretest | The entire set of tests is run once for each of the 8-bit, 16-bit and 32-bit |
(testsavedregex is also used as a working file). To run pcretest on just one of | libraries that are enabled. If you want to run just one set of tests, call |
the test files, give its number as an argument to RunTest, for example: | RunTest with either the -8, -16 or -32 option. |
|
|
RunTest 2 | If valgrind is installed, you can run the tests under it by putting "valgrind" |
| on the RunTest command line. To run pcretest on just one or more specific test |
| files, give their numbers as arguments to RunTest, for example: |
|
|
|
RunTest 2 7 11 |
|
|
|
You can also specify ranges of tests such as 3-6 or 3- (meaning 3 to the |
|
end), or a number preceded by ~ to exclude a test. For example: |
|
|
|
Runtest 3-15 ~10 |
|
|
|
This runs tests 3 to 15, excluding test 10, and just ~13 runs all the tests |
|
except test 13. Whatever order the arguments are in, the tests are always run |
|
in numerical order. |
|
|
|
You can also call RunTest with the single argument "list" to cause it to output |
|
a list of tests. |
|
|
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 |
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 |
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. |
|
|
The second set of tests check pcre_fullinfo(), pcre_info(), pcre_study(), | The second set of tests check pcre_fullinfo(), pcre_study(), |
pcre_copy_substring(), pcre_get_substring(), pcre_get_substring_list(), error |
pcre_copy_substring(), pcre_get_substring(), pcre_get_substring_list(), error |
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 |
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 |
Line 612 RunTest.bat. The version of RunTest.bat included with
|
Line 723 RunTest.bat. The version of RunTest.bat included with
|
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 |
document entitled NON-UNIX-USE.] |
document entitled NON-UNIX-USE.] |
|
|
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 |
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 |
| sixth and seventh tests do the same for Unicode character properties support. |
|
|
The fifth test checks error handling with UTF-8 encoding, and internal UTF-8 | The eighth, ninth, and tenth tests check the pcre_dfa_exec() alternative |
features of PCRE that are not relevant to Perl. | matching function, in non-UTF-8/16/32 mode, UTF-8/16/32 mode, and UTF-8/16/32 |
| mode with Unicode property support, respectively. |
|
|
The sixth test (which is Perl-5.10 compatible) checks the support for Unicode | The eleventh test checks some internal offsets and code size features; it is |
character properties. This file can be also fed directly to the perltest.pl | run only when the default "link size" of 2 is set (in other cases the sizes |
script, provided you are running Perl 5.10 or higher. | change) and when Unicode property support is enabled. |
|
|
The seventh, eighth, and ninth tests check the pcre_dfa_exec() alternative | The twelfth test is run only when JIT support is available, and the thirteenth |
matching function, in non-UTF-8 mode, UTF-8 mode, and UTF-8 mode with Unicode | test is run only when JIT support is not available. They test some JIT-specific |
property support, respectively. | features such as information output from pcretest about JIT compilation. |
|
|
The tenth test checks some internal offsets and code size features; it is run | The fourteenth, fifteenth, and sixteenth tests are run only in 8-bit mode, and |
only when the default "link size" of 2 is set (in other cases the sizes | the seventeenth, eighteenth, and nineteenth tests are run only in 16/32-bit |
change) and when Unicode property support is enabled. | mode. These are tests that generate different output in the two modes. They are |
| for general cases, UTF-8/16/32 support, and Unicode property support, |
| respectively. |
|
|
The eleventh and twelfth tests check out features that are new in Perl 5.10, | The twentieth test is run only in 16/32-bit mode. It tests some specific |
without and with UTF-8 support, respectively. This file can be also fed | 16/32-bit features of the DFA matching engine. |
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 | The twenty-first and twenty-second tests are run only in 16/32-bit mode, when |
with Unicode property support. | the link size is set to 2 for the 16-bit library. They test reloading |
| pre-compiled patterns. |
|
|
The fourteenth test is run only when JIT support is available, and the | The twenty-third and twenty-fourth tests are run only in 16-bit mode. They are |
fifteenth test is run only when JIT support is not available. They test some | for general cases, and UTF-16 support, respectively. |
JIT-specific features such as information output from pcretest about JIT | |
compilation. | |
|
|
|
The twenty-fifth and twenty-sixth tests are run only in 32-bit mode. They are |
|
for general cases, and UTF-32 support, respectively. |
|
|
|
|
Character tables |
Character tables |
---------------- |
---------------- |
|
|
Line 701 will cause PCRE to malfunction.
|
Line 816 will cause PCRE to malfunction.
|
File manifest |
File manifest |
------------- |
------------- |
|
|
The distribution should contain the following files: | The distribution should contain the files listed below. Where a file name is |
| given as pcre[16|32]_xxx it means that there are three files, one with the name |
| pcre_xxx, one with the name pcre16_xx, and a third with the name pcre32_xxx. |
|
|
(A) Source files of the PCRE library functions and their headers: |
(A) Source files of the PCRE library functions and their headers: |
|
|
dftables.c auxiliary program for building pcre_chartables.c |
dftables.c auxiliary program for building pcre_chartables.c |
when --enable-rebuild-chartables is specified | when --enable-rebuild-chartables is specified |
|
|
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 |
coding; used, unless --enable-rebuild-chartables is | coding; used, unless --enable-rebuild-chartables is |
specified, by copying to pcre_chartables.c | specified, by copying to pcre[16]_chartables.c |
|
|
pcreposix.c ) | pcreposix.c ) |
pcre_compile.c ) | pcre[16|32]_byte_order.c ) |
pcre_config.c ) | pcre[16|32]_compile.c ) |
pcre_dfa_exec.c ) | pcre[16|32]_config.c ) |
pcre_exec.c ) | pcre[16|32]_dfa_exec.c ) |
pcre_fullinfo.c ) | pcre[16|32]_exec.c ) |
pcre_get.c ) sources for the functions in the library, | pcre[16|32]_fullinfo.c ) |
pcre_globals.c ) and some internal functions that they use | pcre[16|32]_get.c ) sources for the functions in the library, |
pcre_info.c ) | pcre[16|32]_globals.c ) and some internal functions that they use |
pcre_jit_compile.c ) | pcre[16|32]_jit_compile.c ) |
pcre_maketables.c ) | pcre[16|32]_maketables.c ) |
pcre_newline.c ) | pcre[16|32]_newline.c ) |
pcre_ord2utf8.c ) | pcre[16|32]_refcount.c ) |
pcre_refcount.c ) | pcre[16|32]_string_utils.c ) |
pcre_study.c ) | pcre[16|32]_study.c ) |
pcre_tables.c ) | pcre[16|32]_tables.c ) |
pcre_try_flipped.c ) | pcre[16|32]_ucd.c ) |
pcre_ucd.c ) | pcre[16|32]_version.c ) |
pcre_valid_utf8.c ) | pcre[16|32]_xclass.c ) |
pcre_version.c ) | pcre_ord2utf8.c ) |
pcre_xclass.c ) | pcre_valid_utf8.c ) |
pcre_printint.src ) debugging function that is #included in pcretest, | pcre16_ord2utf16.c ) |
) and can also be #included in pcre_compile() | pcre16_utf16_utils.c ) |
| pcre16_valid_utf16.c ) |
| pcre32_utf32_utils.c ) |
| pcre32_valid_utf32.c ) |
| |
| pcre[16|32]_printint.c ) debugging function that is used by pcretest, |
| ) and can also be #included in pcre_compile() |
| |
pcre.h.in template for pcre.h when built by "configure" |
pcre.h.in template for pcre.h when built by "configure" |
pcreposix.h header for the external POSIX wrapper API |
pcreposix.h header for the external POSIX wrapper API |
pcre_internal.h header for internal use |
pcre_internal.h header for internal use |
Line 775 The distribution should contain the following files:
|
Line 899 The distribution should contain the following files:
|
Makefile.am ) the automake input that was used to create |
Makefile.am ) the automake input that was used to create |
) Makefile.in |
) Makefile.in |
NEWS important changes in this release |
NEWS important changes in this release |
NON-UNIX-USE notes on building PCRE on non-Unix systems | NON-UNIX-USE the previous name for NON-AUTOTOOLS-BUILD |
| NON-AUTOTOOLS-BUILD notes on building PCRE without using autotools |
PrepareRelease script to make preparations for "make dist" |
PrepareRelease script to make preparations for "make dist" |
README this file |
README this file |
RunTest a Unix shell script for running tests |
RunTest a Unix shell script for running tests |
Line 796 The distribution should contain the following files:
|
Line 921 The distribution should contain the following files:
|
doc/pcretest.txt plain text documentation of test program |
doc/pcretest.txt plain text documentation of test program |
doc/perltest.txt plain text documentation of Perl test program |
doc/perltest.txt plain text documentation of Perl test program |
install-sh a shell script for installing files |
install-sh a shell script for installing files |
|
libpcre16.pc.in template for libpcre16.pc for pkg-config |
|
libpcre32.pc.in template for libpcre32.pc for pkg-config |
libpcre.pc.in template for libpcre.pc for pkg-config |
libpcre.pc.in template for libpcre.pc for pkg-config |
libpcreposix.pc.in template for libpcreposix.pc for pkg-config |
libpcreposix.pc.in template for libpcreposix.pc for pkg-config |
libpcrecpp.pc.in template for libpcrecpp.pc for pkg-config |
libpcrecpp.pc.in template for libpcrecpp.pc for pkg-config |
Line 812 The distribution should contain the following files:
|
Line 939 The distribution should contain the following files:
|
testdata/testinput* test data for main library tests |
testdata/testinput* test data for main library tests |
testdata/testoutput* expected test results |
testdata/testoutput* expected test results |
testdata/grep* input and output for pcregrep tests |
testdata/grep* input and output for pcregrep tests |
|
testdata/* other supporting test files |
|
|
(D) Auxiliary files for cmake support |
(D) Auxiliary files for cmake support |
|
|
cmake/COPYING-CMAKE-SCRIPTS |
cmake/COPYING-CMAKE-SCRIPTS |
cmake/FindPackageHandleStandardArgs.cmake |
cmake/FindPackageHandleStandardArgs.cmake |
|
cmake/FindEditline.cmake |
cmake/FindReadline.cmake |
cmake/FindReadline.cmake |
CMakeLists.txt |
CMakeLists.txt |
config-cmake.h.in |
config-cmake.h.in |
Line 842 The distribution should contain the following files:
|
Line 971 The distribution should contain the following files:
|
Philip Hazel |
Philip Hazel |
Email local part: ph10 |
Email local part: ph10 |
Email domain: cam.ac.uk |
Email domain: cam.ac.uk |
Last updated: 06 September 2011 | Last updated: 28 April 2013 |