NAME Alien::TDLib - Find or build TDLib, the Telegram client library SYNOPSIS In the Makefile.PL of an XS consumer: use ExtUtils::MakeMaker; use Alien::TDLib; WriteMakefile( ... INC => Alien::TDLib->cflags, LIBS => [ Alien::TDLib->libs ], ); 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 "ALIEN_TDLIB_VERSION" to install a specific version or commit instead. At install time the system is probed first: "pkg-config tdjson", then a compile-link-and-run test against "-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 "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 resolved. The prebuilt tarball is additionally checked against the sha512 the npm registry publishes for it. The source archive carries a recorded SHA-256 only for the fallback release named below; for any other release the commit sha in the URL is what anchors the content. install_type "system" means a system libtdjson was found and nothing was compiled. "share" means TDLib was installed into the share directory, from source or prebuilt. Alien::TDLib->commit returns the pinned commit sha for share installs and undef for system installs. Alien::TDLib->version returns the pinned version for share installs and the probed version for system installs. Alien::TDLib->prebuilt returns true when the share install is a prebuilt package rather than a source build. BUILD REQUIREMENTS A share build needs: * CMake 3.10 or later * a C++17 compiler (gcc 7+ or clang 5+) * gperf * OpenSSL and zlib development headers Missing build tools are reported before any compilation starts, with the package names for common platforms. TDLib needs roughly 1 GB of RAM per translation unit under GCC, so the parallel job count is throttled to at most one job per 1.5 GB of available RAM, and capped at one below the CPU count to leave a core free. ENVIRONMENT ALIEN_TDLIB_PREBUILT Set to 1 to skip the source build in favour of the prebuilt shared library published as "@prebuilt-tdlib" on npm (version 0.1008066.0, which is TDLib 1.8.66). The source build stays the default. The opt-in takes precedence over a system libtdjson: when a prebuilt package exists for the platform, the system is not probed at all. Platforms with a prebuilt package: linux-x64-glibc linux-x64-musl linux-arm64-glibc linux-arm64-musl darwin-x64 darwin-arm64 win32-x64 An unsupported platform falls through to the source build with a log line; it is never an error. musl is detected from "/lib/ld-musl-*.so.1" or "ldd --version", since $Config{archname} does not distinguish it. The prebuilt tarball is verified against the sha512 integrity published in the npm registry metadata, and its "package.json" records the TDLib commit it was built from; the package is refused when that record differs from the pinned commit, so the binary is checkable rather than trusted. The trade-offs: * it is a third-party binary, not code compiled locally from the pinned source; * its statically linked OpenSSL never picks up system OpenSSL security updates; * there are no BSD builds, so the source build remains necessary for this family's FreeBSD/OpenBSD/NetBSD CI. ALIEN_TDLIB_VERSION Which TDLib to install. Unset, or "latest", installs the newest release published by prebuilt-tdlib. A version such as 1.8.66 installs that release. A 40-character commit sha installs that commit, which is built from source unless prebuilt-tdlib happens to have published a package for it. Pin this if reproducible installs matter to you: without it, two installs a month apart can get different TDLib versions. The trade-off is the other way round from most Aliens, and deliberate -- an unattended pin rots into shipping a years-old TDLib, whereas floating keeps up with a library that releases roughly every three weeks. If the npm registry cannot be reached, the install falls back to a known-good release rather than failing, and logs that it did so. ALIEN_TDLIB_JOBS Overrides the throttled parallel job count of the share build. ALIEN_TDLIB_SKIP_DIGEST Set to 1 to skip the archive verification of the downloaded TDLib source archive (SHA-256) or prebuilt tarball (npm sha512 integrity). The archives are fetched over TLS from URLs that already pin the commit, so this only trades away detection of a corrupted or re-rolled tarball. ALIEN_TDLIB_SKIP_VERSION Set to 1 to accept a system libtdjson of any version, bypassing the 1.8.66 floor. Unsupported: an older library may answer with different wire shapes, and the failures are silent. No bug reports for installs that used this. WATCHING FOR SCHEMA DRIFT Following the newest release means TDLib's API can move underneath a consumer without anyone editing this distribution. What matters is not which version arrived but whether the types that consumer uses still look the same. maint/bump-tdlib.pl (in the repository; not shipped) answers exactly that: perl maint/bump-tdlib.pl --consumer ../EV-Telegram-TDLib It resolves the newest published release, then diffs td_api.tl restricted to the types named anywhere in that consumer's sources, field by field. A release that touches none of them cannot change a wire shape the consumer hardcodes. "--master" compares against tdlib/td master instead, which is built and smoke-tested nowhere. Two things stay manual: the fallback release in inc/Alien/TDLib/Resolve.pm, used when npm is unreachable and worth advancing occasionally, and the vendored prebuilt/tdjson_export.h (CMake GenerateExportHeader boilerplate -- generic, but worth re-checking against a newer tree). LICENSE OF TDLIB TDLib itself is distributed under the Boost Software License 1.0. See https://github.com/tdlib/td for details. AUTHOR vividsnow LICENSE This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.