TDLib 빌드와 첫 연결 — 공식 빌드 안내 따라가기

먼저 고를 것 — 빌드할까, 있는 걸 쓸까

TDLib 은 C++ 로 된 오픈 소스라, 기본은 내 기기에서 직접 빌드해 씁니다. 다만 쓰려는 언어에 따라 길이 다릅니다.

내 언어	보통 쓰는 길
C++ (CMake 프로젝트)	TDLib 을 빌드해 정적·JSON 라이브러리로 연결
자바 · C#	공식 연결(바인딩)을 함께 빌드
파이썬·자바스크립트·고 등	JSON 라이브러리(tdjson)를 빌드해 그 언어에서 C 함수로 부르기

플랫폼·언어별 정확한 명령은 TDLib 공식 페이지(core.telegram.org/tdlib)에서 연결되는 빌드 안내 생성기가 만들어 줍니다. 운영체제와 언어를 고르면 그대로 붙여 넣을 명령이 나옵니다. 이 글은 그 전후에 알아 둘 것을 정리합니다.

필요한 도구

도구	조건(공식 안내)
C++ 컴파일러	C++17 을 지원하는 것 — 윈도우는 Visual Studio 의 C++ 도구
CMake	3.10 이상
라이브러리	OpenSSL · zlib
도구	gperf
선택	PHP — 문서 만들기·저사양 기기용 소스 나누기에만

윈도우에서는 OpenSSL·zlib·gperf 를 패키지 관리자(vcpkg)로 받아 CMake 에 그 위치를 알려 주는 방식이 일반적입니다. 빌드 안내 생성기에서 'Windows' 를 고르면 이 과정이 명령으로 나옵니다.

윈도우에서 실제로 빌드해 본 순서

아래는 빌드 안내 생성기에서 Windows · x64 · JSON 을 골랐을 때 나오는 순서를, 이 사이트가 실제로 돌려 본 그대로 옮긴 것입니다. 명령은 PowerShell 기준이고, vcpkg 는 생성기가 고정해 둔 판으로 맞춥니다.

git clone https://github.com/tdlib/td.git
cd td
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
git checkout (생성기가 알려 주는 고정 판 번호)
./bootstrap-vcpkg.bat
./vcpkg.exe install gperf:x64-windows openssl:x64-windows zlib:x64-windows
cd ..
mkdir build
cd build
cmake -A x64 -DCMAKE_INSTALL_PREFIX:PATH=../tdlib -DCMAKE_TOOLCHAIN_FILE:FILEPATH=../vcpkg/scripts/buildsystems/vcpkg.cmake ..
cmake --build . --target install --config Release

단계	걸린 시간(실측)
TDLib · vcpkg 받기, 고정 판 맞추기, 준비	1분 안쪽
vcpkg 로 gperf · openssl · zlib 설치	약 9분 30초
CMake 설정	약 11초
TDLib 빌드·설치	약 24분

측정 환경은 가상 PC(윈도우 11, CPU 8개, 메모리 12GB)이고, 메모리를 아끼려고 마지막 명령에 --parallel 4 를 붙여 동시 작업을 4개로 묶었습니다. PC 사양에 따라 시간은 달라집니다.

• vcpkg 는 처음 돌 때 필요한 도구(PowerShell 7 · 7-Zip)를 스스로 받아 씁니다.
• gperf 원본은 GNU 서버에서 받는데, 망에 따라 공식 서버가 시간 초과로 막힐 수 있습니다. 이번 실측에서도 한 번 그렇게 멈췄습니다. 그때는 같은 파일을 다른 GNU 미러에서 받아 vcpkg 의 downloads 폴더에 두고 다시 돌리면 됩니다. vcpkg 가 해시로 내용을 확인하므로 미러가 달라도 안전합니다.
• 빌드가 끝나면 tdlib/bin 에 tdjson.dll 과 함께 OpenSSL(libcrypto-3-x64.dll · libssl-3-x64.dll)과 zlib1.dll 이 생깁니다. 내 프로그램과 함께 네 파일을 같이 배포해야 합니다.

첫 연결 — 무엇이 오면 성공인가

1. 내 프로그램에서 tdjson 을 불러 TDLib 클라이언트를 만들고 받기(receive)를 돌리기 시작합니다.
2. 처음 오는 업데이트에 TDLib 판 번호(version 옵션)와 로그인 상태: 설정 기다림(authorizationStateWaitTdlibParameters)이 보이면 연결은 성공입니다. 실측에서는 판 번호 1.8.67 과 이 상태가 바로 왔습니다.
3. 여기서 setTdlibParameters 로 api_id·api_hash·저장 폴더를 넣으면 로그인 단계로 넘어갑니다(TDLib 이란).
4. 개발 중에는 설정의 시험 서버(use_test_dc) 값을 켜 실제 계정 대신 시험 계정으로 돌립니다(로그인 흐름).

사용할 수 있는 메서드는 TDLib 의 스키마 파일(td_api.tl)에 모두 적혀 있습니다. 스키마 읽는 법은 TL 스키마·레이어 읽는 법에 있습니다.