Annotation of embedaddon/pcre/doc/pcrebuild.3, revision 1.1.1.1
1.1 misho 1: .TH PCREBUILD 3
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 in non-Unix-like
18: environments in the file called \fINON_UNIX_USE\fP, which is part of the PCRE
19: distribution. You should consult this file as well as the \fIREADME\fP file if
20: you are building in a non-Unix-like environment.
21: .P
22: The complete list of options for \fBconfigure\fP (which includes the standard
23: ones such as the selection of the installation directory) can be obtained by
24: running
25: .sp
26: ./configure --help
27: .sp
28: The following sections include descriptions of options whose names begin with
29: --enable or --disable. These settings specify changes to the defaults for the
30: \fBconfigure\fP command. Because of the way that \fBconfigure\fP works,
31: --enable and --disable always come in pairs, so the complementary option always
32: exists as well, but as it specifies the default, it is not described.
33: .
34: .
35: .SH "BUILDING SHARED AND STATIC LIBRARIES"
36: .rs
37: .sp
38: The PCRE building process uses \fBlibtool\fP to build both shared and static
39: Unix libraries by default. You can suppress one of these by adding one of
40: .sp
41: --disable-shared
42: --disable-static
43: .sp
44: to the \fBconfigure\fP command, as required.
45: .
46: .
47: .SH "C++ SUPPORT"
48: .rs
49: .sp
50: By default, the \fBconfigure\fP script will search for a C++ compiler and C++
51: header files. If it finds them, it automatically builds the C++ wrapper library
52: for PCRE. You can disable this by adding
53: .sp
54: --disable-cpp
55: .sp
56: to the \fBconfigure\fP command.
57: .
58: .
59: .SH "UTF-8 SUPPORT"
60: .rs
61: .sp
62: To build PCRE with support for UTF-8 Unicode character strings, add
63: .sp
64: --enable-utf8
65: .sp
66: to the \fBconfigure\fP command. Of itself, this does not make PCRE treat
67: strings as UTF-8. As well as compiling PCRE with this option, you also have
68: have to set the PCRE_UTF8 option when you call the \fBpcre_compile()\fP
69: or \fBpcre_compile2()\fP functions.
70: .P
71: If you set --enable-utf8 when compiling in an EBCDIC environment, PCRE expects
72: its input to be either ASCII or UTF-8 (depending on the runtime option). It is
73: not possible to support both EBCDIC and UTF-8 codes in the same version of the
74: library. Consequently, --enable-utf8 and --enable-ebcdic are mutually
75: exclusive.
76: .
77: .
78: .SH "UNICODE CHARACTER PROPERTY SUPPORT"
79: .rs
80: .sp
81: UTF-8 support allows PCRE to process character values greater than 255 in the
82: strings that it handles. On its own, however, it does not provide any
83: facilities for accessing the properties of such characters. If you want to be
84: able to use the pattern escapes \eP, \ep, and \eX, which refer to Unicode
85: character properties, you must add
86: .sp
87: --enable-unicode-properties
88: .sp
89: to the \fBconfigure\fP command. This implies UTF-8 support, even if you have
90: not explicitly requested it.
91: .P
92: Including Unicode property support adds around 30K of tables to the PCRE
93: library. Only the general category properties such as \fILu\fP and \fINd\fP are
94: supported. Details are given in the
95: .\" HREF
96: \fBpcrepattern\fP
97: .\"
98: documentation.
99: .
100: .
101: .SH "JUST-IN-TIME COMPILER SUPPORT"
102: .rs
103: .sp
104: Just-in-time compiler support is included in the build by specifying
105: .sp
106: --enable-jit
107: .sp
108: This support is available only for certain hardware architectures. If this
109: option is set for an unsupported architecture, a compile time error occurs.
110: See the
111: .\" HREF
112: \fBpcrejit\fP
113: .\"
114: documentation for a discussion of JIT usage. When JIT support is enabled,
115: pcregrep automatically makes use of it, unless you add
116: .sp
117: --disable-pcregrep-jit
118: .sp
119: to the "configure" command.
120: .
121: .
122: .SH "CODE VALUE OF NEWLINE"
123: .rs
124: .sp
125: By default, PCRE interprets the linefeed (LF) character as indicating the end
126: of a line. This is the normal newline character on Unix-like systems. You can
127: compile PCRE to use carriage return (CR) instead, by adding
128: .sp
129: --enable-newline-is-cr
130: .sp
131: to the \fBconfigure\fP command. There is also a --enable-newline-is-lf option,
132: which explicitly specifies linefeed as the newline character.
133: .sp
134: Alternatively, you can specify that line endings are to be indicated by the two
135: character sequence CRLF. If you want this, add
136: .sp
137: --enable-newline-is-crlf
138: .sp
139: to the \fBconfigure\fP command. There is a fourth option, specified by
140: .sp
141: --enable-newline-is-anycrlf
142: .sp
143: which causes PCRE to recognize any of the three sequences CR, LF, or CRLF as
144: indicating a line ending. Finally, a fifth option, specified by
145: .sp
146: --enable-newline-is-any
147: .sp
148: causes PCRE to recognize any Unicode newline sequence.
149: .P
150: Whatever line ending convention is selected when PCRE is built can be
151: overridden when the library functions are called. At build time it is
152: conventional to use the standard for your operating system.
153: .
154: .
155: .SH "WHAT \eR MATCHES"
156: .rs
157: .sp
158: By default, the sequence \eR in a pattern matches any Unicode newline sequence,
159: whatever has been selected as the line ending sequence. If you specify
160: .sp
161: --enable-bsr-anycrlf
162: .sp
163: the default is changed so that \eR matches only CR, LF, or CRLF. Whatever is
164: selected when PCRE is built can be overridden when the library functions are
165: called.
166: .
167: .
168: .SH "POSIX MALLOC USAGE"
169: .rs
170: .sp
171: When PCRE is called through the POSIX interface (see the
172: .\" HREF
173: \fBpcreposix\fP
174: .\"
175: documentation), additional working storage is required for holding the pointers
176: to capturing substrings, because PCRE requires three integers per substring,
177: whereas the POSIX interface provides only two. If the number of expected
178: substrings is small, the wrapper function uses space on the stack, because this
179: is faster than using \fBmalloc()\fP for each call. The default threshold above
180: which the stack is no longer used is 10; it can be changed by adding a setting
181: such as
182: .sp
183: --with-posix-malloc-threshold=20
184: .sp
185: to the \fBconfigure\fP command.
186: .
187: .
188: .SH "HANDLING VERY LARGE PATTERNS"
189: .rs
190: .sp
191: Within a compiled pattern, offset values are used to point from one part to
192: another (for example, from an opening parenthesis to an alternation
193: metacharacter). By default, two-byte values are used for these offsets, leading
194: to a maximum size for a compiled pattern of around 64K. This is sufficient to
195: handle all but the most gigantic patterns. Nevertheless, some people do want to
196: process truyl enormous patterns, so it is possible to compile PCRE to use
197: three-byte or four-byte offsets by adding a setting such as
198: .sp
199: --with-link-size=3
200: .sp
201: to the \fBconfigure\fP command. The value given must be 2, 3, or 4. Using
202: longer offsets slows down the operation of PCRE because it has to load
203: additional bytes when handling them.
204: .
205: .
206: .SH "AVOIDING EXCESSIVE STACK USAGE"
207: .rs
208: .sp
209: When matching with the \fBpcre_exec()\fP function, PCRE implements backtracking
210: by making recursive calls to an internal function called \fBmatch()\fP. In
211: environments where the size of the stack is limited, this can severely limit
212: PCRE's operation. (The Unix environment does not usually suffer from this
213: problem, but it may sometimes be necessary to increase the maximum stack size.
214: There is a discussion in the
215: .\" HREF
216: \fBpcrestack\fP
217: .\"
218: documentation.) An alternative approach to recursion that uses memory from the
219: heap to remember data, instead of using recursive function calls, has been
220: implemented to work round the problem of limited stack size. If you want to
221: build a version of PCRE that works this way, add
222: .sp
223: --disable-stack-for-recursion
224: .sp
225: to the \fBconfigure\fP command. With this configuration, PCRE will use the
226: \fBpcre_stack_malloc\fP and \fBpcre_stack_free\fP variables to call memory
227: management functions. By default these point to \fBmalloc()\fP and
228: \fBfree()\fP, but you can replace the pointers so that your own functions are
229: used instead.
230: .P
231: Separate functions are provided rather than using \fBpcre_malloc\fP and
232: \fBpcre_free\fP because the usage is very predictable: the block sizes
233: requested are always the same, and the blocks are always freed in reverse
234: order. A calling program might be able to implement optimized functions that
235: perform better than \fBmalloc()\fP and \fBfree()\fP. PCRE runs noticeably more
236: slowly when built in this way. This option affects only the \fBpcre_exec()\fP
237: function; it is not relevant for \fBpcre_dfa_exec()\fP.
238: .
239: .
240: .SH "LIMITING PCRE RESOURCE USAGE"
241: .rs
242: .sp
243: Internally, PCRE has a function called \fBmatch()\fP, which it calls repeatedly
244: (sometimes recursively) when matching a pattern with the \fBpcre_exec()\fP
245: function. By controlling the maximum number of times this function may be
246: called during a single matching operation, a limit can be placed on the
247: resources used by a single call to \fBpcre_exec()\fP. The limit can be changed
248: at run time, as described in the
249: .\" HREF
250: \fBpcreapi\fP
251: .\"
252: documentation. The default is 10 million, but this can be changed by adding a
253: setting such as
254: .sp
255: --with-match-limit=500000
256: .sp
257: to the \fBconfigure\fP command. This setting has no effect on the
258: \fBpcre_dfa_exec()\fP matching function.
259: .P
260: In some environments it is desirable to limit the depth of recursive calls of
261: \fBmatch()\fP more strictly than the total number of calls, in order to
262: restrict the maximum amount of stack (or heap, if --disable-stack-for-recursion
263: is specified) that is used. A second limit controls this; it defaults to the
264: value that is set for --with-match-limit, which imposes no additional
265: constraints. However, you can set a lower limit by adding, for example,
266: .sp
267: --with-match-limit-recursion=10000
268: .sp
269: to the \fBconfigure\fP command. This value can also be overridden at run time.
270: .
271: .
272: .SH "CREATING CHARACTER TABLES AT BUILD TIME"
273: .rs
274: .sp
275: PCRE uses fixed tables for processing characters whose code values are less
276: than 256. By default, PCRE is built with a set of tables that are distributed
277: in the file \fIpcre_chartables.c.dist\fP. These tables are for ASCII codes
278: only. If you add
279: .sp
280: --enable-rebuild-chartables
281: .sp
282: to the \fBconfigure\fP command, the distributed tables are no longer used.
283: Instead, a program called \fBdftables\fP is compiled and run. This outputs the
284: source for new set of tables, created in the default locale of your C runtime
285: system. (This method of replacing the tables does not work if you are cross
286: compiling, because \fBdftables\fP is run on the local host. If you need to
287: create alternative tables when cross compiling, you will have to do so "by
288: hand".)
289: .
290: .
291: .SH "USING EBCDIC CODE"
292: .rs
293: .sp
294: PCRE assumes by default that it will run in an environment where the character
295: code is ASCII (or Unicode, which is a superset of ASCII). This is the case for
296: most computer operating systems. PCRE can, however, be compiled to run in an
297: EBCDIC environment by adding
298: .sp
299: --enable-ebcdic
300: .sp
301: to the \fBconfigure\fP command. This setting implies
302: --enable-rebuild-chartables. You should only use it if you know that you are in
303: an EBCDIC environment (for example, an IBM mainframe operating system). The
304: --enable-ebcdic option is incompatible with --enable-utf8.
305: .
306: .
307: .SH "PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT"
308: .rs
309: .sp
310: By default, \fBpcregrep\fP reads all files as plain text. You can build it so
311: that it recognizes files whose names end in \fB.gz\fP or \fB.bz2\fP, and reads
312: them with \fBlibz\fP or \fBlibbz2\fP, respectively, by adding one or both of
313: .sp
314: --enable-pcregrep-libz
315: --enable-pcregrep-libbz2
316: .sp
317: to the \fBconfigure\fP command. These options naturally require that the
318: relevant libraries are installed on your system. Configuration will fail if
319: they are not.
320: .
321: .
322: .SH "PCREGREP BUFFER SIZE"
323: .rs
324: .sp
325: \fBpcregrep\fP uses an internal buffer to hold a "window" on the file it is
326: scanning, in order to be able to output "before" and "after" lines when it
327: finds a match. The size of the buffer is controlled by a parameter whose
328: default value is 20K. The buffer itself is three times this size, but because
329: of the way it is used for holding "before" lines, the longest line that is
330: guaranteed to be processable is the parameter size. You can change the default
331: parameter value by adding, for example,
332: .sp
333: --with-pcregrep-bufsize=50K
334: .sp
335: to the \fBconfigure\fP command. The caller of \fPpcregrep\fP can, however,
336: override this value by specifying a run-time option.
337: .
338: .
339: .SH "PCRETEST OPTION FOR LIBREADLINE SUPPORT"
340: .rs
341: .sp
342: If you add
343: .sp
344: --enable-pcretest-libreadline
345: .sp
346: to the \fBconfigure\fP command, \fBpcretest\fP is linked with the
347: \fBlibreadline\fP library, and when its input is from a terminal, it reads it
348: using the \fBreadline()\fP function. This provides line-editing and history
349: facilities. Note that \fBlibreadline\fP is GPL-licensed, so if you distribute a
350: binary of \fBpcretest\fP linked in this way, there may be licensing issues.
351: .P
352: Setting this option causes the \fB-lreadline\fP option to be added to the
353: \fBpcretest\fP build. In many operating environments with a sytem-installed
354: \fBlibreadline\fP this is sufficient. However, in some environments (e.g.
355: if an unmodified distribution version of readline is in use), some extra
356: configuration may be necessary. The INSTALL file for \fBlibreadline\fP says
357: this:
358: .sp
359: "Readline uses the termcap functions, but does not link with the
360: termcap or curses library itself, allowing applications which link
361: with readline the to choose an appropriate library."
362: .sp
363: If your environment has not been set up so that an appropriate library is
364: automatically included, you may need to add something like
365: .sp
366: LIBS="-ncurses"
367: .sp
368: immediately before the \fBconfigure\fP command.
369: .
370: .
371: .SH "SEE ALSO"
372: .rs
373: .sp
374: \fBpcreapi\fP(3), \fBpcre_config\fP(3).
375: .
376: .
377: .SH AUTHOR
378: .rs
379: .sp
380: .nf
381: Philip Hazel
382: University Computing Service
383: Cambridge CB2 3QH, England.
384: .fi
385: .
386: .
387: .SH REVISION
388: .rs
389: .sp
390: .nf
391: Last updated: 06 September 2011
392: Copyright (c) 1997-2011 University of Cambridge.
393: .fi
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to pcrebuild.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pcre / doc