Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated README.md #1679

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Updated README.md #1679

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
195 changes: 129 additions & 66 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,106 +11,169 @@ There are several things we require from **all developers** for the moment.
3. Please study our [**security guidelines**](https://core.telegram.org/mtproto/security_guidelines) and take good care of your users' data and privacy.
4. Please remember to publish **your** code too in order to comply with the licences.

# Quick Compilation Guide
# Telegram iOS Source Code Setup and Build Guide

## Get the Code
## Set Up Apple Developer Account

```
1. Create a free or paid Apple Developer Account at https://developer.apple.com
2. Locate your:
- Developer email address
- Team ID (in Membership Details section)

## Clone the Repository

Clone the Telegram iOS repository with all submodules:
```bash
git clone --recursive -j8 https://github.com/TelegramMessenger/Telegram-iOS.git
```

## Setup Xcode
## Configure Development Environment

Install Xcode (directly from https://developer.apple.com/download/applications or using the App Store).
Generate a random identifier for your bundle ID:
```bash
openssl rand -hex 8
```

## Adjust Configuration
Edit `build-system/template_minimal_development_configuration.json`:
- Add `api_id` and `api_hash`
- Include your Apple Developer email
- Add your Team ID
- Set bundle identifier as `org.{random identifier}`

1. Generate a random identifier:
```
openssl rand -hex 8
```
2. Create a new Xcode project. Use `Telegram` as the Product Name. Use `org.{identifier from step 1}` as the Organization Identifier.
3. Open `Keychain Access` and navigate to `Certificates`. Locate `Apple Development: [email protected] (XXXXXXXXXX)` and double tap the certificate. Under `Details`, locate `Organizational Unit`. This is the Team ID.
4. Edit `build-system/template_minimal_development_configuration.json`. Use data from the previous steps.
## Step 5: Generate Xcode Project

## Generate an Xcode project

```
Run the project generation command:
```bash
python3 build-system/Make/Make.py \
--overrideXcodeVersion \
--cacheDir="$HOME/telegram-bazel-cache" \
generateProject \
--configurationPath=build-system/template_minimal_development_configuration.json \
--disableProvisioningProfiles \
--xcodeManagedCodesigning
```

# Advanced Compilation Guide
## Step 6: Build and Run

## Xcode
1. Open the generated Xcode project
2. Select an iOS simulator
3. Build and run the project (⌘R)

1. Copy and edit `build-system/appstore-configuration.json`.
2. Copy `build-system/fake-codesigning`. Create and download provisioning profiles, using the `profiles` folder as a reference for the entitlements.
3. Generate an Xcode project:
```
python3 build-system/Make/Make.py \
--cacheDir="$HOME/telegram-bazel-cache" \
generateProject \
--configurationPath=configuration_from_step_1.json \
--codesigningInformationPath=directory_from_step_2
```
## APNS (Apple Push Notification Service) Certificates

## IPA
### Generating APNS Certificate

1. Repeat the steps from the previous section. Use distribution provisioning profiles.
2. Run:
```
python3 build-system/Make/Make.py \
--cacheDir="$HOME/telegram-bazel-cache" \
build \
--configurationPath=...see previous section... \
--codesigningInformationPath=...see previous section... \
--buildNumber=100001 \
--configuration=release_arm64
```
1. Go to https://developer.apple.com/account/resources/certificates/list

# FAQ
2. Create Apple Push Notifications service SSL Certificate:
- Choose "Apple Push Notifications service SSL (Sandbox & Production)"
- This single certificate works for both development and production environments

## Xcode is stuck at "build-request.json not updated yet"
3. Certificate Generation Process:
- Click the "+" button in the Certificates section
- Select the Apple Push Notifications service SSL certificate
- Follow the certificate generation wizard
- You'll need to:
* Generate a Certificate Signing Request (CSR) using Keychain Access
* Upload the CSR to Apple's developer portal
* Download the generated certificate

Occasionally, you might observe the following message in your build log:
```
"/Users/xxx/Library/Developer/Xcode/DerivedData/Telegram-xxx/Build/Intermediates.noindex/XCBuildData/xxx.xcbuilddata/build-request.json" not updated yet, waiting...
```
### Exporting Certificate to .p12 and .pem Format

Should this occur, simply cancel the ongoing build and initiate a new one.
1. Open Keychain Access
2. Find the downloaded APNS certificate
3. Export to .p12:
- Right-click and select "Export"
- Choose .p12 format
- Set a strong password for the exported file

## Telegram_xcodeproj: no such package
4. Convert .p12 to .pem:
```bash
# Convert the certificate to PEM format
openssl pkcs12 -in apns-cert.p12 -out apns-cert.pem -nodes -clcerts
```

Following a system restart, the auto-generated Xcode project might encounter a build failure accompanied by this error:
```
ERROR: Skipping '@rules_xcodeproj_generated//generator/Telegram/Telegram_xcodeproj:Telegram_xcodeproj': no such package '@rules_xcodeproj_generated//generator/Telegram/Telegram_xcodeproj': BUILD file not found in directory 'generator/Telegram/Telegram_xcodeproj' of external repository @rules_xcodeproj_generated. Add a BUILD file to a directory to mark it as a package.
```
## Preparing for App Store Distribution

### Create App Store Connect Record

If you encounter this issue, re-run the project generation steps in the README.
1. Go to https://appstoreconnect.apple.com
2. Click "My Apps" and "+"
3. Select "New App"
4. Fill in details:
- Platform: iOS
- Name: [Your App Name]
- Bundle ID: org.[random identifier].Telegram
- SKU: [random identifier]

### Generate Certificates

# Tips
#### Development Certificate
1. Go to https://developer.apple.com/account/resources/certificates/list
2. Create iOS App Development certificate
3. Generate Certificate Signing Request (CSR) using Keychain Access

## Codesigning is not required for simulator-only builds
#### Distribution Certificate
1. Return to certificates page
2. Create "App Store and Ad Hoc" certificate
3. Upload CSR
4. Download and install certificate

### Codesigning Folder Structure

Prepare a `my-codesigning` folder with the following exact structure:

Add `--disableProvisioningProfiles`:
```
python3 build-system/Make/Make.py \
--cacheDir="$HOME/telegram-bazel-cache" \
generateProject \
--configurationPath=path-to-configuration.json \
--codesigningInformationPath=path-to-provisioning-data \
--disableProvisioningProfiles
my-codesigning/
├── certs/
│ ├── Public.cer
│ └── SelfSigned.p12
└── profiles/
├── BroadcastUpload.mobileprovision
├── Intents.mobileprovision
├── NotificationContent.mobileprovision
├── NotificationService.mobileprovision
├── Share.mobileprovision
├── Telegram.mobileprovision
├── WatchApp.mobileprovision
├── WatchExtension.mobileprovision
└── Widget.mobileprovision
```

## Versions
### Create App Identifiers

Each release is built using a specific Xcode version (see `versions.json`). The helper script checks the versions of the installed software and reports an error if they don't match the ones specified in `versions.json`. It is possible to bypass these checks:
1. Go to Identifiers section
2. Create identifiers for:
- Main App
- Notification Service Extension
- Share Extension
- Widget
- Watch App and Extension

### Create Provisioning Profiles

1. Go to Profiles section
2. Create profiles for each app identifier
3. Select "App Store" type
4. Download all profiles
5. Ensure exact naming as shown in the codesigning folder structure

### Build for Distribution

```bash
python3 build-system/Make/Make.py \
--overrideXcodeVersion \
--cacheDir="$HOME/telegram-bazel-cache" \
build \
--configurationPath=build-system/my-appstore-configuration.json \
--codesigningInformationPath=build-system/my-codesigning \
--buildNumber=100008 \
--configuration=release_arm64
```
python3 build-system/Make/Make.py --overrideXcodeVersion build ... # Don't check the version of Xcode
```

### Upload to TestFlight

1. Use Apple's Transporter app
2. Sign in with Apple Developer account
3. Upload generated IPA
4. Configure beta testing in App Store Connect