Build System and Code Generation
Overview
The repository is configured from the root CMakeLists.txt, which sets the CMake version range, parses Telegram/build/version, creates the Telegram project, loads shared helper modules from cmake/, and then enters the helper subtree plus the application subtree with add_subdirectory(cmake) and add_subdirectory(Telegram). In this checkout the top-level cmake/ directory is empty, but the root file still expects helper modules such as cmake/variables.cmake, cmake/options.cmake, and cmake/external/qt/package.cmake; those are therefore provided by the build environment/submodule layout rather than by files covered here.
The main target is declared in Telegram/CMakeLists.txt as add_executable(Telegram WIN32 MACOSX_BUNDLE). That file is the build graph hub: it adds internal libraries (lib_rpl, lib_crl, lib_base, lib_ui, lib_tl, and others), adds Telegram/codegen, defines src_loc and res_loc, includes all target-fragment CMake files under Telegram/cmake/, and finally links Telegram against the generated/object targets and external dependency aliases. Telegram/cmake/telegram_options.cmake is the configuration gate for API credentials, update channel macros, packaged-build behavior, crash-report/autoupdate toggles, closed-alpha special-target behavior, and the macOS Swift-6 translation toggle.
Generated code is wired as explicit CMake custom commands and generated targets:
Telegram/cmake/generate_scheme.cmakeruns Python against Telegram/…/codegen_scheme.py and lib_tl/…/generate_tl.py to turnTelegram/SourceFiles/mtproto/scheme/api.tlandmtproto.tlinto scheme.cpp, scheme.h, and dump-to-text helpers under the build tree.Telegram/cmake/td_scheme.cmakewraps this output in thetd_schemeobject library used by MTProto and export code.- Telegram/…/codegen_scheme.py defines the TL generation options: MTP naming prefixes, built-in TL types, flag inheritance, skipped primitives/templates, type-id exceptions, renamed types, and dump-to-text include wiring. Changes here alter the generated MTP API surface consumed through
tdesktop::td_scheme. Telegram/cmake/generate_lang.cmakeinvokes thecodegen_langtarget to generate lang_auto.cpp, lang_auto.h, counts, and key headers fromTelegram/Resources/langs/lang.strings. With non-Visual Studio/Xcode generators it also scans all source files and emits per-source language-key subset headers, adding aLANG_KEYS_SUBSETcompile definition to each source file.Telegram/cmake/td_lang.cmakeowns thetd_langobject library and its hand-written language parser/key sources.Telegram/cmake/generate_numbers.cmakerunscodegen_numbersto produce numbers.cpp and numbers.h from resource input; it is included byTelegram/cmake/td_ui.cmakealong with style generation fromlib_ui/cmake/generate_styles.cmake.Telegram/cmake/generate_update_keys.cmakeandTelegram/cmake/update_keys_header.cmakeembedTelegram/Resources/update/root-public.pem, manifest.min.json, andmanifest.sigverbatim as byte arrays in update_keys_data.h. Telegram/CMakeLists.txt always generates these forTelegram;Telegram/cmake/test_update_verify.cmakebuilds a focused verifier when test apps or special targets are enabled.Telegram/cmake/generate_midl.cmakeis Windows-only and runsmidlfor IDL files such asplatform/win/windows_quiethours.idlandplatform/win/windows_toastactivator.idl, choosing the MIDL/envfrombuild_winarm/build_win64.Telegram/cmake/qrhi_shaders.cmakecompiles anyshaders/*.vert,*.frag, or*.compnext to the current source directory into.qsbfiles with Qt'sqsb, writes a generatedshaders.qrc, and attaches it toTelegram.Telegram/cmake/generate_models.cmakebakes everyTelegram/Resources/art/**/*.objmesh into.binobjwith Telegram/…/obj2binobj.py, writes a generatedmodels.qrc, and adds abake_modelsdependency toTelegram. Telegram/…/binobj2obj.py is the inverse developer tool for porting existing binary meshes back to source.obj.
Target-fragment CMake files under Telegram/cmake/ define build-time object/static libraries rather than runtime subsystems. td_mtproto.cmake, td_export.cmake, td_iv.cmake, td_tde2e.cmake, td_ui.cmake, and td_webauthn.cmake collect source lists, precompiled headers, include paths, generated-source dependencies, and public/private links for major application areas. lib_ffmpeg.cmake, lib_tgcalls.cmake, lib_stripe.cmake, lib_prisma.cmake, and lib_fido2.cmake wrap third-party or quasi-third-party code into target aliases consumed by Telegram/CMakeLists.txt; lib_fido2.cmake can either use packaged libfido2 via pkg-config or compile vendored libfido2/libcbor with generated headers and platform HID dependencies.
Packaging and platform output rules also live in Telegram/CMakeLists.txt. The resource list adds QRC files, Windows resource/manifest files, language strings, and numbers.txt; target_prepare_qrc(Telegram) prepares Qt resources. macOS builds add .icon resources for Xcode, generate an .icns outside Xcode with iconutil or png2icns, copy RCC files and crashpad into the app bundle, set bundle identifiers/entitlements/output name, and optionally copy the Swift runtime through Telegram/cmake/telegram_apple_swift_runtime.cmake. Windows builds adjust DirectX and PDB link behavior and may add Updater, Packer, or StartupTask helper executables. Linux packaged builds (LINUX AND DESKTOP_APP_USE_PACKAGED) configure DBus/AppStream metadata, run Telegram/cmake/generate_appstream_changelog.cmake, and install the binary, desktop file, service file, metainfo file, and hicolor icons.
Developer-facing build documentation is in docs/building-linux.md, docs/building-mac.md, and docs/building-win.md. Those docs route contributors through recursive clone, dependency preparation scripts under Telegram/build/prepare/, and platform-specific configure/build commands. All three pass TDESKTOP_API_ID and TDESKTOP_API_HASH; docs/api_credentials.md records the official AyuGram credentials used in those examples, while Telegram/cmake/telegram_options.cmake enforces non-empty credentials unless TDESKTOP_API_TEST is set. .devcontainer.json defines a VS Code CentOS container using a tdesktop:centos_env image, Ninja Multi-Config, an out build directory, and a copied compile_commands.json.
Developer tooling under tools/ is focused on review-time checks. tools/…/hook.py can run as an edit hook or pre-commit hook; it reads .clang-tidy for banned Qt helper functions, limits newly added comments in C/C++/ObjC++ files, exempts license headers and test harness paths, and has unit coverage in tools/…/test_hook.py. tools/…/compile_db.py rewrites Ninja's compilation database into out/…/compile_commands.json for clang-tidy by replacing the compiler with clang/clang-cl, dropping unsupported flags, adding platform-specific arguments, and filtering to real C++/ObjC++ translation units; tools/…/README.md documents the clang-tidy and hook setup flow.
Coupling
- If API credential handling changes in
Telegram/cmake/telegram_options.cmake, also update docs/building-linux.md, docs/building-mac.md, docs/building-win.md, and docs/api_credentials.md; configure will fail before compilation whenTDESKTOP_API_IDorTDESKTOP_API_HASHis empty, so stale docs block new builders early. - If
TDESKTOP_UPDATE_CHANNELor the canary CMake options inTelegram/cmake/telegram_options.cmakechange, verify the compile definitions still match the runtime code that readsTDESKTOP_UPDATE_CHANNEL,TDESKTOP_CANARY_COUNTER,TDESKTOP_CANARY_COMMIT,TDESKTOP_CANARY_PUBLIC_CHANNEL,TDESKTOP_CANARY_PRIVATE_CHANNEL_ID, andTDESKTOP_CANARY_METADATA_MSG_ID. - If the TL schema files consumed by
Telegram/cmake/td_scheme.cmakechange shape, check Telegram/…/codegen_scheme.py; it hard-codes type-id exceptions, renamed TL types, flag inheritance, and skipped built-ins, so schema drift can compile into wrong generated MTP names or conversions rather than failing at the CMake layer. - If
Telegram/Resources/langs/lang.stringsor language-key usage conventions change, verifyTelegram/cmake/generate_lang.cmakeandTelegram/cmake/td_lang.cmake; non-IDE generators generate per-source subset headers by scanning all .cpp, .h, and.mmfiles, while Visual Studio and Xcode skip that path. - If update trust files under
Telegram/Resources/update/change, also checkTelegram/cmake/generate_update_keys.cmake,Telegram/cmake/update_keys_header.cmake, andTelegram/cmake/test_update_verify.cmake; the manifest bytes are embedded verbatim because signatures cover exact bytes. - If adding shader or model source assets, route through
Telegram/cmake/qrhi_shaders.cmakeorTelegram/cmake/generate_models.cmake; both generate QRC files in the build tree and attach custom targets toTelegram, so missingQRC_GENERATED_FROMor dependency updates can make AUTORCC ignore generated inputs. - If packaged Linux metadata changes in the source tree, verify the install rules at the end of Telegram/CMakeLists.txt plus
Telegram/cmake/generate_appstream_changelog.cmake; AppStream metadata is configured into the build tree and then modified in place by the changelog generator before install. - If
.clang-tidycustom banned functions change, update tools/…/hook.py expectations and run tools/…/test_hook.py; the hook parses.clang-tidydirectly and reports replacements from that file.
Risks
Telegram/cmake/update_keys_header.cmakereads update manifests as raw hex bytes and writes them into update_keys_data.h; if any future generator normalizes whitespace, text encoding, or line endings for manifest.min.json ormanifest.sig, update verification can fail even though the build succeeds.Telegram/cmake/generate_lang.cmakeusesfile(GLOB_RECURSE ... CONFIGURE_DEPENDS)over all source files for language subsets on non-Visual Studio/Xcode generators; adding a large generated-source tree underTelegram/SourceFilescan make configure/regeneration unexpectedly expensive and can also addLANG_KEYS_SUBSETdefinitions to files that were not intended to participate.Telegram/cmake/lib_fido2.cmakedeliberately keeps some vendored directories off the public include path to avoid header shadowing (openbsd-compat/time.h and libfido2's webauthn.h); changing include visibility there can break Windows SDK WebAuthn builds or recurse through shim headers.Telegram/cmake/telegram_apple_swift_runtime.cmakeshells out toxcode-select,xcrun swift-stdlib-tool, andmkdir; macOS packaging can fail late in POST_BUILD if Xcode command-line tools or Swift runtime layout differ from the assumed Xcode default toolchain path.- tools/…/compile_db.py rewrites compiler commands by filtering known flags and swapping in clang/clang-cl; new compiler flags from the CMake toolchain may be silently dropped only if added to its allow/drop logic, otherwise clang-tidy can fail on a database that the normal build accepts.