Telegram iOS — Complete Setup Guide (Bazel + Xcode)

This guide explains how to correctly clone, configure, and run the Telegram iOS app using Bazel + Xcode, avoiding all common pitfalls.

It is based on real errors and obstacles encountered during setup:

• Xcode version mismatch
• Missing configuration files
• Provisioning / signing errors
• Extensions breaking the build
• Confusion between Terminal and Xcode
• Bazel / rules_xcodeproj misleading errors

If you follow this guide step by step, the app will run in the iOS Simulator and allow login.

---

Important Concepts (Read First)

• Bazel is the real build system
• Xcode does NOT build Telegram directly
• Xcode is used only for:
  • editing code
  • indexing
  • debugging
  • launching the app (via Bazel scripts)

The script build-system/Make/Make.py:

• validates environment
• generates the Xcode project
• configures Bazel flags

If this is not understood, most errors will be repeated.

---

1. Requirements

System

• macOS
• Python 3.10+
• Xcode installed

Verify active Xcode

xcode-select -p

Expected output:

/Applications/Xcode.app/Contents/Developer

Check version:

xcodebuild -version

---

2. Clone the Repository

❌ Cloning without submodules will cause obscure build failures.

Correct commands:

git clone <TELEGRAM_IOS_REPOSITORY_URL>
cd Telegram-iOS
git submodule update --init --recursive

⚠️ Do NOT skip --recursive.

---

3. Understand Build Configuration Files

These files do NOT exist (even if mentioned elsewhere):

• development_configuration.json
• local-dev.json (by default)

Existing configuration files:

ls build-system/*.json

Typical output:

appcenter-configuration.json
appstore-configuration.json
template_minimal_development_configuration.json

👉 For local development + simulator, always start from:

template_minimal_development_configuration.json

---

4. Create Your Local Configuration

❌ Real mistake: referencing a config file that does not exist.

Create the local config:

cp build-system/template_minimal_development_configuration.json build-system/local-dev.json

📍 The file must be inside build-system/. Edit build-system/local-dev.json only if required by the template. Do not invent keys.

---

5. Generate the Xcode Project

Typical errors at this stage:

• Xcode version mismatch
• Missing codesigning arguments
• Provisioning profile errors (even for simulator)
• Extensions breaking the build

✅ Correct and Complete Command

Run in macOS Terminal (not Xcode):

python3 build-system/Make/Make.py \
  --cacheDir="$HOME/telegram-bazel-cache" \
  --overrideXcodeVersion \
  generateProject \
  --configurationPath build-system/local-dev.json \
  --xcodeManagedCodesigning \
  --disableProvisioningProfiles \
  --disableExtensions

Why these flags matter

• --overrideXcodeVersion Prevents failure if your Xcode version is newer than required

• --xcodeManagedCodesigning Required by the script

• --disableProvisioningProfiles Prevents Bazel from searching for .mobileprovision files

• --disableExtensions Skips extension targets that require extra signing If this command fails, do not continue.

---

6. Open the Project in Xcode

Open exactly:

Telegram/Telegram.xcodeproj

❌ Do NOT open:

• the repo folder
• any .xcworkspace
• a newly created project

---

7. Xcode Setup (Minimal)

Select:

• Scheme: Telegram
• Device: iPhone Simulator (iOS 18.x)

❌ Do NOT modify:

• Bundle Identifier
• Development Team
• Automatic Signing
• Provisioning Profiles

---

8. Fix “No Account for Team …” Error (Real Case)

If Xcode fails on the BazelDependencies target:

In Xcode:

1. Select target BazelDependencies
2. Go to Build Settings → Signing
3. Set:

Code Signing Identity → Sign to Run Locally

📌 This helps Xcode run auxiliary targets without requiring real signing.

---

9. Run the App

Press:

Cmd + R

What actually happens:

• Xcode runs scripts
• Scripts call Bazel
• Bazel builds the app
• App installs in the simulator
• Debugger attaches

👉 Xcode does not build Telegram traditionally. If successful:

• App launches
• Login works
• UI is functional

---

FAQ

❓ Do I need to run Make.py every time?

No. Run generateProject only when:

• switching branches
• BUILD files change
• large git pull

For daily development:

• Just Cmd + R in Xcode

---

❓ Why does “Prebuild / Indexing” appear and disappear?

This is normal:

• Xcode indexing
• Bazel resolving dependencies
• rules_xcodeproj scripts running It is not an error.

---

❓ Do I need to wait for indexing before running Make.py ?

No.

• Make.py runs in Terminal
• Xcode indexing is independent

---

❓ Why does the UI not fully match iOS 18 system styles?

Telegram uses a custom UI framework. Not all system visual styles are adopted automatically. This is expected behavior.

---

❓ Why should signing settings not be modified manually?

Because:

• Bazel controls the build
• Xcode is only a frontend
• Manual signing changes break consistency

---