ABCApp의 Package, Dependency, Target, Scheme, Configuration 흐름 정리

처음 보는 사람용 아주 쉬운 설명

이 프로젝트를 레고 조립이라고 생각하면 쉽다. `package`는 부품 상자 목록이고, `dependency`는 어떤 부품을 실제로 쓰겠다는 선언이고, `target`은 실제 완성품 하나고, `scheme`은 그 완성품을 어떤 모드로 실행할지 정하는 버튼이다.

• `package`: 프로젝트가 알고 있는 부품 목록
• `dependency`: 그중 실제로 연결해서 쓰는 부품
• `target`: 앱, 테스트, 위젯 같은 실제 빌드 단위
• `scheme`: 어떤 타깃을 어떤 설정으로 빌드/실행/테스트할지 정한 실행 세트
• `configuration`: `Debug_Qa`, `Release_Qa2` 같은 환경 이름

큰 흐름도

flowchart TD
    A["Package.swift (외부 SPM과 product 타입 정책을 모아 두는 파일)"]
    B["ABCAppPackages.swift (프로젝트가 인식할 로컬 패키지 목록 파일)"]
    C["ABCAppDependencies.swift (앱 타깃 의존성을 적는 파일)"]
    D["ABCAppProject.swift (앱 타깃 생성 규칙을 모아 둔 helper 파일)"]
    E["Project.swift (packages, targets, schemes를 최종 연결하는 파일)"]
    F["생성된 .xcodeproj (Tuist가 만들어 낸 Xcode 프로젝트 결과물)"]
    G["Target (앱, 테스트, 위젯, 확장 기능처럼 실제로 빌드되는 단위)"]
    H["Scheme (어떤 타깃을 어떤 설정으로 실행할지 정하는 실행 묶음)"]
    I["Build Configuration (Debug_Qa, Release_QA 같은 빌드 환경 이름)"]

    A --> C
    B --> E
    C --> D
    D --> E
    E --> F
    F --> G
    F --> H
    H --> I
    G --> I
        

Then 1. `packages`와 `dependencies`의 관계

let project = Project(
    name: "ABC",
    packages: abcAppPackages,
    targets: abcAppTargets(variant: .global)
)

여기서 `packages: abcAppPackages`는 프로젝트가 알고 있는 로컬 패키지 목록이다. 반면 각 `target` 안의 `dependencies`는 그 타깃이 실제로 링크할 대상이다.

Then 2. 이 프로젝트에서 앱 타깃 의존성은 실제로 무엇을 의미하나

dependency definition 을 보면 앱 타깃이 붙이는 의존성이 한곳에 모여 있다.

public let abcAppDependencies: [ProjectDescription.TargetDependency] = abcSharedAppDependencies + [
    .target(name: "ABCWidgetExtension"),
    .target(name: "ABCShareExtension"),
    .target(name: "ABCNotificationServiceExtension")
]

• `.Feature.StreamingPlay`, `.Feature.ABCV3Home`는 로컬 패키지 product를 링크한다.
• `.external(name: "GoogleSignIn")`, `.external(name: "LineSDK")`는 외부 패키지 product를 링크한다.
• `.target(name: "ABCWidgetExtension")`는 같은 프로젝트 안 다른 타깃을 같이 연결한다.

Then 3. `Scheme.scheme(...)` 파라미터 설명

Scheme.scheme(
    name: "StreamingPlayQAApp",
    buildAction: .buildAction(targets: ["StreamingPlayQAApp"]),
    testAction: TestAction.testPlans(["ABCTests.xctestplan"], configuration: "Debug_Qa"),
    runAction: .runAction(configuration: "Debug_Qa"),
    archiveAction: .archiveAction(configuration: "Release_QA")
)

위 예시는 “`StreamingPlayQAApp` 타깃을 QA 디버그 설정으로 실행하고, 아카이브는 QA 릴리즈 설정으로 하라”는 뜻이다.

Then 4. 왜 Xcode에서 스킴이 안 보일 수 있나

선언이 안 된 것은 아니다. 실제 생성된 스킴 파일이 이미 존재한다.

• QRLoginTestApp.xcscheme
• sample app scheme file
• V3LoginApp.xcscheme
• LocalNotificationTestApp.xcscheme

보통 안 보이는 원인은 아래 쪽이다.

1. 예전에 생성된 다른 `.xcodeproj` 또는 다른 워크스페이스를 열고 있는 경우
2. `Project.swift` 수정 후 `tuist generate`를 다시 안 한 경우
3. Xcode가 이전 scheme cache를 보고 있는 경우

Then 5. `Debug_Qa`, `Debug_Qa2`는 무엇인가

이건 단순 문자열이 아니라 커스텀 build configuration 이름이다. 기본 Xcode는 보통 `Debug`, `Release`만 두지만, 이 프로젝트는 환경이 많아서 이를 더 세분화했다.

Then 6. 한 타깃과 여러 스킴, 한 스킴과 여러 타깃

다만 역할은 다르다. `target`은 결과물 단위이고, `scheme`은 그 결과물을 빌드/실행/테스트하는 시나리오 단위다.

Then 7. 프로젝트 타깃과 스킴의 buildAction 타깃 관계

스킴의 `buildAction` 안에 적힌 타깃은 새로 만드는 게 아니라, 프로젝트 안에 이미 정의돼 있는 target 이름을 참조하는 것이다.

// Project.swift
targets: abcAppTargets(variant: .global) + [
    qrLoginTestApp,
    secondOTPTestApp,
    streamingPlayTestApp,
    v3LoginApp,
    noticeTestApp,
    localNotificationTestApp
]

// same file
Scheme.scheme(
    name: "QRLoginTestApp",
    buildAction: .buildAction(targets: ["QRLoginTestApp"])
)

위 예시에서는 `qrLoginTestApp` helper가 실제 target `QRLoginTestApp`을 만들고, 스킴은 그 이름을 build 대상으로 다시 참조한다.

Then 8. 지금 선언 기준으로 정말 전부 포함되나

확인 결과, 대부분은 포함된다. 실제로 아래 buildAction 타깃은 프로젝트 target과 대응하고 생성된 `.xcscheme` 파일도 존재한다.

• `QRLoginTestApp`
• `SecondOTPTestQAApp`
• `StreamingPlayQAApp`
• `V3LoginApp`
• `NoticeTestQAApp`
• `LocalNotificationTestApp`
• `ABCTests`
• `ABC`, `QA_ABC`, `QA2_ABC`, `DEV_ABC`, `SANDBOX_ABC`

하지만 `HomeTestQAApp`은 예외 가능성이 있다. 현재 확인한 범위에서는:

• `Project.swift`에는 `HomeTestQAApp` 스킴 선언이 있다.
• 그런데 대응되는 target 정의는 찾지 못했다.
• 생성된 `HomeTestQAApp.xcscheme` 파일도 찾지 못했다.

Then 9. `Project(... packages: ...)`에 외부 패키지를 넣으면 어디까지 쓸 수 있나

결론부터 말하면 앱 타깃 수준에서 아는 것과 로컬 Swift Package 내부 코드가 직접 import 가능한 것은 다르다.

한 줄 정리

• `Project(... packages: ...)`는 프로젝트와 앱 타깃이 그 패키지를 아는 단계다.
• 각 로컬 package manifest는 그 패키지 내부 코드가 직접 사용하는 단계다.
• 그래서 “앱 타깃에서 쓸 수 있음”과 “모든 로컬 패키지에서 자동 사용 가능”은 같은 말이 아니다.

Then 10. `.external(name: ...)`를 쓸 수 있는 이유

`dependency definition`에서 `.external(name: "GoogleSignIn")`, `.external(name: "LineSDK")`, `.external(name: "AmplitudeSwift")` 같은 선언을 할 수 있는 이유는, central package registry file 에서 외부 package를 먼저 등록해 두었기 때문이다.

let package = Package(
    name: "PackageName",
    dependencies: [
        .package(url: "https://github.com/Alamofire/Alamofire", from: "5.0.0"),
        .package(url: "https://example.com/company-sdk", exact: "5.14.0"),
        .package(url: "https://github.com/amplitude/Amplitude-Swift", from: "1.17.0")
    ]
)

여기서 중요한 건 `.external(name: ...)`는 URL이 아니라 그 package가 노출하는 product 이름을 참조한다는 점이다. 그래서 Facebook SDK처럼 package 하나에서 `FacebookCore`, `FacebookLogin`, `FacebookBasics` 여러 product가 나올 수도 있다.

Then 11. `productTypes`를 static으로 강제하면 로컬 패키지도 동일하게 적용되나

질문의 핵심은 이것이다. `central package registry file`에서 `Alamofire`를 `.staticFramework`로 강제했으면, 로컬 패키지에서 `Alamofire`를 쓸 때도 static으로 들어오나?

이 프로젝트 기준으로는 그렇게 보는 게 맞다. 즉 Tuist가 생성하는 프로젝트 안에서는 `Alamofire` product를 어떤 타깃이 참조하든, 그 product type 정책은 중앙에서 통일된다고 보는 편이 정확하다.

let packageSettings = PackageSettings(
    productTypes: [
        "Alamofire": .staticFramework,
        "PanModal": .staticFramework,
        "RxSwift": .staticFramework,
        "LineSDK": .framework
    ]
)

다만 로컬 패키지 소스가 `Alamofire`를 직접 쓰려면, 여전히 그 패키지 자신의 package manifest에 `Alamofire` dependency 선언은 있어야 한다. 즉 “쓸 수 있느냐”와 “어떤 타입으로 링크되느냐”는 다른 문제다.

로컬 SPM 패키지 논의를 같은 문서에 붙이기

앞으로 `App`, `Core`, `Feature` 아래 로컬 패키지 논의는 이 문서에 계속 이어 붙인다. 이유는 `Package`, `Dependency`, `Target`, `Scheme`, `Configuration`, 로컬 패키지 구조가 모두 서로 연결돼 있기 때문이다.

Then 12. 문자열 dependency는 target 이름인가, product 이름인가

패키지 파일들을 실제로 대조해 보면, 많은 로컬 패키지는 product 이름과 target 이름을 같게 만들어 둔다. 그래서 `"ABCV3LoginETCUseCases"` 같은 문자열을 보면 target 같아 보이지만, 실제로는 같은 이름의 product와 target이 동시에 존재하는 경우가 많다.

반면 `.product(name: "RxCocoa", package: "RxSwift")` 같은 표기는 외부 package의 특정 product를 정확히 집어서 쓰겠다는 뜻이라 더 명시적이다.

Then 13. 프로젝트 안의 로컬 패키지는 실제로 몇 개고, 무엇이 사용되나

실제 저장소에서 package manifest를 전부 확인해 보면 샘플용 Sample/SwiftConcurrencyPlayground와 Tuist 설정용 central package registry file를 제외한 로컬 Swift Package는 총 53개다.

53개 전체 목록

루트 프로젝트 등록 목록에는 없지만 실제 레포에는 있는 5개

flowchart TD
    A["레포에 존재하는 로컬 패키지 53개"]
    B["abcAppPackages에 직접 등록 48개"]
    C["루트 등록 없음 5개"]
    D["앱 타깃에서 직접 연결"]
    E["다른 로컬 패키지 내부에서 재사용"]

    A --> B
    A --> C
    B --> D
    B --> E
    C --> E
        

Then 14. `ABCV3Home`가 앱까지 연결되는 실제 경로

`ABCV3Home`는 이름만 보면 하나의 패키지처럼 보이지만, 실제 앱 연결에서는 하나의 폴더 안에 있는 여러 product 중 두 개가 앱 타깃에 직접 연결된다.

flowchart LR
    A["Feature/ABCV3Home package folder"]
    B["product: ABCV3HomeFeature"]
    C["product: ABCV3HomeData"]
    D["product: ABCV3HomeDataInterface"]
    E[".Feature.ABCV3Home"]
    F[".Feature.ABCV3Data"]
    G["abcAppDependencies"]
    H["ABC / QA_ABC / DEV_ABC app target"]

    A --> B
    A --> C
    A --> D
    B --> E
    C --> F
    E --> G
    F --> G
    G --> H
    B --> D
    C --> D
        

Then 15. 앱, 로컬 SPM, 외부 SPM 전체 의존성 인터랙티브 맵

이 다이어그램은 프로젝트 조립 관점의 핵심 의존성을 한 번에 보도록 만든 지도다. 기본 상태에서는 선을 거의 숨겨서 복잡해 보이지 않게 했고, 특정 타깃이나 패키지에 마우스를 올리면 관련된 패키지와 선만 강조되도록 만들었다.

질문들을 한 번에 묶는 최종 흐름도

flowchart LR
    P1["로컬 패키지를 프로젝트에 등록하는 목록"]
    P2["외부 SPM을 중앙에서 등록하고 타입 정책을 주는 목록"]
    D1["앱 타깃이 실제로 붙이는 의존성 목록"]
    T1["앱, 테스트, 확장 기능 등 실제 빌드되는 타깃 목록"]
    S1["어떤 타깃을 어떤 설정으로 실행할지 정하는 스킴 목록"]
    C1["Debug_Qa / Release_Qa2 같은 실행 환경 설정"]
    X1["Tuist가 생성한 xcscheme 파일들"]
    A1["Xcode 상단에서 고르는 스킴 선택 UI"]

    P1 --> D1
    P2 --> D1
    D1 --> T1
    T1 --> S1
    C1 --> S1
    S1 --> X1
    X1 --> A1
        

예시 흐름

flowchart LR
    A["sample app helper가 테스트용 앱 타깃 정의를 만든다"]
    B["실제로 생성되는 타깃 이름은 StreamingPlayQAApp 이다"]
    C["이 타깃을 실행하기 위한 스킴 파일이 함께 생성된다"]
    D["그 스킴의 buildAction은 StreamingPlayQAApp 을 빌드 대상으로 잡는다"]
    E["그 스킴의 runAction은 Debug_Qa 설정으로 실행한다"]
    F["그 스킴의 archiveAction은 Release_QA 설정으로 아카이브한다"]

    A --> B
    B --> C
    C --> D
    C --> E
    C --> F
        

이 예시는 테스트용 샘플 앱 helper 하나가 먼저 `StreamingPlayQAApp`이라는 실제 타깃을 만들고, 그 다음 스킴이 그 타깃을 빌드 대상으로 선택한 뒤, 실행할 때는 `Debug_Qa`, 아카이브할 때는 `Release_QA`를 사용하도록 묶는 흐름이다.