From 93751f5e0bbc35cf20c27d1e17c070555671f4f1 Mon Sep 17 00:00:00 2001 From: nigel Date: Sat, 24 Feb 2007 21:39:42 +0000 Subject: Load pcre-3.5 into code/trunk. git-svn-id: svn://vcs.exim.org/pcre/code/trunk@53 2f5784b3-3f2a-0410-8824-cb99058d5e15 --- README | 103 ++++++++++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 70 insertions(+), 33 deletions(-) (limited to 'README') diff --git a/README b/README index d124ee0..7557374 100644 --- a/README +++ b/README @@ -17,14 +17,30 @@ 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. +Contributions by users of PCRE +------------------------------ + +You can find contributions from PCRE users in the directory + + ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/Contrib + +where there is also a README file giving brief descriptions of what they are. +Several of them provide support for compiling PCRE on various flavours of +Windows systems (I myself do not use Windows). Some are complete in themselves; +others are pointers to URLs containing relevant files. + + 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, +To build PCRE on a Unix system, first run the "configure" command from the PCRE +distribution directory, with your current directory set to the directory where +you want the files to be created. This command is a standard GNU "autoconf" +configuration script, for which generic instructions are supplied in INSTALL. + +Most commonly, people build PCRE within its own distribution directory, and in +this case, 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 @@ -32,14 +48,22 @@ 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 build in a different directory, just run "configure" with that +directory as current. For example, suppose you have unpacked the PCRE source +into /source/pcre/pcre-xxx, but you want to build it in /build/pcre/pcre-xxx: + +cd /build/pcre/pcre-xxx +/source/pcre/pcre-xxx/configure + 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: +The "configure" script builds five files: +. libtool is a script that builds shared and/or static libraries . 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. @@ -47,8 +71,9 @@ The "configure" script builds four files: 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. +command. You can use "make install" to copy these, the public header files +pcre.h and pcreposix.h, and the man pages 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 @@ -64,26 +89,38 @@ 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. +There is one esoteric feature that is controlled by "configure". It concerns +the character value used for "newline", and is something that you probably do +not want to change on a Unix system. The default is to use whatever value your +compiler gives to '\n'. By using --enable-newline-is-cr or +--enable-newline-is-lf you can force the value to be CR (13) or LF (10) if you +really want to. + 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 +The default distribution builds PCRE as two shared libraries and two static +libraries, as long as the operating system supports shared libraries. Shared +library support relies on the "libtool" script which is built as part of the +"configure" process. + +The libtool script is used to compile and link both shared and static +libraries. They are placed in a subdirectory called .libs when they are newly +built. The programs pcretest and pcregrep are built to use these uninstalled +libraries (by means of wrapper scripts in the case of shared libraries). When +you use "make install" to install shared libraries, pcregrep and pcretest are +automatically re-built to use the newly installed shared libraries before being +installed themselves. However, the versions left in the source directory still +use the uninstalled libraries. + +To build PCRE using static libraries only you must use --disable-shared when configuring it. For example ./configure --prefix=/usr/gnu --disable-shared -Then run "make" in the usual way. +Then run "make" in the usual way. Similarly, you can use --disable-static to +build only shared libraries. Building on non-Unix systems @@ -99,16 +136,16 @@ 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. +To test PCRE on a Unix system, run the RunTest script that is created by the +configuring process. (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: +The script runs the pcretest test program (which is documented in the doc +directory) 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 @@ -241,9 +278,9 @@ The distribution should contain the following files: 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 + ltmain.sh file used to build a libtool script + pcretest.c comprehensive test program + pcredemo.c simple demonstration of coding calls to PCRE perltest Perl test program perltest8 Perl test program for UTF-8 tests pcregrep.c source of a grep utility that uses PCRE @@ -267,4 +304,4 @@ The distribution should contain the following files: pcre.def Philip Hazel -August 2000 +August 2001 -- cgit v1.2.1