--- embedaddon/pcre/doc/pcrebuild.3 2012/10/09 09:19:17 1.1.1.3
+++ embedaddon/pcre/doc/pcrebuild.3 2013/07/22 08:25:56 1.1.1.4
@@ -1,23 +1,54 @@
-.TH PCREBUILD 3 "07 January 2012" "PCRE 8.30"
+.TH PCREBUILD 3 "12 May 2013" "PCRE 8.33"
.SH NAME
PCRE - Perl-compatible regular expressions
.
.
+.SH "BUILDING PCRE"
+.rs
+.sp
+PCRE is distributed with a \fBconfigure\fP script that can be used to build the
+library in Unix-like environments using the applications known as Autotools.
+Also in the distribution are files to support building using \fBCMake\fP
+instead of \fBconfigure\fP. The text file
+.\" HTML
+.\"
+\fBREADME\fP
+.\"
+contains general information about building with Autotools (some of which is
+repeated below), and also has some comments about building on various operating
+systems. There is a lot more information about building PCRE without using
+Autotools (including information about using \fBCMake\fP and building "by
+hand") in the text file called
+.\" HTML
+.\"
+\fBNON-AUTOTOOLS-BUILD\fP.
+.\"
+You should consult this file as well as the
+.\" HTML
+.\"
+\fBREADME\fP
+.\"
+file if you are building in a non-Unix-like environment.
+.
+.
.SH "PCRE BUILD-TIME OPTIONS"
.rs
.sp
-This document describes the optional features of PCRE that can be selected when
-the library is compiled. It assumes use of the \fBconfigure\fP script, where
-the optional features are selected or deselected by providing options to
-\fBconfigure\fP before running the \fBmake\fP command. However, the same
-options can be selected in both Unix-like and non-Unix-like environments using
-the GUI facility of \fBcmake-gui\fP if you are using \fBCMake\fP instead of
-\fBconfigure\fP to build PCRE.
+The rest of this document describes the optional features of PCRE that can be
+selected when the library is compiled. It assumes use of the \fBconfigure\fP
+script, where the optional features are selected or deselected by providing
+options to \fBconfigure\fP before running the \fBmake\fP command. However, the
+same options can be selected in both Unix-like and non-Unix-like environments
+using the GUI facility of \fBcmake-gui\fP if you are using \fBCMake\fP instead
+of \fBconfigure\fP to build PCRE.
.P
-There is a lot more information about building PCRE in non-Unix-like
-environments in the file called \fINON_UNIX_USE\fP, which is part of the PCRE
-distribution. You should consult this file as well as the \fIREADME\fP file if
-you are building in a non-Unix-like environment.
+If you are not using Autotools or \fBCMake\fP, option selection can be done by
+editing the \fBconfig.h\fP file, or by passing parameter settings to the
+compiler, as described in
+.\" HTML
+.\"
+\fBNON-AUTOTOOLS-BUILD\fP.
+.\"
.P
The complete list of options for \fBconfigure\fP (which includes the standard
ones such as the selection of the installation directory) can be obtained by
@@ -32,7 +63,7 @@ The following sections include descriptions of options
exists as well, but as it specifies the default, it is not described.
.
.
-.SH "BUILDING 8-BIT and 16-BIT LIBRARIES"
+.SH "BUILDING 8-BIT, 16-BIT AND 32-BIT LIBRARIES"
.rs
.sp
By default, a library called \fBlibpcre\fP is built, containing functions that
@@ -44,20 +75,28 @@ strings, by adding
.sp
--enable-pcre16
.sp
+to the \fBconfigure\fP command. You can also build yet another separate
+library, called \fBlibpcre32\fP, in which strings are contained in vectors of
+32-bit data units and interpreted either as single-unit characters or UTF-32
+strings, by adding
+.sp
+ --enable-pcre32
+.sp
to the \fBconfigure\fP command. If you do not want the 8-bit library, add
.sp
--disable-pcre8
.sp
-as well. At least one of the two libraries must be built. Note that the C++ and
-POSIX wrappers are for the 8-bit library only, and that \fBpcregrep\fP is an
-8-bit program. None of these are built if you select only the 16-bit library.
+as well. At least one of the three libraries must be built. Note that the C++
+and POSIX wrappers are for the 8-bit library only, and that \fBpcregrep\fP is
+an 8-bit program. None of these are built if you select only the 16-bit or
+32-bit libraries.
.
.
.SH "BUILDING SHARED AND STATIC LIBRARIES"
.rs
.sp
-The PCRE building process uses \fBlibtool\fP to build both shared and static
-Unix libraries by default. You can suppress one of these by adding one of
+The Autotools PCRE building process uses \fBlibtool\fP to build both shared and
+static libraries by default. You can suppress one of these by adding one of
.sp
--disable-shared
--disable-static
@@ -78,26 +117,26 @@ strings). You can disable this by adding
to the \fBconfigure\fP command.
.
.
-.SH "UTF-8 and UTF-16 SUPPORT"
+.SH "UTF-8, UTF-16 AND UTF-32 SUPPORT"
.rs
.sp
To build PCRE with support for UTF Unicode character strings, add
.sp
--enable-utf
.sp
-to the \fBconfigure\fP command. This setting applies to both libraries, adding
-support for UTF-8 to the 8-bit library and support for UTF-16 to the 16-bit
-library. There are no separate options for enabling UTF-8 and UTF-16
-independently because that would allow ridiculous settings such as requesting
-UTF-16 support while building only the 8-bit library. It is not possible to
-build one library with UTF support and the other without in the same
-configuration. (For backwards compatibility, --enable-utf8 is a synonym of
---enable-utf.)
+to the \fBconfigure\fP command. This setting applies to all three libraries,
+adding support for UTF-8 to the 8-bit library, support for UTF-16 to the 16-bit
+library, and support for UTF-32 to the to the 32-bit library. There are no
+separate options for enabling UTF-8, UTF-16 and UTF-32 independently because
+that would allow ridiculous settings such as requesting UTF-16 support while
+building only the 8-bit library. It is not possible to build one library with
+UTF support and another without in the same configuration. (For backwards
+compatibility, --enable-utf8 is a synonym of --enable-utf.)
.P
-Of itself, this setting does not make PCRE treat strings as UTF-8 or UTF-16. As
-well as compiling PCRE with this option, you also have have to set the
-PCRE_UTF8 or PCRE_UTF16 option when you call one of the pattern compiling
-functions.
+Of itself, this setting does not make PCRE treat strings as UTF-8, UTF-16 or
+UTF-32. As well as compiling PCRE with this option, you also have have to set
+the PCRE_UTF8, PCRE_UTF16 or PCRE_UTF32 option (as appropriate) when you call
+one of the pattern compiling functions.
.P
If you set --enable-utf when compiling in an EBCDIC environment, PCRE expects
its input to be either ASCII or UTF-8 (depending on the run-time option). It is
@@ -221,18 +260,20 @@ to the \fBconfigure\fP command.
.sp
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 truly enormous patterns, so it is possible to compile PCRE to use
-three-byte or four-byte offsets by adding a setting such as
+metacharacter). By default, in the 8-bit and 16-bit libraries, 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 truly enormous patterns, so it is
+possible to compile PCRE to use three-byte or four-byte offsets by adding a
+setting such as
.sp
--with-link-size=3
.sp
to the \fBconfigure\fP command. The value given must be 2, 3, or 4. For the
-16-bit library, a value of 3 is rounded up to 4. Using longer offsets slows
-down the operation of PCRE because it has to load additional data when handling
-them.
+16-bit library, a value of 3 is rounded up to 4. In these libraries, using
+longer offsets slows down the operation of PCRE because it has to load
+additional data when handling them. For the 32-bit library the value is always
+4 and cannot be overridden; the value of --with-link-size is ignored.
.
.
.SH "AVOIDING EXCESSIVE STACK USAGE"
@@ -334,6 +375,21 @@ to the \fBconfigure\fP command. This setting implies
--enable-rebuild-chartables. You should only use it if you know that you are in
an EBCDIC environment (for example, an IBM mainframe operating system). The
--enable-ebcdic option is incompatible with --enable-utf.
+.P
+The EBCDIC character that corresponds to an ASCII LF is assumed to have the
+value 0x15 by default. However, in some EBCDIC environments, 0x25 is used. In
+such an environment you should use
+.sp
+ --enable-ebcdic-nl25
+.sp
+as well as, or instead of, --enable-ebcdic. The EBCDIC character for CR has the
+same value as in ASCII, namely, 0x0d. Whichever of 0x15 and 0x25 is \fInot\fP
+chosen as LF is made to correspond to the Unicode NEL character (which, in
+Unicode, is 0x85).
+.P
+The options that select newline behaviour, such as --enable-newline-is-cr,
+and equivalent run-time options, refer to these character values in an EBCDIC
+environment.
.
.
.SH "PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT"
@@ -400,10 +456,79 @@ automatically included, you may need to add something
immediately before the \fBconfigure\fP command.
.
.
+.SH "DEBUGGING WITH VALGRIND SUPPORT"
+.rs
+.sp
+By adding the
+.sp
+ --enable-valgrind
+.sp
+option to to the \fBconfigure\fP command, PCRE will use valgrind annotations
+to mark certain memory regions as unaddressable. This allows it to detect
+invalid memory accesses, and is mostly useful for debugging PCRE itself.
+.
+.
+.SH "CODE COVERAGE REPORTING"
+.rs
+.sp
+If your C compiler is gcc, you can build a version of PCRE that can generate a
+code coverage report for its test suite. To enable this, you must install
+\fBlcov\fP version 1.6 or above. Then specify
+.sp
+ --enable-coverage
+.sp
+to the \fBconfigure\fP command and build PCRE in the usual way.
+.P
+Note that using \fBccache\fP (a caching C compiler) is incompatible with code
+coverage reporting. If you have configured \fBccache\fP to run automatically
+on your system, you must set the environment variable
+.sp
+ CCACHE_DISABLE=1
+.sp
+before running \fBmake\fP to build PCRE, so that \fBccache\fP is not used.
+.P
+When --enable-coverage is used, the following addition targets are added to the
+\fIMakefile\fP:
+.sp
+ make coverage
+.sp
+This creates a fresh coverage report for the PCRE test suite. It is equivalent
+to running "make coverage-reset", "make coverage-baseline", "make check", and
+then "make coverage-report".
+.sp
+ make coverage-reset
+.sp
+This zeroes the coverage counters, but does nothing else.
+.sp
+ make coverage-baseline
+.sp
+This captures baseline coverage information.
+.sp
+ make coverage-report
+.sp
+This creates the coverage report.
+.sp
+ make coverage-clean-report
+.sp
+This removes the generated coverage report without cleaning the coverage data
+itself.
+.sp
+ make coverage-clean-data
+.sp
+This removes the captured coverage data without removing the coverage files
+created at compile time (*.gcno).
+.sp
+ make coverage-clean
+.sp
+This cleans all coverage data including the generated coverage report. For more
+information about code coverage, see the \fBgcov\fP and \fBlcov\fP
+documentation.
+.
+.
.SH "SEE ALSO"
.rs
.sp
-\fBpcreapi\fP(3), \fBpcre16\fP, \fBpcre_config\fP(3).
+\fBpcreapi\fP(3), \fBpcre16\fP, \fBpcre32\fP, \fBpcre_config\fP(3).
.
.
.SH AUTHOR
@@ -420,6 +545,6 @@ Cambridge CB2 3QH, England.
.rs
.sp
.nf
-Last updated: 07 January 2012
-Copyright (c) 1997-2012 University of Cambridge.
+Last updated: 12 May 2013
+Copyright (c) 1997-2013 University of Cambridge.
.fi