Annotation of embedaddon/pcre/doc/html/README.txt, revision 1.1
1.1 ! misho 1: README file for PCRE (Perl-compatible regular expression library)
! 2: -----------------------------------------------------------------
! 3:
! 4: The latest release of PCRE is always available in three alternative formats
! 5: from:
! 6:
! 7: ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre-xxx.tar.gz
! 8: ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre-xxx.tar.bz2
! 9: ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre-xxx.zip
! 10:
! 11: There is a mailing list for discussion about the development of PCRE at
! 12:
! 13: pcre-dev@exim.org
! 14:
! 15: Please read the NEWS file if you are upgrading from a previous release.
! 16: The contents of this README file are:
! 17:
! 18: The PCRE APIs
! 19: Documentation for PCRE
! 20: Contributions by users of PCRE
! 21: Building PCRE on non-Unix-like systems
! 22: Building PCRE without using autotools
! 23: Building PCRE using autotools
! 24: Retrieving configuration information
! 25: Shared libraries
! 26: Cross-compiling using autotools
! 27: Using HP's ANSI C++ compiler (aCC)
! 28: Compiling in Tru64 using native compilers
! 29: Using Sun's compilers for Solaris
! 30: Using PCRE from MySQL
! 31: Making new tarballs
! 32: Testing PCRE
! 33: Character tables
! 34: File manifest
! 35:
! 36:
! 37: The PCRE APIs
! 38: -------------
! 39:
! 40: PCRE is written in C, and it has its own API. There are three sets of
! 41: functions, one for the 8-bit library, which processes strings of bytes, one for
! 42: the 16-bit library, which processes strings of 16-bit values, and one for the
! 43: 32-bit library, which processes strings of 32-bit values. The distribution also
! 44: includes a set of C++ wrapper functions (see the pcrecpp man page for details),
! 45: courtesy of Google Inc., which can be used to call the 8-bit PCRE library from
! 46: C++.
! 47:
! 48: In addition, there is a set of C wrapper functions (again, just for the 8-bit
! 49: library) that are based on the POSIX regular expression API (see the pcreposix
! 50: man page). These end up in the library called libpcreposix. Note that this just
! 51: provides a POSIX calling interface to PCRE; the regular expressions themselves
! 52: still follow Perl syntax and semantics. The POSIX API is restricted, and does
! 53: not give full access to all of PCRE's facilities.
! 54:
! 55: The header file for the POSIX-style functions is called pcreposix.h. The
! 56: official POSIX name is regex.h, but I did not want to risk possible problems
! 57: with existing files of that name by distributing it that way. To use PCRE with
! 58: an existing program that uses the POSIX API, pcreposix.h will have to be
! 59: renamed or pointed at by a link.
! 60:
! 61: If you are using the POSIX interface to PCRE and there is already a POSIX regex
! 62: library installed on your system, as well as worrying about the regex.h header
! 63: file (as mentioned above), you must also take care when linking programs to
! 64: ensure that they link with PCRE's libpcreposix library. Otherwise they may pick
! 65: up the POSIX functions of the same name from the other library.
! 66:
! 67: One way of avoiding this confusion is to compile PCRE with the addition of
! 68: -Dregcomp=PCREregcomp (and similarly for the other POSIX functions) to the
! 69: compiler flags (CFLAGS if you are using "configure" -- see below). This has the
! 70: effect of renaming the functions so that the names no longer clash. Of course,
! 71: you have to do the same thing for your applications, or write them using the
! 72: new names.
! 73:
! 74:
! 75: Documentation for PCRE
! 76: ----------------------
! 77:
! 78: If you install PCRE in the normal way on a Unix-like system, you will end up
! 79: with a set of man pages whose names all start with "pcre". The one that is just
! 80: called "pcre" lists all the others. In addition to these man pages, the PCRE
! 81: documentation is supplied in two other forms:
! 82:
! 83: 1. There are files called doc/pcre.txt, doc/pcregrep.txt, and
! 84: doc/pcretest.txt in the source distribution. The first of these is a
! 85: concatenation of the text forms of all the section 3 man pages except
! 86: those that summarize individual functions. The other two are the text
! 87: forms of the section 1 man pages for the pcregrep and pcretest commands.
! 88: These text forms are provided for ease of scanning with text editors or
! 89: similar tools. They are installed in <prefix>/share/doc/pcre, where
! 90: <prefix> is the installation prefix (defaulting to /usr/local).
! 91:
! 92: 2. A set of files containing all the documentation in HTML form, hyperlinked
! 93: in various ways, and rooted in a file called index.html, is distributed in
! 94: doc/html and installed in <prefix>/share/doc/pcre/html.
! 95:
! 96: Users of PCRE have contributed files containing the documentation for various
! 97: releases in CHM format. These can be found in the Contrib directory of the FTP
! 98: site (see next section).
! 99:
! 100:
! 101: Contributions by users of PCRE
! 102: ------------------------------
! 103:
! 104: You can find contributions from PCRE users in the directory
! 105:
! 106: ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/Contrib
! 107:
! 108: There is a README file giving brief descriptions of what they are. Some are
! 109: complete in themselves; others are pointers to URLs containing relevant files.
! 110: Some of this material is likely to be well out-of-date. Several of the earlier
! 111: contributions provided support for compiling PCRE on various flavours of
! 112: Windows (I myself do not use Windows). Nowadays there is more Windows support
! 113: in the standard distribution, so these contibutions have been archived.
! 114:
! 115:
! 116: Building PCRE on non-Unix-like systems
! 117: --------------------------------------
! 118:
! 119: For a non-Unix-like system, please read the comments in the file
! 120: NON-AUTOTOOLS-BUILD, though if your system supports the use of "configure" and
! 121: "make" you may be able to build PCRE using autotools in the same way as for
! 122: many Unix-like systems.
! 123:
! 124: PCRE can also be configured using the GUI facility provided by CMake's
! 125: cmake-gui command. This creates Makefiles, solution files, etc. The file
! 126: NON-AUTOTOOLS-BUILD has information about CMake.
! 127:
! 128: PCRE has been compiled on many different operating systems. It should be
! 129: straightforward to build PCRE on any system that has a Standard C compiler and
! 130: library, because it uses only Standard C functions.
! 131:
! 132:
! 133: Building PCRE without using autotools
! 134: -------------------------------------
! 135:
! 136: The use of autotools (in particular, libtool) is problematic in some
! 137: environments, even some that are Unix or Unix-like. See the NON-AUTOTOOLS-BUILD
! 138: file for ways of building PCRE without using autotools.
! 139:
! 140:
! 141: Building PCRE using autotools
! 142: -----------------------------
! 143:
! 144: If you are using HP's ANSI C++ compiler (aCC), please see the special note
! 145: in the section entitled "Using HP's ANSI C++ compiler (aCC)" below.
! 146:
! 147: The following instructions assume the use of the widely used "configure; make;
! 148: make install" (autotools) process.
! 149:
! 150: To build PCRE on system that supports autotools, first run the "configure"
! 151: command from the PCRE distribution directory, with your current directory set
! 152: to the directory where you want the files to be created. This command is a
! 153: standard GNU "autoconf" configuration script, for which generic instructions
! 154: are supplied in the file INSTALL.
! 155:
! 156: Most commonly, people build PCRE within its own distribution directory, and in
! 157: this case, on many systems, just running "./configure" is sufficient. However,
! 158: the usual methods of changing standard defaults are available. For example:
! 159:
! 160: CFLAGS='-O2 -Wall' ./configure --prefix=/opt/local
! 161:
! 162: This command specifies that the C compiler should be run with the flags '-O2
! 163: -Wall' instead of the default, and that "make install" should install PCRE
! 164: under /opt/local instead of the default /usr/local.
! 165:
! 166: If you want to build in a different directory, just run "configure" with that
! 167: directory as current. For example, suppose you have unpacked the PCRE source
! 168: into /source/pcre/pcre-xxx, but you want to build it in /build/pcre/pcre-xxx:
! 169:
! 170: cd /build/pcre/pcre-xxx
! 171: /source/pcre/pcre-xxx/configure
! 172:
! 173: PCRE is written in C and is normally compiled as a C library. However, it is
! 174: possible to build it as a C++ library, though the provided building apparatus
! 175: does not have any features to support this.
! 176:
! 177: There are some optional features that can be included or omitted from the PCRE
! 178: library. They are also documented in the pcrebuild man page.
! 179:
! 180: . By default, both shared and static libraries are built. You can change this
! 181: by adding one of these options to the "configure" command:
! 182:
! 183: --disable-shared
! 184: --disable-static
! 185:
! 186: (See also "Shared libraries on Unix-like systems" below.)
! 187:
! 188: . By default, only the 8-bit library is built. If you add --enable-pcre16 to
! 189: the "configure" command, the 16-bit library is also built. If you add
! 190: --enable-pcre32 to the "configure" command, the 32-bit library is also built.
! 191: If you want only the 16-bit or 32-bit library, use --disable-pcre8 to disable
! 192: building the 8-bit library.
! 193:
! 194: . If you are building the 8-bit library and want to suppress the building of
! 195: the C++ wrapper library, you can add --disable-cpp to the "configure"
! 196: command. Otherwise, when "configure" is run without --disable-pcre8, it will
! 197: try to find a C++ compiler and C++ header files, and if it succeeds, it will
! 198: try to build the C++ wrapper.
! 199:
! 200: . If you want to include support for just-in-time compiling, which can give
! 201: large performance improvements on certain platforms, add --enable-jit to the
! 202: "configure" command. This support is available only for certain hardware
! 203: architectures. If you try to enable it on an unsupported architecture, there
! 204: will be a compile time error.
! 205:
! 206: . When JIT support is enabled, pcregrep automatically makes use of it, unless
! 207: you add --disable-pcregrep-jit to the "configure" command.
! 208:
! 209: . If you want to make use of the support for UTF-8 Unicode character strings in
! 210: the 8-bit library, or UTF-16 Unicode character strings in the 16-bit library,
! 211: or UTF-32 Unicode character strings in the 32-bit library, you must add
! 212: --enable-utf to the "configure" command. Without it, the code for handling
! 213: UTF-8, UTF-16 and UTF-8 is not included in the relevant library. Even
! 214: when --enable-utf is included, the use of a UTF encoding still has to be
! 215: enabled by an option at run time. When PCRE is compiled with this option, its
! 216: input can only either be ASCII or UTF-8/16/32, even when running on EBCDIC
! 217: platforms. It is not possible to use both --enable-utf and --enable-ebcdic at
! 218: the same time.
! 219:
! 220: . There are no separate options for enabling UTF-8, UTF-16 and UTF-32
! 221: independently because that would allow ridiculous settings such as requesting
! 222: UTF-16 support while building only the 8-bit library. However, the option
! 223: --enable-utf8 is retained for backwards compatibility with earlier releases
! 224: that did not support 16-bit or 32-bit character strings. It is synonymous with
! 225: --enable-utf. It is not possible to configure one library with UTF support
! 226: and the other without in the same configuration.
! 227:
! 228: . If, in addition to support for UTF-8/16/32 character strings, you want to
! 229: include support for the \P, \p, and \X sequences that recognize Unicode
! 230: character properties, you must add --enable-unicode-properties to the
! 231: "configure" command. This adds about 30K to the size of the library (in the
! 232: form of a property table); only the basic two-letter properties such as Lu
! 233: are supported.
! 234:
! 235: . You can build PCRE to recognize either CR or LF or the sequence CRLF or any
! 236: of the preceding, or any of the Unicode newline sequences as indicating the
! 237: end of a line. Whatever you specify at build time is the default; the caller
! 238: of PCRE can change the selection at run time. The default newline indicator
! 239: is a single LF character (the Unix standard). You can specify the default
! 240: newline indicator by adding --enable-newline-is-cr or --enable-newline-is-lf
! 241: or --enable-newline-is-crlf or --enable-newline-is-anycrlf or
! 242: --enable-newline-is-any to the "configure" command, respectively.
! 243:
! 244: If you specify --enable-newline-is-cr or --enable-newline-is-crlf, some of
! 245: the standard tests will fail, because the lines in the test files end with
! 246: LF. Even if the files are edited to change the line endings, there are likely
! 247: to be some failures. With --enable-newline-is-anycrlf or
! 248: --enable-newline-is-any, many tests should succeed, but there may be some
! 249: failures.
! 250:
! 251: . By default, the sequence \R in a pattern matches any Unicode line ending
! 252: sequence. This is independent of the option specifying what PCRE considers to
! 253: be the end of a line (see above). However, the caller of PCRE can restrict \R
! 254: to match only CR, LF, or CRLF. You can make this the default by adding
! 255: --enable-bsr-anycrlf to the "configure" command (bsr = "backslash R").
! 256:
! 257: . When called via the POSIX interface, PCRE uses malloc() to get additional
! 258: storage for processing capturing parentheses if there are more than 10 of
! 259: them in a pattern. You can increase this threshold by setting, for example,
! 260:
! 261: --with-posix-malloc-threshold=20
! 262:
! 263: on the "configure" command.
! 264:
! 265: . PCRE has a counter that can be set to limit the amount of resources it uses.
! 266: If the limit is exceeded during a match, the match fails. The default is ten
! 267: million. You can change the default by setting, for example,
! 268:
! 269: --with-match-limit=500000
! 270:
! 271: on the "configure" command. This is just the default; individual calls to
! 272: pcre_exec() can supply their own value. There is more discussion on the
! 273: pcreapi man page.
! 274:
! 275: . There is a separate counter that limits the depth of recursive function calls
! 276: during a matching process. This also has a default of ten million, which is
! 277: essentially "unlimited". You can change the default by setting, for example,
! 278:
! 279: --with-match-limit-recursion=500000
! 280:
! 281: Recursive function calls use up the runtime stack; running out of stack can
! 282: cause programs to crash in strange ways. There is a discussion about stack
! 283: sizes in the pcrestack man page.
! 284:
! 285: . The default maximum compiled pattern size is around 64K. You can increase
! 286: this by adding --with-link-size=3 to the "configure" command. In the 8-bit
! 287: library, PCRE then uses three bytes instead of two for offsets to different
! 288: parts of the compiled pattern. In the 16-bit library, --with-link-size=3 is
! 289: the same as --with-link-size=4, which (in both libraries) uses four-byte
! 290: offsets. Increasing the internal link size reduces performance. In the 32-bit
! 291: library, the only supported link size is 4.
! 292:
! 293: . You can build PCRE so that its internal match() function that is called from
! 294: pcre_exec() does not call itself recursively. Instead, it uses memory blocks
! 295: obtained from the heap via the special functions pcre_stack_malloc() and
! 296: pcre_stack_free() to save data that would otherwise be saved on the stack. To
! 297: build PCRE like this, use
! 298:
! 299: --disable-stack-for-recursion
! 300:
! 301: on the "configure" command. PCRE runs more slowly in this mode, but it may be
! 302: necessary in environments with limited stack sizes. This applies only to the
! 303: normal execution of the pcre_exec() function; if JIT support is being
! 304: successfully used, it is not relevant. Equally, it does not apply to
! 305: pcre_dfa_exec(), which does not use deeply nested recursion. There is a
! 306: discussion about stack sizes in the pcrestack man page.
! 307:
! 308: . For speed, PCRE uses four tables for manipulating and identifying characters
! 309: whose code point values are less than 256. By default, it uses a set of
! 310: tables for ASCII encoding that is part of the distribution. If you specify
! 311:
! 312: --enable-rebuild-chartables
! 313:
! 314: a program called dftables is compiled and run in the default C locale when
! 315: you obey "make". It builds a source file called pcre_chartables.c. If you do
! 316: not specify this option, pcre_chartables.c is created as a copy of
! 317: pcre_chartables.c.dist. See "Character tables" below for further information.
! 318:
! 319: . It is possible to compile PCRE for use on systems that use EBCDIC as their
! 320: character code (as opposed to ASCII/Unicode) by specifying
! 321:
! 322: --enable-ebcdic
! 323:
! 324: This automatically implies --enable-rebuild-chartables (see above). However,
! 325: when PCRE is built this way, it always operates in EBCDIC. It cannot support
! 326: both EBCDIC and UTF-8/16/32. There is a second option, --enable-ebcdic-nl25,
! 327: which specifies that the code value for the EBCDIC NL character is 0x25
! 328: instead of the default 0x15.
! 329:
! 330: . In environments where valgrind is installed, if you specify
! 331:
! 332: --enable-valgrind
! 333:
! 334: PCRE will use valgrind annotations to mark certain memory regions as
! 335: unaddressable. This allows it to detect invalid memory accesses, and is
! 336: mostly useful for debugging PCRE itself.
! 337:
! 338: . In environments where the gcc compiler is used and lcov version 1.6 or above
! 339: is installed, if you specify
! 340:
! 341: --enable-coverage
! 342:
! 343: the build process implements a code coverage report for the test suite. The
! 344: report is generated by running "make coverage". If ccache is installed on
! 345: your system, it must be disabled when building PCRE for coverage reporting.
! 346: You can do this by setting the environment variable CCACHE_DISABLE=1 before
! 347: running "make" to build PCRE.
! 348:
! 349: . The pcregrep program currently supports only 8-bit data files, and so
! 350: requires the 8-bit PCRE library. It is possible to compile pcregrep to use
! 351: libz and/or libbz2, in order to read .gz and .bz2 files (respectively), by
! 352: specifying one or both of
! 353:
! 354: --enable-pcregrep-libz
! 355: --enable-pcregrep-libbz2
! 356:
! 357: Of course, the relevant libraries must be installed on your system.
! 358:
! 359: . The default size of internal buffer used by pcregrep can be set by, for
! 360: example:
! 361:
! 362: --with-pcregrep-bufsize=50K
! 363:
! 364: The default value is 20K.
! 365:
! 366: . It is possible to compile pcretest so that it links with the libreadline
! 367: or libedit libraries, by specifying, respectively,
! 368:
! 369: --enable-pcretest-libreadline or --enable-pcretest-libedit
! 370:
! 371: If this is done, when pcretest's input is from a terminal, it reads it using
! 372: the readline() function. This provides line-editing and history facilities.
! 373: Note that libreadline is GPL-licenced, so if you distribute a binary of
! 374: pcretest linked in this way, there may be licensing issues. These can be
! 375: avoided by linking with libedit (which has a BSD licence) instead.
! 376:
! 377: Enabling libreadline causes the -lreadline option to be added to the pcretest
! 378: build. In many operating environments with a sytem-installed readline
! 379: library this is sufficient. However, in some environments (e.g. if an
! 380: unmodified distribution version of readline is in use), it may be necessary
! 381: to specify something like LIBS="-lncurses" as well. This is because, to quote
! 382: the readline INSTALL, "Readline uses the termcap functions, but does not link
! 383: with the termcap or curses library itself, allowing applications which link
! 384: with readline the to choose an appropriate library." If you get error
! 385: messages about missing functions tgetstr, tgetent, tputs, tgetflag, or tgoto,
! 386: this is the problem, and linking with the ncurses library should fix it.
! 387:
! 388: The "configure" script builds the following files for the basic C library:
! 389:
! 390: . Makefile the makefile that builds the library
! 391: . config.h build-time configuration options for the library
! 392: . pcre.h the public PCRE header file
! 393: . pcre-config script that shows the building settings such as CFLAGS
! 394: that were set for "configure"
! 395: . libpcre.pc ) data for the pkg-config command
! 396: . libpcre16.pc )
! 397: . libpcre32.pc )
! 398: . libpcreposix.pc )
! 399: . libtool script that builds shared and/or static libraries
! 400:
! 401: Versions of config.h and pcre.h are distributed in the PCRE tarballs under the
! 402: names config.h.generic and pcre.h.generic. These are provided for those who
! 403: have to built PCRE without using "configure" or CMake. If you use "configure"
! 404: or CMake, the .generic versions are not used.
! 405:
! 406: When building the 8-bit library, if a C++ compiler is found, the following
! 407: files are also built:
! 408:
! 409: . libpcrecpp.pc data for the pkg-config command
! 410: . pcrecpparg.h header file for calling PCRE via the C++ wrapper
! 411: . pcre_stringpiece.h header for the C++ "stringpiece" functions
! 412:
! 413: The "configure" script also creates config.status, which is an executable
! 414: script that can be run to recreate the configuration, and config.log, which
! 415: contains compiler output from tests that "configure" runs.
! 416:
! 417: Once "configure" has run, you can run "make". This builds the the libraries
! 418: libpcre, libpcre16 and/or libpcre32, and a test program called pcretest. If you
! 419: enabled JIT support with --enable-jit, a test program called pcre_jit_test is
! 420: built as well.
! 421:
! 422: If the 8-bit library is built, libpcreposix and the pcregrep command are also
! 423: built, and if a C++ compiler was found on your system, and you did not disable
! 424: it with --disable-cpp, "make" builds the C++ wrapper library, which is called
! 425: libpcrecpp, as well as some test programs called pcrecpp_unittest,
! 426: pcre_scanner_unittest, and pcre_stringpiece_unittest.
! 427:
! 428: The command "make check" runs all the appropriate tests. Details of the PCRE
! 429: tests are given below in a separate section of this document.
! 430:
! 431: You can use "make install" to install PCRE into live directories on your
! 432: system. The following are installed (file names are all relative to the
! 433: <prefix> that is set when "configure" is run):
! 434:
! 435: Commands (bin):
! 436: pcretest
! 437: pcregrep (if 8-bit support is enabled)
! 438: pcre-config
! 439:
! 440: Libraries (lib):
! 441: libpcre16 (if 16-bit support is enabled)
! 442: libpcre32 (if 32-bit support is enabled)
! 443: libpcre (if 8-bit support is enabled)
! 444: libpcreposix (if 8-bit support is enabled)
! 445: libpcrecpp (if 8-bit and C++ support is enabled)
! 446:
! 447: Configuration information (lib/pkgconfig):
! 448: libpcre16.pc
! 449: libpcre32.pc
! 450: libpcre.pc
! 451: libpcreposix.pc
! 452: libpcrecpp.pc (if C++ support is enabled)
! 453:
! 454: Header files (include):
! 455: pcre.h
! 456: pcreposix.h
! 457: pcre_scanner.h )
! 458: pcre_stringpiece.h ) if C++ support is enabled
! 459: pcrecpp.h )
! 460: pcrecpparg.h )
! 461:
! 462: Man pages (share/man/man{1,3}):
! 463: pcregrep.1
! 464: pcretest.1
! 465: pcre-config.1
! 466: pcre.3
! 467: pcre*.3 (lots more pages, all starting "pcre")
! 468:
! 469: HTML documentation (share/doc/pcre/html):
! 470: index.html
! 471: *.html (lots more pages, hyperlinked from index.html)
! 472:
! 473: Text file documentation (share/doc/pcre):
! 474: AUTHORS
! 475: COPYING
! 476: ChangeLog
! 477: LICENCE
! 478: NEWS
! 479: README
! 480: pcre.txt (a concatenation of the man(3) pages)
! 481: pcretest.txt the pcretest man page
! 482: pcregrep.txt the pcregrep man page
! 483: pcre-config.txt the pcre-config man page
! 484:
! 485: If you want to remove PCRE from your system, you can run "make uninstall".
! 486: This removes all the files that "make install" installed. However, it does not
! 487: remove any directories, because these are often shared with other programs.
! 488:
! 489:
! 490: Retrieving configuration information
! 491: ------------------------------------
! 492:
! 493: Running "make install" installs the command pcre-config, which can be used to
! 494: recall information about the PCRE configuration and installation. For example:
! 495:
! 496: pcre-config --version
! 497:
! 498: prints the version number, and
! 499:
! 500: pcre-config --libs
! 501:
! 502: outputs information about where the library is installed. This command can be
! 503: included in makefiles for programs that use PCRE, saving the programmer from
! 504: having to remember too many details.
! 505:
! 506: The pkg-config command is another system for saving and retrieving information
! 507: about installed libraries. Instead of separate commands for each library, a
! 508: single command is used. For example:
! 509:
! 510: pkg-config --cflags pcre
! 511:
! 512: The data is held in *.pc files that are installed in a directory called
! 513: <prefix>/lib/pkgconfig.
! 514:
! 515:
! 516: Shared libraries
! 517: ----------------
! 518:
! 519: The default distribution builds PCRE as shared libraries and static libraries,
! 520: as long as the operating system supports shared libraries. Shared library
! 521: support relies on the "libtool" script which is built as part of the
! 522: "configure" process.
! 523:
! 524: The libtool script is used to compile and link both shared and static
! 525: libraries. They are placed in a subdirectory called .libs when they are newly
! 526: built. The programs pcretest and pcregrep are built to use these uninstalled
! 527: libraries (by means of wrapper scripts in the case of shared libraries). When
! 528: you use "make install" to install shared libraries, pcregrep and pcretest are
! 529: automatically re-built to use the newly installed shared libraries before being
! 530: installed themselves. However, the versions left in the build directory still
! 531: use the uninstalled libraries.
! 532:
! 533: To build PCRE using static libraries only you must use --disable-shared when
! 534: configuring it. For example:
! 535:
! 536: ./configure --prefix=/usr/gnu --disable-shared
! 537:
! 538: Then run "make" in the usual way. Similarly, you can use --disable-static to
! 539: build only shared libraries.
! 540:
! 541:
! 542: Cross-compiling using autotools
! 543: -------------------------------
! 544:
! 545: You can specify CC and CFLAGS in the normal way to the "configure" command, in
! 546: order to cross-compile PCRE for some other host. However, you should NOT
! 547: specify --enable-rebuild-chartables, because if you do, the dftables.c source
! 548: file is compiled and run on the local host, in order to generate the inbuilt
! 549: character tables (the pcre_chartables.c file). This will probably not work,
! 550: because dftables.c needs to be compiled with the local compiler, not the cross
! 551: compiler.
! 552:
! 553: When --enable-rebuild-chartables is not specified, pcre_chartables.c is created
! 554: by making a copy of pcre_chartables.c.dist, which is a default set of tables
! 555: that assumes ASCII code. Cross-compiling with the default tables should not be
! 556: a problem.
! 557:
! 558: If you need to modify the character tables when cross-compiling, you should
! 559: move pcre_chartables.c.dist out of the way, then compile dftables.c by hand and
! 560: run it on the local host to make a new version of pcre_chartables.c.dist.
! 561: Then when you cross-compile PCRE this new version of the tables will be used.
! 562:
! 563:
! 564: Using HP's ANSI C++ compiler (aCC)
! 565: ----------------------------------
! 566:
! 567: Unless C++ support is disabled by specifying the "--disable-cpp" option of the
! 568: "configure" script, you must include the "-AA" option in the CXXFLAGS
! 569: environment variable in order for the C++ components to compile correctly.
! 570:
! 571: Also, note that the aCC compiler on PA-RISC platforms may have a defect whereby
! 572: needed libraries fail to get included when specifying the "-AA" compiler
! 573: option. If you experience unresolved symbols when linking the C++ programs,
! 574: use the workaround of specifying the following environment variable prior to
! 575: running the "configure" script:
! 576:
! 577: CXXLDFLAGS="-lstd_v2 -lCsup_v2"
! 578:
! 579:
! 580: Compiling in Tru64 using native compilers
! 581: -----------------------------------------
! 582:
! 583: The following error may occur when compiling with native compilers in the Tru64
! 584: operating system:
! 585:
! 586: CXX libpcrecpp_la-pcrecpp.lo
! 587: cxx: Error: /usr/lib/cmplrs/cxx/V7.1-006/include/cxx/iosfwd, line 58: #error
! 588: directive: "cannot include iosfwd -- define __USE_STD_IOSTREAM to
! 589: override default - see section 7.1.2 of the C++ Using Guide"
! 590: #error "cannot include iosfwd -- define __USE_STD_IOSTREAM to override default
! 591: - see section 7.1.2 of the C++ Using Guide"
! 592:
! 593: This may be followed by other errors, complaining that 'namespace "std" has no
! 594: member'. The solution to this is to add the line
! 595:
! 596: #define __USE_STD_IOSTREAM 1
! 597:
! 598: to the config.h file.
! 599:
! 600:
! 601: Using Sun's compilers for Solaris
! 602: ---------------------------------
! 603:
! 604: A user reports that the following configurations work on Solaris 9 sparcv9 and
! 605: Solaris 9 x86 (32-bit):
! 606:
! 607: Solaris 9 sparcv9: ./configure --disable-cpp CC=/bin/cc CFLAGS="-m64 -g"
! 608: Solaris 9 x86: ./configure --disable-cpp CC=/bin/cc CFLAGS="-g"
! 609:
! 610:
! 611: Using PCRE from MySQL
! 612: ---------------------
! 613:
! 614: On systems where both PCRE and MySQL are installed, it is possible to make use
! 615: of PCRE from within MySQL, as an alternative to the built-in pattern matching.
! 616: There is a web page that tells you how to do this:
! 617:
! 618: http://www.mysqludf.org/lib_mysqludf_preg/index.php
! 619:
! 620:
! 621: Making new tarballs
! 622: -------------------
! 623:
! 624: The command "make dist" creates three PCRE tarballs, in tar.gz, tar.bz2, and
! 625: zip formats. The command "make distcheck" does the same, but then does a trial
! 626: build of the new distribution to ensure that it works.
! 627:
! 628: If you have modified any of the man page sources in the doc directory, you
! 629: should first run the PrepareRelease script before making a distribution. This
! 630: script creates the .txt and HTML forms of the documentation from the man pages.
! 631:
! 632:
! 633: Testing PCRE
! 634: ------------
! 635:
! 636: To test the basic PCRE library on a Unix-like system, run the RunTest script.
! 637: There is another script called RunGrepTest that tests the options of the
! 638: pcregrep command. If the C++ wrapper library is built, three test programs
! 639: called pcrecpp_unittest, pcre_scanner_unittest, and pcre_stringpiece_unittest
! 640: are also built. When JIT support is enabled, another test program called
! 641: pcre_jit_test is built.
! 642:
! 643: Both the scripts and all the program tests are run if you obey "make check" or
! 644: "make test". For other environments, see the instructions in
! 645: NON-AUTOTOOLS-BUILD.
! 646:
! 647: The RunTest script runs the pcretest test program (which is documented in its
! 648: own man page) on each of the relevant testinput files in the testdata
! 649: directory, and compares the output with the contents of the corresponding
! 650: testoutput files. RunTest uses a file called testtry to hold the main output
! 651: from pcretest. Other files whose names begin with "test" are used as working
! 652: files in some tests.
! 653:
! 654: Some tests are relevant only when certain build-time options were selected. For
! 655: example, the tests for UTF-8/16/32 support are run only if --enable-utf was
! 656: used. RunTest outputs a comment when it skips a test.
! 657:
! 658: Many of the tests that are not skipped are run up to three times. The second
! 659: run forces pcre_study() to be called for all patterns except for a few in some
! 660: tests that are marked "never study" (see the pcretest program for how this is
! 661: done). If JIT support is available, the non-DFA tests are run a third time,
! 662: this time with a forced pcre_study() with the PCRE_STUDY_JIT_COMPILE option.
! 663: This testing can be suppressed by putting "nojit" on the RunTest command line.
! 664:
! 665: The entire set of tests is run once for each of the 8-bit, 16-bit and 32-bit
! 666: libraries that are enabled. If you want to run just one set of tests, call
! 667: RunTest with either the -8, -16 or -32 option.
! 668:
! 669: If valgrind is installed, you can run the tests under it by putting "valgrind"
! 670: on the RunTest command line. To run pcretest on just one or more specific test
! 671: files, give their numbers as arguments to RunTest, for example:
! 672:
! 673: RunTest 2 7 11
! 674:
! 675: You can also specify ranges of tests such as 3-6 or 3- (meaning 3 to the
! 676: end), or a number preceded by ~ to exclude a test. For example:
! 677:
! 678: Runtest 3-15 ~10
! 679:
! 680: This runs tests 3 to 15, excluding test 10, and just ~13 runs all the tests
! 681: except test 13. Whatever order the arguments are in, the tests are always run
! 682: in numerical order.
! 683:
! 684: You can also call RunTest with the single argument "list" to cause it to output
! 685: a list of tests.
! 686:
! 687: The first test file can be fed directly into the perltest.pl script to check
! 688: that Perl gives the same results. The only difference you should see is in the
! 689: first few lines, where the Perl version is given instead of the PCRE version.
! 690:
! 691: The second set of tests check pcre_fullinfo(), pcre_study(),
! 692: pcre_copy_substring(), pcre_get_substring(), pcre_get_substring_list(), error
! 693: detection, and run-time flags that are specific to PCRE, as well as the POSIX
! 694: wrapper API. It also uses the debugging flags to check some of the internals of
! 695: pcre_compile().
! 696:
! 697: If you build PCRE with a locale setting that is not the standard C locale, the
! 698: character tables may be different (see next paragraph). In some cases, this may
! 699: cause failures in the second set of tests. For example, in a locale where the
! 700: isprint() function yields TRUE for characters in the range 128-255, the use of
! 701: [:isascii:] inside a character class defines a different set of characters, and
! 702: this shows up in this test as a difference in the compiled code, which is being
! 703: listed for checking. Where the comparison test output contains [\x00-\x7f] the
! 704: test will contain [\x00-\xff], and similarly in some other cases. This is not a
! 705: bug in PCRE.
! 706:
! 707: The third set of tests checks pcre_maketables(), the facility for building a
! 708: set of character tables for a specific locale and using them instead of the
! 709: default tables. The tests make use of the "fr_FR" (French) locale. Before
! 710: running the test, the script checks for the presence of this locale by running
! 711: the "locale" command. If that command fails, or if it doesn't include "fr_FR"
! 712: in the list of available locales, the third test cannot be run, and a comment
! 713: is output to say why. If running this test produces instances of the error
! 714:
! 715: ** Failed to set locale "fr_FR"
! 716:
! 717: in the comparison output, it means that locale is not available on your system,
! 718: despite being listed by "locale". This does not mean that PCRE is broken.
! 719:
! 720: [If you are trying to run this test on Windows, you may be able to get it to
! 721: work by changing "fr_FR" to "french" everywhere it occurs. Alternatively, use
! 722: RunTest.bat. The version of RunTest.bat included with PCRE 7.4 and above uses
! 723: Windows versions of test 2. More info on using RunTest.bat is included in the
! 724: document entitled NON-UNIX-USE.]
! 725:
! 726: The fourth and fifth tests check the UTF-8/16/32 support and error handling and
! 727: internal UTF features of PCRE that are not relevant to Perl, respectively. The
! 728: sixth and seventh tests do the same for Unicode character properties support.
! 729:
! 730: The eighth, ninth, and tenth tests check the pcre_dfa_exec() alternative
! 731: matching function, in non-UTF-8/16/32 mode, UTF-8/16/32 mode, and UTF-8/16/32
! 732: mode with Unicode property support, respectively.
! 733:
! 734: The eleventh test checks some internal offsets and code size features; it is
! 735: run only when the default "link size" of 2 is set (in other cases the sizes
! 736: change) and when Unicode property support is enabled.
! 737:
! 738: The twelfth test is run only when JIT support is available, and the thirteenth
! 739: test is run only when JIT support is not available. They test some JIT-specific
! 740: features such as information output from pcretest about JIT compilation.
! 741:
! 742: The fourteenth, fifteenth, and sixteenth tests are run only in 8-bit mode, and
! 743: the seventeenth, eighteenth, and nineteenth tests are run only in 16/32-bit
! 744: mode. These are tests that generate different output in the two modes. They are
! 745: for general cases, UTF-8/16/32 support, and Unicode property support,
! 746: respectively.
! 747:
! 748: The twentieth test is run only in 16/32-bit mode. It tests some specific
! 749: 16/32-bit features of the DFA matching engine.
! 750:
! 751: The twenty-first and twenty-second tests are run only in 16/32-bit mode, when
! 752: the link size is set to 2 for the 16-bit library. They test reloading
! 753: pre-compiled patterns.
! 754:
! 755: The twenty-third and twenty-fourth tests are run only in 16-bit mode. They are
! 756: for general cases, and UTF-16 support, respectively.
! 757:
! 758: The twenty-fifth and twenty-sixth tests are run only in 32-bit mode. They are
! 759: for general cases, and UTF-32 support, respectively.
! 760:
! 761:
! 762: Character tables
! 763: ----------------
! 764:
! 765: For speed, PCRE uses four tables for manipulating and identifying characters
! 766: whose code point values are less than 256. The final argument of the
! 767: pcre_compile() function is a pointer to a block of memory containing the
! 768: concatenated tables. A call to pcre_maketables() can be used to generate a set
! 769: of tables in the current locale. If the final argument for pcre_compile() is
! 770: passed as NULL, a set of default tables that is built into the binary is used.
! 771:
! 772: The source file called pcre_chartables.c contains the default set of tables. By
! 773: default, this is created as a copy of pcre_chartables.c.dist, which contains
! 774: tables for ASCII coding. However, if --enable-rebuild-chartables is specified
! 775: for ./configure, a different version of pcre_chartables.c is built by the
! 776: program dftables (compiled from dftables.c), which uses the ANSI C character
! 777: handling functions such as isalnum(), isalpha(), isupper(), islower(), etc. to
! 778: build the table sources. This means that the default C locale which is set for
! 779: your system will control the contents of these default tables. You can change
! 780: the default tables by editing pcre_chartables.c and then re-building PCRE. If
! 781: you do this, you should take care to ensure that the file does not get
! 782: automatically re-generated. The best way to do this is to move
! 783: pcre_chartables.c.dist out of the way and replace it with your customized
! 784: tables.
! 785:
! 786: When the dftables program is run as a result of --enable-rebuild-chartables,
! 787: it uses the default C locale that is set on your system. It does not pay
! 788: attention to the LC_xxx environment variables. In other words, it uses the
! 789: system's default locale rather than whatever the compiling user happens to have
! 790: set. If you really do want to build a source set of character tables in a
! 791: locale that is specified by the LC_xxx variables, you can run the dftables
! 792: program by hand with the -L option. For example:
! 793:
! 794: ./dftables -L pcre_chartables.c.special
! 795:
! 796: The first two 256-byte tables provide lower casing and case flipping functions,
! 797: respectively. The next table consists of three 32-byte bit maps which identify
! 798: digits, "word" characters, and white space, respectively. These are used when
! 799: building 32-byte bit maps that represent character classes for code points less
! 800: than 256.
! 801:
! 802: The final 256-byte table has bits indicating various character types, as
! 803: follows:
! 804:
! 805: 1 white space character
! 806: 2 letter
! 807: 4 decimal digit
! 808: 8 hexadecimal digit
! 809: 16 alphanumeric or '_'
! 810: 128 regular expression metacharacter or binary zero
! 811:
! 812: You should not alter the set of characters that contain the 128 bit, as that
! 813: will cause PCRE to malfunction.
! 814:
! 815:
! 816: File manifest
! 817: -------------
! 818:
! 819: The distribution should contain the files listed below. Where a file name is
! 820: given as pcre[16|32]_xxx it means that there are three files, one with the name
! 821: pcre_xxx, one with the name pcre16_xx, and a third with the name pcre32_xxx.
! 822:
! 823: (A) Source files of the PCRE library functions and their headers:
! 824:
! 825: dftables.c auxiliary program for building pcre_chartables.c
! 826: when --enable-rebuild-chartables is specified
! 827:
! 828: pcre_chartables.c.dist a default set of character tables that assume ASCII
! 829: coding; used, unless --enable-rebuild-chartables is
! 830: specified, by copying to pcre[16]_chartables.c
! 831:
! 832: pcreposix.c )
! 833: pcre[16|32]_byte_order.c )
! 834: pcre[16|32]_compile.c )
! 835: pcre[16|32]_config.c )
! 836: pcre[16|32]_dfa_exec.c )
! 837: pcre[16|32]_exec.c )
! 838: pcre[16|32]_fullinfo.c )
! 839: pcre[16|32]_get.c ) sources for the functions in the library,
! 840: pcre[16|32]_globals.c ) and some internal functions that they use
! 841: pcre[16|32]_jit_compile.c )
! 842: pcre[16|32]_maketables.c )
! 843: pcre[16|32]_newline.c )
! 844: pcre[16|32]_refcount.c )
! 845: pcre[16|32]_string_utils.c )
! 846: pcre[16|32]_study.c )
! 847: pcre[16|32]_tables.c )
! 848: pcre[16|32]_ucd.c )
! 849: pcre[16|32]_version.c )
! 850: pcre[16|32]_xclass.c )
! 851: pcre_ord2utf8.c )
! 852: pcre_valid_utf8.c )
! 853: pcre16_ord2utf16.c )
! 854: pcre16_utf16_utils.c )
! 855: pcre16_valid_utf16.c )
! 856: pcre32_utf32_utils.c )
! 857: pcre32_valid_utf32.c )
! 858:
! 859: pcre[16|32]_printint.c ) debugging function that is used by pcretest,
! 860: ) and can also be #included in pcre_compile()
! 861:
! 862: pcre.h.in template for pcre.h when built by "configure"
! 863: pcreposix.h header for the external POSIX wrapper API
! 864: pcre_internal.h header for internal use
! 865: sljit/* 16 files that make up the JIT compiler
! 866: ucp.h header for Unicode property handling
! 867:
! 868: config.h.in template for config.h, which is built by "configure"
! 869:
! 870: pcrecpp.h public header file for the C++ wrapper
! 871: pcrecpparg.h.in template for another C++ header file
! 872: pcre_scanner.h public header file for C++ scanner functions
! 873: pcrecpp.cc )
! 874: pcre_scanner.cc ) source for the C++ wrapper library
! 875:
! 876: pcre_stringpiece.h.in template for pcre_stringpiece.h, the header for the
! 877: C++ stringpiece functions
! 878: pcre_stringpiece.cc source for the C++ stringpiece functions
! 879:
! 880: (B) Source files for programs that use PCRE:
! 881:
! 882: pcredemo.c simple demonstration of coding calls to PCRE
! 883: pcregrep.c source of a grep utility that uses PCRE
! 884: pcretest.c comprehensive test program
! 885:
! 886: (C) Auxiliary files:
! 887:
! 888: 132html script to turn "man" pages into HTML
! 889: AUTHORS information about the author of PCRE
! 890: ChangeLog log of changes to the code
! 891: CleanTxt script to clean nroff output for txt man pages
! 892: Detrail script to remove trailing spaces
! 893: HACKING some notes about the internals of PCRE
! 894: INSTALL generic installation instructions
! 895: LICENCE conditions for the use of PCRE
! 896: COPYING the same, using GNU's standard name
! 897: Makefile.in ) template for Unix Makefile, which is built by
! 898: ) "configure"
! 899: Makefile.am ) the automake input that was used to create
! 900: ) Makefile.in
! 901: NEWS important changes in this release
! 902: NON-UNIX-USE the previous name for NON-AUTOTOOLS-BUILD
! 903: NON-AUTOTOOLS-BUILD notes on building PCRE without using autotools
! 904: PrepareRelease script to make preparations for "make dist"
! 905: README this file
! 906: RunTest a Unix shell script for running tests
! 907: RunGrepTest a Unix shell script for pcregrep tests
! 908: aclocal.m4 m4 macros (generated by "aclocal")
! 909: config.guess ) files used by libtool,
! 910: config.sub ) used only when building a shared library
! 911: configure a configuring shell script (built by autoconf)
! 912: configure.ac ) the autoconf input that was used to build
! 913: ) "configure" and config.h
! 914: depcomp ) script to find program dependencies, generated by
! 915: ) automake
! 916: doc/*.3 man page sources for PCRE
! 917: doc/*.1 man page sources for pcregrep and pcretest
! 918: doc/index.html.src the base HTML page
! 919: doc/html/* HTML documentation
! 920: doc/pcre.txt plain text version of the man pages
! 921: doc/pcretest.txt plain text documentation of test program
! 922: doc/perltest.txt plain text documentation of Perl test program
! 923: install-sh a shell script for installing files
! 924: libpcre16.pc.in template for libpcre16.pc for pkg-config
! 925: libpcre32.pc.in template for libpcre32.pc for pkg-config
! 926: libpcre.pc.in template for libpcre.pc for pkg-config
! 927: libpcreposix.pc.in template for libpcreposix.pc for pkg-config
! 928: libpcrecpp.pc.in template for libpcrecpp.pc for pkg-config
! 929: ltmain.sh file used to build a libtool script
! 930: missing ) common stub for a few missing GNU programs while
! 931: ) installing, generated by automake
! 932: mkinstalldirs script for making install directories
! 933: perltest.pl Perl test program
! 934: pcre-config.in source of script which retains PCRE information
! 935: pcre_jit_test.c test program for the JIT compiler
! 936: pcrecpp_unittest.cc )
! 937: pcre_scanner_unittest.cc ) test programs for the C++ wrapper
! 938: pcre_stringpiece_unittest.cc )
! 939: testdata/testinput* test data for main library tests
! 940: testdata/testoutput* expected test results
! 941: testdata/grep* input and output for pcregrep tests
! 942: testdata/* other supporting test files
! 943:
! 944: (D) Auxiliary files for cmake support
! 945:
! 946: cmake/COPYING-CMAKE-SCRIPTS
! 947: cmake/FindPackageHandleStandardArgs.cmake
! 948: cmake/FindEditline.cmake
! 949: cmake/FindReadline.cmake
! 950: CMakeLists.txt
! 951: config-cmake.h.in
! 952:
! 953: (E) Auxiliary files for VPASCAL
! 954:
! 955: makevp.bat
! 956: makevp_c.txt
! 957: makevp_l.txt
! 958: pcregexp.pas
! 959:
! 960: (F) Auxiliary files for building PCRE "by hand"
! 961:
! 962: pcre.h.generic ) a version of the public PCRE header file
! 963: ) for use in non-"configure" environments
! 964: config.h.generic ) a version of config.h for use in non-"configure"
! 965: ) environments
! 966:
! 967: (F) Miscellaneous
! 968:
! 969: RunTest.bat a script for running tests under Windows
! 970:
! 971: Philip Hazel
! 972: Email local part: ph10
! 973: Email domain: cam.ac.uk
! 974: Last updated: 28 April 2013
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README.txt CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pcre / doc / html