| README file for PCRE (Perl-compatible regular expression library) |
| ----------------------------------------------------------------- |
| |
| The latest release of PCRE is always available from |
| |
| ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre-xxx.tar.gz |
| |
| Please read the NEWS file if you are upgrading from a previous release. |
| |
| |
| Building PCRE on a Unix system |
| ------------------------------ |
| |
| To build PCRE on a Unix system, run the "configure" command in the PCRE |
| distribution directory. This is a standard GNU "autoconf" configuration script, |
| for which generic instructions are supplied in INSTALL. On many systems just |
| running "./configure" is sufficient, but the usual methods of changing standard |
| defaults are available. For example |
| |
| CFLAGS='-O2 -Wall' ./configure --prefix=/opt/local |
| |
| specifies that the C compiler should be run with the flags '-O2 -Wall' instead |
| of the default, and that "make install" should install PCRE under /opt/local |
| instead of the default /usr/local. The "configure" script builds thre files: |
| |
| . Makefile is built by copying Makefile.in and making substitutions. |
| . config.h is built by copying config.in and making substitutions. |
| . pcre-config is built by copying pcre-config.in and making substitutions. |
| |
| Once "configure" has run, you can run "make". It builds two libraries called |
| libpcre and libpcreposix, a test program called pcretest, and the pgrep |
| command. You can use "make install" to copy these, and the public header file |
| pcre.h, to appropriate live directories on your system, in the normal way. |
| |
| Running "make install" also installs the command pcre-config, which can be used |
| to recall information about the PCRE configuration and installation. For |
| example, |
| |
| pcre-config --version |
| |
| prints the version number, and |
| |
| pcre-config --libs |
| |
| outputs information about where the library is installed. This command can be |
| included in makefiles for programs that use PCRE, saving the programmer from |
| having to remember too many details. |
| |
| |
| Shared libraries on Unix systems |
| -------------------------------- |
| |
| The default distribution builds PCRE as two shared libraries. This support is |
| new and experimental and may not work on all systems. It relies on the |
| "libtool" scripts - these are distributed with PCRE. It should build a |
| "libtool" script and use this to compile and link shared libraries, which are |
| placed in a subdirectory called .libs. The programs pcretest and pgrep are |
| built to use these uninstalled libraries by means of wrapper scripts. When you |
| use "make install" to install shared libraries, pgrep and pcretest are |
| automatically re-built to use the newly installed libraries. However, only |
| pgrep is installed, as pcretest is really just a test program. |
| |
| To build PCRE using static libraries you must use --disable-shared when |
| configuring it. For example |
| |
| ./configure --prefix=/usr/gnu --disable-shared |
| |
| Then run "make" in the usual way. |
| |
| |
| Building on non-Unix systems |
| ---------------------------- |
| |
| For a non-Unix system, read the comments in the file NON-UNIX-USE. PCRE has |
| been compiled on Windows systems and on Macintoshes, but I don't know the |
| details because I don't use those systems. It should be straightforward to |
| build PCRE on any system that has a Standard C compiler, because it uses only |
| Standard C functions. |
| |
| |
| Testing PCRE |
| ------------ |
| |
| To test PCRE on a Unix system, run the RunTest script in the pcre directory. |
| (This can also be run by "make runtest" or "make check".) For other systems, |
| see the instruction in NON-UNIX-USE. |
| |
| The script runs the pcretest test program (which is documented in |
| doc/pcretest.txt) on each of the testinput files (in the testdata directory) in |
| turn, and compares the output with the contents of the corresponding testoutput |
| file. A file called testtry is used to hold the output from pcretest. To run |
| pcretest on just one of the test files, give its number as an argument to |
| RunTest, for example: |
| |
| RunTest 3 |
| |
| The first and third test files can also be fed directly into the perltest |
| script to check that Perl gives the same results. The third file requires the |
| additional features of release 5.005, which is why it is kept separate from the |
| main test input, which needs only Perl 5.004. In the long run, when 5.005 is |
| widespread, these two test files may get amalgamated. |
| |
| The second set of tests check pcre_info(), pcre_study(), 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 wrapper API. |
| |
| The fourth set of tests checks pcre_maketables(), the facility for building a |
| set of character tables for a specific locale and using them instead of the |
| default tables. The tests make use of the "fr" (French) locale. Before running |
| the test, the script checks for the presence of this locale by running the |
| "locale" command. If that command fails, or if it doesn't include "fr" in the |
| list of available locales, the fourth test cannot be run, and a comment is |
| output to say why. If running this test produces instances of the error |
| |
| ** Failed to set locale "fr" |
| |
| in the comparison output, it means that locale is not available on your system, |
| despite being listed by "locale". This does not mean that PCRE is broken. |
| |
| PCRE has its own native API, but a set of "wrapper" functions that are based on |
| the POSIX API are also supplied in the library libpcreposix.a. Note that this |
| just provides a POSIX calling interface to PCRE: the regular expressions |
| themselves still follow Perl syntax and semantics. The header file |
| for the POSIX-style functions is called pcreposix.h. The official POSIX name is |
| regex.h, but I didn't want to risk possible problems with existing files of |
| that name by distributing it that way. To use it with an existing program that |
| uses the POSIX API, it will have to be renamed or pointed at by a link. |
| |
| |
| Character tables |
| ---------------- |
| |
| PCRE uses four tables for manipulating and identifying characters. The final |
| argument of the pcre_compile() function is a pointer to a block of memory |
| containing the concatenated tables. A call to pcre_maketables() can be used to |
| generate a set of tables in the current locale. If the final argument for |
| pcre_compile() is passed as NULL, a set of default tables that is built into |
| the binary is used. |
| |
| The source file called chartables.c contains the default set of tables. This is |
| not supplied in the distribution, but is built by the program dftables |
| (compiled from dftables.c), which uses the ANSI C character handling functions |
| such as isalnum(), isalpha(), isupper(), islower(), etc. to build the table |
| sources. This means that the default C locale which is set for your system will |
| control the contents of these default tables. You can change the default tables |
| by editing chartables.c and then re-building PCRE. If you do this, you should |
| probably also edit Makefile to ensure that the file doesn't ever get |
| re-generated. |
| |
| The first two 256-byte tables provide lower casing and case flipping functions, |
| respectively. The next table consists of three 32-byte bit maps which identify |
| digits, "word" characters, and white space, respectively. These are used when |
| building 32-byte bit maps that represent character classes. |
| |
| The final 256-byte table has bits indicating various character types, as |
| follows: |
| |
| 1 white space character |
| 2 letter |
| 4 decimal digit |
| 8 hexadecimal digit |
| 16 alphanumeric or '_' |
| 128 regular expression metacharacter or binary zero |
| |
| You should not alter the set of characters that contain the 128 bit, as that |
| will cause PCRE to malfunction. |
| |
| |
| Manifest |
| -------- |
| |
| The distribution should contain the following files: |
| |
| (A) The actual source files of the PCRE library functions and their |
| headers: |
| |
| dftables.c auxiliary program for building chartables.c |
| get.c ) |
| maketables.c ) |
| study.c ) source of |
| pcre.c ) the functions |
| pcreposix.c ) |
| pcre.in "source" for the header for the external API; pcre.h |
| is built from this by "configure" |
| pcreposix.h header for the external POSIX wrapper API |
| internal.h header for internal use |
| config.in template for config.h, which is built by configure |
| |
| (B) Auxiliary files: |
| |
| AUTHORS information about the author of PCRE |
| ChangeLog log of changes to the code |
| INSTALL generic installation instructions |
| LICENCE conditions for the use of PCRE |
| COPYING the same, using GNU's standard name |
| Makefile.in template for Unix Makefile, which is built by configure |
| NEWS important changes in this release |
| NON-UNIX-USE notes on building PCRE on non-Unix systems |
| README this file |
| RunTest a Unix shell script for running tests |
| config.guess ) files used by libtool, |
| config.sub ) used only when building a shared library |
| configure a configuring shell script (built by autoconf) |
| configure.in the autoconf input used to build configure |
| doc/Tech.Notes notes on the encoding |
| doc/pcre.3 man page source for the PCRE functions |
| doc/pcre.html HTML version |
| doc/pcre.txt plain text version |
| doc/pcreposix.3 man page source for the POSIX wrapper API |
| doc/pcreposix.html HTML version |
| doc/pcreposix.txt plain text version |
| doc/pcretest.txt documentation of test program |
| doc/perltest.txt documentation of Perl test program |
| doc/pgrep.1 man page source for the pgrep utility |
| doc/pgrep.html HTML version |
| doc/pgrep.txt plain text version |
| install-sh a shell script for installing files |
| ltconfig ) files used to build "libtool", |
| ltmain.sh ) used only when building a shared library |
| pcretest.c test program |
| perltest Perl test program |
| pgrep.c source of a grep utility that uses PCRE |
| pcre-config.in source of script which retains PCRE information |
| testdata/testinput1 test data, compatible with Perl 5.004 and 5.005 |
| testdata/testinput2 test data for error messages and non-Perl things |
| testdata/testinput3 test data, compatible with Perl 5.005 |
| testdata/testinput4 test data for locale-specific tests |
| testdata/testoutput1 test results corresponding to testinput1 |
| testdata/testoutput2 test results corresponding to testinput2 |
| testdata/testoutput3 test results corresponding to testinput3 |
| testdata/testoutput4 test results corresponding to testinput4 |
| |
| (C) Auxiliary files for Win32 DLL |
| |
| dll.mk |
| pcre.def |
| |
| Philip Hazel <ph10@cam.ac.uk> |
| February 2000 |