Skip to content

Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.

A data folder whose path Windows can't express is refused with the reason instead of failing the first setup forever (highball#547, #446)

Gauthier Piarretteeacd69aef346
diff --git a/Sources/HighballKit/BottleStore.swift b/Sources/HighballKit/BottleStore.swift
index 870765c..aaf8cf6 100644
--- a/Sources/HighballKit/BottleStore.swift
+++ b/Sources/HighballKit/BottleStore.swift
@@ -90,6 +90,9 @@ public struct BottleStore: Sendable {
public func create(name rawName: String, engine: InstalledEngine, renderer: Renderer? = nil, windowsVersion: WindowsVersion = .win10) async throws -> Bottle {
let name = rawName.trimmingCharacters(in: .whitespaces)
if let problem = Self.nameProblem(name) { throw HighballError.invalid(problem) }
+ // Wine reaches the engine and the environment through Windows paths, so a folder name
+ // Windows can't hold anywhere above them fails the first boot every time (highball#547).
+ if let problem = HighballPaths.windowsPathProblem(paths.home) { throw HighballError.invalid(problem) }
try paths.ensure()
let url = try Self.bottleURL(name, in: paths)
// lstat, not fileExists: fileExists follows symlinks, so a dangling one sailed through
diff --git a/Sources/HighballKit/Paths.swift b/Sources/HighballKit/Paths.swift
index a763ba5..161ed50 100644
--- a/Sources/HighballKit/Paths.swift
+++ b/Sources/HighballKit/Paths.swift
@@ -78,6 +78,7 @@ public struct HighballPaths: Sendable {
guard fm.isWritableFile(atPath: url.path) else { return "Highball cannot write in that folder." }
let target = url.standardizedFileURL.path + "/", base = defaultHome.standardizedFileURL.path + "/"
if target.hasPrefix(base) || base.hasPrefix(target) { return "Pick a folder outside Highball's own data folder." }
+ if let why = windowsPathProblem(url) { return why }
if (try? url.resourceValues(forKeys: [.volumeIsReadOnlyKey]))?.volumeIsReadOnly == true {
return "That volume is read only."
}
@@ -91,6 +92,23 @@ public struct HighballPaths: Sendable {
return volumeProblem(url)
}
+ /// Why Wine cannot reach a folder through its Windows paths, or nil. Windows drops a trailing
+ /// period or space from every folder name and refuses <>:"|?* and control characters, and Wine
+ /// does the same when it turns a Mac path into a Windows one. A home folder named "a." became
+ /// Z:\Users\a, which does not exist, so the very first Windows setup failed with "could not load
+ /// kernel32.dll" (exit 53) on every try and Repair repeated it (highball#547, #446). Reproduced
+ /// 2026-10-29 with a folder named "u." on engine r28; the same tree without the period boots.
+ public static func windowsPathProblem(_ url: URL) -> String? {
+ for part in url.standardizedFileURL.pathComponents where part != "/" {
+ let bad = part.hasSuffix(".") || part.hasSuffix(" ")
+ || part.unicodeScalars.contains { "<>:\"|?*".unicodeScalars.contains($0) || $0.value < 0x20 }
+ if bad {
+ return "Wine can't use Highball's folder because the folder \"\(part)\" in its path has a name Windows can't use (it ends with a period or a space, or holds one of <>:\"|?*). In Highball's settings, under Environments, use Change… to keep Highball's data in a folder outside it, such as one in /Users/Shared."
+ }
+ }
+ return nil
+ }
+
/// Why a usable folder is still a poor place for a prefix, or nil. Shown before the move,
/// never as a hard stop.
public static func locationWarning(_ url: URL) -> String? {
diff --git a/Tests/HighballKitTests/HomeLocationTests.swift b/Tests/HighballKitTests/HomeLocationTests.swift
index 7132974..07d5c2a 100644
--- a/Tests/HighballKitTests/HomeLocationTests.swift
+++ b/Tests/HighballKitTests/HomeLocationTests.swift
@@ -43,6 +43,34 @@ final class HomeLocationTests: XCTestCase {
XCTAssertNil(HighballPaths.locationWarning(good), "a local folder is not a share warning")
}
+ // Windows drops a trailing period or space from folder names, and Wine with it: a home folder
+ // named "a." became Z:\\Users\\a and the first setup failed with kernel32.dll on every try
+ // (highball#547). Such a path is refused before anything boots, and as a chosen location.
+ func testWindowsPathProblem() throws {
+ XCTAssertNil(HighballPaths.windowsPathProblem(URL(fileURLWithPath: "/Users/a/Library/Application Support/Highball")))
+ XCTAssertNil(HighballPaths.windowsPathProblem(URL(fileURLWithPath: "/Users/a.b/.hidden/Highball")), "a period inside or in front is fine")
+ XCTAssertNotNil(HighballPaths.windowsPathProblem(URL(fileURLWithPath: "/Users/a./Library/Application Support/Highball")))
+ XCTAssertNotNil(HighballPaths.windowsPathProblem(URL(fileURLWithPath: "/Volumes/Games /Highball")), "a trailing space is dropped too")
+ XCTAssertNotNil(HighballPaths.windowsPathProblem(URL(fileURLWithPath: "/tmp/Hi?ball")))
+ let dotted = tmp.appending(path: "x.", directoryHint: .isDirectory)
+ try FileManager.default.createDirectory(at: dotted, withIntermediateDirectories: true)
+ XCTAssertNotNil(HighballPaths.locationProblem(dotted, defaultHome: tmp.appending(path: "default")))
+ }
+
+ func testCreateRefusesAHomeWindowsCannotReach() async throws {
+ let paths = HighballPaths(home: tmp.appending(path: "u./Highball", directoryHint: .isDirectory))
+ let json = #"{"id":"x64-a-r1","displayName":"e","arch":"x86_64","minMacOS":"14.0","components":{}}"#
+ let engine = InstalledEngine(manifest: try JSONDecoder().decode(EngineManifest.self, from: Data(json.utf8)),
+ root: tmp.appending(path: "engine"))
+ do {
+ _ = try await BottleStore(paths: paths).create(name: "Games", engine: engine)
+ XCTFail("create must refuse before booting anything")
+ } catch let HighballError.invalid(why) {
+ XCTAssertTrue(why.contains("u."), why)
+ }
+ XCTAssertFalse(FileManager.default.fileExists(atPath: paths.bottle("Games").path), "nothing is made")
+ }
+
// The volume check asks the volume instead of trusting a name. The old check read
// volumeSupportsSymbolicLinks and refused exFAT by name, but macOS reports exFAT as supporting
// symbolic links and creates them, so it never fired and the promised refusal never happened