Lines Matching +full:- +full:- +full:disable +full:- +full:documentation
1 README file for PCRE2 (Perl-compatible regular expression library)
2 ------------------------------------------------------------------
4 PCRE2 is a re-working of the original PCRE library to provide an entirely new
8 ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre2-xxx.tar.gz
9 ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre2-xxx.tar.bz2
10 ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre2-xxx.zip
13 original and new APIs) at pcre-dev@exim.org. You can access the archives and
16 https://lists.exim.org/mailman/listinfo/pcre-dev
22 Documentation for PCRE2
24 Building PCRE2 on non-Unix-like systems
29 Cross-compiling using autotools
37 --------------
40 functions, one for the 8-bit library, which processes strings of bytes, one for
41 the 16-bit library, which processes strings of 16-bit values, and one for the
42 32-bit library, which processes strings of 32-bit values. There are no C++
45 The distribution does contain a set of C wrapper functions for the 8-bit
47 man page). These can be found in a library called libpcre2-posix. Note that
52 The header file for the POSIX-style functions is called pcre2posix.h. The
61 to ensure that they link with PCRE2's libpcre2-posix library. Otherwise they
65 -Dregcomp=PCRE2regcomp (and similarly for the other POSIX functions) to the
66 compiler flags (CFLAGS if you are using "configure" -- see below). This has the
72 Documentation for PCRE2
73 -----------------------
75 If you install PCRE2 in the normal way on a Unix-like system, you will end up
78 PCRE2 documentation is supplied in two other forms:
90 2. A set of files containing all the documentation in HTML form, hyperlinked
95 Building PCRE2 on non-Unix-like systems
96 ---------------------------------------
98 For a non-Unix-like system, please read the file NON-AUTOTOOLS-BUILD, though if
100 PCRE2 using autotools in the same way as for many Unix-like systems.
104 NON-AUTOTOOLS-BUILD has information about CMake.
112 --------------------------------------
115 environments, even some that are Unix or Unix-like. See the NON-AUTOTOOLS-BUILD
120 ------------------------------
135 CFLAGS='-O2 -Wall' ./configure --prefix=/opt/local
137 This command specifies that the C compiler should be run with the flags '-O2
138 -Wall' instead of the default, and that "make install" should install PCRE2
143 into /source/pcre2/pcre2-xxx, but you want to build it in
144 /build/pcre2/pcre2-xxx:
146 cd /build/pcre2/pcre2-xxx
147 /source/pcre2/pcre2-xxx/configure
159 --disable-shared
160 --disable-static
162 (See also "Shared libraries on Unix-like systems" below.)
164 . By default, only the 8-bit library is built. If you add --enable-pcre2-16 to
165 the "configure" command, the 16-bit library is also built. If you add
166 --enable-pcre2-32 to the "configure" command, the 32-bit library is also
167 built. If you want only the 16-bit or 32-bit library, use --disable-pcre2-8
168 to disable building the 8-bit library.
170 . If you want to include support for just-in-time (JIT) compiling, which can
171 give large performance improvements on certain platforms, add --enable-jit to
174 will be a compile time error. If in doubt, use --enable-jit=auto, which
178 --enable-jit-sealloc, which enables the use of an execmem allocator in JIT
181 . If you do not want to make use of the default support for UTF-8 Unicode
182 character strings in the 8-bit library, UTF-16 Unicode character strings in
183 the 16-bit library, or UTF-32 Unicode character strings in the 32-bit
184 library, you can add --disable-unicode to the "configure" command. This
187 It is also not possible to use --enable-ebcdic (see below) with Unicode
188 support, so if this option is set, you must also use --disable-unicode.
193 either be ASCII or UTF-8/16/32, even when running on EBCDIC platforms.
197 However, only the basic two-letter properties such as Lu are supported.
207 can specify the default newline indicator by adding --enable-newline-is-cr,
208 --enable-newline-is-lf, --enable-newline-is-crlf,
209 --enable-newline-is-anycrlf, --enable-newline-is-any, or
210 --enable-newline-is-nul to the "configure" command, respectively.
216 adding --enable-bsr-anycrlf to the "configure" command (bsr = "backslash R").
219 UTF mode. This can be dangerous because it breaks up multi-code-unit
221 adding --enable-never-backslash-C (note the upper case C) to the "configure"
230 --with-parens-nest-limit=500
237 --with-match-limit=500000
250 --with-match-limit-depth=5000
258 --with-heap-limit=500
265 . In the 8-bit library, the default maximum compiled pattern size is around
266 64 kibibytes. You can increase this by adding --with-link-size=3 to the
268 to different parts of the compiled pattern. In the 16-bit library,
269 --with-link-size=3 is the same as --with-link-size=4, which (in both
270 libraries) uses four-byte offsets. Increasing the internal link size reduces
271 performance in the 8-bit and 16-bit libraries. In the 32-bit library, the
272 link size setting is ignored, as 4-byte offsets are always used.
278 --enable-rebuild-chartables
289 --enable-ebcdic --disable-unicode
291 This automatically implies --enable-rebuild-chartables (see above). However,
293 both EBCDIC and UTF-8/16/32. There is a second option, --enable-ebcdic-nl25,
297 . If you specify --enable-debug, additional debugging code is included in the
302 --enable-valgrind
311 --enable-coverage
318 reporting in the "pcre2build" documentation.
321 you add --disable-pcre2grep-jit to the "configure" command.
325 support can be disabled by adding --disable-pcre2grep-callout to the
328 . The pcre2grep program currently supports only 8-bit data files, and so
329 requires the 8-bit PCRE2 library. It is possible to compile pcre2grep to use
333 --enable-pcre2grep-libz
334 --enable-pcre2grep-libbz2
341 --with-pcre2grep-bufsize=51200
351 --with-pcre2grep-max-bufsize=2097152
353 The default is either 1048576 or the value of --with-pcre2grep-bufsize,
359 --enable-pcre2test-libreadline or --enable-pcre2test-libedit
362 the readline() function. This provides line-editing and history facilities.
363 Note that libreadline is GPL-licenced, so if you distribute a binary of
367 Enabling libreadline causes the -lreadline option to be added to the
368 pcre2test build. In many operating environments with a sytem-installed
371 necessary to specify something like LIBS="-lncurses" as well. This is
379 . There is a special option called --enable-fuzz-support for use by people who
380 want to run fuzzing tests on PCRE2. At present this applies only to the 8-bit
381 library. If set, it causes an extra library called libpcre2-fuzzsupport.a to
387 Setting --enable-fuzz-support also causes a binary called pcre2fuzzcheck to
395 . Releases before 10.30 could be compiled with --disable-stack-for-recursion,
405 . src/config.h build-time configuration options for the library
407 . pcre2-config script that shows the building settings such as CFLAGS
409 . libpcre2-8.pc )
410 . libpcre2-16.pc ) data for the pkg-config command
411 . libpcre2-32.pc )
412 . libpcre2-posix.pc )
425 libraries libpcre2-8, libpcre2-16 and libpcre2-32 are configured, and a test
426 program called pcre2test. If you enabled JIT support with --enable-jit, another
427 test program called pcre2_jit_test is built as well. If the 8-bit library is
428 built, libpcre2-posix and the pcre2grep command are also built. Running
429 "make" with the -j option may speed up compilation on multiprocessor systems.
432 tests are given below in a separate section of this document. The -j option of
441 pcre2grep (if 8-bit support is enabled)
442 pcre2-config
445 libpcre2-8 (if 8-bit support is enabled)
446 libpcre2-16 (if 16-bit support is enabled)
447 libpcre2-32 (if 32-bit support is enabled)
448 libpcre2-posix (if 8-bit support is enabled)
451 libpcre2-8.pc
452 libpcre2-16.pc
453 libpcre2-32.pc
454 libpcre2-posix.pc
463 pcre2-config.1
467 HTML documentation (share/doc/pcre2/html):
471 Text file documentation (share/doc/pcre2):
481 pcre2-config.txt the pcre2-config man page
489 ------------------------------------
491 Running "make install" installs the command pcre2-config, which can be used to
494 pcre2-config --version
498 pcre2-config --libs8
500 outputs information about where the 8-bit library is installed. This command
502 from having to remember too many details. Run pcre2-config with no arguments to
505 The pkg-config command is another system for saving and retrieving information
509 pkg-config --libs libpcre2-16
516 ----------------
528 automatically re-built to use the newly installed shared libraries before being
532 To build PCRE2 using static libraries only you must use --disable-shared when
535 ./configure --prefix=/usr/gnu --disable-shared
537 Then run "make" in the usual way. Similarly, you can use --disable-static to
541 Cross-compiling using autotools
542 -------------------------------
545 order to cross-compile PCRE2 for some other host. However, you should NOT
546 specify --enable-rebuild-chartables, because if you do, the dftables.c source
552 When --enable-rebuild-chartables is not specified, pcre2_chartables.c is
554 tables that assumes ASCII code. Cross-compiling with the default tables should
557 If you need to modify the character tables when cross-compiling, you should
560 Then when you cross-compile PCRE2 this new version of the tables will be used.
564 -------------------
572 script creates the .txt and HTML forms of the documentation from the man pages.
576 -------------
578 To test the basic PCRE2 library on a Unix-like system, run the RunTest script.
582 check". For other environments, see the instructions in NON-AUTOTOOLS-BUILD.
591 Some tests are relevant only when certain build-time options were selected. For
592 example, the tests for UTF-8/16/32 features are run only when Unicode support
599 The entire set of tests is run once for each of the 8-bit, 16-bit and 32-bit
601 RunTest with either the -8, -16 or -32 option.
609 You can also specify ranges of tests such as 3-6 or 3- (meaning 3 to the
612 Runtest 3-15 ~10
632 auxiliary functions, error detection, and run-time flags that are specific to
639 isprint() function yields TRUE for characters in the range 128-255, the use of
643 [\x00-\x7f] the test might contain [\x00-\xff], and similarly in some other
663 with the perltest.sh script, and test 5 checking PCRE2-specific things.
666 non-UTF mode and UTF-mode with Unicode property support, respectively.
669 when Unicode support is enabled. The output is different in 8-bit, 16-bit, and
670 32-bit modes and for different link sizes, so there are different output files
673 Tests 9 and 10 are run only in 8-bit mode, and tests 11 and 12 are run only in
674 16-bit and 32-bit modes. These are tests that generate different output in
675 8-bit mode. Each pair are for general cases and Unicode support, respectively.
677 Test 13 checks the handling of non-UTF characters greater than 255 by
678 pcre2_dfa_match() in 16-bit and 32-bit modes.
684 among other non-JIT things, the match-limiting features of the intepretive
691 partial modes, match-limiting under JIT, and other JIT-specific features.
693 Tests 18 and 19 are run only in 8-bit mode. They check the POSIX interface to
694 the 8-bit library, without and with Unicode support, respectively.
707 ----------------
718 contains tables for ASCII coding. However, if --enable-rebuild-chartables is
725 then re-building PCRE2. If you do this, you should take care to ensure that the
726 file does not get automatically re-generated. The best way to do this is to
730 When the dftables program is run as a result of --enable-rebuild-chartables,
736 program by hand with the -L option. For example:
738 ./dftables -L pcre2_chartables.c.special
740 The first two 256-byte tables provide lower casing and case flipping functions,
741 respectively. The next table consists of three 32-byte bit maps which identify
743 building 32-byte bit maps that represent character classes for code points less
744 than 256. The final 256-byte table has bits indicating various character types,
759 -------------
767 when --enable-rebuild-chartables is specified
770 ASCII coding; unless --enable-rebuild-chartables is
809 src/pcre2_intmodedep.h a mode-specific internal header
837 NON-AUTOTOOLS-BUILD notes on building PCRE2 without using autotools
853 doc/html/* HTML documentation
855 doc/pcre2test.txt plain text documentation of test program
856 install-sh a shell script for installing files
857 libpcre2-8.pc.in template for libpcre2-8.pc for pkg-config
858 libpcre2-16.pc.in template for libpcre2-16.pc for pkg-config
859 libpcre2-32.pc.in template for libpcre2-32.pc for pkg-config
860 libpcre2-posix.pc.in template for libpcre2-posix.pc for pkg-config
866 pcre2-config.in source of script which retains PCRE2 information
874 cmake/COPYING-CMAKE-SCRIPTS
879 config-cmake.h.in
884 ) for use in non-"configure" environments
885 src/config.h.generic ) a version of config.h for use in non-"configure"