Skip to content

Commit 6bce2b7

Browse files
MattKiazykMattKiazyk
committed
documentation
1 parent 4489a08 commit 6bce2b7

23 files changed

Lines changed: 508 additions & 1 deletion

‎README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,22 @@ Then depend on the library product from your target:
2121
.product(name: "XcodesKit", package: "XcodesKit")
2222
```
2323

24+
## API Documentation
25+
26+
XcodesKit includes a DocC catalog at `Sources/XcodesKit/Documentation.docc`.
27+
Open the package in Xcode and choose **Product > Build Documentation** to browse the public API grouped by workflow.
28+
29+
The main entry points are:
30+
31+
- `XcodeListService` for loading Xcode release metadata from Apple or Xcode Releases.
32+
- `InstalledXcodeDiscoveryService` for reading installed Xcode bundles.
33+
- `XcodeListComposer` and `XcodeListPresentationService` for building UI-ready Xcode lists.
34+
- `XcodeArchiveService`, `XcodeArchiveInstallService`, and `XcodeUnarchiveService` for archive download and install workflows.
35+
- `XcodeSelectionService` for selecting an installed Xcode.
36+
- `RuntimeService` and the runtime install services for simulator runtime discovery and installation.
37+
38+
Most services provide default initializers for real network, filesystem, and shell behavior, plus closure-based initializers for tests and host-app integration.
39+
2440
## Development
2541

2642
Build the package:

‎Sources/XcodesKit/Documentation.docc/XcodesKit.md‎

Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
# ``XcodesKit``
2+
3+
Build Xcode and simulator-runtime management features into Swift apps and tools.
4+
5+
## Overview
6+
7+
XcodesKit is the shared package behind XcodesOrg apps. It exposes models and services for discovering available Xcode releases, reading local installations, choosing an installed Xcode, downloading and installing archives, uninstalling Xcode bundles, and managing simulator runtimes.
8+
9+
Most API is organized around small `Sendable` service types. Default initializers use the real network, filesystem, and shell implementations. Initializers that accept closures are intended for tests, previews, and host applications that need to control side effects.
10+
11+
```swift
12+
import XcodesKit
13+
14+
let listService = XcodeListService()
15+
let releases = try await listService.availableXcodes(from: .default)
16+
```
17+
18+
### Common Workflows
19+
20+
Use ``XcodeListService`` to load release metadata from Apple or Xcode Releases.
21+
22+
```swift
23+
let service = XcodeListService()
24+
let xcodes = try await service.availableXcodes(from: .xcodeReleases)
25+
26+
let latest = xcodes.first
27+
```
28+
29+
Use ``InstalledXcodeDiscoveryService`` to read Xcode bundles from a directory.
30+
31+
```swift
32+
let discovery = InstalledXcodeDiscoveryService()
33+
let installed = discovery.installedXcodes(in: "/Applications")
34+
```
35+
36+
Use ``XcodeListComposer`` to combine available releases, installed bundles, and selection state into UI-ready list items.
37+
38+
```swift
39+
let items = XcodeListComposer().compose(
40+
availableXcodes: available,
41+
installedXcodes: installed,
42+
selectedXcodePath: selectedPath,
43+
existingXcodes: previousItems,
44+
dataSource: .xcodeReleases
45+
)
46+
```
47+
48+
Use ``XcodeSelectionService`` to resolve a user-entered path, version string, or `.xcode-version` file into a selection request.
49+
50+
```swift
51+
let request = XcodeSelectionService().request(
52+
pathOrVersion: "15.4",
53+
installedXcodes: installed,
54+
selectedXcodePath: selectedPath
55+
)
56+
```
57+
58+
Use ``RuntimeService`` and the runtime installation services to list, download, and install simulator runtimes.
59+
60+
```swift
61+
let runtimeService = RuntimeService()
62+
let response = try await runtimeService.downloadableRuntimes()
63+
let installed = try await runtimeService.installedRuntimes()
64+
```
65+
66+
### Working With Side Effects
67+
68+
Many services accept closure dependencies so public API consumers can inject their own network, filesystem, or shell behavior.
69+
70+
```swift
71+
let service = XcodeListService { request in
72+
let data = try fixtureData(for: request)
73+
return (data, URLResponse())
74+
}
75+
```
76+
77+
For package-wide test hooks, use ``configureXcodesKitFileContents(_:)`` and ``configureXcodesKitArchs(_:)`` to replace file and architecture lookup behavior.
78+
79+
## Topics
80+
81+
### Release Discovery
82+
83+
- ``XcodeListService``
84+
- ``DataSource``
85+
- ``XcodeListDataSource``
86+
- ``XcodeListStore``
87+
- ``AvailableXcodeCache``
88+
- ``XcodeListComposer``
89+
- ``XcodeListPresentationService``
90+
- ``XcodeListItem``
91+
- ``XcodeListFilters``
92+
- ``XcodeListVersionFilter``
93+
- ``XcodeMajorVersionGroup``
94+
- ``XcodeMinorVersionGroup``
95+
- ``XcodeListElementMajorVersionGroup``
96+
- ``XcodeListElementMinorVersionGroup``
97+
98+
### Xcode Models
99+
100+
- ``AvailableXcodeRelease``
101+
- ``AvailableXcode``
102+
- ``InstalledXcode``
103+
- ``XcodeID``
104+
- ``XcodeInstallState``
105+
- ``XcodeInstallationStep``
106+
- ``XcodeBundleInfo``
107+
- ``InfoPlist``
108+
- ``VersionPlist``
109+
- ``AutoInstallationType``
110+
- ``SelectedActionType``
111+
112+
### Xcode Release Metadata
113+
114+
- ``XcodeRelease``
115+
- ``XcodeVersion``
116+
- ``V``
117+
- ``Release``
118+
- ``Architecture``
119+
- ``ArchitectureVariant``
120+
- ``ArchitectureFilter``
121+
- ``SDKs``
122+
- ``Compilers``
123+
- ``Checksums``
124+
- ``Link``
125+
- ``Links``
126+
- ``YMD``
127+
- ``Downloads``
128+
- ``Download``
129+
- ``ByteCount``
130+
131+
### Installation And Archives
132+
133+
- ``XcodeArchiveService``
134+
- ``XcodeArchive``
135+
- ``XcodeArchiveDownloader``
136+
- ``XcodeInstallResolutionService``
137+
- ``XcodeInstallRequest``
138+
- ``XcodeInstallResolution``
139+
- ``XcodeInstallResolutionError``
140+
- ``XcodeArchiveInstallService``
141+
- ``XcodeArchiveInstallStep``
142+
- ``XcodeArchiveInstallError``
143+
- ``XcodeUnarchiveService``
144+
- ``XcodeUnarchiveStep``
145+
- ``XcodeUnarchiveError``
146+
- ``XcodeInstallRetryService``
147+
- ``XcodeUpdatePolicy``
148+
- ``XcodeAutoInstallService``
149+
- ``XcodeAutoInstallDecision``
150+
- ``XcodeCompatibilityService``
151+
- ``XcodeCompatibilityStatus``
152+
- ``XcodeValidationService``
153+
- ``XcodeValidationError``
154+
- ``XcodeSignatureVerifier``
155+
- ``XcodeSignature``
156+
157+
### Post-Install And Selection
158+
159+
- ``InstalledXcodeDiscoveryService``
160+
- ``XcodePostInstallWorkflowService``
161+
- ``XcodePostInstallPreparationService``
162+
- ``XcodePostInstallService``
163+
- ``XcodeSelectionService``
164+
- ``XcodeSelectionRequest``
165+
- ``XcodeSelectionError``
166+
- ``XcodeSelectionFilesystemService``
167+
- ``XcodeSelectionFilesystemError``
168+
- ``XcodeUninstallService``
169+
- ``XcodesPathResolver``
170+
- ``XcodeVersionFileService``
171+
172+
### Runtime Discovery And Installation
173+
174+
- ``RuntimeService``
175+
- ``DownloadableRuntimesResponse``
176+
- ``DownloadableRuntime``
177+
- ``InstalledRuntime``
178+
- ``RuntimeInstallState``
179+
- ``RuntimeInstallationStep``
180+
- ``RuntimeListStore``
181+
- ``RuntimeListPresentationService``
182+
- ``RuntimeInstallationLookupService``
183+
- ``RuntimeInstallPolicy``
184+
- ``RuntimeInstallMethod``
185+
- ``RuntimeInstallPolicyError``
186+
- ``RuntimeArchiveService``
187+
- ``RuntimeArchiveDownloadStrategyService``
188+
- ``RuntimeArchiveInstallService``
189+
- ``RuntimeArchiveInstallError``
190+
- ``RuntimePackageInstallService``
191+
- ``RuntimeXcodebuildInstallService``
192+
- ``XcodebuildRuntimeDownloadService``
193+
- ``DownloadableRuntimeCache``
194+
- ``CoreSimulatorPlist``
195+
- ``CoreSimulatorImage``
196+
- ``CoreSimulatorRuntimeInfo``
197+
- ``SDKToSeedMapping``
198+
- ``SDKToSimulatorMapping``
199+
- ``makeRuntimeVersion(for:betaNumber:)``
200+
201+
### Downloads, Files, And Shell
202+
203+
- ``ArchiveDownloadService``
204+
- ``ArchiveDownloadStrategyService``
205+
- ``Aria2DownloadService``
206+
- ``Aria2CError``
207+
- ``ArchiveCancellationCleanupService``
208+
- ``CodableFileStore``
209+
- ``ApplicationSupportMigrationService``
210+
- ``HostHardware``
211+
- ``XcodesShell``
212+
- ``XcodesProcess``
213+
- ``ProcessOutput``
214+
- ``ProcessExecutionError``
215+
216+
### Progress And Concurrency
217+
218+
- ``ProgressObservation``
219+
- ``ProgressObservedProperty``
220+
- ``OneShotContinuation``
221+
- ``attemptRetryableTask(_:maxAttempts:shouldRetry:onRetry:)``
222+
- ``attemptResumableTask(_:maxAttempts:onRetry:)``
223+
224+
### Environment And Errors
225+
226+
- ``XcodesKitEnvironment``
227+
- ``XcodesKitFiles``
228+
- ``configureXcodesKitFileContents(_:)``
229+
- ``configureXcodesKitArchs(_:)``
230+
- ``XcodesKitError``

0 commit comments

Comments
 (0)