Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.
Swift apple-silicond3dmetaldxmtdxvkfexgame-porting-toolkitgamingmac-gamingmacosmetalmoltenvksteamswiftuivkd3d-protonwhisky-alternativewindows-gameswinewine-wrapper
Follow Wine reparse points: turn installer junctions into host symlinks
Gauthier Piarrette6c525d4776e6
diff --git a/Sources/HighballKit/Recipe.swift b/Sources/HighballKit/Recipe.swiftindex 4e062cc..cf697de 100644--- a/Sources/HighballKit/Recipe.swift+++ b/Sources/HighballKit/Recipe.swift@@ -303,6 +303,11 @@ public struct RecipeRunner: Sendable {if result.exitStatus != 0 {log?("[\(recipe.id)] \(label) exited with \(result.exitStatus)\(WineRunner.exitCodeNote(for: result.exitStatus)) — treating as done")}+ // Junctions the installer made (EA app: EA Desktop\EA Desktop → a versioned folder)+ // are stubs nothing follows until they are host symlinks.+ for link in WineReparsePoint.materializeTree(under: bottle.driveC, driveC: bottle.driveC) {+ log?("[\(recipe.id)] linked \(link.lastPathComponent) (a Windows junction the installer made, as a symlink)")+ }case let .registry(key, name, type, data):try await runner.regAdd(key: key, name: name, type: type, data: data)case let .winetricks(verbs, _):diff --git a/Sources/HighballKit/WineReparsePoint.swift b/Sources/HighballKit/WineReparsePoint.swiftnew file mode 100644index 0000000..80734ce--- /dev/null+++ b/Sources/HighballKit/WineReparsePoint.swift@@ -0,0 +1,188 @@+import Foundation+import Darwin++/// Wine's on-disk form of an NTFS reparse point, and how to make it usable.+///+/// When a Windows installer creates a directory junction or symbolic link, this Wine+/// (10+, CrossOver 26) leaves an empty directory named after the link plus a trailing `?`,+/// with the raw REPARSE_DATA_BUFFER in the `user.WINEREPARSE` extended attribute. Nothing on+/// the host follows that, and Wine itself did not resolve it either: the EA app's installer+/// makes one for `EA Desktop\EA Desktop`, and the client behind it was "not there" both to+/// Highball and to programs inside the bottle. A real host symlink is followed by both, so this+/// turns such stubs into symlinks, after installs and on demand when a path is missing.+public enum WineReparsePoint {+ public static let attribute = "user.WINEREPARSE"+ /// IO_REPARSE_TAG_SYMLINK and IO_REPARSE_TAG_MOUNT_POINT (a junction).+ static let symlinkTag: UInt32 = 0xA000_000C+ static let mountPointTag: UInt32 = 0xA000_0003+ /// Stubs whose name is taken by the link are moved aside under this prefix.+ static let asidePrefix = ".wine-reparse-"++ public struct Decoded: Equatable, Sendable {+ public var tag: UInt32+ /// The substitute name as Windows wrote it: `13.783.0.6296\EA Desktop` (relative) or `\??\C:\…`.+ public var target: String+ public var isRelative: Bool+ }++ // MARK: Reading++ /// Decodes a REPARSE_DATA_BUFFER for the two tags that name a filesystem target.+ public static func decode(_ data: Data) -> Decoded? {+ guard data.count >= 16 else { return nil }+ let bytes = [UInt8](data)+ func u16(_ o: Int) -> Int { Int(bytes[o]) | Int(bytes[o + 1]) << 8 }+ func u32(_ o: Int) -> UInt32 { UInt32(u16(o)) | UInt32(u16(o + 2)) << 16 }+ let tag = u32(0)+ let subOffset = u16(8), subLength = u16(10)+ let pathBuffer: Int+ let relative: Bool+ switch tag {+ case symlinkTag:+ guard data.count >= 20 else { return nil }+ pathBuffer = 20; relative = u32(16) & 1 == 1+ case mountPointTag:+ pathBuffer = 16; relative = false+ default:+ return nil+ }+ let start = pathBuffer + subOffset, end = start + subLength+ guard subLength >= 2, end <= bytes.count,+ let name = String(bytes: bytes[start..<end], encoding: .utf16LittleEndian) else { return nil }+ return Decoded(tag: tag, target: name, isRelative: relative)+ }++ /// The reparse data on an entry, if it carries any (the entry itself, not what it may link to).+ public static func read(at url: URL) -> Decoded? {+ let path = url.path+ let size = getxattr(path, attribute, nil, 0, 0, XATTR_NOFOLLOW)+ guard size > 0 else { return nil }+ var buffer = [UInt8](repeating: 0, count: size)+ let got = getxattr(path, attribute, &buffer, size, 0, XATTR_NOFOLLOW)+ guard got > 0 else { return nil }+ return decode(Data(buffer[0..<got]))+ }++ /// `EA Desktop?` → `EA Desktop`. A stub without the marker keeps its name.+ public static func linkName(forStub name: String) -> String {+ name.hasSuffix("?") ? String(name.dropLast()) : name+ }++ /// Where the target lives on the host: relative names hang off the stub's directory,+ /// absolute ones go through the bottle's drives (C: is drive_c, Z: is the host root).+ public static func hostTarget(_ decoded: Decoded, stubParent: URL, driveC: URL) -> URL? {+ var t = decoded.target+ for prefix in ["\\??\\", "\\\\?\\"] where t.hasPrefix(prefix) { t.removeFirst(prefix.count) }+ let unix = t.replacingOccurrences(of: "\\", with: "/")+ let hasDrive = t.count >= 2 && t.dropFirst().hasPrefix(":")+ if decoded.isRelative || !hasDrive {+ return stubParent.appending(path: unix).standardizedFileURL+ }+ var rest = String(unix.dropFirst(2))+ if rest.hasPrefix("/") { rest.removeFirst() }+ switch t.prefix(1).lowercased() {+ case "c": return driveC.appending(path: rest).standardizedFileURL+ case "z": return URL(fileURLWithPath: "/" + rest)+ default: return nil+ }+ }++ // MARK: Materialising++ /// Turns every reparse stub directly inside `dir` into a host symlink. Returns the links made.+ /// Skips stubs whose target is not there (a link to nothing helps nobody) and names that are+ /// already taken by something other than the stub itself.+ @discardableResult+ public static func materialize(in dir: URL, driveC: URL) -> [URL] {+ let fm = FileManager.default+ guard let names = try? fm.contentsOfDirectory(atPath: dir.path) else { return [] }+ var made: [URL] = []+ for name in names where !name.hasPrefix(asidePrefix) {+ let stub = dir.appending(path: name)+ guard let decoded = read(at: stub),+ let target = hostTarget(decoded, stubParent: dir, driveC: driveC),+ fm.fileExists(atPath: target.path) else { continue }+ let linkName = linkName(forStub: name)+ let link = dir.appending(path: linkName)+ if linkName == name {+ // The stub occupies the link's name: move the (empty) stub aside first.+ let aside = dir.appending(path: asidePrefix + name)+ try? fm.removeItem(at: aside)+ guard (try? fm.moveItem(at: stub, to: aside)) != nil else { continue }+ } else if (try? fm.attributesOfItem(atPath: link.path)) != nil {+ continue // something already has that name; lstat semantics, so a dangling link counts too+ }+ let destination = decoded.isRelative+ ? decoded.target.replacingOccurrences(of: "\\", with: "/")+ : relativePath(from: dir, to: target)+ if (try? fm.createSymbolicLink(atPath: link.path, withDestinationPath: destination)) != nil {+ made.append(link)+ }+ }+ return made+ }++ /// Materialises stubs anywhere under `root`, directories only, to a bounded depth: installers+ /// put their links a few levels under Program Files, and game trees below that are huge.+ /// `windows/` at the root is skipped.+ @discardableResult+ public static func materializeTree(under root: URL, driveC: URL, maxDepth: Int = 6) -> [URL] {+ let fm = FileManager.default+ var made: [URL] = []+ func walk(_ dir: URL, depth: Int) {+ made += materialize(in: dir, driveC: driveC)+ guard depth < maxDepth,+ let entries = try? fm.contentsOfDirectory(at: dir, includingPropertiesForKeys: [.isDirectoryKey, .isSymbolicLinkKey],+ options: [.skipsHiddenFiles]) else { return }+ for entry in entries {+ let values = try? entry.resourceValues(forKeys: [.isDirectoryKey, .isSymbolicLinkKey])+ guard values?.isDirectory == true, values?.isSymbolicLink != true else { continue }+ if depth == 0, entry.lastPathComponent.lowercased() == "windows" { continue }+ walk(entry, depth: depth + 1)+ }+ }+ walk(root, depth: 0)+ return made+ }++ /// `url` if it exists, else the same path after materialising the stubs that stood in its way,+ /// or nil when something is still missing. Walks from the bottle's drive_c when the path is+ /// inside it, so a missing pin costs a few directory reads and nothing more.+ public static func resolve(_ url: URL, driveC: URL) -> URL? {+ let fm = FileManager.default+ if fm.fileExists(atPath: url.path) { return url }+ let path = url.standardizedFileURL.path+ let base = driveC.standardizedFileURL.path+ var current: URL+ var remaining: ArraySlice<String>+ if path == base || path.hasPrefix(base.hasSuffix("/") ? base : base + "/") {+ current = driveC+ remaining = String(path.dropFirst(base.count)).split(separator: "/").map(String.init)[...]+ } else {+ current = URL(fileURLWithPath: "/")+ remaining = url.standardizedFileURL.pathComponents.dropFirst()[...]+ }+ for component in remaining {+ let next = current.appending(path: component)+ if !fm.fileExists(atPath: next.path) {+ materialize(in: current, driveC: driveC)+ guard fm.fileExists(atPath: next.path) else { return nil }+ }+ current = next+ }+ return current+ }++ /// A relative symlink destination from `dir` to `target` (`../13.783.0.6296/EA Desktop`),+ /// so the link survives the bottle being moved or renamed.+ static func relativePath(from dir: URL, to target: URL) -> String {+ let from = dir.standardizedFileURL.pathComponents+ let to = target.standardizedFileURL.pathComponents+ var common = 0+ while common < from.count, common < to.count, from[common] == to[common] { common += 1 }+ let ups = Array(repeating: "..", count: from.count - common)+ let rest = Array(to[common...])+ let parts = ups + rest+ return parts.isEmpty ? "." : parts.joined(separator: "/")+ }+}diff --git a/Sources/HighballKit/WineRunner.swift b/Sources/HighballKit/WineRunner.swiftindex b5c1718..7f40f2e 100644--- a/Sources/HighballKit/WineRunner.swift+++ b/Sources/HighballKit/WineRunner.swift@@ -200,7 +200,10 @@ public struct WineRunner: Sendable {/// Runs the pinned program, honouring its own renderer/env/args.@discardableResultpublic func start(pin: Pin, extraEnvironment: [String: String] = [:], onOutput: (@Sendable (String) -> Void)? = nil) async throws -> LaunchResult {- let exe = pin.executableURL(driveC: bottle.driveC)+ // A path behind a Windows junction the installer made (EA app) exists only once the+ // junction stub is turned into a host symlink; do that before judging it missing.+ let exe = WineReparsePoint.resolve(pin.executableURL(driveC: bottle.driveC), driveC: bottle.driveC)+ ?? pin.executableURL(driveC: bottle.driveC)// A pin whose target no longer exists otherwise dies deep in Wine with an opaque// c0000135 ("failed to open"). Catch it here with a message the user can act on.// Pins written before 0.7.6 stored only a filename, so old entries resolve to adiff --git a/Sources/highball/main.swift b/Sources/highball/main.swiftindex 73d283c..96d346e 100644--- a/Sources/highball/main.swift+++ b/Sources/highball/main.swift@@ -335,7 +335,7 @@ struct Run: AsyncParsableCommand {result = try await runner.start(pin: p, onOutput: out)}} else if program.contains(":") || program.contains("\\") {- let exe = b.resolve(windowsPath: program)+ let exe = WineReparsePoint.resolve(b.resolve(windowsPath: program), driveC: b.driveC) ?? b.resolve(windowsPath: program)result = try await runner.start(exe, arguments: arguments, renderer: renderer,workingDirectory: exe.deletingLastPathComponent(), onOutput: out)} else if FileManager.default.fileExists(atPath: program) {diff --git a/Tests/HighballKitTests/WineReparsePointTests.swift b/Tests/HighballKitTests/WineReparsePointTests.swiftnew file mode 100644index 0000000..3258341--- /dev/null+++ b/Tests/HighballKitTests/WineReparsePointTests.swift@@ -0,0 +1,165 @@+import XCTest+import Darwin+@testable import HighballKit++final class WineReparsePointTests: XCTestCase {+ private var root: URL!++ override func setUpWithError() throws {+ root = FileManager.default.temporaryDirectory.appending(path: "reparse-\(UUID().uuidString)")+ try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)+ }++ override func tearDownWithError() throws {+ try? FileManager.default.removeItem(at: root)+ }++ // MARK: Fixtures++ /// A REPARSE_DATA_BUFFER as Windows lays it out: header, the name offsets, then the+ /// substitute and print names back to back in UTF-16LE.+ static func blob(tag: UInt32, substitute: String, relative: Bool) -> Data {+ let name = Array(substitute.utf16).flatMap { [UInt8($0 & 0xFF), UInt8($0 >> 8)] }+ let subLen = name.count, printOff = subLen + 2+ var body: [UInt8] = []+ func u16(_ v: Int) { body += [UInt8(v & 0xFF), UInt8(v >> 8)] }+ func u32(_ v: UInt32) { body += [UInt8(v & 0xFF), UInt8(v >> 8 & 0xFF), UInt8(v >> 16 & 0xFF), UInt8(v >> 24)] }+ u16(0); u16(subLen); u16(printOff); u16(subLen)+ if tag == 0xA000_000C { u32(relative ? 1 : 0) }+ body += name + [0, 0] + name + [0, 0]+ var out: [UInt8] = []+ out += [UInt8(tag & 0xFF), UInt8(tag >> 8 & 0xFF), UInt8(tag >> 16 & 0xFF), UInt8(tag >> 24)]+ out += [UInt8(body.count & 0xFF), UInt8(body.count >> 8), 0, 0]+ return Data(out + body)+ }++ /// The bytes Wine 11 (CrossOver 26.3) wrote for the EA app installer's `EA Desktop\EA Desktop`+ /// junction, read back from the bottle with `xattr -p -x user.WINEREPARSE`.+ static let eaJunctionHex = "0C0000A070000000000030003200300001000000"+ + "310033002E003700380033002E0030002E0036003200390036005C004500410020004400650073006B0074006F00700000"+ + "00310033002E003700380033002E0030002E0036003200390036005C004500410020004400650073006B0074006F0070000000"++ /// Makes a stub the way Wine does: an empty directory carrying the attribute.+ func makeStub(in dir: URL, name: String, data: Data) throws {+ let stub = dir.appending(path: name)+ try FileManager.default.createDirectory(at: stub, withIntermediateDirectories: true)+ let rc = data.withUnsafeBytes { setxattr(stub.path, WineReparsePoint.attribute, $0.baseAddress, data.count, 0, XATTR_NOFOLLOW) }+ XCTAssertEqual(rc, 0, "setxattr failed: \(String(cString: strerror(errno)))")+ }++ /// EA's layout: the versioned folder holds the client, the unversioned name is the link.+ func makeEAInstall(under base: URL, stubName: String = "EA Desktop?") throws -> (dir: URL, exe: URL) {+ let dir = base.appending(path: "Program Files/Electronic Arts/EA Desktop")+ let versioned = dir.appending(path: "13.783.0.6296/EA Desktop")+ try FileManager.default.createDirectory(at: versioned, withIntermediateDirectories: true)+ let exe = versioned.appending(path: "EADesktop.exe")+ try Data("MZ".utf8).write(to: exe)+ try makeStub(in: dir, name: stubName, data: Self.blob(tag: 0xA000_000C, substitute: "13.783.0.6296\\EA Desktop", relative: true))+ return (dir, exe)+ }++ // MARK: Decoding++ func testDecodesRelativeSymlinkAndAbsoluteJunction() {+ let sym = WineReparsePoint.decode(Self.blob(tag: 0xA000_000C, substitute: "13.783.0.6296\\EA Desktop", relative: true))+ XCTAssertEqual(sym, .init(tag: 0xA000_000C, target: "13.783.0.6296\\EA Desktop", isRelative: true))+ let junction = WineReparsePoint.decode(Self.blob(tag: 0xA000_0003, substitute: "\\??\\C:\\Program Files\\X\\1.0", relative: false))+ XCTAssertEqual(junction, .init(tag: 0xA000_0003, target: "\\??\\C:\\Program Files\\X\\1.0", isRelative: false))+ XCTAssertNil(WineReparsePoint.decode(Self.blob(tag: 0x8000_0017, substitute: "x", relative: false)), "other tags name no target")+ XCTAssertNil(WineReparsePoint.decode(Data([1, 2, 3])))+ }++ func testDecodesTheBytesWineActuallyWrote() {+ var bytes: [UInt8] = []+ var hex = Substring(Self.eaJunctionHex)+ while hex.count >= 2 { bytes.append(UInt8(hex.prefix(2), radix: 16)!); hex = hex.dropFirst(2) }+ let d = WineReparsePoint.decode(Data(bytes))+ XCTAssertEqual(d?.tag, 0xA000_000C)+ XCTAssertEqual(d?.isRelative, true)+ XCTAssertEqual(d?.target, "13.783.0.6296\\EA Desktop")+ }++ func testHostTargets() {+ let driveC = root.appending(path: "drive_c"), parent = driveC.appending(path: "Program Files/Vendor")+ let rel = WineReparsePoint.hostTarget(.init(tag: 0, target: "1.0\\App", isRelative: true), stubParent: parent, driveC: driveC)+ XCTAssertEqual(rel?.path, parent.appending(path: "1.0/App").path)+ let abs = WineReparsePoint.hostTarget(.init(tag: 0, target: "\\??\\C:\\Program Files\\Vendor\\1.0\\App", isRelative: false), stubParent: parent, driveC: driveC)+ XCTAssertEqual(abs?.path, driveC.appending(path: "Program Files/Vendor/1.0/App").path)+ let z = WineReparsePoint.hostTarget(.init(tag: 0, target: "Z:\\Users\\me\\x", isRelative: false), stubParent: parent, driveC: driveC)+ XCTAssertEqual(z?.path, "/Users/me/x")+ XCTAssertNil(WineReparsePoint.hostTarget(.init(tag: 0, target: "D:\\x", isRelative: false), stubParent: parent, driveC: driveC), "no such drive in a bottle")+ XCTAssertEqual(WineReparsePoint.linkName(forStub: "EA Desktop?"), "EA Desktop")+ XCTAssertEqual(WineReparsePoint.linkName(forStub: "plain"), "plain")+ }++ // MARK: Materialising++ func testStubBecomesARelativeHostSymlinkTheClientIsReachableThrough() throws {+ let driveC = root.appending(path: "drive_c")+ let (dir, _) = try makeEAInstall(under: driveC)+ let made = WineReparsePoint.materialize(in: dir, driveC: driveC)+ XCTAssertEqual(made.map(\.lastPathComponent), ["EA Desktop"])+ let link = dir.appending(path: "EA Desktop")+ XCTAssertEqual(try FileManager.default.destinationOfSymbolicLink(atPath: link.path), "13.783.0.6296/EA Desktop", "relative, so a moved bottle keeps working")+ XCTAssertTrue(FileManager.default.fileExists(atPath: link.appending(path: "EADesktop.exe").path))+ XCTAssertTrue(FileManager.default.fileExists(atPath: dir.appending(path: "EA Desktop?").path), "the stub is left for Wine")+ XCTAssertEqual(WineReparsePoint.materialize(in: dir, driveC: driveC), [], "second pass: nothing left to do")+ }++ func testStubWithoutTheMarkerIsMovedAsideForTheLink() throws {+ let driveC = root.appending(path: "drive_c")+ let (dir, _) = try makeEAInstall(under: driveC, stubName: "EA Desktop")+ XCTAssertEqual(WineReparsePoint.materialize(in: dir, driveC: driveC).map(\.lastPathComponent), ["EA Desktop"])+ XCTAssertTrue(FileManager.default.fileExists(atPath: dir.appending(path: "EA Desktop/EADesktop.exe").path))+ XCTAssertNotNil(WineReparsePoint.read(at: dir.appending(path: ".wine-reparse-EA Desktop")), "the stub survives, aside")+ }++ func testStubToNothingAndTakenNamesAreLeftAlone() throws {+ let driveC = root.appending(path: "drive_c")+ let dir = driveC.appending(path: "Program Files/Vendor")+ try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)+ try makeStub(in: dir, name: "Gone?", data: Self.blob(tag: 0xA000_000C, substitute: "9.9\\Gone", relative: true))+ try makeStub(in: dir, name: "Taken?", data: Self.blob(tag: 0xA000_000C, substitute: "9.9\\Gone", relative: true))+ try FileManager.default.createDirectory(at: dir.appending(path: "9.9/Gone"), withIntermediateDirectories: true)+ try Data().write(to: dir.appending(path: "Taken"))+ try makeStub(in: dir, name: "Nowhere?", data: Self.blob(tag: 0xA000_000C, substitute: "no\\such", relative: true))+ let made = WineReparsePoint.materialize(in: dir, driveC: driveC)+ XCTAssertEqual(made.map(\.lastPathComponent), ["Gone"])+ XCTAssertEqual(try Data(contentsOf: dir.appending(path: "Taken")), Data(), "an existing file is never replaced")+ XCTAssertNil(try? FileManager.default.destinationOfSymbolicLink(atPath: dir.appending(path: "Nowhere").path))+ }++ func testAbsoluteJunctionGetsARelativeLink() throws {+ let driveC = root.appending(path: "drive_c")+ let dir = driveC.appending(path: "Program Files/Vendor")+ try FileManager.default.createDirectory(at: driveC.appending(path: "ProgramData/Vendor/1.0"), withIntermediateDirectories: true)+ try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)+ try makeStub(in: dir, name: "Current?", data: Self.blob(tag: 0xA000_0003, substitute: "\\??\\C:\\ProgramData\\Vendor\\1.0", relative: false))+ XCTAssertEqual(WineReparsePoint.materialize(in: dir, driveC: driveC).count, 1)+ XCTAssertEqual(try FileManager.default.destinationOfSymbolicLink(atPath: dir.appending(path: "Current").path), "../../ProgramData/Vendor/1.0")+ }++ func testResolveMaterialisesWhatStandsInThePathsWay() throws {+ let driveC = root.appending(path: "drive_c")+ let (dir, _) = try makeEAInstall(under: driveC)+ let pinned = dir.appending(path: "EA Desktop/EADesktop.exe")+ XCTAssertFalse(FileManager.default.fileExists(atPath: pinned.path))+ XCTAssertEqual(WineReparsePoint.resolve(pinned, driveC: driveC)?.path, pinned.path)+ XCTAssertTrue(FileManager.default.fileExists(atPath: pinned.path))+ XCTAssertNil(WineReparsePoint.resolve(dir.appending(path: "EA Desktop/Missing.exe"), driveC: driveC))+ XCTAssertNil(WineReparsePoint.resolve(root.appending(path: "outside/nothing"), driveC: driveC))+ }++ func testTreeWalkFindsStubsAFewLevelsDownAndStopsAtTheDepthCap() throws {+ let driveC = root.appending(path: "drive_c")+ let (dir, _) = try makeEAInstall(under: driveC)+ try FileManager.default.createDirectory(at: driveC.appending(path: "windows/system32"), withIntermediateDirectories: true)+ let deep = driveC.appending(path: "a/b/c/d/e/f/g/h")+ try FileManager.default.createDirectory(at: deep.appending(path: "1.0/X"), withIntermediateDirectories: true)+ try makeStub(in: deep, name: "X?", data: Self.blob(tag: 0xA000_000C, substitute: "1.0\\X", relative: true))+ let made = WineReparsePoint.materializeTree(under: driveC, driveC: driveC)+ XCTAssertEqual(made.map(\.lastPathComponent), ["EA Desktop"], "depth 3 is found, depth 8 is beyond the cap")+ XCTAssertTrue(FileManager.default.fileExists(atPath: dir.appending(path: "EA Desktop/EADesktop.exe").path))+ XCTAssertEqual(WineReparsePoint.materializeTree(under: driveC, driveC: driveC, maxDepth: 10).map(\.lastPathComponent), ["X"])+ }+}