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

NAME

6       PCRE2 - Perl-compatible regular expressions (revised API)
7

BUILDING PCRE2

9
10       PCRE2  is distributed with a configure script that can be used to build
11       the library in Unix-like environments using the applications  known  as
12       Autotools. Also in the distribution are files to support building using
13       CMake instead of configure.  The  text  file  README  contains  general
14       information  about  building  with Autotools (some of which is repeated
15       below), and also has some comments about building on various  operating
16       systems.  There  is a lot more information about building PCRE2 without
17       using Autotools (including information about using CMake  and  building
18       "by  hand")  in  the  text file called NON-AUTOTOOLS-BUILD.  You should
19       consult this file as well as the README file if you are building  in  a
20       non-Unix-like environment.
21

PCRE2 BUILD-TIME OPTIONS

23
24       The rest of this document describes the optional features of PCRE2 that
25       can be selected when the library is compiled. It  assumes  use  of  the
26       configure  script,  where  the  optional features are selected or dese‐
27       lected by providing options to configure before running the  make  com‐
28       mand.  However,  the same options can be selected in both Unix-like and
29       non-Unix-like environments if you are using CMake instead of  configure
30       to build PCRE2.
31
32       If  you  are not using Autotools or CMake, option selection can be done
33       by editing the config.h file, or by passing parameter settings  to  the
34       compiler, as described in NON-AUTOTOOLS-BUILD.
35
36       The complete list of options for configure (which includes the standard
37       ones such as the  selection  of  the  installation  directory)  can  be
38       obtained by running
39
40         ./configure --help
41
42       The  following  sections include descriptions of "on/off" options whose
43       names begin with --enable or --disable. Because of the way that config‐
44       ure  works, --enable and --disable always come in pairs, so the comple‐
45       mentary option always exists as well, but as it specifies the  default,
46       it is not described.  Options that specify values have names that start
47       with --with. At the end of a configure run, a summary of the configura‐
48       tion is output.
49

BUILDING 8-BIT, 16-BIT AND 32-BIT LIBRARIES

51
52       By  default, a library called libpcre2-8 is built, containing functions
53       that take string arguments contained in arrays  of  bytes,  interpreted
54       either  as single-byte characters, or UTF-8 strings. You can also build
55       two other libraries, called libpcre2-16 and libpcre2-32, which  process
56       strings  that  are contained in arrays of 16-bit and 32-bit code units,
57       respectively. These can be interpreted either as single-unit characters
58       or  UTF-16/UTF-32 strings. To build these additional libraries, add one
59       or both of the following to the configure command:
60
61         --enable-pcre2-16
62         --enable-pcre2-32
63
64       If you do not want the 8-bit library, add
65
66         --disable-pcre2-8
67
68       as well. At least one of the three libraries must be built.  Note  that
69       the  POSIX wrapper is for the 8-bit library only, and that pcre2grep is
70       an 8-bit program. Neither of these are built if  you  select  only  the
71       16-bit or 32-bit libraries.
72

BUILDING SHARED AND STATIC LIBRARIES

74
75       The  Autotools PCRE2 building process uses libtool to build both shared
76       and static libraries by default. You can suppress an  unwanted  library
77       by adding one of
78
79         --disable-shared
80         --disable-static
81
82       to the configure command.
83

UNICODE AND UTF SUPPORT

85
86       By  default,  PCRE2 is built with support for Unicode and UTF character
87       strings.  To build it without Unicode support, add
88
89         --disable-unicode
90
91       to the configure command. This setting applies to all three  libraries.
92       It  is  not  possible  to  build  one library with Unicode support, and
93       another without, in the same configuration.
94
95       Of itself, Unicode support does not make PCRE2 treat strings as  UTF-8,
96       UTF-16 or UTF-32. To do that, applications that use the library can set
97       the PCRE2_UTF option when they call pcre2_compile() to compile  a  pat‐
98       tern.   Alternatively,  patterns  may be started with (*UTF) unless the
99       application has locked this out by setting PCRE2_NEVER_UTF.
100
101       UTF support allows the libraries to process character code points up to
102       0x10ffff  in  the  strings that they handle. Unicode support also gives
103       access to the Unicode properties of characters, using  pattern  escapes
104       such as \P, \p, and \X. Only the general category properties such as Lu
105       and Nd are supported. Details are given in the pcre2pattern  documenta‐
106       tion.
107
108       Pattern escapes such as \d and \w do not by default make use of Unicode
109       properties. The application can request that they  do  by  setting  the
110       PCRE2_UCP  option.  Unless  the  application has set PCRE2_NEVER_UCP, a
111       pattern may also request this by starting with (*UCP).
112

DISABLING THE USE OF \C

114
115       The \C escape sequence, which matches a single code unit, even in a UTF
116       mode,  can  cause unpredictable behaviour because it may leave the cur‐
117       rent matching point in the middle of a multi-code-unit  character.  The
118       application  can  lock  it  out  by setting the PCRE2_NEVER_BACKSLASH_C
119       option when calling pcre2_compile(). There is also a build-time option
120
121         --enable-never-backslash-C
122
123       (note the upper case C) which locks out the use of \C entirely.
124

JUST-IN-TIME COMPILER SUPPORT

126
127       Just-in-time (JIT) compiler support is included in the build by  speci‐
128       fying
129
130         --enable-jit
131
132       This  support  is available only for certain hardware architectures. If
133       this option is set for an unsupported architecture,  a  building  error
134       occurs.  If in doubt, use
135
136         --enable-jit=auto
137
138       which  enables  JIT  only if the current hardware is supported. You can
139       check if JIT is enabled in the configuration summary that is output  at
140       the  end  of a configure run. If you are enabling JIT under SELinux you
141       may also want to add
142
143         --enable-jit-sealloc
144
145       which enables the use of an execmem allocator in JIT that is compatible
146       with  SELinux.  This  has  no  effect  if  JIT  is not enabled. See the
147       pcre2jit documentation for a discussion of JIT usage. When JIT  support
148       is enabled, pcre2grep automatically makes use of it, unless you add
149
150         --disable-pcre2grep-jit
151
152       to the "configure" command.
153

NEWLINE RECOGNITION

155
156       By  default, PCRE2 interprets the linefeed (LF) character as indicating
157       the end of a line. This is the normal newline  character  on  Unix-like
158       systems.  You can compile PCRE2 to use carriage return (CR) instead, by
159       adding
160
161         --enable-newline-is-cr
162
163       to the configure  command.  There  is  also  an  --enable-newline-is-lf
164       option, which explicitly specifies linefeed as the newline character.
165
166       Alternatively, you can specify that line endings are to be indicated by
167       the two-character sequence CRLF (CR immediately followed by LF). If you
168       want this, add
169
170         --enable-newline-is-crlf
171
172       to the configure command. There is a fourth option, specified by
173
174         --enable-newline-is-anycrlf
175
176       which  causes  PCRE2 to recognize any of the three sequences CR, LF, or
177       CRLF as indicating a line ending. A fifth option, specified by
178
179         --enable-newline-is-any
180
181       causes PCRE2 to recognize any Unicode  newline  sequence.  The  Unicode
182       newline sequences are the three just mentioned, plus the single charac‐
183       ters VT (vertical tab, U+000B), FF (form feed, U+000C), NEL (next line,
184       U+0085),  LS  (line  separator,  U+2028),  and PS (paragraph separator,
185       U+2029). The final option is
186
187         --enable-newline-is-nul
188
189       which causes NUL (binary zero) to be set  as  the  default  line-ending
190       character.
191
192       Whatever default line ending convention is selected when PCRE2 is built
193       can be overridden by applications that use the library. At  build  time
194       it is recommended to use the standard for your operating system.
195

WHAT \R MATCHES

197
198       By  default,  the  sequence \R in a pattern matches any Unicode newline
199       sequence, independently of what has been selected as  the  line  ending
200       sequence. If you specify
201
202         --enable-bsr-anycrlf
203
204       the  default  is changed so that \R matches only CR, LF, or CRLF. What‐
205       ever is selected when PCRE2 is built can be overridden by  applications
206       that use the library.
207

HANDLING VERY LARGE PATTERNS

209
210       Within  a  compiled  pattern,  offset values are used to point from one
211       part to another (for example, from an opening parenthesis to an  alter‐
212       nation  metacharacter).  By default, in the 8-bit and 16-bit libraries,
213       two-byte values are used for these offsets, leading to a  maximum  size
214       for a compiled pattern of around 64 thousand code units. This is suffi‐
215       cient to handle all but the most gigantic patterns. Nevertheless,  some
216       people do want to process truly enormous patterns, so it is possible to
217       compile PCRE2 to use three-byte or four-byte offsets by adding  a  set‐
218       ting such as
219
220         --with-link-size=3
221
222       to  the  configure command. The value given must be 2, 3, or 4. For the
223       16-bit library, a value of 3 is rounded up to 4.  In  these  libraries,
224       using  longer  offsets slows down the operation of PCRE2 because it has
225       to load additional data when handling them. For the 32-bit library  the
226       value  is  always 4 and cannot be overridden; the value of --with-link-
227       size is ignored.
228

LIMITING PCRE2 RESOURCE USAGE

230
231       The pcre2_match() function increments a counter each time it goes round
232       its  main  loop. Putting a limit on this counter controls the amount of
233       computing resource used by a single call to  pcre2_match().  The  limit
234       can be changed at run time, as described in the pcre2api documentation.
235       The default is 10 million, but this can be changed by adding a  setting
236       such as
237
238         --with-match-limit=500000
239
240       to   the   configure   command.   This  setting  also  applies  to  the
241       pcre2_dfa_match() matching function, and to JIT  matching  (though  the
242       counting is done differently).
243
244       The  pcre2_match() function starts out using a 20KiB vector on the sys‐
245       tem stack to record backtracking points. The more  nested  backtracking
246       points there are (that is, the deeper the search tree), the more memory
247       is needed. If the initial vector is not large enough,  heap  memory  is
248       used,  up to a certain limit, which is specified in kibibytes (units of
249       1024 bytes). The limit can be changed at run time, as described in  the
250       pcre2api  documentation.  The default limit (in effect unlimited) is 20
251       million. You can change this by a setting such as
252
253         --with-heap-limit=500
254
255       which limits the amount of heap to 500 KiB. This limit applies only  to
256       interpretive matching in pcre2_match() and pcre2_dfa_match(), which may
257       also use the heap for internal workspace  when  processing  complicated
258       patterns.  This limit does not apply when JIT (which has its own memory
259       arrangements) is used.
260
261       You can also explicitly limit the depth of nested backtracking  in  the
262       pcre2_match() interpreter. This limit defaults to the value that is set
263       for --with-match-limit. You can set a lower default  limit  by  adding,
264       for example,
265
266         --with-match-limit_depth=10000
267
268       to  the  configure  command.  This value can be overridden at run time.
269       This depth limit indirectly limits the amount of heap  memory  that  is
270       used,  but because the size of each backtracking "frame" depends on the
271       number of capturing parentheses in a pattern, the amount of  heap  that
272       is  used  before  the  limit is reached varies from pattern to pattern.
273       This limit was more useful in versions  before  10.30,  where  function
274       recursion was used for backtracking.
275
276       As well as applying to pcre2_match(), the depth limit also controls the
277       depth of recursive function calls in pcre2_dfa_match(). These are  used
278       for  lookaround  assertions,  atomic  groups, and recursion within pat‐
279       terns.  The limit does not apply to JIT matching.
280

CREATING CHARACTER TABLES AT BUILD TIME

282
283       PCRE2 uses fixed tables for processing characters whose code points are
284       less than 256. By default, PCRE2 is built with a set of tables that are
285       distributed in the file src/pcre2_chartables.c.dist. These  tables  are
286       for ASCII codes only. If you add
287
288         --enable-rebuild-chartables
289
290       to  the  configure  command, the distributed tables are no longer used.
291       Instead, a program called dftables is compiled and  run.  This  outputs
292       the source for new set of tables, created in the default locale of your
293       C run-time system. This method of replacing the tables does not work if
294       you  are cross compiling, because dftables is run on the local host. If
295       you need to create alternative tables when cross  compiling,  you  will
296       have to do so "by hand".
297

USING EBCDIC CODE

299
300       PCRE2  assumes  by default that it will run in an environment where the
301       character code is ASCII or Unicode, which is a superset of ASCII.  This
302       is the case for most computer operating systems. PCRE2 can, however, be
303       compiled to run in an 8-bit EBCDIC environment by adding
304
305         --enable-ebcdic --disable-unicode
306
307       to the configure command. This setting implies --enable-rebuild-charta‐
308       bles.  You  should  only  use  it if you know that you are in an EBCDIC
309       environment (for example, an IBM mainframe operating system).
310
311       It is not possible to support both EBCDIC and UTF-8 codes in  the  same
312       version  of  the  library. Consequently, --enable-unicode and --enable-
313       ebcdic are mutually exclusive.
314
315       The EBCDIC character that corresponds to an ASCII LF is assumed to have
316       the  value  0x15 by default. However, in some EBCDIC environments, 0x25
317       is used. In such an environment you should use
318
319         --enable-ebcdic-nl25
320
321       as well as, or instead of, --enable-ebcdic. The EBCDIC character for CR
322       has  the  same  value  as in ASCII, namely, 0x0d. Whichever of 0x15 and
323       0x25 is not chosen as LF is made to correspond to the Unicode NEL char‐
324       acter (which, in Unicode, is 0x85).
325
326       The options that select newline behaviour, such as --enable-newline-is-
327       cr, and equivalent run-time options, refer to these character values in
328       an EBCDIC environment.
329

PCRE2GREP SUPPORT FOR EXTERNAL SCRIPTS

331
332       By default, on non-Windows systems, pcre2grep supports the use of call‐
333       outs with string arguments within the patterns it is matching, in order
334       to  run external scripts. For details, see the pcre2grep documentation.
335       This support can be disabled by adding  --disable-pcre2grep-callout  to
336       the configure command.
337

PCRE2GREP OPTIONS FOR COMPRESSED FILE SUPPORT

339
340       By  default,  pcre2grep reads all files as plain text. You can build it
341       so that it recognizes files whose names end in .gz or .bz2,  and  reads
342       them with libz or libbz2, respectively, by adding one or both of
343
344         --enable-pcre2grep-libz
345         --enable-pcre2grep-libbz2
346
347       to the configure command. These options naturally require that the rel‐
348       evant libraries are installed on your system. Configuration  will  fail
349       if they are not.
350

PCRE2GREP BUFFER SIZE

352
353       pcre2grep  uses an internal buffer to hold a "window" on the file it is
354       scanning, in order to be able to output "before" and "after" lines when
355       it finds a match. The default starting size of the buffer is 20KiB. The
356       buffer itself is three times this size, but because of the  way  it  is
357       used for holding "before" lines, the longest line that is guaranteed to
358       be processable is the notional buffer size. If a longer line is encoun‐
359       tered,  pcre2grep  automatically  expands the buffer, up to a specified
360       maximum size, whose default is 1MiB or the starting size, whichever  is
361       the  larger. You can change the default parameter values by adding, for
362       example,
363
364         --with-pcre2grep-bufsize=51200
365         --with-pcre2grep-max-bufsize=2097152
366
367       to the configure command. The caller of pcre2grep  can  override  these
368       values  by  using  --buffer-size  and  --max-buffer-size on the command
369       line.
370

PCRE2TEST OPTION FOR LIBREADLINE SUPPORT

372
373       If you add one of
374
375         --enable-pcre2test-libreadline
376         --enable-pcre2test-libedit
377
378       to the configure command, pcre2test  is  linked  with  the  libreadline
379       orlibedit library, respectively, and when its input is from a terminal,
380       it reads it using the readline() function. This  provides  line-editing
381       and  history  facilities.  Note that libreadline is GPL-licensed, so if
382       you distribute a binary of pcre2test linked in this way, there  may  be
383       licensing issues. These can be avoided by linking instead with libedit,
384       which has a BSD licence.
385
386       Setting --enable-pcre2test-libreadline causes the -lreadline option  to
387       be  added to the pcre2test build. In many operating environments with a
388       sytem-installed readline library this is sufficient. However,  in  some
389       environments (e.g. if an unmodified distribution version of readline is
390       in use), some extra configuration may be necessary.  The  INSTALL  file
391       for libreadline says this:
392
393         "Readline uses the termcap functions, but does not link with
394         the termcap or curses library itself, allowing applications
395         which link with readline the to choose an appropriate library."
396
397       If  your environment has not been set up so that an appropriate library
398       is automatically included, you may need to add something like
399
400         LIBS="-ncurses"
401
402       immediately before the configure command.
403

INCLUDING DEBUGGING CODE

405
406       If you add
407
408         --enable-debug
409
410       to the configure command, additional debugging code is included in  the
411       build. This feature is intended for use by the PCRE2 maintainers.
412

DEBUGGING WITH VALGRIND SUPPORT

414
415       If you add
416
417         --enable-valgrind
418
419       to  the  configure command, PCRE2 will use valgrind annotations to mark
420       certain memory regions as  unaddressable.  This  allows  it  to  detect
421       invalid  memory  accesses,  and  is  mostly  useful for debugging PCRE2
422       itself.
423

CODE COVERAGE REPORTING

425
426       If your C compiler is gcc, you can build a version of  PCRE2  that  can
427       generate a code coverage report for its test suite. To enable this, you
428       must install lcov version 1.6 or above. Then specify
429
430         --enable-coverage
431
432       to the configure command and build PCRE2 in the usual way.
433
434       Note that using ccache (a caching C compiler) is incompatible with code
435       coverage  reporting. If you have configured ccache to run automatically
436       on your system, you must set the environment variable
437
438         CCACHE_DISABLE=1
439
440       before running make to build PCRE2, so that ccache is not used.
441
442       When --enable-coverage is used,  the  following  addition  targets  are
443       added to the Makefile:
444
445         make coverage
446
447       This  creates  a  fresh coverage report for the PCRE2 test suite. It is
448       equivalent to running "make coverage-reset", "make  coverage-baseline",
449       "make check", and then "make coverage-report".
450
451         make coverage-reset
452
453       This zeroes the coverage counters, but does nothing else.
454
455         make coverage-baseline
456
457       This captures baseline coverage information.
458
459         make coverage-report
460
461       This creates the coverage report.
462
463         make coverage-clean-report
464
465       This  removes the generated coverage report without cleaning the cover‐
466       age data itself.
467
468         make coverage-clean-data
469
470       This removes the captured coverage data without removing  the  coverage
471       files created at compile time (*.gcno).
472
473         make coverage-clean
474
475       This  cleans all coverage data including the generated coverage report.
476       For more information about code coverage, see the gcov and  lcov  docu‐
477       mentation.
478

SUPPORT FOR FUZZERS

480
481       There  is  a  special  option for use by people who want to run fuzzing
482       tests on PCRE2:
483
484         --enable-fuzz-support
485
486       At present this applies only to the 8-bit library. If set, it causes an
487       extra  library  called  libpcre2-fuzzsupport.a  to  be  built,  but not
488       installed. This contains a single function called  LLVMFuzzerTestOneIn‐
489       put()  whose  arguments are a pointer to a string and the length of the
490       string. When called, this function tries to compile  the  string  as  a
491       pattern,  and if that succeeds, to match it.  This is done both with no
492       options and with some random options bits that are generated  from  the
493       string.
494
495       Setting  --enable-fuzz-support  also  causes  a binary called pcre2fuz‐
496       zcheck to be created. This is normally run under valgrind or used  when
497       PCRE2 is compiled with address sanitizing enabled. It calls the fuzzing
498       function and outputs information about what  it  is  doing.  The  input
499       strings  are specified by arguments: if an argument starts with "=" the
500       rest of it is a literal input string. Otherwise, it is assumed to be  a
501       file name, and the contents of the file are the test string.
502

OBSOLETE OPTION

504
505       In  versions  of  PCRE2 prior to 10.30, there were two ways of handling
506       backtracking in the pcre2_match() function. The default was to use  the
507       system stack, but if
508
509         --disable-stack-for-recursion
510
511       was  set,  memory on the heap was used. From release 10.30 onwards this
512       has changed (the stack is no longer used)  and  this  option  now  does
513       nothing except give a warning.
514

SEE ALSO

516
517       pcre2api(3), pcre2-config(3).
518

AUTHOR

520
521       Philip Hazel
522       University Computing Service
523       Cambridge, England.
524

REVISION

526
527       Last updated: 26 April 2018
528       Copyright (c) 1997-2018 University of Cambridge.
529
530
531
532PCRE2 10.32                      26 April 2018                   PCRE2BUILD(3)
Impressum