/[pcre]/code/trunk/doc/html/pcrebuild.html
ViewVC logotype

Diff of /code/trunk/doc/html/pcrebuild.html

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1193 by ph10, Sat Jun 2 11:03:06 2012 UTC revision 1194 by ph10, Wed Oct 31 17:42:29 2012 UTC
# Line 14  man page, in case the conversion went wr Line 14  man page, in case the conversion went wr
14  <br>  <br>
15  <ul>  <ul>
16  <li><a name="TOC1" href="#SEC1">PCRE BUILD-TIME OPTIONS</a>  <li><a name="TOC1" href="#SEC1">PCRE BUILD-TIME OPTIONS</a>
17  <li><a name="TOC2" href="#SEC2">BUILDING 8-BIT and 16-BIT LIBRARIES</a>  <li><a name="TOC2" href="#SEC2">BUILDING 8-BIT, 16-BIT AND 32-BIT LIBRARIES</a>
18  <li><a name="TOC3" href="#SEC3">BUILDING SHARED AND STATIC LIBRARIES</a>  <li><a name="TOC3" href="#SEC3">BUILDING SHARED AND STATIC LIBRARIES</a>
19  <li><a name="TOC4" href="#SEC4">C++ SUPPORT</a>  <li><a name="TOC4" href="#SEC4">C++ SUPPORT</a>
20  <li><a name="TOC5" href="#SEC5">UTF-8 and UTF-16 SUPPORT</a>  <li><a name="TOC5" href="#SEC5">UTF-8, UTF-16 AND UTF-32 SUPPORT</a>
21  <li><a name="TOC6" href="#SEC6">UNICODE CHARACTER PROPERTY SUPPORT</a>  <li><a name="TOC6" href="#SEC6">UNICODE CHARACTER PROPERTY SUPPORT</a>
22  <li><a name="TOC7" href="#SEC7">JUST-IN-TIME COMPILER SUPPORT</a>  <li><a name="TOC7" href="#SEC7">JUST-IN-TIME COMPILER SUPPORT</a>
23  <li><a name="TOC8" href="#SEC8">CODE VALUE OF NEWLINE</a>  <li><a name="TOC8" href="#SEC8">CODE VALUE OF NEWLINE</a>
# Line 31  man page, in case the conversion went wr Line 31  man page, in case the conversion went wr
31  <li><a name="TOC16" href="#SEC16">PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT</a>  <li><a name="TOC16" href="#SEC16">PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT</a>
32  <li><a name="TOC17" href="#SEC17">PCREGREP BUFFER SIZE</a>  <li><a name="TOC17" href="#SEC17">PCREGREP BUFFER SIZE</a>
33  <li><a name="TOC18" href="#SEC18">PCRETEST OPTION FOR LIBREADLINE SUPPORT</a>  <li><a name="TOC18" href="#SEC18">PCRETEST OPTION FOR LIBREADLINE SUPPORT</a>
34  <li><a name="TOC19" href="#SEC19">SEE ALSO</a>  <li><a name="TOC19" href="#SEC19">DEBUGGING WITH VALGRIND SUPPORT</a>
35  <li><a name="TOC20" href="#SEC20">AUTHOR</a>  <li><a name="TOC20" href="#SEC20">CODE COVERAGE REPORTING</a>
36  <li><a name="TOC21" href="#SEC21">REVISION</a>  <li><a name="TOC21" href="#SEC21">SEE ALSO</a>
37    <li><a name="TOC22" href="#SEC22">AUTHOR</a>
38    <li><a name="TOC23" href="#SEC23">REVISION</a>
39  </ul>  </ul>
40  <br><a name="SEC1" href="#TOC1">PCRE BUILD-TIME OPTIONS</a><br>  <br><a name="SEC1" href="#TOC1">PCRE BUILD-TIME OPTIONS</a><br>
41  <P>  <P>
# Line 46  the GUI facility of <b>cmake-gui</b> if Line 48  the GUI facility of <b>cmake-gui</b> if
48  <b>configure</b> to build PCRE.  <b>configure</b> to build PCRE.
49  </P>  </P>
50  <P>  <P>
51  There is a lot more information about building PCRE in non-Unix-like  There is a lot more information about building PCRE without using
52  environments in the file called <i>NON_UNIX_USE</i>, which is part of the PCRE  <b>configure</b> (including information about using <b>CMake</b> or building "by
53    hand") in the file called <i>NON-AUTOTOOLS-BUILD</i>, which is part of the PCRE
54  distribution. You should consult this file as well as the <i>README</i> file if  distribution. You should consult this file as well as the <i>README</i> file if
55  you are building in a non-Unix-like environment.  you are building in a non-Unix-like environment.
56  </P>  </P>
# Line 64  The following sections include descripti Line 67  The following sections include descripti
67  --enable and --disable always come in pairs, so the complementary option always  --enable and --disable always come in pairs, so the complementary option always
68  exists as well, but as it specifies the default, it is not described.  exists as well, but as it specifies the default, it is not described.
69  </P>  </P>
70  <br><a name="SEC2" href="#TOC1">BUILDING 8-BIT and 16-BIT LIBRARIES</a><br>  <br><a name="SEC2" href="#TOC1">BUILDING 8-BIT, 16-BIT AND 32-BIT LIBRARIES</a><br>
71  <P>  <P>
72  By default, a library called <b>libpcre</b> is built, containing functions that  By default, a library called <b>libpcre</b> is built, containing functions that
73  take string arguments contained in vectors of bytes, either as single-byte  take string arguments contained in vectors of bytes, either as single-byte
# Line 75  strings, by adding Line 78  strings, by adding
78  <pre>  <pre>
79    --enable-pcre16    --enable-pcre16
80  </pre>  </pre>
81    to the <b>configure</b> command. You can also build a separate
82    library, called <b>libpcre32</b>, in which strings are contained in vectors of
83    32-bit data units and interpreted either as single-unit characters or UTF-32
84    strings, by adding
85    <pre>
86      --enable-pcre32
87    </pre>
88  to the <b>configure</b> command. If you do not want the 8-bit library, add  to the <b>configure</b> command. If you do not want the 8-bit library, add
89  <pre>  <pre>
90    --disable-pcre8    --disable-pcre8
91  </pre>  </pre>
92  as well. At least one of the two libraries must be built. Note that the C++ and  as well. At least one of the three libraries must be built. Note that the C++
93  POSIX wrappers are for the 8-bit library only, and that <b>pcregrep</b> is an  and POSIX wrappers are for the 8-bit library only, and that <b>pcregrep</b> is
94  8-bit program. None of these are built if you select only the 16-bit library.  an 8-bit program. None of these are built if you select only the 16-bit or
95    32-bit libraries.
96  </P>  </P>
97  <br><a name="SEC3" href="#TOC1">BUILDING SHARED AND STATIC LIBRARIES</a><br>  <br><a name="SEC3" href="#TOC1">BUILDING SHARED AND STATIC LIBRARIES</a><br>
98  <P>  <P>
# Line 104  strings). You can disable this by adding Line 115  strings). You can disable this by adding
115  </pre>  </pre>
116  to the <b>configure</b> command.  to the <b>configure</b> command.
117  </P>  </P>
118  <br><a name="SEC5" href="#TOC1">UTF-8 and UTF-16 SUPPORT</a><br>  <br><a name="SEC5" href="#TOC1">UTF-8, UTF-16 AND UTF-32 SUPPORT</a><br>
119  <P>  <P>
120  To build PCRE with support for UTF Unicode character strings, add  To build PCRE with support for UTF Unicode character strings, add
121  <pre>  <pre>
122    --enable-utf    --enable-utf
123  </pre>  </pre>
124  to the <b>configure</b> command. This setting applies to both libraries, adding  to the <b>configure</b> command. This setting applies to all three libraries,
125  support for UTF-8 to the 8-bit library and support for UTF-16 to the 16-bit  adding support for UTF-8 to the 8-bit library, support for UTF-16 to the 16-bit
126  library. There are no separate options for enabling UTF-8 and UTF-16  library, and support for UTF-32 to the to the 32-bit library. There are no
127  independently because that would allow ridiculous settings such as requesting  separate options for enabling UTF-8, UTF-16 and UTF-32 independently because
128  UTF-16 support while building only the 8-bit library. It is not possible to  that would allow ridiculous settings such as requesting UTF-16 support while
129  build one library with UTF support and the other without in the same  building only the 8-bit library. It is not possible to build one library with
130  configuration. (For backwards compatibility, --enable-utf8 is a synonym of  UTF support and another without in the same configuration. (For backwards
131  --enable-utf.)  compatibility, --enable-utf8 is a synonym of --enable-utf.)
132  </P>  </P>
133  <P>  <P>
134  Of itself, this setting does not make PCRE treat strings as UTF-8 or UTF-16. As  Of itself, this setting does not make PCRE treat strings as UTF-8, UTF-16 or
135  well as compiling PCRE with this option, you also have have to set the  UTF-32. As well as compiling PCRE with this option, you also have have to set
136  PCRE_UTF8 or PCRE_UTF16 option when you call one of the pattern compiling  the PCRE_UTF8, PCRE_UTF16 or PCRE_UTF32 option (as appropriate) when you call
137  functions.  one of the pattern compiling functions.
138  </P>  </P>
139  <P>  <P>
140  If you set --enable-utf when compiling in an EBCDIC environment, PCRE expects  If you set --enable-utf when compiling in an EBCDIC environment, PCRE expects
# Line 233  to the <b>configure</b> command. Line 244  to the <b>configure</b> command.
244  <P>  <P>
245  Within a compiled pattern, offset values are used to point from one part to  Within a compiled pattern, offset values are used to point from one part to
246  another (for example, from an opening parenthesis to an alternation  another (for example, from an opening parenthesis to an alternation
247  metacharacter). By default, two-byte values are used for these offsets, leading  metacharacter). By default, in the 8-bit and 16-bit libraries, two-byte values
248  to a maximum size for a compiled pattern of around 64K. This is sufficient to  are used for these offsets, leading to a maximum size for a compiled pattern of
249  handle all but the most gigantic patterns. Nevertheless, some people do want to  around 64K. This is sufficient to handle all but the most gigantic patterns.
250  process truly enormous patterns, so it is possible to compile PCRE to use  Nevertheless, some people do want to process truly enormous patterns, so it is
251  three-byte or four-byte offsets by adding a setting such as  possible to compile PCRE to use three-byte or four-byte offsets by adding a
252    setting such as
253  <pre>  <pre>
254    --with-link-size=3    --with-link-size=3
255  </pre>  </pre>
256  to the <b>configure</b> command. The value given must be 2, 3, or 4. For the  to the <b>configure</b> command. The value given must be 2, 3, or 4. For the
257  16-bit library, a value of 3 is rounded up to 4. Using longer offsets slows  16-bit library, a value of 3 is rounded up to 4. In these libraries, using
258  down the operation of PCRE because it has to load additional data when handling  longer offsets slows down the operation of PCRE because it has to load
259  them.  additional data when handling them. For the 32-bit library the value is always
260    4 and cannot be overridden; the value of --with-link-size is ignored.
261  </P>  </P>
262  <br><a name="SEC12" href="#TOC1">AVOIDING EXCESSIVE STACK USAGE</a><br>  <br><a name="SEC12" href="#TOC1">AVOIDING EXCESSIVE STACK USAGE</a><br>
263  <P>  <P>
# Line 337  to the <b>configure</b> command. This se Line 350  to the <b>configure</b> command. This se
350  an EBCDIC environment (for example, an IBM mainframe operating system). The  an EBCDIC environment (for example, an IBM mainframe operating system). The
351  --enable-ebcdic option is incompatible with --enable-utf.  --enable-ebcdic option is incompatible with --enable-utf.
352  </P>  </P>
353    <P>
354    The EBCDIC character that corresponds to an ASCII LF is assumed to have the
355    value 0x15 by default. However, in some EBCDIC environments, 0x25 is used. In
356    such an environment you should use
357    <pre>
358      --enable-ebcdic-nl25
359    </pre>
360    as well as, or instead of, --enable-ebcdic. The EBCDIC character for CR has the
361    same value as in ASCII, namely, 0x0d. Whichever of 0x15 and 0x25 is <i>not</i>
362    chosen as LF is made to correspond to the Unicode NEL character (which, in
363    Unicode, is 0x85).
364    </P>
365    <P>
366    The options that select newline behaviour, such as --enable-newline-is-cr,
367    and equivalent run-time options, refer to these character values in an EBCDIC
368    environment.
369    </P>
370  <br><a name="SEC16" href="#TOC1">PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT</a><br>  <br><a name="SEC16" href="#TOC1">PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT</a><br>
371  <P>  <P>
372  By default, <b>pcregrep</b> reads all files as plain text. You can build it so  By default, <b>pcregrep</b> reads all files as plain text. You can build it so
# Line 396  automatically included, you may need to Line 426  automatically included, you may need to
426  </pre>  </pre>
427  immediately before the <b>configure</b> command.  immediately before the <b>configure</b> command.
428  </P>  </P>
429  <br><a name="SEC19" href="#TOC1">SEE ALSO</a><br>  <br><a name="SEC19" href="#TOC1">DEBUGGING WITH VALGRIND SUPPORT</a><br>
430    <P>
431    By adding the
432    <pre>
433      --enable-valgrind
434    </pre>
435    option to to the <b>configure</b> command, PCRE will use valgrind annotations
436    to mark certain memory regions as unaddressable. This allows it to detect
437    invalid memory accesses, and is mostly useful for debugging PCRE itself.
438    </P>
439    <br><a name="SEC20" href="#TOC1">CODE COVERAGE REPORTING</a><br>
440    <P>
441    If your C compiler is gcc, you can build a version of PCRE that can generate a
442    code coverage report for its test suite. To enable this, you must install
443    <b>lcov</b> version 1.6 or above. Then specify
444    <pre>
445      --enable-coverage
446    </pre>
447    to the <b>configure</b> command and build PCRE in the usual way.
448    </P>
449    <P>
450    Note that using <b>ccache</b> (a caching C compiler) is incompatible with code
451    coverage reporting. If you have configured <b>ccache</b> to run automatically
452    on your system, you must set the environment variable
453    <pre>
454      CCACHE_DISABLE=1
455    </pre>
456    before running <b>make</b> to build PCRE, so that <b>ccache</b> is not used.
457    </P>
458    <P>
459    When --enable-coverage is used, the following addition targets are added to the
460    <i>Makefile</i>:
461    <pre>
462      make coverage
463    </pre>
464    This creates a fresh coverage report for the PCRE test suite. It is equivalent
465    to running "make coverage-reset", "make coverage-baseline", "make check", and
466    then "make coverage-report".
467    <pre>
468      make coverage-reset
469    </pre>
470    This zeroes the coverage counters, but does nothing else.
471    <pre>
472      make coverage-baseline
473    </pre>
474    This captures baseline coverage information.
475    <pre>
476      make coverage-report
477    </pre>
478    This creates the coverage report.
479    <pre>
480      make coverage-clean-report
481    </pre>
482    This removes the generated coverage report without cleaning the coverage data
483    itself.
484    <pre>
485      make coverage-clean-data
486    </pre>
487    This removes the captured coverage data without removing the coverage files
488    created at compile time (*.gcno).
489    <pre>
490      make coverage-clean
491    </pre>
492    This cleans all coverage data including the generated coverage report. For more
493    information about code coverage, see the <b>gcov</b> and <b>lcov</b>
494    documentation.
495    </P>
496    <br><a name="SEC21" href="#TOC1">SEE ALSO</a><br>
497  <P>  <P>
498  <b>pcreapi</b>(3), <b>pcre16</b>, <b>pcre_config</b>(3).  <b>pcreapi</b>(3), <b>pcre16</b>, <b>pcre32</b>, <b>pcre_config</b>(3).
499  </P>  </P>
500  <br><a name="SEC20" href="#TOC1">AUTHOR</a><br>  <br><a name="SEC22" href="#TOC1">AUTHOR</a><br>
501  <P>  <P>
502  Philip Hazel  Philip Hazel
503  <br>  <br>
# Line 409  University Computing Service Line 506  University Computing Service
506  Cambridge CB2 3QH, England.  Cambridge CB2 3QH, England.
507  <br>  <br>
508  </P>  </P>
509  <br><a name="SEC21" href="#TOC1">REVISION</a><br>  <br><a name="SEC23" href="#TOC1">REVISION</a><br>
510  <P>  <P>
511  Last updated: 07 January 2012  Last updated: 30 October 2012
512  <br>  <br>
513  Copyright &copy; 1997-2012 University of Cambridge.  Copyright &copy; 1997-2012 University of Cambridge.
514  <br>  <br>

Legend:
Removed from v.1193  
changed lines
  Added in v.1194

  ViewVC Help
Powered by ViewVC 1.1.5