telegram-tui/docs/ios/tdlib-linking.md

TDLib iOS Linking Status

Local toolchain status:

• Xcode 26.5 is installed at /Applications/Xcode.app.
• iOS 26.5 simulator runtime is installed.
• scripts/check-ios-prereqs.sh passes.
• scripts/run-ios-simulator-app.sh launches the fake-backed SwiftUI shell in iOS Simulator.

Previous real TDLib blocker:

DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer cargo build -p tele-ios-ffi --target aarch64-apple-ios-sim --release

Observed failure:

[Your OS or architecture may be unsupported.] Failed to download file: Please try using the `pkg-config` or `local-tdlib` features.
404 Not Found
https://github.com/FedericoBruzzone/tdlib-rs/releases/download/v1.2.0/tdlib-1.8.29-ios-aarch64.zip

Interpretation:

• Rust, Swift, Xcode, and the iOS simulator runtime are working.
• The fake-backed iOS app shell can be built, installed, launched, and rendered.
• download-tdlib cannot be used for iOS because tdlib-rs 1.2.0 does not publish the iOS artifact requested by its build script.

Current real TDLib status:

• scripts/build-tdlib-ios.sh builds TDLib 1.8.29 locally for iOS device and simulator.
• .build/tdlib-ios/iphoneos/lib/libtdjson.1.8.29.dylib is arm64.
• .build/tdlib-ios/iphonesimulator/lib/libtdjson.1.8.29.dylib is a universal x86_64 + arm64 simulator dylib.
• scripts/check-ios-tdlib-linking.sh builds tele-ios-ffi for aarch64-apple-ios-sim with local TDLib.
• IOS_RUST_TARGET=aarch64-apple-ios scripts/build-ios-ffi-with-local-tdlib.sh builds tele-ios-ffi for device with local TDLib.
• scripts/build-ios-real-ffi-xcframework.sh packages simulator Rust slices into tele_ios_ffi.xcframework, packages local libtdjson into tdjson.xcframework, and writes generated Swift bindings into the Swift package's local Generated path.
• TELE_IOS_USE_LOCAL_FFI=1 scripts/build-ios-simulator-app.sh builds and packages the SwiftUI simulator app against the real Rust/TDLib FFI path, including Frameworks/libtdjson.dylib in the .app bundle.
• The repo patches tdlib-rs through crates/vendor/tdlib-rs because upstream src/build.rs does not handle target_os = "ios" for local-tdlib.

Selected path:

1. Keep download-tdlib for the terminal/macOS build path.
2. Build TDLib locally for iOS and iOS Simulator from the TDLib source commit matching TDLib 1.8.29.
3. Build tele-ios-ffi with tele-core/tdlib-local and LOCAL_TDLIB_PATH.
4. Package the resulting Rust FFI library and TDLib dylib into the iOS app/XCFramework path.

The TDLib source commit used for 1.8.29 is:

af69dd4397b6dc1bf23ba0fd0bf429fcba6454f6

This can be checked with:

npm info prebuilt-tdlib@td-1.8.29 tdlib --json

Build local TDLib artifacts:

DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer scripts/build-tdlib-ios.sh

This writes local, untracked outputs to:

.build/tdlib-ios/iphoneos/
.build/tdlib-ios/iphonesimulator/

Build the real iOS FFI path against local TDLib:

DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer scripts/build-ios-ffi-with-local-tdlib.sh

or for a device target:

DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer IOS_RUST_TARGET=aarch64-apple-ios scripts/build-ios-ffi-with-local-tdlib.sh

Package the real FFI path for the Swift app and build the simulator .app:

DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer scripts/build-ios-real-ffi-xcframework.sh
TELE_IOS_USE_LOCAL_FFI=1 DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer scripts/build-ios-simulator-app.sh

Known local prerequisites:

• Xcode with the iOS SDK installed.
• Homebrew build tools: brew install cmake gperf coreutils.
• Rust iOS targets: rustup target add aarch64-apple-ios-sim aarch64-apple-ios.
• scripts/build-tdlib-ios.sh builds only the required OpenSSL platforms through TDLib's vendored Python-Apple-support flow, with a local patch for the simulator target triple under Xcode 26.
• TDLib CMake uses TDLIB_IOS_DEPLOYMENT_TARGET=17.0 by default to match the Swift package minimum iOS version.
• TDLib's prepare_cross_compiling target is run as a host-side generation step before cross-compiling, so generated TL/MIME sources exist for the iOS build.

Example local blocker if these tools are missing:

Required tool not found: cmake

CMake 4.x compatibility is handled by passing -DCMAKE_POLICY_VERSION_MINIMUM=3.5 to TDLib's configure step.