--- 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