14 · 컴파일러·링커·실행 파일

# 컴파일 중간 산출물을 단계별로 확인
swiftc -emit-silgen main.swift     # raw SIL (SILGen 직후)
swiftc -emit-sil     main.swift    # canonical SIL (mandatory 패스 적용, 최적화는 -O 필요)
swiftc -emit-ir      main.swift    # LLVM IR
swiftc -emit-assembly main.swift   # 어셈블리
swiftc -emit-object  main.swift    # main.o (Mach-O object)

# 링크 결과 · 로드 커맨드 확인
otool -L a.out     # 링크된 dylib 목록
otool -l a.out     # 로드 커맨드(LC_UUID, LC_LOAD_DYLIB ...)

# 로드(dyld) 동작 관찰
DYLD_PRINT_LIBRARIES=1  ./a.out    # 로드되는 이미지 출력
DYLD_PRINT_LIBRARIES=1 ./a.out     # 로드되는 이미지 목록
#   (DYLD_PRINT_STATISTICS는 dyld4(iOS 15+)부터 제거되어 아무것도 출력하지 않는다)

# 빌드 시간을 감으로 고치면 엉뚱한 곳을 손대게 된다. 단계별로 나눠 잰다.

# ✅ ① 전체 빌드 타이밍 요약 — 어느 단계가 큰지 한눈에 보인다
xcodebuild -project App.xcodeproj -scheme App \
  -configuration Debug clean build \
  -showBuildTimingSummary
#   CompileSwiftSources   142.3 s
#   Ld                     18.7 s        ← 링크가 크면 동적 프레임워크·심볼 수를 본다
#   CompileAssetCatalog     4.1 s

# ✅ ② 컴파일이 크다면 — 느린 함수·표현식을 찾는다
#    Build Settings → Other Swift Flags 에 추가
#      -Xfrontend -warn-long-function-bodies=200
#      -Xfrontend -warn-long-expression-type-checking=200
#    → 200ms를 넘는 지점이 경고로 뜬다 (대개 타입 추론 폭발)

# 흔한 원인: 복잡한 리터럴 표현식
#   ❌ let x = [1, 2.0, 3].map { $0 * 2 } .reduce(0, +) / Double(n) + offset
#   ✅ 중간 변수로 쪼개고 타입을 명시하면 몇 초가 몇 밀리초가 된다
#      let values: [Double] = [1, 2, 3]

# ✅ ③ 파일별 컴파일 시간 순위
xcodebuild ... OTHER_SWIFT_FLAGS="-Xfrontend -debug-time-function-bodies" 2>&1 \
  | grep -E '^[0-9.]+ms' | sort -rn | head -20
#   (-driver-time-compilation은 현행 swift-driver에서 아무 출력도 하지 않는다.
#    파일 단위 순위는 Xcode의 Build Timeline / -showBuildTimingSummary로 본다)

# ✅ ④ 링크가 크다면
#    · 동적 프레임워크 개수를 줄인다(정적으로 합친다)
#    · 사용하지 않는 의존성을 제거한다
#    · Xcode 15+의 새 링커(ld-prime)를 쓰는지 확인한다
otool -L App.app/App | tail -n +2 | wc -l        # 동적 의존 개수

# ⚠️ Debug와 Release는 병목이 다르다. Debug는 증분 컴파일,
#    Release는 WMO·최적화가 시간을 먹는다. 목적에 맞는 구성으로 잰다.

# pre-main 구간(dyld가 이미지를 올리고 fixup을 적용하는 시간)은 main 이후 코드를 아무리
# 최적화해도 줄지 않는다. 줄이려면 dylib 수·심볼 수·ObjC 클래스 수·전역 초기화 같은
# '구조'를 건드려야 한다.
# 무엇이 큰지 먼저 확인해야 처방이 정해진다.

# ✅ 설정
#   Xcode → Product → Profile → App Launch 템플릿
#   (DYLD_PRINT_STATISTICS / _DETAILS는 iOS 15의 새 dyld부터 제거되어 아무것도 안 찍힌다.
#    옛 블로그 글을 따라 스킴 환경 변수에 넣지 말 것 — 아래 출력 형식은 iOS 14 이하의 것이다.)

# 옛 출력 예시와 읽는 법 — 지금은 App Launch 템플릿의 구간 이름으로 같은 것을 본다
#   Total pre-main time: 512.30 milliseconds (100.0%)
#            dylib loading time: 240.11 ms  (46.8%)   ← 동적 프레임워크가 많다
#           rebase/binding time:  96.40 ms  (18.8%)   ← 포인터·심볼이 많다
#               ObjC setup time:  41.02 ms  ( 8.0%)   ← ObjC 클래스·카테고리가 많다
#              initializer time: 134.77 ms  (26.3%)   ← +load, __attribute__((constructor))

# 처방
#   dylib loading 크다   → 동적 프레임워크를 정적으로 합친다 (가장 효과 큼)
#   rebase/binding 크다  → 심볼 수를 줄인다. 불필요한 public 노출을 internal로.
#   ObjC setup 크다      → ObjC 클래스·카테고리를 줄인다
#   initializer 크다     → +load를 initialize로, 전역 초기화를 지연시킨다

# ✅ post-main(첫 화면까지)은 Instruments의 App Launch 템플릿으로 본다
#    또는 코드로 직접 계측
#      os_signpost로 didFinishLaunching ~ 첫 프레임 구간을 감싼다

# ✅ 실사용자 분포는 MetricKit으로 수집한다
#    MXAppLaunchMetric.histogrammedTimeToFirstDraw → p50/p90을 추적

# ⚠️ 시뮬레이터 수치는 의미가 없다. 반드시 실기기 + Release로 잰다.
#    콜드 스타트를 재려면 앱을 완전히 종료하고 기기를 재부팅한 뒤 첫 실행을 본다.

import Foundation

// 두 오류는 원인 계층이 완전히 다르다. 메시지 형태로 즉시 구분할 수 있다.

// ── 컴파일 에러: 타입·문법 문제. 파일 하나 안에서 판정된다.
func compileErrors() {
    // error: cannot convert value of type 'String' to expected argument type 'Int'
    // error: value of type 'Foo' has no member 'bar'
    // error: missing argument for parameter 'x' in call
    //
    // → 소스를 고친다. 파일:줄 위치가 정확히 나온다.
}

/*  ── 링크 에러: 심볼을 못 찾는다. 모든 오브젝트를 합칠 때 판정된다.

    Undefined symbols for architecture arm64:
      "_OBJC_CLASS_$_FIRApp", referenced from:
          objc-class-ref in AppDelegate.o
    ld: symbol(s) not found for architecture arm64

    → 소스가 아니라 '빌드 구성'을 본다:
       ① 그 프레임워크가 Link Binary With Libraries에 있는가?
       ② 아키텍처가 맞는가? (lipo -info)
       ③ C 상호운용이면 extern "C" / 모듈맵이 맞는가?

    ── 런타임 링크 에러: 로드 시점에 못 찾는다.

    dyld: Symbol not found: _someNewAPI
      Referenced from: /var/.../MyApp
      Expected in: /System/Library/Frameworks/Foo.framework/Foo

    → SDK/OS 버전 불일치나 @available 가드 누락이다.                        */

// ✅ 런타임 링크 에러 방지 — 가용성을 명시한다
func useNewAPI() {
    if #available(iOS 17.0, *) {
        newAPI()
    } else {
        legacyFallback()
    }
}

// ✅ 약한 링크가 필요하면 (선택적 프레임워크)
//    Build Phases → Link Binary → Status: Optional
//    그리고 사용 전에 nil 체크

@available(iOS 17.0, *) func newAPI() {}
func legacyFallback() {}

file libFoo.a         # current ar archive (정적 아카이브)
file libFoo.dylib     # Mach-O 64-bit dynamically linked shared library

otool -hv MyApp.framework/MyApp   # filetype 이 DYLIB 인지 확인
# → EXECUTE/DYLIB 등 Mach-O 타입으로 정적/동적 판별

// Package.swift — SPM에서 링크 타입을 명시적으로 고른다

import PackageDescription

let package = Package(
    name: "Core",
    platforms: [.iOS(.v16)],
    products: [
        // ✅ 기본은 정적 — 런치 시 dylib 로딩·바인딩 비용이 없다
        .library(name: "Core", type: .static, targets: ["Core"]),
        .library(name: "Networking", type: .static, targets: ["Networking"]),

        // ✅ 동적은 '명확한 이유'가 있을 때만
        //    · 앱 본체와 확장(위젯·공유시트)이 코드를 공유해야 한다
        //    · 재컴파일 없이 교체해야 한다
        //    · 순환 의존을 끊어야 한다
        .library(name: "SharedUI", type: .dynamic, targets: ["SharedUI"]),
    ],
    targets: [
        .target(name: "Core"),
        .target(name: "Networking", dependencies: ["Core"]),
        .target(name: "SharedUI", dependencies: ["Core"]),
    ]
)

/*  CocoaPods에서도 명시한다
      use_frameworks! :linkage => :static

    Xcode 프로젝트 타깃이면
      Build Settings → Mach-O Type → Static Library

    ⚠️ 정적 링크의 대가
       · 앱 바이너리가 커진다 (__TEXT 페이지 인 비용 증가)
       · 여러 타깃이 같은 라이브러리를 쓰면 각각에 복제된다
       · 빌드 시간이 늘 수 있다(링크 단계)

    ✅ 판단: 앱 본체 하나뿐이면 정적이 거의 항상 낫다.
       확장이 여럿이고 공유 코드가 크면 그때 동적을 검토한다.                */

# 라이브러리가 실제로 어떻게 링크됐는지는 도구로 확인해야 한다.
# "프레임워크니까 동적"이라는 가정은 자주 틀린다.

# ✅ ① 앱이 로드하는 동적 라이브러리 목록
otool -L MyApp.app/MyApp
#   /usr/lib/libSystem.B.dylib
#   @rpath/SharedUI.framework/SharedUI      ← 우리가 만든 동적 프레임워크
#   /System/Library/Frameworks/UIKit.framework/UIKit

# ✅ ② 특정 프레임워크의 Mach-O 타입 확인
file MyFramework.framework/MyFramework
#   ... dynamically linked shared library arm64   → 동적
#   ... current ar archive                        → 정적(.a를 프레임워크로 포장)

# ✅ ③ 아키텍처 확인 (Undefined symbol의 흔한 원인)
lipo -info libCore.a
#   Architectures in the fat file: arm64 x86_64
#   → 시뮬레이터용 arm64가 없으면 M1 맥 시뮬레이터에서 링크 실패

# ✅ ④ 심볼 중복 확인 — 같은 정적 라이브러리를 두 동적 프레임워크가 품으면
nm -gU FrameworkA.framework/FrameworkA | grep 'T _' | sort > /tmp/a.txt
nm -gU FrameworkB.framework/FrameworkB | grep 'T _' | sort > /tmp/b.txt
comm -12 /tmp/a.txt /tmp/b.txt | head
#   겹치는 심볼이 나오면 중복 로드 경고("Class X is implemented in both...")가 뜬다
#   → 공용 의존은 한 곳에서만 링크되게 경계를 정리한다

# ✅ ⑤ 바이너리 크기 기여도
xcrun size -m MyApp.app/MyApp | head -20

# ⚠️ SPM의 .library type을 생략하면 Xcode가 자동으로 정한다 —
#    의도한 결과인지 위 명령으로 반드시 확인한다

/*  문제 상황
      AppTarget
        ├── FeatureA.framework (동적)  ──┐
        └── FeatureB.framework (동적)  ──┴── 둘 다 Core.a(정적)를 품는다

    결과
      · Core의 심볼이 바이너리에 두 벌 존재한다
      · ObjC 클래스면 런타임 경고: "Class Foo is implemented in both ...
        One of the two will be used. Which one is undefined."
      · 전역 상태(싱글턴·static var)가 두 벌이 되어 조용히 어긋난다
      · 앱 크기도 그만큼 늘어난다                                           */

import PackageDescription

// ✅ 해법 ① Core도 동적으로 만들어 한 벌만 존재하게 한다
let packageA = Package(
    name: "App",
    products: [
        .library(name: "Core", type: .dynamic, targets: ["Core"]),      // 한 벌
        .library(name: "FeatureA", type: .dynamic, targets: ["FeatureA"]),
        .library(name: "FeatureB", type: .dynamic, targets: ["FeatureB"]),
    ],
    targets: [
        .target(name: "Core"),
        .target(name: "FeatureA", dependencies: ["Core"]),
        .target(name: "FeatureB", dependencies: ["Core"]),
    ]
)

// ✅ 해법 ② 전부 정적으로 하고 앱 타깃에서 한 번만 링크한다
let packageB = Package(
    name: "App",
    products: [
        .library(name: "Core", type: .static, targets: ["Core"]),
        .library(name: "FeatureA", type: .static, targets: ["FeatureA"]),
        .library(name: "FeatureB", type: .static, targets: ["FeatureB"]),
    ],
    targets: [
        .target(name: "Core"),
        .target(name: "FeatureA", dependencies: ["Core"]),
        .target(name: "FeatureB", dependencies: ["Core"]),
    ]
)
// 세 라이브러리가 모두 정적이라 Core의 오브젝트가 최종 실행 파일에 한 번만 편입된다 — 애초에 중복이 생기지 않는다 (정적 링크의 이점)

/*  ✅ 검증
      · 런타임 로그에서 "implemented in both" 경고가 없는지
      · 싱글턴 주소가 같은지 확인
          print(Unmanaged.passUnretained(Core.shared).toOpaque())
        두 프레임워크에서 찍어 보고 값이 다르면 두 벌인 것이다              */

# 여러 플랫폼(기기·시뮬레이터·Catalyst)을 한 배포물에 담으려면 XCFramework다.
# 예전 fat 바이너리는 같은 arm64인데 기기용과 시뮬레이터용을 구분할 수 없었다.

# ✅ ① 각 플랫폼별로 아카이브
xcodebuild archive \
  -scheme Core \
  -destination "generic/platform=iOS" \
  -archivePath build/ios.xcarchive \
  SKIP_INSTALL=NO \
  BUILD_LIBRARY_FOR_DISTRIBUTION=YES     # ← 모듈 안정성. 반드시 켠다.

xcodebuild archive \
  -scheme Core \
  -destination "generic/platform=iOS Simulator" \
  -archivePath build/sim.xcarchive \
  SKIP_INSTALL=NO \
  BUILD_LIBRARY_FOR_DISTRIBUTION=YES

# ✅ ② 하나로 합친다
xcodebuild -create-xcframework \
  -framework build/ios.xcarchive/Products/Library/Frameworks/Core.framework \
  -debug-symbols "$PWD/build/ios.xcarchive/dSYMs/Core.framework.dSYM" \
  -framework build/sim.xcarchive/Products/Library/Frameworks/Core.framework \
  -debug-symbols "$PWD/build/sim.xcarchive/dSYMs/Core.framework.dSYM" \
  -output Core.xcframework

# ⚠️ BUILD_LIBRARY_FOR_DISTRIBUTION=YES를 빼면
#    Swift 버전이 다른 프로젝트에서 "module compiled with Swift X.Y cannot be
#    imported by Swift X.Z" 오류가 난다.

# ⚠️ dSYM을 함께 넣지 않으면 소비자 쪽에서 크래시 심볼리케이션이 안 된다.

# ✅ ③ SPM으로 배포하려면 binaryTarget
#    .binaryTarget(name: "Core",
#                  url: "https://.../Core.xcframework.zip",
#                  checksum: "abc123...")
swift package compute-checksum Core.xcframework.zip

# ✅ 순수 소스 배포라면 XCFramework가 필요 없다 — SPM 소스 패키지가 훨씬 단순하다

// .a(정적 라이브러리)에는 코드만 들어간다. 에셋·로컬라이즈·nib는 따라가지 않는다.

// ✅ SPM에서 리소스를 포함하는 방법
import PackageDescription

let package = Package(
    name: "DesignKit",
    defaultLocalization: "ko",
    products: [.library(name: "DesignKit", targets: ["DesignKit"])],
    targets: [
        .target(
            name: "DesignKit",
            resources: [
                .process("Resources/Assets.xcassets"),   // 컴파일·최적화된다
                .process("Resources/ko.lproj"),
                .copy("Resources/config.json")           // 그대로 복사된다
            ]
        )
    ]
)

// ✅ 코드에서 접근할 때는 Bundle.module을 쓴다 (SPM이 자동 생성)
import UIKit

enum DesignKitAssets {
    static var logo: UIImage? {
        UIImage(named: "logo", in: .module, compatibleWith: nil)
    }

    static func localized(_ key: String) -> String {
        NSLocalizedString(key, bundle: .module, comment: "")
    }

    static func config() throws -> Data {
        guard let url = Bundle.module.url(forResource: "config", withExtension: "json")
        else { throw ResourceError.missing }
        return try Data(contentsOf: url)
    }
}

// ⚠️ Bundle.module은 '리소스가 선언된 SPM 타깃 안'에서만 존재한다.
//    앱 타깃에서 쓰면 컴파일 에러다 — 거기서는 Bundle.main을 쓴다.

// ⚠️ .framework로 배포한다면 Bundle(for:)로 자기 번들을 찾는다
final class BundleToken {}
extension Bundle {
    static var designKit: Bundle { Bundle(for: BundleToken.self) }
}

enum ResourceError: Error { case missing }

# .framework는 '포장 방식'이고, 정적/동적은 '링크 방식'이다. 서로 직교한다.
# 네 조합이 모두 존재한다:
#   정적 라이브러리(.a) / 동적 라이브러리(.dylib)
#   정적 프레임워크     / 동적 프레임워크

# ✅ 실제 타입을 확인한다
file Core.framework/Core
#   Mach-O 64-bit dynamically linked shared library arm64  → 동적 프레임워크
#   current ar archive                                     → 정적 프레임워크

# ✅ Mach-O 헤더로도 확인 가능
otool -hv Core.framework/Core | head -5
#   magic      cputype  filetype
#   MH_MAGIC_64  ARM64   DYLIB      → 동적
#   MH_MAGIC_64  ARM64   OBJECT     → 정적

# ✅ 앱이 실제로 동적 로드하는지
otool -L MyApp.app/MyApp | grep Core
#   출력이 있으면 동적, 없으면 정적으로 합쳐진 것

# ✅ Xcode에서 설정하는 곳
#   프레임워크 타깃 → Build Settings → Mach-O Type
#     Dynamic Library / Static Library
#   앱 타깃 → General → Frameworks, Libraries, and Embedded Content
#     Embed & Sign      → 동적 (번들에 포함되어 런타임에 로드)
#     Do Not Embed      → 정적이거나 시스템 제공

# ⚠️ 흔한 사고: 정적 프레임워크를 Embed & Sign으로 설정
#    → 바이너리에 이미 합쳐졌는데 번들에도 복사되어 앱 크기가 두 배가 된다
#    → 심사에서 "unused framework" 경고가 뜨기도 한다

# ✅ 앱 번들에 실제로 무엇이 들어갔는지 확인
ls -la MyApp.app/Frameworks/

nm -gU MyApp     # 이 바이너리가 내보내는(defined, global) 심볼
nm -u  MyApp     # 아직 해소 안 된(undefined) 심볼

# Swift 맹글링된 심볼 읽기
$ swift demangle '$s5MyApp4UserV4nameSSvg'
$s5MyApp4UserV4nameSSvg ---> MyApp.User.name.getter : Swift.String

# 링크 타임 (빌드 실패)
Undefined symbols for architecture arm64:
  "_OBJC_CLASS_$_SomeSDKClass", referenced from:
      objc-class-ref in ViewController.o
ld: symbol(s) not found for architecture arm64

# 런타임 (앱 크래시) — 동적 라이브러리 버전 불일치
dyld[4211]: Symbol not found: _$s7SomeSDK7ServiceC5startyyF
  Referenced from: /private/var/.../MyApp.app/MyApp
  Expected in:     /private/var/.../Frameworks/SomeSDK.framework/SomeSDK

# 소스를 뒤지기 전에 이 순서로 확인한다. 대부분 여기서 끝난다.

# ① 그 프레임워크가 링크 단계에 있는가?
#    Xcode → 앱 타깃 → Build Phases → Link Binary With Libraries
#    또는 Build Settings → Other Linker Flags 의 -framework / -l 항목

# ② 아키텍처가 맞는가? (M1 맥에서 특히 흔하다)
lipo -info libCore.a
#   Architectures in the fat file: arm64 x86_64
#   → 기기용 arm64와 시뮬레이터용 arm64는 다르다.
#     둘 다 필요하면 XCFramework를 써야 한다.

# 현재 빌드 대상 확인
xcodebuild -showBuildSettings -scheme App | grep -E 'ARCHS|VALID_ARCHS|SDKROOT'

# ③ C/C++ 상호운용이면 이름 맹글링이 맞는가?
#    C++ 헤더를 C에서 쓰려면
#      #ifdef __cplusplus
#      extern "C" {
#      #endif
#      void my_function(void);
#      #ifdef __cplusplus
#      }
#      #endif
#
#    Swift에서 C를 쓰려면 모듈맵이 필요하다
#      module CLib {
#          header "clib.h"
#          export *
#      }

# ④ 심볼이 실제로 라이브러리에 있는지 확인
nm -gU libCore.a | grep fetchData
#   출력이 없으면 그 심볼은 정말 없는 것이다 (오타·조건부 컴파일·접근 수준)

# ⑤ 어떤 오브젝트가 그 심볼을 요구하는지
#    오류 메시지의 "referenced from:" 줄이 알려 준다
#      referenced from: objc-class-ref in AppDelegate.o

# 심볼 이름의 접두사만 봐도 어느 계층 문제인지 좁혀진다.

# ── ObjC 클래스 참조
#   "_OBJC_CLASS_$_FIRApp", referenced from: objc-class-ref in AppDelegate.o
#   → 프레임워크 링크 누락. FirebaseCore를 Link Binary에 추가한다.

# ── ObjC 메타클래스
#   "_OBJC_METACLASS_$_MyClass"
#   → 같은 원인. 클래스가 정의된 오브젝트/라이브러리가 안 들어갔다.

# ── C 함수
#   "_sqlite3_open"
#   → 시스템 라이브러리 누락. libsqlite3.tbd를 추가한다.

# ── Swift 심볼 (맹글링됨)
#   "$s4Core6ClientC5fetchyyKF"
xcrun swift demangle '$s4Core6ClientC5fetchyyKF'
#   → Core.Client.fetch() throws -> ()
#   어느 모듈의 어떤 타입·함수인지 즉시 알 수 있다

# 여러 개를 한 번에 풀기 — 링커 출력을 그대로 넘긴다
xcodebuild build 2>&1 | xcrun swift demangle

# ── Swift 심볼 접두사 읽는 법
#   $s      Swift 심볼 시작
#   4Core   모듈 이름 (길이 + 이름)
#   6Client 타입 이름
#   C       class (V=struct, O=enum, P=protocol)
#   F       function

# ✅ 반대로 내 코드의 심볼 이름을 알고 싶으면
nm -gU MyApp.app/MyApp | xcrun swift demangle | grep 'Core.Client'

# ⚠️ 접근 수준도 원인이 된다 — internal 심볼은 모듈 밖에서 안 보인다.
#    라이브러리에서 노출하려면 public 또는 @_spi가 필요하다.

import Foundation

/*  빌드는 통과했는데 실행 시 죽는다:

      dyld[1234]: Symbol not found: _$s10Foundation8SomeNewAPIVMa
        Referenced from: /var/containers/.../MyApp
        Expected in:     /System/Library/Frameworks/Foundation.framework/Foundation

    원인: 최신 SDK로 빌드했는데 구버전 OS에서 실행됐다.
          그 심볼은 새 OS에만 존재한다.                                     */

// ✅ ① @available로 가드한다 — 컴파일러가 강제해 준다
func useModernAPI() {
    if #available(iOS 17.0, *) {
        modernFeature()
    } else {
        legacyFallback()
    }
}

@available(iOS 17.0, *)
func modernFeature() {}
func legacyFallback() {}

// ✅ ② 타입 전체가 새 OS 전용이면 타입에 붙인다
@available(iOS 17.0, *)
struct NewWidget {
    func render() {}
}

// ✅ ③ 프로퍼티·저장 위치에도 가드가 필요하다
final class Manager {
    // ❌ 저장 프로퍼티는 @available로 감쌀 수 없다
    // @available(iOS 17.0, *) var widget: NewWidget?

    // ✅ 계산 프로퍼티나 Any로 우회하거나, 타입 자체를 분리한다
    private var _widget: Any?

    @available(iOS 17.0, *)
    var widget: NewWidget? {
        get { _widget as? NewWidget }
        set { _widget = newValue }
    }
}

// ✅ ④ 최소 배포 타깃을 확인한다
//    Build Settings → iOS Deployment Target
//    이 값보다 새로운 API를 가드 없이 쓰면 컴파일 경고가 뜬다

// ✅ ⑤ 선택적으로 링크되는 프레임워크는 약한 링크로
//    Build Phases → Link Binary → Status: Optional
//    사용 전에 존재 확인:
func useOptionalFramework() {
    if NSClassFromString("SomeOptionalClass") != nil {
        // 안전하게 사용
    }
}

// ⚠️ 실기기 테스트를 최소 배포 타깃 OS에서 반드시 한 번은 해야 잡힌다.
//    최신 OS에서만 테스트하면 이 오류는 출시 후에 발견된다.

# 바이너리와 dSYM 의 UUID 가 같아야 심볼리케이션 가능
dwarfdump --uuid MyApp.app/MyApp
  UUID: A1B2C3D4-... (arm64)
dwarfdump --uuid MyApp.app.dSYM/Contents/Resources/DWARF/MyApp
  UUID: A1B2C3D4-... (arm64)     # ← 같아야 함

# 주소 → 심볼 (-l 은 크래시 리포트의 이미지 로드 주소)
atos -o MyApp.app.dSYM/Contents/Resources/DWARF/MyApp \
     -arch arm64 -l 0x104988000 0x1049c8f34
  User.updateProfile() (in MyApp) (ProfileViewModel.swift:42)

# dSYM이 없으면 사후 크래시 로그는 오프셋 숫자일 뿐이다.

# ✅ ① Build Settings 확인
#    Debug Information Format
#      Debug   : DWARF                    (빠른 빌드)
#      Release : DWARF with dSYM File     ← 반드시 이것
#
#    빌드 설정 키: DEBUG_INFORMATION_FORMAT = dwarf-with-dsym

# CI에서 명시적으로 강제
xcodebuild archive \
  -scheme MyApp \
  -configuration Release \
  -archivePath build/MyApp.xcarchive \
  DEBUG_INFORMATION_FORMAT=dwarf-with-dsym

# ✅ ② 생성됐는지 확인
ls build/MyApp.xcarchive/dSYMs/
#   MyApp.app.dSYM
#   Core.framework.dSYM          ← 의존 프레임워크 것도 있어야 한다

# ⚠️ SPM/CocoaPods 의존 프레임워크의 dSYM이 빠지는 일이 잦다.
#    그러면 서드파티 프레임 안쪽이 심볼리케이션되지 않는다.

# ✅ ③ 모든 아카이브의 dSYM을 버전별로 보관한다
VERSION=$(defaults read "$PWD/build/MyApp.xcarchive/Info.plist" \
          ApplicationProperties | grep CFBundleShortVersionString)
mkdir -p ~/dSYMs/"$VERSION"
cp -R build/MyApp.xcarchive/dSYMs/* ~/dSYMs/"$VERSION"/

# ⚠️ 재빌드하면 UUID가 바뀐다. 같은 소스여도 예전 dSYM으로는 못 푼다.
#    → 릴리스한 바로 그 아카이브의 dSYM을 보관해야 한다.

# ✅ ④ Bitcode를 쓰는 경우(레거시) App Store Connect에서 재생성된 dSYM을 받아야 한다
#    Xcode → Organizer → Archives → Download Debug Symbols

# 사람이 손으로 올리면 반드시 빠뜨린다. 파이프라인에 넣는다.

# ✅ Firebase Crashlytics
find "$ARCHIVE_PATH/dSYMs" -name "*.dSYM" -print0 \
  | xargs -0 "${PODS_ROOT}/FirebaseCrashlytics/upload-symbols" \
      -gsp "$PROJECT_DIR/GoogleService-Info.plist" -p ios

# ✅ Sentry
sentry-cli debug-files upload \
  --org my-org --project my-app \
  "$ARCHIVE_PATH/dSYMs"

# ✅ Bugsnag
find "$ARCHIVE_PATH/dSYMs" -name "*.dSYM" \
  -exec bugsnag-dsym-upload --api-key "$BUGSNAG_KEY" {} \;

# ✅ 업로드 결과를 검증한다 — 조용히 실패하는 경우가 있다
sentry-cli debug-files check "$ARCHIVE_PATH/dSYMs/MyApp.app.dSYM"

# ✅ 누락을 CI에서 잡는다
EXPECTED=$(otool -L MyApp.app/MyApp | grep '@rpath' | wc -l)
FOUND=$(ls "$ARCHIVE_PATH/dSYMs" | wc -l)
if [ "$FOUND" -lt "$EXPECTED" ]; then
  echo "❌ dSYM 누락: 예상 $EXPECTED개, 발견 $FOUND개"
  exit 1
fi

# ⚠️ Run Script Phase로 넣으면 로컬 빌드마다 돌아 느려진다.
#    Archive 액션이나 CI 단계에서만 실행되게 조건을 건다:
#      if [ "$CONFIGURATION" = "Release" ]; then ... fi

# ⚠️ 업로드 도구가 실패해도 빌드가 성공으로 끝나면 아무도 모른다.
#    반드시 exit code를 확인하고 실패 시 빌드를 중단시킨다.

# 심볼리케이션이 안 되면 열에 아홉은 dSYM 매칭 문제다. 코드 문제가 아니다.

# ✅ ① 바이너리의 UUID
dwarfdump --uuid MyApp.app/MyApp
#   UUID: 8A3F1C2D-4E5B-6789-ABCD-EF0123456789 (arm64) MyApp

# ✅ ② dSYM의 UUID
dwarfdump --uuid MyApp.app.dSYM
#   UUID: 8A3F1C2D-4E5B-6789-ABCD-EF0123456789 (arm64) MyApp
#   → 두 값이 '정확히' 같아야 한다

# ✅ ③ 크래시 리포트의 UUID
#    리포트 하단 "Binary Images" 섹션을 본다
#      0x104b78000 - 0x104c9ffff MyApp arm64  <8a3f1c2d4e5b6789abcdef0123456789>
#    이 값과 dSYM UUID를 대조한다

# ✅ ④ 보관 중인 dSYM에서 맞는 것을 찾는다
mdfind "com_apple_xcode_dsym_uuids == 8A3F1C2D-4E5B-6789-ABCD-EF0123456789"

# ✅ ⑤ 수동 심볼리케이션 (도구가 안 될 때)
#    로드 주소(0x104b78000)와 크래시 주소(0x104b9c1f4)를 넣는다
atos -o MyApp.app.dSYM/Contents/Resources/DWARF/MyApp \
     -arch arm64 -l 0x104b78000 0x104b9c1f4
#   → OrderViewModel.submit() (in MyApp) (OrderViewModel.swift:142)

# ✅ ⑥ 전체 리포트를 한 번에
export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
"$DEVELOPER_DIR/SharedFrameworks/DVTFoundation.framework/Versions/A/Resources/symbolicatecrash" crash.ips MyApp.app.dSYM > symbolicated.txt

# ⚠️ UUID가 다르면 그 dSYM으로는 절대 안 된다. 같은 커밋에서 다시 빌드해도
#    빌드 번호·타임스탬프가 달라지면 UUID가 바뀐다.
#    → 릴리스 산출물을 그대로 보관하는 것이 유일한 해법이다.