Carthage: 무엇인가, 분산형 의존성 관리자

Carthage란?

Carthage는 2014년 Swift 커뮤니티의 개발자들이 만든 분산형 아키텍처의 의존성 관리자입니다. Carthage는 중앙 사양 레지스트리를 사용하지 않습니다 — 각 라이브러리는 URL 또는 GitHub 이름을 통해 Git 저장소에서 직접 연결됩니다. Carthage는 소스 코드를 다운로드하여 바이너리 프레임워크(.xcframework 또는 .framework)로 빌드하고, 개발자에게 Xcode 프로젝트에 수동으로 통합할 준비가 된 아티팩트를 제공합니다.

Carthage의 아키텍처는 세 가지 구성 요소로 구성됩니다: CLI 도구 carthage, 구성 파일 Cartfile, 빌드된 프레임워크가 있는 Carthage/Build/ 디렉토리. Carthage와 CocoaPods의 주요 차이점은 .xcodeproj의 자동 수정이 없다는 것입니다. Carthage는 .xcworkspace를 만들지 않으며, 컴파일러 플래그를 구성하지 않고, Pods.xcconfig를 생성하지 않습니다. 개발자는 Xcode를 통해 프로젝트에 수동으로 프레임워크를 추가하여 통합 프로세스를 완전히 제어할 수 있습니다.

Carthage는 병렬 의존성 빌드를 사용하여 멀티코어 프로세서에서 프로세스를 크게 가속화합니다. 각 의존성은 별도의 대상으로 빌드되며, Carthage는 전이 의존성의 그래프를 자동으로 해결하여 올바른 순서로 빌드합니다. 커뮤니티 벤치마크에 따르면 Carthage는 최신 Mac에서 평균 30~60초 안에 15~20개의 의존성을 빌드하며, 이는 라이브러리가 많은 프로젝트의 경우 CocoaPods보다 빠릅니다. Carthage는 모든 Apple 플랫폼(iOS, macOS, watchOS, tvOS)을 지원하며, 버전 0.38+부터 시뮬레이터 및 Apple Silicon 기기 지원을 위한 유니버설 .xcframework를 빌드합니다.

Carthage 작동 방식

Carthage는 각 의존성의 Git 저장소를 클론하고, 지정된 버전(태그, 커밋 또는 브랜치)으로 전환한 후 xcodebuild를 실행하여 프레임워크를 빌드합니다. Carthage는 빌드 스킴에 따라 Xcode 프로젝트 유형(프레임워크, 동적 프레임워크, 정적 라이브러리)을 자동으로 판별합니다. 프로젝트에 여러 스킴이 있는 경우 Carthage는 기본 스킴(알파벳 순서로 첫 번째)을 사용합니다. 빌드 후 Carthage는 완성된 프레임워크를 Carthage/Build/에 복사하고 정확한 버전이 고정된 Cartfile.resolved 파일을 만듭니다. Carthage는 빌드된 프레임워크의 캐싱을 지원합니다 — 의존성에 변경 사항이 없으면 재빌드를 건너뜁니다.

Carthage의 전이 의존성은 Cartfile.resolved를 통해 처리됩니다: Carthage는 필요한 모든 의존성의 그래프를 구성하고 올바른 순서로 빌드합니다. 두 라이브러리가 동일한 타사 라이브러리에 의존하는 경우 Carthage는 한 번 빌드하여 두 라이브러리에 모두 사용합니다. Carthage는 특정 대상과 원인을 나타내는 빌드 오류를 보고하여 문제 진단을 간소화합니다.

Cartfile: 구조, 구문 및 예제

Cartfile은 Carthage 프로젝트의 의존성을 정의하는 Ruby 유사 구문(Cartfile 형식)의 구성 파일입니다. Cartfile은 프로젝트 루트의 .xcodeproj 옆에 위치합니다. Cartfile의 각 줄은 하나의 의존성(소스(Git URL, GitHub 저장소)와 버전)을 설명합니다. 구문은 태그, 커밋 및 브랜치를 통한 버전 고정을 지원합니다.

# 기본 의존성: Carthage
github "Alamofire/Alamofire" ~> 5.9
github "SnapKit/SnapKit" ~> 5.7
github "onevcat/Kingfisher" == 8.0.0

github "Owner/Repo" 지시문은 GitHub 저장소의 약식 형식입니다. Carthage는 자동으로 URL https://github.com/Owner/Repo.git을 구성합니다. GitLab, Bitbucket 및 기타 Git 호스트의 경우 전체 URL이 사용됩니다: git "https://gitlab.com/owner/repo.git". 버전 연산자: ~> 5.9(5.9에서 6.0까지 모든 버전, 6.0 제외), == 8.0.0(정확한 버전), >= 1.0(최소 버전). 특정 커밋은 github "owner/repo" "abc1234"로 고정할 수 있습니다.

전체 Cartfile 예제

Carthage는 다양한 구성을 위한 여러 디렉토리를 지원합니다: Cartfile(기본), Cartfile.private(게시되지 않는 내부 의존성용), Cartfile.resolved(자동 생성). 비공개 의존성은 테스트 프레임워크와 같이 개발 빌드에서만 사용되는 라이브러리에 유용합니다.

# Cartfile — 주요 의존성
github "Alamofire/Alamofire" ~> 5.9
github "SwiftyJSON/SwiftyJSON" ~> 4.0
github "realm/realm-swift" ~> 10.0

# 전체 URL용 GitLab
git "https://gitlab.com/company/internal-lib.git" == 2.1.1

# 개발 브랜치
github "marmelroy/PhoneNumberKit" "development"

github와 git은 Cartfile의 두 가지 소스 유형입니다. 전자는 GitHub 전용이며 자동으로 URL을 생성합니다. 후자는 전체 URL이 있는 모든 공개 또는 비공개 Git 저장소용입니다. 버전은 태그(== 2.1.1), 시맨틱 범위(~> 5.9), 브랜치 이름("development") 또는 커밋 해시("a1b2c3d")로 지정할 수 있습니다. 시맨틱 범위(~>)는 SemVer를 따르는 의존성에 권장되며, 업데이트 시 호환성이 깨지는 변경으로부터 보호합니다.

Cartfile.resolved는 carthage update 후 자동으로 생성됩니다. 전이 의존성을 포함한 모든 설치된 의존성의 정확한 버전을 고정합니다. 이 파일은 Git에 보관해야 합니다 — 이 파일이 없으면 다른 머신에서 carthage bootstrap 명령이 동일한 규칙으로 라이브러리를 빌드하지만 버전이 다를 수 있습니다. carthage outdated는 새 버전을 사용할 수 있는 오래된 의존성 목록을 표시합니다.

Carthage 설치 및 구성

Carthage는 Homebrew(macOS의 표준 패키지 관리자)를 통해 설치됩니다. 대체 방법: GitHub에서 빌드된 .pkg 설치 프로그램으로 설치하거나 소스에서 빌드. Carthage는 Xcode with Command Line Tools(xcodebuild 포함)가 필요하며, Apple Silicon Mac에서는 일부 레거시 의존성을 위해 Rosetta 2가 필요합니다.

# 설치 Carthage를 통해 Homebrew
brew install carthage

# 버전 확인
carthage version

# .pkg에서 설치 (만약 Homebrew를 사용할 수 없을 경우)
# 다운로드: Carthage.pkg를 GitHub Releases에서 가져와 수동으로 설치

Carthage를 설치한 후, 프로젝트 초기화는 프로젝트 루트에 Cartfile을 생성하는 것으로 시작됩니다. Carthage에는 init 명령이 없습니다 — 파일은 텍스트 편집기에서 수동으로 생성됩니다. Cartfile을 의존성으로 채운 후, 개발자는 carthage bootstrap(Cartfile.resolved가 이미 있는 경우) 또는 carthage update(초기 설치 또는 업데이트)를 실행합니다. Carthage는 저장소를 클론하고, 프레임워크를 빌드하여 Carthage/Build/에 배치합니다.

Carthage 업데이트는 brew upgrade carthage를 통해 수행됩니다. 버전은 carthage version으로 확인합니다. 2025년 중반 현재 최신 안정 버전은 0.40으로, 기본 .xcframework 지원, 개선된 병렬 빌드 및 완전한 Swift 6 지원을 제공합니다. 버전 0.39부터 Carthage는 호환성 심 없이 레거시 .framework 빌드를 중단했습니다 — --use-xcframeworks를 명시적으로 지정하는 것이 좋습니다.

# 업데이트: Carthage를 통해 Homebrew
brew upgrade carthage

# 특정 버전 설치
brew install carthage@0.39

# 전체 재설치
brew uninstall carthage && brew install carthage

참고: Carthage는 .xcworkspace를 만들지 않고 .xcodeproj를 수정하지 않습니다. CocoaPods와 달리 Carthage는 Xcode 구성의 완전한 제어를 개발자에게 맡깁니다. 즉, 의존성을 설치한 후 수동으로 프레임워크를 Xcode에 추가해야 합니다(«Xcode에 Carthage 프레임워크 통합» 섹션 참조). Carthage는 또한 각 의존성에 프레임워크 대상이 있는 Xcode 프로젝트 또는 워크스페이스가 포함되어야 합니다 — 그렇지 않으면 빌드가 실패합니다.

프레임워크 빌드: bootstrap 및 update

Carthage는 의존성 작업을 위한 세 가지 주요 명령을 제공합니다: bootstrap, update 및 build. carthage bootstrap은 기존 Cartfile.resolved에서 의존성을 빌드합니다 — CI 환경 및 프로젝트에 합류하는 개발자에게 권장됩니다. carthage update는 Cartfile.resolved를 최신 버전(Cartfile 제약 조건 준수)으로 업데이트하고 빌드를 수행합니다. carthage build는 버전을 저장하지 않고 지정된 모든 의존성을 빌드합니다.

# 초기 설치(버전 업데이트)
carthage update --use-xcframeworks --platform iOS

# 고정된 버전으로 재빌드
carthage bootstrap --use-xcframeworks --platform iOS

# 하나의 의존성만 빌드
carthage build Alamofire --platform iOS

--use-xcframeworks 플래그는 Carthage에 레거시 .framework 대신 유니버설 .xcframework를 빌드하도록 지시합니다. 이는 시뮬레이터와 실제 기기 모두, 그리고 추가 스크립트 없이 Apple Silicon Mac을 지원합니다. --platform iOS 플래그는 빌드를 단일 iOS 플랫폼으로 제한하여, 특히 프로젝트에 크로스 플랫폼 라이브러리가 포함된 경우 프로세스를 크게 가속화합니다.

Carthage는 --cache-builds 플래그를 통한 병렬 빌드를 지원하여 이미 빌드된 프레임워크를 캐시합니다. 재빌드 시 Carthage는 Git 커밋 해시를 확인하고 코드가 변경되지 않은 경우 컴파일을 건너뜁니다.

Xcode에 Carthage 프레임워크 통합

통합 Carthage 프레임워크를 Xcode에 통합하는 것은 4단계로 수동으로 수행됩니다. carthage update 또는 bootstrap을 실행한 후, 빌드된 모든 프레임워크는 Carthage/Build/iOS/(또는 해당 플랫폼)에 위치합니다. 개발자는 Xcode 프로젝트를 열고, 앱 대상을 선택하고, General → Frameworks, Libraries, and Embedded Content에 프레임워크를 추가합니다. 런타임 프레임워크(동적 라이브러리)의 경우 «Embed & Sign»을 선택해야 합니다 — 그렇지 않으면 앱이 시작 시 «dyld: Library not loaded» 오류와 함께 충돌합니다.

Carthage 정적 라이브러리의 경우 더 간단합니다 — 앱의 실행 파일에 직접 링크되므로 포함 단계가 필요하지 않습니다. 그러나 Carthage는 기본적으로 동적 프레임워크를 빌드합니다(명시적으로 구성된 정적 라이브러리 제외). 앱 크기를 최소화하는 것이 중요한 프로젝트의 경우 Xcode 설정을 통한 정적 링크가 권장됩니다.

추가 단계는 Build Phase → Run Script에 Input Files를 추가하는 것입니다. Carthage는 빌드된 프레임워크에서 시뮬레이터 아티팩트를 제거하는 스크립트(strip simulator architectures)가 필요합니다. 이 스크립트는 App Store 빌드에 필요합니다:

# Run Script용 App Store (strip simulator architectures)
FRAMEWORKS_DIR="${SRCROOT}/Carthage/Build/iOS"
for framework in "$FRAMEWORKS_DIR"/*.framework; do
  bash "$BUILD_DIR/src/scripts/strip-framework.sh" "$framework"
done

Carthage는 .xcworkspace 사용이 필요하지 않습니다 — 모든 의존성이 이미 바이너리 프레임워크로 빌드되어 있습니다. Carthage는 워크스페이스를 생성하는 CocoaPods와 달리 .xcodeproj와 직접 작동합니다. 이는 Carthage 의존성이 Xcode 프로젝트 구성을 변경하지 않기 때문에 버전 관리와 CI 설정을 간소화합니다. 유일한 변경 사항은 대상에 프레임워크를 추가하는 것이며, 이는 .pbxproj에 기록됩니다.

Carthage vs CocoaPods vs Swift Package Manager

Carthage, CocoaPods 및 Swift Package Manager(SPM)은 iOS 개발의 세 가지 주요 의존성 관리자입니다. Carthage는 분산형 접근 방식으로 두드러지며, CocoaPods는 중앙 집중식 레지스트리를 제공하고, SPM은 Apple의 내장 솔루션입니다. 이들 간의 선택은 프로젝트 요구 사항, 팀 규모 및 원하는 자동화 수준에 따라 다릅니다.

Carthage는 Xcode 구성에 최소한의 간섭이 필요하고 통합 프로세스를 완전히 제어해야 하는 프로젝트에 선택됩니다. Carthage는 작성자가 사용자에게 의존성을 독립적으로 빌드할 수 있는 자유를 제공하려는 오픈 소스 라이브러리 및 프레임워크에 이상적입니다. Carthage는 UNIX 철학(각 도구는 한 가지 일을 잘 수행)을 중시하는 개발자들 사이에서도 인기가 있습니다. CocoaPods는 자동화가 중요한 수십 개의 의존성이 있는 엔터프라이즈 프로젝트의 표준으로 남아 있습니다. SPM은 Xcode에 내장되어 있고 Apple이 적극적으로 개발하고 있기 때문에 새로운 프로젝트를 위한 선택입니다.

마이그레이션 관리자 간의 마이그레이션은 다른 접근 방식이 필요합니다. Carthage → SPM: Xcode에서 프레임워크 제거, Cartfile 삭제, File → Add Package Dependencies를 통해 Package Dependencies 추가. Carthage → CocoaPods: Carthage 프레임워크 제거, Podfile 생성, 의존성 추가 및 pod init && pod install 실행. Carthage에서 CocoaPods 또는 SPM으로 마이그레이션할 때 프레임워크를 수동으로 업데이트할 필요가 없어집니다 — 모든 의존성이 단일 명령으로 업데이트됩니다. Carthage는 공급업체 종속을 피하고 의존성 빌드의 투명성을 유지하는 것이 중요한 프로젝트에서 계속 관련성이 있습니다.

일반적인 문제 및 해결 방법

Carthage는 안정적인 도구이지만, 개발자는 특히 CI 서버에서 빌드하거나, Xcode를 업데이트하거나, Swift 버전을 변경할 때 정기적으로 일반적인 문제에 직면합니다. 대부분의 문제는 캐시를 지우고, --use-xcframeworks를 올바르게 구성하고, 최소 iOS 버전을 확인하여 해결됩니다.

오류 «The file manager returned an error» — Carthage 캐시가 손상되었거나 파일 권한 충돌이 있을 때 발생합니다. 해결 방법: rm -rf ~/Library/Caches/carthage로 캐시를 삭제하고 carthage bootstrap을 다시 실행합니다. 프로젝트에서 Carthage/ 디렉토리를 삭제하고 재빌드하는 것도 도움이 됩니다. CI 서버에서는 Cartfile.resolved가 변경된 경우에만 Carthage 캐시를 업데이트해야 합니다.

오류 «No such module» — Carthage 빌드는 성공했지만 Xcode에서 프레임워크를 찾을 수 없습니다. 해결 방법: General → Frameworks, Libraries, and Embedded Content에서 프레임워크 경로를 확인합니다. 프레임워크는 Carthage/Build/iOS/에 있어야 합니다. .xcframework가 올바르게 추가되었는지 확인합니다(다시 드래그). 동적 프레임워크의 경우 Embed & Sign을 확인합니다. 오류가 지속되면 Build Settings에 FRAMEWORK_SEARCH_PATHS를 추가합니다.

Swift 비호환성으로 인한 빌드 오류 — 라이브러리가 프로젝트와 다른 Swift 버전으로 빌드되었습니다. 해결 방법: 동일한 Swift 버전으로 소스에서 빌드하도록 carthage update --no-use-binaries를 사용합니다. 라이브러리가 현재 버전에서 컴파일되지 않는 경우 .xcconfig를 사용하여 Swift 버전을 지정하거나 라이브러리를 포크합니다. Carthage 0.39부터 --use-xcframeworks는 바이너리에 올바른 Swift 버전을 자동으로 포함합니다.

CI 빌드 문제 — CI의 Carthage는 적절한 캐시 구성이 필요합니다. 해결 방법: Carthage/Build/ 및 ~/Library/Caches/carthage/를 캐시합니다. 버전 변경을 피하기 위해 CI에서는 update 대신 carthage bootstrap --use-xcframeworks --platform iOS를 사용합니다. GitHub Actions용 공식 Carthage 액션을 사용할 수 있습니다. Jenkins용 — CarthageBuild 플러그인. GUI 없이 macOS에서 Carthage가 충돌할 수 있습니다 — 해결 방법: brew install xcode-build-server를 설치하거나 -UseModernBuildSystem=NO 플래그를 추가합니다.