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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1178 - (show annotations)
Sat Oct 27 16:49:31 2012 UTC (7 years ago) by ph10
File size: 17674 byte(s)
Documentation edits for coverage.
1 .TH PCREBUILD 3 "27 October 2012" "PCRE 8.32"
2 .SH NAME
3 PCRE - Perl-compatible regular expressions
4 .
5 .
6 .SH "PCRE BUILD-TIME OPTIONS"
7 .rs
8 .sp
9 This document describes the optional features of PCRE that can be selected when
10 the library is compiled. It assumes use of the \fBconfigure\fP script, where
11 the optional features are selected or deselected by providing options to
12 \fBconfigure\fP before running the \fBmake\fP command. However, the same
13 options can be selected in both Unix-like and non-Unix-like environments using
14 the GUI facility of \fBcmake-gui\fP if you are using \fBCMake\fP instead of
15 \fBconfigure\fP to build PCRE.
16 .P
17 There is a lot more information about building PCRE without using
18 \fBconfigure\fP (including information about using \fBCMake\fP or building "by
19 hand") in the file called \fINON-AUTOTOOLS-BUILD\fP, which is part of the PCRE
20 distribution. You should consult this file as well as the \fIREADME\fP file if
21 you are building in a non-Unix-like environment.
22 .P
23 The complete list of options for \fBconfigure\fP (which includes the standard
24 ones such as the selection of the installation directory) can be obtained by
25 running
26 .sp
27 ./configure --help
28 .sp
29 The following sections include descriptions of options whose names begin with
30 --enable or --disable. These settings specify changes to the defaults for the
31 \fBconfigure\fP command. Because of the way that \fBconfigure\fP works,
32 --enable and --disable always come in pairs, so the complementary option always
33 exists as well, but as it specifies the default, it is not described.
34 .
35 .
36 .SH "BUILDING 8-BIT, 16-BIT AND 32-BIT LIBRARIES"
37 .rs
38 .sp
39 By default, a library called \fBlibpcre\fP is built, containing functions that
40 take string arguments contained in vectors of bytes, either as single-byte
41 characters, or interpreted as UTF-8 strings. You can also build a separate
42 library, called \fBlibpcre16\fP, in which strings are contained in vectors of
43 16-bit data units and interpreted either as single-unit characters or UTF-16
44 strings, by adding
45 .sp
46 --enable-pcre16
47 .sp
48 to the \fBconfigure\fP command. You can also build a separate
49 library, called \fBlibpcre32\fP, in which strings are contained in vectors of
50 32-bit data units and interpreted either as single-unit characters or UTF-32
51 strings, by adding
52 .sp
53 --enable-pcre32
54 .sp
55 to the \fBconfigure\fP command. If you do not want the 8-bit library, add
56 .sp
57 --disable-pcre8
58 .sp
59 as well. At least one of the two libraries must be built. Note that the C++ and
60 POSIX wrappers are for the 8-bit library only, and that \fBpcregrep\fP is an
61 8-bit program. None of these are built if you select only the 16-bit or 32-bit
62 libraries.
63 .
64 .
65 .SH "BUILDING SHARED AND STATIC LIBRARIES"
66 .rs
67 .sp
68 The PCRE building process uses \fBlibtool\fP to build both shared and static
69 Unix libraries by default. You can suppress one of these by adding one of
70 .sp
71 --disable-shared
72 --disable-static
73 .sp
74 to the \fBconfigure\fP command, as required.
75 .
76 .
77 .SH "C++ SUPPORT"
78 .rs
79 .sp
80 By default, if the 8-bit library is being built, the \fBconfigure\fP script
81 will search for a C++ compiler and C++ header files. If it finds them, it
82 automatically builds the C++ wrapper library (which supports only 8-bit
83 strings). You can disable this by adding
84 .sp
85 --disable-cpp
86 .sp
87 to the \fBconfigure\fP command.
88 .
89 .
90 .SH "UTF-8, UTF-16 AND UTF-32 SUPPORT"
91 .rs
92 .sp
93 To build PCRE with support for UTF Unicode character strings, add
94 .sp
95 --enable-utf
96 .sp
97 to the \fBconfigure\fP command. This setting applies to both libraries, adding
98 support for UTF-8 to the 8-bit library, support for UTF-16 to the 16-bit
99 library, and support for UTF-32 to the to the 32-bit library.
100 There are no separate options for enabling UTF-8, UTF-16 and UTF-32
101 independently because that would allow ridiculous settings such as requesting
102 UTF-16 support while building only the 8-bit library. It is not possible to
103 build one library with UTF support and the other without in the same
104 configuration. (For backwards compatibility, --enable-utf8 is a synonym of
105 --enable-utf.)
106 .P
107 Of itself, this setting does not make PCRE treat strings as UTF-8, UTF-16 or
108 UTF-32. As well as compiling PCRE with this option, you also have have to set
109 the PCRE_UTF8 or PCRE_UTF16 or PCRE_UTF32 option when you call one of the
110 pattern compiling functions.
111 .P
112 If you set --enable-utf when compiling in an EBCDIC environment, PCRE expects
113 its input to be either ASCII or UTF-8 (depending on the run-time option). It is
114 not possible to support both EBCDIC and UTF-8 codes in the same version of the
115 library. Consequently, --enable-utf and --enable-ebcdic are mutually
116 exclusive.
117 .
118 .
119 .SH "UNICODE CHARACTER PROPERTY SUPPORT"
120 .rs
121 .sp
122 UTF support allows the libraries to process character codepoints up to 0x10ffff
123 in the strings that they handle. On its own, however, it does not provide any
124 facilities for accessing the properties of such characters. If you want to be
125 able to use the pattern escapes \eP, \ep, and \eX, which refer to Unicode
126 character properties, you must add
127 .sp
128 --enable-unicode-properties
129 .sp
130 to the \fBconfigure\fP command. This implies UTF support, even if you have
131 not explicitly requested it.
132 .P
133 Including Unicode property support adds around 30K of tables to the PCRE
134 library. Only the general category properties such as \fILu\fP and \fINd\fP are
135 supported. Details are given in the
136 .\" HREF
137 \fBpcrepattern\fP
138 .\"
139 documentation.
140 .
141 .
142 .SH "JUST-IN-TIME COMPILER SUPPORT"
143 .rs
144 .sp
145 Just-in-time compiler support is included in the build by specifying
146 .sp
147 --enable-jit
148 .sp
149 This support is available only for certain hardware architectures. If this
150 option is set for an unsupported architecture, a compile time error occurs.
151 See the
152 .\" HREF
153 \fBpcrejit\fP
154 .\"
155 documentation for a discussion of JIT usage. When JIT support is enabled,
156 pcregrep automatically makes use of it, unless you add
157 .sp
158 --disable-pcregrep-jit
159 .sp
160 to the "configure" command.
161 .
162 .
163 .SH "CODE VALUE OF NEWLINE"
164 .rs
165 .sp
166 By default, PCRE interprets the linefeed (LF) character as indicating the end
167 of a line. This is the normal newline character on Unix-like systems. You can
168 compile PCRE to use carriage return (CR) instead, by adding
169 .sp
170 --enable-newline-is-cr
171 .sp
172 to the \fBconfigure\fP command. There is also a --enable-newline-is-lf option,
173 which explicitly specifies linefeed as the newline character.
174 .sp
175 Alternatively, you can specify that line endings are to be indicated by the two
176 character sequence CRLF. If you want this, add
177 .sp
178 --enable-newline-is-crlf
179 .sp
180 to the \fBconfigure\fP command. There is a fourth option, specified by
181 .sp
182 --enable-newline-is-anycrlf
183 .sp
184 which causes PCRE to recognize any of the three sequences CR, LF, or CRLF as
185 indicating a line ending. Finally, a fifth option, specified by
186 .sp
187 --enable-newline-is-any
188 .sp
189 causes PCRE to recognize any Unicode newline sequence.
190 .P
191 Whatever line ending convention is selected when PCRE is built can be
192 overridden when the library functions are called. At build time it is
193 conventional to use the standard for your operating system.
194 .
195 .
196 .SH "WHAT \eR MATCHES"
197 .rs
198 .sp
199 By default, the sequence \eR in a pattern matches any Unicode newline sequence,
200 whatever has been selected as the line ending sequence. If you specify
201 .sp
202 --enable-bsr-anycrlf
203 .sp
204 the default is changed so that \eR matches only CR, LF, or CRLF. Whatever is
205 selected when PCRE is built can be overridden when the library functions are
206 called.
207 .
208 .
209 .SH "POSIX MALLOC USAGE"
210 .rs
211 .sp
212 When the 8-bit library is called through the POSIX interface (see the
213 .\" HREF
214 \fBpcreposix\fP
215 .\"
216 documentation), additional working storage is required for holding the pointers
217 to capturing substrings, because PCRE requires three integers per substring,
218 whereas the POSIX interface provides only two. If the number of expected
219 substrings is small, the wrapper function uses space on the stack, because this
220 is faster than using \fBmalloc()\fP for each call. The default threshold above
221 which the stack is no longer used is 10; it can be changed by adding a setting
222 such as
223 .sp
224 --with-posix-malloc-threshold=20
225 .sp
226 to the \fBconfigure\fP command.
227 .
228 .
229 .SH "HANDLING VERY LARGE PATTERNS"
230 .rs
231 .sp
232 Within a compiled pattern, offset values are used to point from one part to
233 another (for example, from an opening parenthesis to an alternation
234 metacharacter). By default, two-byte values are used for these offsets, leading
235 to a maximum size for a compiled pattern of around 64K. This is sufficient to
236 handle all but the most gigantic patterns. Nevertheless, some people do want to
237 process truly enormous patterns, so it is possible to compile PCRE to use
238 three-byte or four-byte offsets by adding a setting such as
239 .sp
240 --with-link-size=3
241 .sp
242 to the \fBconfigure\fP command. The value given must be 2, 3, or 4. For the
243 16-bit and 32-bit library, a value of 3 is rounded up to 4. Using longer offsets
244 slows down the operation of PCRE because it has to load additional data when
245 handling them.
246 .
247 .
248 .SH "AVOIDING EXCESSIVE STACK USAGE"
249 .rs
250 .sp
251 When matching with the \fBpcre_exec()\fP function, PCRE implements backtracking
252 by making recursive calls to an internal function called \fBmatch()\fP. In
253 environments where the size of the stack is limited, this can severely limit
254 PCRE's operation. (The Unix environment does not usually suffer from this
255 problem, but it may sometimes be necessary to increase the maximum stack size.
256 There is a discussion in the
257 .\" HREF
258 \fBpcrestack\fP
259 .\"
260 documentation.) An alternative approach to recursion that uses memory from the
261 heap to remember data, instead of using recursive function calls, has been
262 implemented to work round the problem of limited stack size. If you want to
263 build a version of PCRE that works this way, add
264 .sp
265 --disable-stack-for-recursion
266 .sp
267 to the \fBconfigure\fP command. With this configuration, PCRE will use the
268 \fBpcre_stack_malloc\fP and \fBpcre_stack_free\fP variables to call memory
269 management functions. By default these point to \fBmalloc()\fP and
270 \fBfree()\fP, but you can replace the pointers so that your own functions are
271 used instead.
272 .P
273 Separate functions are provided rather than using \fBpcre_malloc\fP and
274 \fBpcre_free\fP because the usage is very predictable: the block sizes
275 requested are always the same, and the blocks are always freed in reverse
276 order. A calling program might be able to implement optimized functions that
277 perform better than \fBmalloc()\fP and \fBfree()\fP. PCRE runs noticeably more
278 slowly when built in this way. This option affects only the \fBpcre_exec()\fP
279 function; it is not relevant for \fBpcre_dfa_exec()\fP.
280 .
281 .
282 .SH "LIMITING PCRE RESOURCE USAGE"
283 .rs
284 .sp
285 Internally, PCRE has a function called \fBmatch()\fP, which it calls repeatedly
286 (sometimes recursively) when matching a pattern with the \fBpcre_exec()\fP
287 function. By controlling the maximum number of times this function may be
288 called during a single matching operation, a limit can be placed on the
289 resources used by a single call to \fBpcre_exec()\fP. The limit can be changed
290 at run time, as described in the
291 .\" HREF
292 \fBpcreapi\fP
293 .\"
294 documentation. The default is 10 million, but this can be changed by adding a
295 setting such as
296 .sp
297 --with-match-limit=500000
298 .sp
299 to the \fBconfigure\fP command. This setting has no effect on the
300 \fBpcre_dfa_exec()\fP matching function.
301 .P
302 In some environments it is desirable to limit the depth of recursive calls of
303 \fBmatch()\fP more strictly than the total number of calls, in order to
304 restrict the maximum amount of stack (or heap, if --disable-stack-for-recursion
305 is specified) that is used. A second limit controls this; it defaults to the
306 value that is set for --with-match-limit, which imposes no additional
307 constraints. However, you can set a lower limit by adding, for example,
308 .sp
309 --with-match-limit-recursion=10000
310 .sp
311 to the \fBconfigure\fP command. This value can also be overridden at run time.
312 .
313 .
314 .SH "CREATING CHARACTER TABLES AT BUILD TIME"
315 .rs
316 .sp
317 PCRE uses fixed tables for processing characters whose code values are less
318 than 256. By default, PCRE is built with a set of tables that are distributed
319 in the file \fIpcre_chartables.c.dist\fP. These tables are for ASCII codes
320 only. If you add
321 .sp
322 --enable-rebuild-chartables
323 .sp
324 to the \fBconfigure\fP command, the distributed tables are no longer used.
325 Instead, a program called \fBdftables\fP is compiled and run. This outputs the
326 source for new set of tables, created in the default locale of your C run-time
327 system. (This method of replacing the tables does not work if you are cross
328 compiling, because \fBdftables\fP is run on the local host. If you need to
329 create alternative tables when cross compiling, you will have to do so "by
330 hand".)
331 .
332 .
333 .SH "USING EBCDIC CODE"
334 .rs
335 .sp
336 PCRE assumes by default that it will run in an environment where the character
337 code is ASCII (or Unicode, which is a superset of ASCII). This is the case for
338 most computer operating systems. PCRE can, however, be compiled to run in an
339 EBCDIC environment by adding
340 .sp
341 --enable-ebcdic
342 .sp
343 to the \fBconfigure\fP command. This setting implies
344 --enable-rebuild-chartables. You should only use it if you know that you are in
345 an EBCDIC environment (for example, an IBM mainframe operating system). The
346 --enable-ebcdic option is incompatible with --enable-utf.
347 .P
348 The EBCDIC character that corresponds to an ASCII LF is assumed to have the
349 value 0x15 by default. However, in some EBCDIC environments, 0x25 is used. In
350 such an environment you should use
351 .sp
352 --enable-ebcdic-nl25
353 .sp
354 as well as, or instead of, --enable-ebcdic. The EBCDIC character for CR has the
355 same value as in ASCII, namely, 0x0d. Whichever of 0x15 and 0x25 is \fInot\fP
356 chosen as LF is made to correspond to the Unicode NEL character (which, in
357 Unicode, is 0x85).
358 .P
359 The options that select newline behaviour, such as --enable-newline-is-cr,
360 and equivalent run-time options, refer to these character values in an EBCDIC
361 environment.
362 .
363 .
364 .SH "PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT"
365 .rs
366 .sp
367 By default, \fBpcregrep\fP reads all files as plain text. You can build it so
368 that it recognizes files whose names end in \fB.gz\fP or \fB.bz2\fP, and reads
369 them with \fBlibz\fP or \fBlibbz2\fP, respectively, by adding one or both of
370 .sp
371 --enable-pcregrep-libz
372 --enable-pcregrep-libbz2
373 .sp
374 to the \fBconfigure\fP command. These options naturally require that the
375 relevant libraries are installed on your system. Configuration will fail if
376 they are not.
377 .
378 .
379 .SH "PCREGREP BUFFER SIZE"
380 .rs
381 .sp
382 \fBpcregrep\fP uses an internal buffer to hold a "window" on the file it is
383 scanning, in order to be able to output "before" and "after" lines when it
384 finds a match. The size of the buffer is controlled by a parameter whose
385 default value is 20K. The buffer itself is three times this size, but because
386 of the way it is used for holding "before" lines, the longest line that is
387 guaranteed to be processable is the parameter size. You can change the default
388 parameter value by adding, for example,
389 .sp
390 --with-pcregrep-bufsize=50K
391 .sp
392 to the \fBconfigure\fP command. The caller of \fPpcregrep\fP can, however,
393 override this value by specifying a run-time option.
394 .
395 .
396 .SH "PCRETEST OPTION FOR LIBREADLINE SUPPORT"
397 .rs
398 .sp
399 If you add
400 .sp
401 --enable-pcretest-libreadline
402 .sp
403 to the \fBconfigure\fP command, \fBpcretest\fP is linked with the
404 \fBlibreadline\fP library, and when its input is from a terminal, it reads it
405 using the \fBreadline()\fP function. This provides line-editing and history
406 facilities. Note that \fBlibreadline\fP is GPL-licensed, so if you distribute a
407 binary of \fBpcretest\fP linked in this way, there may be licensing issues.
408 .P
409 Setting this option causes the \fB-lreadline\fP option to be added to the
410 \fBpcretest\fP build. In many operating environments with a sytem-installed
411 \fBlibreadline\fP this is sufficient. However, in some environments (e.g.
412 if an unmodified distribution version of readline is in use), some extra
413 configuration may be necessary. The INSTALL file for \fBlibreadline\fP says
414 this:
415 .sp
416 "Readline uses the termcap functions, but does not link with the
417 termcap or curses library itself, allowing applications which link
418 with readline the to choose an appropriate library."
419 .sp
420 If your environment has not been set up so that an appropriate library is
421 automatically included, you may need to add something like
422 .sp
423 LIBS="-ncurses"
424 .sp
425 immediately before the \fBconfigure\fP command.
426 .
427 .
428 .SH "DEBUGGING WITH VALGRIND SUPPORT"
429 .rs
430 .sp
431 By adding the
432 .sp
433 --enable-valgrind
434 .sp
435 option to to the \fBconfigure\fP command, PCRE will use valgrind annotations
436 to mark certain memory regions as unaddressable. This allows it to detect
437 invalid memory accesses, and is mostly useful for debugging PCRE itself.
438 .
439 .
440 .SH "CODE COVERAGE REPORTING"
441 .rs
442 .sp
443 The build process can generate a code coverage report for the test suite.
444 To enable this, you must install \fBlcov\fP version 1.6 or above. Then use
445 .sp
446 --enable-coverage
447 .sp
448 to the \fBconfigure\fP command, and generate the report by running
449 .sp
450 make coverage
451 .sp
452 Note that using \fBccache\fP (a caching C compiler) is incompatible with code
453 coverage reporting. If you have configured \fBccache\fP to run automatically
454 on your system you must set the environment variable
455 .sp
456 CCACHE_DISABLE=1
457 .sp
458 before running make to build PCRE, so that \fBccache\fP is not used.
459 .
460 .
461 .SH "SEE ALSO"
462 .rs
463 .sp
464 \fBpcreapi\fP(3), \fBpcre16\fP, \fBpcre32\fP, \fBpcre_config\fP(3).
465 .
466 .
467 .SH AUTHOR
468 .rs
469 .sp
470 .nf
471 Philip Hazel
472 University Computing Service
473 Cambridge CB2 3QH, England.
474 .fi
475 .
476 .
477 .SH REVISION
478 .rs
479 .sp
480 .nf
481 Last updated: 27 October 2012
482 Copyright (c) 1997-2012 University of Cambridge.
483 .fi

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.5