pcrebuild man page
Return to the 
index.htmlPCRE index page .
This page is part of the PCRE HTML documentation. It was generated automatically
from the original man page. If there is any nonsense in it, please consult the
man page, in case the conversion went wrong.
#SEC1PCRE BUILD-TIME OPTIONS #SEC2C++ SUPPORT #SEC3UTF-8 SUPPORT #SEC4UNICODE CHARACTER PROPERTY SUPPORT #SEC5CODE VALUE OF NEWLINE #SEC6BUILDING SHARED AND STATIC LIBRARIES #SEC7POSIX MALLOC USAGE #SEC8LIMITING PCRE RESOURCE USAGE #SEC9HANDLING VERY LARGE PATTERNS #SEC10AVOIDING EXCESSIVE STACK USAGE #SEC11USING EBCDIC CODE #TOC1PCRE BUILD-TIME OPTIONS This document describes the optional features of PCRE that can be selected when
the library is compiled. They are all selected, or deselected, by providing
options to the 
configure script that is run before the makecommand. The complete list of options for 
configure (which includes the
standard ones such as the selection of the installation directory) can be
obtained by running
  ./configure --help
The following sections describe certain options whose names begin with --enable
or --disable. These settings specify changes to the defaults for the
configure command. Because of the way that configure works,
--enable and --disable always come in pairs, so the complementary option always
exists as well, but as it specifies the default, it is not described.
#TOC1C++ SUPPORT By default, the 
configure script will search for a C++ compiler and C++
header files. If it finds them, it automatically builds the C++ wrapper library
for PCRE. You can disable this by adding
  --disable-cpp
to the 
configure command.
#TOC1UTF-8 SUPPORT To build PCRE with support for UTF-8 character strings, add
  --enable-utf8
to the 
configure command. Of itself, this does not make PCRE treat
strings as UTF-8. As well as compiling PCRE with this option, you also have
have to set the PCRE_UTF8 option when you call the 
pcre_compile()function.
#TOC1UNICODE CHARACTER PROPERTY SUPPORT UTF-8 support allows PCRE to process character values greater than 255 in the
strings that it handles. On its own, however, it does not provide any
facilities for accessing the properties of such characters. If you want to be
able to use the pattern escapes \P, \p, and \X, which refer to Unicode
character properties, you must add
  --enable-unicode-properties
to the 
configure command. This implies UTF-8 support, even if you have
not explicitly requested it.
Including Unicode property support adds around 90K of tables to the PCRE
library, approximately doubling its size. Only the general category properties
such as 
Lu and Nd are supported. Details are given in the
pcrepattern.htmlpcrepattern documentation.
#TOC1CODE VALUE OF NEWLINE By default, PCRE treats character 10 (linefeed) as the newline character. This
is the normal newline character on Unix-like systems. You can compile PCRE to
use character 13 (carriage return) instead by adding
  --enable-newline-is-cr
to the 
configure command. For completeness there is also a
--enable-newline-is-lf option, which explicitly specifies linefeed as the
newline character.
#TOC1BUILDING SHARED AND STATIC LIBRARIES The PCRE building process uses 
libtool to build both shared and static
Unix libraries by default. You can suppress one of these by adding one of
  --disable-shared
  --disable-static
to the 
configure command, as required.
#TOC1POSIX MALLOC USAGE When PCRE is called through the POSIX interface (see the
pcreposix.htmlpcreposix documentation), additional working storage is required for holding the pointers
to capturing substrings, because PCRE requires three integers per substring,
whereas the POSIX interface provides only two. If the number of expected
substrings is small, the wrapper function uses space on the stack, because this
is faster than using 
malloc() for each call. The default threshold above
which the stack is no longer used is 10; it can be changed by adding a setting
such as
  --with-posix-malloc-threshold=20
to the 
configure command.
#TOC1LIMITING PCRE RESOURCE USAGE Internally, PCRE has a function called 
match(), which it calls repeatedly
(possibly recursively) when matching a pattern with the 
pcre_exec()function. By controlling the maximum number of times this function may be
called during a single matching operation, a limit can be placed on the
resources used by a single call to 
pcre_exec(). The limit can be changed
at run time, as described in the
pcreapi.htmlpcreapi documentation. The default is 10 million, but this can be changed by adding a
setting such as
  --with-match-limit=500000
to the 
configure command. This setting has no effect on the
pcre_dfa_exec() matching function.
#TOC1HANDLING VERY LARGE PATTERNS Within a compiled pattern, offset values are used to point from one part to
another (for example, from an opening parenthesis to an alternation
metacharacter). By default, two-byte values are used for these offsets, leading
to a maximum size for a compiled pattern of around 64K. This is sufficient to
handle all but the most gigantic patterns. Nevertheless, some people do want to
process enormous patterns, so it is possible to compile PCRE to use three-byte
or four-byte offsets by adding a setting such as
  --with-link-size=3
to the 
configure command. The value given must be 2, 3, or 4. Using
longer offsets slows down the operation of PCRE because it has to load
additional bytes when handling them.
If you build PCRE with an increased link size, test 2 (and test 5 if you are
using UTF-8) will fail. Part of the output of these tests is a representation
of the compiled pattern, and this changes with the link size.
#TOC1AVOIDING EXCESSIVE STACK USAGE When matching with the 
pcre_exec() function, PCRE implements backtracking
by making recursive calls to an internal function called 
match(). In
environments where the size of the stack is limited, this can severely limit
PCRE's operation. (The Unix environment does not usually suffer from this
problem.) An alternative approach that uses memory from the heap to remember
data, instead of using recursive function calls, has been implemented to work
round this problem. If you want to build a version of PCRE that works this way,
add
  --disable-stack-for-recursion
to the 
configure command. With this configuration, PCRE will use the
pcre_stack_malloc and pcre_stack_free variables to call memory
management functions. Separate functions are provided because the usage is very
predictable: the block sizes requested are always the same, and the blocks are
always freed in reverse order. A calling program might be able to implement
optimized functions that perform better than the standard 
malloc() and
free() functions. PCRE runs noticeably more slowly when built in this
way. This option affects only the 
pcre_exec() function; it is not
relevant for the the 
pcre_dfa_exec() function.
#TOC1USING EBCDIC CODE PCRE assumes by default that it will run in an environment where the character
code is ASCII (or Unicode, which is a superset of ASCII). PCRE can, however, be
compiled to run in an EBCDIC environment by adding
  --enable-ebcdic
to the 
configure command.
Last updated: 15 August 2005
Copyright © 1997-2005 University of Cambridge.
Return to the 
index.htmlPCRE index page .
