1PCREBUILD(3)               Library Functions Manual               PCREBUILD(3)
2
3
4

NAME

6       PCRE - Perl-compatible regular expressions
7

PCRE BUILD-TIME OPTIONS

9
10       This  document  describes  the  optional  features  of PCRE that can be
11       selected when the library is compiled. It assumes use of the  configure
12       script,  where the optional features are selected or deselected by pro‐
13       viding options to configure before running the make  command.  However,
14       the  same  options  can be selected in both Unix-like and non-Unix-like
15       environments using the GUI facility of cmake-gui if you are using CMake
16       instead of configure to build PCRE.
17
18       There  is  a  lot more information about building PCRE in non-Unix-like
19       environments in the file called NON_UNIX_USE, which is part of the PCRE
20       distribution.  You  should consult this file as well as the README file
21       if you are building in a non-Unix-like environment.
22
23       The complete list of options for configure (which includes the standard
24       ones  such  as  the  selection  of  the  installation directory) can be
25       obtained by running
26
27         ./configure --help
28
29       The following sections include  descriptions  of  options  whose  names
30       begin with --enable or --disable. These settings specify changes to the
31       defaults for the configure command. Because of the way  that  configure
32       works,  --enable  and --disable always come in pairs, so the complemen‐
33       tary option always exists as well, but as it specifies the default,  it
34       is not described.
35

C++ SUPPORT

37
38       By default, the configure script will search for a C++ compiler and C++
39       header files. If it finds them, it automatically builds the C++ wrapper
40       library for PCRE. You can disable this by adding
41
42         --disable-cpp
43
44       to the configure command.
45

UTF-8 SUPPORT

47
48       To build PCRE with support for UTF-8 Unicode character strings, add
49
50         --enable-utf8
51
52       to  the  configure  command.  Of  itself, this does not make PCRE treat
53       strings as UTF-8. As well as compiling PCRE with this option, you  also
54       have  have to set the PCRE_UTF8 option when you call the pcre_compile()
55       or pcre_compile2() functions.
56
57       If you set --enable-utf8 when compiling in an EBCDIC environment,  PCRE
58       expects its input to be either ASCII or UTF-8 (depending on the runtime
59       option). It is not possible to support both EBCDIC and UTF-8  codes  in
60       the  same  version  of  the  library.  Consequently,  --enable-utf8 and
61       --enable-ebcdic are mutually exclusive.
62

UNICODE CHARACTER PROPERTY SUPPORT

64
65       UTF-8 support allows PCRE to process character values greater than  255
66       in  the  strings that it handles. On its own, however, it does not pro‐
67       vide any facilities for accessing the properties of such characters. If
68       you  want  to  be able to use the pattern escapes \P, \p, and \X, which
69       refer to Unicode character properties, you must add
70
71         --enable-unicode-properties
72
73       to the configure command. This implies UTF-8 support, even if you  have
74       not explicitly requested it.
75
76       Including  Unicode  property  support  adds around 30K of tables to the
77       PCRE library. Only the general category properties such as  Lu  and  Nd
78       are supported. Details are given in the pcrepattern documentation.
79

CODE VALUE OF NEWLINE

81
82       By  default,  PCRE interprets the linefeed (LF) character as indicating
83       the end of a line. This is the normal newline  character  on  Unix-like
84       systems.  You  can compile PCRE to use carriage return (CR) instead, by
85       adding
86
87         --enable-newline-is-cr
88
89       to the  configure  command.  There  is  also  a  --enable-newline-is-lf
90       option, which explicitly specifies linefeed as the newline character.
91
92       Alternatively, you can specify that line endings are to be indicated by
93       the two character sequence CRLF. If you want this, add
94
95         --enable-newline-is-crlf
96
97       to the configure command. There is a fourth option, specified by
98
99         --enable-newline-is-anycrlf
100
101       which causes PCRE to recognize any of the three sequences  CR,  LF,  or
102       CRLF as indicating a line ending. Finally, a fifth option, specified by
103
104         --enable-newline-is-any
105
106       causes PCRE to recognize any Unicode newline sequence.
107
108       Whatever  line  ending convention is selected when PCRE is built can be
109       overridden when the library functions are called. At build time  it  is
110       conventional to use the standard for your operating system.
111

WHAT \R MATCHES

113
114       By  default,  the  sequence \R in a pattern matches any Unicode newline
115       sequence, whatever has been selected as the line  ending  sequence.  If
116       you specify
117
118         --enable-bsr-anycrlf
119
120       the  default  is changed so that \R matches only CR, LF, or CRLF. What‐
121       ever is selected when PCRE is built can be overridden when the  library
122       functions are called.
123

BUILDING SHARED AND STATIC LIBRARIES

125
126       The  PCRE building process uses libtool to build both shared and static
127       Unix libraries by default. You can suppress one of these by adding  one
128       of
129
130         --disable-shared
131         --disable-static
132
133       to the configure command, as required.
134

POSIX MALLOC USAGE

136
137       When PCRE is called through the POSIX interface (see the pcreposix doc‐
138       umentation), additional working storage is  required  for  holding  the
139       pointers  to capturing substrings, because PCRE requires three integers
140       per substring, whereas the POSIX interface provides only  two.  If  the
141       number of expected substrings is small, the wrapper function uses space
142       on the stack, because this is faster than using malloc() for each call.
143       The default threshold above which the stack is no longer used is 10; it
144       can be changed by adding a setting such as
145
146         --with-posix-malloc-threshold=20
147
148       to the configure command.
149

HANDLING VERY LARGE PATTERNS

151
152       Within a compiled pattern, offset values are used  to  point  from  one
153       part  to another (for example, from an opening parenthesis to an alter‐
154       nation metacharacter). By default, two-byte values are used  for  these
155       offsets,  leading  to  a  maximum size for a compiled pattern of around
156       64K. This is sufficient to handle all but the most  gigantic  patterns.
157       Nevertheless,  some  people do want to process truyl enormous patterns,
158       so it is possible to compile PCRE to use three-byte or  four-byte  off‐
159       sets by adding a setting such as
160
161         --with-link-size=3
162
163       to  the  configure  command.  The value given must be 2, 3, or 4. Using
164       longer offsets slows down the operation of PCRE because it has to  load
165       additional bytes when handling them.
166

AVOIDING EXCESSIVE STACK USAGE

168
169       When matching with the pcre_exec() function, PCRE implements backtrack‐
170       ing by making recursive calls to an internal function  called  match().
171       In  environments  where  the size of the stack is limited, this can se‐
172       verely limit PCRE's operation. (The Unix environment does  not  usually
173       suffer from this problem, but it may sometimes be necessary to increase
174       the maximum stack size.  There is a discussion in the  pcrestack  docu‐
175       mentation.)  An alternative approach to recursion that uses memory from
176       the heap to remember data, instead of using recursive  function  calls,
177       has  been  implemented to work round the problem of limited stack size.
178       If you want to build a version of PCRE that works this way, add
179
180         --disable-stack-for-recursion
181
182       to the configure command. With this configuration, PCRE  will  use  the
183       pcre_stack_malloc  and pcre_stack_free variables to call memory manage‐
184       ment functions. By default these point to malloc() and free(), but  you
185       can replace the pointers so that your own functions are used instead.
186
187       Separate  functions  are  provided  rather  than  using pcre_malloc and
188       pcre_free because the  usage  is  very  predictable:  the  block  sizes
189       requested  are  always  the  same,  and  the blocks are always freed in
190       reverse order. A calling program might be able to  implement  optimized
191       functions  that  perform  better  than  malloc()  and free(). PCRE runs
192       noticeably more slowly when built in this way. This option affects only
193       the pcre_exec() function; it is not relevant for pcre_dfa_exec().
194

LIMITING PCRE RESOURCE USAGE

196
197       Internally,  PCRE has a function called match(), which it calls repeat‐
198       edly  (sometimes  recursively)  when  matching  a  pattern   with   the
199       pcre_exec()  function.  By controlling the maximum number of times this
200       function may be called during a single matching operation, a limit  can
201       be  placed  on  the resources used by a single call to pcre_exec(). The
202       limit can be changed at run time, as described in the pcreapi  documen‐
203       tation.  The default is 10 million, but this can be changed by adding a
204       setting such as
205
206         --with-match-limit=500000
207
208       to  the  configure  command.  This  setting  has  no  effect   on   the
209       pcre_dfa_exec() matching function.
210
211       In  some  environments  it is desirable to limit the depth of recursive
212       calls of match() more strictly than the total number of calls, in order
213       to  restrict  the maximum amount of stack (or heap, if --disable-stack-
214       for-recursion is specified) that is used. A second limit controls this;
215       it  defaults  to  the  value  that is set for --with-match-limit, which
216       imposes no additional constraints. However, you can set a  lower  limit
217       by adding, for example,
218
219         --with-match-limit-recursion=10000
220
221       to  the  configure  command.  This  value can also be overridden at run
222       time.
223

CREATING CHARACTER TABLES AT BUILD TIME

225
226       PCRE uses fixed tables for processing characters whose code values  are
227       less  than 256. By default, PCRE is built with a set of tables that are
228       distributed in the file pcre_chartables.c.dist. These  tables  are  for
229       ASCII codes only. If you add
230
231         --enable-rebuild-chartables
232
233       to  the  configure  command, the distributed tables are no longer used.
234       Instead, a program called dftables is compiled and  run.  This  outputs
235       the source for new set of tables, created in the default locale of your
236       C runtime system. (This method of replacing the tables does not work if
237       you  are cross compiling, because dftables is run on the local host. If
238       you need to create alternative tables when cross  compiling,  you  will
239       have to do so "by hand".)
240

USING EBCDIC CODE

242
243       PCRE  assumes  by  default that it will run in an environment where the
244       character code is ASCII (or Unicode, which is  a  superset  of  ASCII).
245       This  is  the  case for most computer operating systems. PCRE can, how‐
246       ever, be compiled to run in an EBCDIC environment by adding
247
248         --enable-ebcdic
249
250       to the configure command. This setting implies --enable-rebuild-charta‐
251       bles.  You  should  only  use  it if you know that you are in an EBCDIC
252       environment (for example,  an  IBM  mainframe  operating  system).  The
253       --enable-ebcdic option is incompatible with --enable-utf8.
254

PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT

256
257       By default, pcregrep reads all files as plain text. You can build it so
258       that it recognizes files whose names end in .gz or .bz2, and reads them
259       with libz or libbz2, respectively, by adding one or both of
260
261         --enable-pcregrep-libz
262         --enable-pcregrep-libbz2
263
264       to the configure command. These options naturally require that the rel‐
265       evant libraries are installed on your system. Configuration  will  fail
266       if they are not.
267

PCRETEST OPTION FOR LIBREADLINE SUPPORT

269
270       If you add
271
272         --enable-pcretest-libreadline
273
274       to  the  configure  command,  pcretest  is  linked with the libreadline
275       library, and when its input is from a terminal, it reads it  using  the
276       readline() function. This provides line-editing and history facilities.
277       Note that libreadline is GPL-licensed, so if you distribute a binary of
278       pcretest linked in this way, there may be licensing issues.
279
280       Setting  this  option  causes  the -lreadline option to be added to the
281       pcretest build. In many operating environments with  a  sytem-installed
282       libreadline this is sufficient. However, in some environments (e.g.  if
283       an unmodified distribution version of readline is in use),  some  extra
284       configuration  may  be necessary. The INSTALL file for libreadline says
285       this:
286
287         "Readline uses the termcap functions, but does not link with the
288         termcap or curses library itself, allowing applications which link
289         with readline the to choose an appropriate library."
290
291       If your environment has not been set up so that an appropriate  library
292       is automatically included, you may need to add something like
293
294         LIBS="-ncurses"
295
296       immediately before the configure command.
297

SEE ALSO

299
300       pcreapi(3), pcre_config(3).
301

AUTHOR

303
304       Philip Hazel
305       University Computing Service
306       Cambridge CB2 3QH, England.
307

REVISION

309
310       Last updated: 29 September 2009
311       Copyright (c) 1997-2009 University of Cambridge.
312
313
314
315                                                                  PCREBUILD(3)
Impressum