/[pcre]/code/trunk/doc/pcrebuild.3
ViewVC logotype

Contents of /code/trunk/doc/pcrebuild.3

Parent Directory Parent Directory | Revision Log Revision Log


Revision 149 - (hide annotations) (download)
Mon Apr 16 15:28:08 2007 UTC (7 years, 7 months ago) by ph10
File size: 9398 byte(s)
Add PCRE_NEWLINE_ANYCRLF.

1 nigel 79 .TH PCREBUILD 3
2 nigel 63 .SH NAME
3     PCRE - Perl-compatible regular expressions
4 nigel 75 .SH "PCRE BUILD-TIME OPTIONS"
5 nigel 63 .rs
6     .sp
7     This document describes the optional features of PCRE that can be selected when
8     the library is compiled. They are all selected, or deselected, by providing
9 nigel 75 options to the \fBconfigure\fP script that is run before the \fBmake\fP
10     command. The complete list of options for \fBconfigure\fP (which includes the
11 nigel 63 standard ones such as the selection of the installation directory) can be
12     obtained by running
13 nigel 75 .sp
14 nigel 63 ./configure --help
15 nigel 75 .sp
16 ph10 128 The following sections include descriptions of options whose names begin with
17     --enable or --disable. These settings specify changes to the defaults for the
18 nigel 75 \fBconfigure\fP command. Because of the way that \fBconfigure\fP works,
19 nigel 63 --enable and --disable always come in pairs, so the complementary option always
20     exists as well, but as it specifies the default, it is not described.
21 nigel 75 .
22 nigel 83 .SH "C++ SUPPORT"
23     .rs
24     .sp
25     By default, the \fBconfigure\fP script will search for a C++ compiler and C++
26     header files. If it finds them, it automatically builds the C++ wrapper library
27     for PCRE. You can disable this by adding
28     .sp
29     --disable-cpp
30     .sp
31     to the \fBconfigure\fP command.
32     .
33 nigel 75 .SH "UTF-8 SUPPORT"
34 nigel 63 .rs
35     .sp
36     To build PCRE with support for UTF-8 character strings, add
37 nigel 75 .sp
38 nigel 63 --enable-utf8
39 nigel 75 .sp
40     to the \fBconfigure\fP command. Of itself, this does not make PCRE treat
41 nigel 63 strings as UTF-8. As well as compiling PCRE with this option, you also have
42 nigel 75 have to set the PCRE_UTF8 option when you call the \fBpcre_compile()\fP
43 nigel 63 function.
44 nigel 75 .
45     .SH "UNICODE CHARACTER PROPERTY SUPPORT"
46 nigel 63 .rs
47     .sp
48 nigel 75 UTF-8 support allows PCRE to process character values greater than 255 in the
49     strings that it handles. On its own, however, it does not provide any
50     facilities for accessing the properties of such characters. If you want to be
51     able to use the pattern escapes \eP, \ep, and \eX, which refer to Unicode
52     character properties, you must add
53     .sp
54     --enable-unicode-properties
55     .sp
56     to the \fBconfigure\fP command. This implies UTF-8 support, even if you have
57     not explicitly requested it.
58     .P
59 ph10 128 Including Unicode property support adds around 30K of tables to the PCRE
60     library. Only the general category properties such as \fILu\fP and \fINd\fP are
61     supported. Details are given in the
62 nigel 75 .\" HREF
63     \fBpcrepattern\fP
64     .\"
65     documentation.
66     .
67     .SH "CODE VALUE OF NEWLINE"
68     .rs
69     .sp
70 nigel 91 By default, PCRE interprets character 10 (linefeed, LF) as indicating the end
71     of a line. This is the normal newline character on Unix-like systems. You can
72     compile PCRE to use character 13 (carriage return, CR) instead, by adding
73 nigel 75 .sp
74 nigel 63 --enable-newline-is-cr
75 nigel 75 .sp
76 nigel 91 to the \fBconfigure\fP command. There is also a --enable-newline-is-lf option,
77     which explicitly specifies linefeed as the newline character.
78     .sp
79     Alternatively, you can specify that line endings are to be indicated by the two
80     character sequence CRLF. If you want this, add
81     .sp
82     --enable-newline-is-crlf
83     .sp
84 nigel 93 to the \fBconfigure\fP command. There is a fourth option, specified by
85     .sp
86 ph10 149 --enable-newline-is-anycrlf
87     .sp
88     which causes PCRE to recognize any of the three sequences CR, LF, or CRLF as
89     indicating a line ending. Finally, a fifth option, specified by
90     .sp
91 nigel 93 --enable-newline-is-any
92     .sp
93 ph10 149 causes PCRE to recognize any Unicode newline sequence.
94 nigel 93 .P
95     Whatever line ending convention is selected when PCRE is built can be
96     overridden when the library functions are called. At build time it is
97     conventional to use the standard for your operating system.
98 nigel 75 .
99     .SH "BUILDING SHARED AND STATIC LIBRARIES"
100 nigel 63 .rs
101     .sp
102 nigel 75 The PCRE building process uses \fBlibtool\fP to build both shared and static
103 nigel 63 Unix libraries by default. You can suppress one of these by adding one of
104 nigel 75 .sp
105 nigel 63 --disable-shared
106     --disable-static
107 nigel 75 .sp
108     to the \fBconfigure\fP command, as required.
109     .
110     .SH "POSIX MALLOC USAGE"
111 nigel 63 .rs
112     .sp
113 nigel 75 When PCRE is called through the POSIX interface (see the
114     .\" HREF
115     \fBpcreposix\fP
116     .\"
117 nigel 63 documentation), additional working storage is required for holding the pointers
118 nigel 75 to capturing substrings, because PCRE requires three integers per substring,
119 nigel 63 whereas the POSIX interface provides only two. If the number of expected
120     substrings is small, the wrapper function uses space on the stack, because this
121 nigel 75 is faster than using \fBmalloc()\fP for each call. The default threshold above
122 nigel 63 which the stack is no longer used is 10; it can be changed by adding a setting
123     such as
124 nigel 75 .sp
125 nigel 63 --with-posix-malloc-threshold=20
126 nigel 75 .sp
127     to the \fBconfigure\fP command.
128     .
129     .SH "HANDLING VERY LARGE PATTERNS"
130 nigel 63 .rs
131     .sp
132     Within a compiled pattern, offset values are used to point from one part to
133     another (for example, from an opening parenthesis to an alternation
134 nigel 75 metacharacter). By default, two-byte values are used for these offsets, leading
135 nigel 63 to a maximum size for a compiled pattern of around 64K. This is sufficient to
136     handle all but the most gigantic patterns. Nevertheless, some people do want to
137     process enormous patterns, so it is possible to compile PCRE to use three-byte
138     or four-byte offsets by adding a setting such as
139 nigel 75 .sp
140 nigel 63 --with-link-size=3
141 nigel 75 .sp
142     to the \fBconfigure\fP command. The value given must be 2, 3, or 4. Using
143 nigel 63 longer offsets slows down the operation of PCRE because it has to load
144     additional bytes when handling them.
145 nigel 75 .
146     .SH "AVOIDING EXCESSIVE STACK USAGE"
147 nigel 73 .rs
148     .sp
149 nigel 77 When matching with the \fBpcre_exec()\fP function, PCRE implements backtracking
150     by making recursive calls to an internal function called \fBmatch()\fP. In
151     environments where the size of the stack is limited, this can severely limit
152     PCRE's operation. (The Unix environment does not usually suffer from this
153 nigel 91 problem, but it may sometimes be necessary to increase the maximum stack size.
154     There is a discussion in the
155     .\" HREF
156     \fBpcrestack\fP
157     .\"
158     documentation.) An alternative approach to recursion that uses memory from the
159     heap to remember data, instead of using recursive function calls, has been
160     implemented to work round the problem of limited stack size. If you want to
161     build a version of PCRE that works this way, add
162 nigel 75 .sp
163 nigel 73 --disable-stack-for-recursion
164 nigel 75 .sp
165     to the \fBconfigure\fP command. With this configuration, PCRE will use the
166     \fBpcre_stack_malloc\fP and \fBpcre_stack_free\fP variables to call memory
167 nigel 73 management functions. Separate functions are provided because the usage is very
168     predictable: the block sizes requested are always the same, and the blocks are
169     always freed in reverse order. A calling program might be able to implement
170 nigel 75 optimized functions that perform better than the standard \fBmalloc()\fP and
171     \fBfree()\fP functions. PCRE runs noticeably more slowly when built in this
172 nigel 77 way. This option affects only the \fBpcre_exec()\fP function; it is not
173     relevant for the the \fBpcre_dfa_exec()\fP function.
174 nigel 75 .
175 nigel 91 .SH "LIMITING PCRE RESOURCE USAGE"
176     .rs
177     .sp
178     Internally, PCRE has a function called \fBmatch()\fP, which it calls repeatedly
179     (sometimes recursively) when matching a pattern with the \fBpcre_exec()\fP
180     function. By controlling the maximum number of times this function may be
181     called during a single matching operation, a limit can be placed on the
182     resources used by a single call to \fBpcre_exec()\fP. The limit can be changed
183     at run time, as described in the
184     .\" HREF
185     \fBpcreapi\fP
186     .\"
187     documentation. The default is 10 million, but this can be changed by adding a
188     setting such as
189     .sp
190     --with-match-limit=500000
191     .sp
192     to the \fBconfigure\fP command. This setting has no effect on the
193     \fBpcre_dfa_exec()\fP matching function.
194     .P
195     In some environments it is desirable to limit the depth of recursive calls of
196     \fBmatch()\fP more strictly than the total number of calls, in order to
197     restrict the maximum amount of stack (or heap, if --disable-stack-for-recursion
198     is specified) that is used. A second limit controls this; it defaults to the
199     value that is set for --with-match-limit, which imposes no additional
200     constraints. However, you can set a lower limit by adding, for example,
201     .sp
202     --with-match-limit-recursion=10000
203     .sp
204     to the \fBconfigure\fP command. This value can also be overridden at run time.
205     .
206 ph10 128 .SH "CREATING CHARACTER TABLES AT BUILD TIME"
207     .rs
208     .sp
209     PCRE uses fixed tables for processing characters whose code values are less
210     than 256. By default, PCRE is built with a set of tables that are distributed
211     in the file \fIpcre_chartables.c.dist\fP. These tables are for ASCII codes
212     only. If you add
213     .sp
214     --enable-rebuild-chartables
215     .sp
216     to the \fBconfigure\fP command, the distributed tables are no longer used.
217     Instead, a program called \fBdftables\fP is compiled and run. This outputs the
218     source for new set of tables, created in the default locale of your C runtime
219     system. (This method of replacing the tables does not work if you are cross
220     compiling, because \fBdftables\fP is run on the local host. If you need to
221     create alternative tables when cross compiling, you will have to do so "by
222     hand".)
223     .
224 nigel 75 .SH "USING EBCDIC CODE"
225 nigel 73 .rs
226     .sp
227     PCRE assumes by default that it will run in an environment where the character
228 nigel 75 code is ASCII (or Unicode, which is a superset of ASCII). PCRE can, however, be
229 nigel 73 compiled to run in an EBCDIC environment by adding
230 nigel 75 .sp
231 nigel 73 --enable-ebcdic
232 nigel 75 .sp
233 ph10 128 to the \fBconfigure\fP command. This setting implies
234     --enable-rebuild-chartables.
235 nigel 93 .
236     .
237     .SH "SEE ALSO"
238     .rs
239     .sp
240     \fBpcreapi\fP(3), \fBpcre_config\fP(3).
241 ph10 99 .
242     .
243     .SH AUTHOR
244     .rs
245     .sp
246     .nf
247     Philip Hazel
248     University Computing Service
249     Cambridge CB2 3QH, England.
250     .fi
251     .
252     .
253     .SH REVISION
254     .rs
255     .sp
256     .nf
257 ph10 149 Last updated: 16 April 2007
258 ph10 99 Copyright (c) 1997-2007 University of Cambridge.
259     .fi

Properties

Name Value
svn:eol-style native
svn:keywords "Author Date Id Revision Url"

webmaster@exim.org
ViewVC Help
Powered by ViewVC 1.1.12