Scheme: esensi, konfigurasi dan peluncuran di Xcode

Apa itu Scheme di Xcode?

Scheme di Xcode adalah file XML (ekstensi .xcscheme) yang menggambarkan urutan aksi dan parameternya untuk membangun dan menganalisis aplikasi. Setiap Scheme terhubung ke satu atau beberapa target dan menentukan dengan konfigurasi apa (Debug, Release, AdHoc) setiap aksi dijalankan. Scheme adalah analog dari Build Variant di Android, tetapi dengan struktur yang lebih fleksibel: satu skema dapat berisi target yang berbeda untuk aksi yang berbeda.

Xcode secara otomatis membuat skema untuk setiap target saat pertama kali proyek dibuka. Nama default skema sama dengan nama target. Jika proyek memiliki target tes, Xcode secara otomatis menambahkannya ke aksi Test pada skema target utama. Untuk proyek dengan banyak target (aplikasi utama + watchOS + extension) Xcode membuat skema terpisah untuk masing-masing, tetapi Anda dapat membuat satu skema yang membangun semua target sekaligus.

Skema disimpan di direktori xcshareddata/xcschemes/ (untuk shared) atau xcuserdata/<user>/xcschemes/ (untuk private). Skema shared masuk ke Git dan digunakan oleh seluruh tim. Skema private disimpan secara lokal dan tidak disinkronkan. File .xcscheme memiliki format XML dengan elemen akar <Scheme>. Di dalamnya ada blok untuk setiap aksi: BuildAction, TestAction, LaunchAction, ProfileAction, AnalyzeAction, ArchiveAction.

Struktur file .xcscheme

.xcscheme adalah file XML yang dapat diedit secara manual atau melalui Xcode. Elemen utama: <BuildAction> (daftar target yang dibangun), <TestAction> (referensi ke target tes), <LaunchAction> (konfigurasi peluncuran), <ProfileAction>, <AnalyzeAction>, <ArchiveAction>. Setiap blok berisi atribut buildConfiguration yang menentukan konfigurasi (Debug/Release) yang digunakan untuk aksi tersebut.

Aksi Scheme: Build, Run, Test, Profile, Analyze, Archive

Scheme terdiri dari enam aksi, masing-masing dapat dikonfigurasi secara independen. Build Action menentukan target mana yang dibangun dan dalam urutan apa. Run Action — bagaimana aplikasi diluncurkan: dengan argumen, variabel lingkungan dan konfigurasi apa. Test Action — tes mana yang dijalankan dan opsi code coverage apa yang aktif. Profile Action — peluncuran dengan alat Instruments untuk pemrofilan. Analyze Action — analisis statis kode dengan Clang Static Analyzer. Archive Action — build untuk publikasi di App Store atau distribusi AdHoc.

Untuk setiap aksi dapat diatur build configuration terpisah. Biasanya untuk Run dan Test digunakan Debug, untuk Archive — Release. Build configuration menentukan kumpulan flag compiler, optimasi dan informasi debugging. Xcode menyediakan dua konfigurasi standar: Debug (tanpa optimasi, dengan simbol debug) dan Release (dengan optimasi, tanpa informasi debug). Pengembang dapat menambahkan konfigurasi khusus melalui project.xcconfig.

Aksi Archive sangat penting — aksi ini membuat .xcarchive yang kemudian diekspor ke .ipa untuk App Store atau AdHoc. Archive Action secara default menggunakan konfigurasi Release, tetapi dapat dialihkan ke AdHoc atau Distribution. Di Archive Action juga tersedia flag revealArchiveInOrganizer — setelah pengarsipan selesai, Xcode membuka Organiser untuk aksi selanjutnya dengan arsip.

<!-- Contoh .xcscheme untuk aplikasi iOS -->
<Scheme
  LastUpgradeVersion = "1500"
  version = "1.7">

  <BuildAction
    parallelizeBuildables = "YES"
    buildImplicitDependencies = "YES">
    <BuildActionEntries>
      <BuildActionEntry
        buildForTesting = "YES"
        buildForRunning = "YES"
        buildForProfiling = "YES"
        buildForArchiving = "YES"
        buildForAnalyzing = "YES">
        <BuildableReference
          BuildableIdentifier = "primary"
          BlueprintIdentifier = "ABCD1234"
          BuildableName = "MyApp.app"
          BlueprintName = "MyApp"
          ReferencedContainer = "container:MyApp.xcodeproj">
        </BuildableReference>
      </BuildActionEntry>
    </BuildActionEntries>
  </BuildAction>

  <LaunchAction
    buildConfiguration = "Debug"
    selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
    enableAddressSanitizer = "YES">
  </LaunchAction>
</Scheme>

Membuat dan mengonfigurasi Scheme

Sanitizer diagnostik

Membuat skema baru dilakukan melalui menu Xcode: Product → Scheme → New Scheme atau dengan tombol “+” di panel Scheme (di samping tombol Run). Saat membuat, target dipilih untuk skema tersebut. Jika skema dipilih sebagai “duplicate”, Xcode secara otomatis menyalin pengaturan dari skema yang ada. Skema baru secara default disimpan sebagai private — untuk mempublikasikan ke tim, Anda perlu mengaktifkan Shared di Manage Schemes.

Jendela Edit Scheme (Product → Scheme → Edit Scheme) berisi enam tab sesuai jumlah aksi. Di setiap tab Anda dapat mengubah build configuration, argumen peluncuran, variabel lingkungan dan flag diagnostik. Di tab Run tersedia opsi: executable (biner mana yang dijalankan), wait for executable to be launched (untuk debugging proses yang diluncurkan), debugger (LLDB atau None), launch arguments, environment variables, dan opsi lanjutan (Address Sanitizer, Thread Sanitizer, Main Thread Checker, Memory Management).

Untuk diagnosis Address Sanitizer (ASan) — mendeteksi keluar dari batas array, use-after-free dan kesalahan memori lain di kode C/C++/ObjC. Thread Sanitizer (TSan) — mendeteksi kondisi balapan (data races) di kode multithread. Undefined Behavior Sanitizer (UBSan) — mengungkap perilaku tidak terdefinisi, misalnya overflow int bertanda. Opsi ini tersedia di Edit Scheme → Run → Diagnostics dan hanya berfungsi untuk build Debug. Mengaktifkan semua sanitizer dapat memperlambat peluncuran 2-3 kali, oleh karena itu disarankan mengaktifkannya secara selektif.

Mengkloning skema untuk lingkungan yang berbeda

Praktik umum — membuat skema terpisah untuk setiap lingkungan: Dev, Staging, Production. Setiap skema menggunakan Build Configuration yang sama (Debug untuk Dev, Release untuk Production), tetapi argumen peluncuran berbeda: -FIRAnalyticsDebugEnabled, -com.apple.CoreData.SQLDebug 1 untuk Dev dan ketiadaannya untuk Production. Argumen peluncuran diteruskan ke UserDefaults (ProcessInfo.processInfo.arguments) dan tersedia untuk dibaca saat aplikasi dimulai. Ini memungkinkan mengganti URL server, tingkat logging dan fitur tanpa mengubah kode.

Skema Shared dan Private: pengelolaan melalui Git

Skema Shared disimpan di <project>.xcworkspace/xcshareddata/xcschemes/ atau <project>.xcodeproj/xcshareddata/xcschemes/ dan masuk ke repositori Git. Semua pengembang tim melihat skema ini di Xcode. Skema Shared adalah satu-satunya cara untuk menyebarkan skema di tim. Jika pengembang membuat skema penting (misalnya “Staging Archive”) tetapi tidak menandainya sebagai Shared, sisa tim tidak akan melihatnya, yang menyebabkan kebingungan: setiap orang akan membuat skemanya sendiri dengan pengaturannya sendiri.

Skema Private disimpan di xcuserdata/<user>/xcschemes/ dan tidak masuk ke Git. Berguna untuk konfigurasi pribadi: misalnya, skema dengan semua sanitizer diaktifkan untuk pengembang tertentu. Skema private tidak boleh berisi pengaturan kritis yang menentukan build proyek — jika pengembang meninggalkan proyek, skema private-nya akan hilang. Rekomendasi: semua skema yang digunakan di CI/CD dan oleh setidaknya dua pengembang harus dijadikan Shared.

Pengelolaan skema dilakukan melalui Manage Schemes (Product → Scheme → Manage Schemes). Di jendela ditampilkan semua skema proyek, statusnya (Shared/Private), dan tombol +/— untuk menambah/menghapus. Centang Shared mengalihkan visibilitas skema untuk tim. Saat konflik Git (perubahan di .xcscheme oleh dua pengembang) Anda perlu menyelesaikan penggabungan dengan hati-hati — file XML dapat berisi pengidentifikasi target yang berbeda. Disarankan untuk menambahkan .xcscheme ke file yang dikunci saat merge (git lfs atau .gitattributes).

Argumen peluncuran dan variabel lingkungan

Arguments di Scheme adalah string yang diteruskan ke aplikasi saat diluncurkan (ProcessInfo.processInfo.arguments) dan variabel lingkungan (ProcessInfo.processInfo.environment). Argumen digunakan untuk flag: -AppleLanguages (ru), -AppleLocale ru_RU untuk simulasi lokalisasi Rusia atau -FIRDebugEnabled untuk mengaktifkan debugging Firebase. Variabel lingkungan diterapkan untuk konfigurasi: API_BASE_URL=http://localhost:3000, LOG_LEVEL=debug.

Untuk mengelola fitur (feature flags) di lingkungan yang berbeda digunakan kombinasi Arguments + Build Configuration. Di skema Dev diatur argumen -FeatureFlagNewOnboarding YES, sedangkan di Production — -FeatureFlagNewOnboarding NO (atau argumen tidak ada). Di kode, pemeriksaan: UserDefaults.standard.bool(forKey: "FeatureFlagNewOnboarding"). Pendekatan ini memungkinkan mengaktifkan fitur secara bertahap di staging tanpa mengubah kode dan tanpa melakukan commit nilai production.

Penting: argumen dan variabel lingkungan Scheme menimpa nilai dari Info.plist. Jika di Info.plist ditentukan API_URL, dan di Scheme — API_URL=http://localhost untuk Run Action, saat diluncurkan dari Xcode akan digunakan nilai dari Scheme. Saat diluncurkan dari perangkat (bukan dari Xcode) — nilai dari Info.plist. Ini nyaman untuk pengembangan lokal, tetapi perlu diingat bahwa variabel Scheme tidak masuk ke build — variabel hanya berfungsi saat diluncurkan melalui Xcode.

import Foundation

struct AppEnvironment {
    var apiBaseURL: String {
        ProcessInfo.processInfo.environment["API_BASE_URL"]
            ?? Bundle.main.object(forInfoDictionaryKey: "API_BASE_URL") as? String
            ?? "https://api.production.com"
    }

    var isDebugMode: Bool {
        ProcessInfo.processInfo.arguments.contains("-DebugModeEnabled")
    }

    var isNewOnboardingEnabled: Bool {
        UserDefaults.standard.bool(forKey: "FeatureFlagNewOnboarding")
    }
}

// Digunakan saat startup
let env = AppEnvironment()
NetworkConfig.shared.configure(baseURL: env.apiBaseURL)

Scheme di CI/CD: otomatisasi melalui xcodebuild

Di CI/CD (GitHub Actions, Jenkins, GitLab CI) Scheme digunakan sebagai argumen utama perintah xcodebuild. Contoh: xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Release -sdk iphoneos archive. Flag -scheme menunjukkan skema mana yang digunakan. xcodebuild membaca semua pengaturan dari file .xcscheme, termasuk build configuration, target dan urutan build. Ini menjamin CI/CD membangun aplikasi dengan parameter yang sama dengan IDE lokal.

Untuk CI/CD, skema Shared sangat penting. Jika skema tidak Shared, xcodebuild tidak akan menemukannya di repositori, dan build akan gagal dengan kesalahan “Scheme not found”. Aturan: sebelum mengonfigurasi CI/CD pastikan semua skema yang digunakan ditandai sebagai Shared. Aturan kedua: di CI/CD jangan gunakan skema default (Xcode otomatis memilih skema pertama) — selalu teruskan nama skema secara eksplisit melalui flag -scheme.

Untuk build paralel beberapa skema (misalnya, aplikasi dan extension watchOS) Anda dapat menjalankan xcodebuild secara berurutan atau paralel. Sistem CI modern memungkinkan memparalelkan build skema yang berbeda melalui matriks: satu job membangun aplikasi iOS, yang kedua — extension watchOS. Ini mengurangi total waktu build dari 15 menjadi 8 menit dengan dua agen paralel. Di akhir, artefak digabungkan menjadi satu .xcarchive menggunakan xcodebuild -exportArchive.

#!/bin/bash — build CI/CD dengan xcodebuild
# 1. Membersihkan dan membangun
xcodebuild clean archive \
  -workspace "MyApp.xcworkspace" \
  -scheme "MyApp Production" \
  -configuration Release \
  -sdk iphoneos \
  -archivePath "build/MyApp.xcarchive" \
  CODE_SIGN_STYLE="Manual" \
  PROVISIONING_PROFILE_SPECIFIER="match AppStore"

# 2. Ekspor ke IPA
xcodebuild -exportArchive \
  -archivePath "build/MyApp.xcarchive" \
  -exportPath "build/ipa" \
  -exportOptionsPlist "ExportOptions.plist"