xtool 딥다이브
— Swift 코드가 아이폰 앱이 되기까지

1프로젝트 한줄 요약

xtool은 SwiftPM 패키지를 iOS 앱으로 빌드하고, 서명해서 실제 기기에 설치하는 크로스플랫폼 명령줄 도구입니다. 핵심은 다른 운영체제에서 Swift 문법을 쓰는 데 있지 않습니다. 이미 존재하는 Swift 컴파일러와 Apple SDK를 연결하고, 설치 가능한 앱을 완성하는 나머지 절차를 자동화하는 데 있습니다.

컴파일된 실행 파일과 아이폰에 설치할 수 있는 앱 사이의 간격을 메우는 것이 xtool의 핵심입니다. 그 간격을 이해하면 빌드 도구, 패키지 관리자, 코드 서명이 왜 서로 다른 부품인지 보이기 시작합니다.

1-1. 사용자가 입력하는 명령과 안에서 벌어지는 일

아래는 공식 설치와 SDK 구성을 마친 뒤의 사용 흐름입니다. 첫 명령은 새 앱 프로젝트를 만들고, 두 번째는 앱을 조립합니다. 기기 설치와 인증은 뒤 단계에서 별도로 다루면 실패 원인을 좁히기 쉽습니다.

# 개발 환경 설정 후, 새로운 앱 프로젝트에서 사용하는 예
xtool new --skip-setup Hello
cd Hello
xtool dev build

# 인증과 기기 연결까지 준비된 경우의 설치 경로
xtool dev run

# 명시적인 기기 실행은 별도 명령이다
xtool launch 실제로_설치된_bundleID

Sources/XToolSupport/NewCommand.swift의 NewCommand.run()은 Package.swift, xtool.yml, SwiftUI 화면 코드를 생성합니다. --skip-setup을 생략하면 먼저 SetupOperation을 호출하므로, 프로젝트 생성만 하려는 독자는 이 차이를 알아두어야 합니다.

Sources/XToolSupport/DevCommand.swift의 DevRunCommand.run()은 앱 빌드 후 IntegratedInstaller.install()로 연결됩니다. 이 함수 본문에는 LaunchCommand 호출이 없습니다. 명령 이름의 “run”만 보고 자동 실행까지 보장된다고 읽지 말고, 실제 설치와 실행 단계를 구분해야 합니다.

1-2. “Xcode replacement”를 읽는 정확한 범위

README는 빌드, 서명·설치, Apple Developer Services 접근을 지원한다고 설명합니다. 소스에서도 이 세 경로를 확인할 수 있습니다. 반면 Xcode의 화면 편집기, SwiftUI 미리보기, Instruments 전체를 구현한 IDE라고 이해하면 범위를 크게 벗어납니다. macOS의 작은 SwiftUI 창도 코드 편집기가 아니라 CLI 등록 방법을 알려주는 안내 화면입니다.

2왜 주목받는가

2026-10-23 분석 기준 선정 순위는 GitHub Trending Swift Weekly #1입니다. 스타 13,421개와 포크 715개는 관심의 크기를 보여주지만, 특정 기능 때문에 순위가 올랐음을 증명하지는 않습니다. 아래 세 가지는 README·문서·구현으로 볼 때 관심을 끌 만한 이유에 대한 해석입니다.

2-1. Linux와 WSL에서 이어지는 iOS 개발 흐름

프로젝트 소개의 “Windows”는 공식 설치 문서 Documentation/xtool.docc/Installation-Linux.md에서 WSL을 통한 Linux 환경으로 구체화됩니다. 기존 Linux 개발 환경에서 SwiftPM 프로젝트를 빌드하고 아이폰으로 전달할 수 있다는 점이 눈에 띕니다. Windows 네이티브 실행 파일이나 Linux용 iOS 시뮬레이터가 제공된다는 뜻은 아닙니다.

개발용 컴퓨터의 운영체제와 결과물이 실행될 운영체제를 분리해 생각하게 만든다는 점이 이 프로젝트의 매력입니다. Linux에서 실행되는 컴파일러가 iOS용 코드를 만들고, 실제 실행은 아이폰이 맡는 구조입니다.

2-2. 설정이 파일에 남고, 자동화의 입력이 된다

Package.swift는 타깃과 의존성을, xtool.yml은 앱 식별자·권한·자원을 표현합니다. GUI에서 클릭한 상태를 기억하는 대신, 설정 변경을 텍스트 차이로 검토할 수 있습니다. 명령줄 중심의 흐름은 반복 작업을 자동화하기에도 알맞지만, 이것만으로 어떤 앱이든 곧바로 App Store에 배포할 수 있다는 보장은 아닙니다.

비교 기준은 Apple의 Xcode 소개, fastlane 공식 저장소, xtool의 Package.swift와 macOS/fastlane/Fastfile입니다. 서로를 대체하는 경우도 있지만, 한 도구가 다른 도구를 내부에서 활용하는 관계도 있습니다.

2-3. 제품의 어려운 부분까지 공개되어 있다

단순한 명령 래퍼였다면 공부 범위도 작았을 것입니다. 이 저장소에는 인증 방식 전환, 운영체제별 HTTP 구현, 기기 연결 복구, 권한과 서버 기능의 매핑, AppImage와 macOS 앱 배포가 함께 있습니다. 초보자에게는 “기능이 동작한다” 이후에 필요한 제품화 작업을 한 번에 살펴볼 수 있는 사례입니다.

3기술 스택 전체 지도

일반적인 웹 서비스의 프론트엔드·백엔드 구분을 그대로 적용하면 혼란스럽습니다. 이 저장소는 로컬 CLI와 라이브러리가 중심입니다. 사용자 접점은 명령줄, 핵심 처리는 PackLib와 XKit, 외부 서비스는 Apple 개발자 API와 인증 보조 서비스입니다. 자체 웹 서버나 데이터베이스를 필수 구성요소로 두지 않습니다.

3-1. 언어와 패키지의 기본 선언

루트 Package.swift 첫 줄은 // swift-tools-version:6.2이며, 플랫폼 선언은 .iOS(.v17)과 .macOS(.v14)입니다. 공개 제품은 XKit, XToolSupport 라이브러리와 xtool 실행 파일입니다. Linux 지원은 여기에 .linux 최소 버전을 적는 방식이 아니라 조건부 의존성과 플랫폼별 구현으로 드러납니다.

3-2. 사용자 접점: 명령줄과 작은 macOS 안내 창

Sources/xtool/XTool.swift의 XToolMain.main()은 18줄짜리 진입 파일에 있습니다. 실제 명령 등록과 취소 처리는 Sources/XToolSupport/XTool.swift로 옮겨져 있습니다. 얇은 실행 파일이 재사용 가능한 라이브러리를 호출하는 구조입니다.

3-3. 핵심 처리 계층: 빌드·네트워크·서명·기기 통신

이 버전은 루트 Package.swift와 Package.resolved 기준입니다. 의존 패키지 내부의 구현 전체가 이 저장소에 포함된다는 뜻은 아닙니다. 예를 들어 zsign의 저수준 서명 코드는 별도 저장소의 책임이며, 여기서는 이를 호출하는 연결부를 읽을 수 있습니다.

3-4. 인프라·빌드: 도구를 만드는 도구들

Sources/XToolSupport/SDKBuilder.swift는 SDK 호환성을 구분하는 값 sdkEpoch = 4도 관리합니다. darwin-tools와 OpenAppleMacros 버전은 이 파일의 상수에, unxip 버전은 Package.resolved에 있습니다. fastlane 버전은 macOS/Gemfile.lock, SwiftLint 버전은 .swiftlint.yml에 있습니다.

도구 버전 하나만 확인해서는 환경을 재현할 수 없고, 패키지·컴파일러·SDK·배포 도구의 버전을 나누어 읽어야 합니다. 특히 Dockerfile의 libimobiledevice는 고정 태그 대신 master를 사용합니다. 잠금 파일이 있다고 전체 공급망이 완전히 고정되는 것은 아닙니다.

4아키텍처 심화 분석

4-1. 시스템 전체 구조도

먼저 xtool dev run의 경로를 보겠습니다. 굵직한 경계는 빌드 계획 → 앱 조립 → 개발 계정 허가 → 서명 → 기기 설치입니다. 아래 그림의 Apple 서비스와 Anisette 서비스는 로컬 모듈 밖에 있으며, 빌드 결과를 만드는 과정과 인증 네트워크 통신은 별개입니다.

사용자 / 편집기
    |
    +-- xtool 명령 -------------------------------------+
    |                                                  |
    v                                                  v
XToolSupport                                     LSP / BSP 연결
  XToolCommand → DevRunCommand                    빌드 정보 전달
    |
    v
PackOperation.run()
    |
    +-- Package.swift / Package.resolved / xtool.yml
    |       |
    |       v
    |   Planner.createPlan() ----> Plan
    |                              |
    |                     +--------+-------------------+
    |                     v                            v
    |                 Packer.pack()              XcodePacker
    |                     |                      프로젝트 생성
    |              SwiftPM / SwiftBuild
    |              + Apple SDK + 도구 모음
    |                     |
    |                     v
    +------------------ 이름.app
                          |
                          v
XKit: IntegratedInstaller.install()
    |
    +-- AutoSigner.sign()
    |      |
    |      +-- DeveloperServicesProvisioningOperation
    |      |     +-- 기기 등록
    |      |     +-- 개발 인증서 확보
    |      |     +-- 앱 ID / 기능 / 프로파일 준비
    |      |                    |
    |      |                    +----> Apple 개발자 서비스
    |      +-- 번들 ID 갱신 / 프로파일 삽입 / 코드 서명
    |
    +-- Payload 압축 ----> .ipa
    +-- AppInstaller ----> 업로드 ----> iPhone / iPad 설치

비밀번호 인증 경로: GrandSlam + ADIDataProvider
                                |
                                +----> Apple 인증 서비스
                                +----> Omnisette 인증 보조 서비스

Sources/XToolSupport/DevCommand.swift는 조립 결과 URL을 받은 뒤 AuthToken, ConnectionOptions, IntegratedInstaller를 연결합니다. dev build는 서명 옵션 없이 조립까지만 할 수 있고, --sign을 주면 별도로 signInPlace()가 호출됩니다.

4-2. 설계 패턴 ① 계획과 실행의 분리

Sources/PackLib/Planner.swift의 createPlan()은 패키지 그래프에서 메인 앱·확장·자원·권한 경로를 찾아 Plan에 담습니다. Packer.pack()은 그 계획을 실제 파일로 바꿉니다. 이렇게 두 단계를 나누면 “무엇을 만들까”를 계산하는 코드와 “어떻게 만들까”를 수행하는 코드를 따로 읽을 수 있습니다.

// Sources/XToolSupport/DevCommand.swift의 핵심 호출 순서 발췌
let planner = Planner(
    buildSettings: buildSettings,
    schema: schema
)
let plan = try await planner.createPlan()

if xcode {
    return try await XcodePacker(plan: plan).createProject()
}

let packer = Packer(
    buildSettings: buildSettings,
    plan: plan
)
let bundle = try await packer.pack()

같은 Plan을 XcodePacker.createProject()에도 넘깁니다. 이 중간 표현이 있기 때문에 SwiftPM 기반 조립과 Xcode 프로젝트 생성이 같은 앱 정의를 공유할 수 있습니다. 실행하기 전에 계획을 데이터로 만들면, 하나의 앱 정의를 여러 출력 방식에 재사용할 수 있습니다.

Planner.buildGraph()는 SwiftPM의 show-dependencies와 describe JSON을 읽습니다. product(...)는 타깃을 순회하며 자원 번들·동적 라이브러리를 수집하고, 호스트에서 동작하는 macro 타깃은 건너뜁니다. 매크로 구현을 아이폰에 넣을 코드와 혼동하지 않도록 하는 구체적인 경계입니다.

4-3. 설계 패턴 ② 프로토콜과 의존성 주입으로 플랫폼 차이 감추기

Sources/XKit/HTTPClientProtocol/HTTPClientProtocol.swift는 HTTP 전송과 WebSocket에 필요한 공통 계약을 정의합니다. Linux에서는 Sources/XKit/HTTPClientProtocol/AsyncHTTPClient+HTTP.swift, Apple 플랫폼에서는 Sources/XKit/HTTPClientProtocol/URLSession+HTTP.swift가 실제 구현을 제공합니다. 사용하는 쪽은 운영체제별 클래스를 직접 만들 필요가 줄어듭니다.

// Sources/XKit/DeveloperServices/DeveloperServicesClient.swift 발췌
@Dependency(\.anisetteDataProvider) var anisetteDataProvider
@Dependency(\.httpClient) var httpClient

// macOS/XToolMac/XToolMac.swift의 저장소 선택 발췌
try await withDependencies {
    $0.keyValueStorage = KeychainStorage(
        service: "sh.xtool.keychain.credentials"
    )
} operation: {
    try await XTool.run()
}

이 패턴은 네트워크뿐 아니라 저장소에도 적용됩니다. 기본 구현은 DirectoryStorage이고, 정식 macOS 앱의 CLI 경로는 위처럼 KeychainStorage를 주입합니다. 테스트에서는 MemoryKeyValueStorage로 바꿀 수 있습니다. “필요한 능력”과 “지금 사용할 구현”을 분리한 셈입니다.

4-4. 설계 패턴 ③ actor와 진행 중인 Task를 이용한 공유 작업 관리

Sources/PackLib/ToolRegistry.swift의 Cache는 actor입니다. 캐시에는 최종 URL 대신 Task<URL, Error>를 저장합니다. 같은 실행 파일 경로를 여러 곳에서 동시에 요청해도, 이미 시작한 탐색 작업을 같이 기다릴 수 있습니다.

// ToolRegistry.Cache.locate(tool:)의 분기 발췌
let task: Task<URL, Error>
if let cached = cache[tool] {
    task = cached
} else {
    task = Task { try await _locate(tool: tool) }
    cache[tool] = task
}
return try await task.value

중요한 순서는 작업을 저장한 다음 기다린다는 것입니다. await 중에는 다른 요청이 actor에 들어올 수 있지만 이미 캐시가 채워져 있습니다. actor가 있다고 비동기 메서드 전체가 하나의 트랜잭션이 되는 것은 아닙니다. 이 구현은 실패한 Task도 남으므로 같은 프로세스 안에서 재요청할 때 재탐색하지 않는다는 점도 읽을 수 있습니다.

IntegratedInstaller와 AppInstaller 역시 actor입니다. 다만 진행률 콜백을 정리하는 queueUpdateTask()는 LockIsolated로 이전 Task를 잡고 순서를 연결합니다. actor라는 이름 하나로 모든 순서 문제가 해결되는 것이 아니라, 콜백이 들어오는 경계도 따로 관리합니다.

4-5. 설계 패턴 ④ 선언형 권한을 실제 서버 기능으로 변환하기

앱의 권한 파일에 키를 적는 것과 Apple 개발자 계정에서 기능을 켜는 것은 서로 다른 일입니다. AppleSignInEntitlement는 com.apple.developer.applesignin을 [String]으로 해석합니다. 이어 Sources/XKit/DeveloperServices/App IDs/Entitlements/DeveloperServicesCapability.swift가 이를 서버 기능 .appleIdAuth와 주 앱 동의 설정으로 변환합니다.

이 연결은 최근 커밋 952a7ff의 “Sign in with Apple 지원”을 이해하는 실마리입니다. 변경의 의미는 로그인 화면 전체를 구현했다는 것이 아니라, 서명·프로비저닝 과정에서 해당 entitlement와 capability를 다루도록 연결했다는 데 있습니다.

권한 해석과 개발자 서비스 연동 코드는 모두 Sources/XKit/ 아래에 있습니다. 무료 팀에서는 addApp(...)이 유료 capability를 요구하는 인식된 권한을 필터링합니다. 따라서 “코드가 키를 이해한다”와 “내 계정으로 그 기능을 쓸 수 있다”는 별개의 조건입니다.

4-6. 실패를 단계별로 나누면 디버깅이 쉬워진다

performWithRecovery()는 신뢰 확인 대기와 기기 암호 잠금 오류를 잡아 메시지를 바꾸고, 기본 0.1초 간격으로 다시 시도합니다. 나머지 오류는 호출부로 전달합니다. 복구 가능한 오류만 구분하는 방식도 배울 만합니다.

5디렉토리 구조 해부

xtool/
+-- Package.swift                 패키지·제품·타깃·의존성 선언
+-- Package.resolved              의존성의 정확한 선택 버전
+-- Sources/
|   +-- xtool/                    CLI 진입점
|   +-- XToolSupport/             명령, 인증 설정, SDK 생성, 편집기 연결
|   +-- PackLib/                  설정 해석, 계획, 빌드, 앱 조립
|   +-- XKit/
|   |   +-- DeveloperServices/    기기·앱 ID·인증서·프로파일 관리
|   |   +-- GrandSlam/            비밀번호 인증과 Anisette 보조 처리
|   |   +-- HTTPClientProtocol/   플랫폼별 네트워크 어댑터
|   |   +-- Model/                인증서·키·권한 데이터
|   |   +-- Signer/               프로비저닝과 코드 서명 연결
|   |   +-- Installation/         기기 연결·전송·설치·디버그 서비스
|   |   +-- Integration/          설치 전 과정의 조정자
|   |   +-- Utilities/            저장소·압축·식별자 등 공통 기능
|   +-- XcodeProjects/            Xcode 프로젝트 형식 변환·입출력
|   +-- DeveloperAPI/Generated/   OpenAPI로 생성한 Swift 코드
|   +-- CXKit/                    OpenSSL 등을 잇는 C 코드와 헤더
|   +-- XUtils/                   프로세스·파일·임시 디렉토리 유틸리티
+-- Tests/XToolTests/              Swift Testing 기반 테스트와 보조 코드
+-- Examples/                     단순 앱·자원·동적 라이브러리·확장 사례
+-- integration-tests/            Docker + Bats 통합 테스트
+-- Documentation/xtool.docc/      설치·첫 앱·앱 구조 문서
+-- Linux/                        AppImage 빌드·패키징
+-- macOS/                        안내 앱·XcodeGen 설정·fastlane 배포
+-- .github/workflows/            빌드·검사·통합 테스트·릴리스
+-- Dockerfile                    Linux 빌드 단계와 실행 이미지
+-- Makefile                      개발·패키징·문서·API 생성 작업

5-1. 코드 규모는 생성 코드를 분리해서 읽는다

커밋 952a7ff의 파일을 확장자별로 세면 아래와 같습니다. 빈 줄과 주석을 포함한 물리적 줄 수이며, 외부 의존성 다운로드와 .git 내부는 제외합니다. 이 숫자는 구현 난이도나 기능 수를 직접 나타내지는 않습니다.

Swift 전체의 약 68%가 생성 코드입니다. 처음부터 가장 큰 파일을 펼치면 복잡함을 과대평가하기 쉽습니다. Makefile의 api 타깃과 Sources/DeveloperAPI/openapi-generator-config.yaml을 보면 BundleIds·BundleIdCapabilities·Certificates·Devices·Profiles 태그의 API만 골라 타입과 클라이언트를 생성한다는 사실을 알 수 있습니다.

5-2. 처음 읽을 때의 추천 순서

1. Sources/xtool/XTool.swift → Sources/XToolSupport/XTool.swift: 진입점과 명령 등록을 읽습니다.
2. Sources/XToolSupport/DevCommand.swift: 사용자가 내린 명령을 어떤 서비스에 연결하는지 봅니다.
3. Sources/PackLib/PackSchema.swift → Sources/PackLib/Planner.swift → Sources/PackLib/Packer.swift: 입력·계획·결과물을 순서대로 봅니다.
4. Sources/XKit/Integration/IntegratedInstaller.swift → Sources/XKit/Signer/AutoSigner.swift: 앱이 설치 허가를 얻는 과정을 읽습니다.
5. 관심 있는 권한 하나만 골라 Sources/XKit/Model/Entitlements/에서 Sources/XKit/DeveloperServices/까지 따라갑니다.

6학습 포인트 (기술별)

6-1. SwiftPM: 타깃·제품·실행 파일은 같은 것이 아니다

타깃은 함께 컴파일할 소스의 단위이고, 제품은 패키지 밖에 공개할 결과물입니다. Examples/DemoSimple/Package.swift는 앱 소스를 .library 제품으로 노출합니다. 그런데 최종 결과는 실행 가능한 앱입니다. 이 차이를 연결하는 곳이 Packer.build()입니다.

이 함수는 xtool/.xtool-tmp/Package.swift를 만들어 원래 패키지를 RootPackage라는 로컬 의존성으로 참조합니다. 그리고 이름-App 실행 타깃, 빈 stub.c, 앱 제품에 대한 의존성을 생성합니다. 사용자가 선언한 라이브러리를 앱 실행 파일로 묶기 위한 임시 빌드 패키지입니다.

// Packer.build()가 생성하는 형태를 Hello라는 이름으로 풀어 쓴 예
dependencies: [
    .package(name: "RootPackage", path: "../.."),
],
targets: [
    .executableTarget(
        name: "Hello-App",
        dependencies: [
            .product(name: "Hello", package: "RootPackage"),
        ],
        linkerSettings: [
            .unsafeFlags([
                "-Xlinker", "-rpath", "-Xlinker", "@executable_path/Frameworks",
            ]),
        ]
    ),
]

작은 실습: Sources/XToolSupport/NewCommand.swift의 템플릿에서 제품 이름과 타깃 이름을 찾고, Plan.Product.targetName이 어떤 이름을 추가하는지 종이에 적어 보세요. 제품 이름을 바꾸면 앱 이름·실행 파일 이름 중 무엇이 연결되는지 예상하는 연습입니다.

6-2. 크로스컴파일: 호스트와 대상의 좌표를 분리한다

BuildSettings는 구형 경로에서 --swift-sdk, SwiftBuild 경로에서 --triple을 사용합니다. SwiftVersion.supportsSwiftBuild는 버전이 6.4 이상인지 검사하고, BuildSystem.default()가 그에 따라 기본값을 선택합니다. 새로운 빌드 엔진은 기존 SwiftPM 명령을 통해 선택됩니다.

macOS에서는 xcrun으로 실제 Swift 실행 파일을 찾고, 잘못 상속된 SDKROOT를 제거합니다. Linux의 SwiftBuild 경로에서는 Darwin SDK의 toolset-swb.json과 플랫폼 폴더 환경 변수를 추가합니다. 같은 명령처럼 보여도 운영체제별 준비물이 다른 이유가 여기 있습니다.

작은 실습: 기본 기기 triple과 시뮬레이터 triple을 Packer.cfBundleSupportedPlatforms(for:)에 대입해 결과를 예측하세요. 정답은 Tests/XToolTests/PackerTests.swift에서 비교할 수 있습니다. 시뮬레이터용 바이너리를 만든다는 것과 시뮬레이터를 해당 운영체제에서 실행한다는 것은 다른 문제입니다.

6-3. 구조적 동시성: 작업의 수명과 실패를 함께 다룬다

Planner.buildGraph()는 여러 패키지 설명을 withThrowingTaskGroup으로 읽고, Packer.pack()은 자원·실행 파일·설정 파일 복사를 작업 그룹으로 묶습니다. 독립 작업은 겹쳐 진행할 수 있지만, 그룹 범위를 떠나기 전에 자식 작업의 종료를 기다립니다.

Packer.pack()은 취소 오류와 일반 오류를 구분하고, 일반 오류가 나면 group.cancelAll()을 호출합니다. 실제 파일 복사 뒤에는 Task.checkCancellation()도 있습니다. 비동기 코드를 읽을 때는 무엇이 동시에 진행되는지와 함께, 실패했을 때 누가 끝까지 정리하는지도 확인해야 합니다.

작은 실습: Packer.pack()에서 동시에 실행 가능한 작업과 반드시 앞서 끝나야 하는 작업을 나누어 보세요. 예를 들어 출력 디렉토리는 자원 복사보다 먼저 존재해야 합니다. TemporaryDirectory의 소유권과 persist(at:)까지 연결하면 성공·실패 시 결과물의 수명도 설명할 수 있습니다.

6-4. 코드 서명: 앱의 신원, 허가, 무결성을 구분한다

위 파일은 모두 Sources/XKit/ 아래에 있습니다. AutoSigner.sign(...)은 서버에서 준비한 새 bundle ID를 Info.plist에 반영하고, 프로파일을 삽입한 뒤 서명 구현을 호출합니다. 먼저 컴파일만 하고 나중에 이 단계를 붙일 수 있도록 역할이 분리되어 있습니다.

작은 실습: Signer.Identity의 .adhoc과 .real을 비교해 보세요. PackOperation에서 권한을 담기 위해 사용하는 ad-hoc 서명과 개발 인증서 기반 서명을 구분하면, “서명 비슷한 단계가 있었는데 왜 기기 설치가 안 되는가”를 설명할 수 있습니다.

6-5. 직렬화와 검증: 문자열 설정을 믿을 수 있는 값으로 바꾼다

PackSchemaBase는 YAML의 구조를 표현하고, PackSchema.init(validating:)는 앱 식별자 지정 여부와 아이콘 확장자 등을 검사합니다. bundleID와 orgID가 모두 있으면 전자가 우선합니다. 아이콘 경로는 확장자가 정확히 png인지 확인하지만, 이 검사만으로 실제 이미지 크기까지 검증하는 것은 아닙니다.

Entitlements.updateEntitlements(...)는 인식된 권한을 수정하면서 미해석 키를 보존하도록 설계되어 있습니다. 다만 무료 팀용 재구성 경로는 인식된 권한 목록으로 다시 만들므로 같은 보존 규칙이 적용되지 않습니다. 추상 타입의 일반 동작과 특정 호출부의 정책을 함께 읽어야 하는 사례입니다.

작은 실습: bundleID만 있는 설정, orgID만 있는 설정, 둘 다 없는 설정을 보고 어느 입력이 어떤 결과가 될지 예측하세요. 마지막 입력은 Must specify either orgID or bundleID 오류로 이어집니다.

6-6. 테스트: 작은 함수와 환경 의존 검사를 나눈다

// Tests/XToolTests/PackerTests.swift의 검증 예 발췌
@Test func cfBundleSupportedPlatformsFollowsBuildTriple() {
    #expect(Packer.cfBundleSupportedPlatforms(
        for: "arm64-apple-ios"
    ) == ["iPhoneOS"])
    #expect(Packer.cfBundleSupportedPlatforms(
        for: "arm64-apple-ios-simulator"
    ) == ["iPhoneSimulator"])
}

Tests/XToolTests/SwiftVersionTests.swift는 다양한 버전 문자열과 잘못된 입력을 @Test(arguments:)로 검증합니다. Tests/XToolTests/RequiresXcodeTrait.swift는 Xcode 경로를 요구하는 테스트의 환경을 별도로 준비합니다. integration-tests/suite/smoke.bats는 새 앱의 빌드 결과에 iOS용 Mach-O 정보가 있는지도 검사합니다. 단위 테스트와 통합 테스트가 서로 다른 실패를 잡는 구체적인 예입니다.

7하드웨어 / 시스템 요구사항

소스와 설정을 읽는 학습에는 Apple 계정이나 아이폰이 필요하지 않습니다. 앱을 빌드하려면 Swift와 Apple SDK가, 실제 기기 설치에는 인증과 연결이 추가로 필요합니다. 저장소는 공식 최소 RAM·CPU 코어 수·디스크 용량을 제시하지 않습니다.

7-1. 세 종류의 “최소 버전”을 혼동하지 않기

Package.swift의 도구 버전 6.2는 xtool 자체를 소스에서 빌드할 때 적용되는 매니페스트 조건입니다. 새 앱 템플릿의 도구 버전은 6.0입니다. Linux 설치 문서는 Swift 6.4를 요구하고, Docker는 6.4.1을 선택합니다. Sources/PackLib/BuildSettings.swift에도 Linux 플랫폼 도구 모음 수정과 빌드 서버 옵션 때문에 6.4가 필요하다는 설명이 있습니다.

패키지가 선언한 버전, 호스트 도구에 필요한 버전, 앱이 실행될 운영체제 버전은 서로 다른 조건입니다. macOS 설치 문서의 Swift 6.1 출력은 설치 확인용 예시입니다. xtool 자체의 소스 빌드 조건과, 배포된 xtool로 앱을 빌드할 때의 조건은 나누어 읽어야 합니다.

Planner는 앱 패키지의 iOS 버전을 사용하고, 없으면 내부 기본값 13.0을 사용합니다. 이 대체값은 모든 앱이 iOS 13에서 동작한다는 보증이 아닙니다. 새 프로젝트는 iOS 17을 선언하며, 앱이 쓰는 API와 의존성도 하한에 영향을 줍니다.

7-2. 메모리·디스크 계획은 공식 하한과 구별하기

실습 준비용 예산으로는 RAM 16GB와 여유 디스크 수십 GB를 잡으면 출발하기 편합니다. 이는 공식 최소 사양이나 성능 측정값이 아닌 학습용 권장 여유입니다. SDK 압축 해제, Swift 의존성, 빌드 캐시가 차지하는 용량은 사용하는 Xcode와 프로젝트 크기에 따라 달라집니다. GPU는 이 CLI의 필수 요구사항으로 선언되어 있지 않습니다.

SDKBuilder.Mode의 buildSlim은 필요한 파일 중심의 SDK를 만들고, 일반 모드는 Xcode 개발 디렉토리의 복사본을 유지해 갱신 경로를 지원합니다. DarwinSDK.Flavor.slim은 제자리 갱신을 지원하지 않습니다. 공간 절약과 업데이트 방식 사이의 선택입니다.

7-3. Docker와 시뮬레이터의 범위

docker-compose.yml은 로컬 소스와 빌드 캐시를 마운트하고, Dockerfile의 dev 단계는 호스트의 usbmuxd 연결을 사용하는 구성을 제시합니다. 컨테이너에서도 USB 연결은 별도로 준비해야 합니다. 개발·빌드 단계의 기반은 Ubuntu 22.04(jammy)이고 Linux 빌드 CI의 실행 호스트는 Ubuntu 24.04입니다. 최종 배포 단계는 swift:6.4.1 이미지를 사용하며 배포판 접미사를 명시하지 않습니다.

DevRunCommand의 --simulator와 SimInstallOperation은 #if os(macOS) 안에 있습니다. 구현은 xcrun simctl install을 사용합니다. Linux에서 시뮬레이터용 대상을 빌드하는 능력과 Apple 시뮬레이터를 Linux에서 실행하는 능력을 같은 것으로 해석하지 마세요.

8직접 해볼 수 있는 실습 과제

처음 두 과제는 소스 열람만으로 완수할 수 있습니다. 이후 과제는 공식 개발 환경을 준비한 독자가 별도 연습용 프로젝트에서 수행하는 제안입니다. 아래 명령은 실습용 예시입니다. SDK와 기기·계정 조건은 각 과제에 맞게 준비하세요.

# 서로 독립적인 네 설정 사례
# A: version: 1, bundleID: com.study.Exact
# B: version: 1, orgID: com.study
# C: version: 1, bundleID와 orgID 모두 없음
# D: version: 1, orgID: com.study, iconPath: Icon.jpg

# 연습용 프로젝트의 xtool.yml
version: 1
bundleID: com.study.Hello
resources:
  - Resources/top.txt

# 환경을 갖춘 뒤 실행할 명령
xtool dev build
find xtool/Hello.app -maxdepth 3 -type f

# 테스트 입력 plist의 dict 안에 들어갈 조각
<key>com.apple.developer.applesignin</key>
<array>
    <string>Default</string>
</array>

실습의 성공 기준은 명령이 끝났다는 사실보다, 결과 파일과 그 파일을 만든 코드의 분기를 연결해 설명하는 데 있습니다. 기기 설치를 추가로 시도할 때도 앱 조립, 서명, 연결, 설치를 따로 기록하면 문제를 좁히기 쉽습니다.

9관련 기술 심화 학습 로드맵

매주 새로운 도구를 설치하기보다, 같은 앱이 지나가는 경계를 하나씩 넓혀 보세요. Swift 문법을 처음 접했다면 1주차를 두 주로 늘려도 됩니다. 기기 설치를 하지 않는 독자는 마지막까지 입력과 예상 결과를 표로 만드는 방식으로 따라갈 수 있습니다.

9-1. 막힐 때 돌아갈 질문

• Swift 문법이 어렵다면: 이 값은 없을 수 있는가, 바뀌는가, 다른 작업과 공유되는가를 먼저 적습니다. 각각 옵셔널, var, 동시성 경계와 연결됩니다.
• 빌드가 어렵다면: 입력은 소스인가, 설정인가, SDK인가를 분리합니다. 결과도 실행 파일, .app, .ipa 중 어느 단계인지 정합니다.
• 인증이 어렵다면: 계정 로그인, 인증서 발급, 앱 기능 등록, 코드 서명을 각각 한 문장으로 설명해 봅니다.
• 코드가 너무 크다면: 생성 파일보다 호출부의 입력·출력 타입을 먼저 봅니다. 큰 타입 정의를 전부 읽는 대신 현재 사용하는 필드만 추적합니다.

9-2. 최종 복습: 같은 요청을 다른 방식으로 구현한다면

마지막에는 Plan을 다른 출력으로 바꿔 보는 설계가 좋습니다. 사람이 읽는 미리보기 표, JSON 보고서, 다른 빌드 경로 중 하나를 고르고 어떤 데이터를 더 담아야 할지 적어 보세요. 현재 구조가 무엇을 쉽게 만들고, 어떤 부분은 아직 직접 호출에 묶여 있는지 드러납니다.

학습의 마지막 결과물은 기능 이름의 목록보다, 새로운 요구를 어느 경계에 넣을지 설명할 수 있는 설계도여야 합니다. 그 설명에 함수 이름과 실패 조건까지 붙으면 다른 개발 도구의 소스를 읽을 때도 같은 방법을 사용할 수 있습니다.

10핵심 키워드 사전

11참고 링크

11-1. 공식 저장소·사용 문서

• xtool 공식 저장소 — 프로젝트 소개, 이슈, 기여 경로
• xtool 공식 문서 — 설치와 일반 사용법
• Linux·Windows 설치 안내 — WSL, Swift, usbmuxd, SDK 준비
• macOS 설치 안내 — Xcode SDK, 앱 번들, CLI 연결
• 첫 앱 튜토리얼 — 기기 신뢰·개발자 모드와 설치 흐름
• 릴리스 1.23.0 — 2026-10-22 공개 버전
• GitHub Trending Swift Weekly — 순위가 시간에 따라 달라지는 주간 목록

11-2. 설명에 연결되는 소스

• Package.swift · Package.resolved — 의존성 범위와 정확한 선택 버전
• DevCommand.swift — 빌드·서명·설치 분기와 시뮬레이터 경계
• Planner.swift · Packer.swift — 의존성 그래프, Plan, 임시 패키지와 앱 조립
• BuildSettings.swift · SDKBuilder.swift — SwiftBuild 선택과 SDK 구성
• IntegratedInstaller.swift · AutoSigner.swift — 프로비저닝부터 설치까지
• DeveloperServicesCapability.swift — Sign in with Apple을 포함한 권한·기능 연결
• WiFiAwareEntitlementTests.swift — 권한 해석·매핑·왕복 변환 테스트의 본보기
• 빌드 CI · 릴리스 CI · Dockerfile — 플랫폼과 배포물의 연결

11-3. 관련 기술의 공식 학습 경로

• Swift 언어 가이드 — 기본 문법, 오류 처리, 동시성
• Swift Package Manager · Swift SDK Generator — 패키지 빌드와 크로스컴파일 SDK의 배경
• Swift Build — 빌드 엔진의 구현과 별도 학습 경로
• Swift Argument Parser · swift-dependencies — CLI 선언과 의존성 교체
• Swift OpenAPI Generator · Swift Testing — 생성 클라이언트와 테스트
• Apple entitlement 문서 · App Store Connect API — 앱 권한과 개발자 서비스
• Xcode 공식 소개 · fastlane 공식 저장소 — 비교 대상의 기능 범위
• libimobiledevice · WSL의 USB 연결 안내 — 기기 통신 기반과 Windows 연결 경로

현재 상태 (2026-10-23 확인)

릴리스 1.23.0과 분석 커밋은 같은 대상을 뜻하지 않습니다. 특히 10월 23일의 Apple 로그인 권한 지원이 10월 22일 릴리스에 포함됐다고 이 표만으로 판단할 수 없습니다. 워크플로가 정의되어 있다는 사실도 모든 실행이 통과했다는 의미는 아닙니다.