X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=pcre%2Fdoc%2Freadme;fp=pcre%2Fdoc%2Freadme;h=0000000000000000000000000000000000000000;hp=d124ee014c1a59b35b3e7e922c0bd8997cc6119b;hb=878f6fc9589394ee23f5e0e9bd549f88532a3978;hpb=66b8a8b2a9a28586e5e7ac6591b271e991449131 diff --git a/pcre/doc/readme b/pcre/doc/readme deleted file mode 100644 index d124ee01..00000000 --- a/pcre/doc/readme +++ /dev/null @@ -1,270 +0,0 @@ -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. - -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. 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. - - -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. - -If you want to make use of the experimential, incomplete support for UTF-8 -character strings in PCRE, you must add --enable-utf8 to the "configure" -command. Without it, the code for handling UTF-8 is not included in the -library. (Even when included, it still has to be enabled by an option at run -time.) - -The "configure" script builds four 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. -. RunTest is a script for running tests - -Once "configure" has run, you can run "make". It builds two libraries called -libpcre and libpcreposix, a test program called pcretest, and the pcregrep -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 pcregrep are -built to use these uninstalled libraries by means of wrapper scripts. When you -use "make install" to install shared libraries, pcregrep and pcretest are -automatically re-built to use the newly installed libraries. However, only -pcregrep 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", "make check", or "make test".) 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 (or -higher) is widespread, these two test files may get amalgamated. - -The second set of tests check pcre_fullinfo(), 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. It also uses the debugging flag to check some of the internals of -pcre_compile(). - -If you build PCRE with a locale setting that is not the standard C locale, the -character tables may be different (see next paragraph). In some cases, this may -cause failures in the second set of tests. For example, in a locale where the -isprint() function yields TRUE for characters in the range 128-255, the use of -[:isascii:] inside a character class defines a different set of characters, and -this shows up in this test as a difference in the compiled code, which is being -listed for checking. Where the comparison test output contains [\x00-\x7f] the -test will contain [\x00-\xff], and similarly in some other cases. This is not a -bug in PCRE. - -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. - -The fifth test checks the experimental, incomplete UTF-8 support. It is not run -automatically unless PCRE is built with UTF-8 support. This file can be fed -directly to the perltest8 script, which requires Perl 5.6 or higher. The sixth -file tests internal UTF-8 features of PCRE that are not relevant to Perl. - - -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.in template for 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/pcregrep.1 man page source for the pcregrep utility - doc/pcregrep.html HTML version - doc/pcregrep.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 - perltest8 Perl test program for UTF-8 tests - pcregrep.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/testinput5 test data for UTF-8 tests compatible with Perl 5.6 - testdata/testinput6 test data for other UTF-8 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 - testdata/testoutput5 test results corresponding to testinput5 - testdata/testoutput6 test results corresponding to testinput6 - -(C) Auxiliary files for Win32 DLL - - dll.mk - pcre.def - -Philip Hazel -August 2000