Skip to content

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

winetricks steps write their own log, streamed, with the exit code as a footer (three core-fonts reports arrived with a game's launch log attached because the step wrote nothing anywhere: #135, #180, #183); the failure text says where the full output is

Gauthier Piarrette5373288b573c
diff --git a/Sources/HighballKit/Recipe.swift b/Sources/HighballKit/Recipe.swift
index 384d7ea..eaffb9f 100644
--- a/Sources/HighballKit/Recipe.swift
+++ b/Sources/HighballKit/Recipe.swift
@@ -496,7 +496,16 @@ public struct RecipeRunner: Sendable {
if !tools.isEmpty {
env["PATH"] = (tools.map(\.path) + [env["PATH"] ?? ProcessInfo.processInfo.environment["PATH"] ?? "/usr/bin:/bin"]).joined(separator: ":")
}
- try Shell.run("/bin/bash", [wt.path, "--unattended"] + verbs, env: env)
+ // Its own log, named like every other one in the folder. Without it the step was
+ // invisible: what winetricks said lived only in the error dialog's Details, so
+ // three reports of the core fonts failing came with a game's launch log attached
+ // and none of them could be answered (highball#135, #180, #183).
+ let stamp = ISO8601DateFormatter().string(from: Date()).replacingOccurrences(of: ":", with: "")
+ let logURL = WineRunner.uniqueLogURL(in: paths.logs,
+ named: "\(stamp)-\(bottle.name)-winetricks-\(verbs.joined(separator: "-"))")
+ log?("[\(recipe.id)] log: \(logURL.path)")
+ try Shell.capture("/bin/bash", [wt.path, "--unattended"] + verbs, env: env, log: logURL,
+ logHeader: "# highball winetricks \(verbs.joined(separator: " ")) bottle=\(bottle.name) engine=\(engine.id)")
case let .environment(name, value):
bottle.settings.environment[name] = value
case let .renderer(r):
diff --git a/Sources/HighballKit/Recovery.swift b/Sources/HighballKit/Recovery.swift
index 94a546b..b313057 100644
--- a/Sources/HighballKit/Recovery.swift
+++ b/Sources/HighballKit/Recovery.swift
@@ -73,6 +73,9 @@ public struct Recovery: Equatable, Sendable {
// #135 two rounds with nothing pasted back. Say it up front.
var meaning = "It downloads its files from the internet as it runs, and those servers refuse now and then, so trying again in a few minutes often works."
if let reason = Self.winetricksReason(output) { meaning += " It said: \(reason)" }
+ // Where the whole run is, so a report can carry it: the newest winetricks file in the
+ // logs folder, which Troubleshooting opens.
+ meaning += " The full output is in Highball's logs folder, in the newest file with winetricks in its name."
return Recovery(headline: "\(what) didn't finish.", meaning: meaning,
actionTitle: "Try again", action: .retry)
case let .processFailed(command, _, _):
diff --git a/Sources/HighballKit/Shell.swift b/Sources/HighballKit/Shell.swift
index 2c38b72..4e56fd1 100644
--- a/Sources/HighballKit/Shell.swift
+++ b/Sources/HighballKit/Shell.swift
@@ -3,8 +3,17 @@ import Foundation
/// Minimal process helpers. Wine itself is launched through `WineRunner`, which streams output;
/// these are for short tools (tar, xattr, wine --version, reg queries).
public enum Shell {
+ /// Runs a tool and returns everything it printed, optionally copying it to `log` as it comes.
+ ///
+ /// The log matters for the long ones. A winetricks verb downloads from servers Highball does
+ /// not run and can take forty minutes, and until 2026-09-22 it wrote nothing anywhere: three
+ /// reports of the core fonts failing (highball#135, #180, #183) arrived with the game's launch
+ /// log attached, because that was the newest file in the folder and the only thing there was
+ /// to attach. The output is streamed rather than kept for the end, so a step that hangs still
+ /// leaves what it managed to say.
@discardableResult
- public static func capture(_ executable: String, _ args: [String], env: [String: String]? = nil, cwd: URL? = nil) throws -> String {
+ public static func capture(_ executable: String, _ args: [String], env: [String: String]? = nil, cwd: URL? = nil,
+ log: URL? = nil, logHeader: String? = nil) throws -> String {
let p = Process()
p.executableURL = URL(fileURLWithPath: executable)
p.arguments = args
@@ -13,10 +22,29 @@ public enum Shell {
let out = Pipe()
p.standardOutput = out
p.standardError = out
+ var handle: FileHandle?
+ if let log {
+ FileManager.default.createFile(atPath: log.path, contents: nil)
+ handle = try? FileHandle(forWritingTo: log)
+ let header = (logHeader.map { $0 + "\n" } ?? "") + "# " + ([executable] + args).joined(separator: " ") + "\n"
+ try? handle?.write(contentsOf: Data(header.utf8))
+ }
+ defer { try? handle?.close() }
+ let started = Date()
try p.run()
- let data = out.fileHandleForReading.readDataToEndOfFile()
+ var data = Data()
+ let reader = out.fileHandleForReading
+ while true {
+ let chunk = reader.availableData
+ if chunk.isEmpty { break }
+ data.append(chunk)
+ try? handle?.write(contentsOf: chunk)
+ }
p.waitUntilExit()
let text = String(decoding: data, as: UTF8.self)
+ // The same footer a Wine launch writes, so a failed step is told from a finished one by
+ // looking at the end of the file (the exit code used to be thrown away, issue #36).
+ try? handle?.write(contentsOf: Data("# exit=\(p.terminationStatus) after \(Int(Date().timeIntervalSince(started)))s\n".utf8))
guard p.terminationStatus == 0 else {
throw HighballError.processFailed(command: ([executable] + args).joined(separator: " "), status: p.terminationStatus, output: text)
}
diff --git a/Tests/HighballKitTests/ShellLogTests.swift b/Tests/HighballKitTests/ShellLogTests.swift
new file mode 100644
index 0000000..19c8e83
--- /dev/null
+++ b/Tests/HighballKitTests/ShellLogTests.swift
@@ -0,0 +1,68 @@
+import XCTest
+@testable import HighballKit
+
+/// A long tool has to leave a file behind. Three reports of the core fonts failing (highball#135,
+/// #180, #183) could not be answered because the winetricks step wrote nothing anywhere: what it
+/// said lived only in the error dialog, and the newest file in the logs folder, the one a report
+/// attaches, was the game's launch log.
+final class ShellLogTests: XCTestCase {
+ private var dir: URL!
+
+ override func setUpWithError() throws {
+ dir = FileManager.default.temporaryDirectory.appending(path: "shell-log-\(UUID().uuidString)")
+ try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+ }
+
+ override func tearDownWithError() throws {
+ try? FileManager.default.removeItem(at: dir)
+ }
+
+ func testTheLogCarriesTheHeaderTheOutputAndTheExitCode() throws {
+ let log = dir.appending(path: "run.log")
+ let text = try Shell.capture("/bin/echo", ["hello"], log: log, logHeader: "# highball winetricks corefonts bottle=Games")
+ XCTAssertEqual(text, "hello\n", "the caller still gets what it always got")
+ let written = try String(contentsOf: log, encoding: .utf8)
+ XCTAssertTrue(written.hasPrefix("# highball winetricks corefonts bottle=Games\n# /bin/echo hello\n"), written)
+ XCTAssertTrue(written.contains("\nhello\n"), written)
+ XCTAssertTrue(written.contains("# exit=0 after "), "a finished step is told from a failed one by the footer")
+ }
+
+ func testAFailedStepStillLeavesItsOutputAndCode() throws {
+ let log = dir.appending(path: "fail.log")
+ XCTAssertThrowsError(try Shell.capture("/bin/sh", ["-c", "echo broke; exit 3"], log: log)) { error in
+ guard case let HighballError.processFailed(_, status, output) = error else { return XCTFail("\(error)") }
+ XCTAssertEqual(status, 3)
+ XCTAssertEqual(output, "broke\n", "Recovery reads the reason out of this")
+ }
+ let written = try String(contentsOf: log, encoding: .utf8)
+ XCTAssertTrue(written.contains("broke"), written)
+ XCTAssertTrue(written.contains("# exit=3 after "), written)
+ }
+
+ func testWithoutALogNothingIsWrittenAndTheOutputIsUnchanged() throws {
+ XCTAssertEqual(try Shell.capture("/bin/echo", ["quiet"]), "quiet\n")
+ XCTAssertEqual(try FileManager.default.contentsOfDirectory(atPath: dir.path), [])
+ }
+
+ /// The output arrives as it is produced, so a step that never finishes still leaves what it
+ /// managed to say. dotnet48 runs for forty minutes and looks idle for most of them.
+ func testOutputIsStreamedRatherThanKeptForTheEnd() throws {
+ let log = dir.appending(path: "stream.log")
+ let started = Date()
+ DispatchQueue.global().asyncAfter(deadline: .now() + 0.4) {
+ let seen = (try? String(contentsOf: log, encoding: .utf8)) ?? ""
+ XCTAssertTrue(seen.contains("first"), "nothing was written while the tool was still running: \(seen)")
+ XCTAssertFalse(seen.contains("# exit="), "the footer arrives at the end, not before")
+ }
+ _ = try Shell.capture("/bin/sh", ["-c", "echo first; sleep 1; echo second"], log: log)
+ XCTAssertGreaterThan(Date().timeIntervalSince(started), 0.9)
+ let written = try String(contentsOf: log, encoding: .utf8)
+ XCTAssertTrue(written.contains("first") && written.contains("second") && written.contains("# exit=0"), written)
+ }
+
+ func testTheLogNameSaysWhichStepItWas() {
+ let name = WineRunner.uniqueLogURL(in: dir, named: "2026-09-22T101500Z-Games-winetricks-corefonts").lastPathComponent
+ XCTAssertEqual(name, "2026-09-22T101500Z-Games-winetricks-corefonts.log",
+ "a report picks the newest log by name, so the verb has to be in it")
+ }
+}