Annotation of embedaddon/pcre/doc/pcrebuild.3, revision 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