Build a PCRE2 Program with pcre2-config

You will use pcre2-config to discover the compiler and linker flags for PCRE2, compile a small C program, and check that the resulting binary can use the library. Allow about fifteen minutes. You need a shell, a C compiler, and the PCRE2 development package. This guide uses the installed Debian command at PCRE2 10.42 from libpcre2-dev version 10.42-4ubuntu2.1.

1. Check which command you are calling

pcre2-config describes an installed PCRE2 development setup. It does not install the library, change compiler settings, or edit a project. Start with read-only checks:

$ command -v pcre2-config
/usr/bin/pcre2-config
$ /usr/bin/pcre2-config --version
10.42
$ dpkg-query -W -f='${Package} ${Version}\n' libpcre2-dev:amd64
libpcre2-dev 10.42-4ubuntu2.1

The path matters. More than one PCRE2 installation can exist, for example a system package and a Homebrew or locally compiled copy. The first executable in PATH supplies the answers. If command -v shows an unexpected path, inspect it before compiling:

$ PATH=/usr/bin:/bin type -a pcre2-config
pcre2-config is /usr/bin/pcre2-config

Checkpoint: use the same path for every command in this guide. The examples use /usr/bin/pcre2-config so that the output stays tied to the Debian package rather than an accidental alternative.

2. Inspect the installation prefixes and flags

Ask for the values individually. The prefix options report where PCRE2 was installed; the library options report link arguments; and the cflags options report include-directory or other compile arguments:

$ /usr/bin/pcre2-config --prefix
/usr
$ /usr/bin/pcre2-config --exec-prefix
/usr
$ /usr/bin/pcre2-config --cflags
$ /usr/bin/pcre2-config --libs8
-lpcre2-8
$ /usr/bin/pcre2-config --libs16
-lpcre2-16
$ /usr/bin/pcre2-config --libs32
-lpcre2-32
$ /usr/bin/pcre2-config --libs-posix
-lpcre2-posix -lpcre2-8

A blank --cflags line is valid. It means this installation needs no extra compiler option for the header search path, because the header is in a standard location. Do not turn a blank line into a literal argument or add an arbitrary include directory.

The suffix on a library flag is significant. PCRE2 provides separate 8-bit, 16-bit and 32-bit library interfaces. Link the width used by the source code. The POSIX wrapper is different again: this installation reports both -lpcre2-posix and -lpcre2-8.

3. Create a small native API test

Make a temporary source file outside your project. The program asks PCRE2 for its version through the native API, then prints it. The PCRE2_CODE_UNIT_WIDTH definition selects the 8-bit API, which matches -lpcre2-8:

$ tmp_c=$(mktemp /tmp/pcre2-config-test.XXXXXX.c)
$ tmp_bin=${tmp_c%.c}
$ trap 'rm -f "$tmp_c" "$tmp_bin"' EXIT
$ cat > "$tmp_c" <<'EOF'
#define PCRE2_CODE_UNIT_WIDTH 8
#include <pcre2.h>
#include <stdio.h>

int main(void)
{
    PCRE2_UCHAR version[64];
    int length = pcre2_config(PCRE2_CONFIG_VERSION, version);

    if (length < 0) {
        return 1;
    }
    puts((char *)version);
    return 0;
}
EOF

This only creates a temporary source file and arranges to remove it when the shell exits. It does not require elevated privileges. If your shell does not support trap, remove the two temporary files manually after testing.

4. Compile and link with the reported values

Use command substitution so the installed helper supplies the flags. Put the library flags after the source file, which also works with linkers that resolve libraries from left to right:

$ cc -std=c11 -Wall -Wextra -o "$tmp_bin" "$tmp_c" \
    $(/usr/bin/pcre2-config --cflags) \
    $(/usr/bin/pcre2-config --libs8)
$ "$tmp_bin"
10.42 2022-12-11

The output begins with the PCRE2 library version that the program loaded at run time. This build also includes the library release date, so it is not expected to be byte-for-byte identical to pcre2-config --version. Confirm the executable and its shared-library dependency if the result is surprising:

$ file "$tmp_bin"
/tmp/pcre2-config-test.XXXXXX: ELF 64-bit LSB pie executable, ...
$ ldd "$tmp_bin" | grep pcre2
        libpcre2-8.so.0 => /lib/x86_64-linux-gnu/libpcre2-8.so.0 (...)

The exact temporary name, architecture wording and library path vary. The useful checks are a successful compiler exit status, a version line from the program, and a dependency on libpcre2-8.

5. Select a different library width deliberately

Do not mix a source definition and a library flag from different widths. For example, a program built with PCRE2_CODE_UNIT_WIDTH 16 must use the 16-bit declarations and --libs16. The same rule applies to width 32:

$ /usr/bin/pcre2-config --libs16
-lpcre2-16
$ /usr/bin/pcre2-config --libs32
-lpcre2-32

The installed command reports these three libraries, so all three are available here. On another build, an unavailable width causes the command to print its usage information rather than a valid linker line. Treat that as a build configuration problem. Do not silently substitute -lpcre2-8, because the declarations and data representation are not interchangeable.

For code using the PCRE2 POSIX wrapper, use the wrapper flags instead of the native API flags:

$ cc -o posix-example posix-example.c \
    $(/usr/bin/pcre2-config --cflags-posix) \
    $(/usr/bin/pcre2-config --libs-posix)

That command assumes a real source file named posix-example.c; it is a pattern, not a file created by this guide. The POSIX wrapper and native PCRE2 API are different interfaces, so choose one according to the source you are compiling.

6. Diagnose the common failures

If compilation cannot find pcre2.h, first compare command -v, --prefix and the package that owns the header. A mixed toolchain can report flags from one installation while the compiler or runtime loader uses another. Prefer one consistent prefix. Do not fix a path mismatch by copying headers or libraries into system directories.

If the linker reports an undefined PCRE2 symbol, check that the matching --libs8, --libs16, --libs32 or --libs-posix option is present and comes after the object or source argument. If it reports that a library cannot be found, inspect the prefix and library search path rather than adding sudo. Installation changes belong to your package manager and may affect other programs.

Shell expansion is another easy trap. A blank cflags result is harmless in the command substitution above. Keep the substitution quoted only if you deliberately need one single argument; compiler flags often contain several arguments, so the usual unquoted form shown here is intentional. Review the expanded command before placing it in a build script that accepts untrusted environment values.