ViewVC logotype

Contents of /code/trunk/README

Parent Directory Parent Directory | Revision Log Revision Log

Revision 43 - (hide annotations) (download)
Sat Feb 24 21:39:21 2007 UTC (8 years, 1 month ago) by nigel
File size: 10752 byte(s)
Load pcre-3.0 into code/trunk.

1 nigel 41 README file for PCRE (Perl-compatible regular expression library)
2     -----------------------------------------------------------------
3 nigel 3
4 nigel 43 The latest release of PCRE is always available from
6     ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre-xxx.tar.gz
8 nigel 41 Please read the NEWS file if you are upgrading from a previous release.
9 nigel 23
10 nigel 35
11 nigel 41 Building PCRE on a Unix system
12     ------------------------------
13 nigel 3
14 nigel 41 To build PCRE on a Unix system, run the "configure" command in the PCRE
15     distribution directory. This is a standard GNU "autoconf" configuration script,
16     for which generic instructions are supplied in INSTALL. On many systems just
17     running "./configure" is sufficient, but the usual methods of changing standard
18     defaults are available. For example
19 nigel 3
20 nigel 41 CFLAGS='-O2 -Wall' ./configure --prefix=/opt/local
22     specifies that the C compiler should be run with the flags '-O2 -Wall' instead
23     of the default, and that "make install" should install PCRE under /opt/local
24 nigel 43 instead of the default /usr/local. The "configure" script builds thre files:
25 nigel 41
26 nigel 43 . Makefile is built by copying Makefile.in and making substitutions.
27     . config.h is built by copying config.in and making substitutions.
28     . pcre-config is built by copying pcre-config.in and making substitutions.
29 nigel 41
30     Once "configure" has run, you can run "make". It builds two libraries called
31 nigel 43 libpcre and libpcreposix, a test program called pcretest, and the pgrep
32 nigel 37 command. You can use "make install" to copy these, and the public header file
33 nigel 41 pcre.h, to appropriate live directories on your system, in the normal way.
34 nigel 3
35 nigel 43 Running "make install" also installs the command pcre-config, which can be used
36     to recall information about the PCRE configuration and installation. For
37     example,
38 nigel 37
39 nigel 43 pcre-config --version
41     prints the version number, and
43     pcre-config --libs
45     outputs information about where the library is installed. This command can be
46     included in makefiles for programs that use PCRE, saving the programmer from
47     having to remember too many details.
50 nigel 41 Shared libraries on Unix systems
51     --------------------------------
52 nigel 39
53 nigel 43 The default distribution builds PCRE as two shared libraries. This support is
54     new and experimental and may not work on all systems. It relies on the
55     "libtool" scripts - these are distributed with PCRE. It should build a
56     "libtool" script and use this to compile and link shared libraries, which are
57     placed in a subdirectory called .libs. The programs pcretest and pgrep are
58     built to use these uninstalled libraries by means of wrapper scripts. When you
59     use "make install" to install shared libraries, pgrep and pcretest are
60     automatically re-built to use the newly installed libraries. However, only
61     pgrep is installed, as pcretest is really just a test program.
62 nigel 39
63 nigel 43 To build PCRE using static libraries you must use --disable-shared when
64     configuring it. For example
65 nigel 3
66 nigel 43 ./configure --prefix=/usr/gnu --disable-shared
67 nigel 41
68 nigel 43 Then run "make" in the usual way.
69 nigel 41
70 nigel 43
71 nigel 41 Building on non-Unix systems
72     ----------------------------
74     For a non-Unix system, read the comments in the file NON-UNIX-USE. PCRE has
75     been compiled on Windows systems and on Macintoshes, but I don't know the
76     details because I don't use those systems. It should be straightforward to
77     build PCRE on any system that has a Standard C compiler, because it uses only
78     Standard C functions.
81     Testing PCRE
82     ------------
84     To test PCRE on a Unix system, run the RunTest script in the pcre directory.
85     (This can also be run by "make runtest" or "make check".) For other systems,
86     see the instruction in NON-UNIX-USE.
88     The script runs the pcretest test program (which is documented in
89     doc/pcretest.txt) on each of the testinput files (in the testdata directory) in
90     turn, and compares the output with the contents of the corresponding testoutput
91     file. A file called testtry is used to hold the output from pcretest. To run
92     pcretest on just one of the test files, give its number as an argument to
93     RunTest, for example:
95 nigel 23 RunTest 3
96 nigel 3
97 nigel 23 The first and third test files can also be fed directly into the perltest
98 nigel 37 script to check that Perl gives the same results. The third file requires the
99 nigel 23 additional features of release 5.005, which is why it is kept separate from the
100     main test input, which needs only Perl 5.004. In the long run, when 5.005 is
101     widespread, these two test files may get amalgamated.
102 nigel 3
103 nigel 29 The second set of tests check pcre_info(), pcre_study(), pcre_copy_substring(),
104     pcre_get_substring(), pcre_get_substring_list(), error detection and run-time
105     flags that are specific to PCRE, as well as the POSIX wrapper API.
106 nigel 7
107 nigel 25 The fourth set of tests checks pcre_maketables(), the facility for building a
108     set of character tables for a specific locale and using them instead of the
109     default tables. The tests make use of the "fr" (French) locale. Before running
110     the test, the script checks for the presence of this locale by running the
111     "locale" command. If that command fails, or if it doesn't include "fr" in the
112     list of available locales, the fourth test cannot be run, and a comment is
113     output to say why. If running this test produces instances of the error
115     ** Failed to set locale "fr"
117     in the comparison output, it means that locale is not available on your system,
118     despite being listed by "locale". This does not mean that PCRE is broken.
120 nigel 3 PCRE has its own native API, but a set of "wrapper" functions that are based on
121     the POSIX API are also supplied in the library libpcreposix.a. Note that this
122     just provides a POSIX calling interface to PCRE: the regular expressions
123     themselves still follow Perl syntax and semantics. The header file
124     for the POSIX-style functions is called pcreposix.h. The official POSIX name is
125     regex.h, but I didn't want to risk possible problems with existing files of
126     that name by distributing it that way. To use it with an existing program that
127 nigel 23 uses the POSIX API, it will have to be renamed or pointed at by a link.
128 nigel 3
130     Character tables
131     ----------------
133 nigel 25 PCRE uses four tables for manipulating and identifying characters. The final
134     argument of the pcre_compile() function is a pointer to a block of memory
135 nigel 35 containing the concatenated tables. A call to pcre_maketables() can be used to
136     generate a set of tables in the current locale. If the final argument for
137     pcre_compile() is passed as NULL, a set of default tables that is built into
138     the binary is used.
139 nigel 3
140 nigel 25 The source file called chartables.c contains the default set of tables. This is
141 nigel 27 not supplied in the distribution, but is built by the program dftables
142     (compiled from dftables.c), which uses the ANSI C character handling functions
143 nigel 25 such as isalnum(), isalpha(), isupper(), islower(), etc. to build the table
144 nigel 35 sources. This means that the default C locale which is set for your system will
145     control the contents of these default tables. You can change the default tables
146     by editing chartables.c and then re-building PCRE. If you do this, you should
147     probably also edit Makefile to ensure that the file doesn't ever get
148     re-generated.
149 nigel 3
150 nigel 25 The first two 256-byte tables provide lower casing and case flipping functions,
151     respectively. The next table consists of three 32-byte bit maps which identify
152     digits, "word" characters, and white space, respectively. These are used when
153     building 32-byte bit maps that represent character classes.
155     The final 256-byte table has bits indicating various character types, as
156 nigel 3 follows:
158     1 white space character
159     2 letter
160     4 decimal digit
161     8 hexadecimal digit
162     16 alphanumeric or '_'
163     128 regular expression metacharacter or binary zero
165     You should not alter the set of characters that contain the 128 bit, as that
166     will cause PCRE to malfunction.
169 nigel 41 Manifest
170     --------
171 nigel 3
172 nigel 41 The distribution should contain the following files:
173 nigel 3
174 nigel 41 (A) The actual source files of the PCRE library functions and their
175     headers:
176 nigel 3
177 nigel 41 dftables.c auxiliary program for building chartables.c
178     get.c )
179     maketables.c )
180     study.c ) source of
181     pcre.c ) the functions
182     pcreposix.c )
183 nigel 43 pcre.in "source" for the header for the external API; pcre.h
184     is built from this by "configure"
185 nigel 41 pcreposix.h header for the external POSIX wrapper API
186     internal.h header for internal use
187     config.in template for config.h, which is built by configure
188 nigel 3
189 nigel 41 (B) Auxiliary files:
190 nigel 3
191 nigel 41 AUTHORS information about the author of PCRE
192     ChangeLog log of changes to the code
193     INSTALL generic installation instructions
194     LICENCE conditions for the use of PCRE
195 nigel 43 COPYING the same, using GNU's standard name
196 nigel 41 Makefile.in template for Unix Makefile, which is built by configure
197     NEWS important changes in this release
198     NON-UNIX-USE notes on building PCRE on non-Unix systems
199     README this file
200     RunTest a Unix shell script for running tests
201     config.guess ) files used by libtool,
202     config.sub ) used only when building a shared library
203     configure a configuring shell script (built by autoconf)
204     configure.in the autoconf input used to build configure
205     doc/Tech.Notes notes on the encoding
206     doc/pcre.3 man page source for the PCRE functions
207     doc/pcre.html HTML version
208     doc/pcre.txt plain text version
209     doc/pcreposix.3 man page source for the POSIX wrapper API
210     doc/pcreposix.html HTML version
211     doc/pcreposix.txt plain text version
212     doc/pcretest.txt documentation of test program
213     doc/perltest.txt documentation of Perl test program
214     doc/pgrep.1 man page source for the pgrep utility
215     doc/pgrep.html HTML version
216     doc/pgrep.txt plain text version
217     install-sh a shell script for installing files
218     ltconfig ) files used to build "libtool",
219     ltmain.sh ) used only when building a shared library
220     pcretest.c test program
221     perltest Perl test program
222     pgrep.c source of a grep utility that uses PCRE
223 nigel 43 pcre-config.in source of script which retains PCRE information
224 nigel 41 testdata/testinput1 test data, compatible with Perl 5.004 and 5.005
225     testdata/testinput2 test data for error messages and non-Perl things
226     testdata/testinput3 test data, compatible with Perl 5.005
227     testdata/testinput4 test data for locale-specific tests
228     testdata/testoutput1 test results corresponding to testinput1
229     testdata/testoutput2 test results corresponding to testinput2
230     testdata/testoutput3 test results corresponding to testinput3
231     testdata/testoutput4 test results corresponding to testinput4
232 nigel 3
233 nigel 41 (C) Auxiliary files for Win32 DLL
234 nigel 29
235 nigel 41 dll.mk
236     pcre.def
237 nigel 29
238 nigel 3 Philip Hazel <ph10@cam.ac.uk>
239 nigel 43 February 2000

ViewVC Help
Powered by ViewVC 1.1.12