Annotation of embedaddon/pcre/doc/html/README.txt, revision 1.1.1.2

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

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>