/[pcre]/code/trunk/README
ViewVC logotype

Contents of /code/trunk/README

Parent Directory Parent Directory | Revision Log Revision Log


Revision 41 - (hide annotations) (download)
Sat Feb 24 21:39:17 2007 UTC (7 years, 8 months ago) by nigel
File size: 9899 byte(s)
Load pcre-2.08a into code/trunk.

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

webmaster@exim.org
ViewVC Help
Powered by ViewVC 1.1.12