Introducing a new way to review your PRs.

Read the announcement

ayugram / ayugramdesktop

Desktop Telegram client with good customization and Ghost mode.

View on GitHub

13 documents · Updated Nov 16, 2026

docs / build-system-codegen

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.cmake runs Python against Telegram/…/codegen_scheme.py and lib_tl/…/generate_tl.py to turn Telegram/SourceFiles/mtproto/scheme/api.tl and mtproto.tl into scheme.cpp, scheme.h, and dump-to-text helpers under the build tree. Telegram/cmake/td_scheme.cmake wraps this output in the td_scheme object 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.cmake invokes the codegen_lang target to generate lang_auto.cpp, lang_auto.h, counts, and key headers from Telegram/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 a LANG_KEYS_SUBSET compile definition to each source file. Telegram/cmake/td_lang.cmake owns the td_lang object library and its hand-written language parser/key sources.
  • Telegram/cmake/generate_numbers.cmake runs codegen_numbers to produce numbers.cpp and numbers.h from resource input; it is included by Telegram/cmake/td_ui.cmake along with style generation from lib_ui/cmake/generate_styles.cmake.
  • Telegram/cmake/generate_update_keys.cmake and Telegram/cmake/update_keys_header.cmake embed Telegram/Resources/update/root-public.pem, manifest.min.json, and manifest.sig verbatim as byte arrays in update_keys_data.h. Telegram/CMakeLists.txt always generates these for Telegram; Telegram/cmake/test_update_verify.cmake builds a focused verifier when test apps or special targets are enabled.
  • Telegram/cmake/generate_midl.cmake is Windows-only and runs midl for IDL files such as platform/win/windows_quiethours.idl and platform/win/windows_toastactivator.idl, choosing the MIDL /env from build_winarm/build_win64.
  • Telegram/cmake/qrhi_shaders.cmake compiles any shaders/*.vert, *.frag, or *.comp next to the current source directory into .qsb files with Qt's qsb, writes a generated shaders.qrc, and attaches it to Telegram.
  • Telegram/cmake/generate_models.cmake bakes every Telegram/Resources/art/**/*.obj mesh into .binobj with Telegram/…/obj2binobj.py, writes a generated models.qrc, and adds a bake_models dependency to Telegram. 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 when TDESKTOP_API_ID or TDESKTOP_API_HASH is empty, so stale docs block new builders early.
  • If TDESKTOP_UPDATE_CHANNEL or the canary CMake options in Telegram/cmake/telegram_options.cmake change, verify the compile definitions still match the runtime code that reads TDESKTOP_UPDATE_CHANNEL, TDESKTOP_CANARY_COUNTER, TDESKTOP_CANARY_COMMIT, TDESKTOP_CANARY_PUBLIC_CHANNEL, TDESKTOP_CANARY_PRIVATE_CHANNEL_ID, and TDESKTOP_CANARY_METADATA_MSG_ID.
  • If the TL schema files consumed by Telegram/cmake/td_scheme.cmake change 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.strings or language-key usage conventions change, verify Telegram/cmake/generate_lang.cmake and Telegram/cmake/td_lang.cmake; non-IDE generators generate per-source subset headers by scanning all .cpp, .h, and .mm files, while Visual Studio and Xcode skip that path.
  • If update trust files under Telegram/Resources/update/ change, also check Telegram/cmake/generate_update_keys.cmake, Telegram/cmake/update_keys_header.cmake, and Telegram/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.cmake or Telegram/cmake/generate_models.cmake; both generate QRC files in the build tree and attach custom targets to Telegram, so missing QRC_GENERATED_FROM or 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-tidy custom banned functions change, update tools/…/hook.py expectations and run tools/…/test_hook.py; the hook parses .clang-tidy directly and reports replacements from that file.

Risks

  • Telegram/cmake/update_keys_header.cmake reads 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 or manifest.sig, update verification can fail even though the build succeeds.
  • Telegram/cmake/generate_lang.cmake uses file(GLOB_RECURSE ... CONFIGURE_DEPENDS) over all source files for language subsets on non-Visual Studio/Xcode generators; adding a large generated-source tree under Telegram/SourceFiles can make configure/regeneration unexpectedly expensive and can also add LANG_KEYS_SUBSET definitions to files that were not intended to participate.
  • Telegram/cmake/lib_fido2.cmake deliberately 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.cmake shells out to xcode-select, xcrun swift-stdlib-tool, and mkdir; 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.