Tuist 의존성 관리 · Static/Dynamic 링킹 완벽 가이드

1. Tuist 프로젝트 네비게이터 구조

Xcode 네비게이터에서 두 가지 다른 의존성 섹션이 보인다:

왜 나뉘어 있나?

productTypes 설정(staticFramework/framework)은 빌드 산출물 타입만 지정하는 것이고, xcodeproj 변환 여부와는 관계없다.

2. Tuist의 전체 역할

xcframework → xcodeproj 변환은 Tuist가 하는 여러 일 중 하나일 뿐. 프로젝트 생성 자동화가 본질이다.

3. Static vs Dynamic Framework

productTypes 설정의 의미

// Tuist/Package.swift
let packageSettings = PackageSettings(
    productTypes: [
        "Alamofire": .staticFramework,   // Static으로 빌드
        "LineSDK": .framework,           // Dynamic으로 빌드
    ]
)

"링커가 참조를 기록"의 의미

링크 타임:
Alamofire ──복사──→ MyApp 실행파일
                   (코드가 실행파일 안에)

런타임:
MyApp 실행파일 하나만 있으면 됨

링크 타임:
LineSDK ──참조──→ MyApp 실행파일 헤더:
                 "LineSDK.framework 필요"

런타임:
dyld가 Frameworks/LineSDK.framework 로드

실행파일 헤더에 기록된 정보 확인:

$ otool -L MyApp

MyApp:
    @rpath/LineSDK.framework/LineSDK    ← "이 프레임워크 필요해"
    /usr/lib/libSystem.B.dylib          ← "시스템 라이브러리 필요해"

4. Xcode GUI에서 의존성 추가 위치

General 탭

Frameworks, Libraries, and Embedded Content
├── + 버튼으로 추가
└── Embed 옵션 선택
    - Do Not Embed
    - Embed & Sign
    - Embed Without Signing

Build Phases 탭

Link Binary With Libraries    ← 링크 (컴파일 타임)
Embed Frameworks             ← 복사 (Dynamic만 해당)

관계 정리

Link Binary With Libraries에 뭐가 들어가나?

Static과 Dynamic 둘 다 들어간다.

Link Binary With Libraries
├── Alamofire.framework      ← Static
├── RxSwift.framework        ← Static
├── LineSDK.framework        ← Dynamic
└── libz.tbd                 ← System library

Link = "이 라이브러리 사용한다" 선언 (둘 다 필요)
Embed = 앱 번들에 파일 복사 (Dynamic만 필요)

5. pbxproj 충돌 문제

.xcodeproj 구조

MStove.xcodeproj/
├── project.pbxproj       ← 이 파일이 문제
├── xcshareddata/
└── xcuserdata/

pbxproj 내용 (일부)

/* Begin PBXFrameworksBuildPhase section */
    3E9F8A2B1C8B4D5E00123456 /* Frameworks */ = {
        isa = PBXFrameworksBuildPhase;
        files = (
            3E9F8A2C1C8B4D5E00789ABC /* Alamofire.framework */,
            3E9F8A2D1C8B4D5E00DEF012 /* RxSwift.framework */,
        );
    };
/* End PBXFrameworksBuildPhase section */

충돌 시나리오

팀원 A: Kingfisher 추가 → pbxproj에 UUID 추가
팀원 B: Lottie 추가    → pbxproj에 다른 UUID 추가
        ↓
    동시에 PR
        ↓
    pbxproj CONFLICT 💥

Tuist의 해결책

팀원 A: MStoveAppDependencies.swift에 Kingfisher 추가
팀원 B: MStoveAppDependencies.swift에 Lottie 추가
        ↓
    일반 Swift 코드라 머지 쉬움
        ↓
    tuist generate → pbxproj 재생성

pbxproj를 커밋 안 하거나, 생성된 걸로 덮어씀 → 충돌 없음

6. 의존성 선언 통합의 가치

Tuist 없이 (순수 Xcode)

타겟이 10개라면:

MStove          → Xcode GUI에서 Alamofire 추가
MStoveVN        → Xcode GUI에서 Alamofire 추가
QA_MStove       → Xcode GUI에서 Alamofire 추가
QA_MStove_VN    → Xcode GUI에서 Alamofire 추가
DEV_MStove      → Xcode GUI에서 Alamofire 추가
... (10번 반복)

Tuist 사용

// 한 번만 선언
private let mstoveSharedAppDependencies: [TargetDependency] = [
    .external(name: "Alamofire"),
    .external(name: "RxSwift"),
    // ...
]

// 모든 타겟이 공유
public let mstoveAppDependencies = mstoveSharedAppDependencies + [...]
public let mstoveVNAppDependencies = mstoveSharedAppDependencies + [...]

→ tuist generate 하면 모든 타겟에 자동 적용

7. Configuration 중복 문제와 해결

현재 프로젝트에서 같은 Configuration 목록이 여러 파일에 중복되어 있다:

MStoveAppProject.swift

public let mstoveProjectSettings = Settings.settings(configurations: [
    .debug(name: "Debug"),
    .debug(name: "Debug_Dev"),
    .debug(name: "Debug_Qa"),
    // ... 20개
])

Package.swift

baseSettings: Settings.settings(configurations: [
    .debug(name: "Debug"),
    .debug(name: "Debug_Dev"),
    .debug(name: "Debug_Qa"),
    // ... 동일한 20개
])

개선 가능한 구조

// Tuist/ProjectDescriptionHelpers/Configurations.swift
public let allConfigurations: [Configuration] = [
    .debug(name: "Debug"),
    .debug(name: "Debug_Dev"),
    // ... 한 곳에서 정의
]

// Package.swift (#if TUIST 블록 안에서)
import ProjectDescriptionHelpers
let packageSettings = PackageSettings(
    baseSettings: Settings.settings(configurations: allConfigurations)
)

// MStoveAppProject.swift
public let mstoveProjectSettings = Settings.settings(
    configurations: allConfigurations
)

Q&A

관련 문서

• Tuist 학습 Q&A 정리
• Tuist 완벽 가이드
• 모듈화 · 빌드 · 링킹 Q&A