NAME
    Alien::curlimpersonate - build and find libcurl-impersonate

SYNOPSIS
    In your Makefile.PL:

        use ExtUtils::MakeMaker;
        use Alien::Base::Wrapper ();
        use Alien::curlimpersonate ();

        my %args = Alien::Base::Wrapper->new('Alien::curlimpersonate')->mm_args2;

        # See "LINKING AGAINST IT" below: the wrapper emits no rpath, so add one.
        my ($libdir) = Alien::curlimpersonate->dynamic_libs;
        $libdir =~ s{/[^/]+$}{} if defined $libdir;
        $args{LDDLFLAGS} = join ' ', grep { defined && length }
            $args{LDDLFLAGS}, ($libdir ? "-Wl,-rpath,$libdir" : ());

        WriteMakefile(NAME => 'My::Module', %args);

    Or just to see what was built:

        use Alien::curlimpersonate;
        say Alien::curlimpersonate->cflags;        # -I/.../include
        say Alien::curlimpersonate->libs;          # -L/.../lib -lcurl-impersonate
        say for Alien::curlimpersonate->dynamic_libs;

DESCRIPTION
    Builds curl-impersonate (a patched libcurl with a bundled BoringSSL)
    from source and exposes its cflags/libs, so an XS module can link a
    libcurl that reproduces a real browser's TLS and HTTP/2 fingerprint --
    JA3/JA4 and the HTTP/2 SETTINGS "Akamai" fingerprint -- rather than the
    one libcurl would otherwise present. See Curl::Impersonate for a Perl
    client built on it.

    This is a source-only Alien: there is no system package of
    libcurl-impersonate to find, so the probe always selects a "share"
    install and the library is compiled at install time. See "SYSTEM
    REQUIREMENTS", because that build is neither short nor dependency-free.

    The pinned upstream version is v1.5.6, from
    <https://github.com/lexiforest/curl-impersonate>.

SYSTEM REQUIREMENTS
    curl-impersonate statically builds BoringSSL, zlib, zstd, brotli,
    nghttp2 and ngtcp2 alongside curl itself. That needs, on top of a C and
    C++ compiler:

    *   "git" -- the source is fetched by cloning the upstream repository

    *   "cmake" (or "cmake3") and "ninja" (or "ninja-build") -- BoringSSL

    *   "go" -- BoringSSL's build generates sources with it

    *   "patch" -- upstream patches curl before building it

    *   GNU make -- upstream's makefile uses GNU-only conditionals. It is
        found automatically, and Alien::gmake is pulled in if the system has
        no GNU make.

    The build checks for these before it starts and names anything missing,
    rather than failing deep inside a compile. On Debian or Ubuntu:

        apt-get install git cmake ninja-build golang-go patch build-essential

    Expect the install to take several minutes -- around five or six on a
    current machine, and longer on a slow or loaded one. It is a full
    BoringSSL and curl build, which is why installing this dist takes far
    longer than the Perl code in it would suggest.

METHODS
    This is an Alien::Base subclass and adds nothing of its own; the useful
    methods are inherited. The ones that matter here:

    "Alien::curlimpersonate->cflags"
        The include flags, as "-I$prefix/include".

    "Alien::curlimpersonate->libs"
        The link flags, as "-L$prefix/lib -lcurl-impersonate". No rpath --
        see below.

    "Alien::curlimpersonate->dynamic_libs"
        The shared library file paths -- not directories, and including the
        versioned names. The order is not defined, but they all live in the
        same directory, so taking that of any one of them is what you want
        for an rpath.

LINKING AGAINST IT
    "libs" deliberately carries no "-Wl,-rpath". Alien::Base relocates the
    "-L" it emits when the Alien is installed to its final location, but it
    does not relocate an rpath -- so an rpath baked in here would point at
    the staging directory and be wrong by the time anyone links against it.

    The consequence is that a consumer linking with "libs" alone produces an
    extension that builds cleanly and then fails at runtime with something
    like "libcurl-impersonate.so.4: cannot open shared object file", unless
    "LD_LIBRARY_PATH" happens to be set.

    So add the rpath yourself, against the resolved library directory, as
    the SYNOPSIS shows: take "dynamic_libs", strip the filename, and pass
    "-Wl,-rpath,$libdir". Curl::Impersonate's Makefile.PL is a working
    example.

CAVEATS
    The upstream version is pinned exactly. That is deliberate -- the whole
    point of this Alien is a reproducible fingerprint, and the set of
    impersonation targets changes between upstream releases -- but it means
    a newer curl-impersonate needs a new release of this dist rather than a
    rebuild.

SEE ALSO
    Curl::Impersonate, Alien::Base, Alien::Build,
    <https://github.com/lexiforest/curl-impersonate>

AUTHOR
    vividsnow

LICENSE
    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    The library it builds, curl-impersonate, is distributed under its own
    terms; see the upstream project for details.