Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions Documentation/Contributing/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,12 @@ After building, a symlink to the product will be created at `./macOS/Build/xtool

You need to have a few dependencies on Linux; see [Dockerfile](/Dockerfile) for specifics. It's often easiest to develop within Docker itself: see [Linux/README.md](/Linux/README.md) for details.

With an installed Darwin Swift SDK, `integration-tests/check-catalyst-sdk.sh <Catalyst SDK root>`
checks the documented direct SwiftPM framework options. Use the absolute SDK root reported by
`xtool sdk status --triple arm64-apple-ios-macabi`. The probe compiles a UIKit Swift overlay API;
it does not link or run an app. Additional arguments are passed to `swift build`, including
`--swift-sdks-path` when testing an isolated SDK directory.

## Debugging

Check out [./Debugging.md](./Debugging.md) for help with debugging xtool issues during development.
Expand Down
77 changes: 76 additions & 1 deletion Documentation/xtool.docc/Control.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,80 @@ bundleID: com.example.Hello
EOF
```

## Select the target platform

`xtool dev build` accepts a target triple for iOS, tvOS, macOS, or Mac Catalyst:

| Platform | Example target triple | Swift package deployment platform |
| --- | --- | --- |
| iOS | `arm64-apple-ios` | `.iOS("17.0")` |
| tvOS | `arm64-apple-tvos` | `.tvOS("17.0")` |
| macOS | `arm64-apple-macosx` | `.macOS("14.0")` |
| Mac Catalyst | `arm64-apple-ios-macabi` | `.macCatalyst("17.0")` and `.macOS("14.0")` |

For example:

```bash
xtool sdk status --triple arm64-apple-tvos
xtool dev build --configuration release --triple arm64-apple-tvos
```

The status command fails if the installed Darwin SDK lacks that target or its SDK directory.
Add `--build-metadata` to print the recorded SDK, platform, and Xcode build values as JSON.
Rebuild an older Darwin SDK to add the new target definitions. tvOS targets are included only when
the supplied Xcode installation contains the corresponding Apple TV SDKs. Mac Catalyst uses the
MacOSX SDK and its `System/iOSSupport` framework, header, and library paths. The SDK artifact retains
Xcode's `Contents/version.plist` as `xcode-version.plist` for consumers that need build provenance.
Linux builds stamp SDK, platform, and Xcode `DT*` values from those retained SDK metadata files into
the app and its extensions. Missing required provenance causes an error instead of fabricated build values.
Its `.macCatalyst` deployment version controls compilation; `.macOS` supplies the separate
`LSMinimumSystemVersion` value in the bundle's `Info.plist`.

For Catalyst, use `xtool dev build` to supply the framework search paths as well as the generated
Swift SDK's header and library paths. A direct `swift build --swift-sdk darwin` invocation needs
explicit framework options. Swift SDK metadata schema 4 does not represent framework search paths,
and Swift 6.4.1 does not add the SDK's `System/iOSSupport` frameworks automatically. Without these
options, even `import UIKit` fails. For a direct SwiftPM library build, set `catalyst_sdk` to the
absolute `SDK root` printed by `xtool sdk status --triple arm64-apple-ios-macabi`, then run:

```bash
catalyst_frameworks="$catalyst_sdk/System/iOSSupport/System/Library/Frameworks"
swift build --build-system native --swift-sdk darwin --triple arm64-apple-ios-macabi \
-Xswiftc -F -Xswiftc "$catalyst_frameworks" \
-Xcc -F -Xcc "$catalyst_frameworks" \
-Xlinker "-F$catalyst_frameworks"
```

The Swift compiler needs its own framework option to load Swift overlays. Passing a framework path
only to Clang can expose Objective-C declarations while leaving Swift-only APIs unavailable. Direct
SwiftPM executable builds also need a compatible linker; the xtool linker override below applies
to `xtool dev build`.

`xtool dev build --print-supported-platforms` prints the platform names without building or requiring
an installed SDK. This reports xtool's packaging capabilities; use the SDK status command to check
the SDKs actually available on a machine.

Linux builds explicitly pass the recorded SDK version to the linker so the executable's
`LC_BUILD_VERSION` reports the SDK used to build it, independently of the minimum deployment version.
Mac Catalyst on Linux requires LLD 23 or newer to handle arm64e macOS libraries reexported by the
Apple SDK. Set `XTOOL_LD64_LLD` to an absolute path to an updated `ld64.lld` executable to override
the installed toolset's linker. The SDK status command checks this prerequisite for Catalyst targets.

macOS and Mac Catalyst produce a `YourApp.app/Contents` bundle with `MacOS`, `Resources`, `Frameworks`,
and `PlugIns` directories as needed. Their `Info.plist` is in `Contents`. When entitlements are configured,
xtool applies them with an ad hoc signature. Sign with an appropriate identity separately. `--ipa` and
automatic development signing are unavailable for these bundles. Automatic development signing remains limited to iOS.

macOS and Mac Catalyst apps with Swift package resource bundles require SwiftBuild, selected
automatically with Swift 6.4 or newer. Native SwiftPM builds of these apps fail with a diagnostic
because their generated `Bundle.module` accessor cannot find resources in `Contents/Resources`.
This restriction includes package resources used only by an app extension. Desktop apps without
package resource bundles, including those with only `xtool.yml` resources, can use native SwiftPM.

These target and bundle rules do not add an Xcode project importer, an asset-catalog compiler, or an
App Store distribution workflow. Target-specific frameworks, compiled resources, signing, and store
acceptance still require validation with the actual Apple SDK and destination platform.

## Change your bundle ID

You can update your app's bundle ID by editing the `bundleID` field in `xtool.yml`.
Expand Down Expand Up @@ -94,7 +168,8 @@ resources:
- Resources/GoogleServices-Info.plist
```

The file will be copied to `Hello.app/GoogleServices-Info.plist`.
The file will be copied to `Hello.app/GoogleServices-Info.plist`, or to
`Hello.app/Contents/Resources/GoogleServices-Info.plist` for macOS and Mac Catalyst.

## Add an app icon

Expand Down
103 changes: 103 additions & 0 deletions Sources/PackLib/ApplePlatform.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
import Foundation

package enum ApplePlatform: String, CaseIterable, Sendable {
case iOS
case tvOS
case macOS
case macCatalyst

package init?(triple: String) {
let components = triple.split(separator: "-")
guard components.count >= 3, components[1] == "apple" else { return nil }
let os = components[2].prefix { !$0.isNumber }
switch os {
case "ios": self = components.contains("macabi") ? .macCatalyst : .iOS
case "tvos": self = .tvOS
case "macos", "macosx": self = .macOS
default: return nil
}
}

package init(validatingTriple triple: String) throws {
guard let platform = Self(triple: triple) else {
let supported = Self.allCases.map(\.rawValue).joined(separator: ", ")
throw StringError("Unsupported target triple '\(triple)'. Supported platforms: \(supported).")
}
self = platform
}

package var usesContentsDirectory: Bool {
self == .macOS || self == .macCatalyst
}

package var packagePlatformName: String {
rawValue.lowercased()
}

package var minimumDeploymentTarget: String {
self == .macOS ? "10.15" : "13.0"
}

package func effectiveDeploymentTarget(
platforms: [String: String], swiftVersion: SwiftVersion, sdkMinimum: String?, tripleMinimum: String? = nil
) -> String {
let declared = platforms[packagePlatformName] ?? (self == .macCatalyst ? platforms["ios"] : nil)
// Match PackageModel.Platform.oldestSupportedVersion in SwiftPM 6.4.
let toolchainMinimum = swiftVersion >= SwiftVersion(6, 4)
? (self == .macOS ? "12.0" : "15.0") : minimumDeploymentTarget
return [declared, toolchainMinimum, sdkMinimum, tripleMinimum].compactMap { $0 }.max {
$0.compare($1, options: .numeric) == .orderedAscending
} ?? toolchainMinimum
}

package func supportedPlatform(triple: String) -> String {
let simulator = triple.split(separator: "-").contains("simulator")
switch self {
case .iOS: return simulator ? "iPhoneSimulator" : "iPhoneOS"
case .tvOS: return simulator ? "AppleTVSimulator" : "AppleTVOS"
case .macOS, .macCatalyst: return "MacOSX"
}
}

package func buildProductsPlatform(triple: String) -> String {
if self == .macCatalyst { return "maccatalyst" }
return supportedPlatform(triple: triple).lowercased()
}

package func linkerPlatform(triple: String) -> String {
let simulator = triple.split(separator: "-").contains("simulator")
switch self {
case .iOS: return simulator ? "ios-simulator" : "ios"
case .tvOS: return simulator ? "tvos-simulator" : "tvos"
case .macOS: return "macos"
case .macCatalyst: return "mac-catalyst"
}
}

package func contentsDirectory(in bundle: URL) -> URL {
usesContentsDirectory ? bundle.appendingPathComponent("Contents", isDirectory: true) : bundle
}

package func resourcesDirectory(in bundle: URL) -> URL {
let contents = contentsDirectory(in: bundle)
return usesContentsDirectory ? contents.appendingPathComponent("Resources", isDirectory: true) : contents
}

package func executableDirectory(in bundle: URL) -> URL {
let contents = contentsDirectory(in: bundle)
return usesContentsDirectory ? contents.appendingPathComponent("MacOS", isDirectory: true) : contents
}

package func additionalSDKOptions(sdkRoot: URL) -> [String] {
guard self == .macCatalyst else { return [] }
let support = sdkRoot.appendingPathComponent("System/iOSSupport")
let frameworks = support.appendingPathComponent("System/Library/Frameworks").path
return [
"-Xswiftc", "-Fsystem", "-Xswiftc", frameworks,
"-Xcc", "-isystem", "-Xcc", support.appendingPathComponent("usr/include").path,
"-Xcc", "-iframework", "-Xcc", frameworks,
"-Xlinker", "-F\(frameworks)",
"-Xlinker", "-L\(support.appendingPathComponent("usr/lib").path)",
]
}
}
63 changes: 60 additions & 3 deletions Sources/PackLib/BuildSettings.swift
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,33 @@ public struct BuildSettings: Sendable {
public let triple: String
public let buildSystem: BuildSystem
public let customOptions: [String]
package let platform: ApplePlatform

package var sdkTriple: String {
Self.sdkTriple(for: triple)
}

package static func sdkTriple(for triple: String) -> String {
var components = triple.split(separator: "-").map(String.init)
guard components.count >= 3 else { return triple }
let os = String(components[2].prefix { !$0.isNumber })
// Swift SDKs register macOS targets under the canonical "macosx" name.
components[2] = os == "macos" ? "macosx" : os
return components.joined(separator: "-")
}

package var tripleDeploymentTarget: String? {
let components = triple.split(separator: "-")
guard components.count >= 3 else { return nil }
let version = components[2].drop { !$0.isNumber }
return version.isEmpty ? nil : String(version)
}

package func triple(deploymentTarget: String) -> String {
var components = sdkTriple.split(separator: "-").map(String.init)
components[2] += deploymentTarget
return components.joined(separator: "-")
}

public var sdkOptions: [String]
public var sdkEnvironment: [Environment.Key: String?]
Expand Down Expand Up @@ -40,6 +67,7 @@ public struct BuildSettings: Sendable {
self.configuration = configuration
self.customOptions = options
self.triple = triple
self.platform = try ApplePlatform(validatingTriple: triple)
self.buildSystem = if let buildSystem { buildSystem } else { try await .default() }

self.sdkEnvironment = [
Expand All @@ -54,14 +82,20 @@ public struct BuildSettings: Sendable {
// i.e. we can pass `--swift-sdk arm64-apple-ios` and it
// just works. See:
// https://github.com/swiftlang/swift-package-manager/pull/6828
self.sdkOptions = ["--swift-sdk", triple]
self.sdkOptions = ["--swift-sdk", Self.sdkTriple(for: triple)]
case .swiftBuild:
self.sdkOptions = ["--triple", triple]
self.sdkOptions = [
"--triple", triple,
// Match the native toolset: SwiftUI integration APIs such as PhotosPicker live in cross-import overlays.
"-Xswiftc", "-Xfrontend", "-Xswiftc", "-enable-cross-import-overlays",
]
#if !os(macOS)
let darwinSDK = try DarwinSDK.current()
.orThrow(StringError("No Darwin SDK configured. Please run `xtool setup`."))
let toolset = try LinkerConfiguration.toolsetOverride(sdk: darwinSDK)
?? darwinSDK.bundle.appendingPathComponent("toolset-swb.json")
self.sdkOptions += [
"--toolset", "\(darwinSDK.bundle.path)/toolset-swb.json",
"--toolset", toolset.path,
]
self.sdkEnvironment.merge([
"XCODE_EXTRA_PLATFORM_FOLDERS": "\(darwinSDK.bundle.path)/Developer/Platforms",
Expand All @@ -70,6 +104,29 @@ public struct BuildSettings: Sendable {
]) { $1 }
#endif
}

if platform == .macCatalyst {
if let sdkRoot = try await sdkRootURL() {
self.sdkOptions += platform.additionalSDKOptions(sdkRoot: sdkRoot)
}
}
#if !os(macOS)
if let darwinSDK = try DarwinSDK.current() {
try await LinkerConfiguration.validate(platform: platform, sdk: darwinSDK)
if self.buildSystem == .swiftPM, let toolset = try LinkerConfiguration.toolsetOverride(sdk: darwinSDK) {
self.sdkOptions += ["--toolset", toolset.path]
}
}
#endif
}

package func sdkRootURL() async throws -> URL? {
#if os(macOS)
let sdkName = platform.supportedPlatform(triple: triple).lowercased()
return URL(fileURLWithPath: try await Self.xcrun(["--sdk", sdkName, "--show-sdk-path"]))
#else
return try DarwinSDK.current()?.sdkRoot(for: sdkTriple)
#endif
}

#if os(macOS)
Expand Down
21 changes: 21 additions & 0 deletions Sources/PackLib/DarwinSDK.swift
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,27 @@ public struct DarwinSDK {
return DarwinSDK(bundle: bundle)
}

public func sdkRoot(for triple: String) throws -> URL {
struct Definition: Decodable {
struct Target: Decodable {
let sdkRootPath: String
}
let targetTriples: [String: Target]
}
let data = try Data(contentsOf: bundle.appendingPathComponent("swift-sdk.json"))
let definition = try JSONDecoder().decode(Definition.self, from: data)
guard let target = definition.targetTriples[triple] else {
throw StringError("""
The installed Darwin SDK does not contain target '\(triple)'. Rebuild it with the required platform SDK.
""")
}
let root = bundle.appendingPathComponent(target.sdkRootPath, isDirectory: true)
guard root.dirExists else {
throw StringError("The installed Darwin SDK is missing the SDK root for '\(triple)': '\(root.path)'")
}
return root
}

public func remove() throws {
try FileManager.default.removeItem(at: bundle)
}
Expand Down
Loading