Annotation of win32/pcre/README, revision 1.1
1.1 ! misha 1: README file for PCRE (Perl-compatible regular expression library)
! 2: -----------------------------------------------------------------
! 3:
! 4: The latest release of PCRE is always available from
! 5:
! 6: ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre-xxx.tar.gz
! 7:
! 8: There is a mailing list for discussion about the development of PCRE at
! 9:
! 10: pcre-dev@exim.org
! 11:
! 12: Please read the NEWS file if you are upgrading from a previous release.
! 13: The contents of this README file are:
! 14:
! 15: The PCRE APIs
! 16: Documentation for PCRE
! 17: Contributions by users of PCRE
! 18: Building PCRE on non-Unix systems
! 19: Building PCRE on Unix-like systems
! 20: Retrieving configuration information on Unix-like systems
! 21: Shared libraries on Unix-like systems
! 22: Cross-compiling on Unix-like systems
! 23: Using HP's ANSI C++ compiler (aCC)
! 24: Making new tarballs
! 25: Testing PCRE
! 26: Character tables
! 27: File manifest
! 28:
! 29:
! 30: The PCRE APIs
! 31: -------------
! 32:
! 33: PCRE is written in C, and it has its own API. The distribution also includes a
! 34: set of C++ wrapper functions (see the pcrecpp man page for details), courtesy
! 35: of Google Inc.
! 36:
! 37: In addition, there is a set of C wrapper functions that are based on the POSIX
! 38: regular expression API (see the pcreposix man page). These end up in the
! 39: library called libpcreposix. Note that this just provides a POSIX calling
! 40: interface to PCRE; the regular expressions themselves still follow Perl syntax
! 41: and semantics. The POSIX API is restricted, and does not give full access to
! 42: all of PCRE's facilities.
! 43:
! 44: The header file for the POSIX-style functions is called pcreposix.h. The
! 45: official POSIX name is regex.h, but I did not want to risk possible problems
! 46: with existing files of that name by distributing it that way. To use PCRE with
! 47: an existing program that uses the POSIX API, pcreposix.h will have to be
! 48: renamed or pointed at by a link.
! 49:
! 50: If you are using the POSIX interface to PCRE and there is already a POSIX regex
! 51: library installed on your system, as well as worrying about the regex.h header
! 52: file (as mentioned above), you must also take care when linking programs to
! 53: ensure that they link with PCRE's libpcreposix library. Otherwise they may pick
! 54: up the POSIX functions of the same name from the other library.
! 55:
! 56: One way of avoiding this confusion is to compile PCRE with the addition of
! 57: -Dregcomp=PCREregcomp (and similarly for the other POSIX functions) to the
! 58: compiler flags (CFLAGS if you are using "configure" -- see below). This has the
! 59: effect of renaming the functions so that the names no longer clash. Of course,
! 60: you have to do the same thing for your applications, or write them using the
! 61: new names.
! 62:
! 63:
! 64: Documentation for PCRE
! 65: ----------------------
! 66:
! 67: If you install PCRE in the normal way on a Unix-like system, you will end up
! 68: with a set of man pages whose names all start with "pcre". The one that is just
! 69: called "pcre" lists all the others. In addition to these man pages, the PCRE
! 70: documentation is supplied in two other forms:
! 71:
! 72: 1. There are files called doc/pcre.txt, doc/pcregrep.txt, and
! 73: doc/pcretest.txt in the source distribution. The first of these is a
! 74: concatenation of the text forms of all the section 3 man pages except
! 75: those that summarize individual functions. The other two are the text
! 76: forms of the section 1 man pages for the pcregrep and pcretest commands.
! 77: These text forms are provided for ease of scanning with text editors or
! 78: similar tools. They are installed in <prefix>/share/doc/pcre, where
! 79: <prefix> is the installation prefix (defaulting to /usr/local).
! 80:
! 81: 2. A set of files containing all the documentation in HTML form, hyperlinked
! 82: in various ways, and rooted in a file called index.html, is distributed in
! 83: doc/html and installed in <prefix>/share/doc/pcre/html.
! 84:
! 85:
! 86: Contributions by users of PCRE
! 87: ------------------------------
! 88:
! 89: You can find contributions from PCRE users in the directory
! 90:
! 91: ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/Contrib
! 92:
! 93: There is a README file giving brief descriptions of what they are. Some are
! 94: complete in themselves; others are pointers to URLs containing relevant files.
! 95: Some of this material is likely to be well out-of-date. Several of the earlier
! 96: contributions provided support for compiling PCRE on various flavours of
! 97: Windows (I myself do not use Windows). Nowadays there is more Windows support
! 98: in the standard distribution, so these contibutions have been archived.
! 99:
! 100:
! 101: Building PCRE on non-Unix systems
! 102: ---------------------------------
! 103:
! 104: For a non-Unix system, please read the comments in the file NON-UNIX-USE,
! 105: though if your system supports the use of "configure" and "make" you may be
! 106: able to build PCRE in the same way as for Unix-like systems. PCRE can also be
! 107: configured in many platform environments using the GUI facility of CMake's
! 108: CMakeSetup. It creates Makefiles, solution files, etc.
! 109:
! 110: PCRE has been compiled on many different operating systems. It should be
! 111: straightforward to build PCRE on any system that has a Standard C compiler and
! 112: library, because it uses only Standard C functions.
! 113:
! 114:
! 115: Building PCRE on Unix-like systems
! 116: ----------------------------------
! 117:
! 118: If you are using HP's ANSI C++ compiler (aCC), please see the special note
! 119: in the section entitled "Using HP's ANSI C++ compiler (aCC)" below.
! 120:
! 121: The following instructions assume the use of the widely used "configure, make,
! 122: make install" process. There is also support for CMake in the PCRE
! 123: distribution; there are some comments about using CMake in the NON-UNIX-USE
! 124: file, though it can also be used in Unix-like systems.
! 125:
! 126: To build PCRE on a Unix-like system, first run the "configure" command from the
! 127: PCRE distribution directory, with your current directory set to the directory
! 128: where you want the files to be created. This command is a standard GNU
! 129: "autoconf" configuration script, for which generic instructions are supplied in
! 130: the file INSTALL.
! 131:
! 132: Most commonly, people build PCRE within its own distribution directory, and in
! 133: this case, on many systems, just running "./configure" is sufficient. However,
! 134: the usual methods of changing standard defaults are available. For example:
! 135:
! 136: CFLAGS='-O2 -Wall' ./configure --prefix=/opt/local
! 137:
! 138: specifies that the C compiler should be run with the flags '-O2 -Wall' instead
! 139: of the default, and that "make install" should install PCRE under /opt/local
! 140: instead of the default /usr/local.
! 141:
! 142: If you want to build in a different directory, just run "configure" with that
! 143: directory as current. For example, suppose you have unpacked the PCRE source
! 144: into /source/pcre/pcre-xxx, but you want to build it in /build/pcre/pcre-xxx:
! 145:
! 146: cd /build/pcre/pcre-xxx
! 147: /source/pcre/pcre-xxx/configure
! 148:
! 149: PCRE is written in C and is normally compiled as a C library. However, it is
! 150: possible to build it as a C++ library, though the provided building apparatus
! 151: does not have any features to support this.
! 152:
! 153: There are some optional features that can be included or omitted from the PCRE
! 154: library. You can read more about them in the pcrebuild man page.
! 155:
! 156: . If you want to suppress the building of the C++ wrapper library, you can add
! 157: --disable-cpp to the "configure" command. Otherwise, when "configure" is run,
! 158: it will try to find a C++ compiler and C++ header files, and if it succeeds,
! 159: it will try to build the C++ wrapper.
! 160:
! 161: . If you want to make use of the support for UTF-8 character strings in PCRE,
! 162: you must add --enable-utf8 to the "configure" command. Without it, the code
! 163: for handling UTF-8 is not included in the library. (Even when included, it
! 164: still has to be enabled by an option at run time.)
! 165:
! 166: . If, in addition to support for UTF-8 character strings, you want to include
! 167: support for the \P, \p, and \X sequences that recognize Unicode character
! 168: properties, you must add --enable-unicode-properties to the "configure"
! 169: command. This adds about 30K to the size of the library (in the form of a
! 170: property table); only the basic two-letter properties such as Lu are
! 171: supported.
! 172:
! 173: . You can build PCRE to recognize either CR or LF or the sequence CRLF or any
! 174: of the preceding, or any of the Unicode newline sequences as indicating the
! 175: end of a line. Whatever you specify at build time is the default; the caller
! 176: of PCRE can change the selection at run time. The default newline indicator
! 177: is a single LF character (the Unix standard). You can specify the default
! 178: newline indicator by adding --enable-newline-is-cr or --enable-newline-is-lf
! 179: or --enable-newline-is-crlf or --enable-newline-is-anycrlf or
! 180: --enable-newline-is-any to the "configure" command, respectively.
! 181:
! 182: If you specify --enable-newline-is-cr or --enable-newline-is-crlf, some of
! 183: the standard tests will fail, because the lines in the test files end with
! 184: LF. Even if the files are edited to change the line endings, there are likely
! 185: to be some failures. With --enable-newline-is-anycrlf or
! 186: --enable-newline-is-any, many tests should succeed, but there may be some
! 187: failures.
! 188:
! 189: . By default, the sequence \R in a pattern matches any Unicode line ending
! 190: sequence. This is independent of the option specifying what PCRE considers to
! 191: be the end of a line (see above). However, the caller of PCRE can restrict \R
! 192: to match only CR, LF, or CRLF. You can make this the default by adding
! 193: --enable-bsr-anycrlf to the "configure" command (bsr = "backslash R").
! 194:
! 195: . When called via the POSIX interface, PCRE uses malloc() to get additional
! 196: storage for processing capturing parentheses if there are more than 10 of
! 197: them in a pattern. You can increase this threshold by setting, for example,
! 198:
! 199: --with-posix-malloc-threshold=20
! 200:
! 201: on the "configure" command.
! 202:
! 203: . PCRE has a counter that can be set to limit the amount of resources it uses.
! 204: If the limit is exceeded during a match, the match fails. The default is ten
! 205: million. You can change the default by setting, for example,
! 206:
! 207: --with-match-limit=500000
! 208:
! 209: on the "configure" command. This is just the default; individual calls to
! 210: pcre_exec() can supply their own value. There is more discussion on the
! 211: pcreapi man page.
! 212:
! 213: . There is a separate counter that limits the depth of recursive function calls
! 214: during a matching process. This also has a default of ten million, which is
! 215: essentially "unlimited". You can change the default by setting, for example,
! 216:
! 217: --with-match-limit-recursion=500000
! 218:
! 219: Recursive function calls use up the runtime stack; running out of stack can
! 220: cause programs to crash in strange ways. There is a discussion about stack
! 221: sizes in the pcrestack man page.
! 222:
! 223: . The default maximum compiled pattern size is around 64K. You can increase
! 224: this by adding --with-link-size=3 to the "configure" command. You can
! 225: increase it even more by setting --with-link-size=4, but this is unlikely
! 226: ever to be necessary. Increasing the internal link size will reduce
! 227: performance.
! 228:
! 229: . You can build PCRE so that its internal match() function that is called from
! 230: pcre_exec() does not call itself recursively. Instead, it uses memory blocks
! 231: obtained from the heap via the special functions pcre_stack_malloc() and
! 232: pcre_stack_free() to save data that would otherwise be saved on the stack. To
! 233: build PCRE like this, use
! 234:
! 235: --disable-stack-for-recursion
! 236:
! 237: on the "configure" command. PCRE runs more slowly in this mode, but it may be
! 238: necessary in environments with limited stack sizes. This applies only to the
! 239: pcre_exec() function; it does not apply to pcre_dfa_exec(), which does not
! 240: use deeply nested recursion. There is a discussion about stack sizes in the
! 241: pcrestack man page.
! 242:
! 243: . For speed, PCRE uses four tables for manipulating and identifying characters
! 244: whose code point values are less than 256. By default, it uses a set of
! 245: tables for ASCII encoding that is part of the distribution. If you specify
! 246:
! 247: --enable-rebuild-chartables
! 248:
! 249: a program called dftables is compiled and run in the default C locale when
! 250: you obey "make". It builds a source file called pcre_chartables.c. If you do
! 251: not specify this option, pcre_chartables.c is created as a copy of
! 252: pcre_chartables.c.dist. See "Character tables" below for further information.
! 253:
! 254: . It is possible to compile PCRE for use on systems that use EBCDIC as their
! 255: default character code (as opposed to ASCII) by specifying
! 256:
! 257: --enable-ebcdic
! 258:
! 259: This automatically implies --enable-rebuild-chartables (see above).
! 260:
! 261: . It is possible to compile pcregrep to use libz and/or libbz2, in order to
! 262: read .gz and .bz2 files (respectively), by specifying one or both of
! 263:
! 264: --enable-pcregrep-libz
! 265: --enable-pcregrep-libbz2
! 266:
! 267: Of course, the relevant libraries must be installed on your system.
! 268:
! 269: . It is possible to compile pcretest so that it links with the libreadline
! 270: library, by specifying
! 271:
! 272: --enable-pcretest-libreadline
! 273:
! 274: If this is done, when pcretest's input is from a terminal, it reads it using
! 275: the readline() function. This provides line-editing and history facilities.
! 276: Note that libreadline is GPL-licenced, so if you distribute a binary of
! 277: pcretest linked in this way, there may be licensing issues.
! 278:
! 279: Setting this option causes the -lreadline option to be added to the pcretest
! 280: build. In many operating environments with a sytem-installed readline
! 281: library this is sufficient. However, in some environments (e.g. if an
! 282: unmodified distribution version of readline is in use), it may be necessary
! 283: to specify something like LIBS="-lncurses" as well. This is because, to quote
! 284: the readline INSTALL, "Readline uses the termcap functions, but does not link
! 285: with the termcap or curses library itself, allowing applications which link
! 286: with readline the to choose an appropriate library."
! 287:
! 288: The "configure" script builds the following files for the basic C library:
! 289:
! 290: . Makefile is the makefile that builds the library
! 291: . config.h contains build-time configuration options for the library
! 292: . pcre.h is the public PCRE header file
! 293: . pcre-config is a script that shows the settings of "configure" options
! 294: . libpcre.pc is data for the pkg-config command
! 295: . libtool is a script that builds shared and/or static libraries
! 296: . RunTest is a script for running tests on the basic C library
! 297: . RunGrepTest is a script for running tests on the pcregrep command
! 298:
! 299: Versions of config.h and pcre.h are distributed in the PCRE tarballs under
! 300: the names config.h.generic and pcre.h.generic. These are provided for the
! 301: benefit of those who have to built PCRE without the benefit of "configure". If
! 302: you use "configure", the .generic versions are not used.
! 303:
! 304: If a C++ compiler is found, the following files are also built:
! 305:
! 306: . libpcrecpp.pc is data for the pkg-config command
! 307: . pcrecpparg.h is a header file for programs that call PCRE via the C++ wrapper
! 308: . pcre_stringpiece.h is the header for the C++ "stringpiece" functions
! 309:
! 310: The "configure" script also creates config.status, which is an executable
! 311: script that can be run to recreate the configuration, and config.log, which
! 312: contains compiler output from tests that "configure" runs.
! 313:
! 314: Once "configure" has run, you can run "make". It builds two libraries, called
! 315: libpcre and libpcreposix, a test program called pcretest, and the pcregrep
! 316: command. If a C++ compiler was found on your system, "make" also builds the C++
! 317: wrapper library, which is called libpcrecpp, and some test programs called
! 318: pcrecpp_unittest, pcre_scanner_unittest, and pcre_stringpiece_unittest.
! 319: Building the C++ wrapper can be disabled by adding --disable-cpp to the
! 320: "configure" command.
! 321:
! 322: The command "make check" runs all the appropriate tests. Details of the PCRE
! 323: tests are given below in a separate section of this document.
! 324:
! 325: You can use "make install" to install PCRE into live directories on your
! 326: system. The following are installed (file names are all relative to the
! 327: <prefix> that is set when "configure" is run):
! 328:
! 329: Commands (bin):
! 330: pcretest
! 331: pcregrep
! 332: pcre-config
! 333:
! 334: Libraries (lib):
! 335: libpcre
! 336: libpcreposix
! 337: libpcrecpp (if C++ support is enabled)
! 338:
! 339: Configuration information (lib/pkgconfig):
! 340: libpcre.pc
! 341: libpcrecpp.pc (if C++ support is enabled)
! 342:
! 343: Header files (include):
! 344: pcre.h
! 345: pcreposix.h
! 346: pcre_scanner.h )
! 347: pcre_stringpiece.h ) if C++ support is enabled
! 348: pcrecpp.h )
! 349: pcrecpparg.h )
! 350:
! 351: Man pages (share/man/man{1,3}):
! 352: pcregrep.1
! 353: pcretest.1
! 354: pcre.3
! 355: pcre*.3 (lots more pages, all starting "pcre")
! 356:
! 357: HTML documentation (share/doc/pcre/html):
! 358: index.html
! 359: *.html (lots more pages, hyperlinked from index.html)
! 360:
! 361: Text file documentation (share/doc/pcre):
! 362: AUTHORS
! 363: COPYING
! 364: ChangeLog
! 365: LICENCE
! 366: NEWS
! 367: README
! 368: pcre.txt (a concatenation of the man(3) pages)
! 369: pcretest.txt the pcretest man page
! 370: pcregrep.txt the pcregrep man page
! 371:
! 372: If you want to remove PCRE from your system, you can run "make uninstall".
! 373: This removes all the files that "make install" installed. However, it does not
! 374: remove any directories, because these are often shared with other programs.
! 375:
! 376:
! 377: Retrieving configuration information on Unix-like systems
! 378: ---------------------------------------------------------
! 379:
! 380: Running "make install" installs the command pcre-config, which can be used to
! 381: recall information about the PCRE configuration and installation. For example:
! 382:
! 383: pcre-config --version
! 384:
! 385: prints the version number, and
! 386:
! 387: pcre-config --libs
! 388:
! 389: outputs information about where the library is installed. This command can be
! 390: included in makefiles for programs that use PCRE, saving the programmer from
! 391: having to remember too many details.
! 392:
! 393: The pkg-config command is another system for saving and retrieving information
! 394: about installed libraries. Instead of separate commands for each library, a
! 395: single command is used. For example:
! 396:
! 397: pkg-config --cflags pcre
! 398:
! 399: The data is held in *.pc files that are installed in a directory called
! 400: <prefix>/lib/pkgconfig.
! 401:
! 402:
! 403: Shared libraries on Unix-like systems
! 404: -------------------------------------
! 405:
! 406: The default distribution builds PCRE as shared libraries and static libraries,
! 407: as long as the operating system supports shared libraries. Shared library
! 408: support relies on the "libtool" script which is built as part of the
! 409: "configure" process.
! 410:
! 411: The libtool script is used to compile and link both shared and static
! 412: libraries. They are placed in a subdirectory called .libs when they are newly
! 413: built. The programs pcretest and pcregrep are built to use these uninstalled
! 414: libraries (by means of wrapper scripts in the case of shared libraries). When
! 415: you use "make install" to install shared libraries, pcregrep and pcretest are
! 416: automatically re-built to use the newly installed shared libraries before being
! 417: installed themselves. However, the versions left in the build directory still
! 418: use the uninstalled libraries.
! 419:
! 420: To build PCRE using static libraries only you must use --disable-shared when
! 421: configuring it. For example:
! 422:
! 423: ./configure --prefix=/usr/gnu --disable-shared
! 424:
! 425: Then run "make" in the usual way. Similarly, you can use --disable-static to
! 426: build only shared libraries.
! 427:
! 428:
! 429: Cross-compiling on Unix-like systems
! 430: ------------------------------------
! 431:
! 432: You can specify CC and CFLAGS in the normal way to the "configure" command, in
! 433: order to cross-compile PCRE for some other host. However, you should NOT
! 434: specify --enable-rebuild-chartables, because if you do, the dftables.c source
! 435: file is compiled and run on the local host, in order to generate the inbuilt
! 436: character tables (the pcre_chartables.c file). This will probably not work,
! 437: because dftables.c needs to be compiled with the local compiler, not the cross
! 438: compiler.
! 439:
! 440: When --enable-rebuild-chartables is not specified, pcre_chartables.c is created
! 441: by making a copy of pcre_chartables.c.dist, which is a default set of tables
! 442: that assumes ASCII code. Cross-compiling with the default tables should not be
! 443: a problem.
! 444:
! 445: If you need to modify the character tables when cross-compiling, you should
! 446: move pcre_chartables.c.dist out of the way, then compile dftables.c by hand and
! 447: run it on the local host to make a new version of pcre_chartables.c.dist.
! 448: Then when you cross-compile PCRE this new version of the tables will be used.
! 449:
! 450:
! 451: Using HP's ANSI C++ compiler (aCC)
! 452: ----------------------------------
! 453:
! 454: Unless C++ support is disabled by specifying the "--disable-cpp" option of the
! 455: "configure" script, you must include the "-AA" option in the CXXFLAGS
! 456: environment variable in order for the C++ components to compile correctly.
! 457:
! 458: Also, note that the aCC compiler on PA-RISC platforms may have a defect whereby
! 459: needed libraries fail to get included when specifying the "-AA" compiler
! 460: option. If you experience unresolved symbols when linking the C++ programs,
! 461: use the workaround of specifying the following environment variable prior to
! 462: running the "configure" script:
! 463:
! 464: CXXLDFLAGS="-lstd_v2 -lCsup_v2"
! 465:
! 466:
! 467: Making new tarballs
! 468: -------------------
! 469:
! 470: The command "make dist" creates three PCRE tarballs, in tar.gz, tar.bz2, and
! 471: zip formats. The command "make distcheck" does the same, but then does a trial
! 472: build of the new distribution to ensure that it works.
! 473:
! 474: If you have modified any of the man page sources in the doc directory, you
! 475: should first run the PrepareRelease script before making a distribution. This
! 476: script creates the .txt and HTML forms of the documentation from the man pages.
! 477:
! 478:
! 479: Testing PCRE
! 480: ------------
! 481:
! 482: To test the basic PCRE library on a Unix system, run the RunTest script that is
! 483: created by the configuring process. There is also a script called RunGrepTest
! 484: that tests the options of the pcregrep command. If the C++ wrapper library is
! 485: built, three test programs called pcrecpp_unittest, pcre_scanner_unittest, and
! 486: pcre_stringpiece_unittest are also built.
! 487:
! 488: Both the scripts and all the program tests are run if you obey "make check" or
! 489: "make test". For other systems, see the instructions in NON-UNIX-USE.
! 490:
! 491: The RunTest script runs the pcretest test program (which is documented in its
! 492: own man page) on each of the testinput files in the testdata directory in
! 493: turn, and compares the output with the contents of the corresponding testoutput
! 494: files. A file called testtry is used to hold the main output from pcretest
! 495: (testsavedregex is also used as a working file). To run pcretest on just one of
! 496: the test files, give its number as an argument to RunTest, for example:
! 497:
! 498: RunTest 2
! 499:
! 500: The first test file can also be fed directly into the perltest.pl script to
! 501: check that Perl gives the same results. The only difference you should see is
! 502: in the first few lines, where the Perl version is given instead of the PCRE
! 503: version.
! 504:
! 505: The second set of tests check pcre_fullinfo(), pcre_info(), pcre_study(),
! 506: pcre_copy_substring(), pcre_get_substring(), pcre_get_substring_list(), error
! 507: detection, and run-time flags that are specific to PCRE, as well as the POSIX
! 508: wrapper API. It also uses the debugging flags to check some of the internals of
! 509: pcre_compile().
! 510:
! 511: If you build PCRE with a locale setting that is not the standard C locale, the
! 512: character tables may be different (see next paragraph). In some cases, this may
! 513: cause failures in the second set of tests. For example, in a locale where the
! 514: isprint() function yields TRUE for characters in the range 128-255, the use of
! 515: [:isascii:] inside a character class defines a different set of characters, and
! 516: this shows up in this test as a difference in the compiled code, which is being
! 517: listed for checking. Where the comparison test output contains [\x00-\x7f] the
! 518: test will contain [\x00-\xff], and similarly in some other cases. This is not a
! 519: bug in PCRE.
! 520:
! 521: The third set of tests checks pcre_maketables(), the facility for building a
! 522: set of character tables for a specific locale and using them instead of the
! 523: default tables. The tests make use of the "fr_FR" (French) locale. Before
! 524: running the test, the script checks for the presence of this locale by running
! 525: the "locale" command. If that command fails, or if it doesn't include "fr_FR"
! 526: in the list of available locales, the third test cannot be run, and a comment
! 527: is output to say why. If running this test produces instances of the error
! 528:
! 529: ** Failed to set locale "fr_FR"
! 530:
! 531: in the comparison output, it means that locale is not available on your system,
! 532: despite being listed by "locale". This does not mean that PCRE is broken.
! 533:
! 534: [If you are trying to run this test on Windows, you may be able to get it to
! 535: work by changing "fr_FR" to "french" everywhere it occurs. Alternatively, use
! 536: RunTest.bat. The version of RunTest.bat included with PCRE 7.4 and above uses
! 537: Windows versions of test 2. More info on using RunTest.bat is included in the
! 538: document entitled NON-UNIX-USE.]
! 539:
! 540: The fourth test checks the UTF-8 support. It is not run automatically unless
! 541: PCRE is built with UTF-8 support. To do this you must set --enable-utf8 when
! 542: running "configure". This file can be also fed directly to the perltest script,
! 543: provided you are running Perl 5.8 or higher. (For Perl 5.6, a small patch,
! 544: commented in the script, can be be used.)
! 545:
! 546: The fifth test checks error handling with UTF-8 encoding, and internal UTF-8
! 547: features of PCRE that are not relevant to Perl.
! 548:
! 549: The sixth test checks the support for Unicode character properties. It it not
! 550: run automatically unless PCRE is built with Unicode property support. To to
! 551: this you must set --enable-unicode-properties when running "configure".
! 552:
! 553: The seventh, eighth, and ninth tests check the pcre_dfa_exec() alternative
! 554: matching function, in non-UTF-8 mode, UTF-8 mode, and UTF-8 mode with Unicode
! 555: property support, respectively. The eighth and ninth tests are not run
! 556: automatically unless PCRE is build with the relevant support.
! 557:
! 558:
! 559: Character tables
! 560: ----------------
! 561:
! 562: For speed, PCRE uses four tables for manipulating and identifying characters
! 563: whose code point values are less than 256. The final argument of the
! 564: pcre_compile() function is a pointer to a block of memory containing the
! 565: concatenated tables. A call to pcre_maketables() can be used to generate a set
! 566: of tables in the current locale. If the final argument for pcre_compile() is
! 567: passed as NULL, a set of default tables that is built into the binary is used.
! 568:
! 569: The source file called pcre_chartables.c contains the default set of tables. By
! 570: default, this is created as a copy of pcre_chartables.c.dist, which contains
! 571: tables for ASCII coding. However, if --enable-rebuild-chartables is specified
! 572: for ./configure, a different version of pcre_chartables.c is built by the
! 573: program dftables (compiled from dftables.c), which uses the ANSI C character
! 574: handling functions such as isalnum(), isalpha(), isupper(), islower(), etc. to
! 575: build the table sources. This means that the default C locale which is set for
! 576: your system will control the contents of these default tables. You can change
! 577: the default tables by editing pcre_chartables.c and then re-building PCRE. If
! 578: you do this, you should take care to ensure that the file does not get
! 579: automatically re-generated. The best way to do this is to move
! 580: pcre_chartables.c.dist out of the way and replace it with your customized
! 581: tables.
! 582:
! 583: When the dftables program is run as a result of --enable-rebuild-chartables,
! 584: it uses the default C locale that is set on your system. It does not pay
! 585: attention to the LC_xxx environment variables. In other words, it uses the
! 586: system's default locale rather than whatever the compiling user happens to have
! 587: set. If you really do want to build a source set of character tables in a
! 588: locale that is specified by the LC_xxx variables, you can run the dftables
! 589: program by hand with the -L option. For example:
! 590:
! 591: ./dftables -L pcre_chartables.c.special
! 592:
! 593: The first two 256-byte tables provide lower casing and case flipping functions,
! 594: respectively. The next table consists of three 32-byte bit maps which identify
! 595: digits, "word" characters, and white space, respectively. These are used when
! 596: building 32-byte bit maps that represent character classes for code points less
! 597: than 256.
! 598:
! 599: The final 256-byte table has bits indicating various character types, as
! 600: follows:
! 601:
! 602: 1 white space character
! 603: 2 letter
! 604: 4 decimal digit
! 605: 8 hexadecimal digit
! 606: 16 alphanumeric or '_'
! 607: 128 regular expression metacharacter or binary zero
! 608:
! 609: You should not alter the set of characters that contain the 128 bit, as that
! 610: will cause PCRE to malfunction.
! 611:
! 612:
! 613: File manifest
! 614: -------------
! 615:
! 616: The distribution should contain the following files:
! 617:
! 618: (A) Source files of the PCRE library functions and their headers:
! 619:
! 620: dftables.c auxiliary program for building pcre_chartables.c
! 621: when --enable-rebuild-chartables is specified
! 622:
! 623: pcre_chartables.c.dist a default set of character tables that assume ASCII
! 624: coding; used, unless --enable-rebuild-chartables is
! 625: specified, by copying to pcre_chartables.c
! 626:
! 627: pcreposix.c )
! 628: pcre_compile.c )
! 629: pcre_config.c )
! 630: pcre_dfa_exec.c )
! 631: pcre_exec.c )
! 632: pcre_fullinfo.c )
! 633: pcre_get.c ) sources for the functions in the library,
! 634: pcre_globals.c ) and some internal functions that they use
! 635: pcre_info.c )
! 636: pcre_maketables.c )
! 637: pcre_newline.c )
! 638: pcre_ord2utf8.c )
! 639: pcre_refcount.c )
! 640: pcre_study.c )
! 641: pcre_tables.c )
! 642: pcre_try_flipped.c )
! 643: pcre_ucp_searchfuncs.c )
! 644: pcre_valid_utf8.c )
! 645: pcre_version.c )
! 646: pcre_xclass.c )
! 647: pcre_printint.src ) debugging function that is #included in pcretest,
! 648: ) and can also be #included in pcre_compile()
! 649: pcre.h.in template for pcre.h when built by "configure"
! 650: pcreposix.h header for the external POSIX wrapper API
! 651: pcre_internal.h header for internal use
! 652: ucp.h ) headers concerned with
! 653: ucpinternal.h ) Unicode property handling
! 654: ucptable.h ) (this one is the data table)
! 655:
! 656: config.h.in template for config.h, which is built by "configure"
! 657:
! 658: pcrecpp.h public header file for the C++ wrapper
! 659: pcrecpparg.h.in template for another C++ header file
! 660: pcre_scanner.h public header file for C++ scanner functions
! 661: pcrecpp.cc )
! 662: pcre_scanner.cc ) source for the C++ wrapper library
! 663:
! 664: pcre_stringpiece.h.in template for pcre_stringpiece.h, the header for the
! 665: C++ stringpiece functions
! 666: pcre_stringpiece.cc source for the C++ stringpiece functions
! 667:
! 668: (B) Source files for programs that use PCRE:
! 669:
! 670: pcredemo.c simple demonstration of coding calls to PCRE
! 671: pcregrep.c source of a grep utility that uses PCRE
! 672: pcretest.c comprehensive test program
! 673:
! 674: (C) Auxiliary files:
! 675:
! 676: 132html script to turn "man" pages into HTML
! 677: AUTHORS information about the author of PCRE
! 678: ChangeLog log of changes to the code
! 679: CleanTxt script to clean nroff output for txt man pages
! 680: Detrail script to remove trailing spaces
! 681: HACKING some notes about the internals of PCRE
! 682: INSTALL generic installation instructions
! 683: LICENCE conditions for the use of PCRE
! 684: COPYING the same, using GNU's standard name
! 685: Makefile.in ) template for Unix Makefile, which is built by
! 686: ) "configure"
! 687: Makefile.am ) the automake input that was used to create
! 688: ) Makefile.in
! 689: NEWS important changes in this release
! 690: NON-UNIX-USE notes on building PCRE on non-Unix systems
! 691: PrepareRelease script to make preparations for "make dist"
! 692: README this file
! 693: RunTest a Unix shell script for running tests
! 694: RunGrepTest a Unix shell script for pcregrep tests
! 695: aclocal.m4 m4 macros (generated by "aclocal")
! 696: config.guess ) files used by libtool,
! 697: config.sub ) used only when building a shared library
! 698: configure a configuring shell script (built by autoconf)
! 699: configure.ac ) the autoconf input that was used to build
! 700: ) "configure" and config.h
! 701: depcomp ) script to find program dependencies, generated by
! 702: ) automake
! 703: doc/*.3 man page sources for the PCRE functions
! 704: doc/*.1 man page sources for pcregrep and pcretest
! 705: doc/index.html.src the base HTML page
! 706: doc/html/* HTML documentation
! 707: doc/pcre.txt plain text version of the man pages
! 708: doc/pcretest.txt plain text documentation of test program
! 709: doc/perltest.txt plain text documentation of Perl test program
! 710: install-sh a shell script for installing files
! 711: libpcre.pc.in template for libpcre.pc for pkg-config
! 712: libpcrecpp.pc.in template for libpcrecpp.pc for pkg-config
! 713: ltmain.sh file used to build a libtool script
! 714: missing ) common stub for a few missing GNU programs while
! 715: ) installing, generated by automake
! 716: mkinstalldirs script for making install directories
! 717: perltest.pl Perl test program
! 718: pcre-config.in source of script which retains PCRE information
! 719: pcrecpp_unittest.cc )
! 720: pcre_scanner_unittest.cc ) test programs for the C++ wrapper
! 721: pcre_stringpiece_unittest.cc )
! 722: testdata/testinput* test data for main library tests
! 723: testdata/testoutput* expected test results
! 724: testdata/grep* input and output for pcregrep tests
! 725:
! 726: (D) Auxiliary files for cmake support
! 727:
! 728: CMakeLists.txt
! 729: config-cmake.h.in
! 730:
! 731: (E) Auxiliary files for VPASCAL
! 732:
! 733: makevp.bat
! 734: makevp_c.txt
! 735: makevp_l.txt
! 736: pcregexp.pas
! 737:
! 738: (F) Auxiliary files for building PCRE "by hand"
! 739:
! 740: pcre.h.generic ) a version of the public PCRE header file
! 741: ) for use in non-"configure" environments
! 742: config.h.generic ) a version of config.h for use in non-"configure"
! 743: ) environments
! 744:
! 745: (F) Miscellaneous
! 746:
! 747: RunTest.bat a script for running tests under Windows
! 748:
! 749: Philip Hazel
! 750: Email local part: ph10
! 751: Email domain: cam.ac.uk
! 752: Last updated: 13 April 2008
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / pcre