SPM: 개념, Swift Package Manager 및 Package.swift

SPM이란?

SPM(Swift Package Manager)는 Swift 언어를 위한 공식 패키지 관리자로, swiftc 컴파일러 및 Xcode 개발 환경에 내장되어 있습니다. 개발자는 이를 사용하여 서드파티 라이브러리를 추가하고, 버전을 관리하며, 자체 패키지를 게시할 수 있습니다. SPM은 Swift 3.0(2016년 9월)에서 명령줄 도구로 처음 등장했으며, Xcode 11(2019년)부터 그래픽 인터페이스와 완전히 통합되어 File → Add Packages 메뉴를 통해 의존성을 추가할 수 있습니다.

SPM은 Git 리포지토리에서 의존성의 소스 코드를 자동으로 다운로드하고, 메인 프로젝트와 병렬로 빌드하며, 결과를 캐시하여 후속 빌드를 더 빠르게 실행합니다. CocoaPods와 달리 SPM은 별도의 작업 공간(xcworkspace)을 생성하지 않으며 의존성이 메인 Xcode 프로젝트의 일부가 됩니다. Swift.org Developer Survey(2024)에 따르면 iOS 개발자의 67%가 SPM을 사용하여 Swift 생태계에서 가장 인기 있는 의존성 관리 도구가 되었습니다.

SPM은 세 가지 플랫폼을 지원합니다: Apple(iOS, macOS, tvOS, watchOS, visionOS), Linux(Ubuntu, CentOS, Amazon Linux) 및 서버 측 Swift(Vapor, Kitura). Linux에서 SPM은 Xcode 없이 완전히 명령줄을 통해 작동합니다.

Swift Package Manager 작동 방식

SPM은 세 가지 핵심 개념을 중심으로 구축되었습니다: 패키지(packages), 제품(products) 및 대상(targets). 패키지는 Package.swift 매니페스트가 있는 Git 리포지토리입니다. 제품은 빌드 결과(라이브러리 또는 실행 파일)입니다. 대상은 패키지 내의 모듈로, 빌드 단위로 컴파일됩니다.

개발자가 Package.swift에 의존성을 추가하면 SPM은 다음 단계를 수행합니다:

1. 클로닝 — SPM이 지정된 URL에서 의존성의 Git 리포지토리를 다운로드합니다.
2. 버전 해결 — SemVer 태그(예: 2.1.3)를 분석하고 지정된 범위 내에서 적절한 버전을 선택합니다.
3. 전이 해결 — 의존성의 의존성을 확인하고 충돌 없는 버전 그래프를 구축합니다.
4. 캐싱 — 다운로드한 소스 코드를 ~Library/Caches/org.swift.swiftpm/에 저장합니다.
5. 컴파일 — 메인 프로젝트의 플래그로 모든 패키지 대상을 빌드합니다.

Package.resolved 파일은 모든 의존성의 정확한 버전을 고정하여 개발 팀이 동일한 라이브러리 세트로 작업하도록 합니다. 이 파일은 버전 관리(git)에 추가해야 합니다.

대안에 비해 SPM의 주요 장점은 중앙 집중식 레지스트리가 필요 없다는 것입니다. 패키지는 GitHub, GitLab, Bitbucket 등 모든 공개 Git 리포지토리뿐만 아니라 회사 사설 Git 서버에도 있을 수 있습니다. Swift 5.2부터 SPM은 소스 코드를 제공하지 않고 XCFramework로 배포되는 바이너리 의존성(바이너리 대상)을 지원합니다.

Package.swift — 프로젝트 매니페스트

Package.swift는 패키지 구조와 의존성을 설명하는 Swift 파일입니다. 파일은 Swift 자체로 작성되며(JSON 또는 YAML 아님), 매니페스트 내에서 조건부 로직, 계산된 상수 및 함수를 사용할 수 있습니다.

Package.swift 기본 구조:

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "MyLibrary",
    platforms: [
        .iOS(.v16),
        .macOS(.v13)
    ],
    products: [
        .library(
            name: "MyLibrary",
            targets: ["MyLibrary"]
        ),
    ],
    dependencies: [
        .package(url: "https://github.com/Alamofire/Alamofire.git",
                 from: "5.9.0"),
        .package(url: "https://github.com/onevcat/Kingfisher.git",
                 from: "7.12.0"),
    ],
    targets: [
        .target(
            name: "MyLibrary",
            dependencies: [
                "Alamofire",
                "Kingfisher"
            ]
        ),
        .testTarget(
            name: "MyLibraryTests",
            dependencies: ["MyLibrary"]
        ),
    ]
)

주요 요소를 살펴보겠습니다:

• // swift-tools-version: 5.9 — SPM 버전을 지정하는 지시문; 사용 가능한 매니페스트 구문이 이에 따라 달라집니다.
• name — Xcode에 표시되고 의존성 링크에 사용되는 패키지 이름입니다.
• platforms — 최소 플랫폼 버전; SPM은 이전 OS 버전에서 패키지 빌드를 허용하지 않습니다.
• products — 패키지가 "내보내는" 것: 라이브러리(.library) 또는 실행 파일(.executable).
• dependencies — URL 및 버전이 있는 외부 패키지 목록; from:, exact:, branch:, revision:을 지원합니다.
• targets — 빌드 대상; 각 대상에는 해당 디렉토리(Sources/TargetName/)의 의존성, 리소스 및 swift 파일 목록이 포함됩니다.

정확한 버전, 브랜치 및 커밋 지정 예:

dependencies: [
    .package(url: "https://github.com/pointfreeco/swift-snapshot-testing.git",
             exact: "1.17.3"),
    .package(url: "https://github.com/pointfreeco/swift-composable-architecture.git",
             branch: "main"),
    .package(url: "https://github.com/apple/swift-log.git",
             revision: "e5c6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4"),
]

Swift 5.9부터 Package.swift에 static framework 및 linkerSettings 지원이 추가되어 정적 및 동적 라이브러리에 대한 더 정밀한 링커 구성이 가능해졌습니다.

SPM 기본 명령어

Swift Package Manager는 터미널을 통해 작업하기 위한 명령어 세트를 제공합니다. 명령어는 패키지 루트 디렉토리(Package.swift가 있는 위치)에서 실행됩니다.

# 라이브러리로 새 패키지 생성
swift package init --type library

# 실행 가능 패키지 생성(콘솔 애플리케이션)
swift package init --type executable

# 프로젝트 빌드
swift build

# 릴리스 구성으로 빌드
swift build -c release

# 테스트 실행
swift test

# 특정 테스트 실행
swift test --filter "MyLibraryTests/testExample"

# 의존성 다운로드 및 해결
swift package resolve

# 의존성을 최신 버전으로 업데이트
swift package update

# 의존성 그래프 표시
swift package show-dependencies

# 빌드 캐시 정리
swift package clean

# Xcode 프로젝트 생성(Xcode 11 이전)
swift package generate-xcodeproj

Xcode 내에서 작업할 때 이러한 명령어의 대부분은 자동으로 실행됩니다: 프로젝트를 열면 의존성이 해결되고, ⌘B로 빌드, ⌘U로 테스트가 시작됩니다. 그러나 Xcode를 사용할 수 없는 CI/CD 파이프라인(GitHub Actions, GitLab CI, Jenkins)에서는 터미널 명령어를 알아야 합니다.

swift package resolve 명령어는 Package.resolved 파일을 생성하거나 업데이트합니다. 이 파일은 전이적 의존성을 포함한 모든 의존성의 정확한 버전을 고정하며 git에 추가해야 합니다. 최신 라이브러리 버전으로 작업하려면 새 기능 브랜치 전에 swift package update를 실행하는 것이 좋습니다.

자체 패키지 만들기

자체 SPM 패키지를 만들면 다중 모듈 프로젝트에서 비즈니스 로직을 캡슐화하고 오픈 소스 라이브러리를 게시하는 데 유용합니다. 단계별 프로세스를 살펴보겠습니다.

단계 1: 초기화

mkdir MyNetworkKit
cd MyNetworkKit
swift package init --type library

단계 2: 디렉토리 구조

swift package init 명령어는 다음 구조를 생성합니다:

MyNetworkKit/
├── Package.swift
├── README.md
├── Sources/
│   └── MyNetworkKit/
│       └── MyNetworkKit.swift
└── Tests/
    └── MyNetworkKitTests/
        └── MyNetworkKitTests.swift

SPM은 자동으로 Sources/ 및 Tests/ 디렉토리를 스캔합니다. Sources 내의 각 하위 디렉토리는 대상(target)에 해당합니다.

단계 3: Package.swift 편집

의존성을 추가하고 대상 플랫폼을 구성해 보겠습니다:

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "MyNetworkKit",
    platforms: [
        .iOS(.v15),
        .macOS(.v12)
    ],
    products: [
        .library(
            name: "MyNetworkKit",
            targets: ["MyNetworkKit"]
        ),
    ],
    dependencies: [
        .package(url: "https://github.com/Alamofire/Alamofire.git",
                 from: "5.9.0"),
    ],
    targets: [
        .target(
            name: "MyNetworkKit",
            dependencies: ["Alamofire"]
        ),
        .testTarget(
            name: "MyNetworkKitTests",
            dependencies: ["MyNetworkKit"]
        ),
    ]
)

단계 4: 코드 작성

// Sources/MyNetworkKit/MyNetworkKit.swift
import Foundation
import Alamofire

public struct NetworkClient {
    private let session: Session

    public init() {
        let configuration = URLSessionConfiguration.default
        configuration.timeoutIntervalForRequest = 30
        self.session = Session(configuration: configuration)
    }

    public func fetchData(from url: String) async throws -> Data {
        let response = try await session.request(url).serializingData().value
        return response
    }
}

단계 5: 게시

패키지를 Git 리포지토리에 푸시하고 SemVer 태그를 만듭니다:

git init
git add .
git commit -m "Initial commit: MyNetworkKit"
git remote add origin https://github.com/username/MyNetworkKit.git
git push -u origin main
git tag 1.0.0
git push --tags

이후 모든 개발자는 .package(url: "https://github.com/username/MyNetworkKit.git", from: "1.0.0")을 사용하여 패키지를 추가할 수 있습니다.

SPM 사용 예제

예제 1: 네트워크 요청을 위한 Alamofire 추가

Alamofire는 Swift에서 가장 인기 있는 HTTP 클라이언트입니다. SPM을 통해 추가하고 GET 요청을 해보겠습니다.

import Alamofire

func fetchUsers() {
    AF.request("https://jsonplaceholder.typicode.com/users")
        .validate()
        .responseDecodable(of: [User].self) { response in
            switch response.result {
            case .success(let users):
                print("(users.count)명의 사용자 수신")
            case .failure(let error):
                print("오류: (error.localizedDescription)")
            }
        }
}

예제 2: Swinject — 의존성 주입

Swinject 라이브러리는 Swift용 DI 컨테이너를 제공합니다. .package(url: "https://github.com/Swinject/Swinject.git", from: "2.8.0")을 통해 추가됩니다.

import Swinject

let container = Container()
container.register(NetworkServiceProtocol.self) { _ in NetworkService() }
container.register(DataRepositoryProtocol.self) { r in
    DataRepository(networkService: r.resolve(NetworkServiceProtocol.self)!)
}

let repository = container.resolve(DataRepositoryProtocol.self)
repository?.loadData()

예제 3: 구조화된 로깅을 위한 Swift-log

Apple의 swift-log 패키지는 여러 백엔드(OSLog, 콘솔, 파일)를 지원하는 통합 로깅 API를 제공합니다.

import Logging

var logger = Logger(label: "com.myapp.network")
logger.logLevel = .debug

logger.info("네트워크 요청 시작됨", metadata: [
    "url": "(requestURL)",
    "method": "GET"
])

logger.warning("응답 시간이 2초 초과")
logger.error("연결 오류: 인터넷 없음")

이 세 가지 예제는 SPM의 일반적인 사용 시나리오(HTTP 클라이언트, DI 컨테이너 및 시스템 인프라)를 다룹니다. 라이브러리 선택은 우연이 아닙니다 — Alamofire, Swinject 및 swift-log는 GitHub에서 가장 많은 별표를 받은 Swift 패키지 상위 20위 안에 있습니다.

CocoaPods 및 Carthage에서 마이그레이션

프로젝트가 CocoaPods 또는 Carthage를 사용하는 경우 SPM으로의 마이그레이션은 몇 단계로 수행됩니다. 이 프로세스는 안전합니다. SPM 의존성은 동일한 프로젝트에서 CocoaPods 및 Carthage와 공존할 수 있어 점진적인 마이그레이션이 가능합니다.

CocoaPods → SPM

1. Xcode에서: File → Add Package Dependency, 패키지 URL을 입력합니다.
2. 버전을 선택하고 필요한 대상에 패키지를 추가합니다.
3. SPM을 통해 모든 의존성을 추가한 후 Podfile에서 줄을 제거합니다.
4. .xcworkspace를 제거하고 .xcodeproj를 연 후 Clean Build Folder를 실행합니다.

Carthage → SPM

1. Xcode File → Add Package Dependency를 통해 패키지를 추가합니다.
2. Cartfile에서 의존성을 제거합니다.
3. Build Phases에서 Carthage 빌드 스크립트를 제거합니다.
4. 캐시 정리: 터미널에서 rm -rf Carthage/ 실행.

2025년 기준으로 SPM은 대부분의 인기 Swift 라이브러리를 지원합니다. 예외는 모듈 맵이 없는 일부 ObjC 프레임워크입니다. 라이브러리가 아직 SPM을 지원하지 않는 경우 README의 Installation 섹션을 확인하세요. 대부분의 작성자는 최신 버전에서 이미 SPM 지원을 추가했습니다.