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