TDLib

TDLib (Telegram Database library) is a cross-platform library for building Telegram clients. It can be easily used from almost any programming language.

Table of Contents

• Features
• Examples and documentation
• Dependencies
• Building
• Installing dependencies
• Using in CMake C++ projects
• Using in Java projects
• Using in .NET projects
• Using with other programming languages
• License

Features

TDLib has many advantages. Notably TDLib is:

• Cross-platform: TDLib can be used on Android, iOS, Windows, macOS, Linux, Windows Phone, WebAssembly, watchOS, tvOS, Tizen, Cygwin. It should also work on other *nix systems with or without minimal effort.
• Multilanguage: TDLib can be easily used with any programming language that is able to execute C functions. Additionally it already has native Java (using JNI) bindings and .NET (using C++/CLI and C++/CX) bindings.
• Easy to use: TDLib takes care of all network implementation details, encryption and local data storage.
• High-performance: in the Telegram Bot API, each TDLib instance handles more than 23000 active bots simultaneously.
• Well-documented: all TDLib API methods and public interfaces are fully documented.
• Consistent: TDLib guarantees that all updates are delivered in the right order.
• Reliable: TDLib remains stable on slow and unreliable Internet connections.
• Secure: all local data is encrypted using a user-provided encryption key.
• Fully-asynchronous: requests to TDLib don't block each other or anything else, responses are sent when they are available.

Examples and documentation

Take a look at our examples. See our Getting Started tutorial for a description of basic TDLib concepts. See description of our JSON, C++, Java and .NET interfaces. See the td_api.tl scheme or the automatically generated HTML documentation for a list of all available TDLib methods and classes.

Dependencies

TDLib depends on:

• C++14 compatible compiler (Clang 3.4+, GCC 4.9+, MSVC 19.0+ (Visual Studio 2015+), Intel C++ Compiler 17+)
• OpenSSL
• zlib
• gperf (build only)
• CMake (3.0.2+, build only)
• PHP (optional, for documentation generation)
• Doxygen (optional, for documentation generation)

Building

Install all TDLib dependencies as described in Installing dependencies. Then enter directory containing TDLib sources and compile them using CMake:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build .

To build TDLib on low memory devices you can use SplitSource.php before compiling main TDLib source code and compile only needed targets:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --target prepare_cross_compiling
cd ..
php SplitSource.php
cd build
cmake --build . --target tdjson
cmake --build . --target tdjson_static
cd ..
php SplitSource.php --undo

In our tests clang 6.0 with libc++ required less than 500 MB of RAM per file and GCC 6.3 used less than 1 GB of RAM per file.

Installing dependencies

macOS

• Install the latest Xcode command line tools, for example, via xcode-select --install.
• Install other dependencies, for example, using Homebrew:

brew install gperf cmake openssl

• Build TDLib with CMake as explained in building. You will likely need to manually specify path to the installed OpenSSL to CMake, e.g.,

cmake -DCMAKE_BUILD_TYPE=Release -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl/ ..

Windows

• Download and install Microsoft Visual Studio 2015 or later.
• Download and install gperf. Add the path to gperf.exe to the PATH environment variable.
• Install vcpkg.
• Run the following commands to install TDLib dependencies using vcpkg:

cd <path to vcpkg>
.\vcpkg.exe install openssl:x64-windows openssl:x86-windows zlib:x64-windows zlib:x86-windows

• Download and install CMake; choose "Add CMake to the system PATH" option while installing.
• Build TDLib with CMake as explained in building, but instead of cmake -DCMAKE_BUILD_TYPE=Release .. use

cmake -DCMAKE_TOOLCHAIN_FILE=<path to vcpkg>\scripts\buildsystems\vcpkg.cmake ..

To build 64-bit TDLib using MSVC, you will need to additionally specify parameter -A x64 to CMake. To build TDLib in Release mode using MSVC, you will need to additionally specify parameter --config Release to the cmake --build . command.

Linux

• Install all dependencies using your package manager.

Using in CMake C++ projects

For C++ projects that use CMake, the best approach is to build TDLib as part of your project or to use a prebuilt installation.

There are several libraries that you could use in your CMake project:

• Td::TdJson, Td::TdJsonStatic — dynamic and static version of a JSON interface. This has a simple C interface, so it can be easily used with any programming language that is able to execute C functions. See td_json_client and td_log documentation for more information.
• Td::TdStatic — static library with C++ interface for general usage. See Client and Log documentation for more information.
• Td::TdCoreStatic — static library with low-level C++ interface intended mostly for internal usage. See ClientActor and Log documentation for more information.

For example, part of your CMakeLists.txt may look like this:

add_subdirectory(td)
target_link_libraries(YourTarget PRIVATE Td::TdStatic)

Or you could install TDLib and then reference it in your CMakeLists.txt like this:

find_package(Td 1.3.2 REQUIRED)
target_link_libraries(YourTarget PRIVATE Td::TdStatic)

See example/cpp/CMakeLists.txt.

Using in Java projects

TDLib provides native Java interface through JNI. To enable it, specify option -DTD_ENABLE_JNI=ON to CMake.

See example/java for example of using TDLib from Java and detailed build and usage instructions.

Using in .NET projects

TDLib provides native .NET interface through C++/CLI and C++/CX. To enable it, specify option -DTD_ENABLE_DOTNET=ON to CMake. .NET Core doesn't support C++/CLI, so if .NET Core is used, then TDLib JSON interface should be used through P/Invoke instead.

See example/csharp for example of using TDLib from C# and detailed build and usage instructions. See example/uwp for example of using TDLib from C# UWP application and detailed build and usage instructions for Visual Studio Extension "TDLib for Universal Windows Platform".

When TDLib is built with TD_ENABLE_DOTNET option enabled, C++ documentation is removed from some files. You need to checkout these files to return C++ documentation back:

git checkout td/telegram/Client.h td/telegram/Log.h td/tl/TlObject.h

Using from other programming languages

TDLib provides efficient native C++, Java, and .NET interfaces. But for most use cases we suggest to use the JSON interface, which can be easily used with any programming language that is able to execute C functions. See td_json_client and td_log documentation for detailed JSON interface description, the td_api.tl scheme or the automatically generated HTML documentation for a list of all available TDLib methods and classes.

See example/python/tdjson_example.py and example/ruby/example.rb for examples of such usage.

License

TDLib is licensed under the terms of the Boost Software License. See LICENSE_1_0.txt for more information.