xref: /aosp_15_r20/external/pcre/doc/html/pcre2build.html (revision 22dc650d8ae982c6770746019a6f94af92b0f024)
1<html>
2<head>
3<title>pcre2build specification</title>
4</head>
5<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
6<h1>pcre2build man page</h1>
7<p>
8Return to the <a href="index.html">PCRE2 index page</a>.
9</p>
10<p>
11This page is part of the PCRE2 HTML documentation. It was generated
12automatically from the original man page. If there is any nonsense in it,
13please consult the man page, in case the conversion went wrong.
14<br>
15<ul>
16<li><a name="TOC1" href="#SEC1">BUILDING PCRE2</a>
17<li><a name="TOC2" href="#SEC2">PCRE2 BUILD-TIME OPTIONS</a>
18<li><a name="TOC3" href="#SEC3">BUILDING 8-BIT, 16-BIT AND 32-BIT LIBRARIES</a>
19<li><a name="TOC4" href="#SEC4">BUILDING SHARED AND STATIC LIBRARIES</a>
20<li><a name="TOC5" href="#SEC5">UNICODE AND UTF SUPPORT</a>
21<li><a name="TOC6" href="#SEC6">DISABLING THE USE OF \C</a>
22<li><a name="TOC7" href="#SEC7">JUST-IN-TIME COMPILER SUPPORT</a>
23<li><a name="TOC8" href="#SEC8">NEWLINE RECOGNITION</a>
24<li><a name="TOC9" href="#SEC9">WHAT \R MATCHES</a>
25<li><a name="TOC10" href="#SEC10">HANDLING VERY LARGE PATTERNS</a>
26<li><a name="TOC11" href="#SEC11">LIMITING PCRE2 RESOURCE USAGE</a>
27<li><a name="TOC12" href="#SEC12">LIMITING VARIABLE-LENGTH LOOKBEHIND ASSERTIONS</a>
28<li><a name="TOC13" href="#SEC13">CREATING CHARACTER TABLES AT BUILD TIME</a>
29<li><a name="TOC14" href="#SEC14">USING EBCDIC CODE</a>
30<li><a name="TOC15" href="#SEC15">PCRE2GREP SUPPORT FOR EXTERNAL SCRIPTS</a>
31<li><a name="TOC16" href="#SEC16">PCRE2GREP OPTIONS FOR COMPRESSED FILE SUPPORT</a>
32<li><a name="TOC17" href="#SEC17">PCRE2GREP BUFFER SIZE</a>
33<li><a name="TOC18" href="#SEC18">PCRE2TEST OPTION FOR LIBREADLINE SUPPORT</a>
34<li><a name="TOC19" href="#SEC19">INCLUDING DEBUGGING CODE</a>
35<li><a name="TOC20" href="#SEC20">DEBUGGING WITH VALGRIND SUPPORT</a>
36<li><a name="TOC21" href="#SEC21">CODE COVERAGE REPORTING</a>
37<li><a name="TOC22" href="#SEC22">DISABLING THE Z AND T FORMATTING MODIFIERS</a>
38<li><a name="TOC23" href="#SEC23">SUPPORT FOR FUZZERS</a>
39<li><a name="TOC24" href="#SEC24">OBSOLETE OPTION</a>
40<li><a name="TOC25" href="#SEC25">SEE ALSO</a>
41<li><a name="TOC26" href="#SEC26">AUTHOR</a>
42<li><a name="TOC27" href="#SEC27">REVISION</a>
43</ul>
44<br><a name="SEC1" href="#TOC1">BUILDING PCRE2</a><br>
45<P>
46PCRE2 is distributed with a <b>configure</b> script that can be used to build
47the library in Unix-like environments using the applications known as
48Autotools. Also in the distribution are files to support building using
49<b>CMake</b> instead of <b>configure</b>. The text file
50<a href="README.txt"><b>README</b></a>
51contains general information about building with Autotools (some of which is
52repeated below), and also has some comments about building on various operating
53systems. The files in the <b>vms</b> directory support building under OpenVMS.
54There is a lot more information about building PCRE2 without using
55Autotools (including information about using <b>CMake</b> and building "by
56hand") in the text file called
57<a href="NON-AUTOTOOLS-BUILD.txt"><b>NON-AUTOTOOLS-BUILD</b>.</a>
58You should consult this file as well as the
59<a href="README.txt"><b>README</b></a>
60file if you are building in a non-Unix-like environment.
61</P>
62<br><a name="SEC2" href="#TOC1">PCRE2 BUILD-TIME OPTIONS</a><br>
63<P>
64The rest of this document describes the optional features of PCRE2 that can be
65selected when the library is compiled. It assumes use of the <b>configure</b>
66script, where the optional features are selected or deselected by providing
67options to <b>configure</b> before running the <b>make</b> command. However, the
68same options can be selected in both Unix-like and non-Unix-like environments
69if you are using <b>CMake</b> instead of <b>configure</b> to build PCRE2.
70</P>
71<P>
72If you are not using Autotools or <b>CMake</b>, option selection can be done by
73editing the <b>config.h</b> file, or by passing parameter settings to the
74compiler, as described in
75<a href="NON-AUTOTOOLS-BUILD.txt"><b>NON-AUTOTOOLS-BUILD</b>.</a>
76</P>
77<P>
78The complete list of options for <b>configure</b> (which includes the standard
79ones such as the selection of the installation directory) can be obtained by
80running
81<pre>
82  ./configure --help
83</pre>
84The following sections include descriptions of "on/off" options whose names
85begin with --enable or --disable. Because of the way that <b>configure</b>
86works, --enable and --disable always come in pairs, so the complementary option
87always exists as well, but as it specifies the default, it is not described.
88Options that specify values have names that start with --with. At the end of a
89<b>configure</b> run, a summary of the configuration is output.
90</P>
91<br><a name="SEC3" href="#TOC1">BUILDING 8-BIT, 16-BIT AND 32-BIT LIBRARIES</a><br>
92<P>
93By default, a library called <b>libpcre2-8</b> is built, containing functions
94that take string arguments contained in arrays of bytes, interpreted either as
95single-byte characters, or UTF-8 strings. You can also build two other
96libraries, called <b>libpcre2-16</b> and <b>libpcre2-32</b>, which process
97strings that are contained in arrays of 16-bit and 32-bit code units,
98respectively. These can be interpreted either as single-unit characters or
99UTF-16/UTF-32 strings. To build these additional libraries, add one or both of
100the following to the <b>configure</b> command:
101<pre>
102  --enable-pcre2-16
103  --enable-pcre2-32
104</pre>
105If you do not want the 8-bit library, add
106<pre>
107  --disable-pcre2-8
108</pre>
109as well. At least one of the three libraries must be built. Note that the POSIX
110wrapper is for the 8-bit library only, and that <b>pcre2grep</b> is an 8-bit
111program. Neither of these are built if you select only the 16-bit or 32-bit
112libraries.
113</P>
114<br><a name="SEC4" href="#TOC1">BUILDING SHARED AND STATIC LIBRARIES</a><br>
115<P>
116The Autotools PCRE2 building process uses <b>libtool</b> to build both shared
117and static libraries by default. You can suppress an unwanted library by adding
118one of
119<pre>
120  --disable-shared
121  --disable-static
122</pre>
123to the <b>configure</b> command. Setting --disable-shared ensures that PCRE2
124libraries are built as static libraries. The binaries that are then created as
125part of the build process (for example, <b>pcre2test</b> and <b>pcre2grep</b>)
126are linked statically with one or more PCRE2 libraries, but may also be
127dynamically linked with other libraries such as <b>libc</b>. If you want these
128binaries to be fully statically linked, you can set LDFLAGS like this:
129<br>
130<br>
131LDFLAGS=--static ./configure --disable-shared
132<br>
133<br>
134Note the two hyphens in --static. Of course, this works only if static versions
135of all the relevant libraries are available for linking.
136</P>
137<br><a name="SEC5" href="#TOC1">UNICODE AND UTF SUPPORT</a><br>
138<P>
139By default, PCRE2 is built with support for Unicode and UTF character strings.
140To build it without Unicode support, add
141<pre>
142  --disable-unicode
143</pre>
144to the <b>configure</b> command. This setting applies to all three libraries. It
145is not possible to build one library with Unicode support and another without
146in the same configuration.
147</P>
148<P>
149Of itself, Unicode support does not make PCRE2 treat strings as UTF-8, UTF-16
150or UTF-32. To do that, applications that use the library can set the PCRE2_UTF
151option when they call <b>pcre2_compile()</b> to compile a pattern.
152Alternatively, patterns may be started with (*UTF) unless the application has
153locked this out by setting PCRE2_NEVER_UTF.
154</P>
155<P>
156UTF support allows the libraries to process character code points up to
1570x10ffff in the strings that they handle. Unicode support also gives access to
158the Unicode properties of characters, using pattern escapes such as \P, \p,
159and \X. Only the general category properties such as <i>Lu</i> and <i>Nd</i>,
160script names, and some bi-directional properties are supported. Details are
161given in the
162<a href="pcre2pattern.html"><b>pcre2pattern</b></a>
163documentation.
164</P>
165<P>
166Pattern escapes such as \d and \w do not by default make use of Unicode
167properties. The application can request that they do by setting the PCRE2_UCP
168option. Unless the application has set PCRE2_NEVER_UCP, a pattern may also
169request this by starting with (*UCP).
170</P>
171<br><a name="SEC6" href="#TOC1">DISABLING THE USE OF \C</a><br>
172<P>
173The \C escape sequence, which matches a single code unit, even in a UTF mode,
174can cause unpredictable behaviour because it may leave the current matching
175point in the middle of a multi-code-unit character. The application can lock it
176out by setting the PCRE2_NEVER_BACKSLASH_C option when calling
177<b>pcre2_compile()</b>. There is also a build-time option
178<pre>
179  --enable-never-backslash-C
180</pre>
181(note the upper case C) which locks out the use of \C entirely.
182</P>
183<br><a name="SEC7" href="#TOC1">JUST-IN-TIME COMPILER SUPPORT</a><br>
184<P>
185Just-in-time (JIT) compiler support is included in the build by specifying
186<pre>
187  --enable-jit
188</pre>
189This support is available only for certain hardware architectures. If this
190option is set for an unsupported architecture, a building error occurs.
191If in doubt, use
192<pre>
193  --enable-jit=auto
194</pre>
195which enables JIT only if the current hardware is supported. You can check
196if JIT is enabled in the configuration summary that is output at the end of a
197<b>configure</b> run. If you are enabling JIT under SELinux you may also want to
198add
199<pre>
200  --enable-jit-sealloc
201</pre>
202which enables the use of an execmem allocator in JIT that is compatible with
203SELinux. This has no effect if JIT is not enabled. See the
204<a href="pcre2jit.html"><b>pcre2jit</b></a>
205documentation for a discussion of JIT usage. When JIT support is enabled,
206<b>pcre2grep</b> automatically makes use of it, unless you add
207<pre>
208  --disable-pcre2grep-jit
209</pre>
210to the <b>configure</b> command.
211</P>
212<br><a name="SEC8" href="#TOC1">NEWLINE RECOGNITION</a><br>
213<P>
214By default, PCRE2 interprets the linefeed (LF) character as indicating the end
215of a line. This is the normal newline character on Unix-like systems. You can
216compile PCRE2 to use carriage return (CR) instead, by adding
217<pre>
218  --enable-newline-is-cr
219</pre>
220to the <b>configure</b> command. There is also an --enable-newline-is-lf option,
221which explicitly specifies linefeed as the newline character.
222</P>
223<P>
224Alternatively, you can specify that line endings are to be indicated by the
225two-character sequence CRLF (CR immediately followed by LF). If you want this,
226add
227<pre>
228  --enable-newline-is-crlf
229</pre>
230to the <b>configure</b> command. There is a fourth option, specified by
231<pre>
232  --enable-newline-is-anycrlf
233</pre>
234which causes PCRE2 to recognize any of the three sequences CR, LF, or CRLF as
235indicating a line ending. A fifth option, specified by
236<pre>
237  --enable-newline-is-any
238</pre>
239causes PCRE2 to recognize any Unicode newline sequence. The Unicode newline
240sequences are the three just mentioned, plus the single characters VT (vertical
241tab, U+000B), FF (form feed, U+000C), NEL (next line, U+0085), LS (line
242separator, U+2028), and PS (paragraph separator, U+2029). The final option is
243<pre>
244  --enable-newline-is-nul
245</pre>
246which causes NUL (binary zero) to be set as the default line-ending character.
247</P>
248<P>
249Whatever default line ending convention is selected when PCRE2 is built can be
250overridden by applications that use the library. At build time it is
251recommended to use the standard for your operating system.
252</P>
253<br><a name="SEC9" href="#TOC1">WHAT \R MATCHES</a><br>
254<P>
255By default, the sequence \R in a pattern matches any Unicode newline sequence,
256independently of what has been selected as the line ending sequence. If you
257specify
258<pre>
259  --enable-bsr-anycrlf
260</pre>
261the default is changed so that \R matches only CR, LF, or CRLF. Whatever is
262selected when PCRE2 is built can be overridden by applications that use the
263library.
264</P>
265<br><a name="SEC10" href="#TOC1">HANDLING VERY LARGE PATTERNS</a><br>
266<P>
267Within a compiled pattern, offset values are used to point from one part to
268another (for example, from an opening parenthesis to an alternation
269metacharacter). By default, in the 8-bit and 16-bit libraries, two-byte values
270are used for these offsets, leading to a maximum size for a compiled pattern of
271around 64 thousand code units. This is sufficient to handle all but the most
272gigantic patterns. Nevertheless, some people do want to process truly enormous
273patterns, so it is possible to compile PCRE2 to use three-byte or four-byte
274offsets by adding a setting such as
275<pre>
276  --with-link-size=3
277</pre>
278to the <b>configure</b> command. The value given must be 2, 3, or 4. For the
27916-bit library, a value of 3 is rounded up to 4. In these libraries, using
280longer offsets slows down the operation of PCRE2 because it has to load
281additional data when handling them. For the 32-bit library the value is always
2824 and cannot be overridden; the value of --with-link-size is ignored.
283</P>
284<br><a name="SEC11" href="#TOC1">LIMITING PCRE2 RESOURCE USAGE</a><br>
285<P>
286The <b>pcre2_match()</b> function increments a counter each time it goes round
287its main loop. Putting a limit on this counter controls the amount of computing
288resource used by a single call to <b>pcre2_match()</b>. The limit can be changed
289at run time, as described in the
290<a href="pcre2api.html"><b>pcre2api</b></a>
291documentation. The default is 10 million, but this can be changed by adding a
292setting such as
293<pre>
294  --with-match-limit=500000
295</pre>
296to the <b>configure</b> command. This setting also applies to the
297<b>pcre2_dfa_match()</b> matching function, and to JIT matching (though the
298counting is done differently).
299</P>
300<P>
301The <b>pcre2_match()</b> function uses heap memory to record backtracking
302points. The more nested backtracking points there are (that is, the deeper the
303search tree), the more memory is needed. There is an upper limit, specified in
304kibibytes (units of 1024 bytes). This limit can be changed at run time, as
305described in the
306<a href="pcre2api.html"><b>pcre2api</b></a>
307documentation. The default limit (in effect unlimited) is 20 million. You can
308change this by a setting such as
309<pre>
310  --with-heap-limit=500
311</pre>
312which limits the amount of heap to 500 KiB. This limit applies only to
313interpretive matching in <b>pcre2_match()</b> and <b>pcre2_dfa_match()</b>, which
314may also use the heap for internal workspace when processing complicated
315patterns. This limit does not apply when JIT (which has its own memory
316arrangements) is used.
317</P>
318<P>
319You can also explicitly limit the depth of nested backtracking in the
320<b>pcre2_match()</b> interpreter. This limit defaults to the value that is set
321for --with-match-limit. You can set a lower default limit by adding, for
322example,
323<pre>
324  --with-match-limit-depth=10000
325</pre>
326to the <b>configure</b> command. This value can be overridden at run time. This
327depth limit indirectly limits the amount of heap memory that is used, but
328because the size of each backtracking "frame" depends on the number of
329capturing parentheses in a pattern, the amount of heap that is used before the
330limit is reached varies from pattern to pattern. This limit was more useful in
331versions before 10.30, where function recursion was used for backtracking.
332</P>
333<P>
334As well as applying to <b>pcre2_match()</b>, the depth limit also controls
335the depth of recursive function calls in <b>pcre2_dfa_match()</b>. These are
336used for lookaround assertions, atomic groups, and recursion within patterns.
337The limit does not apply to JIT matching.
338</P>
339<br><a name="SEC12" href="#TOC1">LIMITING VARIABLE-LENGTH LOOKBEHIND ASSERTIONS</a><br>
340<P>
341Lookbehind assertions in which one or more branches can match a variable number
342of characters are supported only if there is a maximum matching length for each
343top-level branch. There is a limit to this maximum that defaults to 255
344characters. You can alter this default by a setting such as
345<pre>
346  --with-max-varlookbehind=100
347</pre>
348The limit can be changed at runtime by calling
349<b>pcre2_set_max_varlookbehind()</b>. Lookbehind assertions in which every
350branch matches a fixed number of characters (not necessarily all the same) are
351not constrained by this limit.
352<a name="createtables"></a></P>
353<br><a name="SEC13" href="#TOC1">CREATING CHARACTER TABLES AT BUILD TIME</a><br>
354<P>
355PCRE2 uses fixed tables for processing characters whose code points are less
356than 256. By default, PCRE2 is built with a set of tables that are distributed
357in the file <i>src/pcre2_chartables.c.dist</i>. These tables are for ASCII codes
358only. If you add
359<pre>
360  --enable-rebuild-chartables
361</pre>
362to the <b>configure</b> command, the distributed tables are no longer used.
363Instead, a program called <b>pcre2_dftables</b> is compiled and run. This
364outputs the source for new set of tables, created in the default locale of your
365C run-time system. This method of replacing the tables does not work if you are
366cross compiling, because <b>pcre2_dftables</b> needs to be run on the local
367host and therefore not compiled with the cross compiler.
368</P>
369<P>
370If you need to create alternative tables when cross compiling, you will have to
371do so "by hand". There may also be other reasons for creating tables manually.
372To cause <b>pcre2_dftables</b> to be built on the local host, run a normal
373compiling command, and then run the program with the output file as its
374argument, for example:
375<pre>
376  cc src/pcre2_dftables.c -o pcre2_dftables
377  ./pcre2_dftables src/pcre2_chartables.c
378</pre>
379This builds the tables in the default locale of the local host. If you want to
380specify a locale, you must use the -L option:
381<pre>
382  LC_ALL=fr_FR ./pcre2_dftables -L src/pcre2_chartables.c
383</pre>
384You can also specify -b (with or without -L). This causes the tables to be
385written in binary instead of as source code. A set of binary tables can be
386loaded into memory by an application and passed to <b>pcre2_compile()</b> in the
387same way as tables created by calling <b>pcre2_maketables()</b>. The tables are
388just a string of bytes, independent of hardware characteristics such as
389endianness. This means they can be bundled with an application that runs in
390different environments, to ensure consistent behaviour.
391</P>
392<br><a name="SEC14" href="#TOC1">USING EBCDIC CODE</a><br>
393<P>
394PCRE2 assumes by default that it will run in an environment where the character
395code is ASCII or Unicode, which is a superset of ASCII. This is the case for
396most computer operating systems. PCRE2 can, however, be compiled to run in an
3978-bit EBCDIC environment by adding
398<pre>
399  --enable-ebcdic --disable-unicode
400</pre>
401to the <b>configure</b> command. This setting implies
402--enable-rebuild-chartables. You should only use it if you know that you are in
403an EBCDIC environment (for example, an IBM mainframe operating system).
404</P>
405<P>
406It is not possible to support both EBCDIC and UTF-8 codes in the same version
407of the library. Consequently, --enable-unicode and --enable-ebcdic are mutually
408exclusive.
409</P>
410<P>
411The EBCDIC character that corresponds to an ASCII LF is assumed to have the
412value 0x15 by default. However, in some EBCDIC environments, 0x25 is used. In
413such an environment you should use
414<pre>
415  --enable-ebcdic-nl25
416</pre>
417as well as, or instead of, --enable-ebcdic. The EBCDIC character for CR has the
418same value as in ASCII, namely, 0x0d. Whichever of 0x15 and 0x25 is <i>not</i>
419chosen as LF is made to correspond to the Unicode NEL character (which, in
420Unicode, is 0x85).
421</P>
422<P>
423The options that select newline behaviour, such as --enable-newline-is-cr,
424and equivalent run-time options, refer to these character values in an EBCDIC
425environment.
426</P>
427<br><a name="SEC15" href="#TOC1">PCRE2GREP SUPPORT FOR EXTERNAL SCRIPTS</a><br>
428<P>
429By default <b>pcre2grep</b> supports the use of callouts with string arguments
430within the patterns it is matching. There are two kinds: one that generates
431output using local code, and another that calls an external program or script.
432If --disable-pcre2grep-callout-fork is added to the <b>configure</b> command,
433only the first kind of callout is supported; if --disable-pcre2grep-callout is
434used, all callouts are completely ignored. For more details of <b>pcre2grep</b>
435callouts, see the
436<a href="pcre2grep.html"><b>pcre2grep</b></a>
437documentation.
438</P>
439<br><a name="SEC16" href="#TOC1">PCRE2GREP OPTIONS FOR COMPRESSED FILE SUPPORT</a><br>
440<P>
441By default, <b>pcre2grep</b> reads all files as plain text. You can build it so
442that it recognizes files whose names end in <b>.gz</b> or <b>.bz2</b>, and reads
443them with <b>libz</b> or <b>libbz2</b>, respectively, by adding one or both of
444<pre>
445  --enable-pcre2grep-libz
446  --enable-pcre2grep-libbz2
447</pre>
448to the <b>configure</b> command. These options naturally require that the
449relevant libraries are installed on your system. Configuration will fail if
450they are not.
451</P>
452<br><a name="SEC17" href="#TOC1">PCRE2GREP BUFFER SIZE</a><br>
453<P>
454<b>pcre2grep</b> uses an internal buffer to hold a "window" on the file it is
455scanning, in order to be able to output "before" and "after" lines when it
456finds a match. The default starting size of the buffer is 20KiB. The buffer
457itself is three times this size, but because of the way it is used for holding
458"before" lines, the longest line that is guaranteed to be processable is the
459notional buffer size. If a longer line is encountered, <b>pcre2grep</b>
460automatically expands the buffer, up to a specified maximum size, whose default
461is 1MiB or the starting size, whichever is the larger. You can change the
462default parameter values by adding, for example,
463<pre>
464  --with-pcre2grep-bufsize=51200
465  --with-pcre2grep-max-bufsize=2097152
466</pre>
467to the <b>configure</b> command. The caller of <b>pcre2grep</b> can override
468these values by using --buffer-size and --max-buffer-size on the command line.
469</P>
470<br><a name="SEC18" href="#TOC1">PCRE2TEST OPTION FOR LIBREADLINE SUPPORT</a><br>
471<P>
472If you add one of
473<pre>
474  --enable-pcre2test-libreadline
475  --enable-pcre2test-libedit
476</pre>
477to the <b>configure</b> command, <b>pcre2test</b> is linked with the
478<b>libreadline</b> or<b>libedit</b> library, respectively, and when its input is
479from a terminal, it reads it using the <b>readline()</b> function. This provides
480line-editing and history facilities. Note that <b>libreadline</b> is
481GPL-licensed, so if you distribute a binary of <b>pcre2test</b> linked in this
482way, there may be licensing issues. These can be avoided by linking instead
483with <b>libedit</b>, which has a BSD licence.
484</P>
485<P>
486Setting --enable-pcre2test-libreadline causes the <b>-lreadline</b> option to be
487added to the <b>pcre2test</b> build. In many operating environments with a
488system-installed readline library this is sufficient. However, in some
489environments (e.g. if an unmodified distribution version of readline is in
490use), some extra configuration may be necessary. The INSTALL file for
491<b>libreadline</b> says this:
492<pre>
493  "Readline uses the termcap functions, but does not link with
494  the termcap or curses library itself, allowing applications
495  which link with readline the to choose an appropriate library."
496</pre>
497If your environment has not been set up so that an appropriate library is
498automatically included, you may need to add something like
499<pre>
500  LIBS="-ncurses"
501</pre>
502immediately before the <b>configure</b> command.
503</P>
504<br><a name="SEC19" href="#TOC1">INCLUDING DEBUGGING CODE</a><br>
505<P>
506If you add
507<pre>
508  --enable-debug
509</pre>
510to the <b>configure</b> command, additional debugging code is included in the
511build. This feature is intended for use by the PCRE2 maintainers.
512</P>
513<br><a name="SEC20" href="#TOC1">DEBUGGING WITH VALGRIND SUPPORT</a><br>
514<P>
515If you add
516<pre>
517  --enable-valgrind
518</pre>
519to the <b>configure</b> command, PCRE2 will use valgrind annotations to mark
520certain memory regions as unaddressable. This allows it to detect invalid
521memory accesses, and is mostly useful for debugging PCRE2 itself.
522</P>
523<br><a name="SEC21" href="#TOC1">CODE COVERAGE REPORTING</a><br>
524<P>
525If your C compiler is gcc, you can build a version of PCRE2 that can generate a
526code coverage report for its test suite. To enable this, you must install
527<b>lcov</b> version 1.6 or above. Then specify
528<pre>
529  --enable-coverage
530</pre>
531to the <b>configure</b> command and build PCRE2 in the usual way.
532</P>
533<P>
534Note that using <b>ccache</b> (a caching C compiler) is incompatible with code
535coverage reporting. If you have configured <b>ccache</b> to run automatically
536on your system, you must set the environment variable
537<pre>
538  CCACHE_DISABLE=1
539</pre>
540before running <b>make</b> to build PCRE2, so that <b>ccache</b> is not used.
541</P>
542<P>
543When --enable-coverage is used, the following addition targets are added to the
544<i>Makefile</i>:
545<pre>
546  make coverage
547</pre>
548This creates a fresh coverage report for the PCRE2 test suite. It is equivalent
549to running "make coverage-reset", "make coverage-baseline", "make check", and
550then "make coverage-report".
551<pre>
552  make coverage-reset
553</pre>
554This zeroes the coverage counters, but does nothing else.
555<pre>
556  make coverage-baseline
557</pre>
558This captures baseline coverage information.
559<pre>
560  make coverage-report
561</pre>
562This creates the coverage report.
563<pre>
564  make coverage-clean-report
565</pre>
566This removes the generated coverage report without cleaning the coverage data
567itself.
568<pre>
569  make coverage-clean-data
570</pre>
571This removes the captured coverage data without removing the coverage files
572created at compile time (*.gcno).
573<pre>
574  make coverage-clean
575</pre>
576This cleans all coverage data including the generated coverage report. For more
577information about code coverage, see the <b>gcov</b> and <b>lcov</b>
578documentation.
579</P>
580<br><a name="SEC22" href="#TOC1">DISABLING THE Z AND T FORMATTING MODIFIERS</a><br>
581<P>
582The C99 standard defines formatting modifiers z and t for size_t and
583ptrdiff_t values, respectively. By default, PCRE2 uses these modifiers in
584environments other than old versions of Microsoft Visual Studio when
585__STDC_VERSION__ is defined and has a value greater than or equal to 199901L
586(indicating support for C99).
587However, there is at least one environment that claims to be C99 but does not
588support these modifiers. If
589<pre>
590  --disable-percent-zt
591</pre>
592is specified, no use is made of the z or t modifiers. Instead of %td or %zu,
593a suitable format is used depending in the size of long for the platform.
594</P>
595<br><a name="SEC23" href="#TOC1">SUPPORT FOR FUZZERS</a><br>
596<P>
597There is a special option for use by people who want to run fuzzing tests on
598PCRE2:
599<pre>
600  --enable-fuzz-support
601</pre>
602At present this applies only to the 8-bit library. If set, it causes an extra
603library called libpcre2-fuzzsupport.a to be built, but not installed. This
604contains a single function called LLVMFuzzerTestOneInput() whose arguments are
605a pointer to a string and the length of the string. When called, this function
606tries to compile the string as a pattern, and if that succeeds, to match it.
607This is done both with no options and with some random options bits that are
608generated from the string.
609</P>
610<P>
611Setting --enable-fuzz-support also causes a binary called <b>pcre2fuzzcheck</b>
612to be created. This is normally run under valgrind or used when PCRE2 is
613compiled with address sanitizing enabled. It calls the fuzzing function and
614outputs information about what it is doing. The input strings are specified by
615arguments: if an argument starts with "=" the rest of it is a literal input
616string. Otherwise, it is assumed to be a file name, and the contents of the
617file are the test string.
618</P>
619<br><a name="SEC24" href="#TOC1">OBSOLETE OPTION</a><br>
620<P>
621In versions of PCRE2 prior to 10.30, there were two ways of handling
622backtracking in the <b>pcre2_match()</b> function. The default was to use the
623system stack, but if
624<pre>
625  --disable-stack-for-recursion
626</pre>
627was set, memory on the heap was used. From release 10.30 onwards this has
628changed (the stack is no longer used) and this option now does nothing except
629give a warning.
630</P>
631<br><a name="SEC25" href="#TOC1">SEE ALSO</a><br>
632<P>
633<b>pcre2api</b>(3), <b>pcre2-config</b>(3).
634</P>
635<br><a name="SEC26" href="#TOC1">AUTHOR</a><br>
636<P>
637Philip Hazel
638<br>
639Retired from University Computing Service
640<br>
641Cambridge, England.
642<br>
643</P>
644<br><a name="SEC27" href="#TOC1">REVISION</a><br>
645<P>
646Last updated: 15 April 2024
647<br>
648Copyright &copy; 1997-2024 University of Cambridge.
649<br>
650<p>
651Return to the <a href="index.html">PCRE2 index page</a>.
652</p>
653