view release on metacpan or  search on metacpan

lib/Alien/TDLib.pm  view on Meta::CPAN

package Alien::TDLib;

use strict;
use warnings;
use parent 'Alien::Base';

our $VERSION = '0.01';

sub commit { shift->runtime_prop->{commit} }

sub prebuilt { shift->runtime_prop->{prebuilt} }

1;

=head1 NAME

Alien::TDLib - Find or build TDLib, the Telegram client library

=head1 SYNOPSIS

In the Makefile.PL of an XS consumer:

    use ExtUtils::MakeMaker;
    use Alien::TDLib;

    WriteMakefile(
        ...
        INC  => Alien::TDLib->cflags,
        LIBS => [ Alien::TDLib->libs ],
    );

=head1 DESCRIPTION

Alien::TDLib locates TDLib (the Telegram Database Library) on the
system, or installs it, and reports the compiler and linker flags
needed to use the tdjson C interface.

By default it installs the newest TDLib release published by the
prebuilt-tdlib project. That project is the version signal because
tdlib/td publishes no releases of its own and its newest tag is
v1.8.0 (2021); each prebuilt-tdlib package records the TDLib commit
it was built from, which makes it a curated pointer rather than a
moving branch. Releases land roughly every three weeks. Set
C<ALIEN_TDLIB_VERSION> to install a specific version or commit
instead.

At install time the system is probed first: C<pkg-config tdjson>,
then a compile-link-and-run test against C<-ltdjson> for
distributions that ship the shared library without a pkg-config
file. The probe asks the library its own version and accepts it only
at 1.8.66 or newer, the oldest release this family has been checked
against; anything older is rejected with a log line naming the
version and the install falls through to the share path. There is
deliberately no upper bound: capping it would start rejecting
installs the day TDLib ships a new minor, which is the maintenance
this design exists to avoid.

If neither probe finds a usable library, TDLib is installed into the
Alien share directory: built from source by default, or fetched as a
prebuilt shared library when C<ALIEN_TDLIB_PREBUILT=1> is set (see
ENVIRONMENT).

Whichever version is resolved, the install is anchored to one commit:
the source archive is fetched by commit sha, and the prebuilt package
is refused unless its recorded TDLib commit is the one that was